Federation API

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

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 request to the /etcd-replicators API endpoint, resulting in a list of replicators.

curl -X GET \
http://127.0.0.1:8080/api/enterprise/federation/v1/etcd-replicators \
-H "Authorization: Bearer $SENSU_ACCESS_TOKEN"
[
  {
    "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
    }
  }
]

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"
    },
    "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: Bearer $SENSU_ACCESS_TOKEN" \
-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

HTTP/1.1 200 OK

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

In the following example, querying the /etcd-replicators/:etcd-replicator API endpoint returns a JSON map that contains the requested :etcd-replicator.

curl -X GET \
http://127.0.0.1:8080/api/enterprise/federation/v1/etcd-replicators/my_replicator \
-H "Authorization: Bearer $SENSU_ACCESS_TOKEN"
{
  "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
  }
}

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"
  },
  "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: Bearer $SENSU_ACCESS_TOKEN" \
-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

HTTP/1.1 200 OK

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 204 No Content response.

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

HTTP/1.1 204 No Content

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: Bearer $SENSU_ACCESS_TOKEN"

HTTP/1.1 200 OK

[
    {
        "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"
            ]
        }
    }
]

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

In the following example, querying the /clusters/:cluster API endpoint returns a JSON map that contains the requested :etcd-replicator.

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

HTTP/1.1 200 OK

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

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"
    },
    "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: Bearer $SENSU_ACCESS_TOKEN" \
-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

HTTP/1.1 200 OK

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 204 No Content response.

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

HTTP/1.1 204 No Content

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)