Local Development

Local development with DevSpace

Develop and live-reload ARK services directly in your Kubernetes cluster using DevSpace.

Prerequisites

A running Kubernetes cluster (e.g., minikube)
kubectl, uv and DevSpace installed
Docker running locally with BuildKit enabled

One-time setup


# Install DevSpace
brew install devspace uv

You can either start the entire project by doing


devspace dev

Each service contains their own devspace config. If you wish to start individual services and wish to use localhost gateway routes, you must first start it


devspace dev --dependency localhost-gateway

then start your desired service by running


devspace dev --dependency ark-api
## or from the subdirectory itself
cd services/ark-api
devspace dev

cert-manager or gateway-api are installed by default to disable them use env vars ENABLE_CERT_MANAGER and ENABLE_GATEWAY_API_CRDS


ENABLE_CERT_MANAGER=false devspace dev

Argo Workflows is opt-in. To enable it, set ENABLE_ARGO:


ENABLE_ARGO=true devspace dev

SSO Mode

SSO is opt-in. ENABLE_SSO=true deploys a local Dex provider with two hardcoded users, puts ark-api and the dashboard in AUTH_MODE=sso, and turns on Kubernetes impersonation so RBAC applies to the logged-in user instead of the ark-api service account.

One-time setup — the issuer hostname must resolve on your machine:


echo "127.0.0.1  dex.default.svc.cluster.local" | sudo tee -a /etc/hosts


ENABLE_SSO=true devspace dev

User	Access to namespace `default`
`admin@ark.local`	Full access to Ark resources, plus secrets, configmaps, pods and events
`viewer@ark.local`	Read-only on Ark resources

The dashboard hides the write controls for the viewer. It reads the effective permissions from /v1/context, which runs a SelfSubjectRulesReview as the impersonated user.

Dex holds no session of its own, so signing out and back in prompts for credentials again. That is how you switch between the two users.

Dex answers at the same URL for the browser and for the pods, because the dashboard performs the code-for-token exchange server-side and ark-api fetches the JWKS. dex.default.svc.cluster.local resolves in-cluster through CoreDNS and, on your machine, through the /etc/hosts entry plus the port-forward DevSpace starts. A 127.0.0.1.nip.io host cannot serve both: nip.io resolves to 127.0.0.1, which inside a pod is the pod itself.

Configuration lives in charts/ark-dex-dev and in the sso profiles of the ark-api and ark-dashboard DevSpace configs. Restart the Dex port-forward with devspace run sso-forward.

Storage Backend Selection

The ark-controller supports two storage backends: etcd (default) and PostgreSQL. Use the STORAGE_BACKEND environment variable to select:


# etcd (default) - uses Kubernetes CRDs
devspace dev
 
# PostgreSQL - deploys a postgres pod with embedded apiserver
STORAGE_BACKEND=postgresql devspace dev

When using postgresql, the controller runs an embedded API server instead of using CRDs.

Switching between storage backends is destructive. Resources created with etcd (CRDs) are not visible in PostgreSQL and vice versa. Switching to postgresql makes the DevSpace pipeline delete every Ark CRD and clear its finalizers, so all existing Ark resources are lost. ark install leaves the CRDs in place; DevSpace does not. Switching back to etcd runs no cleanup at all: the ark.mckinsey.com APIServices stay registered and keep shadowing the reinstalled CRDs until you remove them. Export first: see Migrating between storage backends.

ark-api and ark-dashboard deploy to namespace: default
ark-controller, ark-completions, and localhost-gateway deploy to namespace: ark-system

Completions Engine in Dev Mode

The completions engine runs as a standalone pod. This allows independent code sync and restart — changing engine code only restarts the engine, not the controller.

DevSpace deploys the engine using the chart at executors/completions/chart/. The controller connects via --completions-addr=http://ark-completions.ark-system.


# Both controller and completions engine start with devspace dev
devspace dev --dependency ark-controller

Check deployment status


devspace list deployments --namespace default
devspace list deployments --namespace ark-system

Open the dashboard

You can find a link to the dashboard by getting the current available endpoints


devspace run routes

Or you can port-forward the dashboard yourself:


kubectl port-forward -n default svc/ark-dashboard 3000:3000
# Then open http://localhost:3000

Live reload behavior

ark-dashboard: hot reloads on save
ark-api: hot reloads on save
ark-controller: restarts container on save

When you change CRDs

Regenerate the manifests from the kubebuilder annotations:


cd ark/
make manifests
kubectl apply -f config/crd/bases/ark.mckinsey.com_queries.yaml

Regenerate the Ark SDK with the updated resource types based on the CRDS:


make ark-sdk-build

This will:

Convert CRDs to OpenAPI spec
Generate Python client from OpenAPI
Apply overlay files for custom functionality
Build the Python wheel

More details on how the Ark SDK is generated and used is at the Ark SDK Developer Guide.

Build/deploy production images


devspace deploy

This builds all images, deploys to the cluster, and streams service logs. Press Ctrl+C to stop log streaming.

Clean up


devspace purge