Admin API

Admin API Documentation

In addition to the standard Cortex API endpoints, Grafana Metrics Enterprise supports an admin HTTP API for managing cluster resources such as instances and tokens.

Cluster API

List Clusters

GET /admin/api/v1/clusters

Response:

{
  "items": [
    {
      "name":  "<string>",              // cluster name
      "display_name": "<string>",       // cluster display name
      "created_at": "<rfc3339 string>", // date created 
      "kind": "<string>",               // cluster type, currently only cortex is supported
      "base_url": "<string>"            // Base URL of the cluster, optional
    }
    ...
  ],
  "type": "cluster"
}

Example:

$ curl -u :$API_TOKEN http://localhost:8080/admin/api/v1/clusters | jq
{
  "items": [
    {
      "name": "metrics-enterprise-dev",
      "display_name": "metrics-enterprise-dev",
      "created_at": "2020-07-13T16:50:41.953793Z",
      "kind": "cortex",
      "base_url": ""
    }
  ],
  "type": "cluster"
}

Get Cluster

GET /admin/api/v1/clusters/{name}

Response:

{
  "name":  "<string>",              // cluster name
  "display_name": "<string>",       // cluster display name
  "created_at": "<rfc3339 string>", // date created 
  "kind": "<string>",               // cluster type, currently only cortex is supported
  "base_url": "<string>"            // Base URL of the cluster, optional
}

Example:

$ curl -u :$API_TOKEN http://localhost:8080/admin/api/v1/clusters/metrics-enterprise-dev | jq
{
  "name": "metrics-enterprise-dev",
  "display_name": "metrics-enterprise-dev",
  "created_at": "2020-07-13T16:50:41.953793Z",
  "kind": "cortex",
  "base_url": ""
}

Instance API

Model

The instance model is made up of the following fields:

  • name: The machine-readable name of an instance. 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. It can contain any set of characters and can be changed.
  • status: The current status of this instance. It can have the following values:
    • active
    • inactive
    • unknown
  • cluster: The name of the GME cluster that this instance is scoped to. You will only be able to write/query this instance from this cluster.

List Instances

GET /admin/api/v1/instances

Response:

{
  "items": [
    {
      "name": "<string>",
      "display_name": "<string>",
      "created_at": "<rfc3339 string>",
      "status": "<string>",
      "cluster": "<string>"
    },
    ...
  ],
  "type": "instance"
}

Example:

$ curl -u :$API_TOKEN localhost:8080/admin/api/v1/instances | jq
{
  "items": [
    {
      "name": "metrics-enterprise-dev",
      "display_name": "Metrics Enterprise Dev Instance",
      "created_at": "2020-07-13T17:37:59.341728283Z",
      "status": "active",
      "cluster": "metrics-enterprise-dev"
    }
  ],
  "type": "instance"
}

Create Instance

POST /admin/api/v1/instances

Example:

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

Get Instance

POST /admin/api/v1/instances/{name}

Response:

{
  "name": "<string>",
  "display_name": "<string>",
  "created_at": "<rfc3339 string>",
  "status": "<string>",
  "cluster": "<string>"
}

Example:

$ curl -u :$API_TOKEN localhost:8080/admin/api/v1/instances/metrics-enterprise-dev | jq
{
  "name": "metrics-enterprise-dev",
  "display_name": "Metrics Enterprise Dev Instance",
  "created_at": "2020-07-13T17:37:59.341728283Z",
  "status": "active",
  "cluster": "metrics-enterprise-dev"
}

Delete Instance

DELETE /admin/api/v1/instances/{name}

Example:

$ curl -u :$API_TOKEN localhost:8080/admin/api/v1/instances/metrics-enterprise-dev

Access Policy API

List Access Policies

GET /admin/api/v1/accesspolicies

Response:

{
  "items": [
    {
      "name": "<string>",
      "display_name": "<string>",
      "created_at": "<rfc3339 string>",
      "realms": [
        {
          "instance": "<string>",
          "cluster": "<string>"
        }
      ],
      "expiration": "<rfc3339 string>",
      "scopes": [
        "<string>",
        ...
      ]
    },
    ...
  ],
  "type": "key"
}

Create Access Policy

POST /admin/api/v1/accesspolicies

Payload:

{
  "name": "<string>",
  "display_name": "<string>",
  "created_at": "<rfc3339 string>",
  "realms": [
    {
      "instance": "<string>",
      "cluster": "<string>"
    }
  ],
  "expiration": "<rfc3339 string>",
  "scopes": [
    "<string>",
    ...
  ]
}

Realms

Realms designate the instance/cluster pairs that the access policy allows requests for:

  • instance: This field must be set to an existing instance or *. * denotes access to all instances.
  • cluster: This field must be set to an existing cluster.
  • label_policies: This is an optional field that can be set to a list of label policies. An access policy gets access to metrics that match at least one of the label policies. If label policies are not set, all metrics will match.
Label policy, selector and label matchers

A label policy contains a selector, that consists of a list of label matchers.

The following label matcher types are supported:

  • EQ: Select labels that are exactly equal to the provided string.
  • NEQ: Select labels that are not equal to the provided string.
  • RE: Select labels that regex-match the provided string.
  • NRE: Select labels that do not regex-match the provided string.
{
  "selector": [
    {
      "type": "<enum: EQ | NEQ | RE | NRE>",
      "name": "<string>",
      "value": "<string>"
    }
  ]
}

The PromQL selector {job="grafana-labs", role!="software-engineer"}, would translate into this label policy:

{
  "selector": [
    {
      "type": "EQ",
      "name": "job",
      "value": "grafana-labs"
    },
    {
      "type": "NE",
      "name": "role",
      "value": "software-engineer"
    }
  ]
}

Scopes

Scopes designate what operations tokens assigned to this access policy will be able to do when calling the GME API.

  • metrics:read: Permission to view data from an instance
  • metrics:write: Permission to write data to an instance
  • metrics:delete: Permission to delete data from an instance
  • admin: Permission to perform admin operations

Get Access Policy

POST /admin/api/v1/accesspolicies/{name}

Response:

{
  "name": "<string>",
  "display_name": "<string>",
  "created_at": "<rfc3339 string>",
  "realms": [
    {
      "instance": "<string>",
      "cluster": "<string>"
    }
  ],
  "expiration": "<rfc3339 string>",
  "scopes": [
    "<string>",
    ...
  ]
}

Delete Access Policy

DELETE /admin/api/v1/accesspolicies/{name}

Token API

List Tokens

GET /admin/api/v1/tokens

Response:

{
  "items": [
    {
      "name": "<string>",
      "display_name": "<string>",
      "created_at": "<rfc3339 string>",
      "expiration": "<rfc3339 string>",
      "access_policy": "<string>"
    },
    ...
  ],
  "type": "key"
}

Create Token

POST /admin/api/v1/tokens

Payload:

{
  "name": "<string>",
  "display_name": "<string>",
  "created_at": "<rfc3339 string>",
  "expiration": "<rfc3339 string>",
  "access_policy": "<string>"
}

Get Token

POST /admin/api/v1/tokens/{name}

Response:

{
  "name": "<string>",
  "display_name": "<string>",
  "created_at": "<rfc3339 string>",
  "expiration": "<rfc3339 string>",
  "access_policy": "<string>"
}

Delete Token

DELETE /admin/api/v1/tokens/{name}

License API

List Licenses

GET /admin/api/v1/licenses

Response:

{
  "items": [
    {
      "name": "<string>",
      "display_name": "<string>",
      "created_at": "<rfc3339 string>",
      "token": {
        "jti": "<string>",
        "iss": "<string>",
        "sub": "<string>",
        "iat": "<int64>",
        "exp": "<int64>",
        "nbf": "<int64>",
        "lexp": "<int64>",
        "lid": "<string>",
        "max_users": "<int64>",
        "included_admins": "<int64>",
        "included_viewers": "<int64>",
        "lic_exp_warn_days": "<int64>",
        "prod": [
          "<string>",
          ...
        ],
        "company": "<string>",
        "slug": "<string>",
      }
    },
    ...
  ],
  "type": "license"
}