Skip to content

Managing and Upgrading Existing Customer Deployments with Omnistrate

Omnistrate provides a powerful feature to adopt, manage, and upgrade existing customer application installations directly from the Omnistrate Command Line Interface (CLI). This allows your support and operations teams to centralize the management of both new and existing deployments, streamlining the entire lifecycle from a single control plane.

This document outlines the process of adopting an existing customer deployment (specifically a Helm-based application running on a Kubernetes cluster) and managing its upgrade path.

Note

Currently, Omnistrate supports adopting Helm-based applications running on Kubernetes clusters. Future versions will expand support to other deployment types.

Core Concepts

  • Deployment Cell: In Omnistrate, a Deployment Cell is a fundamental building block representing an isolated environment where your application runs. In this context, a customer's existing Kubernetes cluster is treated as a Deployment Cell.
  • Adoption: This is the process of bringing an existing, unmanaged customer cluster and application under Omnistrate's management. This is a two-step process: first adopting the cluster (Cell), and then adopting the application (Instance) running within it.
  • Omnistrate Agent: A lightweight agent that gets installed in the customer's cluster. It establishes a secure, reverse-tunnel connection back to your control plane, allowing for management without requiring the customer to open inbound firewall ports.
  • Instance: Represents a specific application deployment, such as a Helm release, that has been adopted and is now managed by Omnistrate.

Step-by-Step Guide

Step 1: Create a Customer User (if not already done)

Before adopting a customer's deployment, ensure that the customer has a registered user account in the Omnistrate UI. This is necessary to link the deployment cell to their account. If the customer does not have an account, you can create one using the Omnistrate UI.

Note

Make sure to enable Auto Verify User to ensure the customer account is activated immediately.

Step 2: Adopt the Customer's Kubernetes Cluster (Deployment Cell)

The first step is to register the customer's existing Kubernetes cluster with Omnistrate. This is done using the omctl deployment-cell adopt command. For more details see the Adopt Deployment Cells Guide.

  1. Run the Adopt Command: Execute the following command, providing details about the customer's cluster.

    omctl deployment-cell adopt \
  --cloud-provider aws \
  --description "Adopted Customer Cluster" \
  --id "example-cluster" \
  --region "us-east-1" \
  --customer-email "customer.email@example.com"
    • --id: A unique, memorable name for this deployment cell.
    • --cloud-provider & --region: The location of the customer's cluster. Can be omitted for on-premises clusters.
    • --customer-email: The email of the customer as registered in the Omnistrate portal, linking the cell to their account.

  2. Provide the Agent Installation Kit to the Customer: Running the command successfully initiates the adoption process and generates an Agent Installation Kit (e.g., example-cluster.tar). This compressed file contains the necessary manifests for the customer to install the Omnistrate agent.

    The status of the cell will be PENDING_ADOPTION until the agent is installed.

Step 3: Customer Installs the Omnistrate Agent

The customer must perform this one-time installation in their cluster.

  1. The customer untars the installation kit (example-cluster.tar).
  2. The kit includes a README.md file with simple kubectl commands.
  3. The customer runs the provided kubectl apply commands, which creates a new namespace (e.g., dataplane-agent) and deploys the Omnistrate agent.

Step 4: Verify Cluster Adoption

Once the agent is running, it will connect back to your Control Plane. You can verify this from your CLI:

omctl deployment-cell status --id example-cluster

The STATUS should now show as HEALTHY and RUNNING, indicating that Omnistrate can now manage the cluster.

Step 5: Adopt the Application Instance (Helm Chart)

With the cluster managed, you can now adopt the specific application running inside it.

  1. Create an Adoption Configuration File: Create a YAML file (e.g., adoption-config.yaml) to describe the Helm release(s) you want to adopt.

    Note

    This file should include the Helm chart repository, release name, namespace, and any necessary credentials. Please ensure that the credentials are set correctly to allow the deployment cell to access the Helm chart repository. This example includes multiple Helm charts for the application platform version.

    resourceAdoptionConfiguration:
  mainApp:
    helmAdoptionConfiguration:
      chartRepoURL: "oci://registry-1.docker.io/mycompanydev"
      releaseName: "app"
      releaseNamespace: "my-app"
      username: "admin"
      password: "dckr_pat_xyz123"
      runtimeConfiguration:
        wait: false
        waitForJobs: false
  supportService:
    helmAdoptionConfiguration:
      chartRepoURL: "oci://registry-1.docker.io/mycompanydev"
      releaseName: "support-svc"
      releaseNamespace: "my-app"
      username: "admin"
      password: "dckr_pat_xyz123"
      runtimeConfiguration:
        wait: false
        waitForJobs: false

  2. Get a list of all the supported platform versions for this service on Omnistrate

omctl service-plan list-versions --service-id s-xK8FMLq7R9 --plan-id pt-nB3Wz6yhKp -f="environment:Prod,service_name:My Application Platform"

✓ Service plan versions retrieved successfully
+-------------+---------------+-----------------------------------+---------------------+--------------+-------------------------+---------+--------------------+
| ENVIRONMENT | PLAN_ID       | PLAN_NAME                         | RELEASE_DESCRIPTION | SERVICE_ID   | SERVICE_NAME            | VERSION | VERSION_SET_STATUS |
+-------------+---------------+-----------------------------------+---------------------+--------------+-------------------------+---------+--------------------+
| Prod        | pt-nB3Wz6yhKp | My Application Enterprise         | 3.2.1               | s-xK8FMLq7R9 | My Application Platform | 3.0     | Preferred          |
| Prod        | pt-nB3Wz6yhKp | My Application Enterprise         | 3.1.4               | s-xK8FMLq7R9 | My Application Platform | 2.0     | Active             |
| Prod        | pt-nB3Wz6yhKp | My Application Enterprise         | 2.5.8               | s-xK8FMLq7R9 | My Application Platform | 1.0     | Active             |
+-------------+---------------+-----------------------------------+---------------------+--------------+-------------------------+---------+--------------------+

  1. Run the Instance Adopt Command: Execute the instance adopt command, referencing the cluster and the configuration file. The following command adopts a 2.5.8 application installation running on the example-cluster deployment cell, using the adoption-config.yaml file to specify the Helm charts and their configurations.

    omctl instance adopt \
  --host-cluster-id example-cluster \
  --service-id s-xK8FMLq7R9 \
  --service-plan-id pt-nB3Wz6yhKp \
  --service-plan-version 1.0 \
  --primary-resource-key mainApp \
  -f adoption-config.yaml

    This command registers the specified Helm charts as a single manageable instance. Omnistrate automatically discovers and stores the currently deployed Helm values.

Step 6: Manage and Upgrade the Adopted Instance

Once adopted, the application instance is a native deployment instance on Omnistrate.

  • Secure Remote Access: To debug or run pre-upgrade scripts, you can securely access the customer's cluster from your local machine. For more details, see the Remotely Access Deployment Cells Guide.

    omctl deployment-cell update-kubeconfig example-cluster --role cluster-admin

    This command fetches a temporary kubeconfig by establishing a secure reverse-tunnel. You can now use kubectl and helm as if you were directly on the cluster, without any network changes on the customer's side.

  • Perform an Upgrade: Upgrading the instance is now a standard Omnistrate procedure.

    • Generate both existing chart values and the proposed chart values for the upgrade. The following command generates both the existing chart values and the chart values proposed from the target tier version as setup in your service template on Omnistrate.
    # MAKE SURE TO REPLACE THE INSTANCE ID WITH THE ACTUAL INSTANCE ID FROM THE PREVIOUS ADOPTION STEP
omctl instance version-upgrade <INSTANCE ID> --existing-configuration existing.yaml  --proposed-configuration proposed-config.yaml --generate-configuration --target-tier-version 1.0 # CHANGE THE TARGET TIER VERSION TO MATCH THE TARGET PLATFORM VERSION
    • Run any pre-upgrade scripts or checks as needed.

    Using the Secure Remote Access feature, you have direct access to the Kubernetes cluster to run any necessary pre-upgrade scripts or checks.

    • Upgrade the instance with the default template values.

    You can trigger an upgrade to a new version with the default args and the platform will use the values setup in the service template for that particular platform version.

    omctl instance version-upgrade <INSTANCE_ID> \
  --target-tier-version 2.0 # Eg: Upgrading from 2.5.8 (Tier version 1.0) to 3.1.4 (Tier version 2.0)
    • Upgrade the instance with modified values.

    If you need to override the default values, you can provide a custom values file. This allows you to specify any modifications needed for the upgrade. For example, if you have a modified values file named modified-values.yaml, you can run the following command:

    omctl instance version-upgrade <INSTANCE_ID> \
  --target-tier-version 2.0 \
  --upgrade-configuration-override modified-values.yaml
    • Applying modifications to existing values for the same platform version.

    If you need to modify the existing values for the same platform version, you can use the same command as above but specify the target tier version same as the current version.

    omctl instance version-upgrade <INSTANCE_ID> \
  --target-tier-version 1.0 \
  --upgrade-configuration-override modified-values.yaml
    • Debug any installation issues.

    If the upgrade fails or is taking too long, you can either use the Secure Remote Access to directly check the status using kubectl or helm commands. In addition, the helm client logs and the actual chart values being applied are available through the instance debug command:

    omctl instance debug <INSTANCE_ID>

  • Centralized View:

    Use omctl instance list to see a consolidated list of all customer deployments, both newly created and adopted, providing a single pane of glass for managing your entire fleet.