Necrotizing Pineapple Music

    @mirantis/lens-extension-cc

    3.1.2 • Public • Published

    Mirantis Container Cloud Lens Extension - v3 Maintenance

    CI

    This Lens Extension adds a status bar item, and a menu item, that makes it easy to connect Lens to a Mirantis Container Cloud instance and add its clusters to Lens.

    ℹ️ Requires Lens >= 5.3.0.

    Extension UI

    Installing

    Installation is very easy! Just make sure Lens 5.3.0 or later is running, and follow these simple steps:

    1. Switch to the Extensions view (CMD+SHIFT+E on macOS).
    2. Enter the name of this extension, @mirantis/lens-extension-cc, into the Install Extension box.
    3. Click on the Install button.

    Extension UI

    You should now be able to choose the new File > Add Cloud Clusters menu item, or click on the Mirantis Container Cloud status bar icon (far right side of the status bar at the bottom of the app), to get started.

    💬 These instructions will help you install the extension for direct use with Lens. Follow the development instructions below if you intend to work on the extension to improve it.

    Upgrading

    To upgrade to a newer release, go to the Extensions view (CMD+SHIFT+E on macOS), uninstall the extension, and then re-install it again.

    Uninstalling

    Go to the Lens Extensions view (CMD+SHIFT+E on macOS) and click the Uninstall button next to this extension.

    Catalog

    Lens 5 replaced its Workspace concept with a new Catalog that allows much more flexibility.

    When adding clusters to Lens with this extension, each cluster will get the following labels:

    • mcc=true
    • project=NAMESPACE (set to the name of the project/namespace in Container Cloud to which the cluster belongs)

    The extension also supports removing and deleting clusters that it added by choosing these items from the cluster's "More" context menu in the Catalog (as well as icons in the Catalog Drawer's toolbar):

    • Remove: Removes the cluster from the Catalog, but leaves the kubeConfig on disk in the configured location.
    • Delete config: Removes the cluster from the Catalog and deletes the kubeConfig from disk.

    In either case, the cluster in Container Cloud is unaffected. If you need to terminate the cluster, please do so in the Container Cloud web application.

    SSO support

    📣 Mirantis Container Cloud instances that use third-party SSO authentication via Keycloak are required in order to use this extension.

    Keycloak Configuration

    Since the integration leverages the lens:// URL protocol handling feature for extensions, Lens 4.2 (or later) is required, and the Keycloak Client of the instance must be configured as follows:

    • Allow the following redirect URI: lens://extensions/@mirantis/lens-extension-cc/oauth/code

    💡 Be sure to make these configuration adjustments on every Keycloak Client (kaas for the management cluster, and k8s for child clusters, by default) that manages clusters you will want to add. The extension does not know ahead of time whether you have given it the appropriate access, and adding clusters without this configuration will result in an error.

    💬 Mirantis Container Cloud 2.9 configures the above for you automatically so you should not have to do this if you're using 2.9 or later.

    Authentication flow

    When connecting to an instance that uses SSO, Lens will open the instance's SSO authorization page in the system's default browser.

    Once authorized, Keycloak will redirect to the lens://... URL, triggering the browser to ask permission to open the Lens app to process the request (unless permission was granted previously with the always allow check box for your SSO ID Provider, e.g. accounts.google.com):

    Lens protocol permission - always allow

    ⚠️ Even if you check the "Always allow" box, your browser may still continue to show a popup message waiting for you to click on an "Open Lens.app" button. This is a built-in security feature. Please be on the look out for this popup in your browser whenever accessing your Container Cloud instance, or adding clusters to Lens.

    Whether the permission was already given, or upon clicking Open Lens.app, Lens will receive focus again, and the extension will then read the list of namespaces and clusters and present them for selection.

    The temporary browser window used for SSO authorization will likely still be open, and should now be closed manually.

    Single cluster limitation

    Due to technical issues with generating a unique kubeConfig per cluster, when the Container Cloud instance uses SSO authorization, cluster selection is limited to a single cluster:

    Single cluster SSO limitation

    We hope to overcome this limitation in the future.

    Supported protocol requests

    Lens 4.2 introduced a new custom Lens protocol handler. This means Lens can now respond to lens:// URL requests made in the browser, and this extension can now support some interesting requests that enable tighter integration between Mirantis Container Cloud instances and Lens.

    Note that this integration is a one-way street: Container Cloud -> Lens. It does not work the other way around. Reverse integration is achieved simply by making Container Cloud API requests from Lens, which is much easier to achieve, and has been used by this extension since its inception.

    The base URL for requests that this extension can respond to is:

    lens://extensions/@mirantis/lens-extension-cc
    

    The following APIs are currently supported by this extension, from the base URL above:

    Protocol - Activate cluster

    Activates a cluster already added to Lens.

    GET /activateCluster
      ?cloudUrl={string}
      &namespace={string}
      &clusterName={string}
      &clusterId={string}
    
    • cloudUrl: URL to the instance, e.g. https://container-cloud.my-company.com
    • namespace: ID of the Container Cloud namespace containing the cluster to activate.
    • clusterName: Name of the cluster to activate.
    • clusterId: ID of the cluster (in namespace) to activate.

    Protocol - Add one cluster

    Adds a single cluster to Lens (if it hasn't already been added) by providing a pre-configured kubeConfig JSON object for the cluster. As such, this endpoint does not require the extension to perform any authentication/authorization requests. It simply stores the kubeConfig on disk and tells Lens where to find it.

    GET /kubeConfig
      ?cloudUrl={string}
      &namespace={string}
      &clusterName={string}
      &clusterId={string}
      &kubeConfig={string}
    
    • cloudUrl: URL to the instance, e.g. https://container-cloud.my-company.com
    • namespace: ID of the Container Cloud namespace containing the cluster to activate.
    • clusterName: Name of the cluster to activate.
    • clusterId: ID of the cluster (in namespace) to activate.
    • kubeConfig: JSON-stringified, Base64-encoded kubeConfig payload.

    Protocol - Add multiple clusters

    Allows the user to add one or more clusters to Lens by telling the extension where to find them. Unlike adding one cluster, it does not automatically add any clusters to Lens. It simply triggers the extension to immediately list all available clusters, and then lets the user choose which ones to add.

    GET /addClusters
      ?cloudUrl={string}
      &username={string}
      &tokens={string}
      [ &namespaces={string} ]
    
    • cloudUrl: URL to the instance, e.g. https://container-cloud.my-company.com
    • username: Username associated with the tokens.
    • tokens: JSON-stringified, Base64-encoded OAuth2 tokens for the user.
    • namespaces (Optional): Comma-delimited list of namespace IDs to restrict the list of clusters presented by the extension (i.e. a filter on namespaces). Only clusters in these namespaces will be listed.

    Protocol - SSO OAuth Code

    Allow the extension to use the system's default browser to broker an OAuth authorization code with a Keycloak client in a Container Cloud instance. This is used both for general access (to list clusters) as well as specific cluster access to generate kubeConfig files to add to Lens.

    GET /oauth/code
      ?code={string}
      [ &state={string} ]
      [ &error={string} ]
      [ &error_description={string} ]
    
    • code: Temporary authorization code to exchange for API tokens.
    • state (Optional): Used to differentiate between requests for general access and specific access. The value is generated by the extension as part of the request and should come back as part of the response.
    • error (Optional): OAuth error message, if an error occurs.
    • error_description (Optional): OAuth error description, if an error occurs.

    FAQ

    • Why are management clusters not selected by default?
      • The extension purposely doesn't not add management clusters to the default/initial set of selected clusters after retrieving clusters from a Mirantis Container Cloud instance because they are typically of less interest than workload clusters.
    • I get an error, "Invalid redirect_uri", when I attempt to access or add my clusters.
      • Make sure you have properly configured all your Keycloak clients for use with the extension.
    • Why can I only selected one cluster to add at a time?
    • I was able to add my cluster to Lens, but Lens fails to show it because of an authentication error.
      • Check if the cluster is only accessible over a private network (i.e. VPN) connection, and try opening it in Lens once connected to the network. Even though you can see the cluster in Container Cloud, as well as in the extension, accessing the cluster's details may still require a VPN connection in this case.
    • Up to, and including, Lens 5.1.3 (and probably some versions after that as well), I get an error like, "Failed to add cluster to Lens" after choosing a cluster and clicking on the "Add cluster" button in the extension, or choosing the "Add cluster to Lens" cluster menu option in Mirantis Container Cloud v2.9 or later.
      • Lens must be restarted after upgrading the extension. This is due to a bug in Lens that causes the extension's registration of IPC event handlers to be ignored, leading to an error message like this. This Lens PR tracks the fix.

    Development

    Yarn 1.x is required

    First, quit Lens if it's currently running.

    Then, clone the repository wherever you prefer to have your code, and then link to it:

    $ git clone https://github.com/Mirantis/lens-extension-cc.git /your/src/path
    $ mkdir -p ~/.k8slens/extensions
    $ ln -s /your/src/path ~/.k8slens/extensions/lens-extension-cc
    $ cd /your/src/path
    $ yarn       # install dependencies
    $ yarn start # start dev build in watch mode

    This will put the development build into watch mode.

    Restart Lens and go to the Extensions View (CMD+SHIFT+E on macOS) to enable it, which will cause it to load for the first time.

    Now, as you make source changes, the build will run, and all you need to do is reload the Lens window (CMD+R on macOS) to see your changes.

    You can also run a one-off development build with yarn dev.

    Note these steps will get much easier once this Lens issue is fixed.

    Dev - Uninstalling

    Go to the Lens Extensions View (CMD+SHIFT+E on macOS) and use the UI to uninstall it.

    This will simply remove the symlink you created in ~/.k8slens/extensions and leave your linked directory intact.

    Dev - Publishing

    First, update the CHANGELOG:

    • Make sure everything in UNRELEASED is accurate
    • Change UNRELEASED -> vX.Y.Z (version that will be published)

    Then use NPM:

    $ npm version <patch|minor|major>
    $ npm publish --access public        # <- NOTE the '--access public' part!
    $ git push && git push --tags

    By default, packages published to an NPM scope/org are private. Use the --access public option to publish it as a public package instead. You can also configure NPM to always publish that single package publicly by running npm config set access public within the repository root directory (i.e. package root).

    The prepublishOnly script will automatically produce a production build in the ./dist directory, which will be published.

    Install

    npm i @mirantis/lens-extension-cc

    DownloadsWeekly Downloads

    7

    Version

    3.1.2

    License

    MIT

    Unpacked Size

    3.84 MB

    Total Files

    6

    Last publish

    Collaborators

    • stefcameron