Skip to main content

Google Kubernetes Engine (GKE)

info

This guide is for installing the latest OSS version of the Kratix project

Depending on your goals, you might instead want to:

Set up Platform Cluster​

Kratix has a very lightweight footprint, defaulting to 100m CPU and 256Mi memory within Kubernetes. The sizing of the underlying platform cluster is primarily driven by the level of concurrency you need to support, as each resource reconciliation runs its own Pod and consumes approximately 200m CPU and 256Mi memory.

For proof-of-value or initial deployments, we generally recommend starting with a cluster of at least 4 vCPUs and 16GiB of memory. This configuration provides sufficient headroom for Kratix to manage workloads effectively while allowing for meaningful parallelisation. As your usage grows, you can scale the cluster vertically to accommodate increased demand.

Start by setting the key variables in your terminal. These should match any pre-existing cluster you plan to use, else they will be used to create one for you:

export GCP_PLATFORM_CLUSTER_NAME=
export GCP_ZONE=
export GCP_PROJECT_NAME=

If you are not using a pre-existing cluster, create a default GKE Platform Cluster by running:

gcloud container clusters create ${GCP_PLATFORM_CLUSTER_NAME} --zone ${GCP_ZONE} --project "${GCP_PROJECT_NAME}"
info

If you want other configurations set, please follow the GKE getting started docs.

Once a GKE cluster is ready for use, use the command below to authorize to the cluster:

gcloud container clusters get-credentials "${GCP_PLATFORM_CLUSTER_NAME}" --zone "${GCP_ZONE}" --project "${GCP_PROJECT_NAME}"
kubectl config current-context
export PLATFORM=$(kubectl config current-context)

Set up Kratix​

warning

These instructions are intended for teams preparing to install Kratix in semi-permanent or permanent environments.

If you are just getting started and have access to a disposable/empty cluster we highly recommend you get started with the quick start instructions which can be used on all Kubernetes clusters and configures a Kratix and its first Destination and State Store backed by MinIO which is configured for learning but is not robust or durable enough for production use.

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 CA certificates and key/cert pairs for the Kratix webhook and Metrics Services.

Webhook Service​

You will need to generate a CA Certificate and key/cert pair 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:
...

Metrics Service​

You will need to generate a CA Certificate and key/cert pair for the following DNS names:

  • kratix-platform-controller-manager-metrics-service.kratix-platform-system.svc
  • kratix-platform-controller-manager-metrics-service.kratix-platform-system.svc.cluster.local

To manually provide the required certificates, you need to create the metrics-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: metrics-server-cert
  namespace: kratix-platform-system
type: kubernetes.io/tls

This secret is referenced in the kratix-platform-controller-manager Deployment.

Lastly, you need to remove the following cert-manager Certificate from Kratix release manifest:

---
...
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: kratix-platform-metrics-server-cert
  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

Configure a Destination and State Store​

Once Kratix is installed, you will want to configure a Destination it can schedule your workflow outputs to and a State Store to store that Destination's content.

For generic instructions, please visit the State Store and Destination pages.

To use a GCP Bucket as your State Store, you can refer to the Kratix Examples repository which provides easy install scripts.

Configuring Metrics Collection​

The Kratix Metrics Service emits a default set of metrics which detail the Kratix Controller's performance as a whole. These can be collected via Prometheus-compatible scraping.

Prometheus is not installed with Kratix so you'll first need to install the Prometheus Operator on your cluster. Once installed, you can create a Service Monitor to scrape metrics from the kratix-platform-controller-manager-metrics-service Metrics Service:

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  labels:
    control-plane: controller-manager
    release: prometheus
  name: prometheus-kube-kratix-prometheus
  namespace: kratix-platform-system
spec:
  endpoints:
    - path: /metrics
      port: https
      scheme: https
      bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
      tlsConfig:
        serverName: kratix-platform-controller-manager-metrics-service.kratix-platform-system.svc
        ca:
          secret:
            name: metrics-server-cert
            key: "tls.crt"
  namespaceSelector:
    matchNames:
      - kratix-platform-system
  selector:
    matchLabels:
      control-plane: controller-manager
note

The Service Monitor must be created in the same Namespace as the metrics-server-cert Secret.