Skip to content
kix /docs
Install the CLI

How-to guide Start and inspect a Kix project

Deploy to kind

Create a local Kubernetes cluster and deploy a Kix example to it.

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:

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:

kix-examples/ 
❱ kubectl cluster-info
Kubernetes control plane is running at https://127.0.0.1:40711
CoreDNS is running at https://127.0.0.1:40711/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:

kix-examples/ 
❱ kix check how-to-application
 TOOL       RESULT  DETAILS                       
 eval       pass    17 manifests evaluated        
 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:

kix-examples/ live capture 
❱ kix deploy how-to-application -y
Show outputHide output · 53 lines 
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/how-to-app created
  ✔ Namespace/how-to-app ready
  ~ Namespace/kube-system configured
  ✔ Namespace/kube-system ready
  + ConfigMap/production-health-script@how-to-app created
  ✔ ConfigMap/production-health-script@how-to-app ready
  + CustomResourceDefinition/packageinstances.kix.run created
  + CustomResourceDefinition/activations.kix.run created
  ✔ CustomResourceDefinition/packageinstances.kix.run ready
  ✔ CustomResourceDefinition/activations.kix.run ready
  + ConfigMap/production@how-to-app created
  ✔ ConfigMap/production@how-to-app ready
  + ConfigMap/preview@how-to-app created
  ✔ ConfigMap/preview@how-to-app ready
   1.068284643s  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"
  + Deployment/preview@how-to-app created
  + Deployment/production@how-to-app created
  + 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-gb5d6ry45b5l configured
  ✔ Activation/how-to-application-gb5d6ry45b5l ready
  • activation 'how-to-application-gb5d6ry45b5l' → 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:

kix-examples/ 
❱ kubectl get namespaces
NAME                 STATUS   AGE
default              Active   81s
how-to-app           Active   75s
kube-node-lease      Active   81s
kube-public          Active   81s
kube-system          Active   81s
local-path-storage   Active   76s
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           75s
deployment.apps/production   2/2     2            2           75s

NAME                 TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
service/preview      ClusterIP   10.96.13.186   <none>        80/TCP    42s
service/production   ClusterIP   10.96.140.46   <none>        80/TCP    41s

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

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

kix-examples/ 
❱ kix status how-to-application
 NAME                             NAMESPACE    KIND                      READY  STATUS    AGE 
 how-to-application-gb5d6ry45b5l  _cluster     Activation                True   Active    41s 
 activations.kix.run              _cluster     CustomResourceDefinition  True   Active    42s 
 packageinstances.kix.run         _cluster     CustomResourceDefinition  True   Active    42s 
 how-to-app                       _cluster     Namespace                 True   Active    42s 
 kube-system                      _cluster     Namespace                 True   Active    48s 
 preview                          how-to-app   ConfigMap                 True   Active    42s 
 production                       how-to-app   ConfigMap                 True   Active    42s 
 production-health-script         how-to-app   ConfigMap                 True   Active    42s 
 preview                          how-to-app   Deployment                True   1/1       42s 
 production                       how-to-app   Deployment                True   2/2       42s 
 production-health                how-to-app   Job                       True   Complete  8s  
 preview                          how-to-app   PackageInstance           True   Active    9s  
 production                       how-to-app   PackageInstance           True   Active    1s  
 preview                          how-to-app   Service                   True   Active    9s  
 production                       how-to-app   Service                   True   Active    8s  
 platform-dns                     kube-system  PackageInstance           True   Active    41s

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.