rancher · rb3ckers · Jan 29, 2026 · Jan 15, 2026 · Jan 15, 2026 · Jan 20, 2026
@@ -34,4 +34,4 @@ checkmake:
 
 .PHONY: preview
 preview:
-	npx http-server build/remote-site -c-1
+	npx http-server build/site -c-1
@@ -1,181 +1,8 @@
 = Service tokens
 :revdate: 2025-07-10
 :page-revdate: {revdate}
-:description: SUSE Observability Self-hosted
+:description: SUSE Observability
 
 == Overview
 
-Using Service tokens it's possible to authenticate to SUSE Observability without having configured a user account. This is useful for situations where you want to use SUSE Observability from headless services like a CI server. In such a scenario you typically don't want to provision a user account in your identity provider.
-
-== Manage service tokens
-
-Service tokens can be managed via the xref:/setup/cli/cli-sts.adoc[`sts` CLI]. The following commands are available:
-
-[,bash]
-----
-> sts service-token --help
-Manage service tokens.
-
-Usage:
-  sts service-token [command]
-
-Available Commands:
-  create      Create a service token
-  delete      Delete a service token
-  list        List service tokens
-
-Use "sts service-token [command] --help" for more information about a command.
-----
-
-It's also possible to <<_set_up_a_bootstrap_service_token,set up a bootstrap service token>> when installing SUSE Observability.
-
-=== Create service tokens
-
-To create a service token for an installed instance of SUSE Observability, you can use the new `sts` CLI.
-
-[,sh]
-----
-sts service-token create
-----
-
-[NOTE]
-====
-Note that the service token will only be displayed once. It isn't possible to see the token again.
-====
-
-
-This command takes the following command line arguments:
-
-|===
-| Flag | Description
-
-| `--name`
-| The name of the service token
-
-| `--expiration`
-| The expiration date of the service token, the format is yyyy-MM-dd. The expiration is optional.
-
-| `--roles`
-| A comma separated list of roles to assign to the service token
-|===
-
-For example, the command below will create a service token with the name `my-service-token` and the role `stackstate-power-user`:
-
-[,sh]
-----
-> sts service-token create --name my-service-token --roles stackstate-power-user
-✅ Service token created: svctok-aaaaa-bbbb-ccccc-ddddd
-----
-
-=== Set up a bootstrap service token
-
-When installing SUSE Observability, it's possible to bootstrap it with a (temporary) service token. This allows for using the CLI without first interacting with SUSE Observability and obtaining an API token from the UI. In order to set this up, you can add the following snippet to the SUSE Observability configuration file:
-
-To configure SUSE Observability to create a bootstrap service token on Kubernetes, The following values need to be added to the file `authentication.yaml`. For example
-
-[,yaml]
-----
-stackstate:
-  authentication:
-    serviceToken:
-      bootstrap:
-        token: <token>
-        roles:
-          - stackstate-power-user
-        ttl: 24h
-----
-
-Follow the steps below to configure SUSE Observability to create a bootstrap service token:
-
-. In `authentication.yaml` - add the bootstrap token:
- ** *token* - The token that will be created on (initial) start of SUSE Observability.
- ** *roles* - An array of roles that will be assigned to the bootstrap token.
- ** *ttl* - Optional. The time-to-live for the service token, expressed as a duration string.
-. Store the file `authentication.yaml` together with the `values.yaml` from the SUSE Observability installation instructions.
-. Run a Helm upgrade to apply the changes.
-+
-[,text]
-----
- helm upgrade \
-   --install \
-   --namespace suse-observability \
-   --values values.yaml \
-   --values authentication.yaml \
- suse-observability \
- suse-observability/suse-observability
-----
-
-[NOTE]
-====
-*Note:*
-
-* The first run of the helm upgrade command will result in pods restarting, which may cause a short interruption of availability.
-* Include `authentication.yaml` on every `helm upgrade` run.
-* The authentication configuration is stored as a Kubernetes secret.
-====
-
-
-==== Setup the bootstrap service token from an external secret
-
-When the bootstrap token should come from an external secret, follow xref:/setup/security/external-secrets.adoc#_getting_authentication_data_from_an_external_secret[these steps] and add the following data:
-
-[,yaml]
-----
-kind: Secret
-metadata:
-   name: "<custom-secret-name>"
-type: Opaque
-data:
-  bootstrap_token: <base64 of token>
-----
-
-This token can be added to the secret next to the data that is already there.
-
-=== List service tokens
-
-The ID, name, expiration date and roles of all created service tokens can be seen using the new `sts` CLI. For example:
-
-[,bash]
-----
-> sts service-token list
-ID              | NAME             | EXPIRATION | ROLES
-107484341630693 | my-service-token |            | [stackstate-power-user]
-----
-
-=== Delete service tokens
-
-A service token can be deleted using the new `sts` CLI. Pass the ID of the service token as an argument. For example:
-
-[,bash]
-----
-> sts service-token delete 107484341630693
-✅ Service token deleted: 107484341630693
-----
-
-== Use service tokens
-
-Once created, a service token can be used to authenticate to SUSE Observability from a headless service. To do this you can either use the CLI or directly talk to the API.
-
-=== SUSE Observability `sts` CLI
-
-A service token can be used for authentication with the `sts` CLI. For details, see xref:/setup/cli/cli-sts.adoc#_authentication[the CLI documentation].
-
-=== SUSE Observability APIs
-
-To use a service token to talk directly to the SUSE Observability Base API, add it to the header of the request in one of the following ways:
-
-* In the `Authorization` header:
-+
-[,bash]
-----
-  > curl -X GET -H "Authorization: ApiKey <TOKEN>" http://localhost:8080/api/server/status
-----
-
-* In the `X-API-Key` header:
-+
-[,bash]
-----
-  > curl -X GET -H "X-API-Key: <TOKEN>" http://localhost:8080/api/server/status
-----
-
-➡️ xref:/setup/cli/cli-sts.adoc#_authentication[Learn more about the SUSE Observability APIs]
+Use the xref:use/security/k8s-service-tokens.adoc[Service Tokens] to authenticate authenticate to SUSE Observability without having an associated a user account. Service tokens are the preferred way to authenticate from CI/CD, or when sending telemetry data from agents or Open Telemetry. How to create and use service tokens is described in the xref:use/security/k8s-service-tokens.adoc[Service Tokens documentation].
@@ -73,7 +73,7 @@ The following permissions are available in SUSE Observability:
 
 |service-token
 |get, create, delete
-|xref:/use/security/k8s-service-tokens.adoc[Service tokens] authenticate an external service and can be used for data ingestion.
+|xref:/setup/security/authentication/service_tokens.adoc[Service tokens] authenticate an external service and can be used for data ingestion.
 
 |settings
 |get, update, unlock

@@ -29,7 +29,7 @@ This will create a new role in SUSE Observability called `grafana` and grant it
 ✅ Service token created: svctok-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 ----
 
-Learn more about xref:/use/security/k8s-service-tokens.adoc[managing ServiceTokens].
+Learn more about xref:/setup/security/authentication/service_tokens.adoc[managing ServiceTokens].
 
 The returned ServiceToken can be used to authenticate with SUSE Observability. You can now add SUSE Observability as a datasource in Grafana.
 

@@ -1,29 +1,55 @@
-= API Keys
+= API Keys (deprecated)
 :revdate: 2025-07-22
 :page-revdate: {revdate}
 :description: SUSE Observability
 
-An API key is primarily used to authenticate against {stackstate-product-name} for sending telemetry data to {stackstate-product-name}. In a helm agent install, this is done by setting the `stackstate.apiKey` helm variable.
+An API key was used to authenticate against {stackstate-product-name} for sending telemetry data to {stackstate-product-name}. In a Helm agent install, this was done by setting the `stackstate.apiKey` helm variable.
 
-You can obtain an API key by following the xref:/k8s-suse-rancher-prime.adoc#_installing_the_suse_observability_agent[StackPack install flow], which uses a Service Token from the platform. 
+API Keys, and Ingestion API keys, are deprecated and will be removed in Q4 of 2026. Service tokens are now the preferred authentication mechanism, also for sending telemetry data. 
 
-You can also obtain an API Key in the following ways from the platform:
+The flow for adding new clusters to {stackstate-product-name} in xref:/k8s-suse-rancher-prime.adoc#_installing_the_suse_observability_agent[StackPack install flow] includes the creation of a cluster specific token that is compatible with the RBAC Agent for Rancher RBAC.
 
-* **Service Token** - Use this key to scope the data to be ingested. A service token is required when installing with xref:/setup/security/rbac/rbac_rancher.adoc[Rancher RBAC support]. It also offers expiration dates. For more information, see xref:/use/security/k8s-service-tokens.adoc#_authenticate_using_service_tokens_for_data_ingestion[Service Tokens].
-* **Bootstrap Service Token** - Use this API key to set up a service token for data ingestion and RBAC. This is the preferred method to create a key before installation. For more information, see xref:/setup/security/authentication/service_tokens.adoc#_set_up_a_bootstrap_service_token[Bootstrap Service Tokens].
-* **Receiver API Key** - This key is generated during the initial installation of your {stackstate-product-name} instance and it never expires. As it is not scoped, it can be used for all agents. 
+== Migrating from API key to service token
 
-[NOTE]
-====
-This method will be replaced in the long run as the RBAC data cannot be ingested with the receiver API Key.
-====
-* **Ingestion API Key** (Deprecated) - You can create Ingestion API Keys using the {stackstate-product-name} CLI (STS). These keys offer expiration dates, requiring periodic rotation for continued functionality.
+There are 2 options to migrate from using the single API Key to using Service Tokens for telemetry data. 
 
-== Ingestion API Keys (`Deprecated`)
+1. Migrate to a Service Token per cluster. This is a bit more work to set up but it supports Rancher RBAC.
+2. Migrate to a single Service Token that you use from all Kubernetes clusters and OTel collectors. This does not support Rancher RBAC.
+
+After migrating all agents and Open Telemetry collectors to service tokens you can now remove the `global.receiverApiKey` or `stackstate.apiKey` from the Helm values for installing {stackstate-product-name} and run a `helm upgrade` to apply the changes.
+
+=== Migrate to a service token per cluster
+
+1. Open the Kubernetes Stackpack in the UI
+2. Expand the cluster you are migrating
+3. Click the "Create new service token" button to get the cluster specific service token and copy the token
+4. Follow the agent installation/upgrade instructions in the stackpack to re-deploy the agent to the cluster with the service token as the API key.
+
+Instead of using the UI you can also generate the token with the CLI as xref:setup/security/authentication/service_tokens#_telemetry_data_ingestion[documented here]. Make sure to also assign the `update-scoped-permissions` scoped to the cluster you are migrating. The other steps remain the same as for the UI.
+
+=== Migrate to a single service token
+
+Generate a service token with the CLI as xref:setup/security/authentication/service_tokens#_telemetry_data_ingestion[documented here].:
+
+[,sh]
+----
+> sts rbac create-subject --subject my-agent
+✅ Created subject 'my-agent'
+> sts rbac grant --subject my-agent --permission update-metrics
+✅ Granted permission 'update-metrics' on 'system' to subject 'my-agent'
+PERMISSION   | RESOURCE
+update-metrics | system
+----
+
+Don't add a `update-scoped-permissions` permission, that will not work for a token that is used from multiple clusters.
+
+Now re-deploy your agents and Open Telemetry collectors by following the instructions available in the UI for the Kubernetes StackPack and the xref:setup/otel/getting-started/getting-started-k8s.adoc[Open Telemetry collector documentation]. Use the generated Service Token as the API key by following.
+
+== Migrate from Ingestion API Keys
 
 Ingestion API Keys were used by external tools to ingest data (such as metrics, events and traces) to the SUSE Observability cluster.
-These tools include the STS Agent or/and OTel Collector. The recommended authentication mechanism is through xref:/use/security/k8s-service-tokens.adoc#_authenticate_using_service_tokens_for_data_ingestion[Service Tokens].
+These tools include the STS Agent or/and OTel Collector. Service tokens have the same, and more, capabilities. Follow the same steps as for the API key (in the previous setion) to migrate to <<_migrate_to_a_service_token_per_cluster, a service token per cluster>> or <<_migrate_to_a_single_service_token, a single service token>>.
 
 == More info
 
-* xref:/use/security/k8s-service-tokens.adoc[Service tokens]
+* xref:use/security/k8s-service-tokens.adoc[Service tokens]