-
Notifications
You must be signed in to change notification settings - Fork 69
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
doc: Update helm chart ingress controller setup info (#1386)
* doc: Update helm chart ingress controller setup info * doc: Add sample ingress controllers page * doc: Update helm chart docs * doc: Add redis version requirement detail for the Helm chart * doc: Update location for sample ingress controllers config
- Loading branch information
Showing
6 changed files
with
368 additions
and
115 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -37,12 +37,12 @@ Please [contact our sales team](mailto:[email protected]) for access | |
|
|
||
| {{% tts %}} on Kubernetes requires the following infrastructural services to run. | ||
|
|
||
| 1. A Kubernetes cluster. | ||
| 2. PostgreSQL compatible database. | ||
| 3. Redis compatible database. | ||
| 1. A Kubernetes cluster | ||
| 2. PostgreSQL compatible database | ||
| 3. Redis compatible database (Redis 6.2 or above is required) | ||
| 4. Blob Storage | ||
| 5. Traefik Proxy to handle the ingress routes. | ||
| 6. TLS Certificates. | ||
| 5. An ingress controller to handle the ingress routes | ||
| 6. TLS Certificates | ||
| 7. (Optional) TimescaleDB | ||
| 8. (Optional) Metrics Server | ||
|
|
||
|
|
@@ -111,113 +111,102 @@ $ sudo chown -R 886:886 <blob> | |
|
|
||
| ##### Disabling Blob Storage | ||
|
|
||
| {{% tts %}} Helm Charts by default expects a blob storage configured but it is possible to use {{% tts %}} without it. You can disable the usage of blob by setting `global.interop.configSource` and `global.blob.provider` values to an empty string `""`. | ||
| {{% tts %}} Helm Chart by default expects a blob storage configured but it is possible to use {{% tts %}} without it. You can disable the usage of blob by setting `global.interop.configSource` and `global.blob.provider` values to an empty string `""`. | ||
|
|
||
| #### 5. Traefik Proxy | ||
|
|
||
| The Things Stack Helm Charts currently only supports the [Traefik](https://traefik.io/traefik/) proxy out of the box to load balance incoming traffic. | ||
|
|
||
| To use a custom proxy/load balancer, set `global.ingress.traefik.enabled` to `false`. | ||
|
|
||
| When Traefik is disabled, the ports and routes necessary for The Things Stack should be mapped manually by the operator. | ||
| Check the `ingress-routes.yaml` files for each component and adapt it to your proxy. Setting up and maintaining a custom proxy is out of the scope of this document. | ||
|
|
||
| If Traefik is not used, skip ahead to [setup TLS certificates]({{< ref "enterprise/kubernetes/generic/prerequisites#6-tls-certificates" >}}). | ||
|
|
||
| The simplest way to install Traefik in the kubernetes cluster is use the [official Helm charts](https://artifacthub.io/packages/helm/traefik/traefik). | ||
|
|
||
| The Things Stack ingress routes need to be mapped to the Traefik entry points. This can be done during installation. | ||
|
|
||
| Save the following as a YAML file (example `traefik.values.yaml`) and use that as the values file for Helm. | ||
| #### 5. An ingress controller | ||
|
|
||
| An ingress controller is needed to route the incoming traffic. Specify the ingress controller by setting the `global.ingress.controller` to the class name of the ingress controller deployed in the cluster. For TLS, make sure to set the `global.ingress.controller.tls.secretName`. The secret has to be accessible from the namespace where the {{% tts %}} Helm Chart is deployed. These ports are needed by {{% tts %}} and must be exposed: | ||
|
|
||
| ```yaml | ||
| deployment: | ||
| replicas: 2 | ||
| ports: | ||
| web: # NOTE: This name is predefined in traefik. | ||
| protocol: TCP | ||
| port: 1885 | ||
| expose: true | ||
| exposedPort: 80 | ||
| redirectTo: websecure | ||
| websecure: # NOTE: This name is predefined in traefik. | ||
| protocol: TCP | ||
| port: 8885 | ||
| expose: true | ||
| exposedPort: 443 | ||
| grpc: | ||
| protocol: TCP | ||
| port: 1884 | ||
| expose: true | ||
| exposedPort: 1884 | ||
| grpcsecure: | ||
| protocol: TCP | ||
| port: 8884 | ||
| expose: true | ||
| exposedPort: 8884 | ||
| # Gateway Connectivity | ||
| gtwmqttv2: | ||
| protocol: TCP | ||
| port: 1881 | ||
| expose: true | ||
| exposedPort: 1881 | ||
| gtwmqttv2secure: | ||
| protocol: TCP | ||
| port: 8881 | ||
| expose: true | ||
| exposedPort: 8881 | ||
| gtwmqttv3: | ||
| protocol: TCP | ||
| port: 1882 | ||
| expose: true | ||
| exposedPort: 1882 | ||
| gtwmqttv3secure: | ||
| protocol: TCP | ||
| port: 8882 | ||
| expose: true | ||
| exposedPort: 8882 | ||
| lbs: | ||
| protocol: TCP | ||
| port: 1887 | ||
| expose: true | ||
| exposedPort: 1887 | ||
| lbssecure: | ||
| protocol: TCP | ||
| port: 8887 | ||
| expose: true | ||
| exposedPort: 8887 | ||
| # Application MQTT | ||
| appmqtt: | ||
| protocol: TCP | ||
| port: 1883 | ||
| expose: true | ||
| exposedPort: 1883 | ||
| appmqttsecure: | ||
| protocol: TCP | ||
| port: 8883 | ||
| expose: true | ||
| exposedPort: 8883 | ||
| udp: | ||
| protocol: UDP | ||
| port: 1700 | ||
| expose: true | ||
| exposedPort: 1700 | ||
| # Interoperability. This part is optional. Only enable it if interoperability is needed. | ||
| interop: | ||
| protocol: TCP | ||
| # Note: Change this to 1886 if using `server-only` mode. | ||
| port: 8886 | ||
| expose: true | ||
| exposedPort: 8886 | ||
| web: | ||
| protocol: TCP | ||
| port: 1885 | ||
| exposedPort: 80 | ||
| websecure: | ||
| protocol: TCP | ||
| port: 8885 | ||
| exposedPort: 443 | ||
| grpc: | ||
| protocol: TCP | ||
| port: 1884 | ||
| exposedPort: 1884 | ||
| grpcsecure: | ||
| protocol: TCP | ||
| port: 8884 | ||
| exposedPort: 8884 | ||
| # Gateway Connectivity | ||
| gtwmqttv2: | ||
| protocol: TCP | ||
| port: 1881 | ||
| exposedPort: 1881 | ||
| gtwmqttv2secure: | ||
| protocol: TCP | ||
| port: 8881 | ||
| exposedPort: 8881 | ||
| gtwmqttv3: | ||
| protocol: TCP | ||
| port: 1882 | ||
| exposedPort: 1882 | ||
| gtwmqttv3secure: | ||
| protocol: TCP | ||
| port: 8882 | ||
| exposedPort: 8882 | ||
| lbs: | ||
| protocol: TCP | ||
| port: 1887 | ||
| exposedPort: 1887 | ||
| lbssecure: | ||
| protocol: TCP | ||
| port: 8887 | ||
| exposedPort: 8887 | ||
| # Application MQTT | ||
| appmqtt: | ||
| protocol: TCP | ||
| port: 1883 | ||
| exposedPort: 1883 | ||
| appmqttsecure: | ||
| protocol: TCP | ||
| port: 8883 | ||
| exposedPort: 8883 | ||
| # The Things Indoor Gateway Pro | ||
| ttigw: | ||
| protocol: "TCP" | ||
| port: 1889 | ||
| exposedPort: 1889 | ||
| ttigwsecure: | ||
| protocol: "TCP" | ||
| port: 8889 | ||
| exposedPort: 8889 | ||
| # Interoperability. This part is optional. Only enable it if interoperability is needed. | ||
| interop: | ||
| protocol: TCP | ||
| # Note: Change this to 1886 if using `server-only` mode. | ||
| port: 8886 | ||
| exposedPort: 8886 | ||
| ``` | ||
| ##### Custom Resource Definitions (CRDs) | ||
| Traefik requires the installation of multiple CRDs (Custom Resource Definitions) to run. | ||
| In case annotations are needed for certain protocols or for the {{% tts %}} services, these can be specified under `global.ingress.annotations` and `global.ingress.serviceAnnotations`. E.g. Traefik annotations can be specified as: | ||
| ```yaml | ||
| ingress: | ||
| controller: "traefik" | ||
| tls: | ||
| secretName: "ingress-tls-cert" | ||
| annotations: | ||
| grpc: | ||
| traefik.ingress.kubernetes.io/router.entrypoints: grpcsecure | ||
| traefik.ingress.kubernetes.io/router.tls: "true" | ||
| http: | ||
| traefik.ingress.kubernetes.io/router.entrypoints: websecure | ||
| semtechws: | ||
| traefik.ingress.kubernetes.io/router.entrypoints: semtechwssecure, semtechws | ||
| traefik.ingress.kubernetes.io/router.tls: "true" | ||
| serviceAnnotations: | ||
| traefik.ingress.kubernetes.io/service.serversscheme: h2c | ||
| ``` | ||
|
|
||
| This can be done using `kubectl`. Choose the appropriate CRD file for the version of Traefik that you are using. | ||
| Examples of ingress controllers configurations can be found [here](https://www.thethingsindustries.com/docs/the-things-stack/host/kubernetes/generic/prerequisites/sample-ingress-controllers/). | ||
|
|
||
| If you are using the official [Traefik Helm Chart](https://github.com/traefik/traefik-helm-chart), the CRDs are installed automatically for you. | ||
| {{< note "{{% tts %}} Helm chart uses Kubernetes ingress rules for routing requests to the components of {{% tts %}}. This allows the users of {{% tts %}} Helm chart to configure an ingress controller of their choice. However, Kubernetes ingress routes support only L7 traffic (HTTP/gRPC). For this reason, UDP Packet Forwarder for gateways is not supported in the Helm chart for now." />}} | ||
|
|
||
| #### 6. TLS Certificates | ||
|
|
||
|
|
@@ -233,10 +222,12 @@ Consequently, the TLS certificates used should cover `domain` and one of the fol | |
| - `*.domain` | ||
| - `<default tenant>.domain` | ||
|
|
||
| The Things Stack expects the name of this secret to be set in the value `global.ingress.tls.secretName`. | ||
| The Things Stack expects the name of this secret to be set in the value `global.ingress.tls.secretName`. In case the gateway controller is enabled in the Helm chart, the name of the secret must be set in the value of `global.ttgc.tls.secretName` as well. | ||
|
|
||
| The process of provisioning and maintenance of the certificate secret is left to the operator. | ||
|
|
||
| If the cluster has a custom CA, it must be specified in `global.tls.rootCA`. The certificate must be specified as a base64 encoded x509 certificate. Multiple certificates must be separated by a new line. | ||
|
|
||
| #### 7. (Optional) TimescaleDB | ||
|
|
||
| Both {{% tts %}} [Storage Integration](https://www.thethingsindustries.com/docs/integrations/storage/) and {{% tts %}} [Network Operations Center](https://www.thethingsindustries.com/docs/concepts/architecture/components/network-operations-center/#accessing-network-operations-center) require a TimescaleDB instance. | ||
|
|
||
Oops, something went wrong.