From 14b6bdf0d4c8f77178468b58088fc0099052f376 Mon Sep 17 00:00:00 2001 From: Aleksei Sizov Date: Mon, 14 Oct 2024 10:06:18 -0500 Subject: [PATCH] Proper call-outs; minor fixes --- .github/workflows/docs.yml | 7 ++++--- docs/aws/cloudformation.md | 3 ++- docs/aws/cluster-parameters.md | 2 +- docs/aws/hosted-control-plane.md | 2 +- docs/azure/cluster-parameters.md | 3 ++- docs/azure/hosted-control-plane.md | 5 +++-- docs/credential/main.md | 12 ++++++------ docs/dev.md | 2 +- docs/install/installation.md | 17 +++++++++++------ docs/install/quick-start.md | 16 +++++++++++----- docs/mk-docs-setup.md | 5 +++-- mkdocs.yml | 13 ++++++++++--- 12 files changed, 55 insertions(+), 32 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 94803e1..60886f2 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,4 +1,4 @@ -name: docs +name: docs on: push: branches: @@ -17,7 +17,7 @@ jobs: - uses: actions/setup-python@v5 with: python-version: 3.x - - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV + - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV - uses: actions/cache@v4 with: key: mkdocs-material-${{ env.cache_id }} @@ -26,5 +26,6 @@ jobs: mkdocs-material- - run: pip install \ mkdocs-material \ + markdown-callouts \ mkdocs-mermaid2-plugin - - run: mkdocs gh-deploy --force \ No newline at end of file + - run: mkdocs gh-deploy --force diff --git a/docs/aws/cloudformation.md b/docs/aws/cloudformation.md index f14db96..37736ea 100644 --- a/docs/aws/cloudformation.md +++ b/docs/aws/cloudformation.md @@ -2,7 +2,8 @@ Before launching a cluster on AWS, it's crucial to set up your AWS infrastructure provider: -> Note. Skip steps below if you've already configured IAM policy for your account +> NOTE: +> Skip steps below if you've already configured IAM policy for your account 1. In order to use clusterawsadm you must have an administrative user in an AWS account. Once you have that administrator user you need to set your environment variables: diff --git a/docs/aws/cluster-parameters.md b/docs/aws/cluster-parameters.md index c30a696..2c08c2b 100644 --- a/docs/aws/cluster-parameters.md +++ b/docs/aws/cluster-parameters.md @@ -39,7 +39,7 @@ stringData: SecretAccessKey: "++AQDEXAMPLE" ``` -> [!NOTE] +> NOTE: > The secret must be created in the same `Namespace` where CAPA provider is > running. In case of Project 2A it's currently `hmc-system`. Placing secret in > any other `Namespace` will result controller not able to read it. diff --git a/docs/aws/hosted-control-plane.md b/docs/aws/hosted-control-plane.md index 26d8f9b..32ccea3 100644 --- a/docs/aws/hosted-control-plane.md +++ b/docs/aws/hosted-control-plane.md @@ -82,7 +82,7 @@ With all the collected data your `ManagedCluster` manifest will look similar to - sg-0e000000000000000 ``` -> [!NOTE] +> NOTE: > In this example we're using the `us-west-1` region, but you should use the region of your VPC. ## HMC ManagedCluster manifest generation diff --git a/docs/azure/cluster-parameters.md b/docs/azure/cluster-parameters.md index 4ad16ea..b7eef98 100644 --- a/docs/azure/cluster-parameters.md +++ b/docs/azure/cluster-parameters.md @@ -34,7 +34,8 @@ will look like this: } ``` -*Note: make sure to save this credentials and treat them like passwords.* +> NOTE: +> Make sure to save this credentials and treat them like passwords. With the data from the json you can now create the `AzureClusterIdentity` object and it's secret. diff --git a/docs/azure/hosted-control-plane.md b/docs/azure/hosted-control-plane.md index ce39a96..0fa8d69 100644 --- a/docs/azure/hosted-control-plane.md +++ b/docs/azure/hosted-control-plane.md @@ -158,5 +158,6 @@ placed to finish cluster deletion. In case if have orphaned `AzureMachines` left you have to delete finalizers on them manually after making sure that no VMs are present in Azure. -*Note: since Azure admission prohibits orphaned objects mutation you'll have to -disable it by deleting it's `mutatingwebhookconfiguration`* +> NOTE: +> Since Azure admission prohibits orphaned objects mutation you'll have to disable +> it by deleting it's `mutatingwebhookconfiguration`* diff --git a/docs/credential/main.md b/docs/credential/main.md index cc4d9ec..8fac23b 100644 --- a/docs/credential/main.md +++ b/docs/credential/main.md @@ -7,8 +7,8 @@ should be passed to it. The following describes how it is implemented in 2A. The following is the process of passing credentials to the system: -1. Provider specific `ClusterIdentity` and `Secret` is created -2. `Credential` object is created referencing `ClusterIdentity` from step 1. +1. Provider specific `ClusterIdentity` and `Secret` are created +2. `Credential` object is created referencing `ClusterIdentity` from step **1**. 3. The `Credential` object is then referenced in the `ManagedCluster`. By design steps 1 and 2 should be executed by the platform lead engender who has @@ -18,10 +18,10 @@ like `ClusterIndentity`. ## Credential object -The `Credential` object acts like a reference to the underlying credentials. It is -namespace-scoped, which means that it must be in the same `Namespace` with the -`ManagedCluster` it is referenced in. -Actual credentials can be located in any namespace. +The `Credential` object acts like a reference to the underlying credentials. It +is namespace-scoped, which means that it must be in the same `Namespace` with +the `ManagedCluster` it is referenced in. Actual credentials can be located in +any namespace. ### Example diff --git a/docs/dev.md b/docs/dev.md index 1bf47ba..ff31b7a 100644 --- a/docs/dev.md +++ b/docs/dev.md @@ -93,7 +93,7 @@ export KUBECONFIG=~/.kube/config ./bin/clusterctl describe cluster -n hmc-system --show-conditions all ``` -> [!NOTE] +> NOTE: > If you encounter any errors in the output of `clusterctl describe cluster` inspect the logs of the > `capa-controller-manager` with: > ``` diff --git a/docs/install/installation.md b/docs/install/installation.md index 424ce42..29cd655 100644 --- a/docs/install/installation.md +++ b/docs/install/installation.md @@ -1,8 +1,10 @@ ### Installation -``` +```bash export KUBECONFIG= +``` +```bash helm install hmc oci://ghcr.io/mirantis/hmc/charts/hmc --version -n hmc-system --create-namespace ``` @@ -64,13 +66,14 @@ export KUBECONFIG= kubectl get template -n hmc-system -o go-template='{{ range .items }}{{ if eq .status.type "deployment" }}{{ .metadata.name }}{{ printf "\n" }}{{ end }}{{ end }}' ``` -For details about the `Template system` in HMC, see [Templates system](../template/main.md). +For details about the `Template system` in HMC, see [Templates system](../template/main.md). If you want to deploy hostded control plate template, make sure to check additional notes on [Hosted control plane](../aws/hosted-control-plane.md). 2. Create the file with the `ManagedCluster` configuration: -> Substitute the parameters enclosed in angle brackets with the corresponding values.\ +> NOTE: +> Substitute the parameters enclosed in angle brackets with the corresponding values. > Enable the `dryRun` flag if required. For details, see [Dry run](#dry-run). ```yaml @@ -92,13 +95,14 @@ spec: 4. Check the status of the newly created `ManagedCluster` object: -`kubectl -n get managedcluster -o=yaml` +`kubectl -n get managedcluster.hmc -o=yaml` 5. Wait for infrastructure to be provisioned and the cluster to be deployed (the provisioning starts only when `spec.dryRun` is disabled): `kubectl -n get cluster -o=yaml` +> TIP: > You may also watch the process with the `clusterctl describe` command (requires the `clusterctl` CLI to be installed): > ``` > clusterctl describe cluster -n --show-conditions all @@ -200,10 +204,11 @@ spec: ## Cleanup 1. Remove the Management object: - + `kubectl delete management.hmc hmc` -> Note: make sure you have no HMC ManagedCluster objects left in the cluster prior to Management deletion +> NOTE: +> Make sure you have no HMC ManagedCluster objects left in the cluster prior to Management deletion 2. Remove the `hmc` Helm release: diff --git a/docs/install/quick-start.md b/docs/install/quick-start.md index ee69c03..6e38e63 100644 --- a/docs/install/quick-start.md +++ b/docs/install/quick-start.md @@ -1,11 +1,17 @@ -## TLDR +## TL;DR - kubectl apply -f https://github.com/Mirantis/hmc/releases/download/v0.0.1/install.yaml +```bash +kubectl apply -f https://github.com/Mirantis/hmc/releases/download/v0.0.1/install.yaml +``` or install using `helm` - helm install hmc oci://ghcr.io/mirantis/hmc/charts/hmc --version v0.0.1 -n hmc-system --create-namespace +```bash +helm install hmc oci://ghcr.io/mirantis/hmc/charts/hmc --version v0.0.1 -n hmc-system --create-namespace +``` -> Note: The HMC installation using Kubernetes manifests does not allow customization of the deployment. -> If the custom HMC configuration should be applied, install HMC using the Helm chart. +> NOTE: +> The HMC installation using Kubernetes manifests does not allow customization of +> the deployment. If the custom HMC configuration should be applied, install HMC +> using the Helm chart. diff --git a/docs/mk-docs-setup.md b/docs/mk-docs-setup.md index ad0a59f..2a2e730 100644 --- a/docs/mk-docs-setup.md +++ b/docs/mk-docs-setup.md @@ -12,7 +12,7 @@ ## Setting up MKdocs and dependancies -1. Setup python Virtual Environment +1. Setup python Virtual Environment `python3 -m venv ./mkdocs` `source ./mkdocs/bin/activate` @@ -27,6 +27,8 @@ `pip install mkdocs-material` + `pip install markdown-callouts` + ## Run MKdocs for dev * `mkdocs serve` - Start the live-reloading docs server. @@ -39,4 +41,3 @@ For full documentation visit [mkdocs.org](https://www.mkdocs.org). * `mkdocs serve` - Start the live-reloading docs server. * `mkdocs build` - Build the documentation site. * `mkdocs -h` - Print help message and exit. - diff --git a/mkdocs.yml b/mkdocs.yml index 6db03f8..cc5ad39 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,8 +42,7 @@ theme: - navigation.tabs.sticky - navigation.footer - navigation.path - - + - content.code.copy extra_css: - stylesheets/extra.css @@ -57,6 +56,14 @@ plugins: # Page tree +markdown_extensions: + - callouts + - pymdownx.details + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format nav: - Home: index.md - Introduction: introduction.md @@ -64,12 +71,12 @@ nav: - Quick Start: install/quick-start.md - Installation Guide: install/installation.md - Templates: template/main.md + - Credential System: credential/main.md - Developer Guide: dev.md - Provider Guides: - AWS: - aws/main.md - aws/cloudformation.md - - aws/credentials.md - aws/cluster-parameters.md - aws/hosted-control-plane.md - aws/nuke.md