GEL admin API

Grafana Enterprise Logs admin API

In the following examples, the environment variable API_TOKEN contains the admin token. Refer to Generate an admin token.

It is also possible to create instances (tenants), access policies, and tokens using the plugin.

Instances (tenants)

An instance (tenant) is made up of the following fields:

  • name: The machine-readable name of an instance (tenant). It must be between 3 and 64 characters and only include the following characters, [a-z0-9-_]. Once set, this field is immutable.
  • display_name: The human-readable name of an instance (tenant). It can contain any set of characters and can be changed.
  • status: The current status of this instance (tenant). It can have the following values:
    • active
    • inactive
    • unknown
  • cluster: The name of the GEL cluster to which this instance (tenant) is scoped. You can only write to or query this instance from this cluster.

Create an instance (a tenant)

To create an instance (a tenant), send a POST request to the /admin/api/v1/instances endpoint.

Example:

$ curl -u :$API_TOKEN localhost:3100/admin/api/v1/instances \
--data '{"name":"dev", "display_name":"Dev Instance", "cluster": "dev-cluster"}'

Read instance (tenant) details

To read the details of an instance (a tenant), use the /admin/api/v1/instances/{name} endpoint.

Example:

$ curl -u :$API_TOKEN localhost:3100/admin/api/v1/instances/enterprise-logs-dev | jq
{
  "name": "enterprise-logs-dev",
  "display_name": "Enterprise Logs Dev Instance",
  "created_at": "2021-02-01T17:37:59.341728283Z",
  "status": "active",
  "cluster": "dev-cluster"
}

Delete an instance (tenant)

To delete an instance (a tenant), use the the/admin/api/v1/instances/{name} endpoint.

Example:

$ curl -X "DELETE" -u :$API_TOKEN localhost:3100/admin/api/v1/instances/enterprise-logs-dev

Access policies

An access policy is made up of the following fields:

  • name: The machine-readable name of a policy.
  • display_name: The human-readable name of an instance (a tenant). It can contain any set of characters and can be changed.
  • created_at: An RFC3339-formatted date time.
  • expiration: An RFC3339-formatted date time
  • realms: A list of realms.
  • scopes: A list of scopes.

A realm designates the instance/cluster pairs for which the access policy allows requests:

  • instance: You must set this field an existing instance (tenant) or *. *, which denotes access to all instances (tenants).
  • cluster: You must set this field to an existing cluster.

A scope designates what operations that the tokens, which are assigned to this access policy, are able to perform when calling the GEL API.

  • logs:read: Permission to view data from an instance (a tenant).
  • logs:write: Permission to write data to an instance (a tenant).
  • logs:delete: Permission to delete data from an instance (a tenant).
  • admin: Permission to perform admin operations.

Create an access policy

To create an instance (a tenant), send a POST request to the /admin/api/v1/accesspolicies endpoint.

$ curl -u :$API_TOKEN localhost:3100/admin/api/v1/accesspolicies \
--data '{"name":"ap1", "display_name":"First access policy", \
  "created_at": "2021-02-01T17:37:59.341728283Z", \
  "expiration": "2021-03-01T17:37:59.341728283Z", \
  "realms": [{"instance": "enterprise-logs-dev", "cluster": "dev-cluster"}], \
  "scopes": ["logs:read", "logs:write"]}'

Read an access policy

To read the details of an instance (a tenant), use the /admin/api/v1/accesspolicies/{name} endpoint.

Example:

$ curl -u :$API_TOKEN localhost:3100/admin/api/v1/accesspolicies/ap1 | jq
{
  "name": "ap1",
  "display_name": "First access policy",
  "created_at": "2021-02-01T17:37:59.341728283Z",
  "realms": [
    {
      "instance": "enterprise-logs-dev",
      "cluster": "dev-cluster"
    }
  ],
  "expiration": "2021-03-01T17:37:59.341728283Z",
  "scopes": [
    "logs:read",
    "logs:write"
  ]
}

Delete an access policy

To delete an instance (a tenant), send a DELETE request to the /admin/api/v1/accesspolicies/{name} endpoint.

Tokens

A token is made up of the following fields:

  • name: The machine-readable name of a policy.
  • display_name: The human-readable name of an instance (tenant). It can contain any set of characters and can be changed.
  • created_at: An RFC3339-formatted date time.
  • expiration: An RFC3339-formatted date time.
  • access_policy: The name of the access policy

Create a token

To create a token, send a POST request to the /admin/api/v1/tokens endpoint.

Example:

$ curl -u :$API_TOKEN localhost:3100/admin/api/v1/tokens \
--data '{"name":"devtoken", "display_name":"Dev token", \
  "created_at": "2021-02-01T17:37:59.341728283Z", \
  "expiration": "2021-03-01T17:37:59.341728283Z", \
  "access_policy": "ap1"}'

Read a token

To read the details of a token, use the /admin/api/v1/tokens/{name} endpoint.

Delete a token

To delete a token, send a DELETE request to the /admin/api/v1/token/{name} endpoint.

Verify that you can write data to your GEL instance (tenant)

The following command pushes a log line by using the Loki API. The TOKEN environment variable contains the preceding token that was created. The value 1612951327316545500 is the current Unix epoch time in nanoseconds at the time of writing; adjust this to the current time. On Linux, you can use the date +%s%N command:

$ date +%s%N
1612951327316545500

Next, the timestamp is used to push a log line:

$ curl -u :$TOKEN localhost:3100/loki/api/v1/push \
-H "Content-Type: application/json" \
-H "X-Scope-OrdID: dev" \
--data '{"streams": [{ "stream": { "job": "example" }, "values": [ [ "1612951327316545500", "A log line" ] ] }]}'