Getting Started

This tutorial renders the podinfo Helm chart with Kokumi, promotes the result to the cluster Kokumi runs in, changes it, and rolls the change back. It takes about ten minutes on a test cluster such as kind.

Install

You need a Kubernetes cluster ≥ 1.30 with a default StorageClass, and kubectl. Install Argo CD, register the bundled registry with it, install Kokumi, and turn on the admin login, as Installation explains:

kubectl create namespace argocd
kubectl apply -n argocd --server-side --force-conflicts \
    -f https://raw.githubusercontent.com/argoproj/argo-cd/v3.5.1/manifests/install.yaml

kubectl -n argocd create secret generic manifests-registry-creds \
    --from-literal=type=oci \
    --from-literal=url=oci://kokumi-registry.kokumi.svc.cluster.local:5000 \
    --from-literal=insecureOCIForceHttp=true \
    --dry-run=client -o yaml | \
kubectl label -f - argocd.argoproj.io/secret-type=repo-creds --local -o yaml | \
kubectl apply -f -

kubectl apply -f \
    https://github.com/kokumi-dev/kokumi/releases/download/0.18.0/install.yaml
kubectl -n kokumi rollout status deployment/kokumi-controller-manager

kubectl -n kokumi patch kitchen default --type=merge \
    -p '{"spec":{"auth":{"adminUser":{"enabled":true}}}}'

Let a namespace deploy

Orders deploy to an Environment of their own namespace. Kokumi keeps the Environment local, the cluster it runs in, in its own namespace kokumi; the example local adds the same to another namespace. Argo CD’s project default must also admit the namespace in its sourceNamespaces:

kubectl create namespace shop
kubectl -n argocd patch appproject default --type=merge -p '{"spec":{"sourceNamespaces":["shop"]}}'

kubectl apply -n shop -k "https://github.com/kokumi-dev/kokumi//examples/local?ref=0.18.0"

The patch replaces the list; where the project lists namespaces already, add shop to it instead. See Environments.

Create a Product and an Order

A Product defines the application: here, the podinfo chart with a base value, and which values its Orders may change.

examples/getting-started/product.yaml

apiVersion: delivery.kokumi.dev/v1alpha1
kind: Product
metadata:
  name: podinfo
spec:
  # A Helm chart pushed to an OCI registry.
  source:
    url: oci://ghcr.io/stefanprodan/charts/podinfo
    version: "6.14.1"

  # Render the chart with these base values. The release name and namespace
  # default to each Order's name and namespace.
  render:
    helm:
      values:
        ui:
          color: "#EF6461"

  # Orders of this Product may set these values and nothing else. Without
  # overrides, Orders may not change anything.
  overrides:
    values:
      policy: Listed
      paths:
      - ui.message
      - replicaCount

An Order is one variant of it, and sets only what differs:

examples/getting-started/order.yaml

apiVersion: delivery.kokumi.dev/v1alpha1
kind: Order
metadata:
  name: podinfo
spec:
  productRef:
    name: podinfo

  # The Environment it deploys to, in the Order's namespace. Kokumi keeps the
  # Environment local in its own namespace, kokumi: the cluster it runs in.
  # The Environment cannot be changed later; another Environment is another
  # Order.
  environmentRef:
    name: local

  # Deep-merged over the Product's values; the Order's win.
  values:
    ui:
      message: "Hello from Kokumi"
    replicaCount: 2

  # Every change renders a new Preparation, an immutable OCI artifact in the
  # bundled registry. Nothing deploys until you promote a Preparation.
  promotion:
    mode: Manual

Apply both:

kubectl apply -n shop -k "https://github.com/kokumi-dev/kokumi//examples/getting-started?ref=0.18.0"

Watch the Preparation

Kokumi merges the Order over its Product, renders the chart, and pushes the result to the bundled registry as an immutable, signed Preparation:

kubectl get preparations -n shop --watch
# NAME                   ORDER     READY   REASON   APPROVED              AGE
# podinfo-d7ce0c46a686   podinfo   True    Ready    ApprovalNotRequired   20s

The Order is Manual, so nothing deploys yet.

Promote it

Open the UI:

kubectl port-forward -n kokumi svc/kokumi-server 8080:80

kubectl -n kokumi get secret kokumi-initial-admin \
    -o jsonpath='{.data.password}' | base64 -d; echo

Open the Order podinfo, look through the rendered files of its Preparation, and click Promote. The promotion creates the Order’s Serving, which deploys the Preparation through an Argo CD Application:

kubectl get servings -n shop
# NAME      ORDER     TARGET                 READY   REASON     APPROVED              VERIFIED             AGE
# podinfo   podinfo   podinfo-d7ce0c46a686   True    Deployed   ApprovalNotRequired   SignaturesVerified   30s

kubectl get deployments -n shop
# NAME      READY   UP-TO-DATE   AVAILABLE   AGE
# podinfo   2/2     2            2           30s

Change it and roll back

Scale the Order to three replicas, with a message that describes the change:

kubectl annotate order podinfo -n shop delivery.kokumi.dev/commit-message="Scale to 3 replicas"
kubectl patch order podinfo -n shop --type=merge -p '{"spec":{"values":{"replicaCount":3}}}'

A second Preparation appears, with the first one as its parent. In the UI, its Changes tab shows the difference to the previous Preparation; promote it, and podinfo runs three replicas. To roll back, promote the first Preparation again. Its artifact is still in the registry, so nothing is rendered again.