Blog HCP Consul on Azure goes GA, plus more Consul news from HashiConf EU Read more
  • Overview
    • Consul on Kubernetes
    • Control access with Consul API Gateway
    • Discover Services with Consul
    • Enforce Zero Trust Networking with Consul
    • Load Balancing with Consul
    • Manage Traffic with Consul
    • Multi-Platform Service Mesh with Consul
    • Network Infrastructure Automation with Consul
    • Observability with Consul
  • Enterprise
  • Tutorials
  • Docs
  • API
  • CLI
  • Community
GitHub
Download
Try HCP Consul
    • v1.12.x (latest)
    • v1.11.x
    • v1.10.x
    • v1.9.x
    • v1.8.x
  • API Introduction
    • Consistency Modes
    • Blocking Queries
    • Filtering
    • Agent Caching

    • Overview
    • Tokens
    • Legacy Tokens
    • Policies
    • Roles
    • Auth Methods
    • Binding Rules
  • Admin Partitions
    • Overview
    • Checks
    • Services
    • Connect
  • Catalog
  • Cluster Peering
  • Config
    • Overview
    • Certificate Authority (CA)
    • Intentions
  • Coordinates
  • Discovery Chain
  • Events
  • Health
  • KV Store
    • Overview
    • Area
    • Autopilot
    • Keyring
    • License
    • Raft
    • Segment
  • Namespaces
  • Prepared Queries
  • Sessions
  • Snapshots
  • Status
  • Transactions

  • Libraries & SDKs
Type '/' to Search

»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.

MethodPathProduces
PUT/configapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenoneservice:write
operator:write1

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

Config Entry KindRequired ACL
ingress-gatewayoperator:write
proxy-defaultsoperator:write
service-defaultsservice:write
service-intentionsintentions:write
service-resolverservice:write
service-routerservice:write
service-splitterservice:write
terminating-gatewayoperator:write

The corresponding CLI command is consul config write.

»Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This parameter defaults to the datacenter of the agent being queried.

  • 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 of the config entry you apply. You can also specify the namespace through other methods.

»Sample Payload

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

»Sample Request

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

»Get Configuration

This endpoint returns a specific config entry.

MethodPathProduces
GET/config/:kind/:nameapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnoneservice:read1
1 The ACL required depends on the config entry kind being read:
Config Entry KindRequired ACL
ingress-gatewayservice:read
proxy-defaults<none>
service-defaultsservice:read
service-intentionsintentions:read
service-resolverservice:read
service-routerservice:read
service-splitterservice:read
terminating-gatewayservice:read

The corresponding CLI command is consul config read.

»Path Parameters

  • kind (string: <required>) - Specifies the kind of the entry to read.

  • name (string: <required>) - Specifies the name of the entry to read. The name of the proxy-defaults config entry must be global, and the name of the mesh config entry must be mesh.

»Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This parameter defaults to the datacenter of the agent being queried.

  • ns (string: "")

    Enterprise
    - Specifies the namespace of the config entry you lookup You can also specify the namespace through other methods.

»Sample Request

$ curl \
    --request GET \
    http://127.0.0.1:8500/v1/config/service-defaults/web
$ 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
}
{
  "Kind": "service-defaults",
  "Name": "web",
  "Protocol": "http",
  "CreateIndex": 15,
  "ModifyIndex": 35
}

»List Configurations

This endpoint returns all config entries of the given kind.

The HTTP response includes the X-Consul-Results-Filtered-By-ACLs: true header if the response array excludes results due to ACL policy configuration. Refer to the HTTP API documentation for more information.

MethodPathProduces
GET/config/:kindapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnoneservice:read1
1 The ACL required depends on the config entry kind being read:
Config Entry KindRequired ACL
ingress-gatewayservice:read
proxy-defaults<none>
service-defaultsservice:read
service-intentionsintentions:read
service-resolverservice:read
service-routerservice:read
service-splitterservice:read
terminating-gatewayservice:read

The corresponding CLI command is consul config list.

»Path Parameters

  • kind (string: <required>) - Specifies the kind of the entry to list.

»Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This parameter defaults to the datacenter of the agent being queried.

  • ns (string: "")

    Enterprise
    - Specifies the namespace of the config entries you lookup. You can also specify the namespace through other methods.

»Sample Request

$ curl \
    --request GET \
    http://127.0.0.1:8500/v1/config/service-defaults
$ 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
  }
]
[
  {
    "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.

MethodPathProduces
DELETE/config/:kind/:nameapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenoneservice:write
operator:write1
1 The ACL required depends on the config entry kind being deleted:
Config Entry KindRequired ACL
ingress-gatewayoperator:write
proxy-defaultsoperator:write
service-defaultsservice:write
service-intentionsintentions:write
service-resolverservice:write
service-routerservice:write
service-splitterservice:write
terminating-gatewayoperator:write

The corresponding CLI command is consul config delete.

»Path Parameters

  • kind (string: <required>) - Specifies the kind of the entry to delete.

  • name (string: <required>) - Specifies the name of the entry to delete. The name of the proxy-defaults config entry must be global, and the name of the mesh config entry must be mesh.

»Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This parameter defaults to the datacenter of the agent being queried.

  • cas (int: 0) - Specifies to use a Check-And-Set operation. Unlike PUT, the index must be greater than 0 for Consul to take any action: a 0 index will not delete the config entry. If the index is non-zero, the config entry is only deleted if the index matches the ModifyIndex of that config entry.

  • ns (string: "")

    Enterprise
    - Specifies the namespace of the config entry you delete. You can also specify the namespace through other methods.

»Sample Request

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

»Methods to Specify Namespace
Enterprise

Config endpoints support several methods for specifying the namespace of configuration entry resources with the following order of precedence:

  1. ns query parameter
  2. X-Consul-Namespace request header
  3. Namespace is inherited from the namespace of the request's ACL token (if any)
  4. The default namespace
github logoEdit this page
IntroGuidesDocsCommunityPrivacySecurityBrandConsent Manager