Others (KinD etc)
System setup
This guide will show you how to use Kratix on two Kubernetes clusters. Install the prerequisites listed below if they aren't already on your system. If you are using pre-existing clusters or want to use a different tool to provision your clusters, skip requirements 1 and 2.
kind
CLI / Kubernetes-in-Docker (KinD): Used to create and manage local Kubernetes clusters in Docker. See the quick start guide to install.docker
CLI / Docker: Used to orchestrate containers.kind
(above) requires that you have Docker installed and configured. See Get Docker to install.kubectl
/ Kubernetes command-line tool: The CLI for Kubernetes — allows you to run commands against Kubernetes clusters. See the install guide.
To get setup locally quickly with KinD clusters you can use the ./scripts/quick-start.sh
from the root of the Kratix repository. This provisions
an in-cluster MinIO
to use as the backing State Store.
Alternatively you can provide the --git
flag to create it with an in-cluster Gitea
instance instead.
Set up platform cluster
If you are not using a pre-existing cluster, create your platform cluster locally using KinD:
kind create cluster --image kindest/node:v1.27.3 --name platform
# set PLATFORM to point to the platform cluster context
export PLATFORM="kind-platform"
Install cert-manager
Kratix requires a set of certificates in order to deploy its internal Validating and Mutating Kubernetes webhooks. By default Kratix is configured to use cert-manager to generate the certificates, therefore we need to install cert-manager. If you already have it installed, skip to the next section.
Don't want to use cert-manager? Manually provide the required certificates
Cert-manager is used to generate a CA, and a key/cert pair which is configured for the following DNS names:
kratix-platform-webhook-service.kratix-platform-system.svc.cluster.local
kratix-platform-webhook-service.kratix-platform-system.svc
To manually provide the required certificates, you need to create the
webhook-server-cert
secret in the kratix-platform-system
namespace with the
following keys:
apiVersion: v1
data:
ca.crt: # Base64 CA certificate
tls.crt: # Base64 encoded Server certificate
tls.key: # Base64 encoded Server private key
kind: Secret
metadata:
name: webhook-server-cert
namespace: kratix-platform-system
type: kubernetes.io/tls
As part of installing Kratix we create a few resources that require the CA
certificate. You will have to manually add the CA certificate to the resources
mentioned below, and manually remove the cert-manager Certificate
and Issuer
resources. The following resources need to be updated to contain the Base64
encoded CA certificate:
-
MutatingWebhookConfiguration/kratix-platform-mutating-webhook-configuration
apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
metadata:
name: kratix-platform-mutating-webhook-configuration
webhooks:
- admissionReviewVersions:
- v1
clientConfig:
caBundle: .... # there might be multiple admissionReviewVersions, ensure you update all of them -
ValidatingWebhookConfiguration/kratix-platform-validating-webhook-configuration
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
name: kratix-platform-validating-webhook-configuration
webhooks:
- admissionReviewVersions:
- v1
clientConfig:
caBundle: .... # there might be multiple admissionReviewVersions, ensure you update all of them -
CustomResourceDefinition/promises.platform.kratix.io
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: promises.platform.kratix.io
spec:
conversion:
strategy: Webhook
webhook:
clientConfig:
caBundle: ....
Lastly, you need to remove the following cert-manager Issuer and Certificate from Kratix release manifest:
---
...
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: kratix-platform-serving-cert
namespace: kratix-platform-system
spec:
...
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: kratix-platform-selfsigned-issuer
namespace: kratix-platform-system
spec:
...
To install it, run:
kubectl --context $PLATFORM apply --filename https://github.com/cert-manager/cert-manager/releases/download/v1.15.0/cert-manager.yaml
Make sure that cert-manager
is ready before installing Kratix:
$ kubectl --context $PLATFORM get pods --namespace cert-manager
NAME READY STATUS RESTARTS AGE
cert-manager-7476c8fcf4-r8cnd 1/1 Running 0 19s
cert-manager-cainjector-bdd866bd4-7d8zp 1/1 Running 0 19s
cert-manager-webhook-5655dcfb4b-54r49 1/1 Running 0 19s
Install Kratix
Install Kratix on the Platform Cluster.
kubectl apply --context $PLATFORM --filename https://github.com/syntasso/kratix/releases/latest/download/kratix.yaml
You can also install and configure Kratix with Helm. For more information, see the Helm Chart documentation.
Make sure that kratix
is ready before proceeding:
$ kubectl --context $PLATFORM get pods --namespace kratix-platform-system
NAME READY STATUS RESTARTS AGE
kratix-platform-controller-manager-78d57569b-bn4t4 2/2 Running 0 25s
Set up State Store
Kratix uses GitOps to provision resources on the worker clusters. You can configure Kratix with multiple GitOps repositories by creating State Stores. Kratix supports Bucket State Store and Git State Store.
Using a Git State Store is recommended for production environments as it provides better security and version control. However, for development and testing purposes, you can also use the Bucket State Store.
If your are using local KinD clusters you can install MinIO or Gitea as an in-cluster State Store.
- Bucket (on KinD)
- Git (on KinD)
- Custom
# Install MinIO and register it as a BucketStateStore
kubectl apply --context $PLATFORM --filename https://raw.githubusercontent.com/syntasso/kratix/main/config/samples/minio-install.yaml
kubectl apply --context $PLATFORM --filename https://raw.githubusercontent.com/syntasso/kratix/main/config/samples/platform_v1alpha1_bucketstatestore.yaml
# Generate Gitea credentials and namespace
# Requires `gitea` CLI: https://docs.gitea.com/installation/install-from-binary
bash <(curl -s https://raw.githubusercontent.com/syntasso/kratix/refs/heads/main/scripts/generate-gitea-credentials.sh)
# Install Gitea and register it as a Git State Store
kubectl apply --context $PLATFORM --filename https://raw.githubusercontent.com/syntasso/kratix/main/hack/platform/gitea-install.yaml
kubectl apply --context $PLATFORM --filename https://raw.githubusercontent.com/syntasso/kratix/main/config/samples/platform_v1alpha1_gitstatestore.yaml
If your aren't using KinD clusters you will need to create your own State Store that is accessible by the platform and worker cluster. Follow the docs for creating State Stores.
Set up a worker cluster
Create worker cluster
If you are not using a pre-existing cluster, create your worker cluster locally using KinD:
kind create cluster --image kindest/node:v1.27.3 --name worker
# set WORKER to point to the worker cluster context
export WORKER="kind-worker"
If you are using your own pre-existing cluster, set the WORKER
environment
variable to the name of the kubectl context used to communicate to it.
Installing and Configuring a GitOps agent
Now that your Kubernetes Destination is created and Kratix is aware of it, the
last step is to install and configure a GitOps agent so that Kubernetes documents
that get written to the StateStore
are deployed to the cluster. Kratix is agnostic to
which GitOps agent you choose to use. See our GitOps Agent installation
documentation for configuring the GitOps agent of your choice.