diff --git a/docs/_partials/installation/_install-check-flux-and-finish.mdx b/docs/_partials/installation/_install-check-flux-and-finish.mdx
index 2024ae29..a08543de 100644
--- a/docs/_partials/installation/_install-check-flux-and-finish.mdx
+++ b/docs/_partials/installation/_install-check-flux-and-finish.mdx
@@ -3,11 +3,9 @@ to receive workloads. You can verify its readiness by observing the `kratix-work
namespace appearing in the `worker` cluster:
```shell-session
-$ kubectl --context $WORKER get namespaces
+$ kubectl --context $WORKER get namespace kratix-worker-system
NAME STATUS AGE
-...
kratix-worker-system Active 1m
-...
```
🎉 **Congratulations!** Kratix is now installed! Jump to [Installing and using a Promise](installing-a-promise) to spin up your first as-a-service offering.
diff --git a/docs/workshop/part-i/01-installing-kratix.md b/docs/workshop/part-i/01-installing-kratix.md
index 4b098259..fb999f3b 100644
--- a/docs/workshop/part-i/01-installing-kratix.md
+++ b/docs/workshop/part-i/01-installing-kratix.md
@@ -103,6 +103,7 @@ Check the Kubernetes documentation for further details on [Custom
Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
and [Custom Resources
Definition](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/).
+
Verify the Kratix deployment:
@@ -353,7 +354,7 @@ through similar steps you ran during the worker cluster Destination registration
There's a script in the `kratix` directory that will do exactly that. This script replicates the setup you performed previously in the [Destination setup](./installing-kratix#destination-setup) section. Run:
```bash
-./scripts/register-destination --name platform-cluster --context $PLATFORM --state-store default --strict-match-labels
+./scripts/register-destination --name platform-cluster --context $PLATFORM --state-store default --strict-match-labels --with-label environment=platform
```
The platform cluster should now be registered with Kratix and ready to receive
@@ -364,6 +365,7 @@ kubectl --context $PLATFORM get destinations
```
The above command will give an output similar to:
+
```shell-session
NAME AGE
platform-cluster 1m
@@ -377,6 +379,7 @@ kubectl --context $PLATFORM get namespaces --watch
```
The above command will give an output similar to:
+
```shell-session
NAME STATUS AGE
...
@@ -402,5 +405,6 @@ To recap the steps you took:
1. ✅ Told Kratix about the worker and platform clusters, as Destinations
## 🎉 Congratulations
+
✅ Kratix is now installed and configured!
👉🏾 [Next you will deploy your first Promise](./installing-a-promise).
diff --git a/docs/workshop/part-i/02-installing-a-promise.md b/docs/workshop/part-i/02-installing-a-promise.md
index 6fd44a8d..353ed8b8 100644
--- a/docs/workshop/part-i/02-installing-a-promise.md
+++ b/docs/workshop/part-i/02-installing-a-promise.md
@@ -44,21 +44,14 @@ minio 1/1 1 1 1h
You should also have a `kratix-worker-system` namespace in your worker cluster:
```bash
-kubectl --context $WORKER get namespaces
+kubectl --context $WORKER get namespace kratix-worker-system
```
The above command will give an output similar to:
```shell-session
NAME STATUS AGE
-default Active 41m
-flux-system Active 39m
-//highlight-next-line
kratix-worker-system Active 35m
-kube-node-lease Active 41m
-kube-public Active 41m
-kube-system Active 41m
-local-path-storage Active 41m
```
If your outputs do not align with the above, please refer back to
diff --git a/docs/workshop/part-i/03-multiple-promise.md b/docs/workshop/part-i/03-multiple-promise.md
index 929aa692..4844f304 100644
--- a/docs/workshop/part-i/03-multiple-promise.md
+++ b/docs/workshop/part-i/03-multiple-promise.md
@@ -4,6 +4,7 @@ title: Using Compound Promises
id: multiple-promises
slug: ../multiple-promises
---
+
```mdx-code-block
import CompoundPromiseDiagram from "/img/docs/workshop/compound-promise-diagram.svg"
import PavedPathDiagram from "/img/docs/workshop/compound-promise-paved-path-diagram.svg"
@@ -75,14 +76,14 @@ kubectl --context $PLATFORM get pods --namespace kratix-platform-system
```
The above command will give an output similar to:
+
```shell-session
NAME READY STATUS RESTARTS AGE
kratix-platform-controller-manager-7cc49f598b-zqkmz 2/2 Running 0 4h4m
-minio-6f75d9fbcf-jpstv 1/1 Running 0 4h4m
```
-If the command above display a different output, please refer back to previous
-guides.
+If the command above does not include a ready kratix-platform-controller-manager,
+please refer back to previous guides.
### Install the Promise
@@ -114,82 +115,104 @@ kubectl --context $PLATFORM get promises --watch
The above command will eventually include the following output:
```shell-session
+easyapp Unavailable EasyApp example.promise.syntasso.io/v1
+easyapp Unavailable EasyApp example.promise.syntasso.io/v1
+easyapp Unavailable EasyApp example.promise.syntasso.io/v1
easyapp Available EasyApp example.promise.syntasso.io/v1
```
-Once you see the "Available", press Ctrl+C to
-exit the watch mode.
+Once the EasyApp promise becomes "Available", you should see the sub-Promises
+getting automatically installed. If you haven't killed the watch command, you
+should see the following output appearing:
-At this point, you may be asking yourself: _"Wait, wasn't the EasyApp Promise supposed to install three Promises? Why is there only one?"_
-
-That's because the EasyApp Promise makes use of the Kratix _Destination Selectors_ feature.
+```shell-session
+nginx-ingress
+postgresql
+nginx-ingress Unavailable deployment marketplace.kratix.io/v1alpha1
+postgresql Unavailable postgresql marketplace.kratix.io/v1alpha1
+...
+nginx-ingress Available deployment marketplace.kratix.io/v1alpha1
+postgresql Available postgresql marketplace.kratix.io/v1alpha1
+```
-Destination Selectors allow Promises to specify scheduling logic to determine the suitable Destinations for hosting Dependencies and workloads.
+Once all promises are "Available", press Ctrl+C to
+exit the watch mode.
-You can verify the EasyApp Destination Selector by describing the Promise:
+The dependencies for the sub-Promises, on the other hands, are installed on the Worker
+destination. You can validate that by checking the deployments on the Worker:
```bash
-kubectl --context $PLATFORM describe promise easyapp | tail -n 30 | \
- grep "Destination Selectors" --after-context 2 --max-count 1
+kubectl --context $WORKER get deployments --watch
```
-The above command will give an output similar to:
+The above command will give an output similar to (it may take a few minutes for
+it to appear and to start):
+
```shell-session
-Destination Selectors:
- Match Labels:
- Environment: platform
+NAME READY UP-TO-DATE AVAILABLE AGE
+nginx-nginx-ingress 1/1 1 1 1m
+postgres-operator 1/1 1 1 1m
```
-This means the EasyApp Promise is telling Kratix:
+When the deployments eventually complete, press Ctrl+C to exit.
+
+## Understanding Destination Selectors
+
+You may be asking yourself: how did Kratix know it should install the
+sub-promises on the Platform cluster? And how did it know to install the NGINX
+and the PostgreSQL Promises dependencies on the Worker cluster?
+
+The answer is: **Destination Selectors**.
-> Only install my Dependencies (i.e., the NGINX and the PostgreSQL Promises) in
-> Destinations with the **label environment=platform**.
+Destination Selectors are a powerful feature in Kratix that allows Promises to
+specify where their dependencies and resources should be scheduled to. Similar
+to how Kubernetes uses labels to select resources, Kratix uses Destination
+Selectors to select Destinations.
-Check the registered Destinations again, but this time ask `kubectl` to also show the Destination labels:
+You can verify the EasyApp Destination Selectors by describing the Promise:
```bash
-kubectl --context $PLATFORM get destinations --show-labels
+kubectl --context $PLATFORM describe promise easyapp | tail -n 30 | \
+ grep "Destination Selectors" --after-context 2 --max-count 1
```
The above command will give an output similar to:
+
```shell-session
-NAME AGE LABELS
-platform-cluster 10m
-worker-cluster 1h environment=dev
+Destination Selectors:
+ Match Labels:
+ Environment: platform
```
-
+> Only install the EasyApp Dependencies (i.e., the NGINX and the PostgreSQL
+> Promises) in Destinations with the **label environment=platform**.
-Note that the platform cluster is missing the required label. Adding the missing
-label should cause the system to converge to the desired state:
+So, on the Platform Destination, you should have a label `environment=platform`. Verify:
```bash
-kubectl --context $PLATFORM label destination platform-cluster environment=platform; \
-kubectl --context $PLATFORM get promises --watch
+kubectl --context $PLATFORM get destination platform-cluster --show-labels
```
-The above command will eventually converge to an output similar to:
+The above command will give an output similar to:
+
```shell-session
-NAME STATUS KIND API VERSION VERSION
-easyapp Available EasyApp example.promise.syntasso.io/v1
-nginx-ingress Available deployment marketplace.kratix.io/v1alpha1
-postgresql Available postgresql marketplace.kratix.io/v1alpha1
+NAME AGE LABELS
+platform-cluster 1h environment=platform
```
-Once you see the expected three Promises, press Ctrl+C to
-exit the watch mode.
-
-Once the sub-Promises are installed, their Dependencies will be scheduled to a
-Destination. The EasyApp sub-Promises are also declaring a Destination Selector.
-Verify:
+That explains why the NGINX and the PostgreSQL Promises were installed on the
+Platform cluster. But how did the dependencies of those Promises end up on the
+Worker cluster?
+
+Once again, Destination Selectors are the answer. Check the destination
+selectors defined in the NGINX and the PostgreSQL Promises:
```bash
kubectl --context $PLATFORM describe promise nginx-ingress | grep "Destination Selectors:" -A 2 -m 1
@@ -197,6 +220,7 @@ kubectl --context $PLATFORM describe promise postgresql | grep "Destination Sele
```
The above command will give an output similar to:
+
```shell-session
Destination Selectors:
Match Labels:
@@ -208,37 +232,21 @@ The NGINX and the PostgreSQL Promises are telling Kratix:
> Only install my Dependencies (which include, the NGINX Ingress Controller and the
> PostgreSQL operator) in Destinations with the **label environment=dev**.
-As you may have noted before, the worker cluster is already labelled correctly.
-Verify:
+Similarly, if you check the Worker Destination, you should see the label
+`environment=dev`:
```bash
kubectl --context $PLATFORM get destination worker-cluster --show-labels
```
The above command will give an output similar to:
+
```shell-session
NAME AGE LABELS
worker-cluster 1h environment=dev
```
-Since the worker Destination includes the label, the NGINX and PostgreSQL Promise
-Dependencies should be getting installed into the worker cluster. Verify:
-
-```bash
-kubectl --context $WORKER get deployments --watch
-```
-
-The above command will give an output similar to (it may take a few minutes for
-it to appear and to start):
-
-```shell-session
-NAME READY UP-TO-DATE AVAILABLE AGE
-nginx-nginx-ingress 1/1 1 1 1m
-postgres-operator 1/1 1 1 1m
-```
-
-When the deployments eventually complete, press Ctrl+C to
-exit.
+The entire installation process is summarised in the diagram below:
-Platform users can go ahead and start using the Promises!
:::info Managing a Fleet of Destinations
@@ -264,6 +271,7 @@ If you are curious to learn more about Kratix scheduling, check the
:::
+Your Platform is now ready to deploy EasyApps!
## Request an EasyApp
@@ -275,6 +283,7 @@ kubectl --context $PLATFORM get promises
```
The above command will give an output similar to:
+
```shell-session
NAME STATUS KIND API VERSION VERSION
easyapp Available EasyApp example.promise.syntasso.io/v1
@@ -305,6 +314,7 @@ EOF
```
The above command will give an output similar to:
+
```shell-session
easyapp.example.promise.syntasso.io/example created
```
@@ -313,7 +323,6 @@ The EasyApp Promise will take that request and generate the necessary
requests for the sub-Promises, wiring up the application to the Postgres
service.
-