enterprise/federation/v1

COMMERCIAL FEATURE: Access federation in the packaged Sensu Go distribution. For more information, read Get started with commercial features.

NOTE: Requests to enterprise/federation/v1 API endpoints require you to authenticate with a Sensu API key or access token. The code examples in this document use the environment variable $SENSU_API_KEY to represent a valid API key in API requests.

Get all replicators

The /etcd-replicators API endpoint provides HTTP GET access to a list of replicators.

NOTE: The etcd-replicators datatype is only accessible for users who have a cluster role that permits access to replication resources.

Example

The following example demonstrates a GET request to the /etcd-replicators API endpoint:

curl -X GET \
http://127.0.0.1:8080/api/enterprise/federation/v1/etcd-replicators \
-H "Authorization: Key $SENSU_API_KEY"

The request results in a successful HTTP/1.1 200 OK response and a JSON array that contains the etcd replicator definitions:

[
  {
    "api_version": "federation/v1",
    "type": "EtcdReplicator",
    "metadata": {
      "name": "my_replicator",
      "created_by": "admin"
    },
    "spec": {
      "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem",
      "cert": "/path/to/ssl/cert.pem",
      "key": "/path/to/ssl/key.pem",
      "insecure": false,
      "url": "http://remote-etcd.example.com:2379",
      "api_version": "core/v2",
      "resource": "Role",
      "replication_interval_seconds": 30
    }
  }
]

API Specification

/etcd-replicators (GET)
description Returns the list of replicators.
example url http://hostname:8080/api/enterprise/federation/v1/etcd-replicators
response type Array
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output 
[
  {
    "api_version": "federation/v1",
    "type": "EtcdReplicator",
    "metadata": {
      "name": "my_replicator",
      "created_by": "admin"
    },
    "spec": {
      "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem",
      "cert": "/path/to/ssl/cert.pem",
      "key": "/path/to/ssl/key.pem",
      "insecure": false,
      "url": "http://remote-etcd.example.com:2379",
      "api_version": "core/v2",
      "resource": "Role",
      "replication_interval_seconds": 30
    }
  }
]

Create a new replicator

The /etcd-replicators API endpoint provides HTTP POST access to create replicators.

NOTE: Create a replicator for each resource type you want to replicate. Replicating namespace resources will not replicate the resources that belong to those namespaces.

Example

The following example demonstrates a request to the /etcd-replicators API endpoint to create the replicator my_replicator:

curl -X POST \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "api_version": "federation/v1",
  "type": "EtcdReplicator",
  "metadata": {
    "name": "my_replicator"
  },
  "spec": {
    "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem",
    "cert": "/path/to/ssl/cert.pem",
    "key": "/path/to/ssl/key.pem",
    "insecure": false,
    "url": "http://remote-etcd.example.com:2379",
    "api_version": "core/v2",
    "resource": "Role",
    "replication_interval_seconds": 30
  }
}' \
http://127.0.0.1:8080/api/enterprise/federation/v1/etcd-replicators

The request will return a successful HTTP/1.1 201 Created response.

API Specification

/etcd-replicators (POST)
description Creates a new replicator (if none exists).
example URL http://hostname:8080/api/enterprise/federation/v1/etcd-replicators
payload 
{
  "api_version": "federation/v1",
  "type": "EtcdReplicator",
  "metadata": {
    "name": "my_replicator"
  },
  "spec": {
    "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem",
    "cert": "/path/to/ssl/cert.pem",
    "key": "/path/to/ssl/key.pem",
    "insecure": false,
    "url": "http://remote-etcd.example.com:2379",
    "api_version": "core/v2",
    "resource": "Role",
    "replication_interval_seconds": 30
  }
}
response codes
  • Success: 200 (OK)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

Get a specific replicator

The /etcd-replicators/:etcd-replicator API endpoint provides HTTP GET access to data for a specific :etcd-replicator, by replicator name.

NOTE: The etcd-replicators datatype is only accessible for users who have a cluster role that permits access to replication resources.

Example

The following example queries the /etcd-replicators/:etcd-replicator API endpoint for a specific :etcd-replicator.

curl -X GET \
http://127.0.0.1:8080/api/enterprise/federation/v1/etcd-replicators/my_replicator \
-H "Authorization: Key $SENSU_API_KEY"

The request will return a successful HTTP/1.1 200 OK response and a JSON map that contains the requested :etcd-replicator definition (in this example, my_replicator):

{
  "api_version": "federation/v1",
  "type": "EtcdReplicator",
  "metadata": {
    "name": "my_replicator",
    "created_by": "admin"
  },
  "spec": {
    "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem",
    "cert": "/path/to/ssl/cert.pem",
    "key": "/path/to/ssl/key.pem",
    "insecure": false,
    "url": "http://remote-etcd.example.com:2379",
    "api_version": "core/v2",
    "resource": "Role",
    "replication_interval_seconds": 30
  }
}

API Specification

/etcd-replicators/:etcd-replicator (GET)
description Returns the specified replicator.
example url http://hostname:8080/api/enterprise/federation/v1/etcd-replicators/my_replicator
response type Map
response codes
  • Success: 200 (OK)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)
output 
{
  "api_version": "federation/v1",
  "type": "EtcdReplicator",
  "metadata": {
    "name": "my_replicator",
    "created_by": "admin"
  },
  "spec": {
    "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem",
    "cert": "/path/to/ssl/cert.pem",
    "key": "/path/to/ssl/key.pem",
    "insecure": false,
    "url": "http://remote-etcd.example.com:2379",
    "api_version": "core/v2",
    "resource": "Role",
    "replication_interval_seconds": 30
  }
}

Create or update a replicator

The /etcd-replicators/:etcd-replicator API endpoint provides HTTP PUT access to create or update a specific :etcd-replicator, by replicator name.

Example

The following example demonstrates a request to the /etcd-replicators/:etcd-replicator API endpoint to update the replicator my_replicator:

curl -X PUT \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "api_version": "federation/v1",
  "type": "EtcdReplicator",
  "metadata": {
    "name": "my_replicator"
  },
  "spec": {
    "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem",
    "cert": "/path/to/ssl/cert.pem",
    "key": "/path/to/ssl/key.pem",
    "insecure": false,
    "url": "http://remote-etcd.example.com:2379",
    "api_version": "core/v2",
    "resource": "Role",
    "replication_interval_seconds": 30
  }
}' \
http://127.0.0.1:8080/api/enterprise/federation/v1/etcd-replicators/my-replicator

The request will return a successful HTTP/1.1 201 Created response.

API Specification

/etcd-replicators/:etcd-replicator (PUT)
description Creates or updates the specified replicator. The replicator resource and API version cannot be altered.
example URL http://hostname:8080/api/enterprise/federation/v1/etcd-replicators/my_replicator
payload 
{
  "api_version": "federation/v1",
  "type": "EtcdReplicator",
  "metadata": {
    "name": "my_replicator"
  },
  "spec": {
    "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem",
    "cert": "/path/to/ssl/cert.pem",
    "key": "/path/to/ssl/key.pem",
    "insecure": false,
    "url": "http://remote-etcd.example.com:2379",
    "api_version": "core/v2",
    "resource": "Role",
    "replication_interval_seconds": 30
  }
}
response codes
  • Success: 201 (Created)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

Delete a replicator

The /etcd-replicators/:etcd-replicator API endpoint provides HTTP DELETE access to delete the specified replicator from Sensu.

Example

The following example shows a request to the /etcd-replicators/:etcd-replicator API endpoint to delete the replicator my_replicator, resulting in a successful HTTP/1.1 204 No Content response.

curl -X DELETE \
-H "Authorization: Key $SENSU_API_KEY" \
http://127.0.0.1:8080/api/enterprise/federation/v1/etcd-replicators/my_replicator

API Specification

/etcd-replicators/:etcd-replicator (DELETE)
description Deletes the specified replicator from Sensu.
example url http://hostname:8080/api/enterprise/federation/v1/etcd-replicators/my_replicator
response codes
  • Success: 204 (No Content)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)

Get all clusters

The /clusters API endpoint provides HTTP GET access to a list of clusters.

Example

The following example demonstrates a request to the /clusters API endpoint, resulting in a list of clusters.

curl -X GET \
http://127.0.0.1:8080/api/enterprise/federation/v1/clusters \
-H "Authorization: Key $SENSU_API_KEY"

The request results in a successful HTTP/1.1 200 OK response and a JSON array that contains the cluster definitions:

[
  {
    "type": "Cluster",
    "api_version": "federation/v1",
    "metadata": {
      "name": "us-west-2a",
      "created_by": "admin"
    },
    "spec": {
      "api_urls": [
        "http://10.0.0.1:8080",
        "http://10.0.0.2:8080",
        "http://10.0.0.3:8080"
      ]
    }
  }
]

API Specification

/clusters (GET)
description Returns the list of clusters.
example url http://hostname:8080/api/enterprise/federation/v1/clusters
response type Array
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output 
[
  {
    "type": "Cluster",
    "api_version": "federation/v1",
    "metadata": {
      "name": "us-west-2a",
      "created_by": "admin"
    },
    "spec": {
      "api_urls": [
        "http://10.0.0.1:8080",
        "http://10.0.0.2:8080",
        "http://10.0.0.3:8080"
      ]
    }
  }
]

Get a specific cluster

The /clusters/:cluster API endpoint provides HTTP GET access to data for a specific cluster, by cluster name.

Example

The following example queries the /clusters/:cluster API endpoint for a specific :cluster.

curl -X GET \
http://127.0.0.1:8080/api/enterprise/federation/v1/clusters/us-west-2a \
-H "Authorization: Key $SENSU_API_KEY"

The request will return a successful HTTP/1.1 200 OK response and a JSON map that contains the requested :cluster definition (in this example, us-west-2a):

{
  "type": "Cluster",
  "api_version": "federation/v1",
  "metadata": {
    "name": "us-west-2a",
    "created_by": "admin"
  },
  "spec": {
    "api_urls": [
      "http://10.0.0.1:8080",
      "http://10.0.0.2:8080",
      "http://10.0.0.3:8080"
    ]
  }
}

API Specification

/clusters/:cluster (GET)
description Returns the specified cluster.
example url http://hostname:8080/api/enterprise/federation/v1/clusters/us-west-2a
response type Map
response codes
  • Success: 200 (OK)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)
output 
{
  "type": "Cluster",
  "api_version": "federation/v1",
  "metadata": {
    "name": "us-west-2a",
    "created_by": "admin"
  },
  "spec": {
    "api_urls": [
      "http://10.0.0.1:8080",
      "http://10.0.0.2:8080",
      "http://10.0.0.3:8080"
    ]
  }
}

Create or update a cluster

The /clusters/:cluster API endpoint provides HTTP PUT access to create or update a specific cluster, by cluster name.

NOTE: Only cluster admins have PUT access to clusters.

Example

The following example demonstrates a request to the /clusters/:cluster API endpoint to update the cluster us-west-2a:

curl -X PUT \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "type": "Cluster",
  "api_version": "federation/v1",
  "metadata": {
    "name": "us-west-2a"
  },
  "spec": {
    "api_urls": [
      "http://10.0.0.1:8080",
      "http://10.0.0.2:8080",
      "http://10.0.0.3:8080"
    ]
  }
}' \
http://127.0.0.1:8080/api/enterprise/federation/v1/clusters/us-west-2a

The request will return a successful HTTP/1.1 201 Created response.

API Specification

/clusters/:cluster (PUT)
description Creates or updates the specified cluster.
example URL http://hostname:8080/api/enterprise/federation/v1/clusters/us-west-2a
payload 
{
  "type": "Cluster",
  "api_version": "federation/v1",
  "metadata": {
    "name": "us-west-2a"
  },
  "spec": {
    "api_urls": [
      "http://10.0.0.1:8080",
      "http://10.0.0.2:8080",
      "http://10.0.0.3:8080"
    ]
  }
}
response codes
  • Success: 201 (Created)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

Delete a cluster

The /clusters/:cluster API endpoint provides HTTP DELETE access to delete the specified cluster from Sensu.

NOTE: Only cluster admins have DELETE access to clusters.

Example

The following example shows a request to the /clusters/:cluster API endpoint to delete the cluster us-west-2a, resulting in a successful HTTP/1.1 204 No Content response.

curl -X DELETE \
-H "Authorization: Key $SENSU_API_KEY" \
http://127.0.0.1:8080/api/enterprise/federation/v1/clusters/us-west-2a

API Specification

/clusters/:cluster (DELETE)
description Deletes the specified cluster from Sensu.
example url http://hostname:8080/api/enterprise/federation/v1/clusters/us-west-2a
response codes
  • Success: 204 (No Content)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)