Admin API Documentation

Admin API

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

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.

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"
}