k8s Custom Secret Management

Overview

The SUSE Observability Agent supports specifying custom secrets that contain the API key, cluster authorization token, cluster name and SUSE Observability URL. This feature is useful for users who wish to manage their own secrets, including deployments managed through Fleet or other GitOps tools.

The Helm Chart

Configuration Options

A service token must be used instead of API key as they are synonymous. If a global apikey is required, you can use a bootstrap token.

  • global.apiKey.fromSecret: Specify a pre-existing secret name residing in the same namespace which contains an STS_API_KEY field containing the api key.

  • global.clusterAgentAuthToken.fromSecret: Specify a pre-existing secret name residing in the same namespace which contains an STS_CLUSTER_AGENT_AUTH_TOKEN field containing a token for securing connections between the cluster and node agents.

  • global.clusterName.fromSecret: Specify a pre-existing secret in the same namespace containing an STS_CLUSTER_NAME field. When set, this takes precedence over stackstate.cluster.name.

  • global.url.fromSecret: Specify a pre-existing secret in the same namespace containing an STS_URL field. When set, this takes precedence over stackstate.url.

The global.clusterName.fromSecret and global.url.fromSecret options require SUSE Observability Agent Helm chart version 1.7.0 or later. Secret names support Helm templating. Each option can reference the same secret or a different secret, and secret references can be combined with literal values for the remaining settings.

Automatic discovery of a cluster name configured through global.clusterName.fromSecret requires SUSE Observability Rancher UI extension version 2.4.1 or later. The logged-in Rancher user must be able to read the agent Deployments and the referenced Secret. With an older extension or insufficient permissions, the Rancher cluster display name must match STS_CLUSTER_NAME for health views and component links to target the correct cluster.

Behavior Description

  • Automatic Secret Creation: By default, the chart requires an stackstate.apiKey to be specified and will create a secret by itself. The STS_CLUSTER_AGENT_AUTH_TOKEN is generated automatically.

  • Custom Secret Management: When overriding the fromSecret fields, the corresponding values are taken from those secrets when the agent pods start. Provision the secrets before the pods start and restart the affected workloads after changing the secret values.

  • Implied Omission: When specifying that you would like to manage your own secrets, the chart will ignore values for stackstate.apiKey and stackstate.cluster.authToken.

How to use in values.yaml

A service token must be used instead of API key as they are synonymous. Any environment variable that continues to refer to apiKey is for backwards compatibility.

  1. Using Automatic Secret Creation (Default):

     stackstate:
   apiKey: "<your service token>"

  2. Managing Own Secrets:

     global:
   apiKey:
     fromSecret: "observability-agent-config"
   clusterName:
     fromSecret: "observability-agent-config"
   url:
     fromSecret: "observability-agent-config"
   clusterAgentAuthToken:
     fromSecret: "name-of-my-cluster-agent-auth-token-secret"

In this example, observability-agent-config must contain STS_API_KEY (the service token), STS_CLUSTER_NAME and STS_URL. The separate cluster-agent authorization secret must contain STS_CLUSTER_AGENT_AUTH_TOKEN; omit global.clusterAgentAuthToken.fromSecret to let the chart generate that token automatically.

Use lowercase letters, digits, dots and dashes for STS_CLUSTER_NAME, starting and ending with a letter or digit. Set STS_URL to the HTTP(S) receiver URL without a trailing slash. Logs and OTel endpoints are derived from this URL; explicit otel.platformHttpOtlpEndpoint or otel.platformGrpcOtlpEndpoint overrides still take precedence.

The chart does not read secret contents during rendering, so Helm cannot validate these values and Fleet does not need access to their contents.