From 179a37a048feb04b144c4bf44ef776705aee0bc8 Mon Sep 17 00:00:00 2001 From: Fabian Gruen Date: Wed, 7 Feb 2024 17:06:42 +0100 Subject: [PATCH 1/2] chore: add how to set up cluster info from webpage to our repo --- .../how-to-setup-aks-cluster-via-terraform.md | 118 ++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 docs/how-to-setup-aks-cluster-via-terraform.md diff --git a/docs/how-to-setup-aks-cluster-via-terraform.md b/docs/how-to-setup-aks-cluster-via-terraform.md new file mode 100644 index 0000000..0bf7d61 --- /dev/null +++ b/docs/how-to-setup-aks-cluster-via-terraform.md @@ -0,0 +1,118 @@ +# How to setup and AKS cluster via terraform + +:exclamation: This is partly outdated information please see our general [README.md](../README.md) + +This guide is only for those who operate the environment + +This how-to will guide you through the setup of a new AKS cluster via terraform. It is based on the terraform scripts in +our [k8s-cluster-stack](https://github.com/catenax-ng/k8s-cluster-stack) repository. + +## Prerequisites + +Terraform is run by CLI on your local machine. We are not using any Pipelines for that. Therefor you need to install the +terraform CLI for your operating system either by package manager for your OS, or by downloadable installer +from [https://www.terraform.io/downloads](https://www.terraform.io/downloads). You can verify your installation by +running a command like `terraform --version` from your terminal. + +We assign service principals to our AKS clusters, that we can later use as technical user for the connection from our +core ArgoCD instance. If you do not already have a service principal, that you want to use, you can create one with the +following commands: + +```shell +# Logging in with your personal Azure account +az login --tenant catenax.onmicrosoft.com +# Creating a service principal, without assigning it to any resources/roles yet. +az ad sp create-for-rbac --skip-assignment +``` + +You'll need the 'client id' and 'secret id' values later on. + +## Terraform state + +Terraform uses [`state`](https://www.terraform.io/language/state) to track status and differences of your real world +resources and your configuration. While being very useful in most situation, we actively decided to NOT manage/save the +terraform state to track our AKS cluster resources. We think, that sharing and storing the state file is too much of an +effort. + +In our case of demonstration environments the impact of recreating the cluster from scratch and deploying all the tools +and apps is not too high. + +## Creating the AKS cluster + +The following steps show you how to... + +- initialize terraform +- create a terraform plan +- apply that plan to your Azure subscription + +It is assumed, that before running any terraform commands, you cloned +the [k8s-cluster-stack](https://github.com/catenax-ng/k8s-cluster-stack) +repository. You should then open a terminal session and navigate to the repository path. + +For the following instructions it is also assumed, that you already navigated to the AKS related terraform directory, +which is at `/terraform/01_core_cluster/` in the repository. + +### Removing existing terraform config + +We always run the AKS cluster creation from a clean working directory. So in case you did run any terraform commands +before, there are some files, that could disturb the clean run. To get rid of these files remove state files, plans and +the .terraform directory + +```shell +rm *.tfstate* +rm *.tfplan +rm -rf .terraform +``` + +### Initialize terraform + +Before you can create or apply a terraform plan, you have to [initialize](https://www.terraform.io/cli/commands/init) +the terraform working directory by running `terraform init`. + +This will initialize the necessary modules and download plugins for the used providers. + +### Creating and applying the terraform plan + +A [terraform plan](https://www.terraform.io/cli/commands/plan) is an execution plan that will give you a preview about +the changes to your infrastructure. As input for the plan, you'll need to specify a set of variable values. Most of the +variables are already set with sane defaults. A mandatory variable, that you need to specify is `environment_name`. To +set this variable, create a file named after the environment you want to create with the ending '.tfvars' in the +`01_core_cluster/environments/` directory. The value is specified as key-value-pair. Another useful variable that you +can set is `k8s_vm_size`, which will specify the Azure specific VM type, that is used for the k8s nodes. + +An example tfvars file could look like the following: + +```hcl +# Example terraform AKS environment variable specification +# /terraform/01_core_cluster/core.tfvars +environment_name = "core" +k8s_vm_size = "Standard_D8s_v4" +``` + +Beside these variables, that you can safely commit to the repository, you also need to specify the client id and client +secret of the service principal, that should be assigned to the cluster. For this kind of variable, terraform provides +a way to set specific environment variables, that have to be of the form +`TF_VAR_`. You can set the service principal config like follows: + +```shell +export TF_VAR_service_principal_client_id= +export TF_VAR_service_principal_client_secret= +``` + +With the variables specified in your tfvars and the service principal config set via environment variable, you can +create the plan and apply it to Azure with the following command: + +```shell +# replace with the actual name of the environment you chose +terraform plan -var-file=environments/.tfvars -out .plan +terraform apply .plan +``` + +## Verifying the AKS resources are created + +If you successfully applied the terraform plan, you will find a resource group with the naming pattern `cx--rg` +in your subscription in the [Azure portal](https://portal.azure.com/). Part of that resource group will be your newly +created AKS cluster. + +You will also find a public IP with the naming pattern `cx--public-ip` in a slightly different resource group, +that Azure created automatically for the kubernetes nodes pool. From 22e0f6c489ea4f8c5e8cd3311b541296a5085708 Mon Sep 17 00:00:00 2001 From: Fabian Gruen Date: Fri, 9 Feb 2024 11:14:11 +0100 Subject: [PATCH 2/2] docs: rm state info + add dedicated link how to create new cluster --- .../how-to-setup-aks-cluster-via-terraform.md | 26 ++----------------- 1 file changed, 2 insertions(+), 24 deletions(-) diff --git a/docs/how-to-setup-aks-cluster-via-terraform.md b/docs/how-to-setup-aks-cluster-via-terraform.md index 0bf7d61..4e8ac11 100644 --- a/docs/how-to-setup-aks-cluster-via-terraform.md +++ b/docs/how-to-setup-aks-cluster-via-terraform.md @@ -1,6 +1,6 @@ # How to setup and AKS cluster via terraform -:exclamation: This is partly outdated information please see our general [README.md](../README.md) +:exclamation: This is partly outdated information please see our general [README.md#create-a-new-environment](../README.md#create-a-new-environment) This guide is only for those who operate the environment @@ -27,16 +27,6 @@ az ad sp create-for-rbac --skip-assignment You'll need the 'client id' and 'secret id' values later on. -## Terraform state - -Terraform uses [`state`](https://www.terraform.io/language/state) to track status and differences of your real world -resources and your configuration. While being very useful in most situation, we actively decided to NOT manage/save the -terraform state to track our AKS cluster resources. We think, that sharing and storing the state file is too much of an -effort. - -In our case of demonstration environments the impact of recreating the cluster from scratch and deploying all the tools -and apps is not too high. - ## Creating the AKS cluster The following steps show you how to... @@ -46,24 +36,12 @@ The following steps show you how to... - apply that plan to your Azure subscription It is assumed, that before running any terraform commands, you cloned -the [k8s-cluster-stack](https://github.com/catenax-ng/k8s-cluster-stack) +the [cloud-infra](https://github.com/catenax-ng/cloud-infra) repository. You should then open a terminal session and navigate to the repository path. For the following instructions it is also assumed, that you already navigated to the AKS related terraform directory, which is at `/terraform/01_core_cluster/` in the repository. -### Removing existing terraform config - -We always run the AKS cluster creation from a clean working directory. So in case you did run any terraform commands -before, there are some files, that could disturb the clean run. To get rid of these files remove state files, plans and -the .terraform directory - -```shell -rm *.tfstate* -rm *.tfplan -rm -rf .terraform -``` - ### Initialize terraform Before you can create or apply a terraform plan, you have to [initialize](https://www.terraform.io/cli/commands/init)