From f80181c5c6c057d3c070d3f136f0ff9d431a5938 Mon Sep 17 00:00:00 2001 From: Saurabh Lohe <105858985+slohe1@users.noreply.github.com> Date: Mon, 11 Sep 2023 07:45:45 +0530 Subject: [PATCH] OPSEXP-1821 Update helm docs with Rancher Desktop deployment (#1003) --- ...op-deployment.md => desktop-deployment.md} | 73 +++++++++---------- 1 file changed, 34 insertions(+), 39 deletions(-) rename docs/helm/{docker-desktop-deployment.md => desktop-deployment.md} (57%) diff --git a/docs/helm/docker-desktop-deployment.md b/docs/helm/desktop-deployment.md similarity index 57% rename from docs/helm/docker-desktop-deployment.md rename to docs/helm/desktop-deployment.md index 1ff2a7750..e3d7707c7 100644 --- a/docs/helm/docker-desktop-deployment.md +++ b/docs/helm/desktop-deployment.md @@ -1,6 +1,6 @@ -# Alfresco Content Services Helm Deployment with Docker For Desktop +# Alfresco Content Services Helm Deployment on local machines -This page describes how to deploy Alfresco Content Services (ACS) Enterprise or Community using [Helm](https://helm.sh) onto [Docker for Desktop](https://docs.docker.com/desktop/). +This page describes how to deploy Alfresco Content Services (ACS) Enterprise or Community using [Helm](https://helm.sh) onto [Rancher Desktop](https://rancherdesktop.io/) and [Docker for Desktop](https://docs.docker.com/desktop/). ## Prerequisites @@ -8,35 +8,32 @@ This page describes how to deploy Alfresco Content Services (ACS) Enterprise or - You've read the [main Helm README](./README.md) page - You are proficient in Kubernetes - A machine with at least 16GB memory -- [Docker for Desktop](https://docs.docker.com/desktop/) for container management installed -- Latest version of [Kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) is installed -- Latest version of [Helm](https://helm.sh/docs/intro/install) is installed +- Having installed either of: + - [Rancher for Desktop](https://rancherdesktop.io/). Includes kubectl and Helm, ready to use right after installation. + - [Docker for Desktop](https://docs.docker.com/desktop/). Requires separate install of kubectl and Helm. -The following instructions are also applicable to [Rancher Desktop](https://rancherdesktop.io/) users. Rancher desktop will provide `kubectl` and `helm` out of the box. it is open source but less mature than Docker desktop. - -## Configure Docker for Desktop - -In order to deploy onto Docker for Desktop we need to configure it with as much CPU and memory as possible on the "Resources" tab in Docker for Desktop's preferences pane as shown in the screenshot below. Similar resource requirement apply to Rancher Desktop. +### Rancher Desktop specific configuration -![Resources](./diagrams/dfd-resources.png) +Uncheck `Enable Traefik` from the `Kubernetes Settings` page to disable the default ingress controller. You may need to exit and restart Rancher Desktop for the change to take effect. Ref: [Setup NGINX Ingress Controller](https://docs.rancherdesktop.io/how-to-guides/setup-NGINX-Ingress-Controller) -### Docker for Desktop specific configuration +### Docker Desktop specific configuration -To deploy the Helm charts Kubernetes needs to be enabled, this can be done from the "Kubernetes" tab, as shown in the screenshot below. Press the "Apply & Restart" button to confirm. +On top of the Docker desktop [Prerequisites](./desktop-deployment.md#Prerequisites), it is essential to install the latest version of [Kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) & [Helm](https://helm.sh/docs/intro/install). -![k8s Enabled](./diagrams/dfd-k8s-enabled.png) +After the installation of Docker Desktop, the following configurations should be adjusted within Docker Desktop settings. -### Rancher Desktop specific configuration +- `Settings > Resources > Advanced > CPUs:8, Memory: 16GB, Swap: 1GB` +- `Settings > kubernetes > Enable Kubernetes` -Uncheck `Enable Traefik` from the `Kubernetes Settings` page to disable Traefik. You may need to exit and restart Rancher Desktop for the change to take effect. Ref: [Setup NGINX Ingress Controller](https://docs.rancherdesktop.io/how-to-guides/setup-NGINX-Ingress-Controller) +After changing the necessary settings `Apply and restart` the docker desktop. -## Deploy +## Deployment -Once Docker for Desktop is running follow the steps in the following sections to deploy ACS (Enterprise or Community) to your local machine. +Please proceed to execute the instructions detailed in the following sections for the installation of ACS (Enterprise or Community edition) on your local system. ### Namespace -Namespaces in Kubernetes isolate workloads from each other, create a namespace to host ACS inside the cluster using the following command (we'll then use the `alfresco` namepsace throughout the rest of the tutorial): +To establish an isolated environment for ACS within the Kubernetes cluster, initiate the creation of a Kubernetes namespace using the provided command. Throughout the subsequent sections of this tutorial, we will consistently refer to this namespace as 'alfresco' ```bash kubectl create namespace alfresco @@ -44,14 +41,14 @@ kubectl create namespace alfresco ### Ingress -Add the chart repository using the following command: +Add the ingress-nginx chart repository: ```bash helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx helm repo update ``` -Deploy an ingress controller into the alfresco namespace using the command below: +Install an ingress-nginx controller within the 'alfresco' namespace: ```bash helm install acs-ingress ingress-nginx/ingress-nginx --version=4.4.0 \ @@ -68,33 +65,31 @@ helm install acs-ingress ingress-nginx/ingress-nginx --version=4.4.0 \ # Verify NGINX is up and running kubectl get pods --namespace alfresco -NAME READY STATUS RESTARTS AGE -acs-ingress-ingress-nginx-controller-77b76b95f7-hf9hq 1/1 Running 0 2m55s +NAME READY STATUS RESTARTS AGE +acs-ingress-ingress-nginx-controller-5647c976f-f7b6q 1/1 Running 0 98m # Verify expose localhost:80 kubectl get svc --namespace alfresco NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -acs-ingress-ingress-nginx-controller-admission ClusterIP 10.43.244.72 443/TCP 69m -acs-ingress-ingress-nginx-controller LoadBalancer 10.43.182.81 192.168.1.146 80:31155/TCP,443:32209/TCP 69m +acs-ingress-ingress-nginx-controller-admission ClusterIP 10.43.42.230 443/TCP 98m +acs-ingress-ingress-nginx-controller LoadBalancer 10.43.90.117 192.168.29.69 80:31363/TCP,443:30980/TCP 98m ``` ### ACS -This repository allows you to either deploy a system using released stable artifact or the latest in-progress development artifacts. +This repository offers you the option to either deploy a system using stable released artifacts or the latest in-progress development artifacts. -To use a released version of the Helm chart add the stable chart repository using the following command: +To use a released version of the Helm chart add the stable chart repository: ```bash helm repo add alfresco https://kubernetes-charts.alfresco.com/stable helm repo update ``` -Now decide whether you want to install the Community or Enterprise edition and follow the steps in the relevant section below. - -#### Community +#### Community localhost deployment -To install the latest version of Community we need to use the [community_values.yaml file](../../helm/alfresco-content-services). Once downloaded execute the command below to deploy. +To install the latest version of Community we need to download the [community_values.yaml file](../../helm/alfresco-content-services). Once downloaded, execute the following to initiate the deployment. ```bash helm install acs alfresco/alfresco-content-services \ @@ -109,8 +104,8 @@ helm install acs alfresco/alfresco-content-services \ #### Enterprise localhost deployment -See the [registry authentication](registry-authentication.md) page to configure -credentials to access the Alfresco Enterprise registry. +ACS enterprise version needs to pull container images from private image repositories. +To configure credentials for accessing the Alfresco Enterprise registry, please review the information provided in the [registry authentication](registry-authentication.md) The Enterprise Helm deployment is intended for a Cloud based Kubernetes cluster and therefore requires a large amount of resources out-of-the-box. To reduce the @@ -123,7 +118,7 @@ To install the Enterprise on localhost we need to use the local-dev-values.yaml curl -fO https://raw.githubusercontent.com/Alfresco/acs-deployment/master/docs/helm/values/local-dev-values.yaml ``` -Once downloaded execute the command below to deploy. +Once downloaded, execute the following to initiate the deployment. ```bash helm install acs alfresco/alfresco-content-services \ @@ -134,16 +129,16 @@ helm install acs alfresco/alfresco-content-services \ --namespace alfresco ``` -> NOTE: The command will wait until the deployment is ready so please be patient. See below for [troubleshooting](./docker-desktop-deployment.md#troubleshooting) tips. +> NOTE: The command will wait until the deployment is ready so please be patient. See below for [troubleshooting](#troubleshooting) tips. -The command above installs the latest version of ACS Enterprise. +The `helm` command above installs the most current released version of ACS Enterprise. #### Enterprise deployment for previous versions To deploy a previous version of ACS Enterprise follow the steps below. 1. Download the version specific values file you require from [this folder](../../helm/alfresco-content-services) -2. Deploy the specific version of ACS by running the following command: +2. Deploying the specific version of ACS can be achieved by executing the following: ```bash helm install acs alfresco/alfresco-content-services \ @@ -185,11 +180,11 @@ If you deployed Enterprise you'll also have access to: ## Troubleshooting -If your deployment fails it's most likely to be caused by resource limitations, please refer to the sections below for more information. Please also consult the [Helm Troubleshooting section](./README.md#Troubleshooting) for more generic troubleshooting tips and tricks. +In the event of a deployment failure, it is important to recognize that resource constraints are a common underlying cause. For further insights and guidance. Additionally, you can find more comprehensive troubleshooting advice in the [Helm Troubleshooting section](./README.md#Troubleshooting) ### Lack Of Resources -The most common reason for deployment failures with Docker for Desktop is lack of memory or disk space. Check the "Resources" tab in Docker for Desktop's preferences pane, increase the allocation if you can and re-try. +One of the most prevalent causes of deployment failures is insufficient memory or CPU resources. It is imperative to ensure that an adequate amount of resources is allocated to prevent deployment failures. To save the deployment of two more pods you can also try disabling the Sync Service, to do that provide the additional `--set` option below with your helm install command: