Merge pull request #108 from Mirantis/docs

Add documentation describing HMC installation process
Mirantis · Jul 24, 2024 · 97f84e5 · 97f84e5
2 parents df5c12b + 19c9505
commit 97f84e5
Show file tree

Hide file tree

Showing 6 changed files with 329 additions and 57 deletions.
diff --git 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=<admin-user-access-key>
-export AWS_SECRET_ACCESS_KEY=<admin-user-secret-access-key>
-export AWS_SESSION_TOKEN=<session-token> # Optional. If you are using Multi-Factor Auth.
+export KUBECONFIG=<path-to-management-kubeconfig>
+
+helm install hmc oci://ghcr.io/mirantis/hmc/charts/hmc --version <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 <path-to-management-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=<your-access-key>
-export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
-export AWS_SESSION_TOKEN=<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 <path-to-management-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=<path-to-management-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 <deployment-name> -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: <cluster-name>
+  namespace: <cluster-namespace>
+spec:
+  template: <template-name>
+  dryRun: <true/false>
+  config:
+    <cluster-configuration>
 ```
-kubectl --kubeconfig ~/.kube/config get secret -n hmc-system <deployment-name>-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 <deployment-namespace> get deployment.hmc <deployment-name> -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 <deployment-namespace> get cluster <deployment-name> -o=yaml`
+
+> You may also watch the process with the `clusterctl describe` command (requires the `clusterctl` CLI to be installed):
+> ```
+> clusterctl describe cluster <deployment-name> -n <deployment-namespace> --show-conditions all
+> ```
+
+6. Retrieve the `kubeconfig` of your managed cluster:
+
+```
+kubectl get secret -n hmc-system <deployment-name>-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: <cluster-name>
+  namespace: <cluster-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
@@ -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=<aws-region>
+export AWS_ACCESS_KEY_ID=<admin-user-access-key>
+export AWS_SECRET_ACCESS_KEY=<admin-user-secret-access-key>
+export AWS_SESSION_TOKEN=<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
@@ -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
@@ -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=<aws-region>
+export AWS_ACCESS_KEY_ID=<your-access-key>
+export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
+export AWS_SESSION_TOKEN=<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
@@ -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)