feat: add path to all destinations (#188)

Co-authored-by: Sapphire Mason-Brown <[email protected]>

Author: kirederik

docs/_partials/_writing-a-promise.md

@@ -773,4 +773,4 @@ kubectl --context $WORKER get pods
 ## 🎉   Congratulations!
 
 ✅&nbsp;&nbsp; You have written a Kratix Promise. <br />
-👉🏾&nbsp;&nbsp; Let's [add a new Worker](./scheduling).
+👉🏾&nbsp;&nbsp; Let's [add a new Destination](./new-destination).

docs/main/03-reference/13-destinations/01-destinations.md

@@ -39,11 +39,12 @@ metadata:
   labels:
     environment: dev
 spec:
-  # Destination identifier: optional, appended path to be used within the State Store
+  # Path within the State Store to write to.
+  # Optional, defaults to the name of the Destination.
+  # To write straight to the root of the State Store, set it to `/`.
   path: path/in/statestore
 
-  # Optional, defaults to false
-
+  # Optional, defaults to false.
   # By default, Kratix will schedule workloads for Promises without
   #   `destinationSelectors` to all available Destinations.
   # If this property is set to true, Kratix will only schedule Workloads
@@ -73,41 +74,31 @@ spec:
     kind: BucketStateStore
 ```
 
-When a new Destination is registered in the platform cluster (i.e., a new Destination resource is
-created), Kratix will write to two paths in the [State
-Store](../statestore/intro):
-one for `resources`, one for `dependencies`. The path within the `State Store` follows the following pattern:
+When a new Destination is created in the platform cluster, Kratix will write to
+two paths in the [State Store](../statestore/intro): one for `resources`, one
+for `dependencies`. The path within the `State Store` follows the pattern:
 
 For `dependencies`:
 
-```yaml
+```
 statestore.Spec.Path/
     destination.Spec.Path/
-        destination.Name/
-            dependencies/
-                promise.Name/
+        dependencies/
+            promise.Name/
 ```
 
 For `resources`:
 
-```yaml
+```
 statestore.Spec.Path/
     destination.Spec.Path/
-        destination.Name/
-            resources/
-                resource.Namespace/
-                    promise.Name/
-                        resource.Namespace/
-```
-
-For example installing and requesting from a Promise that provides `Redis` as a service you would get:
-
-```bash
-worker-cluster/dependencies/redis/static/dependencies.yaml
-worker-cluster/resources/default/redis/my-request/redis.yaml
+        resources/
+            resource.Namespace/
+                promise.Name/
+                    resource.Namespace/
 ```
 
-For example:
+For example, for the following configuration:
 
 ```yaml
 ---
@@ -137,18 +128,18 @@ spec:
     kind: BucketStateStore
 ```
 
-The above configuration would result in the following paths being written to:
-
-- `destinations/dev/default/worker-1/dependencies/`
-- `destinations/dev/default/worker-1/resources/`
+The following directories would be created in the State Store:
 
-<br/>
+- `destinations/dev/default/dependencies/`
+- `destinations/dev/default/resources/`
 
-The paths should be used when setting up the workers to pull
-down from the `StateStore`.
+Kratix will, by default, write to unique directories within those paths depending on the
+Promise or Resource being requested. You can stop this behaviour by setting the `filepath.mode` to `none`.
 
 :::info
 
-The reason for two directories is that GitOps applies require any prerequisite workloads like CRDs to be ready before any dependent workloads are applied. By dividing the two directories you can configure your GitOps tool to manage this for you.
+Pre-requisites, like CRDs, are written to the `dependencies` subdirectory. This setup is
+often required by GitOps tools to ensure that all dependencies are ready before the
+resources themselves are applied.
 
 :::

docs/main/03-reference/13-destinations/02-multidestination-management.md

@@ -18,7 +18,7 @@ In Kratix, scheduling happens in two stages:
    ([Scheduling Workloads](#resources))
 
 The following sections on this page document those stages. For hands-on scheduling guides,
-check the [Adding a new Destination](../../guides/scheduling) and [Compound
+check the [Adding a new Destination](../../guides/new-destination) and [Compound
 Promises](../../guides/compound-promises) pages.
 
 ## Scheduling Promises {#promises}
@@ -176,13 +176,13 @@ With the following `/kratix/metadata/destination-selectors.yaml`:
 
 Kratix will schedule the documents as follows:
 
-* `document-2.yaml`, `document-3.yaml` are scheduled to destinations with the
+- `document-2.yaml`, `document-3.yaml` are scheduled to destinations with the
   `workflow=subdir` label.
-  * The scheduling config in `destination-selectors.yaml` has specifically scheduled this
+  - The scheduling config in `destination-selectors.yaml` has specifically scheduled this
     directory.
-* `document-0.yaml`, `some-dir/document-1.yaml` are scheduled to destinations with
+- `document-0.yaml`, `some-dir/document-1.yaml` are scheduled to destinations with
   the `promise=label` label.
-  * They are not contained within a directory associated with a specific scheduling, so
+  - They are not contained within a directory associated with a specific scheduling, so
     revert to the [default scheduling](#default).
 
 ### Default scheduling {#default}
@@ -219,9 +219,11 @@ In the event of a label conflict, the Promise `spec.destinationSelectors` take p
 over any dynamic scheduling.
 
 The order of precedence is as follows:
+
 1. Promise `spec.destinationSelectors`
 2. Promise workflow `destination-selectors.yaml`
 3. Resource workflow `destination-selectors.yaml`
+
 :::
 
 :::important

docs/main/04-guides/04-scheduling.mdx docs/main/04-guides/04-new-destination.mdx

@@ -3,19 +3,24 @@ description: Guide on how to register a new Destination with Kratix
 title: Adding a new Destination
 ---
 
-One of the most powerful features of Kratix is its ability to react when new Destinations are added to the platform. These Destinations can represent additional Kubernetes clusters, Kubernetes namespaces, or completely different infrastructure like a Terraform Cloud account or edge compute provider. By default, any Promise installed into Kratix will schedule it's Dependencies to new Destinations joining the platform.
+One of the most powerful features of Kratix is its ability to react when new
+Destinations are added to the platform. These Destinations can represent
+additional Kubernetes clusters, Kubernetes namespaces, or completely different
+infrastructure like a Terraform Cloud account or edge compute provider. By
+default, any Promise installed into Kratix will schedule it's Dependencies to
+new Destinations joining the platform.
 
 ## Prerequisites
 
-In this section, we will register a new Kubernetes cluster as a Destination with Kratix, and
-experience the Kratix multi-cluster capabilities. Before continuing, you will need a Platform
-Kubernetes cluster running Kratix, and a second worker Kubernetes cluster to
-register with the Platform. You also need at least one Promise installed on
-the Platform.
+In this section, we will register a new Kubernetes cluster as a Destination with
+Kratix, and experience the Kratix multi-cluster capabilities. Before continuing,
+you will need a Platform Kubernetes cluster running Kratix, and a second worker
+Kubernetes cluster to register with the Platform. You also need at least one
+Promise installed on the Platform.
 
 For the context of this guide, we will assume the setup from [Installing Kratix
-with KinD](./installing-kratix-others) and that the following environment variables are
-set:
+with KinD](./installing-kratix-others) and that the following environment
+variables are set:
 
 ```bash
 export PLATFORM="kind-platform"
@@ -29,12 +34,12 @@ installed, if needed.
 
 ```shell-session
 $ kubectl --context $PLATFORM get destinations.platform.kratix.io
-NAME               AGE
-worker-1   1h
+NAME       READY
+worker-1   True
 
 $ kubectl --context $PLATFORM get promises.platform.kratix.io
-NAME              AGE
-jenkins-promise   1h
+NAME      STATUS      KIND      API VERSION                      VERSION
+jenkins   Available   jenkins   marketplace.kratix.io/v1alpha1
 ```
 
 On the worker, you should see the Jenkins Operator running:
@@ -49,8 +54,9 @@ If your setup is different, update the commands accordingly.
 
 ## Preparing the new cluster
 
-You will now add the new cluster to the Platform as a Destination and watch Kratix reconcile the
-system. For that, you need to first create the new Kubernetes cluster:
+You will now add the new cluster to the Platform as a Destination and watch
+Kratix reconcile the system. For that, you need to first create the new
+Kubernetes cluster:
 
 ```bash
 kind create cluster --image kindest/node:v1.27.3 --name worker-2
@@ -70,8 +76,8 @@ cd /path/to/kratix
 
 ## Registering the Destination
 
-You can now register your cluster with Kratix as a Destination. Create a file called `worker-2.yaml` with the
-following contents:
+You can now register your cluster with Kratix as a Destination. Create a file
+called `worker-2.yaml` with the following contents:
 
 ```yaml title="worker-2.yaml"
 apiVersion: platform.kratix.io/v1alpha1
@@ -97,9 +103,9 @@ Check the Destination was created:
 
 ```shell-session {4}
 $ kubectl --context $PLATFORM get destinations.platform.kratix.io
-NAME       AGE
-worker-1   1h
-worker-2   1h
+NAME       READY
+worker-1   True
+worker-2   True
 ```
 
 Kratix will react to the new Destination by scheduling the Jenkins Promise
@@ -112,14 +118,16 @@ NAME                                READY   STATUS    RESTARTS   AGE
 jenkins-operator-778d6fc487-c9w8f   1/1     Running   0          1h
 ```
 
-When you request a new Jenkins, the Resources will be created in one of the available Destinations, by default this is selected in a non-deterministic way.
+When you request a new Jenkins, the Resources will be created in one of the
+available Destinations, by default this is selected in a non-deterministic way.
 
 For further documentation on Destination scheduling, check the [Destination Reference
 documentation](../reference/destinations/intro).
 
-:::info
-If you are specifically interested in making a Resource location deterministic, you can check out the [scheduling workloads](../reference/destinations/multidestination-management#resources) reference.
-:::
+:::info If you are specifically interested in making a Resource location
+deterministic, you can check out the [scheduling
+workloads](../reference/destinations/multidestination-management#resources)
+reference. :::
 
 ## 🎉 Congratulations