consul/website/source/api/catalog.html.md
Matt Keeler 18b29c45c4
New ACLs (#4791)
This PR is almost a complete rewrite of the ACL system within Consul. It brings the features more in line with other HashiCorp products. Obviously there is quite a bit left to do here but most of it is related docs, testing and finishing the last few commands in the CLI. I will update the PR description and check off the todos as I finish them over the next few days/week.
Description

At a high level this PR is mainly to split ACL tokens from Policies and to split the concepts of Authorization from Identities. A lot of this PR is mostly just to support CRUD operations on ACLTokens and ACLPolicies. These in and of themselves are not particularly interesting. The bigger conceptual changes are in how tokens get resolved, how backwards compatibility is handled and the separation of policy from identity which could lead the way to allowing for alternative identity providers.

On the surface and with a new cluster the ACL system will look very similar to that of Nomads. Both have tokens and policies. Both have local tokens. The ACL management APIs for both are very similar. I even ripped off Nomad's ACL bootstrap resetting procedure. There are a few key differences though.

    Nomad requires token and policy replication where Consul only requires policy replication with token replication being opt-in. In Consul local tokens only work with token replication being enabled though.
    All policies in Nomad are globally applicable. In Consul all policies are stored and replicated globally but can be scoped to a subset of the datacenters. This allows for more granular access management.
    Unlike Nomad, Consul has legacy baggage in the form of the original ACL system. The ramifications of this are:
        A server running the new system must still support other clients using the legacy system.
        A client running the new system must be able to use the legacy RPCs when the servers in its datacenter are running the legacy system.
        The primary ACL DC's servers running in legacy mode needs to be a gate that keeps everything else in the entire multi-DC cluster running in legacy mode.

So not only does this PR implement the new ACL system but has a legacy mode built in for when the cluster isn't ready for new ACLs. Also detecting that new ACLs can be used is automatic and requires no configuration on the part of administrators. This process is detailed more in the "Transitioning from Legacy to New ACL Mode" section below.
2018-10-19 12:04:07 -04:00

19 KiB

layout page_title sidebar_current description
api Catalog - HTTP API api-catalog The /catalog endpoints register and deregister nodes, services, and checks in Consul.

Catalog HTTP API

The /catalog endpoints register and deregister nodes, services, and checks in Consul. The catalog should not be confused with the agent, since some of the API methods look similar.

Register Entity

This endpoint is a low-level mechanism for registering or updating entries in the catalog. It is usually preferable to instead use the agent endpoints for registration as they are simpler and perform anti-entropy.

Method Path Produces
PUT /catalog/register application/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
NO none none node:write,service:write

Parameters

  • ID (string: "") - An optional UUID to assign to the service. If not provided, one is generated. This must be a 36-character UUID.

  • Node (string: <required>) - Specifies the node ID to register.

  • Address (string: <required>) - Specifies the address to register.

  • Datacenter (string: "") - Specifies the datacenter, which defaults to the agent's datacenter if not provided.

  • TaggedAddresses (map<string|string>: nil) - Specifies the tagged addresses.

  • NodeMeta (map<string|string>: nil) - Specifies arbitrary KV metadata pairs for filtering purposes.

  • Service (Service: nil) - Specifies to register a service. If ID is not provided, it will be defaulted to the value of the Service.Service property. Only one service with a given ID may be present per node. The service Tags, Address, Meta, and Port fields are all optional.

  • Check (Check: nil) - Specifies to register a check. The register API manipulates the health check entry in the Catalog, but it does not setup the script, TTL, or HTTP check to monitor the node's health. To truly enable a new health check, the check must either be provided in agent configuration or set via the agent endpoint.

    The CheckID can be omitted and will default to the value of Name. As with Service.ID, the CheckID must be unique on this node. Notes is an opaque field that is meant to hold human-readable text. If a ServiceID is provided that matches the ID of a service on that node, the check is treated as a service level health check, instead of a node level health check. The Status must be one of passing, warning, or critical.

    The Definition field can be provided with details for a TCP or HTTP health check. For more information, see the Health Checks page.

    Multiple checks can be provided by replacing Check with Checks and sending an array of Check objects.

  • SkipNodeUpdate (bool: false) - Specifies whether to skip updating the node part of the registration. Useful in the case where only a health check or service entry on a node needs to be updated.

It is important to note that Check does not have to be provided with Service and vice versa. A catalog entry can have either, neither, or both.

Sample Payload

{
  "Datacenter": "dc1",
  "ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
  "Node": "foobar",
  "Address": "192.168.10.10",
  "TaggedAddresses": {
    "lan": "192.168.10.10",
    "wan": "10.0.10.10"
  },
  "NodeMeta": {
    "somekey": "somevalue"
  },
  "Service": {
    "ID": "redis1",
    "Service": "redis",
    "Tags": [
      "primary",
      "v1"
    ],
    "Address": "127.0.0.1",
    "Meta": {
        "redis_version": "4.0"
    },
    "Port": 8000
  },
  "Check": {
    "Node": "foobar",
    "CheckID": "service:redis1",
    "Name": "Redis health check",
    "Notes": "Script based health check",
    "Status": "passing",
    "ServiceID": "redis1",
    "Definition": {
      "TCP": "localhost:8888",
      "Interval": "5s",
      "Timeout": "1s",
      "DeregisterCriticalServiceAfter": "30s"
    }
  },
  "SkipNodeUpdate": false
}

Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/catalog/register

Deregister Entity

This endpoint is a low-level mechanism for directly removing entries from the Catalog. It is usually preferable to instead use the agent endpoints for deregistration as they are simpler and perform anti-entropy.

Method Path Produces
PUT /catalog/deregister application/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
NO none none node:write,service:write

Parameters

The behavior of the endpoint depends on what keys are provided.

  • Node (string: <required>) - Specifies the ID of the node. If no other values are provided, this node, all its services, and all its checks are removed.

  • Datacenter (string: "") - Specifies the datacenter, which defaults to the agent's datacenter if not provided.

  • CheckID (string: "") - Specifies the ID of the check to remove.

  • ServiceID (string: "") - Specifies the ID of the service to remove. The service and all associated checks will be removed.

Sample Payloads

{
  "Datacenter": "dc1",
  "Node": "foobar"
}
{
  "Datacenter": "dc1",
  "Node": "foobar",
  "CheckID": "service:redis1"
}
{
  "Datacenter": "dc1",
  "Node": "foobar",
  "ServiceID": "redis1"
}

Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/catalog/deregister

List Datacenters

This endpoint returns the list of all known datacenters. The datacenters will be sorted in ascending order based on the estimated median round trip time from the server to the servers in that datacenter.

This endpoint does not require a cluster leader and will succeed even during an availability outage. Therefore, it can be used as a simple check to see if any Consul servers are routable.

Method Path Produces
GET /catalog/datacenters application/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
NO none none none

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/catalog/datacenters

Sample Response

["dc1", "dc2"]

List Nodes

This endpoint and returns the nodes registered in a given datacenter.

Method Path Produces
GET /catalog/nodes application/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
YES all none node:read

Parameters

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. This is specified as part of the URL as a query parameter.

  • near (string: "") - Specifies a node name to sort the node list in ascending order based on the estimated round trip time from that node. Passing ?near=_agent will use the agent's node for the sort. This is specified as part of the URL as a query parameter.

  • node-meta (string: "") - Specifies a desired node metadata key/value pair of the form key:value. This parameter can be specified multiple times, and will filter the results to nodes with the specified key/value pairs. This is specified as part of the URL as a query parameter.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/catalog/nodes

Sample Response

[
  {
    "ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
    "Node": "baz",
    "Address": "10.1.10.11",
    "Datacenter": "dc1",
    "TaggedAddresses": {
      "lan": "10.1.10.11",
      "wan": "10.1.10.11"
    },
    "Meta": {
      "instance_type": "t2.medium"
    }
  },
  {
    "ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
    "Node": "foobar",
    "Address": "10.1.10.12",
    "Datacenter": "dc2",
    "TaggedAddresses": {
      "lan": "10.1.10.11",
      "wan": "10.1.10.12"
    },
    "Meta": {
      "instance_type": "t2.large"
    }
  }
]

List Services

This endpoint returns the services registered in a given datacenter.

Method Path Produces
GET /catalog/services application/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
YES all none service:read

Parameters

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. This is specified as part of the URL as a query parameter.

  • node-meta (string: "") - Specifies a desired node metadata key/value pair of the form key:value. This parameter can be specified multiple times, and will filter the results to nodes with the specified key/value pairs. This is specified as part of the URL as a query parameter.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/catalog/services

Sample Response

{
  "consul": [],
  "redis": [],
  "postgresql": [
    "primary",
    "secondary"
  ]
}

The keys are the service names, and the array values provide all known tags for a given service.

List Nodes for Service

This endpoint returns the nodes providing a service in a given datacenter.

Method Path Produces
GET /catalog/service/:service application/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
YES all background refresh node:read,service:read

Parameters

  • service (string: <required>) - Specifies the name of the service for which to list nodes. This is specified as part of the URL.

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. This is specified as part of the URL as a query parameter.

  • tag (string: "") - Specifies the tag to filter on. This is specified as part of the URL as a query parameter. Can be used multiple times for additional filtering, returning only the results that include all of the tag values provided.

  • near (string: "") - Specifies a node name to sort the node list in ascending order based on the estimated round trip time from that node. Passing ?near=_agent will use the agent's node for the sort. This is specified as part of the URL as a query parameter.

  • node-meta (string: "") - Specifies a desired node metadata key/value pair of the form key:value. This parameter can be specified multiple times, and will filter the results to nodes with the specified key/value pairs. This is specified as part of the URL as a query parameter.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/catalog/service/my-service

Sample Response

[
  {
    "ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
    "Node": "foobar",
    "Address": "192.168.10.10",
    "Datacenter": "dc1",
    "TaggedAddresses": {
      "lan": "192.168.10.10",
      "wan": "10.0.10.10"
    },
    "NodeMeta": {
      "somekey": "somevalue"
    },
    "CreateIndex": 51,
    "ModifyIndex": 51,
    "ServiceAddress": "172.17.0.3",
    "ServiceEnableTagOverride": false,
    "ServiceID": "32a2a47f7992:nodea:5000",
    "ServiceName": "foobar",
    "ServicePort": 5000,
    "ServiceMeta": {
        "foobar_meta_value": "baz"
    },
    "ServiceTags": [
      "tacos"
    ],
    "ServiceProxyDestination": "",
    "ServiceProxy": {
        "DestinationServiceName": "",
        "DestinationServiceID": "",
        "LocalServiceAddress": "",
        "LocalServicePort": 0,
        "Config": null,
        "Upstreams": null
    },
    "ServiceConnect": {
        "Native": false,
        "Proxy": null
    },
  }
]
  • Address is the IP address of the Consul node on which the service is registered.

  • Datacenter is the data center of the Consul node on which the service is registered.

  • TaggedAddresses is the list of explicit LAN and WAN IP addresses for the agent

  • NodeMeta is a list of user-defined metadata key/value pairs for the node

  • CreateIndex is an internal index value representing when the service was created

  • ModifyIndex is the last index that modified the service

  • Node is the name of the Consul node on which the service is registered

  • ServiceAddress is the IP address of the service host — if empty, node address should be used

  • ServiceEnableTagOverride indicates whether service tags can be overridden on this service

  • ServiceID is a unique service instance identifier

  • ServiceName is the name of the service

  • ServiceMeta is a list of user-defined metadata key/value pairs for the service

  • ServicePort is the port number of the service

  • ServiceTags is a list of tags for the service

  • ServiceKind is the kind of service, usually "". See the Agent registration API for more information.

  • ServiceProxyDestination Deprecated this field duplicates ServiceProxy.DestinationServiceName for backwards compatibility. It will be removed in a future major version release.

  • ServiceProxy is the proxy config as specified in Connect Proxies.

  • ServiceConnect are the Connect settings. The value of this struct is equivalent to the Connect field for service registration.

List Nodes for Connect-capable Service

This endpoint returns the nodes providing a Connect-capable service in a given datacenter. This will include both proxies and native integrations. A service may register both Connect-capable and incapable services at the same time, so this endpoint may be used to filter only the Connect-capable endpoints.

Method Path Produces
GET /catalog/connect/:service application/json

Parameters and response format are the same as /catalog/service/:service.

List Services for Node

This endpoint returns the node's registered services.

Method Path Produces
GET /catalog/node/:node application/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries Consistency Modes Agent Caching ACL Required
YES all none node:read,service:read

Parameters

  • node (string: <required>) - Specifies the name of the node for which to list services. This is specified as part of the URL.

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. This is specified as part of the URL as a query parameter.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/catalog/node/my-node

Sample Response

{
  "Node": {
    "ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
    "Node": "foobar",
    "Address": "10.1.10.12",
    "Datacenter": "dc1",
    "TaggedAddresses": {
      "lan": "10.1.10.12",
      "wan": "10.1.10.12"
    },
    "Meta": {
      "instance_type": "t2.medium"
    }
  },
  "Services": {
    "consul": {
      "ID": "consul",
      "Service": "consul",
      "Tags": null,
      "Meta": {},
      "Port": 8300
    },
    "redis": {
      "ID": "redis",
      "Service": "redis",
      "Tags": [
        "v1"
      ],
      "Meta": {
        "redis_version": "4.0"
      },
      "Port": 8000
    }
  }
}