Version: Next

BuildPlane

A BuildPlane represents the infrastructure layer responsible for executing build workloads in OpenChoreo. It provides the necessary compute resources and configuration for running CI/CD pipelines, typically using Argo Workflows or similar build orchestration systems. Each BuildPlane is associated with a specific Kubernetes cluster where build jobs are executed.

OpenChoreo uses agent-based communication where the control plane communicates with the build cluster through a WebSocket agent running in the BuildPlane cluster. The cluster agent establishes a secure WebSocket connection to the control plane's cluster gateway.

API Version

openchoreo.dev/v1alpha1

Resource Definition

Metadata

BuildPlanes are namespace-scoped resources that must be created within an Organization's namespace.

apiVersion: openchoreo.dev/v1alpha1
kind: BuildPlane
metadata:
  name: <buildplane-name>
  namespace: <org-namespace>  # Organization namespace

Spec Fields

Field	Type	Required	Default	Description
`planeID`	string	No	default-buildplane	Identifies the logical plane this CR connects to. Must match `clusterAgent.planeId` Helm value.
`clusterAgent`	ClusterAgentConfig	Yes	-	Configuration for cluster agent-based communication
`secretStoreRef`	SecretStoreRef	No	-	Reference to External Secrets Operator ClusterSecretStore in the BuildPlane
`observabilityPlaneRef`	string	No	-	Name of the ObservabilityPlane resource for monitoring and logging

PlaneID

The planeID identifies the logical plane this BuildPlane CR connects to. Multiple BuildPlane CRs can share the same planeID to connect to the same physical cluster while maintaining separate configurations for multi-tenancy scenarios.

Validation Rules:

Maximum length: 63 characters
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$ (lowercase alphanumeric, hyphens allowed)
Examples: "shared-builder", "ci-cluster", "us-west-2"

PlaneID Consistency

The planeID in the BuildPlane CR must match the clusterAgent.planeId Helm value configured during build plane installation. If not specified, it defaults to the CR name for backwards compatibility.

ClusterAgentConfig

Configuration for cluster agent-based communication with the build cluster. The cluster agent establishes a WebSocket connection to the control plane's cluster gateway.

Field	Type	Required	Default	Description
`clientCA`	ValueFrom	Yes	-	CA certificate to verify the agent's client certificate (base64-encoded PEM)

SecretStoreRef

Reference to an External Secrets Operator ClusterSecretStore.

Field	Type	Required	Default	Description
`name`	string	Yes	-	Name of the ClusterSecretStore in the BuildPlane

ValueFrom

Common pattern for referencing secrets or providing inline values. Either secretRef or value should be specified.

Field	Type	Required	Default	Description
`secretRef`	SecretKeyReference	No	-	Reference to a secret key
`value`	string	No	-	Inline value (not recommended for sensitive data)

SecretKeyReference

Reference to a specific key in a Kubernetes secret.

Field	Type	Required	Default	Description
`name`	string	Yes	-	Name of the secret
`namespace`	string	No	Same as parent resource	Namespace of the secret
`key`	string	Yes	-	Key within the secret

Status Fields

The BuildPlane status is currently minimal, with fields reserved for future use.

Field	Type	Default	Description
-	-	-	Status fields are reserved for future use

Getting the Agent CA Certificate

The cluster agent automatically generates its CA certificate when deployed to the build plane cluster. This certificate is used by the control plane to verify the identity of the build plane agent during mTLS authentication.

Extracting the CA Certificate

You can extract the CA certificate using:

# For multi-cluster setups, specify the build plane cluster context
kubectl --context <buildplane-context> get secret cluster-agent-tls \
  -n openchoreo-build-plane \
  -o jsonpath='{.data.ca\.crt}' | base64 -d

# Example for k3d multi-cluster setup:
kubectl --context k3d-openchoreo-bp get secret cluster-agent-tls \
  -n openchoreo-build-plane \
  -o jsonpath='{.data.ca\.crt}' | base64 -d

important

In multi-cluster setups, you must specify the --context flag to target the build plane cluster, not the control plane cluster. The cluster-agent-tls secret exists in the build plane cluster where the agent is deployed.

Adding the Certificate to the BuildPlane CR

You can add the CA certificate to the BuildPlane CR in two ways:

Option 1: Inline value (for testing/development)

# Extract the CA certificate from the build plane cluster
BP_CA_CERT=$(kubectl --context <buildplane-context> get secret cluster-agent-tls \
  -n openchoreo-build-plane \
  -o jsonpath='{.data.ca\.crt}' | base64 -d)

# Create BuildPlane in the control plane with inline CA certificate
kubectl --context <control-plane-context> apply -f - <<EOF
apiVersion: openchoreo.dev/v1alpha1
kind: BuildPlane
metadata:
  name: my-buildplane
  namespace: my-org
spec:
  planeID: "default-buildplane"
  clusterAgent:
    clientCA:
      value: |
$(echo "$BP_CA_CERT" | sed 's/^/        /')
EOF

Option 2: Secret reference (recommended for production)

# Extract the CA certificate from the build plane cluster and save to file
kubectl --context <buildplane-context> get secret cluster-agent-tls \
  -n openchoreo-build-plane \
  -o jsonpath='{.data.ca\.crt}' | base64 -d > /tmp/buildplane-ca.crt

# Create a secret in the control plane cluster
kubectl --context <control-plane-context> create secret generic buildplane-agent-ca \
  --from-file=ca.crt=/tmp/buildplane-ca.crt \
  -n my-org

# Create BuildPlane in the control plane referencing the secret
kubectl --context <control-plane-context> apply -f - <<EOF
apiVersion: openchoreo.dev/v1alpha1
kind: BuildPlane
metadata:
  name: my-buildplane
  namespace: my-org
spec:
  planeID: "default-buildplane"
  clusterAgent:
    clientCA:
      secretRef:
        name: buildplane-agent-ca
        namespace: my-org
        key: ca.crt
EOF

Examples

Basic BuildPlane Configuration

This example shows a minimal BuildPlane configuration.

apiVersion: openchoreo.dev/v1alpha1
kind: BuildPlane
metadata:
  name: production-buildplane
  namespace: my-org
spec:
  planeID: "prod-builder"
  clusterAgent:
    clientCA:
      secretRef:
        name: buildplane-agent-ca
        key: ca.crt

BuildPlane with Secret Store

This example demonstrates using External Secrets Operator for managing secrets.

apiVersion: openchoreo.dev/v1alpha1
kind: BuildPlane
metadata:
  name: secure-buildplane
  namespace: my-org
spec:
  planeID: "secure-builder"
  clusterAgent:
    clientCA:
      secretRef:
        name: agent-ca-cert
        namespace: openchoreo-system
        key: ca.crt
  secretStoreRef:
    name: vault-backend

BuildPlane with Observability

This example shows a BuildPlane linked to an ObservabilityPlane for monitoring build jobs.

apiVersion: openchoreo.dev/v1alpha1
kind: BuildPlane
metadata:
  name: monitored-buildplane
  namespace: my-org
spec:
  planeID: "prod-ci"
  clusterAgent:
    clientCA:
      value: |
        -----BEGIN CERTIFICATE-----
        MIIDXTCCAkWgAwIBAgIJAKL0UG+mRKuoMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
        ... (certificate content) ...
        -----END CERTIFICATE-----
  secretStoreRef:
    name: default
  observabilityPlaneRef: production-observability

Multi-tenant BuildPlane Configuration

This example shows multiple BuildPlane CRs sharing the same planeID for multi-tenancy.

# Organization 1's BuildPlane
apiVersion: openchoreo.dev/v1alpha1
kind: BuildPlane
metadata:
  name: org1-buildplane
  namespace: org1
spec:
  planeID: "shared-builder"  # Same physical cluster
  clusterAgent:
    clientCA:
      secretRef:
        name: shared-cluster-ca
        key: ca.crt
  secretStoreRef:
    name: org1-secrets

---
# Organization 2's BuildPlane
apiVersion: openchoreo.dev/v1alpha1
kind: BuildPlane
metadata:
  name: org2-buildplane
  namespace: org2
spec:
  planeID: "shared-builder"  # Same physical cluster
  clusterAgent:
    clientCA:
      secretRef:
        name: shared-cluster-ca
        key: ca.crt
  secretStoreRef:
    name: org2-secrets

Annotations

BuildPlanes support the following annotations:

Annotation	Description
`openchoreo.dev/display-name`	Human-readable name for UI display
`openchoreo.dev/description`	Detailed description of the BuildPlane

DataPlane - Runtime infrastructure for deployed applications
Component - Application components that trigger builds
Organization - Organizational context for BuildPlanes
WorkflowRun - Build job executions on BuildPlanes

API Version​

Resource Definition​

Metadata​

Spec Fields​

PlaneID​

ClusterAgentConfig​

SecretStoreRef​

ValueFrom​

SecretKeyReference​

Status Fields​

Getting the Agent CA Certificate​

Extracting the CA Certificate​

Adding the Certificate to the BuildPlane CR​

Examples​

Basic BuildPlane Configuration​

BuildPlane with Secret Store​

BuildPlane with Observability​

Multi-tenant BuildPlane Configuration​

Annotations​

Related Resources​