Skip to content

Commit

Permalink
style(formatting): technical review
Browse files Browse the repository at this point in the history
  • Loading branch information
@christinaausley
christinaausley committed Mar 26, 2024
1 parent 02a0466 commit fa23b59
Showing 1 changed file with 55 additions and 45 deletions.
100 changes: 55 additions & 45 deletions ...-managed/platform-deployment/helm-kubernetes/guides/local-kubernetes-cluster.md
View file
Original file line number Diff line number Diff line change
@@ -1,30 +1,31 @@
---
id: local-kubernetes-cluster
title: "Local Kubernetes Cluster"
description: "Deploy Camunda 8 Self-Managed on Kubernetes local cluster for development purposes using KIND."
title: "Local Kubernetes cluster"
description: "Deploy Camunda 8 Self-Managed on your Kubernetes local cluster for development purposes using kind."
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

You can deploy Camunda 8 Self-Managed on Kubernetes local cluster for development purposes using [KIND](https://kind.sigs.k8s.io/).
You can deploy Camunda 8 Self-Managed on your Kubernetes local cluster for development purposes using [kind](https://kind.sigs.k8s.io/).

In this guide, we will use `KIND`. However, the concept is the same for any other tool like `K3s`, `Minikube`, or `MicroK8s`. The goal in this guide is to reduce the resources required by Camunda components so they can work on a personal machine.
In this guide, we will use **kind**. However, the concept is the same for other tools like K3s, minikube, or MicroK8s. The goal in this guide is to reduce the resources required by Camunda components so they can work on a personal machine.

## Preparation

Based on your system, install the CLI tools used in this guide if you don't already have them:

- [kind](https://kind.sigs.k8s.io/docs/user/quick-start)
- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)
- [helm](https://helm.sh/docs/intro/install/)
- [Helm](https://helm.sh/docs/intro/install/)

## Create a local Kubernetes cluster

At this stage, you should consider how to connect to the future Camunda 8 cluster. If you are setting up Camunda 8 for the first time, we recommend using **port-forwarding**, in which case you may continue to the create KIND cluster.
If you are familiar with Camunda 8 deployment and are looking to start process automation development, consider using Ingress. In this case, complete the Ingress configuration Prerequisites section [Connecting](#connecting-to-camunda-8-components) to Camunda 8 components](#connecting-to-camunda-8-components).
At this stage, you should consider how to connect to the future Camunda 8 cluster. If you are setting up Camunda 8 for the first time, we recommend using **port-forwarding**, in which case you may continue to create kind clusters.

If you have not done it already, create a local Kubernetes cluster with the following command:
If you are familiar with Camunda 8 deployment and are looking to start process automation development, consider using Ingress. In this case, complete the Ingress configuration prerequisites section to [connect to Camunda 8 components](#connecting-to-camunda-8-components).

If you have not done so already, create a local Kubernetes cluster with the following command:

```sh
kind create cluster --name camunda-platform-local
Expand All @@ -38,23 +39,24 @@ kubectl cluster-info --context kind-camunda-platform-local

## Deploy

Now it's time to deploy Camunda 8 on the local Kubernetes cluster.
Now it's time to deploy Camunda 8 on the local Kubernetes cluster:

First, add the Camunda 8 Helm repository using the following command:
1. Add the Camunda 8 Helm repository using the following command:

```
helm repo add camunda https://helm.camunda.io
helm repo update
```

Next, download the Camunda 8 Helm chart values file designed for the KIND cluster: [camunda-platform-core-kind-values.yaml](https://github.com/camunda/camunda-platform-helm/blob/main/kind/camunda-platform-core-kind-values.yaml).
2. Download the Camunda 8 Helm chart values file designed for the kind cluster: [camunda-platform-core-kind-values.yaml](https://github.com/camunda/camunda-platform-helm/blob/main/kind/camunda-platform-core-kind-values.yaml).

:::note
If you are deploying Camunda 8 with Ingress configuration, make sure to add additional values to the file you just downloaded `camunda-platform-core-kind-values.yaml` as described in the [Connecting to Camunda 8 components](#connecting-to-camunda-8-components) section.
If you are deploying Camunda 8 with Ingress configuration, make sure to add additional values to the file you just downloaded `camunda-platform-core-kind-values.yaml` as described in [connecting to Camunda 8 components](#connecting-to-camunda-8-components).
:::

Lastly, install Camunda 8 using the `camunda-platform-core-kind-values.yaml` file downloaded in a previous step. This file might contain additional value if you are adding Ingress, TLS, or using a variety of other configuration properties [Camunda Helm Chart Parameters](https://artifacthub.io/packages/helm/camunda/camunda-platform#parameters) )
Execute the following command:
3. Install Camunda 8 using the `camunda-platform-core-kind-values.yaml` file you downloaded previously. This file might contain additional values if you are adding Ingress, TLS, or using a variety of other configuration properties. See [Camunda Helm chart parameters](https://artifacthub.io/packages/helm/camunda/camunda-platform#parameters).

4. Execute the following command:

```sh
helm install camunda-platform camunda/camunda-platform \
Expand All @@ -63,58 +65,66 @@ helm install camunda-platform camunda/camunda-platform \

This will deploy Camunda 8 components (Optimize, Connectors, and Zeebe), but with a set of parameters tailored to a local environment setup.

Depending on your machine hardware and internet connection speed, the services might take some time to get started since it will download the Docker images of all Camunda 8 components to your local KIND cluster.
Check that each pod is running and ready with `kubectl get pods`. If one or more of your pods are pending for long time, it means it cannot be scheduled onto a node. Usually, this happens because there are insufficient resources that prevent it. Use the `kubectl describe <POD NAME>` command to check its status.
Depending on your machine hardware and internet connection speed, the services might take some time to get started as it will download the Docker images of all Camunda 8 components to your local kind cluster.

5. Check that each pod is running and ready with `kubectl get pods`. If one or more of your pods are pending for long time, it means it cannot be scheduled onto a node. Usually, this happens because there are insufficient resources that prevent it. Use the `kubectl describe <POD NAME>` command to check its status.

## Connecting to Camunda 8 components

Camunda services deployed in a Kubernetes cluster are not accessible from outside the cluster. To connect to your Camunda 8 cluster, you can use either Port-forwarding or Kubernetes Ingress.
Please note, that the setup described here skips Identity setup and uses a default basic authentication with username and password as 'demo/demo'.
Camunda services deployed in a Kubernetes cluster are not accessible from outside the cluster. To connect to your Camunda 8 cluster, use either port-forwarding or Kubernetes Ingress.

:::note
The setup described here skips Identity setup and uses a default basic authentication with username and password as 'demo/demo'.
:::

<Tabs groupId="c8-connectivity">
<TabItem value="port-forward" label="Port-Forwarding">
<Tabs groupId="c8-connectivity" defaultValue="port-forward" queryString values={
[
{label: 'Port-forwarding', value: 'port-forward' },
{label: 'Ingress configuration', value: 'ingress' }
]}>

To interact with the Camunda services inside a Kubernetes cluster without Ingress setup, you can use [kubectl port-forward](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_port-forward/) command to route traffic from your local machine to the services running in the `KIND` cluster. This is useful for quick tests or for development purposes.
<TabItem value="port-forward">

First, port-forward each of the components. Use a separate terminal for each command:
Then each component could be accessed on http://localhost:PORT (e.g., Optimize will have the address http://localhost:8083). A full list of port mapping contains in a helm deployment status i.e. `helm status camunda-platform`
To interact with the Camunda services inside a Kubernetes cluster without Ingress setup, you can use the [kubectl port-forward](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_port-forward/) command to route traffic from your local machine to the services running in the kind cluster. This is useful for quick tests or for development purposes.

### Connecting to the workflow engine
First, port-forward each of the components. Use a separate terminal for each command. Then, each component can be accessed at `http://localhost:PORT` (for example, Optimize will have the address `http://localhost:8083`). A full list of port mapping contains in a Helm deployment status, for example, `helm status camunda-platform`.

To interact with the Camunda workflow engine via Zeebe Gateway using [zbctl](https://docs.camunda.io/docs/apis-tools/cli-client/) or a local client/worker from outside the Kubernetes cluster, run `kubectl port-forward` to the Zeebe gateway as follows:
## Connecting to the workflow engine

To interact with the Camunda workflow engine via Zeebe Gateway using [zbctl](/docs/apis-tools/cli-client/cli-get-started.md) or a local client/worker from outside the Kubernetes cluster, run `kubectl port-forward` to the Zeebe gateway as follows:

```sh
kubectl port-forward svc/camunda-zeebe-gateway 26500:26500
```

:::note
Command `helm status camunda-platform` will print port-forward comand examples for each deployed Camunda 8 component as a reference.
The command `helm status camunda-platform` will print port-forward command examples for each deployed Camunda 8 component as reference.
:::

:::note
To get a full list of the deployed Camunda components and their network properties, run `kubectl get services`. In Kubernetes, a Service is a method for exposing a network application that is running as one or more Pods in your cluster.
To get a full list of the deployed Camunda components and their network properties, run `kubectl get services`. In Kubernetes, a service is a method for exposing a network application that is running as one or more pods in your cluster.
:::

</TabItem>
</TabItem>

<TabItem value="Ingress" label="Ingress Configuration">
<TabItem value="ingress">

Camunda 8 Self-Managed has multiple web applications and gRPC services. Both can be accessed using Kubernetes Ingress.
In this example, we will use a combined ingress configuration. For more information, please refer to the [Combined and separated Ingress setup](https://docs.camunda.io/docs/self-managed/platform-deployment/helm-kubernetes/guides/ingress-setup/) guide.

#### Prerequisites:
In this example, we will use a combined ingress configuration. For more information, refer to [combined and separated Ingress setup](/docs/self-managed/platform-deployment/helm-kubernetes/guides/ingress-setup.md).

## Prerequisites

1. Add local host mapping so that we can resolve the domain name that will be used to access Camunda 8 cluster `camunda.local` to the local IP address `127.0.0.1`.
If you are using Mac or Linux, you need to modify `/etc/hosts` file, for Windows, you need to modify `c:\Windows\System32\Drivers\etc\hosts`. Add following two lines:
1. Add local host mapping so you can resolve the domain name that will be used to access the Camunda 8 cluster `camunda.local` to the local IP address `127.0.0.1`. If you are using Mac or Linux, modify the `/etc/hosts` file. For Windows, modify `c:\Windows\System32\Drivers\etc\hosts`. Add the following two lines:

```sh
127.0.0.1 camunda.local
127.0.0.1 zeebe.camunda.local
```

Now, your OS will resolve `camunda.local` addresses to the local IP address, later in this section, we will connect this IP address to Camunda 8 services running inside of the KIND cluster.
Now, your OS will resolve `camunda.local` addresses to the local IP address. Later in this section, we will connect this IP address to Camunda 8 services running inside the kind cluster.

2. The `KIND` cluster must be created with `extraPortMappings` and `node-labels`. Create `kind.config` file as following:
2. The kind cluster must be created with `extraPortMappings` and `node-labels`. Create a `kind.config` file:

```yaml
kind: Cluster
Expand All @@ -138,30 +148,30 @@ nodes:
hostPort: 18080
```
Modify KIND create cluster command to use the above configuration file. You might need to delete and re-create this cluster if you are planning to enable Ingress (see [Delete KIND cluster](#clean) ):
Modify the `kind create cluster` command to use the above configuration file. You might need to delete and re-create this cluster if you are planning to enable Ingress (see [delete kind cluster](#clean) ):

```sh
kind create cluster --name camunda-platform-local --config kind.config
```

3. Install `ingress-nginx` ingress controller:
3. Install the ingress-nginx Ingress controller:

```sh
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml
```

For more information, please refer to [kind Ingress documenation](https://kind.sigs.k8s.io/docs/user/ingress/#ingress-nginx)
For more information, refer to the [kind Ingress documentation](https://kind.sigs.k8s.io/docs/user/ingress/#ingress-nginx).

:::note
ingress-ngnix controller resources (pods, services, etc) will be deployed into `ingress-nginx` namespace. It may take a few minutes to download container images and configure deployments.
Make sure that all pods are running with `kubectl get pods --namespace ingress-nginx` command before continuing.
ingress-ngnix controller resources (pods, services, etc.) will be deployed into the `ingress-nginx` namespace. It may take a few minutes to download container images and configure deployments.
Make sure all pods are running with the `kubectl get pods --namespace ingress-nginx` command before continuing.
:::

### Ingress configuration in Camunda 8 Helm Charts:
## Ingress configuration in Camunda 8 Helm charts

In this article, we will use the combined Ingress configuration. However, there is one quirk with this particular setup to be aware of - Zeebe Gateway uses gRPC, which uses HTTP/2. This means that Zeebe Gateway has to use its own subdomain `zeebe.camunda.local` instead of context path (i.e `/zeebe`).
In this document, we will use the combined Ingress configuration. However, there is one quirk with this particular setup to be aware of - Zeebe Gateway uses gRPC, which uses HTTP/2. This means the Zeebe Gateway has to use its own subdomain `zeebe.camunda.local` instead of context path (such as `/zeebe`).

Add the following values to the `camunda-platform-core-kind-values.yaml` to allow Camunda 8 components discovered by the Ingress controller.
Add the following values to `camunda-platform-core-kind-values.yaml` to allow Camunda 8 components to be discovered by the Ingress controller.

```yaml
global:
Expand All @@ -183,9 +193,9 @@ ingress:
host: "zeebe.camunda.local"
```

Proceed to install Camunda HELM Chart [Deploy](#deploy)
Proceed to install the Camunda Helm chart [Deploy](#deploy)

</TabItem>
</TabItem>
</Tabs>

## Clean
Expand Down

0 comments on commit fa23b59

Please sign in to comment.