From 805cd937b3cc4cf73ed22a372df73f9a27f3538c Mon Sep 17 00:00:00 2001 From: Bastian Krol Date: Wed, 18 Sep 2024 16:37:12 +0200 Subject: [PATCH] docs(chart): document helm values to create an operator config resource --- helm-chart/dash0-operator/README.md | 116 ++++++++++++++++++++++++---- 1 file changed, 101 insertions(+), 15 deletions(-) diff --git a/helm-chart/dash0-operator/README.md b/helm-chart/dash0-operator/README.md index 0b290b13..34d6dd6f 100644 --- a/helm-chart/dash0-operator/README.md +++ b/helm-chart/dash0-operator/README.md @@ -27,6 +27,25 @@ Supported runtimes for automatic instrumentation: - [Helm](https://helm.sh) >= 3.x, please refer to Helm's [documentation](https://helm.sh/docs/) for more information on installing Helm. +To use the operator, you will need provide two configuration values: +* `endpoint`: The URL of the Dash0 ingress endpoint backend to which telemetry data will be sent. + This property is mandatory when installing the operator. + This is the OTLP/gRPC endpoint of your Dash0 organization. + The correct OTLP/gRPC endpoint can be copied fom https://app.dash0.com -> organization settings -> "Endpoints". + Note that the correct endpoint value will always start with `ingress.` and end in `dash0.com:4317`. + Including a protocol prefix (e.g. `https://`) is optional. +* Either `token` or `secretRef`: Exactly one of these two properties needs to be provided when installing the operator. + * `token`: This is the Dash0 authorization token of your organization. + The authorization token for your Dash0 organization can be copied from https://app.dash0.com -> organization + settings -> "Auth Tokens". + The prefix `Bearer ` must *not* be included in the value. + Note that when you provide a token, it will be rendered verbatim into a Kubernetes ConfigMap object. + Anyone with API access to the Kubernetes cluster will be able to read the value. + Use a secret reference and a Kubernetes secret if you want to avoid that. + * `secretRef`: A reference to an existing Kubernetes secret in the Dash0 operator's namespace. + The secret needs to contain the Dash0 authorization token. + See below for details on how exactly the secret should be created and configured. + ## Installation Before installing the operator, add the Dash0 operator's Helm repository as follows: @@ -38,6 +57,36 @@ helm repo update dash0-operator Now you can install the operator into your cluster via Helm with the following command: +```console +helm install \ + --namespace dash0-system \ + --create-namespace \ + --set operator.dash0Backend.enabled=true \ + --set operator.dash0Backend.endpoint=REPLACE THIS WITH YOUR DASH0 INGRESS ENDPOINT \ + --set operator.dash0Backend.token=REPLACE THIS WITH YOUR DASH0 AUTH TOKEN \ + dash0-operator \ + dash0-operator/dash0-operator +``` + +Instead of providing the auth token directly, you can also use a secret reference: + +```console +helm install \ + --namespace dash0-system \ + --create-namespace \ + --set operator.dash0Backend.enabled=true \ + --set operator.dash0Backend.endpoint=REPLACE THIS WITH YOUR DASH0 INGRESS ENDPOINT \ + --set operator.dash0Backend.secretRef.name=REPLACE THIS WITH THE NAME OF AN EXISTING KUBERNETES SECRET \ + --set operator.dash0Backend.secretRef.key=REPLACE THIS WITH THE PROPERTY KEY IN THAT SECRET \ + dash0-operator \ + dash0-operator/dash0-operator +``` + +See https://kubernetes.io/docs/concepts/configuration/secret/ for more information on using a Kubernetes secrets +with the Dash0 operator. + +Last but not least, you can also install the operator without providing a Dash0 backend configuration: + ```console helm install \ --namespace dash0-system \ @@ -46,6 +95,11 @@ helm install \ dash0-operator/dash0-operator ``` +However, you will need to create a Dash0 operator configuration resource later that provides the backend connection +settings. +That is, providing `--set operator.dash0Backend.enabled=true` and the other backend-related settings when running +`helm install` is simply a shortcut to deploy the Dash0 operator configuration resource automatically at startup. + On its own, the operator will not do much. To actually have the operator monitor your cluster, two more things need to be set up: 1. a [Dash0 backend connection](#configuring-the-dash0-backend-connection) has to be configured and @@ -57,7 +111,12 @@ Both steps are described in the following sections. ### Configuring the Dash0 Backend Connection -Create a file `dash0-operator-configuration.yaml` with the following content: +You can skip this step if you provided `--set operator.dash0Backend.enabled=true` together with the endpoint and either +a token or a secret reference when running `helm install`. In that case, proceed to the next section, +[Enable Dash0 Monitoring For a Namespace](#enable-dash0-monitoring-for-a-namespace). + +Otherwise, configure the backend connection now by creating a file `dash0-operator-configuration.yaml` with the +following content: ```yaml apiVersion: operator.dash0.com/v1alpha1 @@ -81,7 +140,7 @@ You need to provide two configuration settings: Replace the value in the example above with the OTLP/gRPC endpoint of your Dash0 organization. The correct OTLP/gRPC endpoint can be copied fom https://app.dash0.com -> organization settings -> "Endpoints". Note that the correct endpoint value will always start with `ingress.` and end in `dash0.com:4317`. - A protocol prefix (e.g. `https://`) should not be included in the value. + Including a protocol prefix (e.g. `https://`) is optional. * `spec.export.dash0.authorization.token` or `spec.export.dash0.authorization.secretRef`: Exactly one of these two properties needs to be provided. Providing both will cause a validation error when installing the Dash0Monitoring resource. @@ -119,6 +178,7 @@ For _each namespace_ that you want to monitor with Dash0, enable workload monito resource_ into that namespace: Create a file `dash0-monitoring.yaml` with the following content: + ```yaml apiVersion: operator.dash0.com/v1alpha1 kind: Dash0Monitoring @@ -134,6 +194,7 @@ kubectl apply --namespace my-nodejs-applications -f dash0-monitoring.yaml ``` If you want to monitor the `default` namespace with Dash0, use the following command: + ```console kubectl apply -f dash0-monitoring.yaml ``` @@ -217,13 +278,31 @@ kubectl create secret generic \ With this example command, you would create a secret with the name `dash0-authorization-secret` in the namespace `dash0-system`. -If you installed the operator into a different namespace, replace the `--namespace` parameter accordingly. +If you installed (or plan to install) the operator into a different namespace, replace the `--namespace` parameter +accordingly. + +The name of the secret as well as the key of the token value within the secret must be provided when referencing the +secret during `helm install`, or in the YAML file for the Dash0 operator configuration resource (in the `secretRef` +property). + +For creating the operator configuration resource with `helm install`, the command would look like this, assuming the +secret has been created as shown above: + +```console +helm install \ + --namespace dash0-system \ + --set operator.dash0Backend.enabled=true \ + --set operator.dash0Backend.endpoint=REPLACE THIS WITH YOUR DASH0 INGRESS ENDPOINT \ + --set operator.dash0Backend.secretRef.name=dash0-authorization-secret \ + --set operator.dash0Backend.secretRef.key=token \ + dash0-operator \ + dash0-operator/dash0-operator +``` + +If you do not want to install the operator configuration resource via `helm install` but instead deploy it manually, +and use a secret reference for the auth token, the following example YAML file would work work with the secret created +above: -The name of the secret as well as the key of the token value within the secret must be provided in the YAML file for -the Dash0 monitoring resource, in the `secretRef` property. -If the `name` property is omitted, the name `dash0-authorization-secret` will be assumed. -If the `key` property is omitted, the key `token` will be assumed. -Here is an example that uses the secret created above: ```yaml apiVersion: operator.dash0.com/v1alpha1 kind: Dash0OperatorConfiguration @@ -232,17 +311,19 @@ metadata: spec: export: dash0: - endpoint: ingress... # TODO needs to be replaced with the actual value, see above + endpoint: ingress... # TODO REPLACE THIS WITH YOUR DASH0 INGRESS ENDPOINT authorization: - # Provide the name and key of a secret existing in the Dash0 operator's namespace as secretRef: secretRef: name: dash0-authorization-secret key: token ``` -Since the name `dash0-authorization-secret` and the key `token` are the defaults, this `secretRef` could have also been -written as follows: +When deploying the operator configuration resource via `kubectl`, the following defaults apply: +* If the `name` property is omitted, the name `dash0-authorization-secret` will be assumed. +* If the `key` property is omitted, the key `token` will be assumed. + +With these defaults in mind, the `secretRef` could have also been written as follows: ```yaml apiVersion: operator.dash0.com/v1alpha1 @@ -258,9 +339,13 @@ spec: secretRef: {} ``` +Note: There are no defaults when using `--set operator.dash0Backend.secretRef.name` and +`--set operator.dash0Backend.secretRef.key` with `helm install`, so for that approach the values must always be +provided explicitly. + Note that by default, Kubernetes secrets are stored _unencrypted_, and anyone with API access to the Kubernetes cluster will be able to read the value. -Additional steps are required to make sure secret values are encrypted. +Additional steps are required to make sure secret values are encrypted, if that is desired. See https://kubernetes.io/docs/concepts/configur**ation/secret/ for more information on Kubernetes secrets. ### Dash0 Dataset Configuration @@ -287,8 +372,9 @@ spec: ### Exporting Data to Other Observability Backends -Instead of `spec.export.dash0`, you can also provide `spec.export.http` or `spec.export.grpc` to export telemetry data -to arbitrary OTLP-compatible backends, or to another local OpenTelemetry collector. +Instead of `spec.export.dash0` in the Dash0 operator configuration resource, you can also provide `spec.export.http` or +`spec.export.grpc` to export telemetry data to arbitrary OTLP-compatible backends, or to another local OpenTelemetry +collector. Here is an example for HTTP: