Service accounts

A service account provides an identity that a service can use to access Chronosphere APIs, Chronoctl, Terraform, and the Chronosphere Collector. Use service accounts for automated, programmatic interactions, such as CI/CD, ingesting telemetry, or automated queries. Chronosphere Observability Platform attributes all actions that a service takes to its service account. A service account can’t access the user interface, only the APIs. Accounts can belong to teams. When you create a service account, Chronosphere also creates a non-expiring API token that the service account uses for authentication.

Service accounts are distinct from user accounts, which provide identities for users who can also authenticate interactively and use Chronosphere Observability Platform.To use tools that require non-interactive authentication, such as Chronoctl, Terraform, or the Chronosphere API, create a temporary personal access token with the same permissions as your user account. You can also assign service accounts to teams with the SysAdmin role, which also grants those service accounts administrative permissions.For details about accounts and teams, see Accounts and Teams. For details about interactive user account authentication, see Authenticating with Observability Platform.

View service accounts

Web
Chronoctl
API

In the navigation menu, click Go to Admin and then select Platform > Service Accounts.

To return all service accounts and their label restrictions, use the Chronoctl service-accounts list command.For example, to return all service accounts in JSON format, run:

chronoctl service-accounts list --output=json

To complete this action with the Chronosphere API, use the ListServiceAccounts endpoint.Because the Chronosphere API requires authentication, include an API token with your curl request, as shown in the following example. For more details, see Create an API token.

export CHRONOSPHERE_API_TOKEN="TOKEN"
export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
     -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"

Replace the following:

TOKEN: Your API token.
INSTANCE: The subdomain name for your organization’s Observability Platform instance.
METHOD: The HTTP method to use with the request, such as GET or POST.
ENDPOINT_PATH: The specific endpoint you want to access.

The service account list contains the following information:

Name: The service account name.
Service account email: The unique email user for this service account.
Created by: The service account creator.
Restriction: The type of restrictions on this account. Unrestricted accounts don’t have a value here.
Last used: When this service token was last accessed. This field can be inaccurate if more than 1000 service accounts are active.
Metric label: For restricted accounts, the key/value label pair restriction.

If you have a service account token, and don’t know which account it belongs to, use the following Chronoctl command:

chronoctl auth whoami --api-token=TOKEN

Replace TOKEN with your service account token.

Create a service account

New service accounts can be one of the following types, each configured differently:

An unrestricted service account, which grants full access to all Chronosphere APIs and entities, including administration and monitoring features.
A restricted service account, which grants certain permissions to access only telemetry data, and optionally limiting displayed metrics to those with one or a pair of specific, case-sensitive label names and values.

To use a service account with Chronoctl or Terraform, you must create an unrestricted service account. To use a service account with the Chronosphere Collector, create a restricted write-only service account.

Create an unrestricted service account

A service account can access the entire Chronosphere API, but this access doesn’t necessarily grant it all possible privileges. You can also assign the SysAdmin role to the team that the service account belongs to, but doing so is required only if the service account needs to create, modify, and delete accounts, teams, and certain resources. To make an unrestricted service account read-only, remove it from the Default team and any other team that grants the Editor or SysAdmin role. The account retains read-only access to all Chronosphere APIs. For more information, see Assign team roles and permissions.

You must be a member of a team with the SysAdmin role to create a new service account.

Select from the following methods to create an unrestricted service account.

Web
Chronoctl
Terraform
API

To create an unrestricted service account:

In the navigation menu, click Go to Admin and then select Platform > Service Accounts.
Click + Service Account. This opens the Add Service Account dialog.
In the Service Account Name field, enter a descriptive name for the service account.
In the Service Account Type section, select Unrestricted.
Click Save.

After creating the service account, Chronosphere displays its secret token.

This is the only time Observability Platform displays the service account’s token. Store it securely. If you lose the token, you must delete and recreate the service account to generate a new token.

To create and manage service accounts with Chronoctl, the account you use must either be a member of a team with the SysAdmin role or an unrestricted service account.

Generate a templated service account resource with the chronoctl service-accounts scaffold command:
chronoctl service-accounts scaffold > service-account.yml
Replace service-account.yml with any valid filename.
Edit the generated template to configure the new service account. Remove any fields that you don’t need to configure. For example, to configure an unrestricted service account with the slug ci-build-account and name CI Build Account, the resulting resource is:
service-account.yml
api_version: v1/config kind: ServiceAccount spec: slug: ci-build-account name: CI Build Account unrestricted: true

Create the resource by passing the file containing the resource to the service-accounts create command.

chronoctl service-accounts create -f service-account.yml

The command returns the service account resource, including its secret API token:

api_version: v1/config
kind: ServiceAccount
spec:
  slug: ci-build-account
  name: CI Build Account
  token: acc261....
  email: 7da....@serviceaccount.chronosphere.io
  unrestricted: true

To create an unrestricted service account with Terraform, use the chronosphere_service_account resource type and assign a name to use in Observability Platform inside the resource declaration.For example, this code creates a service account without any restrictions that Terraform refers to as all_access:

resource "chronosphere_service_account" "all_access" {
  name = "Terraform - Unrestricted"
}

Add the definition to a Terraform file.
Run this command to create the resource:
terraform apply

Terraform stores the new service account’s secret token in its state. To use the token in other Terraform resources, use the .token field of the service account resource.Using the previous example, the token for the service account with the Terraform resource name all_access is accessible at chronosphere_service_account.all_access.token.To view the token, inspect your Terraform state file. For example, you can use the jq tool to filter service accounts in the state file:

jq '.resources[] | select(.type=="chronosphere_service_account")' terraform.tfstate

To complete this action with the Chronosphere API, use the CreateServiceAccount endpoint and update the service_account.unrestricted key.Because the Chronosphere API requires authentication, include an API token with your curl request, as shown in the following example. For more details, see Create an API token.

export CHRONOSPHERE_API_TOKEN="TOKEN"
export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
     -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"

Replace the following:

TOKEN: Your API token.
INSTANCE: The subdomain name for your organization’s Observability Platform instance.
METHOD: The HTTP method to use with the request, such as GET or POST.
ENDPOINT_PATH: The specific endpoint you want to access.

Create a restricted service account

A restricted service account can access only the telemetry ingest and query APIs. The account can’t access any of the other APIs. It can’t make configuration changes, such as adding rules, creating monitors, or adding accounts. You can also optionally define Label Restrictions on restricted accounts to limit the account to querying or ingesting only specific labels or label-value pairs when authenticating with the account’s token. The following types of restricted service accounts are available:

Read-only accounts are permitted only to query data. If you also define Label Restrictions, the account can query only metrics with the defined metric label keys or key-value pairs.
Write-only accounts are permitted only to ingest data. If you also define Label Restrictions, the account can ingest only metrics with the defined metric label keys or key-value pairs.
Read & write accounts are permitted to both query and ingest data, following any defined Label Restrictions.

Write-only accounts are based on the principle of least privilege. A robot whose only job is to send ingest data to the server doesn’t need query access. Restricted, read-only service accounts are restricted to reading even if the service account is added to a team with Editor or SysAdmin roles. Restricted accounts using label restrictions force a label with a specific value to be present on write, and allows queries that include only that label/value pair. Label restrictions support a maximum of two key/value pairs. Key/value pairs on individual service accounts must be unique. You can’t set multiple values for the same label key.

Observability Platform strips this label from query responses. Users with a restricted service account aren’t aware that they’re viewing metrics that match only the specified label.Users see all other telemetry.

Select from the following methods to create a restricted service account.

Web
Chronoctl
Terraform
API

To create a restricted service account, you must have administrative privileges.

In the navigation menu, click Go to Admin and then select Platform > Service Accounts.
Click + Service Account. This opens the Add Service Account dialog.
In the Service Account Name field, enter a descriptive name for the service account.
In the Service Account Type section, select Restricted. Observability Platform displays additional fields for you to complete.
Complete the creation process based on your needs. Use the Label Restrictions section to limit this account’s metrics access to only labels with one, or a pair of specific key/value pairs. Click +Add Label to add a second key/value pair. Label restrictions are case sensitive.
Click Save.

After creating the service account, Observability Platform displays its secret token.

To create a restricted service account with Chronoctl, use the service-accounts create command.Specify required values as command arguments:

name (--name)
permission (--permission). Valid permission values are:
- READ: Read-only access.
- WRITE: Write access.
- READ_WRITE: Read and write access.

You can also specify optional metric label arguments:

label name (--label-name)
label value (--label-value)

Generate a templated service account resource with the service-accounts scaffold command:
chronoctl service-accounts scaffold > service-account.yaml
Replace service-account.yaml with any valid filename.
Edit the generated template to configure the new service account. Remove any fields that you don’t need to configure. For example, to configure a restricted service account that can read and write only metrics with the label tenant and the value name, the resulting resource is:
service-account.yml
api_version: v1/config kind: ServiceAccount spec: slug: tenant-name name: tenant metrics_restriction: labels: tenant: name permission: READ_WRITE

Create the service account:

chronoctl service-accounts create -f service-account.yml

The command returns the service account resource, including its secret API token:

api_version: v1/config
kind: ServiceAccount
spec:
  slug: tenant-name
  name: tenant
  metrics_restriction:
    labels:
      tenant: name
  token: acc261....
  email: 7da....@serviceaccount.chronosphere.io

To create a restricted service account using Terraform, use the chronosphere_service_account resource type followed by a resource name, and include a restriction section in the resource declaration.You must add a permission value in the restriction section to define the account’s access. Valid permission values are:

READ: Read-only access.
WRITE: Write access.
READ_AND_WRITE: Read and write access.

You can optionally add a labels value in the restriction section to additionally restrict the service account’s access to limit metrics to display only those that have the specified label name and value.For example, this code creates a restricted service account that Terraform refers to as restricted_labeled, which can only read and write metrics with the label name tenant and label value name:

resource "chronosphere_service_account" "restricted_labeled" {
  name = "Terraform - Restricted, READ_AND_WRITE, labeled"
  restriction {
    permission = "READ_AND_WRITE"
    labels     = { "tenant" : "name" }
  }
}

Add the definition to a Terraform file.
Run this command to create the resource:
terraform apply

jq '.resources[] | select(.type=="chronosphere_service_account")' terraform.tfstate

To complete this action with the Chronosphere API, use the CreateServiceAccount endpoint.Because the Chronosphere API requires authentication, include an API token with your curl request, as shown in the following example. For more details, see Create an API token.

export CHRONOSPHERE_API_TOKEN="TOKEN"
export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
     -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"

Replace the following:

TOKEN: Your API token.
INSTANCE: The subdomain name for your organization’s Observability Platform instance.
METHOD: The HTTP method to use with the request, such as GET or POST.
ENDPOINT_PATH: The specific endpoint you want to access.

Label restriction example

Label restrictions support a third-party use case, where Chronosphere is the first party, and a Chronosphere customer (CompanyX) is the second party. A Chronosphere customer’s customer (CompanyA, CompanyB, or CompanyC) is the third party. In this scenario, CompanyX uses one tenant with Chronosphere to store data about CompanyA, CompanyB, and CompanyC, discriminated by some key (such as third-party) with a value of A, B, or C. Employees of CompanyX can see all of the data. Employees of CompanyA get a restricted service account with a label restriction of third-party=A. CompanyA doesn’t know this key or this value. Whenever they send data to Chronosphere, Chronosphere augments the writes with third-party=A. Whenever CompanyA does queries, Chronosphere lets them see time series that include only third-party=A, but Chronosphere strips this label before showing the time series to employees of CompanyA.

Delete a service account

Select from the following methods to delete a service account.

Users can modify Terraform-managed resources only by using Terraform. Learn more.

Web
Chronoctl
Terraform
API

To delete a service account, you must have administrative privileges.

In the navigation menu, click Go to Admin and then select Platform > Service Accounts.
Select the checkboxes for one or more service accounts you want to delete.
Click Delete at the top of the list of service accounts.

To delete a service account with Chronoctl, the account you use must either be a member of a team with the SysAdmin role, or an unrestricted service account.Use the service-accounts delete command, passing the account’s slug as the --slug argument.For example, to delete a service account with the slug tenant-name:

chronoctl service-accounts delete tenant-name

To delete a resource that’s managed by Terraform:

Edit your Terraform configuration file to remove the pre-existing resource definition.
Run this command to remove the resource from Observability Platform:
terraform apply

To complete this action with the Chronosphere API, use the DeleteServiceAccount endpoint.Because the Chronosphere API requires authentication, include an API token with your curl request, as shown in the following example. For more details, see Create an API token.

export CHRONOSPHERE_API_TOKEN="TOKEN"
export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
     -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"

Replace the following:

TOKEN: Your API token.
INSTANCE: The subdomain name for your organization’s Observability Platform instance.
METHOD: The HTTP method to use with the request, such as GET or POST.
ENDPOINT_PATH: The specific endpoint you want to access.

Observability Platform

Telemetry Pipeline

More information

View service accounts

Create a service account

Create an unrestricted service account

Create a restricted service account

Label restriction example

Delete a service account

​View service accounts

​Create a service account

​Create an unrestricted service account

​Create a restricted service account

​Label restriction example

​Delete a service account

View service accounts

Create a service account

Create an unrestricted service account

Create a restricted service account

Label restriction example

Delete a service account