From 2262deee5ae42453558d2dcc9d35bfc935c70b22 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 29 Nov 2024 17:48:37 +0100 Subject: [PATCH] [DPE-5353;DPE-5355] Documentation on AKS and EKS deployments (#155) Co-authored-by: upload-charms-docs-bot --- docs/how-to/h-deploy-aks.md | 100 ++++++++++++++++++++++++--------- docs/how-to/h-deploy-eks.md | 109 +++++++++++++++++++++++++++--------- 2 files changed, 155 insertions(+), 54 deletions(-) diff --git a/docs/how-to/h-deploy-aks.md b/docs/how-to/h-deploy-aks.md index cf779c3b..2557776c 100644 --- a/docs/how-to/h-deploy-aks.md +++ b/docs/how-to/h-deploy-aks.md @@ -3,6 +3,7 @@ [Azure Kubernetes Service](https://learn.microsoft.com/en-us/azure/aks/) (AKS) allows you to quickly deploy a production ready Kubernetes cluster in Azure. To access the AKS Web interface, go to [https://portal.azure.com/](https://portal.azure.com/). ## Summary + * [Install Azure and Juju tooling](#install-client-environment) * [Create AKS Cluster](#create-aks-cluster) * [Bootstrap Juju controller on AKS](#bootstrap-juju-controller-on-aks) @@ -14,12 +15,16 @@ ## Install Client Environment +Client environment includes: +* Juju +* Azure CLI + ### Juju Install Juju via snap: ```shell -sudo snap install juju +sudo snap install juju --channel 3.5/stable ``` Check that the Juju version is correctly installed: @@ -28,11 +33,11 @@ Check that the Juju version is correctly installed: juju version ``` -which should show: - +[details="Sample output:"] ```shell 3.5.2-genericlinux-amd64 ``` +[/details] ### Azure CLI @@ -44,8 +49,7 @@ Verify that it is correctly installed running the command below: az --version ``` -which should show the following output: - +[details="Sample output:"] ```shell azure-cli 2.65.0 @@ -66,33 +70,38 @@ Legal docs and information: aka.ms/AzureCliLegal Your CLI is up-to-date. ``` +[/details] ## Create AKS cluster Login to your Azure account: + ```shell az login ``` -This following examples in this guide will use the single server AKS in location `eastus` - feel free to change this for your own deployment. - Create a new [Azure Resource Group](https://learn.microsoft.com/en-us/cli/azure/manage-azure-groups-azure-cli): ```shell -az group create --name aks --location eastus +az group create --name --location ``` -Export the deployment name for further use: -```shell -export JUJU_NAME=aks-$USER-$RANDOM -``` +The placeholder `` can be a label of your choice, and it will be used to tag +the resources created on Azure. Also the following guide will use the single server AKS, +using `LOCATION=eastus` - but feel free to change this for your own deployment. Bootstrap AKS with the following command (increase nodes count/size if necessary): + ```shell -az aks create -g aks -n ${JUJU_NAME} --enable-managed-identity --node-count 1 --node-vm-size=Standard_D4s_v4 --generate-ssh-keys +az aks create -g -n $ --enable-managed-identity --node-count 1 --node-vm-size= --generate-ssh-keys ``` -Sample output: +[note type="caution"] +We recommend selecting an instance type that provides at the very least `16` GB of RAM and `4` cores, e.g. `Standard_A4_v4`. +You can find more information about the available instance types in the [Azure documentation](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/overview). +[/note] + +[details="Sample output:"] ```yaml { "aadProfile": null, @@ -110,17 +119,20 @@ Sample output: "enableNodePublicIp": false, ... ``` +[/details] Dump newly bootstrapped AKS credentials: + ```shell -az aks get-credentials --resource-group aks --name ${JUJU_NAME} --context aks +az aks get-credentials --resource-group --name --context aks ``` -Sample output: +[details="Sample output:"] ```shell ... Merged "aks" as current context in ~/.kube/config ``` +[/details] You can verify that the cluster and your client `kubectl` CLI is correctly configured by running a simple command, such as: @@ -133,10 +145,12 @@ which should provide the list of the pod services running. ## Bootstrap Juju controller on AKS Bootstrap Juju controller: + ```shell juju bootstrap aks ``` -Sample output: + +[details="Sample output:"] ```shell Creating Juju controller "aks" on aks/eastus Bootstrap to Kubernetes cluster identified as azure/eastus @@ -152,23 +166,28 @@ Now you can run juju add-model to create a new model to deploy k8s workloads. ``` +[/details] ## Deploy Charms Create a new Juju model, if needed: + ```shell juju add-model ``` -> (Optional) Increase the debug level if you are troubleshooting charms: -> ```shell -> juju model-config logging-config='=INFO;unit=DEBUG' -> ``` + +[note type="caution"] +(Optional) Increase the debug level if you are troubleshooting charms: +```shell +juju model-config logging-config='=INFO;unit=DEBUG' +``` +[/note] Then, Charmed Kafka can be deployed as usual: ```shell juju deploy zookeeper-k8s -n3 --channel 3/stable -juju deploy kafka-k8s -n3 --constraints "instance-type=Standard_A4_v2" --channel 3/stable +juju deploy kafka-k8s -n3 --channel 3/stable juju integrate kafka-k8s zookeeper-k8s ``` @@ -191,23 +210,42 @@ For more information on Data Integrator and how to use it, please refer to the [ ## Display deployment information Display information about the current deployments with the following commands: + +```shell +kubectl cluster-info +``` + +[details="Sample output:"] ```shell -~$ kubectl cluster-info Kubernetes control plane is running at https://aks-user-aks-aaaaa-bbbbb.hcp.eastus.azmk8s.io:443 CoreDNS is running at https://aks-user-aks-aaaaa-bbbbb.hcp.eastus.azmk8s.io:443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy Metrics-server is running at https://aks-user-aks-aaaaa-bbbbb.hcp.eastus.azmk8s.io:443/api/v1/namespaces/kube-system/services/https:metrics-server:/proxy +``` +[/details] -~$ az aks list +``` +az aks list +``` +[details="Sample output:"] +```shell ... "count": 1, "currentOrchestratorVersion": "1.28.9", "enableAutoScaling": false, ... +``` +[/details] -~$ kubectl get node +``` +kubectl get node +``` + +[details="Sample output:"] +```shell NAME STATUS ROLES AGE VERSION aks-nodepool1-31246187-vmss000000 Ready agent 11m v1.28.9 ``` +[/details] ## Clean up @@ -220,16 +258,22 @@ To clean the AKS cluster, resources and juju cloud, run the following commands: ```shell juju destroy-controller --destroy-all-models --destroy-storage --force ``` + List all services and then delete those that have an associated EXTERNAL-IP value (load balancers, ...): + ```shell kubectl get svc --all-namespaces -kubectl delete svc +kubectl delete svc ``` + Next, delete the AKS resources (source: [Deleting an all Azure VMs]((https://learn.microsoft.com/en-us/cli/azure/delete-azure-resources-at-scale#delete-all-azure-resources-of-a-type) )) + ```shell -az aks delete -g aks -n ${JUJU_NAME} +az aks delete -g -n ``` -Finally, logout from AKS to clean the local credentials (to avoid forgetting and leaking): + +Finally, logout from AKS to clean the local credentials (to avoid forgetting and getting exposed to a risk of leaking credentials): + ```shell az logout ``` \ No newline at end of file diff --git a/docs/how-to/h-deploy-eks.md b/docs/how-to/h-deploy-eks.md index ead7ef9a..46de9a09 100644 --- a/docs/how-to/h-deploy-eks.md +++ b/docs/how-to/h-deploy-eks.md @@ -3,6 +3,7 @@ [Amazon Elastic Kubernetes Service](https://aws.amazon.com/eks/) (EKS) is a popular, fully automated Kubernetes service. To access the EKS Web interface, go to [console.aws.amazon.com/eks/home](https://console.aws.amazon.com/eks/home). ## Summary + * [Install EKS and Juju tooling](#install-eks-juju) * [Create a new EKS cluster](#create-eks-cluster) * [Bootstrap Juju on EKS](#boostrap-juju) @@ -14,34 +15,61 @@ ## Install EKS and Juju tooling -Install [Juju](https://juju.is/docs/juju/install-juju) and the [`kubectl` CLI tools](https://kubernetes.io/docs/tasks/tools/) via snap: +Install [Juju](https://juju.is/docs/juju/install-juju) and the [`kubectl` CLI tools](https://kubernetes.io/docs/tasks/tools/) (that will be used for managing the Kubernetes cluster) via snap: ```shell -sudo snap install juju +sudo snap install juju --channel 3.5/stable sudo snap install kubectl --classic ``` Follow the installation guides for: + * [eksctl](https://eksctl.io/installation/) - the Amazon EKS CLI * [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - the Amazon Web Services CLI -To check they are all correctly installed, you can run the commands demonstrated below with sample outputs: +To check they are all correctly installed, you can run the commands below. + +```shell +juju version +``` + +[details="Sample output:"] +```shell +3.5.2-genericlinux-amd64 +``` +[/details] ```shell -> juju version -3.1.7-ubuntu-amd64 +kubectl version --client +``` -> kubectl version --client +[details="Sample output:"] +```shell Client Version: v1.28.2 Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3 +``` +[/details] + +```shell +eksctl info +``` -> eksctl info +[details="Sample output:"] +```shell eksctl version: 0.159.0 kubectl version: v1.28.2 +``` +[/details] + +```shell +aws --version +``` -> aws --version +[details="Sample output:"] +```shell aws-cli/2.13.25 Python/3.11.5 Linux/6.2.0-33-generic exe/x86_64.ubuntu.23 prompt/off ``` +[/details] ### Authenticate @@ -53,29 +81,36 @@ AWS Access Key ID [None]: SECRET_ACCESS_KEY_ID AWS Secret Access Key [None]: SECRET_ACCESS_KEY_VALUE Default region name [None]: eu-west-3 Default output format [None]: +``` + +Verify that the CLI tool is correctly authenticating + +```shell +aws sts get-caller-identity +``` -> aws sts get-caller-identity +[details="Sample output:"] +```yaml { "UserId": "1234567890", "Account": "1234567890", "Arn": "arn:aws:iam::1234567890:root" } ``` +[/details] ## Create a new EKS cluster Export the deployment name for further use: + ```shell export JUJU_NAME=eks-$USER-$RANDOM ``` This following examples in this guide will use the location `eu-west-3` and K8s `v.1.27` - feel free to change this for your own deployment. -Sample `cluster.yaml`: - -```shell -~$ cat <<-EOF > cluster.yaml ---- +[details="Sample `cluster.yaml`:"] +```yaml apiVersion: eksctl.io/v1alpha5 kind: ClusterConfig @@ -108,8 +143,8 @@ nodeGroups: onDemandBaseCapacity: 0 onDemandPercentageAboveBaseCapacity: 50 spotInstancePools: 2 -EOF ``` +[/details] Bootstrap EKS cluster with the following command: @@ -117,8 +152,7 @@ Bootstrap EKS cluster with the following command: eksctl create cluster -f cluster.yaml ``` -Sample output: - +[details="Sample `cluster.yaml`:"] ```shell ... 2023-10-12 11:13:58 [ℹ] using region eu-west-3 @@ -126,6 +160,7 @@ Sample output: ... 2023-10-12 11:40:00 [✔] EKS cluster "eks-taurus-27506" in "eu-west-3" region is ready ``` +[/details] ## Bootstrap Juju on EKS @@ -149,10 +184,13 @@ Create a new Juju model, if needed: juju add-model ``` -> (Optional) Increase the debug level if you are troubleshooting charms: -> ```shell -> juju model-config logging-config='=INFO;unit=DEBUG' -> ``` +[note] +(Optional) Increase the debug level if you are troubleshooting charms: + +```shell +juju model-config logging-config='=INFO;unit=DEBUG' +``` +[/note] Then, Charmed Kafka can be deployed as usual: @@ -183,20 +221,39 @@ For more information on Data Integrator and how to use it, please refer to the [ Display information about the current deployments with the following commands: ```shell -~$ kubectl cluster-info +kubectl cluster-info +``` + +[details="Sample output:"] +```shell Kubernetes control plane is running at https://AAAAAAAAAAAAAAAAAAAAAAA.gr7.eu-west-3.eks.amazonaws.com CoreDNS is running at https://AAAAAAAAAAAAAAAAAAAAAAA.gr7.eu-west-3.eks.amazonaws.com/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy +``` +[/details] + +```shell +eksctl get cluster -A +``` -~$ eksctl get cluster -A +[details="Sample output:"] +```shell NAME REGION EKSCTL CREATED eks-marc-9587 eu-west-3 True +``` +[/details] -~$ kubectl get node +```shell +kubectl get node +``` + +[details="Sample output:"] +```shell NAME STATUS ROLES AGE VERSION ip-192-168-1-168.eu-west-3.compute.internal Ready 5d22h v1.27.16-eks-a737599 ip-192-168-45-234.eu-west-3.compute.internal Ready 3h25m v1.27.16-eks-a737599 ip-192-168-85-225.eu-west-3.compute.internal Ready 5d22h v1.27.16-eks-a737599 ``` +[/details] ## Clean up @@ -218,14 +275,14 @@ kubectl get svc --all-namespaces kubectl delete svc ``` -Next, delete the EKS cluster (source: [Deleting an Amazon EKS cluster]((https://docs.aws.amazon.com/eks/latest/userguide/delete-cluster.html) )) +Next, delete the EKS cluster (As described on the [Deleting an Amazon EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/delete-cluster.html) page): ```shell eksctl get cluster -A eksctl delete cluster --region eu-west-3 --force --disable-nodegroup-eviction ``` -Finally, remove AWS CLI user credentials (to avoid forgetting and leaking): +Finally, remove AWS CLI user credentials (to avoid forgetting and getting exposed to a risk of leaking credentials): ```shell rm -f ~/.aws/credentials