Installation

Requirements

Argo CD

Kokumi deploys through Argo CD: every Serving creates and updates Argo CD Application resources that point at the immutable OCI artifacts of its Preparations. Install Argo CD, in the namespace argocd, before Kokumi:

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

The last document of install.yaml is a RoleBinding in argocd that lets Kokumi register Clusters with Argo CD: it may create, update and delete Secrets there, and the admission policy kokumi-argocd-secret-integrity keeps it to the cluster Secrets it manages. Installed without Argo CD, everything else applies and that document fails; apply install.yaml again once Argo CD is installed.

Until Argo CD’s CRDs exist, Kokumi renders, signs and scans as usual, and Servings deploy nothing and report ArgoCDNotInstalled. They deploy once Argo CD is installed, without a restart.

Argo CD registry credentials

The bundled registry serves plain HTTP. Register it with Argo CD with insecureOCIForceHttp=true, so that Argo CD can pull the Preparations:

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 -

An Order that pushes to another registry needs Argo CD credentials for that registry instead; see Registries and Repositories.

Install

kubectl apply -f \
    https://github.com/kokumi-dev/kokumi/releases/download/0.18.0/install.yaml

To check a release before you apply it, see Release Verification.

This installs:

• The Kokumi CRDs. kubectl get kokumi -A lists every Kokumi object: all its kinds are in the category kokumi.
• In the namespace kokumi:
  • the controller manager, which creates the Kitchen default, the Registry of the bundled registry, the Cluster in-cluster and the Environment local on start;
  • the API server and web UI, Service kokumi-server, also exposed as NodePort 30051;
  • the bundled registry, Service kokumi-registry, also exposed as NodePort 30050, with the 1 GiB PersistentVolumeClaim kokumi-registry-pvc;
  • the kokumi-scanner component and its NetworkPolicy, idle until the Kitchen enables vulnerability scanning.
• The namespace kokumi-signing, for the signing key.
• RBAC roles and bindings, and in argocd the RoleBinding that lets the controller write Argo CD’s cluster Secrets.
• Admission policies, named kokumi-*, that guard Approvals, statuses, the signing key, the Secrets that Registries and Clusters name, and the controller’s writes in argocd. They assume the install namespace kokumi; see Authorization.

Verify

kubectl get pods -n kokumi
kubectl logs -n kokumi deployment/kokumi-controller-manager -c manager -f

Turn on login

A fresh installation has no login method: the UI says No login method is configured, and the API refuses every request. Turn on the built-in admin account on the Kitchen:

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

The controller generates a password for the user admin. Read it:

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

Then delete the Secret kokumi-initial-admin, or bring your own password, or sign in with OIDC instead; see Authentication. The server picks up changes to the Kitchen and its Secrets without a restart.

Access the UI

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

Open http://localhost:8080 in your browser.

Signing key

On its first start the controller generates the key that signs every artifact, in the Secret kokumi-signing-key in the namespace kokumi-signing. To bring your own key instead, create the Secret before installing:

kubectl create namespace kokumi-signing
cosign generate-key-pair k8s://kokumi-signing/kokumi-signing-key

See Signing for how the key is protected and rotated.

Private certificate authorities

A registry whose certificate a private CA signed needs that CA. For one Registry, put it in the Secret its certSecretRef names (see Registries and Repositories). A CA that every registry of the platform uses belongs into the trust store of the controller and the server: mount it into both containers and list its directory in SSL_CERT_DIR next to the system one, for example with a kustomize patch of kokumi-controller-manager and kokumi-server:

spec:
  template:
    spec:
      containers:
      - name: manager                  # server: the container of kokumi-server
        env:
        - name: SSL_CERT_DIR
          value: /etc/ssl/certs:/etc/kokumi/ca
        volumeMounts:
        - name: platform-ca
          mountPath: /etc/kokumi/ca
          readOnly: true
      volumes:
      - name: platform-ca
        configMap:
          name: platform-ca            # a ConfigMap with the CA's PEM file

Upgrade

Apply the install.yaml of the new version:

kubectl apply -f \
    https://github.com/kokumi-dev/kokumi/releases/download/<VERSION>/install.yaml

Kokumi is pre-1.0, and a release may change its CRDs without a migration; the release notes say what to re-apply. To run the latest release, follow its docs; to run your own change, see Run your build.

Uninstall

Delete Kokumi’s CustomResourceDefinitions first, while Kokumi runs: that deletes every Kokumi object, and Kokumi releases each of them. Servings remove their Argo CD Applications, and what runs on the clusters keeps running. Clusters remove their registrations from Argo CD. Then delete the rest:

kubectl get crd -o name | grep '\.delivery\.kokumi\.dev$' | xargs kubectl delete
kubectl delete --ignore-not-found -f \
    https://github.com/kokumi-dev/kokumi/releases/download/0.18.0/install.yaml

Deleting install.yaml alone stops Kokumi together with its objects, and the objects whose finalizers Kokumi could not release keep the kokumi namespace in Terminating. In argocd, remove the Secret manifests-registry-creds and the namespaces you added to the sourceNamespaces of an AppProject yourself.