Service tokens

Overview

Using Service tokens it’s possible to authenticate to SUSE Observability without having an associated 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 sts CLI. The following commands are available:

> 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 when installing SUSE® Observability.

Create service tokens

The Open Telemetry and Kubernetes StackPacks let you create a subject and service token with all required permissions set up.

To create a service token for SUSE® Observability, you can use the sts CLI.

sts service-token create

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-k8s-troubleshooter:

> sts service-token create --name my-service-token --roles stackstate-k8s-troubleshooter
✅ 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 using the CLI without first interacting with SUSE® Observability and obtaining an API token from the UI. In order to set this up, 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:

stackstate:
  authentication:
    serviceToken:
      bootstrap:
        token: <token>
        roles:
          - stackstate-admin
        ttl: 24h

Follow the steps below to configure SUSE® Observability to create a bootstrap service token:

  1. In authentication.yaml - add the bootstrap token:

    • token - The token that is created at the (initial) start of SUSE® Observability.

    • roles - An array of roles that are assigned to the bootstrap token.

    • ttl - Optional. The time-to-live for the service token, expressed as a duration string.

  2. Store the file authentication.yaml together with the values.yaml from the SUSE® Observability installation instructions.

  3. Run a Helm upgrade to apply the changes.

     helm upgrade \
   --install \
   --namespace suse-observability \
   --values values.yaml \
   --values authentication.yaml \
 suse-observability \
 suse-observability/suse-observability

  • 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

Instead of specifying the bootstrap token via the Helm values you can also read the bootstrap token from a secret that is created and managed outside of the Helm chart (an external secret). To use a boostrap token from an external, follow these steps and add the following data:

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 sts CLI. For example:

> sts service-token list
ID              | NAME             | EXPIRATION | ROLES
107484341630693 | my-service-token |            | [stackstate-admin]

Delete service tokens

A service token can be deleted using the sts CLI. Pass the ID of the service token as an argument. For example:

> sts service-token delete 107484341630693
✅ Service token deleted: 107484341630693

Use service tokens

You use Service tokens to authenticate when using the SUSE Observability APIs: * When using the CLI * When using the HTTP APIs directly * When ingesting telemetry data

SUSE Observability sts CLI

A service token is used for authentication with the sts CLI. For more information, see the CLI documentation.

SUSE Observability APIs

To use a service token to talk directly to the SUSE Observability API, add it to the header of the request in one of the following ways:

  • In the Authorization header:

      > curl -X GET -H "Authorization: ApiKey <TOKEN>" http://localhost:8080/api/server/status

  • In the X-API-Key header:

      > curl -X GET -H "X-API-Key: <TOKEN>" http://localhost:8080/api/server/status

Telemetry Data Ingestion

In order to create a Service Token for telemetry data ingestion you need first to create a role:

> 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

If you want to use the service token to ingest Kubernetes RBAC data, you also need to grant update-scoped-permissions:

> sts rbac grant --subject my-agent --permission update-scoped-permissions --resource my-cluster
✅ Granted permission 'update-scoped-permissions' on 'my-cluster' to subject 'my-agent'
PERMISSION                | RESOURCE
update-metrics            | system
update-scoped-permissions | my-cluster

This will create a new role in SUSE Observability called my-agent and grant it the update-metrics permission. You can then create a ServiceToken for this role:

> sts service-token create --name my-agent --roles my-agent
✅ Service token created: svctok-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The newly created service token can be used as the api key for authentication of telemetry data from: