docs: Add how to deploy CAREN (#599)

jimmidyson · web-flow · commit b8d52beb48df · 2024-05-01T17:21:52.000+01:00
Also add some more icon bling to the menu and update menu ordering.
diff --git a/.markdownlint.json b/.markdownlint.json
@@ -1,6 +1,6 @@
 {
   "heading-style": { "style": "atx" },
   "ul-style": { "style": "dash" },
-  "line-length": { "line_length": 120, "stern": true },
+  "line-length": { "line_length": 120, "code_blocks": false },
   "hr-style": { "style": "---" }
 }
diff --git a/docs/content/_index.md b/docs/content/_index.md
@@ -1,5 +1,5 @@
 +++
-title = "CAPI Runtime Extensions"
+title = "Cluster API Runtime Extensions - Nutanix (CAREN)"
 
 # [[cascade]]
 # type = "blog"
@@ -23,11 +23,12 @@ templating by introducing variables specified with an OpenAPI schema that can th
 via patches.
 
 The [Runtime SDK] feature provides an extensibility mechanism to hook into `ClusterClass` managed Kubernetes clusters'
-lifecycle. This project, CAPI Runtime Extensions, provides implementations of various runtime hooks that can be used in
-`ClusterClasses` across providers. This includes variables and patches that can be used across any provider to configure
-generic Kubernetes capabilities, such as configuring audit policy or HTTP proxy configuration. These capabilities are
-not provider-specific and delivering these capabilities in code instead of directly embedded in `ClusterClass`
-definitions leads to a much more robust experience via fast-feedback unit tests, as opposed to long running e2e tests.
+lifecycle. This project, Cluster API Runtime Extensions - Nutanix (CAREN), provides implementations of various runtime
+hooks that can be used in `ClusterClasses` across providers. This includes variables and patches that can be used across
+any provider to configure generic Kubernetes capabilities, such as configuring audit policy or HTTP proxy configuration.
+These capabilities are not provider-specific and delivering these capabilities in code instead of directly embedded in
+`ClusterClass` definitions leads to a much more robust experience via fast-feedback unit tests, as opposed to long
+running e2e tests.
 
 In addition to cluster resource customizations, this project enables management of essential cluster addons (e.g. CNI)
 via variable definitions, e.g. selecting a CNI provider via variables defined on the `Cluster` resource itself. The goal
diff --git a/docs/content/addons/_index.md b/docs/content/addons/_index.md
@@ -1,5 +1,5 @@
 +++
 title = "Addons"
-weight = 2
+weight = 3
 icon = "fa-solid fa-cubes"
 +++
diff --git a/docs/content/addons/cluster-autoscaler.md b/docs/content/addons/cluster-autoscaler.md
@@ -1,5 +1,6 @@
 +++
 title = "Cluster Autoscaler"
+icon = "fa-solid fa-up-right-and-down-left-from-center"
 +++
 
 By leveraging CAPI cluster lifecycle hooks, this handler deploys [Cluster Autoscaler][cluster-autoscaler]
diff --git a/docs/content/contributing/_index.md b/docs/content/contributing/_index.md
@@ -1,5 +1,5 @@
 +++
 title = "Contributing"
 weight = 99
-icon = "fa-solid fa-gift"
+icon = "fa-solid fa-hand-holding-heart"
 +++
diff --git a/docs/content/contributing/e2e_tests.md b/docs/content/contributing/e2e_tests.md
@@ -1,5 +1,6 @@
 +++
 title = "End-to-end tests"
+icon = "fa-solid fa-bugs"
 +++
 
 This project uses [Ginkgo] to run end-to-end tests. Tests are labelled to make running targeted or specific tests
diff --git a/docs/content/contributing/releasing.md b/docs/content/contributing/releasing.md
@@ -1,5 +1,6 @@
 +++
 title = "Releasing"
+icon = "fa-solid fa-gift"
 +++
 
 This project uses [release-please] to automate changelog updates per release. Due to security restrictions[^1] in the
@@ -9,7 +10,7 @@ This project uses [release-please] to automate changelog updates per release. Du
 When a release has been cut, a new release PR can be created manually using the `release-please` CLI locally. This needs
 to be run by someone with write permissions to the repository. Create the `release-please` branch and PR:
 
-```bash
+```shell
 make release-please
 ```
 
@@ -20,19 +21,19 @@ date).
 When a release is ready, the commits in the release PR will need to be signed (again, this is a security requirement).
 To do this, check out the PR branch locally:
 
-```bash
+```shell
 gh pr checkout <RELEASE_PR_NUMBER>
 ```
 
 Sign the previous commit:
 
-```bash
+```shell
 git commit --gpg-sign --amend
 ```
 
 And force push:
 
-```bash
+```shell
 git push --force-with-lease
 ```
 
diff --git a/docs/content/customization/_index.md b/docs/content/customization/_index.md
@@ -1,6 +1,6 @@
 +++
 title = "Cluster customizations"
-weight = 1
+weight = 2
 icon = "fa-solid fa-screwdriver-wrench"
 +++
 
diff --git a/docs/content/customization/nutanix/_index.md b/docs/content/customization/nutanix/_index.md
@@ -1,6 +1,6 @@
 +++
 title = "Nutanix"
-icon = "fa-brands fa-nutanix"
+icon = "fa-solid fa-server"
 +++
 
 The customizations in this section are applicable only to Nutanix clusters. They will only be applied to clusters that
diff --git a/docs/content/getting-started/_index.md b/docs/content/getting-started/_index.md
@@ -0,0 +1,8 @@
++++
+title = "Getting started"
+icon = "fa-solid fa-forward-fast"
+weight = 1
++++
+
+To deploy CAREN, follow the docs on how to deploy CAREN using either
+[clusterctl]({{< ref "deployment/via-clusterctl" >}}) or [Helm]({{< ref "deployment/via-helm" >}}).
diff --git a/docs/content/getting-started/deployment/_index.md b/docs/content/getting-started/deployment/_index.md
@@ -0,0 +1,11 @@
++++
+title = "Deploying CAREN"
+icon = "fa-solid fa-truck-fast"
++++
+
+CAREN is implemented as a CAPI runtime extension provider, which means it can be deployed alongside all other CAPI
+providers in the same way [using `clusterctl`]({{< ref "via-clusterctl" >}}). However, as CAREN is not yet integrated
+into `clusterctl`, it is necessary to first configure `clusterctl` to know about CAREN before we can deploy it.
+
+Alternatively you can install CAREN [via Helm]({{< ref "via-helm" >}}). Installing via Helm will provide default some
+default `ClusterClasses` and allow for further customization of the CAREN deployment.
diff --git a/docs/content/getting-started/deployment/via-clusterctl.md b/docs/content/getting-started/deployment/via-clusterctl.md
@@ -0,0 +1,35 @@
++++
+title = "Via clusterctl"
+icon = "fa-solid fa-circle-nodes"
+weight = 1
++++
+
+Add the following to your `clusterctl.yaml` file, which is normally found at
+`${XDG_CONFIG_HOME}/cluster-api/clusterctl.yaml` (or `${HOME}/cluster-api/clusterctl.yaml`). See [clusterctl
+configuration file] for more details. If the `providers` section already exists, add the entry and omit the `providers`
+key from this block below:
+
+```yaml
+providers:
+  - name: "caren"
+    url: "https://github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/releases/latest/runtime-extension-components.yaml"
+    type: "RuntimeExtensionProvider"
+```
+
+Now we can deploy CAREN and other necessary providers (update infrastructure providers for your needs), leaving all
+configuration values blank as we will specify these when creating clusters:
+
+```shell
+env CLUSTER_TOPOLOGY=true \
+    EXP_RUNTIME_SDK=true  \
+    EXP_CLUSTER_RESOURCE_SET=true  \
+    NUTANIX_ENDPOINT= NUTANIX_PASSWORD= NUTANIX_USER=  \
+    AWS_B64ENCODED_CREDENTIALS=  \
+    clusterctl init \
+      --infrastructure docker,nutanix:v1.4.0-alpha.2,aws \
+      --addon helm \
+      --runtime-extension caren \
+      --wait-providers
+```
+
+[clusterctl configuration file]: https://cluster-api.sigs.k8s.io/clusterctl/configuration.html?highlight=clusterctl%20config#variables
diff --git a/docs/content/getting-started/deployment/via-helm.md b/docs/content/getting-started/deployment/via-helm.md
@@ -0,0 +1,33 @@
++++
+title = "Via Helm"
+icon = "fa-solid fa-helmet-safety"
+weight = 2
++++
+
+When installing CAREN via Helm, we need to deploy Cluster API core providers and any other required infrastructure
+providers to our management cluster via `clusterctl`:
+
+```shell
+env CLUSTER_TOPOLOGY=true \
+    EXP_RUNTIME_SDK=true  \
+    EXP_CLUSTER_RESOURCE_SET=true  \
+    NUTANIX_ENDPOINT= NUTANIX_PASSWORD= NUTANIX_USER=  \
+    AWS_B64ENCODED_CREDENTIALS=  \
+    clusterctl init \
+      --infrastructure docker,nutanix:v1.4.0-alpha.2,aws \
+      --addon helm \
+      --wait-providers
+```
+
+We can then deploy CAREN via Helm by adding the Helm repo and installing in the usual way via Helm:
+Add the CAREN Helm repo:
+
+```shell
+helm repo add caren https://nutanix-cloud-native.github.io/cluster-api-runtime-extensions-nutanix/helm
+helm repo update caren
+helm upgrade --install caren caren/cluster-api-runtime-extensions-nutanix \
+  --namespace cluster-api-runtime-extensions-nutanix-system \
+  --create-namespace \
+  --wait \
+  --wait-for-jobs
+```
diff --git a/docs/content/lifecycle/_index.md b/docs/content/lifecycle/_index.md
@@ -1,5 +1,5 @@
 +++
 title = "Lifecycle handlers"
-weight = 3
+weight = 4
 icon = "fa-solid fa-seedling"
 +++
diff --git a/docs/hugo.toml b/docs/hugo.toml
@@ -127,8 +127,8 @@ sidebar_cache_limit = 1000
 [params.ui.feedback]
 enable = true
 # The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful).
-yes = 'Glad to hear it! Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
-no = 'Sorry to hear that. Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
+yes = 'Glad to hear it! Please <a href="https://github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/issues/new">tell us how we can improve</a>.'
+no = 'Sorry to hear that. Please <a href="https://github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/issues/new">tell us how we can improve</a>.'
 
 # Adds a reading time to the top of each doc.
 # If you want this feature, but occasionally need to remove the Reading time from a single page,

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"heading-style": { "style": "atx" },`
`3`	`3`	`"ul-style": { "style": "dash" },`
`4`		`- "line-length": { "line_length": 120, "stern": true },`
	`4`	`+ "line-length": { "line_length": 120, "code_blocks": false },`
`5`	`5`	`"hr-style": { "style": "---" }`
`6`	`6`	`}`