luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity
open-consul/website/source/api/config.html.md

9.4 KiB
Raw Blame History

layout page_title sidebar_current description
api Config - HTTP API api-config The /config endpoints are for managing centralized configuration in Consul.

Config HTTP Endpoint

The /config endpoints create, update, delete and query central configuration entries registered with Consul. See the agent configuration for more information on how to enable this functionality for centrally configuring services and configuration entries docs for a description of the configuration entries content.

Apply Configuration

This endpoint creates or updates the given config entry.

Method Path Produces
PUT /config 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 service:write
operator:write1

1 The ACL required depends on the config entry kind being updated:

Config Entry Kind Required ACL
service-defaults service:write
proxy-defaults operator:write

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.

  • cas (int: 0) - Specifies to use a Check-And-Set operation. If the index is 0, Consul will only store the entry if it does not already exist. If the index is non-zero, the entry is only set if the current index matches the ModifyIndex of that entry.

  • ns (string: "") - (Enterprise Only) Specifies the namespace in which the service and checks will be registered. This value may be provided by either the ns URL query parameter or in the X-Consul-Namespace header. Additionally, the namespace may be provided within the Service or Check fields but if present in multiple places, they must all be the same. If not provided at all, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.

Sample Payload

{
    "Kind": "service-defaults",
    "Name": "web",
    "Protocol": "http"
}

Sample Request

$ curl \
    --request PUT \
    --data @payload \
    http://127.0.0.1:8500/v1/config

Get Configuration

This endpoint returns a specific config entry.

Method Path Produces
GET /config/:kind/:name 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:read1

1 The ACL required depends on the config entry kind being read:

Config Entry Kind Required ACL
service-defaults service:read
proxy-defaults <none>

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.

  • kind (string: <required>) - Specifies the kind of the entry to read. This is specified as part of the URL.

  • name (string: <required>) - Specifies the name of the entry to read. This is specified as part of the URL.

  • ns (string: "") - (Enterprise Only) Specifies the namespace in which the service and checks will be registered. This value may be provided by either the ns URL query parameter or in the X-Consul-Namespace header. Additionally, the namespace may be provided within the Service or Check fields but if present in multiple places, they must all be the same. If not provided at all, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.

Sample Request

$ curl \
    --request GET \
    http://127.0.0.1:8500/v1/config/service-defaults/web

Sample Response

{
    "Kind": "service-defaults",
    "Name": "web",
    "Protocol": "http",
    "CreateIndex": 15,
    "ModifyIndex": 35
}

List Configurations

This endpoint returns all config entries of the given kind.

Method Path Produces
GET /config/:kind 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:read1

1 The ACL required depends on the config entry kind being read:

Config Entry Kind Required ACL
service-defaults service:read
proxy-defaults <none>

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.

  • kind (string: <required>) - Specifies the kind of the entry to list. This is specified as part of the URL.

  • ns (string: "") - (Enterprise Only) Specifies the namespace in which the service and checks will be registered. This value may be provided by either the ns URL query parameter or in the X-Consul-Namespace header. Additionally, the namespace may be provided within the Service or Check fields but if present in multiple places, they must all be the same. If not provided at all, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.

Sample Request

$ curl \
    --request GET \
    http://127.0.0.1:8500/v1/config/service-defaults

Sample Response

[
    {
        "Kind": "service-defaults",
        "Name": "db",
        "Protocol": "tcp",
        "CreateIndex": 16,
        "ModifyIndex": 16
    },
    {
        "Kind": "service-defaults",
        "Name": "web",
        "Protocol": "http",
        "CreateIndex": 13,
        "ModifyIndex": 13
    }
]

Delete Configuration

This endpoint deletes the given config entry.

Method Path Produces
DELETE /config/:kind/:name 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 service:write
operator:write1

1 The ACL required depends on the config entry kind being deleted:

Config Entry Kind Required ACL
service-defaults service:write
proxy-defaults operator:write

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.

  • kind (string: <required>) - Specifies the kind of the entry to delete. This is specified as part of the URL.

  • name (string: <required>) - Specifies the name of the entry to delete. This is specified as part of the URL.

  • ns (string: "") - (Enterprise Only) Specifies the namespace in which the service and checks will be registered. This value may be provided by either the ns URL query parameter or in the X-Consul-Namespace header. Additionally, the namespace may be provided within the Service or Check fields but if present in multiple places, they must all be the same. If not provided at all, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.

Sample Request

$ curl \
    --request DELETE \
    http://127.0.0.1:8500/v1/config/service-defaults/web