Version: v0.15.x

Run OpenChoreo on Your Environment

This guide walks you through setting up OpenChoreo on any Kubernetes cluster (k3s, GKE, EKS, DOKS, AKS, or self-managed). You will install each plane one at a time, and after each one you will do something real with it: log in, deploy a service, or trigger a build.

It uses a single-cluster topology (all planes in one cluster). For split-cluster setups, follow Multi-Cluster Connectivity.

All gateways are configured with HTTPS using self-signed certificates by default. You can replace them with certificates from a real CA later.

OpenChoreo has four planes:

Control Plane runs the API, console, identity provider, and controllers.
Data Plane runs your workloads and routes traffic to them.
Build Plane builds container images from source using Argo Workflows.
Observability Plane collects logs and metrics from all other planes.

What you will get:

OpenChoreo running on your Kubernetes cluster with HTTPS
A reachable console URL over your cluster LoadBalancer
A deployed web app you can open in your browser
Optional source-to-image build pipeline and log collection

Prerequisites

Tool	Version	Purpose
kubectl	v1.32+	Kubernetes CLI
Helm	v3.12+	Package manager

Recommended cluster baseline: Kubernetes 1.32+, LoadBalancer support, and a default StorageClass.

Verify everything is installed:

kubectl version --client
helm version --short
kubectl get nodes
kubectl auth can-i '*' '*' --all-namespaces

Step 1: Install Prerequisites

These are third-party components that OpenChoreo depends on. None of them are OpenChoreo-specific, they are standard Kubernetes building blocks.

Gateway API CRDs

The Gateway API is the Kubernetes-native way to manage ingress and routing. OpenChoreo uses it to route traffic to workloads in every plane.

kubectl apply --server-side \
  -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.1/experimental-install.yaml

cert-manager

cert-manager automates TLS certificate management. OpenChoreo uses it to issue certificates for internal communication between planes and for gateway TLS.

helm upgrade --install cert-manager oci://quay.io/jetstack/charts/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.19.2 \
  --set crds.enabled=true \
  --wait --timeout 180s

External Secrets Operator

External Secrets Operator syncs secrets from external providers (like Vault, AWS Secrets Manager, or Azure Key Vault) into Kubernetes. For this guide, you will point it at a fake provider. For production backends, see Secret Management.

helm upgrade --install external-secrets oci://ghcr.io/external-secrets/charts/external-secrets \
  --namespace external-secrets \
  --create-namespace \
  --version 1.3.2 \
  --set installCRDs=true \
  --wait --timeout 180s

kgateway

kgateway is the Gateway API implementation that actually handles traffic. It watches for Gateway and HTTPRoute resources across all namespaces, so installing it once is enough. Every plane creates its own Gateway resource in its own namespace, and this single kgateway controller manages all of them.

helm upgrade --install kgateway-crds oci://cr.kgateway.dev/kgateway-dev/charts/kgateway-crds \
  --version v2.1.1

helm upgrade --install kgateway oci://cr.kgateway.dev/kgateway-dev/charts/kgateway \
  --namespace openchoreo-control-plane \
  --create-namespace \
  --version v2.1.1

Step 2: Setup Secrets

OpenChoreo uses External Secrets Operator to manage secrets. All secrets are stored in a ClusterSecretStore and synced into the right namespaces using ExternalSecret resources. In production you would point this at a real provider like Vault, AWS Secrets Manager, or Azure Key Vault. For this guide, a fake provider with static values is enough.

ClusterSecretStore

kubectl apply -f - <<EOF
apiVersion: external-secrets.io/v1
kind: ClusterSecretStore
metadata:
  name: default
spec:
  provider:
    fake:
      data:
      # Sample apps
      - key: npm-token
        value: "fake-npm-token-for-development"
      - key: docker-username
        value: "dev-user"
      - key: docker-password
        value: "dev-password"
      - key: github-pat
        value: "fake-github-token-for-development"
      - key: username
        value: "dev-user"
      - key: password
        value: "dev-password"
      # Backstage (web console)
      - key: backstage-backend-secret
        value: "local-dev-backend-secret"
      - key: backstage-client-secret
        value: "backstage-portal-secret"
      - key: backstage-jenkins-api-key
        value: "placeholder-not-in-use"
      # OpenSearch (observability)
      - key: opensearch-username
        value: "admin"
      - key: opensearch-password
        value: "ThisIsTheOpenSearchPassword1"
      # RCA agent
      - key: RCA_LLM_API_KEY
        value: "fake-llm-api-key-for-development"
EOF

For production secret backends, see Secret Management.

Step 3: Setup TLS

Create a self-signed CA that all planes will use for TLS. A bootstrap ClusterIssuer generates a CA certificate, then a second ClusterIssuer uses that CA to issue certificates cluster-wide.

kubectl apply -f - <<'EOF'
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: selfsigned-bootstrap
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: openchoreo-ca
  namespace: cert-manager
spec:
  isCA: true
  commonName: openchoreo-ca
  secretName: openchoreo-ca-secret
  privateKey:
    algorithm: ECDSA
    size: 256
  issuerRef:
    name: selfsigned-bootstrap
    kind: ClusterIssuer
---
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: openchoreo-ca
spec:
  ca:
    secretName: openchoreo-ca-secret
EOF

Wait for the CA to be ready:

kubectl wait --for=condition=Ready certificate/openchoreo-ca \
  -n cert-manager --timeout=60s

Production TLS

Replace the openchoreo-ca ClusterIssuer with a real CA (e.g. Let's Encrypt via an ACME ClusterIssuer) for trusted certificates. All Certificate resources in this guide reference openchoreo-ca, so swapping the issuer is a single change.

tip

All curl commands in this guide use -k to skip certificate verification since we are using self-signed certs. Browsers will also show a certificate warning that you need to accept.

Step 4: Setup Control Plane

The control plane is the brain of OpenChoreo. It runs the API server, the web console, the identity provider, and the controllers that reconcile your resources.

First, install a minimal control plane to get a LoadBalancer address. The chart requires valid hostnames upfront, so temporary values are used here and replaced with real ones after discovering the external IP.

helm upgrade --install openchoreo-control-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-control-plane \
--version 0.15.0 \
--namespace openchoreo-control-plane \
--create-namespace \
--values - <<'EOF'
openchoreoApi:
  http:
      hostnames:
          - "api.placeholder.tld"
backstage:
  baseUrl: "https://console.placeholder.tld"
  secretName: backstage-secrets
  http:
      hostnames:
          - "console.placeholder.tld"
security:
  oidc:
      issuer: "https://thunder.placeholder.tld"
thunder:
  host: "thunder.placeholder.tld"
gateway:
  tls:
      enabled: false
EOF

Some pods will crash-loop at this point because Thunder and Backstage secrets are not configured yet. That is expected. The only thing needed from this step is the Gateway's LoadBalancer address.

EKS only: make the LoadBalancer internet-facing

kubectl patch svc gateway-default -n openchoreo-control-plane \
  -p '{"metadata":{"annotations":{"service.beta.kubernetes.io/aws-load-balancer-scheme":"internet-facing"}}}'

Gateway Patch (Optional)

On some platforms (especially macOS), the envoy proxy inside the gateway crashes because /tmp is not writable. This patch adds a writable volume. If you don't hit this issue you can skip it, but it's harmless either way. See kgateway#9800.

kubectl patch deployment gateway-default -n openchoreo-control-plane \
--type='json' -p='[{"op":"add","path":"/spec/template/spec/volumes/-","value":{"name":"tmp","emptyDir":{}}},{"op":"add","path":"/spec/template/spec/containers/0/volumeMounts/-","value":{"name":"tmp","mountPath":"/tmp"}}]'

Wait for the service to get an external address, then resolve it:

kubectl get svc gateway-default -n openchoreo-control-plane -w

CP_LB_IP=$(kubectl get svc gateway-default -n openchoreo-control-plane -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
if [ -z "$CP_LB_IP" ]; then
  CP_LB_HOSTNAME=$(kubectl get svc gateway-default -n openchoreo-control-plane -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
  CP_LB_IP=$(dig +short "$CP_LB_HOSTNAME" | head -1)
fi

export CP_BASE_DOMAIN="openchoreo.${CP_LB_IP//./-}.nip.io"
echo "Control plane base domain: ${CP_BASE_DOMAIN}"
echo "  Console: console.${CP_BASE_DOMAIN}"
echo "  API:     api.${CP_BASE_DOMAIN}"
echo "  Thunder: thunder.${CP_BASE_DOMAIN}"

If your cluster returns only a hostname and dig is not available, use nslookup to resolve the IP, or use your own DNS domain instead of nip.io.

Create the Control Plane TLS Certificate

Issue a wildcard certificate covering all control plane subdomains:

kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: cp-gateway-tls
  namespace: openchoreo-control-plane
spec:
  secretName: cp-gateway-tls
  issuerRef:
    name: openchoreo-ca
    kind: ClusterIssuer
  dnsNames:
    - "*.${CP_BASE_DOMAIN}"
    - "${CP_BASE_DOMAIN}"
  privateKey:
    rotationPolicy: Always
EOF

kubectl wait --for=condition=Ready certificate/cp-gateway-tls \
  -n openchoreo-control-plane --timeout=60s

Install Thunder (Identity Provider)

Thunder handles authentication and OAuth flows. The setup job is a pre-install helm hook that bootstraps users, groups, and OAuth applications on the very first helm install. To change these later, uninstall Thunder, delete the PVC, and reinstall.

curl -fsSL https://raw.githubusercontent.com/openchoreo/openchoreo/release-v0.15/install/k3d/common/values-thunder.yaml \
| sed "s#http://thunder.openchoreo.localhost:8080#https://thunder.${CP_BASE_DOMAIN}#g" \
| sed "s#thunder.openchoreo.localhost#thunder.${CP_BASE_DOMAIN}#g" \
| sed "s#http://openchoreo.localhost:8080#https://console.${CP_BASE_DOMAIN}#g" \
| sed "s#port: 8080#port: 443#g" \
| sed 's#scheme: "http"#scheme: "https"#g' \
| helm upgrade --install thunder oci://ghcr.io/asgardeo/helm-charts/thunder \
    --namespace openchoreo-control-plane \
    --create-namespace \
    --version 0.21.0 \
    --values -

Wait for Thunder to finish bootstrapping:

kubectl wait --for=condition=available deployment/thunder-deployment \
  -n openchoreo-control-plane --timeout=180s

You can browse and modify the Thunder configuration at:

echo "https://thunder.${CP_BASE_DOMAIN}/develop"

Username	Password
`admin`	`admin`

Backstage Secrets

The web console (Backstage) needs a backend secret for session signing and an OAuth client secret to authenticate with Thunder:

kubectl apply -f - <<EOF
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: backstage-secrets
  namespace: openchoreo-control-plane
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: ClusterSecretStore
    name: default
  target:
    name: backstage-secrets
  data:
  - secretKey: backend-secret
    remoteRef:
      key: backstage-backend-secret
  - secretKey: client-secret
    remoteRef:
      key: backstage-client-secret
  - secretKey: jenkins-api-key
    remoteRef:
      key: backstage-jenkins-api-key
EOF

Configure the Control Plane

Upgrade with real hostnames, TLS enabled, and JWKS skip-verify for self-signed certs. Backstage also needs NODE_TLS_REJECT_UNAUTHORIZED=0 so its Node.js runtime can reach Thunder's token endpoint through the self-signed gateway.

helm upgrade openchoreo-control-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-control-plane \
--version 0.15.0 \
--namespace openchoreo-control-plane \
--reuse-values \
--values - <<EOF
openchoreoApi:
  config:
      server:
          publicUrl: "https://api.${CP_BASE_DOMAIN}"
      security:
          authentication:
              jwt:
                  jwks:
                      skip_tls_verify: true
  http:
      hostnames:
          - "api.${CP_BASE_DOMAIN}"
backstage:
  secretName: backstage-secrets
  baseUrl: "https://console.${CP_BASE_DOMAIN}"
  http:
      hostnames:
          - "console.${CP_BASE_DOMAIN}"
  auth:
      redirectUrls:
          - "https://console.${CP_BASE_DOMAIN}/api/auth/openchoreo-auth/handler/frame"
  extraEnv:
      - name: NODE_TLS_REJECT_UNAUTHORIZED
        value: "0"
security:
  oidc:
      issuer: "https://thunder.${CP_BASE_DOMAIN}"
      jwksUrl: "https://thunder.${CP_BASE_DOMAIN}/oauth2/jwks"
      authorizationUrl: "https://thunder.${CP_BASE_DOMAIN}/oauth2/authorize"
      tokenUrl: "https://thunder.${CP_BASE_DOMAIN}/oauth2/token"
thunder:
  host: "thunder.${CP_BASE_DOMAIN}"
gateway:
  tls:
      enabled: true
      hostname: "*.${CP_BASE_DOMAIN}"
      certificateRefs:
          - name: cp-gateway-tls
EOF

Wait for all deployments to come up:

kubectl wait -n openchoreo-control-plane \
  --for=condition=available --timeout=300s deployment --all

Verify HTTPS is working:

curl -sk https://thunder.${CP_BASE_DOMAIN}/health/readiness
curl -sk https://api.${CP_BASE_DOMAIN}/health
curl -sk -o /dev/null -w "%{http_code}" https://console.${CP_BASE_DOMAIN}/

Step 5: Install Default Resources

OpenChoreo needs some base resources before you can deploy anything: a project, environments, component types, and a deployment pipeline.

kubectl apply -f https://raw.githubusercontent.com/openchoreo/openchoreo/release-v0.15/samples/getting-started/all.yaml

Label the default namespace as a control plane namespace:

kubectl label namespace default openchoreo.dev/controlplane-namespace=true

Step 6: Setup Data Plane

The data plane is where your workloads actually run. It has its own gateway for routing traffic, and a cluster-agent that connects back to the control plane to receive deployment instructions.

Namespace and Certificates

Each plane needs a copy of the cluster-gateway CA certificate so its agent can establish a trusted connection to the control plane. This is how planes authenticate with each other.

kubectl create namespace openchoreo-data-plane --dry-run=client -o yaml | kubectl apply -f -

CA_CRT=$(kubectl get secret cluster-gateway-ca \
  -n openchoreo-control-plane -o jsonpath='{.data.ca\.crt}' | base64 -d)

kubectl create configmap cluster-gateway-ca \
  --from-literal=ca.crt="$CA_CRT" \
  -n openchoreo-data-plane --dry-run=client -o yaml | kubectl apply -f -

TLS_CRT=$(kubectl get secret cluster-gateway-ca \
  -n openchoreo-control-plane -o jsonpath='{.data.tls\.crt}' | base64 -d)
TLS_KEY=$(kubectl get secret cluster-gateway-ca \
  -n openchoreo-control-plane -o jsonpath='{.data.tls\.key}' | base64 -d)

kubectl create secret generic cluster-gateway-ca \
  --from-literal=tls.crt="$TLS_CRT" \
  --from-literal=tls.key="$TLS_KEY" \
  --from-literal=ca.crt="$CA_CRT" \
  -n openchoreo-data-plane --dry-run=client -o yaml | kubectl apply -f -

Install the Data Plane

helm upgrade --install openchoreo-data-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-data-plane \
--version 0.15.0 \
--namespace openchoreo-data-plane \
--create-namespace \
--set gateway.tls.enabled=false \
--set clusterAgent.tls.generateCerts=true

Single-node clusters (k3s, Rancher Desktop, minikube)

On single-node clusters all LoadBalancer services share the same IP. Add --set gateway.httpPort=8080 --set gateway.httpsPort=8443 to avoid port conflicts with the control plane gateway. Update publicHTTPPort / publicHTTPSPort in the DataPlane registration below to match.

EKS only: make the LoadBalancer internet-facing

kubectl patch svc gateway-default -n openchoreo-data-plane \
  -p '{"metadata":{"annotations":{"service.beta.kubernetes.io/aws-load-balancer-scheme":"internet-facing"}}}'

Gateway Patch (Optional)

Same envoy /tmp workaround as the control plane.

kubectl patch deployment gateway-default -n openchoreo-data-plane \
--type='json' -p='[{"op":"add","path":"/spec/template/spec/volumes/-","value":{"name":"tmp","emptyDir":{}}},{"op":"add","path":"/spec/template/spec/containers/0/volumeMounts/-","value":{"name":"tmp","mountPath":"/tmp"}}]'

Get the data plane IP and derive a domain:

kubectl get svc gateway-default -n openchoreo-data-plane -w

DP_LB_IP=$(kubectl get svc gateway-default -n openchoreo-data-plane -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
if [ -z "$DP_LB_IP" ]; then
  DP_LB_HOSTNAME=$(kubectl get svc gateway-default -n openchoreo-data-plane -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
  DP_LB_IP=$(dig +short "$DP_LB_HOSTNAME" | head -1)
fi

export DP_DOMAIN="apps.openchoreo.${DP_LB_IP//./-}.nip.io"
echo "Data plane domain: *.${DP_DOMAIN}"

Create the Data Plane TLS Certificate

kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: dp-gateway-tls
  namespace: openchoreo-data-plane
spec:
  secretName: dp-gateway-tls
  issuerRef:
    name: openchoreo-ca
    kind: ClusterIssuer
  dnsNames:
    - "*.${DP_DOMAIN}"
    - "${DP_DOMAIN}"
  privateKey:
    rotationPolicy: Always
EOF

kubectl wait --for=condition=Ready certificate/dp-gateway-tls \
  -n openchoreo-data-plane --timeout=60s

Enable TLS on the Data Plane

helm upgrade openchoreo-data-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-data-plane \
--version 0.15.0 \
--namespace openchoreo-data-plane \
--reuse-values \
--values - <<EOF
gateway:
  tls:
      enabled: true
      hostname: "*.${DP_DOMAIN}"
      certificateRefs:
          - name: dp-gateway-tls
EOF

Register the Data Plane

The DataPlane resource tells the control plane about this data plane. It includes the agent's CA certificate (so the control plane trusts its WebSocket connection) and the gateway's public address (so the control plane knows how to route traffic to workloads).

AGENT_CA=$(kubectl get secret cluster-gateway-ca \
  -n openchoreo-data-plane -o jsonpath='{.data.ca\.crt}' | base64 -d)

kubectl apply -f - <<EOF
apiVersion: openchoreo.dev/v1alpha1
kind: DataPlane
metadata:
  name: default
  namespace: default
spec:
  planeID: default
  clusterAgent:
    clientCA:
      value: |
$(echo "$AGENT_CA" | sed 's/^/        /')
  secretStoreRef:
    name: default
  gateway:
    publicVirtualHost: ${DP_DOMAIN}
    organizationVirtualHost: ${DP_DOMAIN}
    publicHTTPPort: 80
    publicHTTPSPort: 443
    organizationHTTPPort: 80
    organizationHTTPSPort: 443
EOF

Try it: Log In and Deploy

Open the OpenChoreo console in your browser:

echo "https://console.${CP_BASE_DOMAIN}"

Username	Password
`admin@openchoreo.dev`	`Admin@123`

You should see the OpenChoreo console. Deploy a sample web app:

kubectl apply -f https://raw.githubusercontent.com/openchoreo/openchoreo/release-v0.15/samples/from-image/react-starter-web-app/react-starter.yaml

kubectl wait --for=condition=available deployment \
  -l openchoreo.dev/component=react-starter -A --timeout=180s

HOSTNAME=$(kubectl get httproute -A -l openchoreo.dev/component=react-starter \
  -o jsonpath='{.items[0].spec.hostnames[0]}')
DP_HTTPS_PORT=$(kubectl get gateway gateway-default -n openchoreo-data-plane \
  -o jsonpath='{.spec.listeners[?(@.protocol=="HTTPS")].port}')
PORT_SUFFIX=$([ "$DP_HTTPS_PORT" = "443" ] && echo "" || echo ":${DP_HTTPS_PORT}")

echo "https://${HOSTNAME}${PORT_SUFFIX}"

Open that URL in your browser (accept the self-signed certificate warning). You should see the React starter application running.

Step 7: Setup Build Plane (Optional)

The build plane takes source code, builds a container image, pushes it to a registry, and tells the control plane about the new image. It uses Argo Workflows to run build pipelines.

Namespace and Certificates

Same process as the data plane. Copy the cluster-gateway CA so the build plane's agent can connect to the control plane:

kubectl create namespace openchoreo-build-plane --dry-run=client -o yaml | kubectl apply -f -

CA_CRT=$(kubectl get secret cluster-gateway-ca \
  -n openchoreo-control-plane -o jsonpath='{.data.ca\.crt}' | base64 -d)

kubectl create configmap cluster-gateway-ca \
  --from-literal=ca.crt="$CA_CRT" \
  -n openchoreo-build-plane --dry-run=client -o yaml | kubectl apply -f -

TLS_CRT=$(kubectl get secret cluster-gateway-ca \
  -n openchoreo-control-plane -o jsonpath='{.data.tls\.crt}' | base64 -d)
TLS_KEY=$(kubectl get secret cluster-gateway-ca \
  -n openchoreo-control-plane -o jsonpath='{.data.tls\.key}' | base64 -d)

kubectl create secret generic cluster-gateway-ca \
  --from-literal=tls.crt="$TLS_CRT" \
  --from-literal=tls.key="$TLS_KEY" \
  --from-literal=ca.crt="$CA_CRT" \
  -n openchoreo-build-plane --dry-run=client -o yaml | kubectl apply -f -

Install the Build Plane

Builds need somewhere to push images. This guide uses ttl.sh, an anonymous ephemeral registry where images expire automatically. No authentication needed.

helm upgrade --install openchoreo-build-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-build-plane \
--version 0.15.0 \
--namespace openchoreo-build-plane \
--create-namespace \
--set clusterAgent.tls.generateCerts=true \
--set openbao.server.dev.enabled=true \
--set defaultResources.enabled=true \
--set defaultResources.registry.host=ttl.sh \
--set defaultResources.registry.repoPath=openchoreo-builds \
--set defaultResources.registry.tlsVerify=true \
--set defaultResources.buildpackCache.enabled=false

To use your own container registry (ACR, ECR, GAR, GHCR, Docker Hub), follow Container Registry Configuration.

Register the Build Plane

The build plane helm chart includes OpenBao (a Vault fork) and creates a ClusterSecretStore named openbao for managing build secrets. The registration below references that store.

AGENT_CA=$(kubectl get secret cluster-gateway-ca \
  -n openchoreo-build-plane -o jsonpath='{.data.ca\.crt}' | base64 -d)

kubectl apply -f - <<EOF
apiVersion: openchoreo.dev/v1alpha1
kind: BuildPlane
metadata:
  name: default
  namespace: default
spec:
  planeID: default
  clusterAgent:
    clientCA:
      value: |
$(echo "$AGENT_CA" | sed 's/^/        /')
  secretStoreRef:
    name: openbao
EOF

Try it: Build from Source

Apply a sample component that builds a Go service from source:

kubectl apply -f https://raw.githubusercontent.com/openchoreo/openchoreo/release-v0.15/samples/from-source/services/go-docker-greeter/greeting-service.yaml

Watch the build progress:

kubectl get workflow -n openchoreo-ci-default --watch

After the build completes, wait for the deployment:

kubectl wait --for=condition=available deployment \
  -l openchoreo.dev/component=greeting-service -A --timeout=300s

Resolve the hostname and call the service:

HOSTNAME=$(kubectl get httproute -A -l openchoreo.dev/component=greeting-service \
  -o jsonpath='{.items[0].spec.hostnames[0]}')
PATH_PREFIX=$(kubectl get httproute -A -l openchoreo.dev/component=greeting-service \
  -o jsonpath='{.items[0].spec.rules[0].matches[0].path.value}')
DP_HTTPS_PORT=$(kubectl get gateway gateway-default -n openchoreo-data-plane \
  -o jsonpath='{.spec.listeners[?(@.protocol=="HTTPS")].port}')
PORT_SUFFIX=$([ "$DP_HTTPS_PORT" = "443" ] && echo "" || echo ":${DP_HTTPS_PORT}")

curl -k "https://${HOSTNAME}${PORT_SUFFIX}${PATH_PREFIX}/greeter/greet"

OpenChoreo built your code, pushed the image to ttl.sh, and deployed it to the data plane.

k3s / Rancher Desktop

On k3s with the Docker runtime, the generate-workload-cr build step may fail with crun: the requested cgroup controller 'pids' is not available. This happens because the step runs podman inside the workflow pod and Docker does not delegate all cgroup v2 controllers. The image build and push still succeed. You can work around this by manually creating the Workload CR using the workload descriptor from the source repo and referencing the built image. Switching Rancher Desktop to the containerd runtime avoids this issue.

Step 8: Setup Observability Plane (Optional)

The observability plane collects logs and metrics from all other planes. It runs OpenSearch for storage, Fluent Bit for log collection, and an Observer API for querying.

Namespace and Certificates

kubectl create namespace openchoreo-observability-plane --dry-run=client -o yaml | kubectl apply -f -

CA_CRT=$(kubectl get secret cluster-gateway-ca \
  -n openchoreo-control-plane -o jsonpath='{.data.ca\.crt}' | base64 -d)

kubectl create configmap cluster-gateway-ca \
  --from-literal=ca.crt="$CA_CRT" \
  -n openchoreo-observability-plane --dry-run=client -o yaml | kubectl apply -f -

TLS_CRT=$(kubectl get secret cluster-gateway-ca \
  -n openchoreo-control-plane -o jsonpath='{.data.tls\.crt}' | base64 -d)
TLS_KEY=$(kubectl get secret cluster-gateway-ca \
  -n openchoreo-control-plane -o jsonpath='{.data.tls\.key}' | base64 -d)

kubectl create secret generic cluster-gateway-ca \
  --from-literal=tls.crt="$TLS_CRT" \
  --from-literal=tls.key="$TLS_KEY" \
  --from-literal=ca.crt="$CA_CRT" \
  -n openchoreo-observability-plane --dry-run=client -o yaml | kubectl apply -f -

OpenSearch Credentials

The Observer API needs credentials to connect to OpenSearch:

kubectl apply -f - <<EOF
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: observer-opensearch-credentials
  namespace: openchoreo-observability-plane
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: ClusterSecretStore
    name: default
  target:
    name: observer-opensearch-credentials
  data:
  - secretKey: username
    remoteRef:
      key: opensearch-username
  - secretKey: password
    remoteRef:
      key: opensearch-password
EOF

Install the Observability Plane

helm upgrade --install openchoreo-observability-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-observability-plane \
--version 0.15.0 \
--namespace openchoreo-observability-plane \
--create-namespace \
--set openSearch.enabled=true \
--set openSearchCluster.enabled=false \
--set gateway.tls.enabled=false \
--set clusterAgent.tls.generateCerts=true \
--set observer.openSearchSecretName=observer-opensearch-credentials \
--set security.oidc.jwksUrl="https://thunder.${CP_BASE_DOMAIN}/oauth2/jwks" \
--set security.oidc.tokenUrl="https://thunder.${CP_BASE_DOMAIN}/oauth2/token" \
--set-string security.oidc.jwksUrlTlsInsecureSkipVerify=true \
--timeout 25m

Single-node clusters (k3s, Rancher Desktop, minikube)

On single-node clusters all LoadBalancer services share the same IP. Add --set gateway.httpPort=9080 --set gateway.httpsPort=9443 to avoid port conflicts with the control plane and data plane gateways.

Gateway Patch (Optional)

Same envoy /tmp workaround as the other planes.

kubectl patch deployment gateway-default -n openchoreo-observability-plane \
--type='json' -p='[{"op":"add","path":"/spec/template/spec/volumes/-","value":{"name":"tmp","emptyDir":{}}},{"op":"add","path":"/spec/template/spec/containers/0/volumeMounts/-","value":{"name":"tmp","mountPath":"/tmp"}}]'

Create the Observability Plane TLS Certificate

Get the observer gateway IP and create a certificate:

OBS_LB_IP=$(kubectl get svc gateway-default -n openchoreo-observability-plane -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
if [ -z "$OBS_LB_IP" ]; then
  OBS_LB_HOSTNAME=$(kubectl get svc gateway-default -n openchoreo-observability-plane -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
  OBS_LB_IP=$(dig +short "$OBS_LB_HOSTNAME" | head -1)
fi

export OBS_DOMAIN="observer.${OBS_LB_IP//./-}.nip.io"
echo "Observer domain: ${OBS_DOMAIN}"

kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: obs-gateway-tls
  namespace: openchoreo-observability-plane
spec:
  secretName: obs-gateway-tls
  issuerRef:
    name: openchoreo-ca
    kind: ClusterIssuer
  dnsNames:
    - "*.${OBS_LB_IP//./-}.nip.io"
    - "${OBS_DOMAIN}"
  privateKey:
    rotationPolicy: Always
EOF

kubectl wait --for=condition=Ready certificate/obs-gateway-tls \
  -n openchoreo-observability-plane --timeout=60s

Enable TLS and Fluent Bit

helm upgrade openchoreo-observability-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-observability-plane \
--version 0.15.0 \
--namespace openchoreo-observability-plane \
--reuse-values \
--set gateway.tls.enabled=true \
--set "gateway.tls.hostname=*.${OBS_LB_IP//./-}.nip.io" \
--set "gateway.tls.certificateRefs[0].name=obs-gateway-tls" \
--set fluent-bit.enabled=true \
--timeout 10m

Register the Observability Plane

AGENT_CA=$(kubectl get secret cluster-gateway-ca \
  -n openchoreo-observability-plane -o jsonpath='{.data.ca\.crt}' | base64 -d)

kubectl apply -f - <<EOF
apiVersion: openchoreo.dev/v1alpha1
kind: ObservabilityPlane
metadata:
  name: default
  namespace: default
spec:
  planeID: default
  clusterAgent:
    clientCA:
      value: |
$(echo "$AGENT_CA" | sed 's/^/        /')
  observerURL: http://observer.openchoreo-observability-plane.svc.cluster.local:8080
EOF

Link Planes and Enable Logs

Tell the data plane (and build plane, if installed) where to send their telemetry:

kubectl patch dataplane default -n default --type merge \
  -p '{"spec":{"observabilityPlaneRef":{"kind":"ObservabilityPlane","name":"default"}}}'

# If you installed the build plane:
kubectl patch buildplane default -n default --type merge \
  -p '{"spec":{"observabilityPlaneRef":{"kind":"ObservabilityPlane","name":"default"}}}'

Verify the observer is reachable:

OBS_HTTPS_PORT=$(kubectl get gateway gateway-default -n openchoreo-observability-plane \
  -o jsonpath='{.spec.listeners[?(@.protocol=="HTTPS")].port}')
OBS_PORT_SUFFIX=$([ "$OBS_HTTPS_PORT" = "443" ] && echo "" || echo ":${OBS_HTTPS_PORT}")

curl -sk "https://${OBS_DOMAIN}${OBS_PORT_SUFFIX}/health"

Production Configuration

This guide gets all planes running on a real cluster with self-signed TLS. For production hardening, see:

Cleanup

Delete plane registrations:

kubectl delete dataplane default -n default 2>/dev/null
kubectl delete buildplane default -n default 2>/dev/null
kubectl delete observabilityplane default -n default 2>/dev/null

Uninstall OpenChoreo planes and prerequisites:

helm uninstall openchoreo-observability-plane -n openchoreo-observability-plane 2>/dev/null
helm uninstall openchoreo-build-plane -n openchoreo-build-plane 2>/dev/null
helm uninstall openchoreo-data-plane -n openchoreo-data-plane 2>/dev/null
helm uninstall openchoreo-control-plane -n openchoreo-control-plane 2>/dev/null
helm uninstall thunder -n openchoreo-control-plane 2>/dev/null
helm uninstall kgateway -n openchoreo-control-plane 2>/dev/null
helm uninstall kgateway-crds 2>/dev/null
helm uninstall external-secrets -n external-secrets 2>/dev/null
helm uninstall cert-manager -n cert-manager 2>/dev/null

Delete namespaces:

kubectl delete namespace \
  openchoreo-control-plane \
  openchoreo-data-plane \
  openchoreo-build-plane \
  openchoreo-observability-plane \
  external-secrets \
  cert-manager 2>/dev/null

Next Steps

Explore the sample applications
Follow Deploy Your First Component
Move to multi-cluster isolation using Multi-Cluster Connectivity

Prerequisites​

Step 1: Install Prerequisites​

Gateway API CRDs​

cert-manager​

External Secrets Operator​

kgateway​

Step 2: Setup Secrets​

ClusterSecretStore​

Step 3: Setup TLS​

Step 4: Setup Control Plane​

Gateway Patch (Optional)​

Create the Control Plane TLS Certificate​

Install Thunder (Identity Provider)​

Backstage Secrets​

Configure the Control Plane​

Step 5: Install Default Resources​

Step 6: Setup Data Plane​

Namespace and Certificates​

Install the Data Plane​

Gateway Patch (Optional)​

Create the Data Plane TLS Certificate​

Enable TLS on the Data Plane​

Register the Data Plane​

Try it: Log In and Deploy​

Step 7: Setup Build Plane (Optional)​

Namespace and Certificates​

Install the Build Plane​

Register the Build Plane​

Try it: Build from Source​

Step 8: Setup Observability Plane (Optional)​

Namespace and Certificates​

OpenSearch Credentials​

Install the Observability Plane​

Gateway Patch (Optional)​

Create the Observability Plane TLS Certificate​

Enable TLS and Fluent Bit​

Register the Observability Plane​

Link Planes and Enable Logs​

Production Configuration​

Cleanup​

Next Steps​

Prerequisites

Step 1: Install Prerequisites

Gateway API CRDs

cert-manager

External Secrets Operator

kgateway

Step 2: Setup Secrets

ClusterSecretStore

Step 3: Setup TLS

Step 4: Setup Control Plane

Gateway Patch (Optional)

Create the Control Plane TLS Certificate

Install Thunder (Identity Provider)

Backstage Secrets

Configure the Control Plane

Step 5: Install Default Resources

Step 6: Setup Data Plane

Namespace and Certificates

Install the Data Plane

Gateway Patch (Optional)

Create the Data Plane TLS Certificate

Enable TLS on the Data Plane

Register the Data Plane

Try it: Log In and Deploy

Step 7: Setup Build Plane (Optional)

Namespace and Certificates

Install the Build Plane

Register the Build Plane

Try it: Build from Source

Step 8: Setup Observability Plane (Optional)

Namespace and Certificates

OpenSearch Credentials

Install the Observability Plane

Gateway Patch (Optional)

Create the Observability Plane TLS Certificate

Enable TLS and Fluent Bit

Register the Observability Plane

Link Planes and Enable Logs

Production Configuration

Cleanup

Next Steps