From 19c9505380fb1cf152674cbf757e9eba85d72c5e Mon Sep 17 00:00:00 2001 From: eromanova Date: Mon, 22 Jul 2024 14:50:37 +0400 Subject: [PATCH] Add documentation describing HMC installation process HMC-59 --- README.md | 249 +++++++++++++++++++++++++-------- docs/aws/cloudformation.md | 21 +++ docs/aws/cluster-parameters.md | 17 +++ docs/aws/credentials.md | 28 ++++ docs/aws/main.md | 18 +++ docs/dev.md | 53 +++++++ 6 files changed, 329 insertions(+), 57 deletions(-) create mode 100644 docs/aws/cloudformation.md create mode 100644 docs/aws/cluster-parameters.md create mode 100644 docs/aws/credentials.md create mode 100644 docs/aws/main.md create mode 100644 docs/dev.md diff --git a/README.md b/README.md index a797163fa..cc866d188 100644 --- a/README.md +++ b/README.md @@ -1,97 +1,232 @@ # Mirantis Hybrid Cloud Platform -## Getting Started +## Installation -Below is the example on how to deploy an HMC managed cluster on AWS with k0s. -The kind cluster acts as management in this example. +### TLDR -### Prerequisites +> kubectl apply -f https://github.com/Mirantis/hmc/releases/download/v0.0.1/install.yaml -#### Clone HMC repository +or install using `helm` -``` -git clone https://github.com/Mirantis/hmc.git && cd hmc -``` +> helm install hmc oci://ghcr.io/mirantis/hmc/charts/hmc --version v0.0.1 -n hmc-system --create-namespace -#### Install required CLIs +Then follow the [Deploy a managed cluster](#deploy-a-managed-cluster) guide to create a managed cluster. -Run: +### Development guide -``` -make cli-install -``` +See [Install HMC for development purposes](docs/dev.md#hmc-installation-for-development). + +### Software Prerequisites + +Mirantis Hybrid Container Cloud requires the following: + +1. Existing management cluster (minimum required kubernetes version 1.28.0). +2. `kubectl` CLI installed locally. -#### AWS IAM setup +Optionally, the following CLIs may be helpful: -Before launching a cluster, it's crucial to set up your AWS infrastructure provider: +1. `helm` (required only when installing HMC using `helm`). +2. `clusterctl` (to handle the lifecycle of the managed clusters). -> Note. Skip steps below if you've already configured IAM policy for your account +### Providers configuration -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: +Follow the instruction to configure providers. Currently supported providers: +* [AWS](docs/aws/main.md#prepare-the-aws-infra-provider) + +### Installation ``` -export AWS_REGION=us-east-1 -export AWS_ACCESS_KEY_ID= -export AWS_SECRET_ACCESS_KEY= -export AWS_SESSION_TOKEN= # Optional. If you are using Multi-Factor Auth. +export KUBECONFIG= + +helm install hmc oci://ghcr.io/mirantis/hmc/charts/hmc --version -n hmc-system --create-namespace ``` -2. After these are set run this command to create IAM cloud formation stack: +See [HMC configuration options](templates/hmc/values.yaml). -``` -./bin/clusterawsadm bootstrap iam create-cloudformation-stack +#### 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 + namespace: hmc-system +spec: + core: + capi: + template: cluster-api + hmc: + template: hmc + providers: + - template: k0smotron + - config: + credentialsSecretName: aws-credentials + template: cluster-api-provider-aws ``` -#### Configure AWS credentials for the bootstrap +There are two options to override the default management configuration of HMC: -1. Ensure AWS user has enough permissions to deploy cluster. Ensure that these policies were attached to the AWS user: +1. Update the `Management` object after the HMC installation using `kubectl`: -* `control-plane.cluster-api-provider-aws.sigs.k8s.io` -* `controllers.cluster-api-provider-aws.sigs.k8s.io` -* `nodes.cluster-api-provider-aws.sigs.k8s.io` + `kubectl --kubeconfig -n hmc-system edit management` -2. Retrieve access key and export it as environment variable: +2. Deploy HMC skipping the default `Management` object creation and provide your own `Management` +configuration: -``` -export AWS_REGION=us-east-1 -export AWS_ACCESS_KEY_ID= -export AWS_SECRET_ACCESS_KEY= -export AWS_SESSION_TOKEN= # Optional. If you are using Multi-Factor Auth. -``` + * Create `management.yaml` file and configure core components and providers. + See [Management API](api/v1alpha1/management_types.go). -3. Create the base64 encoded credentials using `clusterawsadm`. This command uses your environment variables and -encodes them in a value to be stored in a Kubernetes Secret. + * Specify `--create-management=false` controllerManager argument and install HMC: -``` -export AWS_B64ENCODED_CREDENTIALS=$(./bin/clusterawsadm bootstrap credentials encode-as-profile) -``` + If installing using `helm` add the following parameter to the `helm install` command: -### Deploy HMC + `--set="controllerManager.manager.args={--create-management=false}"` -1. Configure your cluster parameters in `config/dev/deployment.yaml`: + * Create `hmc-system/hmc` `Management` object after HMC installation: - * Configure the `name` of the deployment - * Change `amiID` and `instanceType` for control plane and worker machines - * Specify the number of control plane and worker machines, etc + `kubectl --kubeconfig -n hmc-system create -f management.yaml` -2. Run `make dev-apply` to deploy and configure management cluster +## Deploy a managed cluster -3. Wait a couple of minutes for management components to be up and running +To deploy a managed cluster: -4. Run `make dev-aws-apply` to deploy managed cluster on AWS with default configuration +1. Select the `Template` you want to use for the deployment. To list all available templates, run: -5. Wait for infrastructure to be provisioned and the cluster to be deployed. You may watch the process with the -`./bin/clusterctl describe` command. Example: +```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 }}' ``` -export KUBECONFIG=~/.kube/config -./bin/clusterctl describe cluster -n hmc-system --show-conditions all -``` +2. Create the file with the `Deployment` configuration: -8. Retrieve the `kubeconfig` of your managed cluster: +> 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: Deployment +metadata: + name: + namespace: +spec: + template: + dryRun: + config: + ``` -kubectl --kubeconfig ~/.kube/config get secret -n hmc-system -kubeconfig -o=jsonpath={.data.value} | base64 -d > kubeconfig + +3. Create the `Deployment` object: + +`kubectl create -f deployment.yaml` + +4. Check the status of the newly created `Deployment` object: + +`kubectl -n get deployment.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` + +> 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 `Deployment` supports two modes: with and without (default) `dryRun`. + +If no configuration (`spec.config`) provided, the `Deployment` 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 `Deployment` object with default configuration: + +```yaml +apiVersion: hmc.mirantis.com/v1alpha1 +kind: Deployment +metadata: + name: + namespace: +spec: + config: + clusterNetwork: + pods: + cidrBlocks: + - 10.244.0.0/16 + services: + cidrBlocks: + - 10.96.0.0/12 + controlPlane: + additionalSecurityGroupIDs: [] + 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: + additionalSecurityGroupIDs: [] + 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 `Deployment` object that passed the validation: + +```yaml +apiVersion: hmc.mirantis.com/v1alpha1 +kind: Deployment +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: Deployment is ready + reason: Succeeded + status: "True" + type: Ready + observedGeneration: 1 ``` diff --git a/docs/aws/cloudformation.md b/docs/aws/cloudformation.md new file mode 100644 index 000000000..f14db966d --- /dev/null +++ b/docs/aws/cloudformation.md @@ -0,0 +1,21 @@ +# AWS IAM setup + +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 + +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: + +``` +export AWS_REGION= +export AWS_ACCESS_KEY_ID= +export AWS_SECRET_ACCESS_KEY= +export AWS_SESSION_TOKEN= # Optional. If you are using Multi-Factor Auth. +``` + +2. After these are set run this command to create IAM cloud formation stack: + +``` +clusterawsadm bootstrap iam create-cloudformation-stack +``` diff --git a/docs/aws/cluster-parameters.md b/docs/aws/cluster-parameters.md new file mode 100644 index 000000000..38108b856 --- /dev/null +++ b/docs/aws/cluster-parameters.md @@ -0,0 +1,17 @@ +# AWS cluster parameters + +## Software prerequisites + +1. `clusterawsadm` CLI installed locally. +2. `AWS_B64ENCODED_CREDENTIALS` environment variable to be exported. +See [AWS credentials](credentials.md#aws-credentials-configuration) (p. 1-3) + +## AWS AMI + +Use `clusterawsadm` to get available AMIs to deploy managed cluster: + +```bash +clusterawsadm ami list +``` + +For details, see [Pre-built Kubernetes AMIs](https://cluster-api-aws.sigs.k8s.io/topics/images/built-amis.html). diff --git a/docs/aws/credentials.md b/docs/aws/credentials.md new file mode 100644 index 000000000..7f11fdd8a --- /dev/null +++ b/docs/aws/credentials.md @@ -0,0 +1,28 @@ +# AWS Credentials configuration + +1. Ensure AWS user has enough permissions to deploy cluster. Ensure that these policies were attached to the AWS user: + +* `control-plane.cluster-api-provider-aws.sigs.k8s.io` +* `controllers.cluster-api-provider-aws.sigs.k8s.io` +* `nodes.cluster-api-provider-aws.sigs.k8s.io` + +2. Retrieve access key and export it as environment variable: + +``` +export AWS_REGION= +export AWS_ACCESS_KEY_ID= +export AWS_SECRET_ACCESS_KEY= +export AWS_SESSION_TOKEN= # Optional. If you are using Multi-Factor Auth. +``` + +3. Create the base64 encoded credentials using `clusterawsadm`: + +``` +export AWS_B64ENCODED_CREDENTIALS=$(clusterawsadm bootstrap credentials encode-as-profile) +``` + +4. Create the secret with AWS credentials in the `hmc-system` namespace: + +``` +kubectl create secret generic aws-credentials -n hmc-system --from-literal credentials="$(echo $AWS_B64ENCODED_CREDENTIALS | base64 -d)" +``` diff --git a/docs/aws/main.md b/docs/aws/main.md new file mode 100644 index 000000000..275919cbe --- /dev/null +++ b/docs/aws/main.md @@ -0,0 +1,18 @@ +# Prepare the AWS infra provider + +## Software prerequisites + +1. `kubectl` CLI installed locally. +2. `clusterawsadm` CLI installed locally. + +## Configure AWS IAM + +Follow the AWS IAM [setup quide](cloudformation.md#aws-iam-setup). + +## Configure AWS credentials + +Follow the AWS Credentials [configuration quide](credentials.md#aws-credentials-configuration). + +## AWS cluster parameters + +Follow the [AWS Cluster Parameters guide](cluster-parameters.md#aws-cluster-parameters) diff --git a/docs/dev.md b/docs/dev.md new file mode 100644 index 000000000..90dc35e58 --- /dev/null +++ b/docs/dev.md @@ -0,0 +1,53 @@ +# HMC installation for development + +Below is the example on how to install HMC for development purposes and create +a managed cluster on AWS with k0s for testing. The kind cluster acts as management in this example. + +## Prerequisites + +### Clone HMC repository + +``` +git clone https://github.com/Mirantis/hmc.git && cd hmc +``` + +### Install required CLIs + +Run: + +``` +make cli-install +``` + +### AWS Provider Setup + +Follow the instruction to configure AWS Provider: [AWS Provider Setup](aws/main.md#prepare-the-aws-infra-provider) + +## Deploy HMC + +1. Configure your cluster parameters in `config/dev/deployment.yaml`: + + * Configure the `name` of the deployment + * Change `amiID` and `instanceType` for control plane and worker machines + * Specify the number of control plane and worker machines, etc + +2. Run `make dev-apply` to deploy and configure management cluster + +3. Wait a couple of minutes for management components to be up and running + +4. Run `make dev-aws-apply` to deploy managed cluster on AWS with default configuration + +5. Wait for infrastructure to be provisioned and the cluster to be deployed. You may watch the process with the + `./bin/clusterctl describe` command. Example: + +``` +export KUBECONFIG=~/.kube/config + +./bin/clusterctl describe cluster -n hmc-system --show-conditions all +``` + +6. Retrieve the `kubeconfig` of your managed cluster: + +``` +kubectl --kubeconfig ~/.kube/config get secret -n hmc-system -kubeconfig -o=jsonpath={.data.value} | base64 -d > kubeconfig +```