Federation API

COMMERCIAL FEATURE: Access federation in the packaged Sensu Go distribution. For more information, see the getting started guide.

The /etcd-replicators endpoint

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

/etcd-replicators (GET)

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

EXAMPLE

The following example demonstrates a request to the /etcd-replicators endpoint, resulting in a list of replicators.

NOTE: If you did not specify a namespace when you created a replicator, the response will not include a namespace key-value pair.

curl http://127.0.0.1:8080/api/enterprise/federation/v1/etcd-replicators -H "Authorization: Bearer $SENSU_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 a 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
    }
  }
]

/etcd-replicators (POST)

NOTE: If you do not specify a namespace when you create a replicator, all namespaces for the given resource are replicated.

/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)

The /etcd-replicators/:etcd-replicator endpoint

/etcd-replicators/:etcd-replicator (GET)

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

EXAMPLE

In the following example, querying the /etcd-replicators/:etcd-replicator endpoint returns a JSON Map containing the requested :etcd-replicator.

NOTE: If you did not specify a namespace when you created the replicator, the response will not include a namespace key-value pair.

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

/etcd-replicators/:etcd-replicator (PUT)

EXAMPLE

The following example demonstrates a request to update the replicator my_replicator.

curl -X PUT \
-H "Authorization: Bearer $SENSU_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://hostname: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/{etcd-replicator_name}
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)

/etcd-replicators/:etcd-replicator (DELETE)

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

EXAMPLE

The following example shows a request to delete the replicator my_replicator, resulting in a successful HTTP 204 No Content response.

curl -X DELETE \
-H "Authorization: Bearer $SENSU_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/{etcd-replicator_name}
response codes
  • Success: 204 (No Content)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)

The /clusters endpoint

/clusters (GET)

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

EXAMPLE

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

curl -H "Authorization: Bearer $SENSU_TOKEN" \
http://127.0.0.1:8080/api/enterprise/federation/v1/clusters

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

The /clusters/:cluster endpoint

/clusters/:cluster (GET)

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

EXAMPLE

In the following example, querying the /clusters/:cluster endpoint returns a JSON Map containing the requested :etcd-replicator.

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

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

/clusters/:cluster (PUT)

NOTE: Only cluster admins have PUT access to clusters.

EXAMPLE

The following example demonstrates a request to update the cluster us-west-2a.

curl -X PUT \
-H "Authorization: Bearer $SENSU_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)

/clusters/:cluster (DELETE)

The /clusters/:cluster 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 delete the cluster us-west-2a, resulting in a successful HTTP 204 No Content response.

curl -X DELETE \
-H "Authorization: Bearer $SENSU_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)