Development Cluster with Kind

This guide describes how to set up a local development cluster using Kind for testing and developing SolAr.

Warning

This setup is intended for local development and testing only. Do not use in production.

Prerequisites

• Docker installed and running
• Kind installed
• kubectl installed
• Helm installed
• yq installed
• Flux CLI installed

This should be taken care of if you use the Makefile. The ocm CLI is not a manual prerequisite, the Makefile provisions it into bin/ automatically.

Quick Start

Spin up the complete development cluster:

make dev-cluster

This will:

1. Create a Kind cluster named solar-dev (if it doesn't exist)
2. Build and load Docker images into the cluster
3. Transfer the ocm-demo component
4. Install and configure:
5. cert-manager
6. trust-manager
7. Zot registries (discovery and deploy)
8. SolAr with your local images
9. solar-discovery in scan mode, with the local discovery Zot already registered as a Registry, so the catalog populates automatically once an OCM package is pushed

What Gets Installed

Component	Namespace	Description
cert-manager	cert-manager	TLS certificate management
trust-manager	cert-manager	Trust bundle management
zot-discovery	zot	OCI registry for discovery
zot-deploy	zot	OCI registry for deployment
solar	solar-system	SolAr API server and controllers
solar-discovery	solar-system	Scans the discovery registry (scan mode) and populates the catalog

Accessing Registries

The Zot registries use ClusterIP services. Use kubectl port-forward to access them:

# Terminal 1: Forward zot-discovery
kubectl -n zot port-forward svc/zot-discovery 4443:443

# Terminal 2: Forward zot-deploy
kubectl -n zot port-forward svc/zot-deploy 4444:443

Then access at:

• zot-discovery: https://localhost:4443
• zot-deploy: https://localhost:4444

Pushing Images

Tag and push images to the local registries:

# Push to zot-discovery
docker tag localhost/local/solar-discovery-worker:dev.* \
    localhost:4443/solar-discovery-worker:local
docker push localhost:4443/solar-discovery-worker:local

# Push to zot-deploy
docker tag localhost/local/solar-apiserver:dev.* \
    localhost:4444/solar-apiserver:local
docker push localhost:4444/solar-apiserver:local

Pulling Images

Configure your local Kubernetes cluster to pull from the local registries:

# Create image pull secret if needed
kubectl create secret docker-registry zot-creds \
    --docker-server=localhost:4443 \
    --docker-username=admin \
    --docker-password=admin \
    -n your-namespace

# Add to service account
kubectl patch serviceaccount default \
    -p '{"imagePullSecrets":[{"name":"zot-creds"}]}' \
    -n your-namespace

Setting Up Discovery for Testing

The test/fixtures/setup-discovery.sh script sets up the OCM transfer workflow for testing the discovery worker.

When to Use It

Use this script when you want to:

• Test the discovery worker with real OCI artifacts
• Verify discovery functionality end-to-end
• Debug discovery-related issues

Running the Script

./test/fixtures/setup-discovery.sh

This will:

1. Wait for zot-discovery to be ready
2. Start a port-forward to zot-discovery
3. Transfer the ocm-demo component via OCM (using test/fixtures/e2e/ocmconfig, which trusts the cluster CA)
4. Clean up the port-forward (always, via a trap)

Since make dev-cluster deploys solar-discovery in scan mode with the discovery Zot already registered, you do not apply a Registry yourself. A few seconds after the transfer the discovery worker scans the registry and creates the Component and ComponentVersion in the solar-system namespace:

kubectl --context kind-solar-dev -n solar-system get components,componentversions

Environment Variables

Variable	Default	Description
KIND_CLUSTER_DEV	solar-dev	Kind cluster name
KUBECTL	kubectl	Kubernetes CLI
OCM	ocm	OCM CLI path. The Makefile provisions it into bin/go/ocm, which is not on PATH, so for standalone use pass OCM=./bin/go/ocm
OCM_CONFIG	./test/fixtures/e2e/ocmconfig	ocm config file (needs the rootcerts block that trusts the cluster CA)
OCM_DEMO_DIR	test/fixtures/ocm-demo-ctf	ocm-demo CTF location
LOCAL_PORT	4443	local port for the zot-discovery port-forward

Example:

OCM=./bin/go/ocm KIND_CLUSTER_DEV=my-cluster ./test/fixtures/setup-discovery.sh

Setting Up Release for Testing

The test/fixtures/setup-release.sh script creates Component and Release resources to test if RenderTasks are created correctly and can push to the zot-deploy registry.

When to Use It

Use this script when you want to:

• Test Release resource creation and rendering
• Verify RenderTasks are created for Release resources
• Test pushing rendered releases to the deploy zot registry

Prerequisites

Run setup-discovery.sh first to transfer the ocm-demo OCM package to zot-discovery:

./test/fixtures/setup-discovery.sh

Running the Script

./test/fixtures/setup-release.sh

This will apply:

• test/fixtures/e2e/componentversion.yaml - Creates Component and ComponentVersion resources
• test/fixtures/e2e/release.yaml - Creates a Release resource

Environment Variables

Variable	Default	Description
KIND_CLUSTER_DEV	solar-dev	Kind cluster name
KUBECTL	kubectl	Kubernetes CLI
NAMESPACE	solar-system	Target namespace

Example:

NAMESPACE=my-namespace ./test/fixtures/setup-release.sh

Watching the Results

After applying, watch for the Release and its associated Job/Pod. Replace my-namespace with your namespace if different:

kubectl get components,componentversions,releases,jobs,pods -n my-namespace -w

The flow is:

1. Component and ComponentVersion are created in the namespace
2. Release is created in the namespace
3. The rendertask_controller creates a Job in the same namespace
4. The Job spawns a Pod that renders the release and pushes it to the zot-deploy registry

Rebuilding Without Full Setup

After making code changes, rebuild images and reload them:

make dev-cluster-rebuild

This builds and loads Docker images without reinstalling everything.

Cleaning Up

Remove the development cluster:

make cleanup-dev-cluster

Or delete only the Kind cluster:

kind delete cluster --name solar-dev

Troubleshooting

Webhook Not Ready

If you see TLS certificate errors related to webhooks, wait a moment for cert-manager to initialize, then retry:

kubectl get pods -n cert-manager
kubectl get certificates -n cert-manager

Images Not Loading

Verify images are loaded into Kind:

kind get images --name solar-dev

Port Conflicts

If ports 4443 or 4444 are in use, modify the service port in the respective values files under test/fixtures/.