Single Cluster Setup
This guide provides step-by-step instructions for setting up a local development environment for OpenChoreo using Kind (Kubernetes in Docker).
Prerequisites
- Docker – Just have it installed on your machine, and you're good to go.
- We recommend using Docker Engine version 26.0+.
- Allocate at least 8 GB RAM and 4 CPU cores to Docker (or the VM running Docker).
- Kind v0.20+ installed
- kubectl v1.32+ installed
- Helm v3.12+ installed
Verify Prerequisites
Before proceeding, verify that all tools are installed and meet the minimum version requirements:
# Check Docker (should be v20.10+)
docker --version
# Check Kind (should be v0.20+)
kind --version
# Check kubectl (should be v1.32+)
kubectl version --client
# Check Helm (should be v3.12+)
helm version --short
Make sure Docker is running:
docker info
Quick Setup
This setup uses pre-built images and Helm charts from the OpenChoreo registry.
1. Create OpenChoreo Kind Cluster
Create a new Kind cluster using the provided configuration:
curl -s https://raw.githubusercontent.com/openchoreo/openchoreo/main/install/kind/kind-config.yaml | kind create cluster --config=-
This will:
- Create a cluster named "openchoreo"
- Set up control plane and worker nodes
- Configure the worker node with OpenChoreo-specific labels
- Set kubectl context to "kind-openchoreo"
2. Install Cilium CNI
Install Cilium as the Container Network Interface (CNI). This will create the cilium namespace automatically:
helm install cilium oci://ghcr.io/openchoreo/helm-charts/cilium --version 0.0.0-latest-dev --create-namespace --namespace cilium --wait
Wait for Cilium pods to be ready:
kubectl wait --for=condition=Ready pod -l k8s-app=cilium -n cilium --timeout=300s
Verify that the nodes are now Ready:
kubectl get nodes
You should see both nodes in Ready status.
3. Install OpenChoreo Control Plane
Install the OpenChoreo control plane using the following helm install command. This will create the openchoreo-control-plane namespace automatically:
helm install control-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-control-plane \
--version 0.0.0-latest-dev \
--create-namespace --namespace openchoreo-control-plane \
--timeout=10m
Wait for the installation to complete and verify all pods are running:
kubectl get pods -n openchoreo-control-plane
You should see pods for:
controller-manager(Running)api-server(Running)cert-manager-*(3 pods, all Running)
4. Install OpenChoreo Data Plane
Install the OpenChoreo data plane using the following helm install command. This will create the openchoreo-data-plane namespace automatically:
helm install data-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-data-plane \
--version 0.0.0-latest-dev \
--create-namespace --namespace openchoreo-data-plane \
--timeout=10m \
--set cert-manager.enabled=false \
--set cert-manager.crds.enabled=false
We disable cert-manager since it's already installed by the control plane.
Wait for dataplane components to be ready:
kubectl get pods -n openchoreo-data-plane
You should see pods for:
hashicorp-vault-0(Running)secrets-store-csi-driver-*(Running on each node)gateway-*(Running)registry-*(Running)redis-*(Running)envoy-gateway-*(Running)envoy-ratelimit-*(Running)fluent-bit-*(Running)
5. Install OpenChoreo Build Plane (Optional)
The Build Plane is required if you plan to use OpenChoreo’s internal CI capabilities. If you're only deploying pre-built container images, you can skip this step.
Install the OpenChoreo build plane using the following helm install command for CI/CD capabilities using Argo Workflows. This will create the openchoreo-build-plane namespace automatically:
helm install build-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-build-plane \
--version 0.0.0-latest-dev \
--create-namespace --namespace openchoreo-build-plane --timeout=10m
Wait for the build plane components to be ready:
kubectl get pods -n openchoreo-build-plane
You should see pods for:
argo-workflow-controller-*(Running)
Configure BuildPlane
Register the build plane with the control plane by running:
curl -s https://raw.githubusercontent.com/openchoreo/openchoreo/main/install/add-build-plane.sh | bash
This script will:
- Detect single-cluster mode automatically
- Extract cluster credentials from your kubeconfig
- Create a BuildPlane resource in the default namespace
- Configure the build plane connection to the control plane
Verify that the BuildPlane was created:
kubectl get buildplane -n default
6. Configure DataPlane
Register the data plane with the control plane by running:
curl -s https://raw.githubusercontent.com/openchoreo/openchoreo/main/install/add-default-dataplane.sh | bash
This script will:
- Detect single-cluster mode automatically
- Extract cluster credentials from your kubeconfig
- Create a DataPlane resource in the default namespace
- Configure the registry and gateway endpoints
Verify the DataPlane was created:
kubectl get dataplane -n default
7. Install OpenChoreo Observability Plane (Optional)
Install the OpenChoreo observability plane using the following helm install command for monitoring and logging capabilities. This will create the openchoreo-observability-plane namespace automatically:
helm install observability-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-observability-plane \
--version 0.0.0-latest-dev \
--create-namespace --namespace openchoreo-observability-plane \
--timeout=10m
Wait for the observability plane components to be ready:
kubectl get pods -n openchoreo-observability-plane
You should see pods for:
opensearch-0(Running) - Log storage backendopensearch-dashboard-*(Running) - Visualization dashboardobserver-*(Running) - Log processing service
The OpenSearch pod may take several minutes.
Verify that all pods are ready:
kubectl wait --for=condition=Ready pod --all -n openchoreo-observability-plane --timeout=600s
Verify FluentBit is sending logs to OpenSearch:
# Check if kubernetes indices are being created
kubectl exec -n openchoreo-observability-plane opensearch-0 -- curl -s "http://localhost:9200/_cat/indices?v" | grep kubernetes
# Check recent log count
kubectl exec -n openchoreo-observability-plane opensearch-0 -- curl -s "http://localhost:9200/kubernetes-*/_count" | jq '.count'
If the indices exist and the count is greater than 0, FluentBit is successfully collecting and storing logs.
Configure Observer Integration
Configure the DataPlane and BuildPlane to use the observer service.
# Configure DataPlane to use observer service
kubectl patch dataplane default -n default --type merge -p '{"spec":{"observer":{"url":"http://observer.openchoreo-observability-plane:8080","authentication":{"basicAuth":{"username":"dummy","password":"dummy"}}}}}'
# Configure BuildPlane to use observer service
kubectl patch buildplane default -n default --type merge -p '{"spec":{"observer":{"url":"http://observer.openchoreo-observability-plane:8080","authentication":{"basicAuth":{"username":"dummy","password":"dummy"}}}}}'
Important: Without this configuration, build logs will not be pushed to the observability plane and application logs will not be visible in the Backstage portal, significantly impacting the developer experience.
This configuration enables:
- Application logs to appear in Backstage portal
- Enhanced logging and monitoring across build and data planes
- Integration with the observability plane for comprehensive platform monitoring
- Centralized log publishing and access through the observer service
Verify the observer configuration:
# Check DataPlane observer config
kubectl get dataplane default -n default -o jsonpath='{.spec.observer}' | jq '.'
# Check BuildPlane observer config
kubectl get buildplane default -n default -o jsonpath='{.spec.observer}' | jq '.'
8. Install OpenChoreo Backstage Portal (Optional)
Install the OpenChoreo Backstage developer portal to provide a unified developer experience for your OpenChoreo platform. Backstage serves as a centralized hub where developers can discover, manage, and monitor all their services and components.
The Backstage portal provides:
- Cell Diagram: View all deployed components and their relationships
- Logs: View runtime logs and build logs of each component
- Configure and Deploy: Configure, deploy and promote web applications and services through environments
helm install openchoreo-backstage-demo oci://ghcr.io/openchoreo/helm-charts/backstage-demo \
--version 0.0.0-latest-dev \
--namespace openchoreo-control-plane
Wait for the Backstage pod to be ready:
kubectl wait --for=condition=Ready pod -l app.kubernetes.io/name=backstage -n openchoreo-control-plane --timeout=300s
Verify the installation:
# Check pod status
kubectl get pods -l app.kubernetes.io/name=backstage -n openchoreo-control-plane
# Check service
kubectl get svc backstage-demo -n openchoreo-control-plane
To access the Backstage portal:
# Port forward the Backstage service in background and open browser
kubectl port-forward -n openchoreo-control-plane svc/backstage-demo 7007:7007 > /dev/null 2>&1 & sleep 2 && open http://localhost:7007
# Or if you prefer to manually open the browser:
kubectl port-forward -n openchoreo-control-plane svc/backstage-demo 7007:7007 > /dev/null 2>&1 & sleep 2
# Then access in browser at http://localhost:7007
# To stop the port-forward when done:
pkill -f "kubectl.*port-forward.*backstage-demo.*7007:7007"
You can verify the portal is working correctly with curl:
curl -s http://localhost:7007 | head -20
What You'll See in Backstage
Once you access the Backstage portal, you'll find:
Service Catalog:
- All OpenChoreo components automatically discovered and cataloged
- Component metadata, ownership, and lifecycle information
OpenChoreo Integration:
- Cell Diagram: View all deployed components and their relationships
- Logs: View runtime logs and build logs of each component
- Configure and Deploy: Configure, deploy and promote web applications and services through environments
The OpenChoreo Backstage plugin automatically synchronizes with your platform, ensuring developers always have up-to-date information about their services and the broader platform ecosystem.
9. Install OpenChoreo Default Identity Provider (Optional)
Install the OpenChoreo default identity provider to secure APIs deployed on your platform. This component provides authentication and authorization capabilities for your services.
This identity provider is intended for demonstration and development purposes only. It is not production-ready and should not be used in production environments.
Install the identity provider using the following helm install command. This will create the openchoreo-identity-system namespace automatically:
helm install identity-provider oci://ghcr.io/openchoreo/helm-charts/openchoreo-identity-provider \
--version 0.0.0-latest-dev \
--create-namespace --namespace openchoreo-identity-system \
--timeout=10m
Wait for the identity provider components to be ready:
kubectl get pods -n openchoreo-identity-system
You should see pods for the identity provider service running.
Verify the installation:
# Check pod status
kubectl wait --for=condition=Ready pod --all -n openchoreo-identity-system --timeout=300s
# Check service
kubectl get svc -n openchoreo-identity-system
10. Verify OpenChoreo Installation
Check that default OpenChoreo resources were created:
# Check default organization and project
kubectl get organizations,projects,environments -A
# Check default platform classes
kubectl get serviceclass,apiclass -n default
# Check all OpenChoreo CRDs
kubectl get crds | grep openchoreo
# Check gateway resources
kubectl get gateway,httproute -n openchoreo-data-plane
Check that all components are running:
# Check cluster info
kubectl cluster-info --context kind-openchoreo
# Check control plane pods
kubectl get pods -n openchoreo-control-plane
# Check data plane pods
kubectl get pods -n openchoreo-data-plane
# Check build plane pods (if installed)
kubectl get pods -n openchoreo-build-plane
# Check observability plane pods (if installed)
kubectl get pods -n openchoreo-observability-plane
# Check identity provider pods (if installed)
kubectl get pods -n openchoreo-identity-system
# Check Cilium pods
kubectl get pods -n cilium
# Check nodes (should be Ready)
kubectl get nodes
Next Steps
After completing this setup you can:
- Explore the Backstage portal (if installed) at
http://localhost:7007to get familiar with the developer interface - Deploy your first component and see it appear automatically in Backstage
- Test the GCP microservices demo to see multi-component applications in action
- Deploy additional sample applications from the OpenChoreo samples
- Use Backstage to monitor component health, view logs, and manage your application portfolio
- Develop and test new OpenChoreo features
Cleaning Up
To completely remove the development environment:
# Delete the Kind cluster
kind delete cluster --name openchoreo
# Remove kubectl context (optional)
kubectl config delete-context kind-openchoreo
# Clean up cert-manager leader election leases (for future reinstalls)
kubectl delete lease cert-manager-controller -n kube-system --ignore-not-found
kubectl delete lease cert-manager-cainjector-leader-election -n kube-system --ignore-not-found