Kratix Cheat Sheet

Overview

Kratix is an open-source framework by Syntasso that enables platform teams to build internal developer platforms on Kubernetes using a declarative, API-driven approach. It introduces the concept of “Promises” — composable building blocks that define what a platform offers (such as databases, message queues, or entire environments) and how those offerings are fulfilled. When developers request a resource through a Promise, Kratix orchestrates the provisioning across one or more Kubernetes clusters using GitOps-based state management.

Kratix follows a platform-as-a-product philosophy where the platform team curates a marketplace of self-service capabilities and developers consume them through simple resource requests. The framework handles multi-cluster scheduling, resource lifecycle management, and pipeline-based customization (validation, mutation, security scanning) of requested resources. This enables organizations to encode their best practices, compliance requirements, and infrastructure patterns into reusable, self-service building blocks.

Installation

Install Kratix

# Install Kratix on the platform cluster
kubectl apply --filename https://github.com/syntasso/kratix/releases/latest/download/kratix.yaml

# Verify installation
kubectl get pods -n kratix-platform-system
kubectl get crds | grep kratix

# Expected CRDs:
# promises.platform.kratix.io
# works.platform.kratix.io
# workplacements.platform.kratix.io
# destinations.platform.kratix.io

Install with Helm

# Add Kratix Helm repo
helm repo add kratix https://syntasso.github.io/helm-charts
helm repo update

# Install Kratix
helm install kratix kratix/kratix \
  --namespace kratix-platform-system \
  --create-namespace

# Verify
kubectl get pods -n kratix-platform-system

Register a Worker Cluster (Destination)

# Register a worker/destination cluster using GitOps (Flux)
cat <<EOF | kubectl apply -f -
apiVersion: platform.kratix.io/v1alpha1
kind: Destination
metadata:
  name: worker-cluster-1
  labels:
    environment: production
    region: us-east
spec:
  stateStoreRef:
    name: default-state-store
    kind: GitStateStore
EOF

# Create GitStateStore for state management
cat <<EOF | kubectl apply -f -
apiVersion: platform.kratix.io/v1alpha1
kind: GitStateStore
metadata:
  name: default-state-store
spec:
  url: https://github.com/org/platform-state.git
  branch: main
  secretRef:
    name: git-credentials
EOF

# Create git credentials secret
kubectl create secret generic git-credentials \
  --from-literal=username=git-user \
  --from-literal=password=git-token

# Or use BucketStateStore for S3-based state
cat <<EOF | kubectl apply -f -
apiVersion: platform.kratix.io/v1alpha1
kind: BucketStateStore
metadata:
  name: s3-state-store
spec:
  endpoint: s3.amazonaws.com
  bucketName: kratix-platform-state
  region: us-east-1
  secretRef:
    name: s3-credentials
  insecure: false
EOF

Core Concepts — Promises

Creating a Promise

# postgres-promise.yaml — Self-service PostgreSQL
apiVersion: platform.kratix.io/v1alpha1
kind: Promise
metadata:
  name: postgresql
spec:
  # What developers request (the API)
  api:
    apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    metadata:
      name: postgresqls.database.example.com
    spec:
      group: database.example.com
      names:
        kind: PostgreSQL
        plural: postgresqls
        singular: postgresql
      scope: Namespaced
      versions:
        - name: v1
          served: true
          storage: true
          schema:
            openAPIV3Schema:
              type: object
              properties:
                spec:
                  type: object
                  properties:
                    size:
                      type: string
                      enum: ["small", "medium", "large"]
                      default: "small"
                    version:
                      type: string
                      default: "15"
                    highAvailability:
                      type: boolean
                      default: false
                  required: ["size"]

  # Shared dependencies installed on worker clusters
  dependencies:
    - apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: postgresql-operator
        namespace: postgres-system
      spec:
        replicas: 1
        selector:
          matchLabels:
            app: postgres-operator
        template:
          metadata:
            labels:
              app: postgres-operator
          spec:
            containers:
              - name: operator
                image: registry.example.com/postgres-operator:v1.10.0

  # Pipeline to transform requests into resources
  workflows:
    resource:
      configure:
        - apiVersion: platform.kratix.io/v1alpha1
          kind: Pipeline
          metadata:
            name: configure-postgres
          spec:
            containers:
              - name: generate-resources
                image: registry.example.com/postgres-promise-pipeline:v1.0.0

# Install the Promise on the platform cluster
kubectl apply -f postgres-promise.yaml

# Verify Promise is installed
kubectl get promises
kubectl get crds | grep postgresql

Pipeline Container (Resource Generator)

#!/bin/bash
# pipeline.sh — Runs inside the pipeline container
# Kratix provides the resource request at /kratix/input/object.yaml
# Write output resources to /kratix/output/

# Read the request
REQUEST=$(cat /kratix/input/object.yaml)
NAME=$(echo "$REQUEST" | yq '.metadata.name')
NAMESPACE=$(echo "$REQUEST" | yq '.metadata.namespace')
SIZE=$(echo "$REQUEST" | yq '.spec.size')
VERSION=$(echo "$REQUEST" | yq '.spec.version')
HA=$(echo "$REQUEST" | yq '.spec.highAvailability')

# Map sizes to resource specs
case "$SIZE" in
  small)  CPU="500m"; MEM="1Gi"; STORAGE="10Gi"; REPLICAS=1 ;;
  medium) CPU="1";    MEM="4Gi"; STORAGE="50Gi"; REPLICAS=1 ;;
  large)  CPU="2";    MEM="8Gi"; STORAGE="100Gi"; REPLICAS=3 ;;
esac

if [ "$HA" = "true" ]; then
  REPLICAS=3
fi

# Generate the PostgreSQL cluster resource
cat > /kratix/output/postgres-cluster.yaml <<EOF
apiVersion: acid.zalan.do/v1
kind: postgresql
metadata:
  name: ${NAME}
  namespace: ${NAMESPACE}
  labels:
    managed-by: kratix
    promise: postgresql
spec:
  teamId: ${NAMESPACE}
  numberOfInstances: ${REPLICAS}
  postgresql:
    version: "${VERSION}"
  volume:
    size: ${STORAGE}
  resources:
    requests:
      cpu: ${CPU}
      memory: ${MEM}
EOF

# Generate connection secret
cat > /kratix/output/connection-info.yaml <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: ${NAME}-connection-info
  namespace: ${NAMESPACE}
data:
  host: "${NAME}.${NAMESPACE}.svc.cluster.local"
  port: "5432"
  database: "${NAME}"
EOF

echo "Pipeline completed for PostgreSQL: $NAME (size: $SIZE, HA: $HA)"

Requesting Resources (Developer Experience)

# Developer requests a PostgreSQL database
cat <<EOF | kubectl apply -f -
apiVersion: database.example.com/v1
kind: PostgreSQL
metadata:
  name: my-app-db
  namespace: team-alpha
spec:
  size: medium
  version: "15"
  highAvailability: true
EOF

# Check request status
kubectl get postgresqls -n team-alpha
kubectl describe postgresql my-app-db -n team-alpha

# List all available Promises (what can I request?)
kubectl get promises

# Delete a resource (triggers cleanup)
kubectl delete postgresql my-app-db -n team-alpha

Configuration

Multi-Cluster Scheduling

# Promise with destination selectors
apiVersion: platform.kratix.io/v1alpha1
kind: Promise
metadata:
  name: postgresql
spec:
  destinationSelectors:
    - matchLabels:
        environment: production
        has-ssd: "true"
  # ... rest of promise spec

# Label destinations for scheduling
kubectl label destination worker-cluster-1 environment=production has-ssd=true
kubectl label destination worker-cluster-2 environment=staging

# Resource request can also specify destination preferences
cat <<EOF | kubectl apply -f -
apiVersion: database.example.com/v1
kind: PostgreSQL
metadata:
  name: staging-db
  namespace: team-alpha
  labels:
    kratix.io/destination-selectors: "environment=staging"
spec:
  size: small
EOF

Pipeline with Multiple Stages

# Multi-stage pipeline with validation and generation
workflows:
  resource:
    configure:
      - apiVersion: platform.kratix.io/v1alpha1
        kind: Pipeline
        metadata:
          name: validate-and-configure
        spec:
          containers:
            # Stage 1: Validate the request
            - name: validate
              image: registry.example.com/postgres-validator:v1.0.0
            
            # Stage 2: Security scan
            - name: security-check
              image: registry.example.com/security-scanner:v1.0.0
            
            # Stage 3: Generate resources
            - name: generate
              image: registry.example.com/postgres-generator:v1.0.0
            
            # Stage 4: Add monitoring
            - name: add-monitoring
              image: registry.example.com/monitoring-sidecar:v1.0.0

    # Delete pipeline (cleanup when resource is removed)
    delete:
      - apiVersion: platform.kratix.io/v1alpha1
        kind: Pipeline
        metadata:
          name: cleanup-postgres
        spec:
          containers:
            - name: cleanup
              image: registry.example.com/postgres-cleanup:v1.0.0

Advanced Usage

Compound Promises

# A Promise that bundles multiple sub-promises
apiVersion: platform.kratix.io/v1alpha1
kind: Promise
metadata:
  name: web-application-environment
spec:
  api:
    apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    metadata:
      name: webapps.platform.example.com
    spec:
      group: platform.example.com
      names:
        kind: WebApp
        plural: webapps
      scope: Namespaced
      versions:
        - name: v1
          served: true
          storage: true
          schema:
            openAPIV3Schema:
              type: object
              properties:
                spec:
                  type: object
                  properties:
                    name:
                      type: string
                    tier:
                      type: string
                      enum: ["basic", "standard", "premium"]

  # Dependencies: install sub-operators on worker clusters
  dependencies:
    - apiVersion: platform.kratix.io/v1alpha1
      kind: Promise
      metadata:
        name: postgresql
    - apiVersion: platform.kratix.io/v1alpha1
      kind: Promise
      metadata:
        name: redis

  workflows:
    resource:
      configure:
        - apiVersion: platform.kratix.io/v1alpha1
          kind: Pipeline
          metadata:
            name: provision-webapp-environment
          spec:
            containers:
              - name: generate
                image: registry.example.com/webapp-env-generator:v1.0.0

GitOps State Store Configuration

# Verify state store connectivity
kubectl get gitstatestore -o yaml
kubectl get bucketstatestores -o yaml

# Check work placements
kubectl get workplacements -A
kubectl get works -A

# Debug state store sync
kubectl logs -n kratix-platform-system deploy/kratix-platform-controller-manager --tail=50

Troubleshooting

Issue	Cause	Solution
Promise not creating CRD	API schema validation error	Check OpenAPI schema in Promise spec
Pipeline stuck	Container image pull failure	Verify image registry access and image tags
Resources not appearing on worker	State store sync failure	Check GitStateStore credentials and repo access
Destination not receiving work	Label selectors don’t match	Verify destination labels match Promise selectors
Dependencies not installed	Worker cluster not connected	Check Flux/ArgoCD sync on worker cluster
Delete pipeline not running	Finalizer not set	Ensure Promise has delete workflow configured
Resource request rejected	Schema validation failure	Check request matches Promise API schema
Multiple Promises conflict	CRD naming collision	Use unique group names per Promise

# Debug Kratix controller
kubectl logs -n kratix-platform-system deploy/kratix-platform-controller-manager --tail=100

# Check Promise status
kubectl describe promise postgresql

# View pipeline job logs
kubectl get jobs -A | grep kratix
kubectl logs job/configure-postgres-pipeline-xxxxx

# Check works and placements
kubectl get works -A -o wide
kubectl get workplacements -A -o wide

# Verify destinations
kubectl get destinations -o wide

# Check resource request status
kubectl get postgresqls -A -o yaml | grep -A5 status