Skip to content

Adopting an Existing Kubernetes Cluster as a Deployment Cell on Omnistrate

This guide walks you through the process of adopting an existing Kubernetes cluster as a deployment cell on Omnistrate using the omctl command-line tool. This allows you to onboard existing deployments in your or your customer's Kubernetes clusters and map them to deployment instances in the Omnistrate platform.

Prerequisites

  • omctl CLI tool installed
  • Access to the Kubernetes cluster you want to adopt

Step-by-Step Guide

1. Login as Service Provider

First, authenticate as the service provider who will be onboarding customer Kubernetes clusters:

omctl login

2. Adopt the Kubernetes Cluster

Use the deployment-cell adopt command to register your existing Kubernetes cluster:

omctl deployment-cell adopt \
  --cloud-provider aws \
  --description "adopted cluster" \
  --id "cluster-1" \
  --region us-east-1 \
  --user-email [email protected]

Parameters: - --cloud-provider: The cloud provider where your cluster is hosted (e.g., aws, gcp, azure) - --description: A descriptive name for your deployment cell - --id: A unique identifier for the deployment cell - --region: The region where the cluster is located - --user-email: (Optional) Email of the customer who owns the cluster. If not provided, the cluster will be adopted under the logged-in user

This command will initiate the adoption process and register the cluster with Omnistrate. It will also download an installation kit for the agent that needs to be installed on the cluster in the same directory where you run the command.

Example output: 

Adopting deployment cell:
  ID: cluster-1
  Cloud Provider: aws
  Region: us-east-1
  Description: adopted cluster
  User Email: [email protected]
Deployment cell adoption initiated successfully!
Adoption result:
  Adoption Status: PENDING_ADOPTION
  Agent Installation Kit: Saved as cluster-1.tar
  Note: Use the agent installation kit to complete the adoption process

3. Install the Agent on the Cluster

To complete the adoption, you need to install the Omnistrate agent on your Kubernetes cluster by following the README instructions provided in the downloaded installation kit (cluster-1.tar).

Extract the kit and follow the instructions:

mkdir kit && cp cluster-1.tar kit && cd kit
tar -xf cluster-1.tar

# Eg:
# First set the kubectl context to your desired cluster

# Then apply the necessary Kubernetes manifests to set up the deployment agent:
# Create namespace first and wait for it to be created
kubectl apply -f ./ns.yaml && \
  kubectl wait --for=jsonpath='{.status.phase}'=Active namespace/dataplane-agent --timeout=60s

# Apply the necessary manifests to set up the deployment agent
kubectl apply -f ./cluster-role-binding.yaml \
    -f ./deployment.yaml \
    -f ./dp-agent-tls.yaml \
    -f ./priority-class.yaml \
    -f ./sa.yaml

# Wait for the agent to be ready
kubectl -n dataplane-agent wait deployment/dp-agent --for=condition=Available --timeout=60s

3. Check Adoption Status

Verify the adoption status of your cluster:

omctl deployment-cell status --id cluster-1

Example output: 

+----------------+-------------------------------+----------------------------+----------------------------+-----------------------------------------+-----------+-----------+------------------+------------+
| CLOUD_PROVIDER | CURRENT_NUMBER_OF_DEPLOYMENTS | CUSTOMER_EMAIL             | CUSTOMER_ORGANIZATION_NAME | HEALTH_STATUS                           | ID        | REGION    | STATUS           | TYPE       |
+----------------+-------------------------------+----------------------------+----------------------------+-----------------------------------------+-----------+-----------+------------------+------------+
| aws            |                             0 | [email protected] | Omnistrate                 | Status: UNKNOWN | Entities: 0/0 healthy | cluster-1 | us-east-1 | PENDING_ADOPTION | Kubernetes |
+----------------+-------------------------------+----------------------------+----------------------------+-----------------------------------------+-----------+-----------+------------------+------------+

4. Filter Status by Customer Email

To view the status for a specific customer:

omctl deployment-cell status --id cluster-1 --customer-email [email protected]

Example output: 

+----------------+-------------------------------+----------------------------+----------------------------+-----------------------------------------+-----------+-----------+------------------+------------+
| CLOUD_PROVIDER | CURRENT_NUMBER_OF_DEPLOYMENTS | CUSTOMER_EMAIL             | CUSTOMER_ORGANIZATION_NAME | HEALTH_STATUS                           | ID        | REGION    | STATUS           | TYPE       |
+----------------+-------------------------------+----------------------------+----------------------------+-----------------------------------------+-----------+-----------+------------------+------------+
| aws            |                             0 | [email protected] | Omnistrate                 | Status: UNKNOWN | Entities: 0/0 healthy | cluster-1 | us-east-1 | PENDING_ADOPTION | Kubernetes |
+----------------+-------------------------------+----------------------------+----------------------------+-----------------------------------------+-----------+-----------+------------------+------------+

5. Delete a Deployment Cell

To remove a deployment cell:

Deregistering a Deployment Cell

omctl deployment-cell delete --id cluster-1 --customer-email [email protected]

You'll be prompted for confirmation: 

Are you sure you want to delete deployment cell 'cluster-1'? This action cannot be undone.
Type 'yes' to confirm:

For non-interactive deletion, use the --force flag:

omctl deployment-cell delete --id cluster-1 --customer-email [email protected] --force

Success output: 

Deleting deployment cell: cluster-1
Deployment cell 'cluster-1' deleted successfully!

Uninstalling the Agent

After deregistering, you may want to uninstall the agent from the Kubernetes cluster. Follow the instructions in the README of the installation kit to remove the agent resources from your cluster.

Important Notes

  • The PENDING_ADOPTION status indicates that the cluster adoption process is in progress and waiting for the agent to be installed and connected.
  • Multiple customers can have deployment cells with the same ID in different organizations
  • Deletion is permanent and cannot be undone
  • Health status will show as UNKNOWN until the adoption process is complete and the cluster is fully integrated

Next Steps

After successful adoption, you can: - Deploy services to the adopted cluster - Monitor cluster health and performance - Manage customer access and permissions

For more information, refer to the Omnistrate documentation or contact support.