Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(ingress-nginx): correct nginx mentionings and replace NGINX Ingress usage #3147

Merged
merged 5 commits into from
Jan 4, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Camunda 8 Helm chart doesn't manage or deploy Ingress controllers, it only deplo

## Preparation

- An Ingress controller should be deployed in advance. The examples below use `Nginx` Ingress controller, but any Ingress controller could be used by setting `ingress.className`.
- An Ingress controller should be deployed in advance. The examples below use the [ingress-nginx Controller](https://github.com/kubernetes/ingress-nginx), but any Ingress controller could be used by setting `ingress.className`.
- TLS configuration is not handled in the examples because it varies between different workflows. It could be configured directly using `ingress.tls` options or via an external tool like [Cert-Manager](https://github.com/cert-manager/cert-manager) using `ingress.annotations`. For more details, check available [configuration options](https://github.com/camunda/camunda-platform-helm/tree/main/charts/camunda-platform#configuration).

## Combined Ingress setup
Expand Down Expand Up @@ -191,21 +191,31 @@ Ingress resources require the cluster to have an [Ingress Controller](https://ku

### Example local configuration

An Ingress Controller is also required when working a local Camunda 8 installation. Take a look at an Ingress Controller configuration using the [Nginx Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/):
An Ingress Controller is also required when working on a local Camunda 8 installation. Take a look at an Ingress Controller configuration using the [ingress-nginx Controller](https://kubernetes.github.io/ingress-nginx/deploy/#bare-metal-clusters/):

```yaml
# nginx_ingress_values.yml
# ingress_nginx_values.yml
controller:
replicaCount: 1
hostNetwork: true
updateStrategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 1
service:
type: NodePort

publishService:
enabled: false
```

To install this Ingress Controller to your local cluster, execute the following command:
To install this [ingress-nginx Controller](https://github.com/kubernetes/ingress-nginx) to your local cluster, execute the following command:

```shell
helm install -f nginx_ingress_values.yaml nginx-ingress oci://ghcr.io/nginxinc/charts/nginx-ingress --version 0.18.0
helm install -f ingress_nginx_values.yml \
ingress-nginx ingress-nginx \
--repo https://kubernetes.github.io/ingress-nginx \
--version "4.9.0" \
--namespace ingress-nginx \
--create-namespace
```

## Troubleshooting
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,4 +30,4 @@ It's recommended to use `Performance (SSD) persistent disks` volume type with at

### Zeebe Ingress

Zeebe requires an Ingress controller that supports `gRPC`, so if you are using [GKE Ingress](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress) (ingress-gce), not Nginx Ingress, you might need to do extra steps. Namely, using `cloud.google.com/app-protocols` annotation in Zeebe Service. For more details, visit the GKE guide [using HTTP/2 for load balancing with Ingress](https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-http2).
Zeebe requires an Ingress controller that supports `gRPC`, so if you are using [GKE Ingress](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress) (ingress-gce), not [ingress-nginx](https://github.com/kubernetes/ingress-nginx), you might need to do extra steps. Namely, using `cloud.google.com/app-protocols` annotation in Zeebe Service. For more details, visit the GKE guide [using HTTP/2 for load balancing with Ingress](https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-http2).
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,6 @@ should use `Premium SSD` volumes of at least `256 GB` (P15).

### Zeebe Ingress

**Azure Application Gateway Ingress cannot be used as an Ingress for Zeebe/Zeebe-Gateway** because Zeebe requires an Ingress controller that supports `gRPC`. You should use any other Ingress controller that supports `gRPC`, like the [Ingress-NGINX controller](https://github.com/kubernetes/ingress-nginx).
**Azure Application Gateway Ingress cannot be used as an Ingress for Zeebe/Zeebe-Gateway** because Zeebe requires an Ingress controller that supports `gRPC`. You should use any other Ingress controller that supports `gRPC`, like the [ingress-nginx controller](https://github.com/kubernetes/ingress-nginx).

Currently, the Azure Application Gateway Ingress controller doesn't support `gRPC`. For more details, follow the upstream [GitHub issue about gRPC/HTTP2 support](https://github.com/Azure/application-gateway-kubernetes-ingress/issues/1015).
Original file line number Diff line number Diff line change
Expand Up @@ -269,7 +269,15 @@ To use these routes for the Zeebe Gateway, configure this through Ingress as wel

### Alternatives

An alternative is to install the Ingress Controller of choice and use this instead; for example, [NGINX](https://www.redhat.com/en/blog/using-nginx-ingress-controller-red-hat-openshift).
An alternative to using [routes](https://docs.openshift.com/container-platform/4.14/networking/routes/route-configuration.html) is to install and use one of the Kubernetes Ingress Controllers instead, for example, the [ingress-nginx Controller](https://github.com/kubernetes/ingress-nginx).

:::warning

Do not confuse the [ingress-nginx Controller](https://github.com/kubernetes/ingress-nginx) with the [NGINX Ingress Controller](https://www.redhat.com/en/blog/using-nginx-ingress-controller-red-hat-openshift) that is endorsed by Red Hat for usage with OpenShift. Despite very similar names, they are two different products.

If you should decide to use the Rad Hat endorsed [NGINX Ingress Controller](https://www.redhat.com/en/blog/using-nginx-ingress-controller-red-hat-openshift), you would require additional adjustments done to the Camunda 8 ingress objects and the NGINX Ingress Controlle itself, to make `gRPC` and `HTTP/2` connections work. In that case, please refer to the [example and the prerequisites](https://github.com/nginxinc/kubernetes-ingress/blob/main/examples/ingress-resources/grpc-services/README.md).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like there is a typo here, but Rad Hat sounds like a sweet company name 😆


:::

### Prerequisite

Expand Down
4 changes: 2 additions & 2 deletions docs/self-managed/platform-deployment/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,14 +36,14 @@ global:

Zeebe requires an Ingress controller that supports `gRPC` which is built on top of `HTTP/2` transport layer. Therefore, to expose Zeebe-Gateway externally, you need the following:

1. An Ingress controller that supports `gRPC` ([Ingress-NGINX controller](https://github.com/kubernetes/ingress-nginx) supports it out of the box).
1. An Ingress controller that supports `gRPC` ([ingress-nginx controller](https://github.com/kubernetes/ingress-nginx) supports it out of the box).
2. TLS (HTTPS) via [Application-Layer Protocol Negotiation (ALPN)](https://www.rfc-editor.org/rfc/rfc7301.html) enabled in the Zeebe-Gateway Ingress object.

However, according to the official Kubernetes documentation about [Ingress TLS](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls):

> There is a gap between TLS features supported by various Ingress controllers. Please refer to documentation on nginx, GCE, or any other platform specific Ingress controller to understand how TLS works in your environment.

Therefore, if you are not using the [Ingress-NGINX controller](https://github.com/kubernetes/ingress-nginx), ensure you pay attention to TLS configuration of the Ingress controller of your choice. Find more details about the Zeebe Ingress setup in the [Kubernetes platforms supported by Camunda](./helm-kubernetes/platforms/platforms.md).
Therefore, if you are not using the [ingress-nginx controller](https://github.com/kubernetes/ingress-nginx), ensure you pay attention to TLS configuration of the Ingress controller of your choice. Find more details about the Zeebe Ingress setup in the [Kubernetes platforms supported by Camunda](./helm-kubernetes/platforms/platforms.md).

## Identity `contextPath`

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Camunda 8 Helm chart doesn't manage or deploy Ingress controllers, it only deplo

## Preparation

- An Ingress controller should be deployed in advance. The examples below use `Nginx` Ingress controller, but any Ingress controller could be used by setting `ingress.className`.
- An Ingress controller should be deployed in advance. The examples below use the [ingress-nginx Controller](https://github.com/kubernetes/ingress-nginx), but any Ingress controller could be used by setting `ingress.className`.
- TLS configuration is not handled in the examples because it varies between different workflows. It could be configured directly using `ingress.tls` options or via an external tool like [Cert-Manager](https://github.com/cert-manager/cert-manager) using `ingress.annotations`. For more details, check available [configuration options](https://github.com/camunda/camunda-platform-helm/tree/main/charts/camunda-platform#configuration).

## Combined Ingress setup
Expand Down Expand Up @@ -183,21 +183,31 @@ Ingress resources require the cluster to have an [Ingress Controller](https://ku

### Example local configuration

An Ingress Controller is also required when working a local Camunda 8 installation. Take a look at an Ingress Controller configuration using the [Nginx Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/):
An Ingress Controller is also required when working on a local Camunda 8 installation. Take a look at an Ingress Controller configuration using the [ingress-nginx Controller](https://kubernetes.github.io/ingress-nginx/deploy/#bare-metal-clusters/):

```yaml
# nginx_ingress_values.yml
# ingress_nginx_values.yml
controller:
replicaCount: 1
hostNetwork: true
updateStrategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 1
service:
type: NodePort

publishService:
enabled: false
```

To install this Ingress Controller to your local cluster, execute the following command:
To install this [ingress-nginx Controller](https://github.com/kubernetes/ingress-nginx) to your local cluster, execute the following command:

```shell
helm install -f nginx_ingress_values.yaml nginx-ingress oci://ghcr.io/nginxinc/charts/nginx-ingress --version 0.18.0
helm install -f ingress_nginx_values.yml \
ingress-nginx ingress-nginx \
--repo https://kubernetes.github.io/ingress-nginx \
--version "4.9.0" \
--namespace ingress-nginx \
--create-namespace
```

## Troubleshooting
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,4 +30,4 @@ It's recommended to use `Performance (SSD) persistent disks` volume type with at

### Zeebe Ingress

Zeebe requires an Ingress controller that supports `gRPC`, so if you are using [GKE Ingress](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress) (ingress-gce), not Nginx Ingress, you might need to do extra steps. Namely, using `cloud.google.com/app-protocols` annotation in Zeebe Service. For more details, visit the GKE guide [using HTTP/2 for load balancing with Ingress](https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-http2).
Zeebe requires an Ingress controller that supports `gRPC`, so if you are using [GKE Ingress](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress) (ingress-gce), not [ingress-nginx](https://github.com/kubernetes/ingress-nginx), you might need to do extra steps. Namely, using `cloud.google.com/app-protocols` annotation in Zeebe Service. For more details, visit the GKE guide [using HTTP/2 for load balancing with Ingress](https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-http2).
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,6 @@ should use `Premium SSD` volumes of at least `256 GB` (P15).

### Zeebe Ingress

**Azure Application Gateway Ingress cannot be used as an Ingress for Zeebe/Zeebe-Gateway** because Zeebe requires an Ingress controller that supports `gRPC`. You should use any other Ingress controller that supports `gRPC`, like the [Ingress-NGINX controller](https://github.com/kubernetes/ingress-nginx).
**Azure Application Gateway Ingress cannot be used as an Ingress for Zeebe/Zeebe-Gateway** because Zeebe requires an Ingress controller that supports `gRPC`. You should use any other Ingress controller that supports `gRPC`, like the [ingress-nginx controller](https://github.com/kubernetes/ingress-nginx).

Currently, the Azure Application Gateway Ingress controller doesn't support `gRPC`. For more details, follow the upstream [GitHub issue about gRPC/HTTP2 support](https://github.com/Azure/application-gateway-kubernetes-ingress/issues/1015).
Original file line number Diff line number Diff line change
Expand Up @@ -272,7 +272,15 @@ To use these routes for the Zeebe Gateway, configure this through Ingress as wel

### Alternatives

An alternative is to install the Ingress Controller of choice and use this instead; for example, [NGINX](https://www.redhat.com/en/blog/using-nginx-ingress-controller-red-hat-openshift).
An alternative to using [routes](https://docs.openshift.com/container-platform/4.14/networking/routes/route-configuration.html) is to install and use one of the Kubernetes Ingress Controllers instead, for example, the [ingress-nginx Controller](https://github.com/kubernetes/ingress-nginx).

:::warning

Do not confuse the [ingress-nginx Controller](https://github.com/kubernetes/ingress-nginx) with the [NGINX Ingress Controller](https://www.redhat.com/en/blog/using-nginx-ingress-controller-red-hat-openshift) that is endorsed by Red Hat for usage with OpenShift. Despite very similar names, they are two different products.

If you should decide to use the Rad Hat endorsed [NGINX Ingress Controller](https://www.redhat.com/en/blog/using-nginx-ingress-controller-red-hat-openshift), you would require additional adjustments done to the Camunda 8 ingress objects and the NGINX Ingress Controlle itself, to make `gRPC` and `HTTP/2` connections work. In that case, please refer to the [example and the prerequisites](https://github.com/nginxinc/kubernetes-ingress/blob/main/examples/ingress-resources/grpc-services/README.md).

:::

### Prerequisite

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,14 +40,14 @@ Changing this property after the initial install will require manual corrections

Zeebe requires an Ingress controller that supports `gRPC` which is built on top of `HTTP/2` transport layer. Therefore, to expose Zeebe-Gateway externally, you need the following:

1. An Ingress controller that supports `gRPC` ([Ingress-NGINX controller](https://github.com/kubernetes/ingress-nginx) supports it out of the box).
1. An Ingress controller that supports `gRPC` ([ingress-nginx controller](https://github.com/kubernetes/ingress-nginx) supports it out of the box).
2. TLS enabled (HTTPS) in the Zeebe-Gateway Ingress object.

However, according to the official Kubernetes documentation about [Ingress TLS](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls):

> There is a gap between TLS features supported by various Ingress controllers. Please refer to documentation on nginx, GCE, or any other platform specific Ingress controller to understand how TLS works in your environment.

Therefore, if you are not using the [Ingress-NGINX controller](https://github.com/kubernetes/ingress-nginx), ensure you pay attention to TLS configuration of the Ingress controller of your choice. Find more details about the Zeebe Ingress setup in the [Kubernetes platforms supported by Camunda](./helm-kubernetes/platforms/platforms.md).
Therefore, if you are not using the [ingress-nginx controller](https://github.com/kubernetes/ingress-nginx), ensure you pay attention to TLS configuration of the Ingress controller of your choice. Find more details about the Zeebe Ingress setup in the [Kubernetes platforms supported by Camunda](./helm-kubernetes/platforms/platforms.md).

## Identity `contextPath`

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Camunda 8 Helm chart doesn't manage or deploy Ingress controllers, it only deplo

## Preparation

- An Ingress controller should be deployed in advance. The examples below use `Nginx` Ingress controller, but any Ingress controller could be used by setting `ingress.className`.
- An Ingress controller should be deployed in advance. The examples below use the [ingress-nginx Controller](https://github.com/kubernetes/ingress-nginx), but any Ingress controller could be used by setting `ingress.className`.
- TLS configuration is not handled in the examples because it varies between different workflows. It could be configured directly using `ingress.tls` options or via an external tool like [Cert-Manager](https://github.com/cert-manager/cert-manager) using `ingress.annotations`. For more details, check available [configuration options](https://github.com/camunda/camunda-platform-helm/tree/main/charts/camunda-platform#configuration).

## Combined Ingress setup
Expand Down Expand Up @@ -191,21 +191,31 @@ Ingress resources require the cluster to have an [Ingress Controller](https://ku

### Example local configuration

An Ingress Controller is also required when working a local Camunda 8 installation. Take a look at an Ingress Controller configuration using the [Nginx Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/):
An Ingress Controller is also required when working on a local Camunda 8 installation. Take a look at an Ingress Controller configuration using the [ingress-nginx Controller](https://kubernetes.github.io/ingress-nginx/deploy/#bare-metal-clusters/):

```yaml
# nginx_ingress_values.yml
# ingress_nginx_values.yml
controller:
replicaCount: 1
hostNetwork: true
updateStrategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 1
service:
type: NodePort

publishService:
enabled: false
```

To install this Ingress Controller to your local cluster, execute the following command:
To install this [ingress-nginx Controller](https://github.com/kubernetes/ingress-nginx) to your local cluster, execute the following command:

```shell
helm install -f nginx_ingress_values.yaml nginx-ingress oci://ghcr.io/nginxinc/charts/nginx-ingress --version 0.18.0
helm install -f ingress_nginx_values.yml \
ingress-nginx ingress-nginx \
--repo https://kubernetes.github.io/ingress-nginx \
--version "4.9.0" \
--namespace ingress-nginx \
--create-namespace
```

## Troubleshooting
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,4 +30,4 @@ It's recommended to use `Performance (SSD) persistent disks` volume type with at

### Zeebe Ingress

Zeebe requires an Ingress controller that supports `gRPC`, so if you are using [GKE Ingress](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress) (ingress-gce), not Nginx Ingress, you might need to do extra steps. Namely, using `cloud.google.com/app-protocols` annotation in Zeebe Service. For more details, visit the GKE guide [using HTTP/2 for load balancing with Ingress](https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-http2).
Zeebe requires an Ingress controller that supports `gRPC`, so if you are using [GKE Ingress](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress) (ingress-gce), not [ingress-nginx](https://github.com/kubernetes/ingress-nginx), you might need to do extra steps. Namely, using `cloud.google.com/app-protocols` annotation in Zeebe Service. For more details, visit the GKE guide [using HTTP/2 for load balancing with Ingress](https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-http2).
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,6 @@ should use `Premium SSD` volumes of at least `256 GB` (P15).

### Zeebe Ingress

**Azure Application Gateway Ingress cannot be used as an Ingress for Zeebe/Zeebe-Gateway** because Zeebe requires an Ingress controller that supports `gRPC`. You should use any other Ingress controller that supports `gRPC`, like the [Ingress-NGINX controller](https://github.com/kubernetes/ingress-nginx).
**Azure Application Gateway Ingress cannot be used as an Ingress for Zeebe/Zeebe-Gateway** because Zeebe requires an Ingress controller that supports `gRPC`. You should use any other Ingress controller that supports `gRPC`, like the [ingress-nginx controller](https://github.com/kubernetes/ingress-nginx).

Currently, the Azure Application Gateway Ingress controller doesn't support `gRPC`. For more details, follow the upstream [GitHub issue about gRPC/HTTP2 support](https://github.com/Azure/application-gateway-kubernetes-ingress/issues/1015).
Loading
Loading