Dash0 Kubernetes Operator Helm Chart

This repository contains the Helm chart for the Dash0 Kubernetes operator.

The Dash0 Kubernetes Operator makes observability for Kubernetes easy. Simply install the operator into your cluster to get OpenTelemetry data flowing from your Kubernetes workloads to Dash0.

Description

The Dash0 Kubernetes operator installs an OpenTelemetry collector into your cluster that sends data to your Dash0 ingress endpoint, with authentication already configured out of the box. Additionally, it will enable gathering OpenTelemetry data from applications deployed to the cluster for a selection of supported runtimes.

More information on the Dash0 Kubernetes Operator can be found at https://github.com/dash0hq/dash0-operator/blob/main/README.md.

Prerequisites

• Kubernetes >= 1.xx
• Helm >= 3.xx, please refer to Helm's documentation for more information on installing Helm.

Installation

Before installing the operator, add the Dash0 operator's Helm repository as follows:

helm repo add dash0-operator https://dash0hq.github.io/dash0-operator
helm repo update

Now you can install the operator into your cluster via Helm with the following command:

01234
helm install \
 --namespace dash0-system \
 --create-namespace \
 dash0-operator \
 dash0-operator/dash0-operator

Note that Dash0 has to be enabled per namespace that you want to monitor, which is described in the next section.

Enable Dash0 Monitoring For a Namespace

For each namespace that you want to monitor with Dash0, enable monitoring by installing a Dash0 monitoring resource into that namespace:

Create a file dash0-monitoring.yamlCopy with the following content:

012345678910111213141516
apiVersion: operator.dash0.com/v1alpha1
kind: Dash0Monitoring
metadata:
  name: dash0-monitoring-resource
spec:
  export:
    dash0:
      # Replace this value with the actual OTLP/gRPC endpoint of your Dash0 organization.
      endpoint: ingress... # TODO needs to be replaced with the actual value, see below

      authorization:
        # Provide the Dash0 authorization token as a string via the token property:
        token: auth_... # TODO needs to be replaced with the actual value, see below

  # Opt-out settings for particular use cases. The default value is "all". Other possible values are
  # "created-and-updated" and "none".
  # instrumentWorkloads: all

At this point, you need to provide two configuration settings:

• spec.export.dash0.endpointCopy: The URL of the observability backend to which telemetry data will be sent. This property is mandatory. 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/settings. Note that the correct endpoint value will always start with ingress.Copy and end in dash0.com:4317Copy. A protocol prefix (eg. https://Copy) should not be included in the value.
• spec.export.dash0.authorization.tokenCopy or spec.export.dash0.authorization.secretRefCopy: Exactly one of these two properties needs to be provided. Providing both will cause a validation error when installing the Dash0Monitoring resource.
  • spec.export.dash0.authorization.tokenCopy: Replace the value in the example above with the Dash0 authorization token of your organization. The authorization token for your Dash0 organization can be copied from https://app.dash0.com/settings. The prefix Bearer Copymust not be included in the value. Note that the value 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 the secretRefCopy property and a Kubernetes secret if you want to avoid that.
  • spec.export.dash0.authorization.secretRefCopy: A reference to an existing Kubernetes secret in the Dash0 operator's namespace. See the next section for an example file that uses a secretRefCopy. The secret needs to contain the Dash0 authorization token. See below for details on how exactly the secret should be created and configured. 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. See https://kubernetes.io/docs/concepts/configuration/secret/ for more information on Kubernetes secrets.

The other configuration settings are optional:

• instrumentWorkloadsCopy: A global opt-out for workload instrumentation for the target namespace. There are threepossible settings: allCopy, created-and-updatedCopy and noneCopy. By default, the setting allCopy is assumed.If this setting is omitted, the value allCopy is assumed and new/updated as well as existing Kubernetes workloads will be intrumented by the operator to send telemetry to Dash0, as described above.More fine-grained per-workload control over instrumentation is available by setting the label dash0.com/enable=falseCopy on individual workloads.The behavior when changing this setting for an existing Dash0 monitoring resource is as follows:
  • allCopy: If set to allCopy (or omitted), the operator will:
    • instrument existing workloads in the target namespace (i.e. workloads already running in the namespace) when the Dash0 monitoring resource is deployed,
    • instrument existing workloads or update the instrumentation of already instrumented workloads in the target namespace when the Dash0 Kubernetes operator is first started or restarted (for example when updating the operator),
    • instrument new workloads in the target namespace when they are deployed, and
    • instrument changed workloads in the target namespace when changes are applied to them. Note that the first two actions (instrumenting existing workloads) will result in restarting the pods of the affected workloads.
  • created-and-updatedCopy: If set to created-and-updatedCopy, the operator will not instrument existing workloads in the target namespace. Instead, it will only:
    • instrument new workloads in the target namespace when they are deployed, and
    • instrument changed workloads in the target namespace when changes are applied to them. This setting is useful if you want to avoid pod restarts as a side effect of deploying the Dash0 monitoring resource or restarting the Dash0 Kubernetes operator.
  • noneCopy: You can opt out of instrumenting workloads entirely by setting this option to noneCopy. With instrumentWorkloads: noneCopy, workloads in the target namespace will never be instrumented to send telemetry to Dash0.
  • When this setting is updated to instrumentWorkloads=allCopy (and it had a different value before): All existing uninstrumented workloads will be instrumented.
  • When this setting is updated to instrumentWorkloads=noneCopy (and it had a different value before): The instrumentation will be removed from all instrumented workloads.
  • Updating this value to instrumentWorkloads=created-and-updatedCopy has no immediate effect; existing uninstrumented workloads will not be instrumented, existing instrumented workloads will not be uninstrumented. Newly deployed or updated workloads will be instrumented from the point of the configuration change onwards as described above.

After providing the required values, save the file and apply the resource to the namespace you want to monitor. For example, if you want to monitor workloads in the namespace my-nodejs-applicationsCopy, use the following command:

kubectl apply --namespace my-nodejs-applications -f dash0-monitoring.yamlCopy

If you want to monitor the defaultCopy namespace with Dash0, use the following command:

kubectl apply -f dash0-monitoring.yamlCopy

Using a Kubernetes Secret for the Dash0 Authorization Token

If you want to provide the Dash0 authorization token via a Kubernetes secret instead of providing the token as a string, create the secret in the namespace where the Dash0 operator is installed. If you followed the guide above, the name of that namespace is dash0-systemCopy. The authorization token for your Dash0 organization can be copied from https://app.dash0.com/settings. You can freely choose the name of the secret and the key of the token within the secret.

Create the secret by using the following command:

0123
kubectl create secret generic \
 dash0-authorization-secret \
 --namespace dash0-system \
 --from-literal=token=auth_...your-token-here...

With this example command, you would create a secret with the name dash0-authorization-secretCopy in the namespace dash0-systemCopy. If you installed the operator into a different namespace, replace the --namespaceCopy parameter accordingly.

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 secretRefCopy property. If the nameCopy property is omitted, the name dash0-authorization-secretCopy will be assumed. If the keyCopy property is omitted, the key tokenCopy will be assumed. Here is an example that uses the secret created above:

0123456789101112131415161718192021222324252627282930
apiVersion: operator.dash0.com/v1alpha1
kind: Dash0Monitoring
metadata:
  name: dash0-monitoring-resource
spec:
  export:
    dash0:
      # Replace this value with the actual OTLP/gRPC endpoint of your Dash0 organization.
      endpoint: ingress... # TODO needs to be replaced with the actual value, see below

      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:

apiVersion: operator.dash0.com/v1alpha1
kind: Dash0Monitoring
metadata:
  name: dash0-monitoring-resource
spec:
  export:
    dash0:
      # Replace this value with the actual OTLP/gRPC endpoint of your Dash0 organization.
      endpoint: ingress... # TODO needs to be replaced with the actual value, see below

      authorization:
        # Provide the name and key of a secret existing in the Dash0 operator's namespace as secretRef:
        secretRef: {}

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. See https://kubernetes.io/docs/concepts/configur**ation/secret/ for more information on Kubernetes secrets.

Dash0 Dataset Configuration

Use the spec.export.dash0.datasetCopy property to configure the dataset that should be used for the telemetry data. By default, data will be sent to the dataset defaultCopy.

012345678910
apiVersion: operator.dash0.com/v1alpha1
kind: Dash0Monitoring
metadata:
  name: dash0-monitoring-resource
spec:
  export:
    dash0:
      endpoint: ingress... # TODO needs to be replaced with the actual value, see below
      dataset: my-custom-dataset
      authorization:
        ...

Disable Dash0 Monitoring For a Namespace

If you want to stop monitoring a namespace with Dash0, remove the Dash0 monitoring resource from that namespace. For example, if you want to stop monitoring workloads in the namespace my-nodejs-applicationsCopy, use the following command:

kubectl delete --namespace my-nodejs-applications Dash0Monitoring dash0-monitoring-resourceCopy

or, alternatively, by using the dash0-monitoring.yamlCopy file created earlier:

kubectl delete --namespace my-nodejs-applications -f dash0-monitoring.yamlCopy

Uninstallation

To remove the Dash0 Kubernetes Operator from your cluster, run the following command:

helm uninstall dash0-operator --namespace dash0-systemCopy

Depending on the command you used to install the operator, you may need to use a different Helm release name or namespace.

This will also automatically disable Dash0 monitoring for all namespaces by deleting the Dash0 monitoring resources in all namespaces. Optionally, remove the namespace that has been created for the operator:

kubectl delete namespace dash0-system
Copy

If you choose to not remove the namespace, you might want to consider removing the secret with the Dash0 authorization token (if such a secret has been created):

kubectl delete secret --namespace dash0-system dash0-authorization-secretCopy

If you later decide to install the operator again, you will need to enable Dash0 monitoring in each namespace you want to monitor again, see Enable Dash0 Monitoring For a Namespace.