diff --git a/docs/aws/credentials.md b/docs/aws/credentials.md index 6f96dda..08de1df 100644 --- a/docs/aws/credentials.md +++ b/docs/aws/credentials.md @@ -26,7 +26,7 @@ export AWS_B64ENCODED_CREDENTIALS=$(clusterawsadm bootstrap credentials encode-a > By default, HMC fetches the AWS variables configuration from the `aws-variables` secret in the `hmc-system` > namespace. If you want to change the name of the secret you should overwrite the configuration of the cluster > API provider AWS in the HMC Management object. \ -> For details, see: [Extended Management Configuration](../../README.md#extended-management-configuration) +> For details, see: [Extended Management Configuration](../install/installation.md#extended-management-configuration) > You can also provide additional configuration variables, but the `AWS_B64ENCODED_CREDENTIALS` parameter is required. diff --git a/docs/aws/hosted-control-plane.md b/docs/aws/hosted-control-plane.md index 19ea791..26d8f9b 100644 --- a/docs/aws/hosted-control-plane.md +++ b/docs/aws/hosted-control-plane.md @@ -19,8 +19,7 @@ reused with a management cluster. If you deployed your AWS Kubernetes cluster using Cluster API Provider AWS (CAPA) you can obtain all the necessary data with the commands below or use the template found below in the -[HMC ManagedCluster manifest -generation](#hmc-managed-cluster-manifest-generation) section. +[HMC ManagedCluster manifest generation](#hmc-managedcluster-manifest-generation) section. If using the `aws-standalone-cp` template to deploy a hosted cluster it is recommended to use a `t3.large` or larger instance type as the `hmc-controller` diff --git a/docs/index.md b/docs/index.md index 04f5b80..8c0918b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -# Welcome to HMC Docs +# Welcome to Mirantis Project 2A Docs # Introduction diff --git a/docs/install/installation.md b/docs/install/installation.md new file mode 100644 index 0000000..ea88d30 --- /dev/null +++ b/docs/install/installation.md @@ -0,0 +1,214 @@ +### Installation + +``` +export KUBECONFIG= + +helm install hmc oci://ghcr.io/mirantis/hmc/charts/hmc --version -n hmc-system --create-namespace +``` + + +#### Extended Management configuration + +By default, the Hybrid Container Cloud is being deployed with the following configuration: + +```yaml +apiVersion: hmc.mirantis.com/v1alpha1 +kind: Management +metadata: + name: hmc +spec: + core: + capi: + template: cluster-api + hmc: + template: hmc + providers: + - template: k0smotron + - config: + configSecret: + name: aws-variables + template: cluster-api-provider-aws +``` + +There are two options to override the default management configuration of HMC: + +1. Update the `Management` object after the HMC installation using `kubectl`: + + `kubectl --kubeconfig edit management` + +2. Deploy HMC skipping the default `Management` object creation and provide your own `Management` +configuration: + + * Create `management.yaml` file and configure core components and providers. + See [Management API](api/v1alpha1/management_types.go). + + * Specify `--create-management=false` controller argument and install HMC: + + If installing using `helm` add the following parameter to the `helm install` command: + + `--set="controller.createManagement=false"` + + * Create `hmc` `Management` object after HMC installation: + + `kubectl --kubeconfig create -f management.yaml` + +## Deploy a managed cluster + +To deploy a managed cluster: + +1. Select the `Template` you want to use for the deployment. To list all available templates, run: + +```bash +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](../templates/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.\ +> Enable the `dryRun` flag if required. For details, see [Dry run](#dry-run). + +```yaml +apiVersion: hmc.mirantis.com/v1alpha1 +kind: ManagedCluster +metadata: + name: + namespace: +spec: + template: + dryRun: + config: + +``` + +3. Create the `ManagedCluster` object: + +`kubectl create -f managedcluster.yaml` + +4. Check the status of the newly created `ManagedCluster` object: + +`kubectl -n get managedcluster -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` + +> 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 +> ``` + +6. Retrieve the `kubeconfig` of your managed cluster: + +``` +kubectl get secret -n hmc-system -kubeconfig -o=jsonpath={.data.value} | base64 -d > kubeconfig +``` + +### Dry run + +HMC `ManagedCluster` supports two modes: with and without (default) `dryRun`. + +If no configuration (`spec.config`) provided, the `ManagedCluster` object will be populated with defaults +(default configuration can be found in the corresponding `Template` status) and automatically marked as `dryRun`. + +Here is an example of the `ManagedCluster` object with default configuration: + +```yaml +apiVersion: hmc.mirantis.com/v1alpha1 +kind: ManagedCluster +metadata: + name: + namespace: +spec: + config: + clusterNetwork: + pods: + cidrBlocks: + - 10.244.0.0/16 + services: + cidrBlocks: + - 10.96.0.0/12 + controlPlane: + amiID: "" + iamInstanceProfile: control-plane.cluster-api-provider-aws.sigs.k8s.io + instanceType: "" + controlPlaneNumber: 3 + k0s: + version: v1.27.2+k0s.0 + publicIP: false + region: "" + sshKeyName: "" + worker: + amiID: "" + iamInstanceProfile: nodes.cluster-api-provider-aws.sigs.k8s.io + instanceType: "" + workersNumber: 2 + template: aws-standalone-cp + dryRun: true +``` + +After you adjust your configuration and ensure that it passes validation (`TemplateReady` condition +from `status.conditions`), remove the `spec.dryRun` flag to proceed with the deployment. + +Here is an example of a `ManagedCluster` object that passed the validation: + +```yaml +apiVersion: hmc.mirantis.com/v1alpha1 +kind: ManagedCluster +metadata: + name: aws-standalone + namespace: aws +spec: + template: aws-standalone-cp + config: + region: us-east-2 + publicIP: true + controlPlaneNumber: 1 + workersNumber: 1 + controlPlane: + amiID: ami-02f3416038bdb17fb + instanceType: t3.small + worker: + amiID: ami-02f3416038bdb17fb + instanceType: t3.small + status: + conditions: + - lastTransitionTime: "2024-07-22T09:25:49Z" + message: Template is valid + reason: Succeeded + status: "True" + type: TemplateReady + - lastTransitionTime: "2024-07-22T09:25:49Z" + message: Helm chart is valid + reason: Succeeded + status: "True" + type: HelmChartReady + - lastTransitionTime: "2024-07-22T09:25:49Z" + message: ManagedCluster is ready + reason: Succeeded + status: "True" + type: Ready + observedGeneration: 1 +``` + +## 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 + +2. Remove the `hmc` Helm release: + +`helm uninstall hmc -n hmc-system` + +3. Remove the `hmc-system` namespace: + +`kubectl delete ns hmc-system` diff --git a/docs/quick-start.md b/docs/install/quick-start.md similarity index 89% rename from docs/quick-start.md rename to docs/install/quick-start.md index 39e6132..e3e6ca5 100644 --- a/docs/quick-start.md +++ b/docs/install/quick-start.md @@ -1,8 +1,5 @@ -# Mirantis Hybrid Cloud Platform -## Installation - -### TLDR +## TLDR kubectl apply -f https://github.com/Mirantis/hmc/releases/download/v0.0.1/install.yaml diff --git a/docs/mk-docs-setup.md b/docs/mk-docs-setup.md index 998a4d4..ad0a59f 100644 --- a/docs/mk-docs-setup.md +++ b/docs/mk-docs-setup.md @@ -1,4 +1,4 @@ -# HMC MKdocs Setup +# Project 2A MKdocs Setup ## Project layout diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index e65d3c7..0e155ce 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -23,17 +23,21 @@ height: fit-content; /* Adjust the size as needed */ } .md-header__title { - font-size: 1.1rem; + font-size: 1rem; } .md-nav { - font-size: .8rem; - font-weight: 800; - line-height: 1.3; + font-size: .7rem; + font-weight: 500; + line-height: 1.1; } - .md-typeset h1, .md-typeset h2 { + .md-typeset h1 { font-weight: 500; letter-spacing: -.01em; } + .md-typeset h2 { + font-weight: 400; + letter-spacing: -.01em; + } .md-typeset h3 { - font-weight: 500; + font-weight: 200; } diff --git a/mkdocs.yml b/mkdocs.yml index 7e34a1d..afd9a7a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,22 +1,14 @@ -site_name: HMC +site_name: Project 2A site_author: Mirantis docs_dir: ./docs repo_name: GitHub repo_url: https://github.com/mirantis/hmc copyright: - '© 2005 - 2024 Mirantis, Inc. All rights reserved. “Mirantis” and “FUEL” are registered trademarks of Mirantis, Inc. All other trademarks are the property of their respective owners.' -nav: - - Home: index.md - - Introduction: introduction.md - - Quick Start: quick-start.md - - Developer Guide: dev.md - - - + '© 2005 - 2024 Mirantis, Inc. All rights reserved.' theme: name: "material" font: - text: overpass + text: Overpass code: Roboto Mono palette: # Palette toggle for light mode @@ -41,8 +33,16 @@ theme: search_index_only: true features: - toc.autohide + - toc.integrate - search.suggest - search.highlight + - navigation.sections + - navigation.tabs + - navigation.tabs.sticky + - navigation.footer + - navigation.path + + extra_css: - stylesheets/extra.css @@ -51,3 +51,34 @@ plugins: - search - mermaid2 +#extra: +# generator: false + +# Page tree + +nav: + - Home: index.md + - Introduction: introduction.md + - Installation: + - Quick Start: install/quick-start.md + - Installation Guide: install/installation.md + - Templates: templates/templates.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 + - Azure: + - azure/main.md + - azure/cluster-parameters.md + - azure/hosted-control-plane.md + - azure/machine-parameters.md + - Vsphere: + - vsphere/main.md + - vsphere/cluster-parameters.md + - vsphere/hosted-control-plane.md + - vsphere/machine-parameters.md