Adopting an Existing Kubernetes Cluster as a Deployment Cell on Omnistrate¶
What Does It Mean to Adopt a Deployment Cell?¶
Adopting a deployment cell means integrating an existing Kubernetes cluster into Omnistrate's cellular architecture as a managed deployment target. This process transforms your existing infrastructure into an Omnistrate-managed deployment cell while preserving your current investments and operational practices.
Key Benefits of Adoption¶
Leverage Existing Infrastructure: Instead of provisioning new infrastructure, you can utilize existing Kubernetes clusters that you or your customers have already invested in. This approach maximizes ROI on current infrastructure while gaining Omnistrate's management capabilities.
Maintain Control and Compliance: Adopted cells allow you to keep infrastructure within your existing security boundaries and compliance frameworks. This is particularly valuable for:
- Regulated industries with strict data residency requirements
- Organizations with existing security and compliance certifications
- Customers who prefer to maintain direct control over their infrastructure
How Adoption Works¶
When you adopt a deployment cell, Omnistrate installs a lightweight agent on your Kubernetes cluster that:
- Establishes secure communication with the Omnistrate control plane
- Enables deployment and management of services through Omnistrate
- Provides monitoring and observability integration
- Maintains the cluster's existing security and network configurations
The adopted cluster becomes a fully managed deployment cell within Omnistrate's cellular architecture, allowing you to deploy and manage services alongside other deployment cells in your fleet.
Deployment Cell Adoption Guide¶
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¶
omctlCLI tool installed- Access to the Kubernetes cluster you want to adopt
Step-by-Step Guide¶
1. Login as SaaS Provider¶
First, authenticate as the SaaS Provider who will be onboarding customer Kubernetes clusters:
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 \
--customer-email alok+drprod@omnistrate.com
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 - --customer-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: alok+drprod@omnistrate.com
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:
Example output:
+----------------+-------------------------------+----------------------------+----------------------------+-----------------------------------------+-----------+-----------+------------------+------------+
| CLOUD_PROVIDER | CURRENT_NUMBER_OF_DEPLOYMENTS | CUSTOMER_EMAIL | CUSTOMER_ORGANIZATION_NAME | HEALTH_STATUS | ID | REGION | STATUS | TYPE |
+----------------+-------------------------------+----------------------------+----------------------------+-----------------------------------------+-----------+-----------+------------------+------------+
| aws | 0 | alok+drprod@omnistrate.com | 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:
Example output:
+----------------+-------------------------------+----------------------------+----------------------------+-----------------------------------------+-----------+-----------+------------------+------------+
| CLOUD_PROVIDER | CURRENT_NUMBER_OF_DEPLOYMENTS | CUSTOMER_EMAIL | CUSTOMER_ORGANIZATION_NAME | HEALTH_STATUS | ID | REGION | STATUS | TYPE |
+----------------+-------------------------------+----------------------------+----------------------------+-----------------------------------------+-----------+-----------+------------------+------------+
| aws | 0 | alok+drprod@omnistrate.com | 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¶
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:
Success output:
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_ADOPTIONstatus 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
UNKNOWNuntil 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.