Compound Promise
Compound Promises are Promises that, in its WCR, contain other Promises. That ability allows Platform teams deliver entire stacks on demand, instead of simple databases or services.
In this tutorial, you will
- encapsulate multiple Promises into a Compound Promise
- request a complete development environment through a Compound Promise
Pre-requisites
You need an installation of Kratix for this section. Click here for instructions
The simplest way to do so is by running the quick-start script from within the Kratix directory. The script will create two KinD clusters, install, and configure Kratix.
./scripts/quick-start.sh --recreate
You can run Kratix either with a multi-cluster or a single-cluster setup. The commands on the remainder of this document assume that two environment variables are set:
PLATFORM
representing the Platform cluster Kubernetes contextWORKER
representing the Worker cluster Kubernetes context
If you ran the quick-start script above, do:
export PLATFORM="kind-platform"
export WORKER="kind-worker"
For single cluster setups, the two variables should be set to the same value. You can find your cluster context by running:
kubectl config get-contexts
Refer back to Installing Kratix for more details.
Register the Platform as a Worker
To install a Compound Promises, the first step is to register the Platform cluster itself as an available Worker Cluster. That's because the WCR for the Compound Promises are Promises themselves, hence need to be scheduled to the Platform cluster.
Create a new Cluster document platform-cluster.yaml
with the
following contents:
apiVersion: platform.kratix.io/v1alpha1
kind: Cluster
metadata:
name: platform-cluster
labels:
environment: platform
spec:
id: platform-cluster
bucketPath: platform
Register the Cluster:
kubectl --context $PLATFORM apply --filename platform-cluster.yaml
Install and configure GitOps
For the Platform Cluster to behave like a Worker Cluster, you will need to install the
GitOps toolkit in it. The quickest way to do that is to run the ./scripts/install-gitops
script from the Kratix root directory:
cd /path/to/kratix
./scripts/install-gitops --context $PLATFORM --bucket-path platform
Install a Compound Promise
You can now install a "Paved Path" Promise:
kubectl --context $PLATFORM apply --filename https://raw.githubusercontent.com/syntasso/kratix/main/samples/paved-path-demo/paved-path-demo-promise.yaml
This Promise is composed of a Knative and Postgres. Installing the Promise on the Platform will have the following side-effects:
- Three Promises will be installed in the Platform Cluster: Paved Path, Knative and Postgres.
- The Knative and Postgres's WCR will be installed on the Worker Cluster.
To verify the installation was successful, run:
$ kubectl --context $PLATFORM get promises
NAME AGE
ha-postgres-promise 1h
knative-serving-promise 1h
paved-path-demo-promise 1h
$ kubectl --context $WORKER get pods -A
NAME READY STATUS RESTARTS AGE
postgres-operator-6c6dbd4459-kv5lw 1/1 Running 0 1h
$ kubectl --context $WORKER get crds | grep knative
certificates.networking.internal.knative.dev 2022-11-25T12:24:20Z
clusterdomainclaims.networking.internal.knative.dev 2022-11-25T12:24:20Z
...
Send a Resource Request
Platform users can now send Resource Requests for a new "Paved Path". That will create a new Knative Serving and a new Postgres database in the Worker Cluster:
kubectl --context $PLATFORM apply --filename https://raw.githubusercontent.com/syntasso/kratix/main/samples/paved-path-demo/paved-path-demo-resource-request.yaml
You can see the pipeline for the Paved Path Promise running, which will in turn trigger the Knative and Postgres pipelines:
$ kubectl --context $PLATFORM get pods
NAME READY STATUS RESTARTS AGE
request-pipeline-ha-postgres-promise-default-617a3 0/1 Completed 0 64s
request-pipeline-knative-serving-promise-default-e0157 0/1 Completed 0 64s
request-pipeline-paved-path-demo-promise-default-d3a89 0/1 Completed 0 87s
Eventually, the resources will be ready to be used:
$ kubectl --context $WORKER get pods -A
NAMESPACE NAME READY STATUS RESTARTS AGE
default acid-minimal-cluster-0 1/1 Running 0 1h
default acid-minimal-cluster-1 1/1 Running 0 1h
...
knative-serving activator-7d967fb5f4-4k4m5 1/1 Running 0 1h
knative-serving autoscaler-684b55df5f-7gw86 1/1 Running 0 1h
knative-serving controller-65866d54fc-zfh8d 1/1 Running 0 1h
knative-serving default-domain-dl972 0/1 Completed 0 1h
...
🎉 Congratulations: you have installed a Compound Promise and created an instance of the Paved Path!
A closer look in the Promise
Start by noticing the workerClusterResources
for the Paved Path Promise:
apiVersion: platform.kratix.io/v1alpha1
kind: Promise
metadata:
name: paved-path-demo-promise
spec:
clusterSelector:
environment: platform
workerClusterResources:
- apiVersion: platform.kratix.io/v1alpha1
kind: Promise
metadata:
name: knative-serving-promise
spec:
clusterSelector:
environment: dev
workerClusterResources:
# remainder of the knative promise
- apiVersion: platform.kratix.io/v1alpha1
kind: Promise
metadata:
name: ha-postgres-promise
spec:
clusterSelector:
environment: dev
workerClusterResources:
# remainder of the postgres promise ...
# remainder of the paved path promise...
Since Paved Path Promise WCRs are Promises, and considering that Kratix (and its CRDs) is only installed in the Platform Cluster, you need to ensure the WCR is applied exclusively to the Platform Cluster.
That is controlled by the clusterSelector
:
apiVersion: platform.kratix.io/v1alpha1
kind: Promise
metadata:
name: paved-path-demo-promise
spec:
clusterSelector:
environment: platform
workerClusterResources:
- # knative Promise
- # postgresPromise
# remainder of the paved path promise
The Paved Path Promise clusterSelector
is set to environment: platform
. That is
telling Kratix to install the sub-Promises into Clusters with a
environment: platform
label.
You may have noticed that, when registering the Platform Cluster, the Cluster definition included exactly that label. You can verify the applied labels with:
$ kubectl --context $PLATFORM get clusters.platform.kratix.io --show-labels
NAME AGE LABELS
platform-cluster 1hr environment=platform
worker-cluster-1 1hr environment=dev
However, the sub-Promises WCR (i.e. the Knative and Postgres WCR) should not be installed
in the Platform Cluster, but in the Worker Cluster. When you executed the quick start
script, it registered the Worker Cluster with a label environment: dev
(as
per output above). The clusterSelector
field in the sub-Promises are set to
exactly that:
apiVersion: platform.kratix.io/v1alpha1
kind: Promise
metadata:
name: paved-path-demo-promise
spec:
clusterSelector:
environment: platform
workerClusterResources:
- apiVersion: platform.kratix.io/v1alpha1
kind: Promise
metadata:
name: knative-serving-promise
spec:
clusterSelector:
environment: dev
workerClusterResources:
# remainder of the knative promise
- apiVersion: platform.kratix.io/v1alpha1
kind: Promise
metadata:
name: ha-postgres-promise
spec:
clusterSelector:
environment: dev
workerClusterResources:
# remainder of the postgres promise ...
# remainder of the paved path promise...
This configuration ensures the Knative CRDs and the Postgres Operator are installed exclusively in the Worker Cluster. This is how, when installing the Paved Path Promise, Kratix knew it should install the sub-Promises in the Platform Cluster and the sub-Promises dependencies in the Worker Cluster.
A closer look in the Pipeline
When a Resource Request is created, the Paved Path Pipeline is triggered. Usually, the output of the pipeline is a set of Kubernetes Resources that need to be created. For Compound Promises, that's usually a set of Resource Requests to be applied in the Platform itself.
The Paved Path Promise is a very basic example, but you can see that's exactly what the pipeline is doing in its Dockerfile.
🎉 Congratulations
✅ You have just installed and used your first Compound Promise.
👉 Let's see where to go from here.