Skip to content
kix docs

Deploy to kind

Use kind to run a Kubernetes cluster in Docker for local Kix development. The kix-examples repository includes a single-node kind configuration and clusters that are safe to deploy together.

This guide assumes Docker, kind, kubectl, and the Kix CLI are installed.

Create the cluster

Section titled “Create the cluster”

From the kix-examples repository, create the configured cluster:

Run in kix-examples/ 
❱ kind create cluster --config kind-config.yaml

The configuration names the cluster kix-demo. Kind creates the kubectl context kind-kix-demo and selects it as the current context.

Confirm that kubectl can reach the API server:

Run in kix-examples/ 
❱ kubectl cluster-info
Kubernetes control plane is running at https://127.0.0.1:57687
CoreDNS is running at https://127.0.0.1:57687/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

If another context is current, select the kind context explicitly:

❱ kubectl config use-context kind-kix-demo

Check the cluster definition

Section titled “Check the cluster definition”

Validate the example before connecting Kix to Kubernetes:

Run in kix-examples/ 
❱ kix check how-to-application
 TOOL         RESULT  DETAILS                                                       
 eval         pass    16 manifests evaluated                                        
 kubeconform  pass    skipped (this validation tool is not yet integrated with Kix) 
 pluto        pass    skipped (this validation tool is not yet integrated with Kix) 
 kyverno      pass    skipped (this validation tool is not yet integrated with Kix) 
 scorecard    pass    0 errors, 11 warnings, 2 info

This evaluates the cluster and runs its configured validation without applying resources.

Deploy the application

Section titled “Deploy the application”

Deploy the cluster and accept the plan:

Run in kix-examples/
❱ kix deploy how-to-application -y Show output 
Building cluster 'how-to-application'...
Cluster how-to-application: 16 manifests
Connecting to cluster...
No previous activation on cluster — first deploy.

  _cluster
    ~ cluster-level resources (4 added)
  how-to-app
    + preview 1.0.0 (3 resources)
    + production 1.0.0 (5 resources)
  kube-system
    + platform-dns (0 resources)

  Plan: cluster-level changes, 3 added
  Resources: 4 real content, 0 dep-affected
  ↻ 1 under the rerun rule (deleted first when live): Job/production-health@how-to-app
plan: 16 nodes
  ~ Namespace/kube-system configured
  + Namespace/how-to-app created
  ✔ Namespace/kube-system ready
  ✔ Namespace/how-to-app ready
  + CustomResourceDefinition/packageinstances.kix.run created
  + ConfigMap/production-health-script@how-to-app created
  ✔ ConfigMap/production-health-script@how-to-app ready
  + CustomResourceDefinition/activations.kix.run created
  + ConfigMap/preview@how-to-app created
  ✔ ConfigMap/preview@how-to-app ready
  + ConfigMap/production@how-to-app created
  ✔ ConfigMap/production@how-to-app ready
  ✔ CustomResourceDefinition/activations.kix.run ready
  + Deployment/preview@how-to-app created
  + Deployment/production@how-to-app created
   0.759471667s  WARN kix::cluster::client: apiserver request failed, retrying method=GET path="/apis/kix.run/v1alpha1/activations" attempt=1 max_attempts=7 delay_ms=1000 reason="429 Too Many Requests"
  ✔ CustomResourceDefinition/packageinstances.kix.run ready
  + PackageInstance/platform-dns@kube-system created
  ✔ PackageInstance/platform-dns@kube-system ready
  ✔ Deployment/preview@how-to-app ready
  + Service/preview@how-to-app created
  ✔ Service/preview@how-to-app ready
  + PackageInstance/preview@how-to-app created
  ✔ PackageInstance/preview@how-to-app ready
  ✔ Deployment/production@how-to-app ready
  + Service/production@how-to-app created
  ✔ Service/production@how-to-app ready
  + recreate Job/production-health@how-to-app created
  ✔ Job/production-health@how-to-app ready
  + PackageInstance/production@how-to-app created
  ✔ PackageInstance/production@how-to-app ready
  ~ Activation/how-to-application-aq1zdgf9gsnb configured
  ✔ Activation/how-to-application-aq1zdgf9gsnb ready
  • activation 'how-to-application-aq1zdgf9gsnb' → Active

Deploy complete: 14 created, 2 configured, 0 unchanged, 0 failed

Kix builds the manifests, compares them with the current activation, applies resources in dependency order, waits for readiness, runs the production health check, and records the new activation.

The captured deployment ends with the activation becoming Active. A failed resource or post-deploy check prevents that transition.

Inspect the result

Section titled “Inspect the result”

Check the namespaces and workloads with kubectl:

Run in kix-examples/ 
❱ kubectl get namespaces
NAME                 STATUS   AGE
default              Active   60s
how-to-app           Active   55s
kube-node-lease      Active   60s
kube-public          Active   60s
kube-system          Active   60s
local-path-storage   Active   56s
Run in kix-examples/ 
❱ kubectl get deployments,services,jobs -n how-to-app
NAME                         READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/preview      1/1     1            1           55s
deployment.apps/production   2/2     2            2           55s

NAME                 TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
service/preview      ClusterIP   10.96.18.107    <none>        80/TCP    29s
service/production   ClusterIP   10.96.209.157   <none>        80/TCP    29s

NAME                          STATUS     COMPLETIONS   DURATION   AGE
job.batch/production-health   Complete   1/1           1s         5s

Use Kix to see the status associated with the cluster definition:

Run in kix-examples/ 
❱ kix status how-to-application
 NAME                             NAMESPACE    KIND                      READY  STATUS    AGE 
 how-to-application-aq1zdgf9gsnb  _cluster     Activation                True   Active    2s  
 activations.kix.run              _cluster     CustomResourceDefinition  True   Active    38s 
 packageinstances.kix.run         _cluster     CustomResourceDefinition  True   Active    38s 
 how-to-app                       _cluster     Namespace                 True   Active    38s 
 kube-system                      _cluster     Namespace                 True   Active    43s 
 preview                          how-to-app   ConfigMap                 True   Active    38s 
 production                       how-to-app   ConfigMap                 True   Active    38s 
 production-health-script         how-to-app   ConfigMap                 True   Active    38s 
 preview                          how-to-app   Deployment                True   1/1       38s 
 production                       how-to-app   Deployment                True   2/2       38s 
 production-health                how-to-app   Job                       True   Complete  10s 
 preview                          how-to-app   PackageInstance           True   Active    12s 
 production                       how-to-app   PackageInstance           True   Active    2s  
 preview                          how-to-app   Service                   True   Active    12s 
 production                       how-to-app   Service                   True   Active    12s 
 platform-dns                     kube-system  PackageInstance           True   Active    36s

Remove the local cluster

Section titled “Remove the local cluster”

When you no longer need it, delete the kind cluster:

❱ kind delete cluster --name kix-demo

This removes the local Kubernetes cluster and everything deployed into it. It does not change the files in kix-examples.