Skip to content
kix /docs
Install the CLI

How-to guide Start and inspect a Kix project

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 Kix 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 · 78 lines 
Building cluster 'how-to-application'...
Cluster how-to-application: 17 manifests
Connecting to cluster...
No previous activation on cluster. First deploy.

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

  Plan: cluster-level changes, 4 added
  Resources: 4 real content, 0 dep-affected
  ↻ 1 under the rerun rule (deleted first when live): Job/production-health@how-to-app

Not checked by the dry run (13); their changes come from comparing builds:
  ? 5 its CRD is changed by this deploy, and was checked as it is now:
      Activation/how-to-application-6rhi3wpk9iml
      PackageInstance/platform-dns@kube-system
      PackageInstance/platform-storage@kube-system
      PackageInstance/preview@how-to-app
      PackageInstance/production@how-to-app
  ? 8 its namespace is created by this deploy:
      ConfigMap/preview@how-to-app
      ConfigMap/production-health-script@how-to-app
      ConfigMap/production@how-to-app
      Deployment/preview@how-to-app
      Deployment/production@how-to-app
      and 3 more (-o json lists them)

Not checked by any preview: whether Pods start, pull their images, and pass their probes.

Objects: 17 written, 0 deleted (sha256:0259ef15fef8d74b8e97783aa5ecce1e719dd93ce351b4ef1561e5cd7d9017e3)
plan: 17 nodes
  ~ Namespace/kube-system configured
  + Namespace/how-to-app created
  ✔ Namespace/kube-system ready
  ✔ Namespace/how-to-app ready
  + CustomResourceDefinition/activations.kix.run created
  + CustomResourceDefinition/packageinstances.kix.run created
  + ConfigMap/preview@how-to-app created
  ✔ ConfigMap/preview@how-to-app ready
  + ConfigMap/production-health-script@how-to-app created
  ✔ ConfigMap/production-health-script@how-to-app ready
  + ConfigMap/production@how-to-app created
  ✔ ConfigMap/production@how-to-app ready
  + Deployment/preview@how-to-app created
  + Deployment/production@how-to-app created
  ✔ CustomResourceDefinition/activations.kix.run ready
  ✔ CustomResourceDefinition/packageinstances.kix.run ready
  + PackageInstance/platform-dns@kube-system created
  + PackageInstance/platform-storage@kube-system created
  ✔ PackageInstance/platform-storage@kube-system ready
  … Deployment/preview@how-to-app waiting: Deployment/preview: 0/1 ready, 1/1 updated (idle 10s) (14s of 180s); 3 objects wait for it: Service/preview@how-to-app and 2 more
  … Deployment/production@how-to-app waiting: Deployment/production: 0/2 ready, 2/2 updated (idle 10s) (14s of 180s); 4 objects wait for it: Service/production@how-to-app and 3 more
  … PackageInstance/platform-dns@kube-system waiting: Deployment/coredns: 0/2 ready, 2/2 updated (12s of 180s); 3 objects wait for it: Activation/how-to-application-6rhi3wpk9iml, Job/production-health@how-to-app, and 1 more
  ✔ PackageInstance/platform-dns@kube-system 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
  ✔ 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
  … Job/production-health@how-to-app waiting: Job/production-health: 0 succeeded (idle 0s) (14s of 180s); 2 objects wait for it: PackageInstance/production@how-to-app and 1 more
  ✔ Job/production-health@how-to-app ready
  + PackageInstance/production@how-to-app created
  ✔ PackageInstance/production@how-to-app ready
  ~ Activation/how-to-application-6rhi3wpk9iml configured
  ✔ Activation/how-to-application-6rhi3wpk9iml ready
  • activation 'how-to-application-6rhi3wpk9iml' → Active

Deploy complete: 15 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   52s
how-to-app           Active   46s
kube-node-lease      Active   52s
kube-public          Active   52s
kube-system          Active   52s
local-path-storage   Active   48s
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           46s
deployment.apps/production   2/2     2            2           46s

NAME                 TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
service/preview      ClusterIP   10.96.75.52    <none>        80/TCP    18s
service/production   ClusterIP   10.96.46.123   <none>        80/TCP    16s

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

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

kix-examples/ 
❱ kix status how-to-application
Kubernetes cluster ID: 273d1992-4151-4e27-b64e-d3cab7e00d1f
Kubernetes version: v1.35.0

 NAME                             NAMESPACE    KIND                      READY  STATUS    AGE 
 how-to-application-6rhi3wpk9iml  _cluster     Activation                True   Active    56s 
 activations.kix.run              _cluster     CustomResourceDefinition  True   Active    57s 
 packageinstances.kix.run         _cluster     CustomResourceDefinition  True   Active    57s 
 how-to-app                       _cluster     Namespace                 True   Active    57s 
 kube-system                      _cluster     Namespace                 True   Active    1m  
 preview                          how-to-app   ConfigMap                 True   Active    57s 
 production                       how-to-app   ConfigMap                 True   Active    57s 
 production-health-script         how-to-app   ConfigMap                 True   Active    57s 
 preview                          how-to-app   Deployment                True   1/1       57s 
 production                       how-to-app   Deployment                True   2/2       57s 
 production-health                how-to-app   Job                       True   Complete  21s 
 preview                          how-to-app   PackageInstance           True   Active    25s 
 production                       how-to-app   PackageInstance           True   Active    1s  
 preview                          how-to-app   Service                   True   Active    25s 
 production                       how-to-app   Service                   True   Active    21s 
 platform-dns                     kube-system  PackageInstance           True   Active    56s 
 platform-storage                 kube-system  PackageInstance           True   Active    56s

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.