Update getting started guides

Author: ThomasVitale

docs/getting-started/installation.md

@@ -5,40 +5,64 @@ description: Basic installation of the platform
 
 # Installation
 
-Let's discover how to install a basic version of the Kadras Engineering Platform.
+Let's discover how to install Kadras Engineering Platform on a local Kubernetes cluster with [kind](https://kind.sigs.k8s.io).
 
 ## Prerequisites
 
-* Kubernetes 1.24+
-* Carvel [`kctrl`](https://carvel.dev/kapp-controller/docs/latest/install/#installing-kapp-controller-cli-kctrl) CLI.
-* Sigstore [`cosign`](https://docs.sigstore.dev/cosign/installation/) CLI.
-* Carvel [kapp-controller](https://carvel.dev/kapp-controller) deployed in your Kubernetes cluster. You can install it with Carvel [`kapp`](https://carvel.dev/kapp/docs/latest/install) (recommended choice) or `kubectl`.
+Ensure you have the following tools installed in your local environment:
+
+* Kubernetes [`kubectl`](https://kubectl.docs.kubernetes.io/installation/kubectl)
+* [kind](https://kind.sigs.k8s.io)
+* Carvel [`kctrl`](https://carvel.dev/kapp-controller/docs/latest/install)
+* Carvel [`kapp`](https://carvel.dev/kapp-controller/docs/latest/install/#installing-kapp-controller-cli-kctrl) CLI.
+
+Then, create a local Kubernetes cluster with kind.
+
+```shell
+cat <<EOF | kind create cluster --config=-
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+nodes:
+- role: control-plane
+  kubeadmConfigPatches:
+  - |
+    kind: InitConfiguration
+    nodeRegistration:
+      kubeletExtraArgs:
+        node-labels: "ingress-ready=true"
+  extraPortMappings:
+  - containerPort: 80
+    hostPort: 80
+    protocol: TCP
+  - containerPort: 443
+    hostPort: 443
+    protocol: TCP
+EOF
+```
 
-  ```shell
-  kapp deploy -a kapp-controller -y \
-    -f https://github.com/carvel-dev/kapp-controller/releases/latest/download/release.yml
-  ```
+## Deploy Carvel kapp-controller
+
+The platform relies on the Kubernetes-native package management capabilities offered by Carvel [kapp-controller](https://carvel.dev/kapp-controller). You can install it with Carvel [`kapp`](https://carvel.dev/kapp/docs/latest/install) (recommended choice) or `kubectl`.
+
+```shell
+kapp deploy -a kapp-controller -y \
+  -f https://github.com/carvel-dev/kapp-controller/releases/latest/download/release.yml
+```
 
 ## Add the Kadras Repository
 
-Add the Kadras repository to make all Kadras packages available to the cluster.
+Add the Kadras repository to make the platform packages available to the cluster.
 
   ```shell
   kubectl create namespace kadras-packages
   kctrl package repository add -r kadras-packages \
-    --url ghcr.io/kadras-io/kadras-packages \
+    --url ghcr.io/kadras-io/kadras-packages:0.11.1 \
     -n kadras-packages
   ```
 
-You can check the full list of available packages as follows.
-
-  ```shell
-  kctrl package available list -n kadras-packages 
-  ```
-
 ## Create a Secret for the OCI Registry
 
-First, create a Secret with the credentials to access your container registry in read/write mode. It will be used by the platform to publish and consume OCI artifacts.
+The platform will need to interact with a container registry. Create a Secret with the credentials to access your container registry with read/write permissions. It will be used by the platform to publish and consume OCI artifacts.
 
   ```shell
   export SUPPLY_CHAIN_REGISTRY_HOSTNAME=<hostname>
@@ -77,8 +101,8 @@ workspace_provisioner:
 ```
 
 * `<domain>` is the base domain name the platform will use to configure the Ingress controller. It must be a valid DNS name. For example, `lab.thomasvitale.com`.
-* `<oci-server>` is the server of the OCI registry where the platform will publish and consume OCI images. It must be the same used in step 3 when creating a Secret with the OCI registry credentials. For example, `ghcr.io`, `gcr.io`, `quay.io`, `index.docker.io`.
-* `<oci-repository>` is the repository in the OCI registry where the platform will publish and consume OCI images. It must be the same used in step 3 when creating a Secret with the OCI registry credentials. For example, it might be your username or organization name depending on which OCI server you're using.
+* `<oci-server>` is the server of the OCI registry where the platform will publish and consume OCI images. It must be the same used in the previous step when creating a Secret with the OCI registry credentials. For example, `ghcr.io`, `gcr.io`, `quay.io`, `index.docker.io`.
+* `<oci-repository>` is the repository in the OCI registry where the platform will publish and consume OCI images. It must be the same used in the previous step when creating a Secret with the OCI registry credentials. For example, it might be your username or organization name depending on which OCI server you're using.
 
 ## Install the Platform
 
@@ -87,17 +111,11 @@ Reference the `values.yml` file you created in the previous step and install the
   ```shell
   kctrl package install -i engineering-platform \
     -p engineering-platform.packages.kadras.io \
-    -v ${VERSION} \
+    -v 0.9.2 \
     -n kadras-packages \
     --values-file values.yml
   ```
 
-You can find the `${VERSION}` value by retrieving the list of package versions available in the Kadras package repository installed on your cluster.
-
-  ```shell
-  kctrl package available list -p engineering-platform.packages.kadras.io -n kadras-packages
-  ```
-
 ## Verify the Installation
 
 Verify that all the platform components have been installed and properly reconciled.

docs/getting-started/workload.md

@@ -39,4 +39,4 @@ Using the Cartographer CLI, you can inspect the status of a workload and its sup
 carto apps workload get band-service
 ```
 
-The application will be available at `https://band-service.default.<your-domain-name>`, where `<your-domain-name>` is the base domain used during the platform installation.
+The application will be available at `https://band-service.default.127.0.0.1.sslip.io`.

docs/introduction.md

@@ -21,4 +21,4 @@ The platform provides several capabilities based on open-source projects, includ
 * GitOps support with Flux, ArgoCD and Carvel
 * Air-gapped support with Carvel.
 
-Get started with Kadras by [installing the platform](/docs/getting-started/installation) and [creating your first workload](/docs/getting-started/workload).
+Get started with Kadras by [installing the platform](/docs/getting-started/installation) and [creating your first workload](/docs/getting-started/workload) on a local environment.