Kratix Ep 4: Core Concepts Deep Dive (How-To)

1. The Anatomy of a Promise (HOW)

#

To create a new, self-service API in Kratix, we must author a Kubernetes Custom Resource of kind: Promise.

This action is the exclusive responsibility of the Platform Engineer (WHO), and it is executed solely on the Platform Cluster (WHERE).

Create a new file in your terminal named promise-redis.yaml:

apiVersion: platform.kratix.io/v1alpha1
kind: Promise
metadata:
  name: redis
spec:
  # 1. The API (What the Application Developer sees)
  api:
    apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    metadata:
      name: redis.marketplace.acmecorp.com
    spec:
      group: marketplace.acmecorp.com
      names:
        kind: Redis
        plural: redis
      versions:
        - name: v1alpha1
          served: true
          storage: true
          schema:
            openAPIV3Schema:
              type: object
              properties:
                spec:
                  type: object
                  properties:
                    size:
                      type: string
                      enum: ["small", "medium", "large"]
                    environment:
                      type: string
                      enum: ["dev", "staging", "prod"]
                  required:
                    - size
                    - environment

  # 2. The Dependencies (What is installed globally on the Worker Clusters)
  dependencies:
    - apiVersion: v1
      kind: Namespace
      metadata:
        name: redis-system

  # 3. The Workflows (The Pipeline container definition)
  workflows:
    resource:
      configure:
        - apiVersion: platform.kratix.io/v1alpha1
          kind: Pipeline
          metadata:
            name: redis-pipeline
          spec:
            containers:
              - name: pipeline
                image: docker.io/acmecorp/redis-pipeline:v1

Let’s break down exactly what happens under the hood when you run kubectl apply -f promise-redis.yaml on the Platform Cluster.

2. Block 1: The API (CRD)

#

The api block is literally just a standard Kubernetes Custom Resource Definition (CRD) nested directly inside the Promise YAML.

When you apply the Promise, Kratix extracts this block and dynamically installs the CRD into the Platform Cluster.

This action instantly generates the Redis API for your Application Developers. Because we meticulously defined the openAPIV3Schema, the Kubernetes API server itself will act as our bouncer. It will automatically enforce that the E-Commerce developer must provide a size of small, medium, or large.

If a junior developer makes a typo and submits size: gigantic, the Kubernetes API will reject it instantly with a 400 Bad Request error, long before Kratix even attempts to process it. This strict validation is crucial for building a reliable, production-grade IDP that doesn’t silently fail.

3. Block 2: Dependencies

#

Sometimes, an application requires prerequisite, static infrastructure to exist on the Worker cluster before the application itself can be deployed.

In our Redis example, we are telling Kratix to ensure that a Kubernetes Namespace called redis-system exists.

Kratix treats dependencies as Static State. As soon as the Promise is installed into the Platform Cluster, Kratix immediately pushes this Namespace YAML to the State Store (the Git repository). This ensures the namespace is deployed to every matching Worker cluster immediately, preparing them for future Redis requests. You can put anything in the dependencies block: Roles, RoleBindings, NetworkPolicies, or even base ConfigMaps that all Redis instances will need to share.

4. Block 3: The Workflows (Pipelines)

#

This is the undisputed brain of the operation.

When an E-Commerce developer submits a Redis Claim (e.g., requesting size: large), Kratix needs to know how to translate that abstract request into actual, functional Kubernetes Deployment YAML.

Kratix achieves this by booting a Pipeline Container. In our YAML, we instructed Kratix to boot docker.io/acmecorp/redis-pipeline:v1.

How the Pipeline Container Works

#

You (the Platform Engineer) must write the code for this Docker image, build it, and push it to a registry beforehand.

When Kratix boots your container, it creates an isolated environment and mounts two specific directories into it:

1. /kratix/input/: Kratix automatically places a JSON file here representing the Developer’s Claim (e.g., {"spec": {"size": "large", "environment": "dev"}}).
2. /kratix/output/: An entirely empty directory.

Your container (which can be written in a Python script, a Bash script, or a compiled Go binary) simply reads the JSON from the input folder, executes whatever business logic you desire, generates the required Kubernetes YAML (like a StatefulSet and a Service), and writes that generated YAML into the /kratix/output/ directory.

When your container finishes its work and exits with a 0 (Success) status code, Kratix grabs all the YAML files located in /kratix/output/ and commits them directly to Git!

5. Targeting Worker Clusters (Destinations)

#

By default, when your pipeline generates YAML and exits successfully, Kratix will push that YAML to every single Worker cluster registered in the system.

In a production environment, this is almost never what you want. You want the developer to be able to explicitly choose the environment (Dev, Staging, or Prod), and you want the YAML to only land on the cluster that matches that environment.

To solve this routing problem, we must add a destinationSelectors block to our Promise. This block allows the Promise to filter which Worker clusters are allowed to receive the output based on Kubernetes labels.

Let’s modify our Promise YAML to include routing logic based on the developer’s claim:

spec:
  # ... (api, dependencies, workflows)
  
  # Tell Kratix how to route the output!
  destinationSelectors:
    - matchLabels:
        # We can dynamically route based on the developer's request!
        environment: dev

While hardcoding environment: dev works for testing, Kratix actually allows you to write Pipeline scripts that dynamically set the Destination based on the environment parameter the developer provided in their input JSON.

When the routing is properly configured, Kratix will evaluate all connected Worker clusters, find the one with the matching environment label, and commit the generated YAML exclusively to that specific Git repository folder.

Conclusion & Next Steps

#

You now possess a deep understanding of the anatomy of a Kratix Promise. You have seen how it defines the frontend API that developers interact with, the static dependencies that prep the worker clusters, the dynamic pipeline logic that generates the workloads, and the multi-cluster routing selectors that ensure the workloads land in the correct geographical or environmental location.

But how do those Worker clusters actually retrieve the YAML from Git? We have repeatedly mentioned “ArgoCD” and “GitOps” in the previous architectural episodes, but we haven’t actually executed the configuration yet.

In Episode 5: ArgoCD GitOps Integration, we will leave the safety of the Platform Cluster and focus entirely on the Worker Cluster. We will execute the exact terminal commands required to configure ArgoCD to connect to the Kratix State Store and synchronize our Redis payloads automatically, closing the deployment loop.