»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:write 1 |
1 The ACL required depends on the config entry kind being updated:
Config Entry Kind | Required ACL |
---|
ingress-gateway | operator:write |
proxy-defaults | operator:write |
service-defaults | service:write |
service-intentions | intentions:write |
service-resolver | service:write |
service-router | service:write |
service-splitter | service:write |
terminating-gateway | 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
- Specifies the namespace the config
entry will apply to. This value may be provided by either the ns
URL query
parameter or in the X-Consul-Namespace
header. If not provided,
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:read 1 |
1 The ACL required depends on the config entry kind being read:
Config Entry Kind | Required ACL |
---|
ingress-gateway | service:read |
proxy-defaults | <none> |
service-defaults | service:read |
service-intentions | intentions:read |
service-resolver | service:read |
service-router | service:read |
service-splitter | service:read |
terminating-gateway | 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.
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
- Specifies the namespace to query.
This value may be provided by either the ns
URL query parameter or in the
X-Consul-Namespace
header. If not provided, 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:read 1 |
1 The ACL required depends on the config entry kind being read:
Config Entry Kind | Required ACL |
---|
ingress-gateway | service:read |
proxy-defaults | <none> |
service-defaults | service:read |
service-intentions | intentions:read |
service-resolver | service:read |
service-router | service:read |
service-splitter | service:read |
terminating-gateway | 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.
kind
(string: <required>)
- Specifies the kind of the entry to list. This
is specified as part of the URL.
ns
(string: "")
Enterprise
- Specifies the namespace to query.
This value may be provided by either the ns
URL query parameter or in the
X-Consul-Namespace
header. If not provided, 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:write 1 |
1 The ACL required depends on the config entry kind being deleted:
Config Entry Kind | Required ACL |
---|
ingress-gateway | operator:write |
proxy-defaults | operator:write |
service-defaults | service:write |
service-intentions | intentions:write |
service-resolver | service:write |
service-router | service:write |
service-splitter | service:write |
terminating-gateway | 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
- Specifies the namespace to delete from.
This value may be provided by either the ns
URL query parameter or in the
X-Consul-Namespace
header. If not provided, 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