diff --git a/.markdownlint.json b/.markdownlint.json index 4af4c680f..cb8ef31ec 100644 --- 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 index ec69c95f0..3cb01cb54 100644 --- 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 index f9d80428f..7317de4c7 100644 --- 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 index 8402a900a..68394f3de 100644 --- 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 index c345e0bbe..ef09ff1cf 100644 --- 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 index 57d9e776d..66e22ec24 100644 --- 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 index 27362dc99..b8c70fc20 100644 --- 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 ``` 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 index 3a1cfc911..9f3752ede 100644 --- 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 index 30a6fc676..b8788c286 100644 --- 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 new file mode 100644 index 000000000..d1c8f70eb --- /dev/null +++ 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 new file mode 100644 index 000000000..7b5412987 --- /dev/null +++ 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 new file mode 100644 index 000000000..8fd72b35b --- /dev/null +++ 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 new file mode 100644 index 000000000..e9b353ded --- /dev/null +++ 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 index 5f84e30bc..32aa5736e 100644 --- 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 index 5bb02b5fb..df01f0a04 100644 --- 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 tell us how we can improve.' -no = 'Sorry to hear that. Please tell us how we can improve.' +yes = 'Glad to hear it! Please tell us how we can improve.' +no = 'Sorry to hear that. Please tell us how we can improve.' # 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,