From d92fc43f82c27693666af2b76589bd46fb5b0731 Mon Sep 17 00:00:00 2001 From: Aleksander Borowski Date: Fri, 24 Nov 2023 17:07:46 +0100 Subject: [PATCH] doc: Add Azure kubernetes section --- .../host/kubernetes/azure/_index.md | 11 ++ .../kubernetes/azure/configuration/_index.md | 76 +++++++++ .../kubernetes/azure/deployment/_index.md | 148 ++++++++++++++++++ .../kubernetes/azure/prerequisites/_index.md | 31 ++++ .../azure/troubleshooting/_index.md | 8 + .../host/kubernetes/preparation/_index.md | 39 ----- .../host/kubernetes/self-managed/_index.md | 9 ++ .../configuration/_index.md | 3 + .../database-migrations/_index.md | 0 .../install-charts/_index.md | 2 + .../{ => self-managed}/monitoring/_index.md | 2 + .../self-managed/preparation/_index.md | 41 +++++ .../prerequisites/_index.md | 6 +- .../troubleshooting/_index.md | 5 +- 14 files changed, 339 insertions(+), 42 deletions(-) create mode 100644 doc/content/the-things-stack/host/kubernetes/azure/_index.md create mode 100644 doc/content/the-things-stack/host/kubernetes/azure/configuration/_index.md create mode 100644 doc/content/the-things-stack/host/kubernetes/azure/deployment/_index.md create mode 100644 doc/content/the-things-stack/host/kubernetes/azure/prerequisites/_index.md create mode 100644 doc/content/the-things-stack/host/kubernetes/azure/troubleshooting/_index.md delete mode 100644 doc/content/the-things-stack/host/kubernetes/preparation/_index.md create mode 100644 doc/content/the-things-stack/host/kubernetes/self-managed/_index.md rename doc/content/the-things-stack/host/kubernetes/{ => self-managed}/configuration/_index.md (98%) rename doc/content/the-things-stack/host/kubernetes/{ => self-managed}/database-migrations/_index.md (100%) rename doc/content/the-things-stack/host/kubernetes/{ => self-managed}/install-charts/_index.md (99%) rename doc/content/the-things-stack/host/kubernetes/{ => self-managed}/monitoring/_index.md (99%) create mode 100644 doc/content/the-things-stack/host/kubernetes/self-managed/preparation/_index.md rename doc/content/the-things-stack/host/kubernetes/{ => self-managed}/prerequisites/_index.md (98%) rename doc/content/the-things-stack/host/kubernetes/{ => self-managed}/troubleshooting/_index.md (80%) diff --git a/doc/content/the-things-stack/host/kubernetes/azure/_index.md b/doc/content/the-things-stack/host/kubernetes/azure/_index.md new file mode 100644 index 0000000000..56c7cdf19a --- /dev/null +++ b/doc/content/the-things-stack/host/kubernetes/azure/_index.md @@ -0,0 +1,11 @@ +--- +title: "Azure" +description: "" +weight: 1 +--- + +{{% tts %}} can be deployed to Azure as a set of highly available services on Azure Kubernetes Service using Terraform and Helm. + +This guide gives an overview of the architecture and shows how to deploy your own highly available {{% tts %}} cluster. + + diff --git a/doc/content/the-things-stack/host/kubernetes/azure/configuration/_index.md b/doc/content/the-things-stack/host/kubernetes/azure/configuration/_index.md new file mode 100644 index 0000000000..e00ea5ea28 --- /dev/null +++ b/doc/content/the-things-stack/host/kubernetes/azure/configuration/_index.md @@ -0,0 +1,76 @@ +--- +title: "Configuration" +description: "" +weight: 2 +aliases: [/getting-started/kubernetes/azure/configuration] +--- + +{{% tts %}} requires a few configuration files to be prepared. In this step, we create them and store them for further use. + + + +## Terraform Backend + +Create a `config.azurerm.tfbackend` file and put it in `1-infrastructure`, `2-kubernetes` and one of the chosen DNS provider templates directories. We recommend `azure-dns` provider for this deployment. + +``` +storage_account_name = +container_name = +key = +use_azuread_auth = true +``` + +## Deployment Configuration + +Create a `deployment.auto.tfvars.json` file in `1-infrastructure` directory. + +The following contains only the minimum mandatory fields for this configuration file. For a full list of possible values check the `variables.tf` file in this directory. + +``` +{ + "azure_ad_admin_group_object_id": # Object ID of the AKS admin group. + "deployment_name": # Name of the deployment. + "environment": # 'prod', 'staging' or 'dev'. + "cluster": # Cluster identifier for multi-cluster deployments. + "location": # Azure location + "resource_group": { + "create": # If set to `true` a new Resource Group will be created on deployment. + # Otherwise a Resource Group is going to be imported based on "name" parameter. + "name": # Optional custom Azure Resource Group name. Mandatory when "create" is set to `false`. + }, + "domain": { + "name": # Domain where The Things Stack is available. + "dns_zone": # Azure DNS zone. + } +} +``` + +## ACME Configuration + +Create an `acme.auto.tfvars.json` file in the DNS templates directory. + +It is only required to set the `acme_email` field. + +``` +{ + "acme_email": # ACME email that will receive notifications about expiring Certificates. +} +``` + +## The Things Stack Values + +Create a `tts.values.yaml` file in the `2-kubernetes` templates directory. + +The following contains only the minimum mandatory fields for this values file. For a full list of possible values check the `values.yaml` file of {{% tts %}} Helm chart. + +```yaml +license: + key: # TTS license key +global: + deployment: + initialTenant: + tenantID: # Initial tenant ID + adminEmail: # Admin email + adminUserID: # Admin ID + adminPassword: # Admin password +``` diff --git a/doc/content/the-things-stack/host/kubernetes/azure/deployment/_index.md b/doc/content/the-things-stack/host/kubernetes/azure/deployment/_index.md new file mode 100644 index 0000000000..2f0cce6e88 --- /dev/null +++ b/doc/content/the-things-stack/host/kubernetes/azure/deployment/_index.md @@ -0,0 +1,148 @@ +--- +title: "Deployment" +description: "" +weight: 3 +--- + +This page describes the steps for deploying {{% tts %}} on Azure Kubernetes Service. + + + +## Azure Infrastructure + +Start with the `1-infrastructure` templates that create the foundation for your deployment. + +If you haven't done this before create a Terraform backend configuration file `config.azurerm.tfbackend`. You can read more about it in the [**Configuration**]({{< ref "/the-things-stack/host/kubernetes/azure/configuration#terraform-backend" >}}) section. + +Initialize the Terraform state. + +```bash +$ make init +``` + +Plan the deployment and verify everything is going to be set up correctly. + +```bash +$ make plan +``` + +Now apply the template. + +```bash +$ make apply +``` + +Get the `kubeconfig` next. + +```bash +# Set KUBECONFIG if you don't want to override the default kubeconfig. +$ export KUBECONFIG='local.kubeconfig' + +# Set KUBE_CONFIG_PATH to the location of the kubeconfig. +# If you didn't set the KUBECONFIG variable use '~/.kube/config' instead. +# Ref https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#file-config +$ export KUBE_CONFIG_PATH="$(pwd)/${KUBECONFIG}" + +$ az aks get-credentials --resource-group $(terraform output -raw resource_group_name) --name $(terraform output -raw aks_cluster_name) +``` + +{{< warning >}} +If `var.allow_cluster_admin_access` is disabled, then `kubelogin` must be installed. +{{}} + +Follow the promp to authenticate the `kubectl`. + +```bash +$ kubectl get pods +To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code xxxxxx to authenticate. +``` + +Export the DNS values used for [**DNS Infrastructure**]({{< relref "#dns-infrastructure" >}}). Use the provider chosen during the [**Configuration**]({{< ref "/the-things-stack/host/kubernetes/azure/configuration#acme-configuration" >}}). + +```bash +$ DNS_PROVIDER='' +$ make dns.values | jq > "$(git rev-parse --show-toplevel)/dns/${DNS_PROVIDER}/dns.auto.tfvars.json" +``` + +Export the Infrastructural values used for [**Kubernetes Templates**]({{< relref "#kubernetes-templates" >}}). + +```bash +$ make infra.values | jq > '../2-kubernetes/infra.auto.tfvars.json' +``` + +## DNS Infrastructure + +Now we need to set up the DNS infrastructure. Head over to the directory of the provider you chose during the last steps of the [**Azure Infrastructure**]({{< relref "#azure-infrastructure" >}}) section. + +If you haven't done this before create a Terraform backend configuration file `config.azurerm.tfbackend`. You can read more about it in the section ... . + +Initialize the Terraform state. + +{{< note >}} +`KUBE_CONFIG_PATH` should point to your `kubeconfig`. + +```bash +# Example +$ export KUBE_CONFIG_PATH='~/.kube/config' +``` + +{{}} + +```bash +$ make init +``` + +Plan the deployment and verify everything is going to be set up correctly. + +```bash +$ make plan +``` + +Now apply the template. + +```bash +$ make apply +``` + +Verify the certificate is in ready state. This may take a couple of minutes after the deployment for the certificate to reach a ready state. + +```bash +$ kubectl -n tts get cert +``` + +In case the certificate won't reach a ready state head over to [Troubleshooting Problems with ACME / Let's Encrypt Certificates](https://cert-manager.io/docs/troubleshooting/acme/). + +## Kubernetes Templates + +Head over to the `2-kubernetes` directory next. + +If you haven't done this before create a Terraform backend configuration file `config.azurerm.tfbackend`. You can read more about it in the section ... . + +Initialize the Terraform state. + +```bash +$ make init +``` + +Plan the deployment and verify everything is going to be set up correctly. + +{{< note >}} +`KUBE_CONFIG_PATH` should point to your `kubeconfig`. + +```bash +# Example +$ export KUBE_CONFIG_PATH='~/.kube/config' +``` +{{}} + +```bash +$ make plan +``` + +Now apply the template. + +```bash +$ make apply +``` + +Once all the targets are healthy and if the configuration was correct, The Things Stack console will be accessible at `https://.`. diff --git a/doc/content/the-things-stack/host/kubernetes/azure/prerequisites/_index.md b/doc/content/the-things-stack/host/kubernetes/azure/prerequisites/_index.md new file mode 100644 index 0000000000..0dbdc64a02 --- /dev/null +++ b/doc/content/the-things-stack/host/kubernetes/azure/prerequisites/_index.md @@ -0,0 +1,31 @@ +--- +title: "Prerequisites" +description: "" +weight: 1 +aliases: [/getting-started/kubernetes/azure/prerequisites] +--- + +The following are required for {{% tts %}} on Azure Kubernetes Service. + + + +# Tools + +1. [Terraform](https://www.terraform.io/) +2. [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) +3. [Helm version 3](https://helm.sh/docs/intro/). Check the version of Helm installed using `helm version`. Helm v3.8 or above is required. + +## License + +The Things Stack requires a license key to run. Please [contact our sales team](mailto:sales@thethingsindustries.com) for your license key. + +## (Optional) Packet Broker Access + +The Things Stack contains the Packet Broker Agent component that can communicate with [Packet Broker](https://packetbroker.net/). + +Packet Broker is disabled by default in the Helm charts. When enabled, it can operate either only a Forwarder or as both a Forwarder and a Home Network. Check the [The Things Stack Documentation](https://www.thethingsindustries.com/docs/the-things-stack/packet-broker/) for more details. + +- If the cluster acts simply as a forwarder that forwards traffic to Packet Broker, then all that is needed are access credentials. +- If the cluster also needs to work as a Packer Broker Home Network, in addition to the access credentials, the cluster either needs a NetID from the LoRa Alliance or The Things Industries can lease a DevAddr Block. + +Please [contact our sales team](mailto:sales@thethingsindustries.com) for access credentials and a Device Address Block (if necessary). diff --git a/doc/content/the-things-stack/host/kubernetes/azure/troubleshooting/_index.md b/doc/content/the-things-stack/host/kubernetes/azure/troubleshooting/_index.md new file mode 100644 index 0000000000..95ef34a294 --- /dev/null +++ b/doc/content/the-things-stack/host/kubernetes/azure/troubleshooting/_index.md @@ -0,0 +1,8 @@ +--- +title: "Troubleshooting" +description: "" +weight: 9 +aliases: [/getting-started/kubernetes/azure/troubleshooting] +--- + +This guide contains general troubleshooting information. diff --git a/doc/content/the-things-stack/host/kubernetes/preparation/_index.md b/doc/content/the-things-stack/host/kubernetes/preparation/_index.md deleted file mode 100644 index 180eed9904..0000000000 --- a/doc/content/the-things-stack/host/kubernetes/preparation/_index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "Preparation" -description: "" -weight: 2 -aliases: [/getting-started/kubernetes/preparation] ---- - -{{% tts %}} requires a few secret values to be configured. In this step, we generate them and store them for further use. - -Copy each generated secret to a local file and then transfer those values later into the corresponding location in the `values.yaml` file. - -{{< note "Secrets are required to be hex-encoded strings of the exact length mentioned in this guide." />}} - -|Secret|Description|Size|Setting in `values.yaml`| -|---|----|---|---| -|Cluster Keys|Key used by cluster components to communicate|32|`global.cluster.keys`| -|HTTP Cookie Block Key|Block Key for HTTP Cookies|32|`global.http.cookie.blockKey`| -|HTTP Cookie Hash Key|Hash Key for HTTP Cookies|32|`global.http.cookie.hashKey`| -|Metrics Password|Password to access exposed Prometheus metrics|16|`global.http.metrics.password`| -|PProf Password|Password to access profiling (pprof) |16|`global.http.pprof.password`| -|Console Oauth Secret|Secret used by the Console to connect to The Things Stack|16|`global.console.oauth.clientSecret`| -|Tenant Administration Key|Secret used to administer cluster tenants|32|`global.tenancy.adminKey`| -|NOC Grafana Admin Password (optional)|Grafana admin password for The Things Stack Network Operations Center|24|`noc.grafana.adminPassword`| -|NOC Oauth Client Secret (optional)|OAuth client secret for The Things Stack Network Operations Center|24|`noc.oauth.clientSecret`| - -The simplest option is to use `openssl`. - -```bash -size=<> -$ openssl rand -hex ${size} -``` - -For example, to generate `global.http.cookie.hashKey` you can run the following. - -```bash -size=32 -$ openssl rand -hex ${size} -e1bf1a49ac7e1cb593f1c3afeab494ca950bba06d764110854f801da42e3d568 -``` diff --git a/doc/content/the-things-stack/host/kubernetes/self-managed/_index.md b/doc/content/the-things-stack/host/kubernetes/self-managed/_index.md new file mode 100644 index 0000000000..12f06a63d5 --- /dev/null +++ b/doc/content/the-things-stack/host/kubernetes/self-managed/_index.md @@ -0,0 +1,9 @@ +--- +title: "Self Managed" +description: "" +weight: 2 +--- + +This guide is meant for people who want to deploy {{% tts %}} on Kubernetes with self-hosted infrastructure. It gives an overview of the Helm charts and the steps required to deploy them. + + diff --git a/doc/content/the-things-stack/host/kubernetes/configuration/_index.md b/doc/content/the-things-stack/host/kubernetes/self-managed/configuration/_index.md similarity index 98% rename from doc/content/the-things-stack/host/kubernetes/configuration/_index.md rename to doc/content/the-things-stack/host/kubernetes/self-managed/configuration/_index.md index d3c4b60f06..5be6ed99b6 100644 --- a/doc/content/the-things-stack/host/kubernetes/configuration/_index.md +++ b/doc/content/the-things-stack/host/kubernetes/self-managed/configuration/_index.md @@ -7,6 +7,8 @@ aliases: [/getting-started/kubernetes/configuration] {{% tts %}} Helm chart is configured using `yaml` files. This guide assumes that these fields are saved in a `.values.yaml` file and used for deployment/updates. + + The following is a list of mandatory minimum fields. For a full list of possible values, check the `values.yaml` file at the root of the {{% tts %}} Helm chart. {{< warning >}} Some values in this file are secrets. Make sure to check this file into a secure repository.{{}} @@ -28,6 +30,7 @@ global: region: # region azure: # Set only if provider is "azure". accountName: # account name + clientID: # client ID gcp: # Set only if provider is "gcp". # Base64 encoded GCP credentials.json file. # One option is to run `$ cat .json | base64`. diff --git a/doc/content/the-things-stack/host/kubernetes/database-migrations/_index.md b/doc/content/the-things-stack/host/kubernetes/self-managed/database-migrations/_index.md similarity index 100% rename from doc/content/the-things-stack/host/kubernetes/database-migrations/_index.md rename to doc/content/the-things-stack/host/kubernetes/self-managed/database-migrations/_index.md diff --git a/doc/content/the-things-stack/host/kubernetes/install-charts/_index.md b/doc/content/the-things-stack/host/kubernetes/self-managed/install-charts/_index.md similarity index 99% rename from doc/content/the-things-stack/host/kubernetes/install-charts/_index.md rename to doc/content/the-things-stack/host/kubernetes/self-managed/install-charts/_index.md index daf02a7eb4..189c0fc81f 100644 --- a/doc/content/the-things-stack/host/kubernetes/install-charts/_index.md +++ b/doc/content/the-things-stack/host/kubernetes/self-managed/install-charts/_index.md @@ -9,6 +9,8 @@ aliases: [/getting-started/kubernetes/install-charts] Use the following steps to install the chart. + + 1. Login to the registry. This step can be skipped if you've already logged in via Docker Client. ```bash diff --git a/doc/content/the-things-stack/host/kubernetes/monitoring/_index.md b/doc/content/the-things-stack/host/kubernetes/self-managed/monitoring/_index.md similarity index 99% rename from doc/content/the-things-stack/host/kubernetes/monitoring/_index.md rename to doc/content/the-things-stack/host/kubernetes/self-managed/monitoring/_index.md index 1e6d5b1cdd..9135c10680 100644 --- a/doc/content/the-things-stack/host/kubernetes/monitoring/_index.md +++ b/doc/content/the-things-stack/host/kubernetes/self-managed/monitoring/_index.md @@ -7,6 +7,8 @@ aliases: [/getting-started/kubernetes/monitoring] {{% tts %}} exposes Prometheus metrics at the `/metrics` endpoint. This route is protected by Basic Auth with username `metrics` and password `global.http.metrics.password`. + + To scrape these metrics, you can install Prometheus in the cluster. The installation details are outside the scope of this document. The following scrape config can be used to scrape metrics from each of the components of The Things Stack. diff --git a/doc/content/the-things-stack/host/kubernetes/self-managed/preparation/_index.md b/doc/content/the-things-stack/host/kubernetes/self-managed/preparation/_index.md new file mode 100644 index 0000000000..15ae1b120e --- /dev/null +++ b/doc/content/the-things-stack/host/kubernetes/self-managed/preparation/_index.md @@ -0,0 +1,41 @@ +--- +title: "Preparation" +description: "" +weight: 2 +aliases: [/getting-started/kubernetes/self-managed/preparation] +--- + +{{% tts %}} requires a few secret values to be configured. In this step, we generate them and store them for further use. + + + +Copy each generated secret to a local file and then transfer those values later into the corresponding location in the `values.yaml` file. + +{{< note "Secrets are required to be hex-encoded strings of the exact length mentioned in this guide." />}} + +| Secret | Description | Size | Setting in `values.yaml` | +| ------------------------------------- | --------------------------------------------------------------------- | ---- | ----------------------------------- | +| Cluster Keys | Key used by cluster components to communicate | 32 | `global.cluster.keys` | +| HTTP Cookie Block Key | Block Key for HTTP Cookies | 32 | `global.http.cookie.blockKey` | +| HTTP Cookie Hash Key | Hash Key for HTTP Cookies | 32 | `global.http.cookie.hashKey` | +| Metrics Password | Password to access exposed Prometheus metrics | 16 | `global.http.metrics.password` | +| PProf Password | Password to access profiling (pprof) | 16 | `global.http.pprof.password` | +| Console Oauth Secret | Secret used by the Console to connect to The Things Stack | 16 | `global.console.oauth.clientSecret` | +| Tenant Administration Key | Secret used to administer cluster tenants | 32 | `global.tenancy.adminKey` | +| NOC Grafana Admin Password (optional) | Grafana admin password for The Things Stack Network Operations Center | 24 | `noc.grafana.adminPassword` | +| NOC Oauth Client Secret (optional) | OAuth client secret for The Things Stack Network Operations Center | 24 | `noc.oauth.clientSecret` | + +The simplest option is to use `openssl`. + +```bash +size=<> +$ openssl rand -hex ${size} +``` + +For example, to generate `global.http.cookie.hashKey` you can run the following. + +```bash +size=32 +$ openssl rand -hex ${size} +e1bf1a49ac7e1cb593f1c3afeab494ca950bba06d764110854f801da42e3d568 +``` diff --git a/doc/content/the-things-stack/host/kubernetes/prerequisites/_index.md b/doc/content/the-things-stack/host/kubernetes/self-managed/prerequisites/_index.md similarity index 98% rename from doc/content/the-things-stack/host/kubernetes/prerequisites/_index.md rename to doc/content/the-things-stack/host/kubernetes/self-managed/prerequisites/_index.md index 18d2307af6..f9774b9fdc 100644 --- a/doc/content/the-things-stack/host/kubernetes/prerequisites/_index.md +++ b/doc/content/the-things-stack/host/kubernetes/self-managed/prerequisites/_index.md @@ -2,11 +2,13 @@ title: "Prerequisites" description: "" weight: 1 -aliases: [/getting-started/kubernetes/prerequisites] +aliases: [/getting-started/kubernetes/self-managed/prerequisites] --- The following are required for {{% tts %}} on Kubernetes. + + ## Installation Tools 1. [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) @@ -112,7 +114,7 @@ To use a custom proxy/load balancer, set `global.ingress.traefik.enabled` to `fa 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 "the-things-stack/host/kubernetes/prerequisites#6-tls-certificates" >}}). +If Traefik is not used, skip ahead to [setup TLS certificates]({{< ref "the-things-stack/host/kubernetes/self-managed/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). diff --git a/doc/content/the-things-stack/host/kubernetes/troubleshooting/_index.md b/doc/content/the-things-stack/host/kubernetes/self-managed/troubleshooting/_index.md similarity index 80% rename from doc/content/the-things-stack/host/kubernetes/troubleshooting/_index.md rename to doc/content/the-things-stack/host/kubernetes/self-managed/troubleshooting/_index.md index acb6c2aa21..13484e411e 100644 --- a/doc/content/the-things-stack/host/kubernetes/troubleshooting/_index.md +++ b/doc/content/the-things-stack/host/kubernetes/self-managed/troubleshooting/_index.md @@ -2,11 +2,13 @@ title: "Troubleshooting" description: "" weight: 6 -aliases: [/getting-started/kubernetes/troubleshooting] +aliases: [/getting-started/kubernetes/self-managed/troubleshooting] --- This guide contains general troubleshooting information. + + ### Why do the GS, NS, AS and JS components fail to start? The one thing that is common between these four components (and not others) is that they all use Redis. Make sure to troubleshoot the Redis server that's used. Ensure that Redis is reachable from within the cluster. If authentication is required, make sure that the configuration works. @@ -32,3 +34,4 @@ The Things Stack runs kubernetes jobs to initialize and migrate Postgres. This e ### Gateways don't work when targeting the UDP port 1700 Ensure that UDP port (default 1700) is exposed outside the k8s cluster via your chosen proxy or load balancer. +ur `docker-compose.yml` file uses [Compose file version 3.7](https://docs.docker.com/compose/compose-file/). If using a package manager to install Docker Compose, it is possible to install an old, unsupported version. See Docker's [installation instructions](https://docs.docker.com/compose/install/) to upgrade to a more recent version.