Kubernetes Operator

The Control Plane Kubernetes Operator enables you to manage Control Plane resources directly from your Kubernetes cluster using custom resource definitions (CRDs). It provides a bridge between Kubernetes-native workflows and Control Plane infrastructure, making it ideal for GitOps deployments with tools like ArgoCD.

Overview

With the operator installed, you can:

Define resources as YAML - Create GVCs, workloads, secrets, and other resources as Kubernetes manifests
Enable GitOps - Store your infrastructure in Git and deploy automatically with ArgoCD
Maintain consistency - Keep your Kubernetes and Control Plane resources in sync

Supported resources

The operator manages the following Control Plane resource types from Kubernetes. Most resources use Control Plane CRDs; secrets use the native Kubernetes Secret format described below.

Resource	Description
`agent`	Secure connectivity to private networks
`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`	GVC that 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 autoscaling
`workload`	Application containers running on Control Plane

Key concepts

Custom resource structure

Control Plane custom resources differ from standard Kubernetes resources. Fields like org, gvc, and description are at the top level, not inside spec:

apiVersion: cpln.io/v1
kind: workload
metadata:
  name: my-workload
  namespace: default
org: my-org          # Top level, not in spec
gvc: my-gvc          # Top level, not in spec
description: My app  # Top level, not in spec
spec:
  type: serverless
  # ...

Always use the export feature to generate accurate manifests.

Secrets handling

Secrets use native Kubernetes Secret objects with a special label and org annotation:

apiVersion: v1
kind: Secret
metadata:
  name: my-secret
  labels:
    app.kubernetes.io/managed-by: cpln-operator  # Required
  annotations:
    cpln.io/org: my-org  # Required
data:
  payload: <base64-encoded-value>

The app.kubernetes.io/managed-by: cpln-operator label is required for the operator to manage the secret. The cpln.io/org annotation tells the operator which Control Plane org to sync the secret to.

Deletion protection

Deleting a Kubernetes resource while the operator is running removes the corresponding resource from Control Plane. To prevent this, add the cpln.io/resource-policy: keep annotation:

metadata:
  name: production
  annotations:
    cpln.io/resource-policy: keep

Resources with this annotation remain in Control Plane even when deleted from Kubernetes.

Get started

Ready to set up the operator? Follow our step-by-step installation guide:

Install the Kubernetes Operator

Complete guide covering cert-manager installation, Helm deployment, authentication setup, and deploying your first resources

Exporting resources as Kubernetes manifests

You don’t have to write manifests from scratch. Control Plane provides built-in tools to export resources in Kubernetes manifest format.

Console UI
CLI

Export existing resources:Select any resource and click the Export dropdown in the upper right corner, then choose K8s CRD to download the manifest.Preview before creating:When creating a new resource, configure it using the UI, then click Preview and select K8s CRD. This generates the manifest without deploying the resource, which is useful for storing in Git and deploying via ArgoCD.

Use the --output crd flag to export any resource:

# Export a workload as a Kubernetes manifest
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 and save to a file
cpln workload get my-workload --gvc production -o crd --org my-org > workload.yaml

This workflow is ideal for transitioning to GitOps: configure resources in the console UI, export them as Kubernetes manifests, commit them to Git, and let ArgoCD manage deployments.

Deploying resources

Once you have Kubernetes manifests, apply them to your cluster using kubectl:

kubectl apply -f gvc.yaml
kubectl apply -f workload.yaml

The operator watches for resource changes and synchronizes them to Control Plane automatically. You can organize 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)

For production GitOps workflows, store your manifests in Git and use ArgoCD to manage deployments. See the installation guide for ArgoCD integration details.

Documentation

Quickstart

Concepts

Core

Reference

Overview

Supported resources

Key concepts

Get started

Install the Kubernetes Operator

Exporting resources as Kubernetes manifests

Deploying resources

Additional resources

GitHub Repository

cpln apply

​Overview

​Supported resources

​Key concepts

​Get started

Install the Kubernetes Operator

​Exporting resources as Kubernetes manifests

​Deploying resources

​Additional resources

GitHub Repository

cpln apply

Overview

Supported resources

Key concepts

Get started

Exporting resources as Kubernetes manifests

Deploying resources

Additional resources