> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes Operator

> Manage Control Plane resources as Kubernetes CRDs for GitOps workflows with ArgoCD. Supports GVCs, workloads, identities, secrets, policies, domains, and cloud accounts.

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 CRD 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 through CRDs:

| 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`            | 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                          |

## Key concepts

<AccordionGroup>
  <Accordion title="CRD structure">
    Control Plane CRDs differ from standard Kubernetes resources. Fields like `org`, `gvc`, and `description` are at the **top level**, not inside `spec`:

    ```yaml theme={null}
    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](#exporting-resources-as-crds) to generate accurate manifests.
  </Accordion>

  <Accordion title="Secrets handling">
    Secrets use native Kubernetes Secret objects with a special label:

    ```yaml theme={null}
    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.
  </Accordion>

  <Accordion title="Deletion protection">
    Deleting a CRD removes the corresponding resource from Control Plane. To prevent this, add the `cpln.io/resource-policy: keep` annotation:

    ```yaml theme={null}
    metadata:
      name: production
      annotations:
        cpln.io/resource-policy: keep
    ```

    Resources with this annotation remain in Control Plane even when deleted from Kubernetes.
  </Accordion>
</AccordionGroup>

## Get started

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

<Card title="Install the Kubernetes Operator" href="/guides/cli/cpln-operator" icon="rocket">
  Complete guide covering cert-manager installation, Helm deployment, authentication setup, and deploying your first resources
</Card>

## Exporting resources as CRDs

You don't have to write CRD manifests from scratch. Control Plane provides built-in tools to export any resource in Kubernetes CRD format.

<Tabs>
  <Tab title="Console UI">
    **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—perfect for storing in Git and deploying via ArgoCD.
  </Tab>

  <Tab title="CLI">
    Use the `--output crd` flag to export any resource:

    ```bash theme={null}
    # Export a workload as a CRD 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
    ```
  </Tab>
</Tabs>

<Tip>
  This workflow is ideal for transitioning to GitOps: configure resources in the console UI, export them as CRDs, commit to Git, and let ArgoCD manage deployments.
</Tip>

## Deploying resources

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

```bash theme={null}
kubectl apply -f gvc.yaml
kubectl apply -f workload.yaml
```

The operator watches for CRD changes and syncs 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](/guides/cli/cpln-operator#argocd-integration) for ArgoCD integration details.

## Additional resources

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/controlplane-com/k8s-operator">
    Source code, CRD schemas, and issue tracking
  </Card>

  <Card title="cpln apply" icon="terminal" href="/guides/cpln-apply">
    Alternative: Deploy resources from YAML using the CLI
  </Card>
</CardGroup>