Kubernetes Operator - Control Plane

The Control Plane Kubernetes Operator enables you to manage Control Plane resources directly from your Kubernetes cluster using custom resource definitions (CRDs). It bridges the gap between Kubernetes-native workflows and Control Plane infrastructure.

What you’ll achieve

By the end of this guide, you will have:

A Kubernetes cluster with the Control Plane operator installed
Authentication configured between your cluster and Control Plane
The ability to deploy and manage Control Plane resources using Kubernetes CRDs
Optional ArgoCD integration for GitOps workflows

When to use this

GitOps workflows

Manage Control Plane resources alongside your Kubernetes manifests in Git

ArgoCD integration

Deploy Control Plane resources through ArgoCD applications

Kubernetes-native experience

Manage GVCs, workloads, secrets, and more using CRDs

Infrastructure as Code

Define your entire Control Plane infrastructure declaratively

Supported resources

The operator manages the following Control Plane resource types through CRDs:

Resource	Description
`agent`	Secure connectivity to private networks and cloud provider services
`auditctx`	Tamper-proof audit trail for tracking actions
`cloudaccount`	Cloud provider integrations (AWS, GCP, Azure, NGS)
`domain`	Custom domain mapping with TLS and geo-routing
`group`	Membership collection of users and service accounts
`gvc`	Global Virtual Cloud - groups workloads and defines deployment locations
`identity`	Grants workloads access to cloud resources and private networks
`ipset`	Reserved public IP addresses for workloads
`location`	Cloud regions where workloads can be deployed
`mk8s`	Managed Kubernetes clusters across cloud providers
`org`	Top-level context for all Control Plane resources
`policy`	Grants permissions to principals on target resources
`secret`	Encrypted storage for credentials and sensitive data
`serviceaccount`	Machine identity for headless API operations
`volumeset`	Persistent storage with snapshots and auto-scaling
`workload`	Application containers running on Control Plane

Prerequisites

Kubernetes cluster

A running Kubernetes cluster (v1.19+). This can be:

A managed cluster (EKS, GKE, AKS)
A local cluster (kind, minikube, Docker Desktop)
Any conformant Kubernetes distribution

If you don’t have a cluster, see Quick start (local cluster) to set one up.

Helm CLI

Install Helm v3.0+ for deploying the operator:

# macOS
brew install helm

# Linux
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# Windows
choco install kubernetes-helm

For other installation methods, see the Helm installation guide.

kubectl configured

Ensure kubectl is configured and can communicate with your cluster:

kubectl cluster-info

Control Plane account

You need to be signed up to Control Plane and have access to an org. If you don’t already:

Sign up for Control Plane and create a billing account
Create an Org

You also need permissions to create service accounts within your org.

Quick start (local cluster)

If you don’t have a Kubernetes cluster, you can set up a local one for testing.

Docker must be installed and running on your machine for local Kubernetes clusters.

Repo Quick Start
kind
minikube

Clone the operator repository and run the quick start command to create a local kind cluster with the operator pre-installed:

git clone https://github.com/controlplane-com/k8s-operator.git
cd k8s-operator
make cluster-quickstart

This creates a kind cluster and installs cert-manager and the operator automatically.Verify the cluster is running:

kubectl cluster-info

Install kind, then create a cluster:

kind create cluster --name cpln-operator

# Verify
kubectl cluster-info

Then continue with the installation steps below.

Install minikube, then start a cluster:

minikube start

# Verify
kubectl cluster-info

Then continue with the installation steps below.

Installation

If you used the Repo Quick Start above, skip to Step 3: Configure authentication — cert-manager and the operator are already installed.

Step 1: Install cert-manager

The operator requires cert-manager for webhook certificate management.

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.3/cert-manager.yaml

Wait for cert-manager to be ready:

kubectl wait --for=condition=Available deployment --all -n cert-manager --timeout=300s

Step 2: Install the operator

Add the Control Plane Helm repository and install the operator:

# Add the Helm repository
helm repo add cpln https://controlplane-com.github.io/k8s-operator
helm repo update

# Install the operator in the controlplane namespace
helm install cpln-operator cpln/cpln-operator \
  -n controlplane \
  --create-namespace

Verify the operator is running:

kubectl get pods -n controlplane -l app=operator

Step 3: Configure authentication

The operator needs credentials to communicate with the Control Plane API. You have two options:

Using the CLI (Recommended)
Manual setup

The CLI automatically creates the service account and Kubernetes secret:

cpln operator install \
  --serviceaccount k8s-operator \
  --org YOUR_ORG_NAME

This command:

Creates a service account

Creates a service account named k8s-operator if it doesn’t already exist

Assigns group membership

Adds the service account to the superusers group (customizable with --serviceaccount-group)

Generates authentication key

Creates a new key for the service account

Creates Kubernetes secret

Stores the credentials as a secret in the controlplane namespace

Command options:

Option	Description
`--serviceaccount, -s`	Service account name (required)
`--serviceaccount-group, -g`	Group to assign (default: `superusers`)
`--export`	Export YAML to stdout instead of applying to cluster
`--org`	Target organization

Use --export to review or store the Kubernetes resources before applying:

# Export to a file for review or GitOps
cpln operator install \
  --serviceaccount k8s-operator \
  --org YOUR_ORG_NAME \
  --export > operator-secret.yaml

# Apply later
kubectl apply -f operator-secret.yaml

For production, assign the service account to a group with limited permissions:

cpln operator install \
  --serviceaccount k8s-operator \
  --serviceaccount-group operators \
  --org YOUR_ORG_NAME

If you prefer manual control, create the secret yourself:1. Create a service account in Control Plane:

cpln serviceaccount create --name k8s-operator --org YOUR_ORG_NAME

2. Add it to a group with appropriate permissions:

cpln group add-member superusers --serviceaccount k8s-operator --org YOUR_ORG_NAME

3. Generate a key:

cpln serviceaccount add-key k8s-operator --description "cpln operator" --org YOUR_ORG_NAME -o json

Save the key value from the output.4. Create the Kubernetes secret:

# Create the namespace if it doesn't exist
kubectl create namespace controlplane --dry-run=client -o yaml | kubectl apply -f -

Create a file named operator-secret.yaml with the following content:

apiVersion: v1
kind: Secret
metadata:
  name: YOUR_ORG_NAME
  namespace: controlplane
  labels:
    app.kubernetes.io/managed-by: cpln-operator
  annotations:
    cpln.io/service-account: k8s-operator
data:
  token: BASE64_ENCODED_KEY  # base64 encode your key: echo -n "YOUR_KEY" | base64

Apply the secret:

kubectl apply -f operator-secret.yaml

Generating CRD manifests

You don’t need to write CRD manifests from scratch. Control Plane can export any resource in Kubernetes CRD format.

Console UI
CLI

Export existing resources:

Navigate to any resource (GVC, workload, identity, etc.)
Click the Export dropdown in the upper right corner
Select K8s CRD to download the manifest

Preview during creation:

Create a new resource and configure it using the UI
Before clicking Create, click Preview
Select K8s CRD to generate the manifest
Copy or download the YAML without deploying

This lets you use the UI’s guided configuration, then store the manifest in Git for GitOps deployments.

Export any existing resource with the -o crd flag:

# Export a workload
cpln workload get my-workload --gvc production -o crd --org my-org

# Export a GVC
cpln gvc get production -o crd --org my-org

# Export an identity
cpln identity get my-identity --gvc production -o crd --org my-org

# Save directly to a file
cpln workload get my-workload --gvc production -o crd --org my-org > workload.yaml

Combine this with ArgoCD: configure resources in the console, export as CRDs, commit to your Git repository, and let ArgoCD handle deployments automatically.

Deploying resources

All Control Plane resources are managed through CRDs. Each resource requires:

org: The target Control Plane organization
gvc: The target GVC (for GVC-scoped resources like workloads and identities)

We recommend organizing resources by namespace:

One namespace per GVC for GVC-scoped resources (workloads, identities, volumesets)
One namespace per org for org-scoped resources (GVCs, secrets, policies)

The CRD structure differs from standard Kubernetes resources. Fields like org, gvc, and description are at the top level, not inside spec. Always use the export feature to generate accurate manifests.

Apply with kubectl

You can apply CRD manifests directly using kubectl. Save the following GVC manifest to a file (e.g., gvc.yaml):

apiVersion: cpln.io/v1
kind: gvc
metadata:
  name: my-gvc
  namespace: default
org: YOUR_ORG_NAME  # Replace with your Control Plane org name
description: my-gvc
spec:
  staticPlacement:
    locationLinks:
      - //location/aws-eu-central-1

Apply it to your cluster:

kubectl apply -f gvc.yaml

Verify the resource was created:

kubectl get gvcs

The operator syncs the CRD to Control Plane. You can verify the GVC exists:

cpln gvc get my-gvc --org YOUR_ORG_NAME

GitOps with ArgoCD

For production workflows, store your CRD manifests in a Git repository or package them as a Helm chart, and use ArgoCD to manage deployments automatically.

Preventing resource deletion

Deleting a Kubernetes resource while the operator is installed and running will remove the corresponding resource from Control Plane. You can prevent this by adding the cpln.io/resource-policy: keep annotation to the metadata:

kind: gvc
apiVersion: cpln.io/v1
org: your-org-name
metadata:
  name: production
  annotations:
    cpln.io/resource-policy: keep
spec:
  # ...

With this annotation, deleting the Kubernetes resource will not delete the Control Plane resource.

ArgoCD integration

The operator integrates seamlessly with ArgoCD for GitOps workflows. Once the operator is installed, you can point ArgoCD at a Git repository containing YAML manifests or a Helm chart.

This section assumes ArgoCD is already installed on your cluster. See the ArgoCD installation guide if you haven’t set it up yet.

Defining ArgoCD applications

An ArgoCD Application defines what to deploy (source) and where to deploy it (destination). For Control Plane CRDs, you can use either a Helm chart or raw YAML manifests stored in a Git repository. Save the manifest to a file (e.g., app.yaml) and update the placeholder values before applying.

Helm Chart
YAML Manifests

Point ArgoCD at a Helm repository containing your Control Plane CRD templates:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-helm-app
  namespace: argocd  # This is usually where ArgoCD is installed
spec:
  project: default
  destination:
    server: https://kubernetes.default.svc  # Cluster API server URL
    namespace: your-namespace  # Target namespace in your cluster
  source:
    repoURL: https://your-org.github.io/your-repo/  # URL of your Helm repository
    chart: my-cpln-chart  # Name of your Helm chart
    targetRevision: 0.1.0  # Chart version
    helm:
      values: |
        org: your-org-name
  syncPolicy:
    automated:
      prune: true  # Automatically delete resources no longer defined in the chart
      selfHeal: true  # Automatically sync drifted resources

To create your own Helm chart:

Create a new Helm chart: helm create my-cpln-chart
Add your Control Plane CRD manifests to the templates/ directory
Push the chart to a GitHub repository
Publish the chart to GitHub Pages or a Helm repository

Point ArgoCD at a Git repository containing Control Plane CRD manifests:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-cpln-app
  namespace: argocd  # This is usually where ArgoCD is installed
spec:
  project: default
  destination:
    server: https://kubernetes.default.svc  # Cluster API server URL
    namespace: your-namespace  # Target namespace in your cluster
  source:
    repoURL: https://github.com/your-org/your-repo.git  # Your Git repository URL
    path: manifests  # Path to the directory containing YAML files
    targetRevision: main  # Branch, tag, or commit
  syncPolicy:
    automated:
      prune: true  # Automatically delete resources no longer defined in the repo
      selfHeal: true  # Automatically sync drifted resources

Apply your ArgoCD Application:

kubectl -n argocd apply -f app.yaml

Example application

The k8s-operator repository includes a ready-to-use example that deploys a GVC, workload, identity, and other resources. Copy the following manifest and save it to a file (e.g., example-app.yaml):

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-helm-app
  namespace: argocd
spec:
  project: default
  destination:
    server: 'https://kubernetes.default.svc'
    namespace: fresh
  source:
    repoURL: 'https://cuppojoe.github.io/argo-example/'
    chart: argo-example
    targetRevision: 0.2.3
    helm:
      values: |
        org: YOUR_ORG_NAME  # Replace with your Control Plane org name
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Before applying:

Replace YOUR_ORG_NAME with your actual Control Plane org name

Apply the manifest:

kubectl apply -f example-app.yaml

The example Helm chart creates the following Control Plane resources:

GVC named fresh in aws-eu-central-1
Workload with a serverless container
Identity for cloud access
Policy for permissions
Secret for credentials
Additional resources (agent, domain, ipset)

Connecting to the ArgoCD UI

To access the ArgoCD UI, retrieve the admin password and port-forward the service:

# Print the initial admin password
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d && echo

# Port-forward to the ArgoCD UI
kubectl -n argocd port-forward service/argocd-server 18081:443

Open a browser and navigate to https://localhost:18081. Accept the self-signed certificate and log in with username admin and the password from the command above.

Store your Control Plane CRD manifests in a Git repository and point ArgoCD at it. Changes merged to your main branch will automatically sync to Control Plane.

Secrets handling

For security reasons, secret data must be stored using a native Kubernetes Secret object, not a custom resource. This makes secrets slightly different from other resource types.

The app.kubernetes.io/managed-by: cpln-operator label is required for the operator to manage the secret. Secrets without this label are ignored.

apiVersion: v1
kind: Secret
type: opaque
metadata:
  name: my-secret
  namespace: default
  labels:
    app.kubernetes.io/managed-by: cpln-operator  # Required for operator to manage this secret
  annotations:
    cpln.io/org: your-org-name  # Required: your Control Plane org name
data:
  encoding: cGxhaW4=  # base64 encoded: plain
  payload: c2VjcmV0LXZhbHVl  # base64 encoded: secret-value

Uninstalling

Remove operator credentials

Remove the authentication secret:

cpln operator uninstall --org YOUR_ORG_NAME

Or manually:

kubectl delete secret YOUR_ORG_NAME -n controlplane

Remove the operator

helm uninstall cpln-operator -n controlplane

Remove cert-manager (optional)

If you no longer need cert-manager:

kubectl delete -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.3/cert-manager.yaml

Uninstalling the operator does not delete Control Plane resources that were created by it. Resources in Control Plane will continue to exist.

Troubleshooting

Operator pods not starting

Check cert-manager is running:

kubectl get pods -n cert-manager

Verify webhook certificates:

kubectl get certificates -n controlplane

Resources not syncing

Check operator logs:

kubectl logs -n controlplane -l app=operator -f

Verify the authentication secret exists (look for a secret named after your org):

kubectl get secrets -n controlplane

If the secret for your org doesn’t exist, run the cpln operator install command to create it.

Permission denied errors

Ensure the service account has appropriate permissions in Control Plane. Check which group and/or policy the service account belongs to and verify it has the necessary permissions.To reconfigure authentication, run the cpln operator install command which will create a service account and add it to the superusers group.

CRD validation errors

View the full resource spec available for each CRD:

kubectl explain gvc.spec
kubectl explain workload.spec

Namespace doesn't exist

Create the controlplane namespace:

kubectl create namespace controlplane

Next steps

GVC Reference

Learn about GVC configuration options

Workload Reference

Explore workload deployment options

Identity Reference

Configure cloud access and permissions

Policy Reference

Configure access control rules

How-to Guides

CLI Configuration

Integrations

Configure Resources

Create Resources

Deployment

GitOps

Images

Native Networking

Observability

Workload Access

​What you’ll achieve

​When to use this

GitOps workflows

ArgoCD integration

Kubernetes-native experience

Infrastructure as Code

​Supported resources

​Prerequisites

​Quick start (local cluster)

​Installation

​Step 1: Install cert-manager

​Step 2: Install the operator

​Step 3: Configure authentication

​Generating CRD manifests

​Deploying resources

​Apply with kubectl

​GitOps with ArgoCD

​Preventing resource deletion

​ArgoCD integration

​Defining ArgoCD applications

​Example application

​Connecting to the ArgoCD UI

​Secrets handling

​Uninstalling

​Remove operator credentials

​Remove the operator

​Remove cert-manager (optional)

​Troubleshooting

​Next steps

GVC Reference

Workload Reference

Identity Reference

Policy Reference

What you’ll achieve

When to use this

Supported resources

Prerequisites

Quick start (local cluster)

Installation

Step 1: Install cert-manager

Step 2: Install the operator

Step 3: Configure authentication

Generating CRD manifests

Deploying resources

Apply with kubectl

GitOps with ArgoCD

Preventing resource deletion

ArgoCD integration

Defining ArgoCD applications

Example application

Connecting to the ArgoCD UI

Secrets handling

Uninstalling

Remove operator credentials

Remove the operator

Remove cert-manager (optional)

Troubleshooting

Next steps