luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity
open-consul/website/content/docs/discovery/services.mdx

707 lines
40 KiB
Plaintext
Raw Normal View History

website: document checks and services
2014-02-19 02:05:18 +00:00
---
intro and api navigation converted
2020-04-07 18:55:19 +00:00
layout: docs
docs: update structure (#8506) - moved and renamed files/folders based on new structure - updated docs navigation based on new structure - moved CLI to top nav (created commands.jsx and commands-navigation.js) - updated and added redirects - updating to be consistent with standalone categories - changing "overview" link in top nav to lead to where intro was moved (docs/intro) - adding redirects for intro content - deleting old intro folders - format all data/navigation files - deleting old commands folder - reverting changes to glossary page - adjust intro navigation for removal of 'vs' paths - add helm page redirect - fix more redirects - add a missing redirect - fix broken anchor links and formatting mistakes - deleted duplicate section, added redirect, changed link - removed duplicate glossary page
2020-09-01 15:14:13 +00:00
page_title: Register Services - Service Definitions
intro and api navigation converted
2020-04-07 18:55:19 +00:00
description: >-
One of the main goals of service discovery is to provide a catalog of
available services. To that end, the agent provides a simple service
definition format to declare the availability of a service and to potentially
associate it with a health check. A health check is considered to be
application level if it is associated with a service. A service is defined in
a configuration file or added at runtime over the HTTP interface.
website: document checks and services
2014-02-19 02:05:18 +00:00
---
# Services
One of the main goals of service discovery is to provide a catalog of available
services. To that end, the agent provides a simple service definition format
Grammatical cleanup in services.html.
2015-01-29 00:43:52 +00:00
to declare the availability of a service and to potentially associate it with
fixed typos, finished applying tables, minor editing
2021-08-24 16:57:48 +00:00
a health check. A health check associated with a service is considered to be an
fixed more typos, applied additional tables, additional edits
2021-08-24 18:15:33 +00:00
application-level check. Define services in a configuration file or add it at
runtime using the HTTP interface.
website: document checks and services
2014-02-19 02:05:18 +00:00
fixed typos, finished applying tables, minor editing
2021-08-24 16:57:48 +00:00
Complete the [Getting Started tutorials](https://learn.hashicorp.com/tutorials/consul/get-started-service-discovery?utm_source=consul.io&utm_medium=docs) to get hands-on experience registering a simple service with a health check on your local machine.
[docs] Adding Links to Learn (#6611) * adding links to Learn * fixing a couple typos * adding utm paramaters * Update website/source/docs/connect/registration/sidecar-service.md * Update website/source/docs/connect/registration/sidecar-service.md * Update website/source/docs/acl/acl-system.html.md * Update website/source/docs/acl/acl-system.html.md * Update website/source/docs/agent/encryption.html.md Co-Authored-By: Judith Malnick <judith.patudith@gmail.com> * Update website/source/docs/connect/proxies/built-in.md Co-Authored-By: Judith Malnick <judith.patudith@gmail.com> * Update website/source/docs/connect/registration/sidecar-service.md Co-Authored-By: Judith Malnick <judith.patudith@gmail.com> * Update website/source/docs/install/index.html.md Co-Authored-By: Judith Malnick <judith.patudith@gmail.com> * Update website/source/docs/agent/kv.html.md * Update website/source/docs/connect/security.html.md * Update website/source/docs/connect/security.html.md * Update website/source/docs/internals/architecture.html.md
2019-10-14 15:40:35 +00:00
website: document checks and services
2014-02-19 02:05:18 +00:00
## Service Definition
fixed typos, finished applying tables, minor editing
2021-08-24 16:57:48 +00:00
Configure a service by providing the service definition to the agent. You can
either specify the configuration file using the `-config-file` option, or specify
the directory containing the service definition file with the `-config-dir` option.
fixed more typos, applied additional tables, additional edits
2021-08-24 18:15:33 +00:00
Consul can load service definitions saved as `.json` or `.hcl` files.
applying @blake 's feedback
2021-08-30 21:49:32 +00:00
Send a `SIGHUP` to the running agent or use [`consul reload`](/commands/reload) to check for new service definitions or to
fixed typos, finished applying tables, minor editing
2021-08-24 16:57:48 +00:00
update existing services. Alternatively, the service can be [registered dynamically](/api-docs/agent/service#register-service)
docs(discovery/service): Clarify multiple service definitions Be more explicit that the definition of multiple services only works in config files, not using the HTTP API. Ref: https://discuss.hashicorp.com/t/register-multiple-services-via-put-request/
2021-04-29 17:39:11 +00:00
using the [HTTP API](/api).
website: document proxy security settings
2018-06-12 15:58:31 +00:00
Added HCL examples to service discovery page (#11989) Improved HCL examples in the service discovery docs page
2022-01-10 19:12:42 +00:00
A service definition contains a set of parameters that specify various aspects of the service, including how it is discovered by other services in the network.
All possible parameters are included in the following example, but only the top-level `service` parameter and its `name` parameter child are required by default.
<CodeTabs heading="Service Definition">
```hcl
service {
name = "redis"
id = "redis"
port = 80
tags = ["primary"]
meta = {
custom_meta_key = "custom_meta_value"
}
tagged_addresses = {
lan = {
address = "192.168.0.55"
port = 8000
}
wan = {
address = "198.18.0.23"
port = 80
}
}
port = 8000
socket_path = "/tmp/redis.sock"
enable_tag_override = false
checks = [
{
args = ["/usr/local/bin/check_redis.py"]
interval = "10s"
}
]
kind = "connect-proxy"
proxy_destination = "redis"
proxy = {
destination_service_name = "redis"
destination_service_id = "redis1"
local_service_address = "127.0.0.1"
local_service_port = 9090
local_service_socket_path = "/tmp/redis.sock"
mode = "transparent"
transparent_proxy {
outbound_listener_port = 22500
}
mesh_gateway = {
mode = "local"
}
expose = {
checks = true
paths = [
{
path = "/healthz"
local_path_port = 8080
listener_port = 21500
protocol = "http2"
}
]
}
}
connect = {
native = false
}
weights = {
passing = 5
warning = 1
}
token = "233b604b-b92e-48c8-a253-5f11514e4b50"
namespace = "foo"
}
```
website: document checks and services
2014-02-19 02:05:18 +00:00
docs: Update code blocks across website * Use CodeTabs for examples in multiple formats. * Ensure correct language on code fences. * Use CodeBlockConfig for examples with filenames, or which need highlighted content.
2021-07-31 01:37:33 +00:00
```json
Use new Markdown syntaxes and add SEO descriptions
2014-10-19 23:40:10 +00:00
{
"service": {
website: broken partial rendering and missing id (#4862) * Fix partial rendering in service command (CLI) help * Fix sample JSON to be a valid json for service registration * Add missing id field to make the complete document complete.
2018-10-29 08:41:25 +00:00
"id": "redis",
Use new Markdown syntaxes and add SEO descriptions
2014-10-19 23:40:10 +00:00
"name": "redis",
Documentation pass I was reviewing some docs and found a few issues. 1. Fixed some spelling mistakes. 2. Re-formatted some paragraphs. 3. Changed some potentially loaded language. 4. Fixed some grammar issues. 5. Tried to consistently use syntax-highlighting. 6. Fixed post-period spacing. 7. Fixed some formatting issues and inconsistency. 8. All "notes" are either proper notes or re-written.
2016-11-25 16:00:02 +00:00
"tags": ["primary"],
Makes addresses blank in service definition.
2016-11-22 16:29:29 +00:00
"address": "",
Added documentation for meta
2018-04-24 19:56:35 +00:00
"meta": {
"meta": "for my service"
Fix JSON in service configuration
2018-06-27 07:06:27 +00:00
},
Add tagged addresses for services (#5965) This allows addresses to be tagged at the service level similar to what we allow for nodes already. The address translation that can be enabled with the `translate_wan_addrs` config was updated to take these new addresses into account as well.
2019-06-17 14:51:50 +00:00
"tagged_addresses": {
"lan": {
"address": "192.168.0.55",
"port": 8000,
},
"wan": {
"address": "198.18.0.23",
"port": 80
}
},
Use new Markdown syntaxes and add SEO descriptions
2014-10-19 23:40:10 +00:00
"port": 8000,
[Fix] Add missing quote (#10484)
2021-06-24 20:59:39 +00:00
"socket_path": "/tmp/redis.sock",
config: add generic method to translate between CamelCase and snake_case (#3557) * doc: document discrepancy between id and CheckID * doc: document enable_tag_override change * config: add TranslateKeys helper TranslateKeys makes it easier to map between different representations of internal structures. It allows to recursively map alias keys to canonical keys in structured maps. * config: use TranslateKeys for config file This also adds support for 'enabletagoverride' and removes the need for a separate CheckID alias field. * config: remove dead code * agent: use TranslateKeys for FixupCheckType * agent: translate enable_tag_override during service registration * doc: add '.hcl' as valid extension * config: map ScriptArgs to args * config: add comment for TranslateKeys
2017-10-10 23:40:59 +00:00
"enable_tag_override": false,
agent: support multiple checks per service
2015-01-14 01:52:17 +00:00
"checks": [
{
Remove the script field from checks in favor of args
2018-05-08 22:31:53 +00:00
"args": ["/usr/local/bin/check_redis.py"],
agent: support multiple checks per service
2015-01-14 01:52:17 +00:00
"interval": "10s"
}
website: document proxy security settings
2018-06-12 15:58:31 +00:00
],
Allow config-file based Service Definitions for unmanaged proxies and Connect-natice apps. (#4443)
2018-07-25 18:55:41 +00:00
"kind": "connect-proxy",
[WIP] Initial draft of Sidecar Service and Managed Proxy deprecation docs (#4752) * Initial draft of Sidecar Service and Managed Proxy deprecation docs * Service definition deprecation notices and sidecar service * gRPC and sidecar service config options; Deprecate managed proxy options * Envoy Docs: Basic envoy command; envoy getting started/intro * Remove change that snuck in * Envoy custom config example * Add agent/service API docs; deprecate proxy config endpoint * Misc grep cleanup for managed proxies; capitalize Envoy * Updates to getting started guide * Add missing link * Refactor Envoy guide into a separate guide and add bootstrap reference notes. * Add limitations to Envoy docs; Highlight no fixes for known managed proxy issues on deprecation page; clarify snake cae stuff; Sidecar Service lifecycle
2018-10-11 09:44:42 +00:00
"proxy_destination": "redis", // Deprecated
Add Proxy Upstreams to Service Definition (#4639) * Refactor Service Definition ProxyDestination. This includes: - Refactoring all internal structs used - Updated tests for both deprecated and new input for: - Agent Services endpoint response - Agent Service endpoint response - Agent Register endpoint - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Register - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Services endpoint response - Catalog Node endpoint response - Catalog Service endpoint response - Updated API tests for all of the above too (both deprecated and new forms of register) TODO: - config package changes for on-disk service definitions - proxy config endpoint - built-in proxy support for new fields * Agent proxy config endpoint updated with upstreams * Config file changes for upstreams. * Add upstream opaque config and update all tests to ensure it works everywhere. * Built in proxy working with new Upstreams config * Command fixes and deprecations * Fix key translation, upstream type defaults and a spate of other subtele bugs found with ned to end test scripts... TODO: tests still failing on one case that needs a fix. I think it's key translation for upstreams nested in Managed proxy struct. * Fix translated keys in API registration. ≈ * Fixes from docs - omit some empty undocumented fields in API - Bring back ServiceProxyDestination in Catalog responses to not break backwards compat - this was removed assuming it was only used internally. * Documentation updates for Upstreams in service definition * Fixes for tests broken by many refactors. * Enable travis on f-connect branch in this branch too. * Add consistent Deprecation comments to ProxyDestination uses * Update version number on deprecation notices, and correct upstream datacenter field with explanation in docs
2018-09-12 16:07:47 +00:00
"proxy": {
"destination_service_name": "redis",
"destination_service_id": "redis1",
Update services.html.md
2019-01-24 12:41:43 +00:00
"local_service_address": "127.0.0.1",
Add Proxy Upstreams to Service Definition (#4639) * Refactor Service Definition ProxyDestination. This includes: - Refactoring all internal structs used - Updated tests for both deprecated and new input for: - Agent Services endpoint response - Agent Service endpoint response - Agent Register endpoint - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Register - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Services endpoint response - Catalog Node endpoint response - Catalog Service endpoint response - Updated API tests for all of the above too (both deprecated and new forms of register) TODO: - config package changes for on-disk service definitions - proxy config endpoint - built-in proxy support for new fields * Agent proxy config endpoint updated with upstreams * Config file changes for upstreams. * Add upstream opaque config and update all tests to ensure it works everywhere. * Built in proxy working with new Upstreams config * Command fixes and deprecations * Fix key translation, upstream type defaults and a spate of other subtele bugs found with ned to end test scripts... TODO: tests still failing on one case that needs a fix. I think it's key translation for upstreams nested in Managed proxy struct. * Fix translated keys in API registration. ≈ * Fixes from docs - omit some empty undocumented fields in API - Bring back ServiceProxyDestination in Catalog responses to not break backwards compat - this was removed assuming it was only used internally. * Documentation updates for Upstreams in service definition * Fixes for tests broken by many refactors. * Enable travis on f-connect branch in this branch too. * Add consistent Deprecation comments to ProxyDestination uses * Update version number on deprecation notices, and correct upstream datacenter field with explanation in docs
2018-09-12 16:07:47 +00:00
"local_service_port": 9090,
Docs for Unix Domain Sockets (#10252) * Docs for Unix Domain Sockets There are a number of cases where a user might wish to either 1) expose a service through a Unix Domain Socket in the filesystem ('downstream') or 2) connect to an upstream service by a local unix domain socket (upstream). As of Consul (1.10-beta2) we've added new syntax and support to configure the Envoy proxy to support this To connect to a service via local Unix Domain Socket instead of a port, add local_bind_socket_path and optionally local_bind_socket_mode to the upstream config for a service: upstreams = [ { destination_name = "service-1" local_bind_socket_path = "/tmp/socket_service_1" local_bind_socket_mode = "0700" ... } ... ] This will cause Envoy to create a socket with the path and mode provided, and connect that to service-1 The mode field is optional, and if omitted will use the default mode for Envoy. This is not applicable for abstract sockets. See https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#envoy-v3-api-msg-config-core-v3-pipe for details NOTE: These options conflict the local_bind_socket_port and local_bind_socket_address options. We can bind to an port or we can bind to a socket, but not both. To expose a service listening on a Unix Domain socket to the service mesh use either the 'socket_path' field in the service definition or the 'local_service_socket_path' field in the proxy definition. These fields are analogous to the 'port' and 'service_port' fields in their respective locations. services { name = "service-2" socket_path = "/tmp/socket_service_2" ... } OR proxy { local_service_socket_path = "/tmp/socket_service_2" ... } There is no mode field since the service is expected to create the socket it is listening on, not the Envoy proxy. Again, the socket_path and local_service_socket_path fields conflict with address/port and local_service_address/local_service_port configuration entries. Set up a simple service mesh with dummy services: socat -d UNIX-LISTEN:/tmp/downstream.sock,fork UNIX-CONNECT:/tmp/upstream.sock socat -v tcp-l:4444,fork exec:/bin/cat services { name = "sock_forwarder" id = "sock_forwarder.1" socket_path = "/tmp/downstream.sock" connect { sidecar_service { proxy { upstreams = [ { destination_name = "echo-service" local_bind_socket_path = "/tmp/upstream.sock" config { passive_health_check { interval = "10s" max_failures = 42 } } } ] } } } } services { name = "echo-service" port = 4444 connect = { sidecar_service {} } Kind = "ingress-gateway" Name = "ingress-service" Listeners = [ { Port = 8080 Protocol = "tcp" Services = [ { Name = "sock_forwarder" } ] } ] consul agent -dev -enable-script-checks -config-dir=./consul.d consul connect envoy -sidecar-for sock_forwarder.1 consul connect envoy -sidecar-for echo-service -admin-bind localhost:19001 consul config write ingress-gateway.hcl consul connect envoy -gateway=ingress -register -service ingress-service -address '{{ GetInterfaceIP "eth0" }}:8888' -admin-bind localhost:19002 netcat 127.0.0.1 4444 netcat 127.0.0.1 8080 Signed-off-by: Mark Anderson <manderson@hashicorp.com> * fixup Unix capitalization Signed-off-by: Mark Anderson <manderson@hashicorp.com> * Update website/content/docs/connect/registration/service-registration.mdx Co-authored-by: Blake Covarrubias <blake@covarrubi.as> * Provide examples in hcl and json Signed-off-by: Mark Anderson <manderson@hashicorp.com> * Apply suggestions from code review Co-authored-by: Blake Covarrubias <blake@covarrubi.as> * One more fixup for docs Signed-off-by: Mark Anderson <manderson@hashicorp.com> Co-authored-by: Blake Covarrubias <blake@covarrubi.as>
2021-06-05 01:54:31 +00:00
"local_service_socket_path": "/tmp/redis.sock",
Add docs for transparent proxy mode and config (#10038) Add docs for transparent proxy mode and config Co-authored-by: Nitya Dhanushkodi <nitya@hashicorp.com> Co-authored-by: Blake Covarrubias <blake@covarrubi.as> Co-authored-by: Iryna Shustava <ishustava@users.noreply.github.com> Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com>
2021-04-16 19:50:02 +00:00
"mode": "transparent",
"transparent_proxy": {
"outbound_listener_port": 22500
docs(discovery/service): Clarify multiple service definitions Be more explicit that the definition of multiple services only works in config files, not using the HTTP API. Ref: https://discuss.hashicorp.com/t/register-multiple-services-via-put-request/
2021-04-29 17:39:11 +00:00
},
Add Proxy Upstreams to Service Definition (#4639) * Refactor Service Definition ProxyDestination. This includes: - Refactoring all internal structs used - Updated tests for both deprecated and new input for: - Agent Services endpoint response - Agent Service endpoint response - Agent Register endpoint - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Register - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Services endpoint response - Catalog Node endpoint response - Catalog Service endpoint response - Updated API tests for all of the above too (both deprecated and new forms of register) TODO: - config package changes for on-disk service definitions - proxy config endpoint - built-in proxy support for new fields * Agent proxy config endpoint updated with upstreams * Config file changes for upstreams. * Add upstream opaque config and update all tests to ensure it works everywhere. * Built in proxy working with new Upstreams config * Command fixes and deprecations * Fix key translation, upstream type defaults and a spate of other subtele bugs found with ned to end test scripts... TODO: tests still failing on one case that needs a fix. I think it's key translation for upstreams nested in Managed proxy struct. * Fix translated keys in API registration. ≈ * Fixes from docs - omit some empty undocumented fields in API - Bring back ServiceProxyDestination in Catalog responses to not break backwards compat - this was removed assuming it was only used internally. * Documentation updates for Upstreams in service definition * Fixes for tests broken by many refactors. * Enable travis on f-connect branch in this branch too. * Add consistent Deprecation comments to ProxyDestination uses * Update version number on deprecation notices, and correct upstream datacenter field with explanation in docs
2018-09-12 16:07:47 +00:00
"config": {},
Initial Mesh Gateway Docs (#6090)
2019-07-08 23:40:57 +00:00
"upstreams": [],
"mesh_gateway": {
"mode": "local"
Expose HTTP-based paths through Connect proxy (#6446) Fixes: #5396 This PR adds a proxy configuration stanza called expose. These flags register listeners in Connect sidecar proxies to allow requests to specific HTTP paths from outside of the node. This allows services to protect themselves by only listening on the loopback interface, while still accepting traffic from non Connect-enabled services. Under expose there is a boolean checks flag that would automatically expose all registered HTTP and gRPC check paths. This stanza also accepts a paths list to expose individual paths. The primary use case for this functionality would be to expose paths for third parties like Prometheus or the kubelet. Listeners for requests to exposed paths are be configured dynamically at run time. Any time a proxy, or check can be registered, a listener can also be created. In this initial implementation requests to these paths are not authenticated/encrypted.
2019-09-26 02:55:52 +00:00
},
"expose": {
"checks": true,
"paths": [
{
"path": "/healthz",
"local_path_port": 8080,
"listener_port": 21500,
"protocol": "http2"
}
]
Initial Mesh Gateway Docs (#6090)
2019-07-08 23:40:57 +00:00
}
website: broken partial rendering and missing id (#4862) * Fix partial rendering in service command (CLI) help * Fix sample JSON to be a valid json for service registration * Add missing id field to make the complete document complete.
2018-10-29 08:41:25 +00:00
},
website: document proxy security settings
2018-06-12 15:58:31 +00:00
"connect": {
"native": false,
[WIP] Initial draft of Sidecar Service and Managed Proxy deprecation docs (#4752) * Initial draft of Sidecar Service and Managed Proxy deprecation docs * Service definition deprecation notices and sidecar service * gRPC and sidecar service config options; Deprecate managed proxy options * Envoy Docs: Basic envoy command; envoy getting started/intro * Remove change that snuck in * Envoy custom config example * Add agent/service API docs; deprecate proxy config endpoint * Misc grep cleanup for managed proxies; capitalize Envoy * Updates to getting started guide * Add missing link * Refactor Envoy guide into a separate guide and add bootstrap reference notes. * Add limitations to Envoy docs; Highlight no fixes for known managed proxy issues on deprecation page; clarify snake cae stuff; Sidecar Service lifecycle
2018-10-11 09:44:42 +00:00
"sidecar_service": {}
"proxy": { // Deprecated
website: document proxy security settings
2018-06-12 15:58:31 +00:00
"command": [],
"config": {}
}
Implementation of Weights Data structures (#4468) * Implementation of Weights Data structures Adding this datastructure will allow us to resolve the issues #1088 and #4198 This new structure defaults to values: ``` { Passing: 1, Warning: 0 } ``` Which means, use weight of 0 for a Service in Warning State while use Weight 1 for a Healthy Service. Thus it remains compatible with previous Consul versions. * Implemented weights for DNS SRV Records * DNS properly support agents with weight support while server does not (backwards compatibility) * Use Warning value of Weights of 1 by default When using DNS interface with only_passing = false, all nodes with non-Critical healthcheck used to have a weight value of 1. While having weight.Warning = 0 as default value, this is probably a bad idea as it breaks ascending compatibility. Thus, we put a default value of 1 to be consistent with existing behaviour. * Added documentation for new weight field in service description * Better documentation about weights as suggested by @banks * Return weight = 1 for unknown Check states as suggested by @banks * Fixed typo (of -> or) in error message as requested by @mkeeler * Fixed unstable unit test TestRetryJoin * Fixed unstable tests * Fixed wrong Fatalf format in `testrpc/wait.go` * Added notes regarding DNS SRV lookup limitations regarding number of instances * Documentation fixes and clarification regarding SRV records with weights as requested by @banks * Rephrase docs
2018-09-07 14:30:47 +00:00
},
"weights": {
"passing": 5,
"warning": 1
Add missing token field in the service definition in the docs (#5685) Fixes #5684
2019-04-18 20:05:51 +00:00
},
Sync of OSS changes to support namespaces (#6909)
2019-12-10 02:26:41 +00:00
"token": "233b604b-b92e-48c8-a253-5f11514e4b50",
"namespace": "foo"
Use new Markdown syntaxes and add SEO descriptions
2014-10-19 23:40:10 +00:00
}
}
```
website: document checks and services
2014-02-19 02:05:18 +00:00
Added HCL examples to service discovery page (#11989) Improved HCL examples in the service discovery docs page
2022-01-10 19:12:42 +00:00
</CodeTabs>
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
The following table describes the available parameters for service definitions.
### `service`
fixed typos, finished applying tables, minor editing
2021-08-24 16:57:48 +00:00
This is the root-level parameter that defines the service. You can specify the parameters to configure the service.
applying @blake 's feedback
2021-08-30 21:49:32 +00:00
| Parameter | Description | Default | Required |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------- |
| `id` | String value that specifies the service ID. <p>If not specified, the value of the `name` field will be used. </p><p>Services must have unique IDs per node, so you should specify unique values if the default `name` will conflict with other services.</p> | Value of the `name` parameter | Optional |
| `name` | Specifies the name of the service. <br/>The value for this parameter is used as the ID if the `id` parameter is not specified.<br/>We recommend using valid DNS labels for service definition names for compatibility with external DNSs. | None | Required |
| `tags` | List of string values that can be used to add service-level labels. <br/>For example, you can define tags that distinguish between `primary` and `secondary` nodes or service versions. <br/>We recommend using valid DNS labels for service definition IDs for compatibility with external DNSs.<br/>Tag values are opaque to Consul.<br/> | None | Optional |
| `address` | String value that specifies a service-specific IP address or hostname. <br/>If no value is specified, the IP address of the agent node is used by default. <br/>There is no service-side validation of this parameter. | IP address of the agent node | Optional |
| `meta` | Object that defines a map of the max 64 key/value pairs. <br/>The meta object has the same limitations as the node meta object in the node definition. <br/>Meta data can be retrieved per individual instance of the service. All instances of a given service have their own copy of the meta data. <br/> See [Adding Meta Data](#adding-meta-data) for supported parameters.<br/> | None | Optional |
| `tagged_addresses` | Tagged addresses are additional addresses that may be defined for a node or service. See [Tagged Addresses](#tagged-addresses) for details. | None | Optional |
| `port` | Integer value that specifies a service-specific port number. The port number should be specified when the `address` parameter is defined to improve service discoverability. | Optional |
| `socket_path` | String value that specifies the path to the service socket. <br/>Specify this parameter to expose the service to the mesh if the service listens on a Unix Domain socket. | None | Optional |
| `enable_tag_override` | Boolean value that determines if the anti-entropy feature for the service is enabled. <br/> If set to `true`, then external agents can update this service in the catalog and modify the tags.<br/> Subsequent local sync operations by this agent will ignore the updated tags. <br/> This parameter only applies to the locally-registered service. If multiple nodes register the same service, the `enable_tag_override` configuration, and all other service configuration items, operate independently. <br/>Updating the tags for services registered on one node is independent from the same service (by name) registered on another node. <br/> See [anti-entropy syncs](/docs/internals/anti-entropy) for additional information.<br/> | False | Optional |
| `checks` | Array of objects that define health checks for the service. See [Health Checks](#health-checks) for details. | None | Optional |
| `kind` | String value that identifies the service as a Connect proxy. See [Connect](#connect) for details. | None | Optional |
| `proxy_destination` | String value that specifies the _name_ of the destination service that the service currently being configured proxies to. <br/>This parameter is deprecated. Use `proxy.destination_service` instead. <br/>See [Connect](#connect) for additional information. | None | Optional |
| `proxy` | Object that defines the destination services that the service currently being configured proxies to. See [Proxy](#proxy) for additional information. | None | Optional |
| `connect` | Object that configures a Consul Connect service mesh connection. See [Connect](#connect) for details. | None | Optional |
| `weights` | Object that configures the weight of the service in terms of its DNS service (SRV) response. See [DNS SRV Weights](#dns-srv-weights) for details. | None | Optional |
| `token` | String value specifying the ACL token to be used to register the service (if the ACL system is enabled). The token is required for the service to interact with the service catalog. See [Security Configurations](#security-configurations) for details. | None | Required if ACLs are enabled |
| `namespace` | String value specifying the Consul Namespace where the service should be registered. See [Security Configurations](#security-configurations) for details. | None | Optional |
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
### Adding Meta Data
fixed typos, finished applying tables, minor editing
2021-08-24 16:57:48 +00:00
You can add semantic meta data to the service using the `meta` parameter. This parameter defines a map of max 64 key/value pairs. You can specify the following parameters to define meta data for the service.
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
fixed typos, finished applying tables, minor editing
2021-08-24 16:57:48 +00:00
| Parameter | Description | Default | Required |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
| `KEY` | String value that adds semantic metadata to the service. <br/>Keys can only have ASCII characters (`A` - `Z`, `a` - `z`, `0` - `9`, `_`, and `-`). <br/>Keys can not have special characters. <br/>Keys are limited to 128 characters.<br/>Values are limited to 512 characters. | None | Optional |
Added documentation for meta
2018-04-24 19:56:35 +00:00
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
### Security Configurations
If the ACL system is enabled, specify a value for the `token` parameter to provide an ACL token. This token is
used for any interaction with the catalog for the service, including [anti-entropy syncs](/docs/internals/anti-entropy) and deregistration.
[WIP] Initial draft of Sidecar Service and Managed Proxy deprecation docs (#4752) * Initial draft of Sidecar Service and Managed Proxy deprecation docs * Service definition deprecation notices and sidecar service * gRPC and sidecar service config options; Deprecate managed proxy options * Envoy Docs: Basic envoy command; envoy getting started/intro * Remove change that snuck in * Envoy custom config example * Add agent/service API docs; deprecate proxy config endpoint * Misc grep cleanup for managed proxies; capitalize Envoy * Updates to getting started guide * Add missing link * Refactor Envoy guide into a separate guide and add bootstrap reference notes. * Add limitations to Envoy docs; Highlight no fixes for known managed proxy issues on deprecation page; clarify snake cae stuff; Sidecar Service lifecycle
2018-10-11 09:44:42 +00:00
Clarifying service definition requirements for registering a service … (#8608)
2020-09-03 18:25:54 +00:00
Services registered in Consul clusters where both [Consul Namespaces](/docs/enterprise/namespaces)<EnterpriseAlert inline />
and the ACL system are enabled can be registered to specific namespaces that are associated with
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
ACL tokens scoped to the namespace. Services registered with a service definition
Clarifying service definition requirements for registering a service … (#8608)
2020-09-03 18:25:54 +00:00
will not inherit the namespace associated with the ACL token specified in the `token`
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
field. The `namespace` _and_ the `token` parameters must be included in the service definition for the service to be registered to the
Clarifying service definition requirements for registering a service … (#8608)
2020-09-03 18:25:54 +00:00
namespace that the ACL token is scoped to.
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
### Health Checks
Expose HTTP-based paths through Connect proxy (#6446) Fixes: #5396 This PR adds a proxy configuration stanza called expose. These flags register listeners in Connect sidecar proxies to allow requests to specific HTTP paths from outside of the node. This allows services to protect themselves by only listening on the loopback interface, while still accepting traffic from non Connect-enabled services. Under expose there is a boolean checks flag that would automatically expose all registered HTTP and gRPC check paths. This stanza also accepts a paths list to expose individual paths. The primary use case for this functionality would be to expose paths for third parties like Prometheus or the kubelet. Listeners for requests to exposed paths are be configured dynamically at run time. Any time a proxy, or check can be registered, a listener can also be created. In this initial implementation requests to these paths are not authenticated/encrypted.
2019-09-26 02:55:52 +00:00
fixed typos, finished applying tables, minor editing
2021-08-24 16:57:48 +00:00
You can add health checks to your service definition. Health checks perform several safety functions, such as allowing a web balancer to gracefully remove failing nodes and allowing a database
applying @blake 's feedback
2021-08-30 21:49:32 +00:00
to replace a failed secondary. The health check functionality is strongly integrated into the DNS interface, as well. If a service is failing its health check or a node has any failing system-level check, the DNS interface will omit that
Expose HTTP-based paths through Connect proxy (#6446) Fixes: #5396 This PR adds a proxy configuration stanza called expose. These flags register listeners in Connect sidecar proxies to allow requests to specific HTTP paths from outside of the node. This allows services to protect themselves by only listening on the loopback interface, while still accepting traffic from non Connect-enabled services. Under expose there is a boolean checks flag that would automatically expose all registered HTTP and gRPC check paths. This stanza also accepts a paths list to expose individual paths. The primary use case for this functionality would be to expose paths for third parties like Prometheus or the kubelet. Listeners for requests to exposed paths are be configured dynamically at run time. Any time a proxy, or check can be registered, a listener can also be created. In this initial implementation requests to these paths are not authenticated/encrypted.
2019-09-26 02:55:52 +00:00
node from any service query.
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
The health check name is automatically generated as `service:<service-id>`. If there are multiple service checks
Expose HTTP-based paths through Connect proxy (#6446) Fixes: #5396 This PR adds a proxy configuration stanza called expose. These flags register listeners in Connect sidecar proxies to allow requests to specific HTTP paths from outside of the node. This allows services to protect themselves by only listening on the loopback interface, while still accepting traffic from non Connect-enabled services. Under expose there is a boolean checks flag that would automatically expose all registered HTTP and gRPC check paths. This stanza also accepts a paths list to expose individual paths. The primary use case for this functionality would be to expose paths for third parties like Prometheus or the kubelet. Listeners for requests to exposed paths are be configured dynamically at run time. Any time a proxy, or check can be registered, a listener can also be created. In this initial implementation requests to these paths are not authenticated/encrypted.
2019-09-26 02:55:52 +00:00
registered, the ID will be generated as `service:<service-id>:<num>` where
`<num>` is an incrementing number starting from `1`.
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
Consul includes several check types with different options. Refer to the [health checks documentation](/docs/agent/checks) for details.
Expose HTTP-based paths through Connect proxy (#6446) Fixes: #5396 This PR adds a proxy configuration stanza called expose. These flags register listeners in Connect sidecar proxies to allow requests to specific HTTP paths from outside of the node. This allows services to protect themselves by only listening on the loopback interface, while still accepting traffic from non Connect-enabled services. Under expose there is a boolean checks flag that would automatically expose all registered HTTP and gRPC check paths. This stanza also accepts a paths list to expose individual paths. The primary use case for this functionality would be to expose paths for third parties like Prometheus or the kubelet. Listeners for requests to exposed paths are be configured dynamically at run time. Any time a proxy, or check can be registered, a listener can also be created. In this initial implementation requests to these paths are not authenticated/encrypted.
2019-09-26 02:55:52 +00:00
### Proxy
Service definitions allow for an optional proxy registration. Proxies used with Connect
initial
2020-04-06 20:27:35 +00:00
are registered as services in Consul's catalog.
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
See the [Proxy Service Registration](/docs/connect/registration/service-registration) reference
initial
2020-04-06 20:27:35 +00:00
for the available configuration options.
Expose HTTP-based paths through Connect proxy (#6446) Fixes: #5396 This PR adds a proxy configuration stanza called expose. These flags register listeners in Connect sidecar proxies to allow requests to specific HTTP paths from outside of the node. This allows services to protect themselves by only listening on the loopback interface, while still accepting traffic from non Connect-enabled services. Under expose there is a boolean checks flag that would automatically expose all registered HTTP and gRPC check paths. This stanza also accepts a paths list to expose individual paths. The primary use case for this functionality would be to expose paths for third parties like Prometheus or the kubelet. Listeners for requests to exposed paths are be configured dynamically at run time. Any time a proxy, or check can be registered, a listener can also be created. In this initial implementation requests to these paths are not authenticated/encrypted.
2019-09-26 02:55:52 +00:00
[WIP] Initial draft of Sidecar Service and Managed Proxy deprecation docs (#4752) * Initial draft of Sidecar Service and Managed Proxy deprecation docs * Service definition deprecation notices and sidecar service * gRPC and sidecar service config options; Deprecate managed proxy options * Envoy Docs: Basic envoy command; envoy getting started/intro * Remove change that snuck in * Envoy custom config example * Add agent/service API docs; deprecate proxy config endpoint * Misc grep cleanup for managed proxies; capitalize Envoy * Updates to getting started guide * Add missing link * Refactor Envoy guide into a separate guide and add bootstrap reference notes. * Add limitations to Envoy docs; Highlight no fixes for known managed proxy issues on deprecation page; clarify snake cae stuff; Sidecar Service lifecycle
2018-10-11 09:44:42 +00:00
### Connect
fixed more typos, applied additional tables, additional edits
2021-08-24 18:15:33 +00:00
The `kind` parameter determines the service's role. Services can be configured to perform several roles, but you must omit the `kind` parameter for typical non-proxy instances.
applying @blake 's feedback
2021-08-30 21:49:32 +00:00
The following roles are supported for service entries:
- `connect-proxy`: Defines the configuration for a connect proxy
- `ingress-gateway`: Defines the configuration for an [ingress gateway](/docs/connect/config-entries/ingress-gateway)
- `mesh-gateway`: Defines the configuration for a [mesh gateway](/docs/connect/gateways/mesh-gateway#mesh-gateway-configuration)
- `terminating-gateway`: Defines the configuration for a [terminating gateway](/docs/connect/config-entries/terminating-gateway#terminating-gateway)
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
fixed more typos, applied additional tables, additional edits
2021-08-24 18:15:33 +00:00
In the service definition example described above, the service is registered as a proxy because the `kind` property is set to `connect-proxy`.
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
The `proxy` parameter is also required for Connect proxy registrations and is only valid if `kind` is `connect-proxy`.
missed typo
2021-08-30 21:50:55 +00:00
Refer to the [Proxy Service Registration](/docs/connect/registration/service-registration) documentation for details about this type.
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
fixed more typos, applied additional tables, additional edits
2021-08-24 18:15:33 +00:00
When the `kind` parameter is set to `connect-proxy`, the only required parameter for the `proxy` configuration is `destination_service_name`.
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
Refer to the [complete proxy configuration example](/docs/connect/registration/service-registration#complete-configuration-example) for additional information.
[WIP] Initial draft of Sidecar Service and Managed Proxy deprecation docs (#4752) * Initial draft of Sidecar Service and Managed Proxy deprecation docs * Service definition deprecation notices and sidecar service * gRPC and sidecar service config options; Deprecate managed proxy options * Envoy Docs: Basic envoy command; envoy getting started/intro * Remove change that snuck in * Envoy custom config example * Add agent/service API docs; deprecate proxy config endpoint * Misc grep cleanup for managed proxies; capitalize Envoy * Updates to getting started guide * Add missing link * Refactor Envoy guide into a separate guide and add bootstrap reference notes. * Add limitations to Envoy docs; Highlight no fixes for known managed proxy issues on deprecation page; clarify snake cae stuff; Sidecar Service lifecycle
2018-10-11 09:44:42 +00:00
fixed more typos, applied additional tables, additional edits
2021-08-24 18:15:33 +00:00
The `connect` field can be specified to configure [Connect](/docs/connect) for a service. This field is available in Consul 1.2.0 and later. The following parameters are available.
| Parameter | Description | Default | Required |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------- |
| `native` | Boolean value that advertises the service as [Connect-native](/docs/connect/native). <br/>If set to `true`, do not configure a `sidecar_service`. | `false` | Optional |
| `sidecar_service` | Object that defines a nested service definition. <br/>Do not configure if `native` is set to `true`. | See [Sidecar Service Registration](/docs/connect/registration/sidecar-service) for default configurations. | Optional |
applying @blake 's feedback
2021-08-30 21:49:32 +00:00
-> **Non-service registration roles**: The `kind` values supported for configuration entries are different than what is supported for service registrations. Refer to the [Configuration Entries](/docs/connect/config-entries) documentation for information about non-service registration types.
fixed more typos, applied additional tables, additional edits
2021-08-24 18:15:33 +00:00
#### Deprecated parameters
Different Consul Connect parameters are supported for different Consul versions. The following table describes changes applicable to service discovery.
| Parameter | Description | Consul version | Status |
| ------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------- |
| `proxy_destination` | Specified the proxy destination **in the root level** of the definition file. | 1.2.0 to 1.3.0 | Deprecated since 1.5.0. <br/> Use `proxy.destination_service_name` instead. |
| `connect.proxy` | Specified "managed" proxies, [which have been deprecated](/docs/connect/proxies/managed-deprecated). | 1.2.0 (beta) to 1.3.0 (beta) | Deprecated. |
Clarify enable_tag_override explanation In designing a potential UI for a configuration of `enable_tag_override`, I found the documentation confusing and lengthy. Here, I've made an attempt at re-writing this section to be more concise and clear. I also made a few small changes to the organization of this file to map explanations to the order of the properties listing at the top. I find it easier to scan docs when explanations appear in the same order they are listed at the top. For explanations that span multiple paragraphs, I provided a subheading, which also helps in linking from other pages. Finally, I removed a duplicated paragraph from the documentation.
2018-10-05 15:53:27 +00:00
[WIP] Initial draft of Sidecar Service and Managed Proxy deprecation docs (#4752) * Initial draft of Sidecar Service and Managed Proxy deprecation docs * Service definition deprecation notices and sidecar service * gRPC and sidecar service config options; Deprecate managed proxy options * Envoy Docs: Basic envoy command; envoy getting started/intro * Remove change that snuck in * Envoy custom config example * Add agent/service API docs; deprecate proxy config endpoint * Misc grep cleanup for managed proxies; capitalize Envoy * Updates to getting started guide * Add missing link * Refactor Envoy guide into a separate guide and add bootstrap reference notes. * Add limitations to Envoy docs; Highlight no fixes for known managed proxy issues on deprecation page; clarify snake cae stuff; Sidecar Service lifecycle
2018-10-11 09:44:42 +00:00
### DNS SRV Weights
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
You can configure how the service responds to DNS SRV requests by specifying a set of states/weights in the `weights` field.
#### `weights`
When DNS SRV requests are made, the response will include the weights specified for the given state of the service.
This allows some instances to be given higher weight if they have more capacity. It also allows load reduction on
services with checks in `warning` status by giving passing instances a higher weight.
[WIP] Initial draft of Sidecar Service and Managed Proxy deprecation docs (#4752) * Initial draft of Sidecar Service and Managed Proxy deprecation docs * Service definition deprecation notices and sidecar service * gRPC and sidecar service config options; Deprecate managed proxy options * Envoy Docs: Basic envoy command; envoy getting started/intro * Remove change that snuck in * Envoy custom config example * Add agent/service API docs; deprecate proxy config endpoint * Misc grep cleanup for managed proxies; capitalize Envoy * Updates to getting started guide * Add missing link * Refactor Envoy guide into a separate guide and add bootstrap reference notes. * Add limitations to Envoy docs; Highlight no fixes for known managed proxy issues on deprecation page; clarify snake cae stuff; Sidecar Service lifecycle
2018-10-11 09:44:42 +00:00
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
| Parameter | Description | Default | Required |
| --------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -------- |
| `STATE` | Integer value indicating its weight. A higher number indicates more weight. | If not specified, the following weights are used: <br/> `"passing" : 1` <br/> `"warning" : 1` | Optional |
If a service is `critical`, it is excluded from DNS responses.
Services with warning checks are included in responses by default, but excluded if the optional param `only_passing = true`
is present in the agent DNS configuration or the `passing` query parameter is used via the API.
[WIP] Initial draft of Sidecar Service and Managed Proxy deprecation docs (#4752) * Initial draft of Sidecar Service and Managed Proxy deprecation docs * Service definition deprecation notices and sidecar service * gRPC and sidecar service config options; Deprecate managed proxy options * Envoy Docs: Basic envoy command; envoy getting started/intro * Remove change that snuck in * Envoy custom config example * Add agent/service API docs; deprecate proxy config endpoint * Misc grep cleanup for managed proxies; capitalize Envoy * Updates to getting started guide * Add missing link * Refactor Envoy guide into a separate guide and add bootstrap reference notes. * Add limitations to Envoy docs; Highlight no fixes for known managed proxy issues on deprecation page; clarify snake cae stuff; Sidecar Service lifecycle
2018-10-11 09:44:42 +00:00
Clarify enable_tag_override explanation In designing a potential UI for a configuration of `enable_tag_override`, I found the documentation confusing and lengthy. Here, I've made an attempt at re-writing this section to be more concise and clear. I also made a few small changes to the organization of this file to map explanations to the order of the properties listing at the top. I find it easier to scan docs when explanations appear in the same order they are listed at the top. For explanations that span multiple paragraphs, I provided a subheading, which also helps in linking from other pages. Finally, I removed a duplicated paragraph from the documentation.
2018-10-05 15:53:27 +00:00
### Enable Tag Override and Anti-Entropy
Services may also contain a `token` field to provide an ACL token. This token is
used for any interaction with the catalog for the service, including
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
[anti-entropy syncs](/docs/internals/anti-entropy) and deregistration.
Clarify enable_tag_override explanation In designing a potential UI for a configuration of `enable_tag_override`, I found the documentation confusing and lengthy. Here, I've made an attempt at re-writing this section to be more concise and clear. I also made a few small changes to the organization of this file to map explanations to the order of the properties listing at the top. I find it easier to scan docs when explanations appear in the same order they are listed at the top. For explanations that span multiple paragraphs, I provided a subheading, which also helps in linking from other pages. Finally, I removed a duplicated paragraph from the documentation.
2018-10-05 15:53:27 +00:00
You can optionally disable the anti-entropy feature for this service using the
`enable_tag_override` flag. External agents can modify tags on services in the
catalog, so subsequent sync operations can either maintain tag modifications or
revert them. If `enable_tag_override` is set to `TRUE`, the next sync cycle may
revert some service properties, **but** the tags would maintain the updated value.
If `enable_tag_override` is set to `FALSE`, the next sync cycle will revert any
updated service properties, **including** tags, to their original value.
Documentation pass I was reviewing some docs and found a few issues. 1. Fixed some spelling mistakes. 2. Re-formatted some paragraphs. 3. Changed some potentially loaded language. 4. Fixed some grammar issues. 5. Tried to consistently use syntax-highlighting. 6. Fixed post-period spacing. 7. Fixed some formatting issues and inconsistency. 8. All "notes" are either proper notes or re-written.
2016-11-25 16:00:02 +00:00
It's important to note that this applies only to the locally registered
service. If you have multiple nodes all registering the same service
config: add generic method to translate between CamelCase and snake_case (#3557) * doc: document discrepancy between id and CheckID * doc: document enable_tag_override change * config: add TranslateKeys helper TranslateKeys makes it easier to map between different representations of internal structures. It allows to recursively map alias keys to canonical keys in structured maps. * config: use TranslateKeys for config file This also adds support for 'enabletagoverride' and removes the need for a separate CheckID alias field. * config: remove dead code * agent: use TranslateKeys for FixupCheckType * agent: translate enable_tag_override during service registration * doc: add '.hcl' as valid extension * config: map ScriptArgs to args * config: add comment for TranslateKeys
2017-10-10 23:40:59 +00:00
their `enable_tag_override` configuration and all other service
Removed two space after period exceptions
2016-11-25 18:25:09 +00:00
configuration items are independent of one another. Updating the tags
Documentation pass I was reviewing some docs and found a few issues. 1. Fixed some spelling mistakes. 2. Re-formatted some paragraphs. 3. Changed some potentially loaded language. 4. Fixed some grammar issues. 5. Tried to consistently use syntax-highlighting. 6. Fixed post-period spacing. 7. Fixed some formatting issues and inconsistency. 8. All "notes" are either proper notes or re-written.
2016-11-25 16:00:02 +00:00
for the service registered on one node is independent of the same
config: add generic method to translate between CamelCase and snake_case (#3557) * doc: document discrepancy between id and CheckID * doc: document enable_tag_override change * config: add TranslateKeys helper TranslateKeys makes it easier to map between different representations of internal structures. It allows to recursively map alias keys to canonical keys in structured maps. * config: use TranslateKeys for config file This also adds support for 'enabletagoverride' and removes the need for a separate CheckID alias field. * config: remove dead code * agent: use TranslateKeys for FixupCheckType * agent: translate enable_tag_override during service registration * doc: add '.hcl' as valid extension * config: map ScriptArgs to args * config: add comment for TranslateKeys
2017-10-10 23:40:59 +00:00
service (by name) registered on another node. If `enable_tag_override` is
Removed two space after period exceptions
2016-11-25 18:25:09 +00:00
not specified the default value is false. See [anti-entropy
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
syncs](/docs/internals/anti-entropy) for more info.
Documentation pass I was reviewing some docs and found a few issues. 1. Fixed some spelling mistakes. 2. Re-formatted some paragraphs. 3. Changed some potentially loaded language. 4. Fixed some grammar issues. 5. Tried to consistently use syntax-highlighting. 6. Fixed post-period spacing. 7. Fixed some formatting issues and inconsistency. 8. All "notes" are either proper notes or re-written.
2016-11-25 16:00:02 +00:00
config: add generic method to translate between CamelCase and snake_case (#3557) * doc: document discrepancy between id and CheckID * doc: document enable_tag_override change * config: add TranslateKeys helper TranslateKeys makes it easier to map between different representations of internal structures. It allows to recursively map alias keys to canonical keys in structured maps. * config: use TranslateKeys for config file This also adds support for 'enabletagoverride' and removes the need for a separate CheckID alias field. * config: remove dead code * agent: use TranslateKeys for FixupCheckType * agent: translate enable_tag_override during service registration * doc: add '.hcl' as valid extension * config: map ScriptArgs to args * config: add comment for TranslateKeys
2017-10-10 23:40:59 +00:00
For Consul 0.9.3 and earlier you need to use `enableTagOverride`. Consul 1.0
supports both `enable_tag_override` and `enableTagOverride` but the latter is
Remove support for EnableTagOverride in config files
2018-05-07 23:19:13 +00:00
deprecated and has been removed as of Consul 1.1.
config: add generic method to translate between CamelCase and snake_case (#3557) * doc: document discrepancy between id and CheckID * doc: document enable_tag_override change * config: add TranslateKeys helper TranslateKeys makes it easier to map between different representations of internal structures. It allows to recursively map alias keys to canonical keys in structured maps. * config: use TranslateKeys for config file This also adds support for 'enabletagoverride' and removes the need for a separate CheckID alias field. * config: remove dead code * agent: use TranslateKeys for FixupCheckType * agent: translate enable_tag_override during service registration * doc: add '.hcl' as valid extension * config: map ScriptArgs to args * config: add comment for TranslateKeys
2017-10-10 23:40:59 +00:00
Document tagged addresses (#10744) Add section for tagged addresses on service definition documentation. Resolves #6989 Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
2021-08-12 23:49:59 +00:00
### Tagged Addresses
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
Tagged addresses are additional addresses that may be defined for a node or
Document tagged addresses (#10744) Add section for tagged addresses on service definition documentation. Resolves #6989 Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
2021-08-12 23:49:59 +00:00
service. Tagged addresses can be used by remote agents and services as alternative
addresses for communicating with the given node or service. Multiple tagged
addresses may be configured on a node or service.
fixed typos, finished applying tables, minor editing
2021-08-24 16:57:48 +00:00
The following example describes the syntax for defining a tagged address.
Document tagged addresses (#10744) Add section for tagged addresses on service definition documentation. Resolves #6989 Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
2021-08-12 23:49:59 +00:00
<CodeTabs heading="Tagged address format">
```hcl
service {
name = "redis"
port = 80
tagged_addresses {
<tag> = {
address = "<address>"
port = port
}
}
}
```
```json
{
"service": {
"name": "redis",
"port": 80,
"tagged_addresses": {
"<tag>": {
"address": "<address>",
"port": port
}
}
}
}
```
</CodeTabs>
fixed typos, finished applying tables, minor editing
2021-08-24 16:57:48 +00:00
The following table provides an overview of the various tagged address types supported by Consul.
Document tagged addresses (#10744) Add section for tagged addresses on service definition documentation. Resolves #6989 Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
2021-08-12 23:49:59 +00:00
fixed typos, finished applying tables, minor editing
2021-08-24 16:57:48 +00:00
| Type | Description | Tags |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
| LAN | LAN addresses are intended to be directly accessible only from services within the same Consul data center. See [LAN tags](#lan-tags) for details. | `lan` <br/> `lan_ipv4` <br/> `lan_ipv6` |
| Virtual | Virtual tagged addresses are logical address types that can be configured on [Connect](/docs/connect)-enabled services. The virtual address provides a fixed IP address that can be used by downstream services when connecting to an upstream service. See [Virtual tags](#virtual-tags) for details. | `virtual` |
| WAN | Define a WAN address for the service or node when it should be accessed at an alternate address by services in a remote datacenter. See [WAN tags](#wan-tags) for details. | `wan` <br/> `wan_ipv4` <br/> `wan_ipv6` |
Document tagged addresses (#10744) Add section for tagged addresses on service definition documentation. Resolves #6989 Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
2021-08-12 23:49:59 +00:00
fixed typos, finished applying tables, minor editing
2021-08-24 16:57:48 +00:00
#### LAN tags
Document tagged addresses (#10744) Add section for tagged addresses on service definition documentation. Resolves #6989 Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
2021-08-12 23:49:59 +00:00
testing markdown table format for ref docs
2021-08-20 20:41:03 +00:00
- `lan` - The IPv4 LAN address at which the node or service is accessible.
- `lan_ipv4` - The IPv4 LAN address at which the node or service is accessible.
- `lan_ipv6` - The IPv6 LAN address at which the node or service is accessible.
Document tagged addresses (#10744) Add section for tagged addresses on service definition documentation. Resolves #6989 Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
2021-08-12 23:49:59 +00:00
<CodeTabs heading="Example LAN tagged address configuration">
<CodeBlockConfig filename="redis-service.hcl">
```hcl
service {
name = "redis"
address = "192.0.2.10"
port = 80
tagged_addresses {
lan = {
address = "192.0.2.10"
port = 80
}
lan_ipv4 = {
address = "192.0.2.10"
port = 80
}
lan_ipv6 = {
address = "2001:db8:1:2:cafe::1337"
port = 80
}
}
}
```
</CodeBlockConfig>
<CodeBlockConfig filename="redis-service.json">
```json
{
"service": {
"name": "redis",
"address": "192.0.2.10",
"port": 80,
"tagged_addresses": {
"lan": {
"address": "192.0.2.10",
"port": 80
},
"lan_ipv4": {
"address": "192.0.2.10",
"port": 80
},
"lan_ipv6": {
"address": "2001:db8:1:2:cafe::1337",
"port": 80
}
}
}
}
```
</CodeBlockConfig>
</CodeTabs>
fixed typos, finished applying tables, minor editing
2021-08-24 16:57:48 +00:00
#### Virtual tags
Document tagged addresses (#10744) Add section for tagged addresses on service definition documentation. Resolves #6989 Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
2021-08-12 23:49:59 +00:00
fixed typos, finished applying tables, minor editing
2021-08-24 16:57:48 +00:00
Connections to virtual addresses are load balanced across available instances of a service, provided the following conditions are satisfied:
Document tagged addresses (#10744) Add section for tagged addresses on service definition documentation. Resolves #6989 Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
2021-08-12 23:49:59 +00:00
1. [Transparent proxy](/docs/connect/transparent-proxy) is enabled for the
downstream and upstream services.
1. The upstream service is not configured for individual instances to be
[dialed directly](/docs/connect/config-entries/service-defaults#dialeddirectly).
fixed typos, finished applying tables, minor editing
2021-08-24 16:57:48 +00:00
Virtual addresses are not required to be routable IPs within the
Document tagged addresses (#10744) Add section for tagged addresses on service definition documentation. Resolves #6989 Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
2021-08-12 23:49:59 +00:00
network. They are strictly a control plane construct used to provide a fixed
address for the instances of a given logical service. Egress connections from
the proxy to an upstream service will be destined to the IP address of an
individual service instance, not the virtual address of the logical service.
Use the following address tag to specify the logical address at which the
service can be reached by other services in the mesh.
- `virtual` - The virtual IP address at which a logical service is reachable.
<CodeTabs heading="Example virtual tagged address configuration">
<CodeBlockConfig filename="redis-service.hcl">
```hcl
service {
name = "redis"
address = "192.0.2.10"
port = 80
tagged_addresses {
virtual = {
address = "203.0.113.50"
port = 80
}
}
}
```
</CodeBlockConfig>
<CodeBlockConfig filename="redis-service.json">
```json
{
"service": {
"name": "redis",
"address": "192.0.2.10",
"port": 80,
"tagged_addresses": {
"virtual": {
"address": "203.0.113.50",
"port": 80
}
}
}
}
```
</CodeBlockConfig>
</CodeTabs>
fixed typos, finished applying tables, minor editing
2021-08-24 16:57:48 +00:00
#### WAN tags
Document tagged addresses (#10744) Add section for tagged addresses on service definition documentation. Resolves #6989 Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
2021-08-12 23:49:59 +00:00
One or more of the following address tags can be configured for a node or service
to advertise how it should be accessed over the WAN.
- `wan` - The IPv4 WAN address at which the node or service is accessible when
being dialed from a remote data center.
- `wan_ipv4` - The IPv4 WAN address at which the node or service is accessible
when being dialed from a remote data center.
- `wan_ipv6` - The IPv6 WAN address at which the node or service is accessible
when being dialed from a remote data center.
<CodeTabs heading="Example WAN tagged address configuration">
<CodeBlockConfig filename="redis-service.hcl">
```hcl
service {
name = "redis"
address = "192.0.2.10"
port = 80
tagged_addresses {
wan = {
address = "198.51.100.200"
port = 80
}
wan_ipv4 = {
address = "198.51.100.200"
port = 80
}
wan_ipv6 = {
address = "2001:db8:5:6:1337::1eaf"
port = 80
}
}
}
```
</CodeBlockConfig>
<CodeBlockConfig filename="redis-service.json">
```json
{
"service": {
"name": "redis",
"address": "192.0.2.10",
"port": 80,
"tagged_addresses": {
"wan": {
"address": "198.51.100.200",
"port": 80
},
"wan_ipv4": {
"address": "198.51.100.200",
"port": 80
},
"wan_ipv6": {
"address": "2001:db8:5:6:1337::1eaf",
"port": 80
}
}
}
}
```
</CodeBlockConfig>
</CodeTabs>
Add multiple service definition support This change-set adds another key to the configuration decoding called `services`, which is expected to be a list of service definitions. It follows the established convention of only allowing one of the keys: `service`, `check`, `services`. For every entry in the list it calls the corresponding decode method and appends it to the Servics of the resulting Config. While a similar result could be achieved with changing the Services member of the Config struct to have named mapstruct tag it lacks the proper time conversions provided by DecodeServiceDefinition.
2014-10-24 02:22:25 +00:00
## Multiple Service Definitions
docs(discovery/service): Clarify multiple service definitions Be more explicit that the definition of multiple services only works in config files, not using the HTTP API. Ref: https://discuss.hashicorp.com/t/register-multiple-services-via-put-request/
2021-04-29 17:39:11 +00:00
Multiple services definitions can be provided at once when registering services
via the agent configuration by using the plural `services` key (registering
multiple services in this manner is not supported using the HTTP API).
Add multiple service definition support This change-set adds another key to the configuration decoding called `services`, which is expected to be a list of service definitions. It follows the established convention of only allowing one of the keys: `service`, `check`, `services`. For every entry in the list it calls the corresponding decode method and appends it to the Servics of the resulting Config. While a similar result could be achieved with changing the Services member of the Config struct to have named mapstruct tag it lacks the proper time conversions provided by DecodeServiceDefinition.
2014-10-24 02:22:25 +00:00
Added HCL examples to service discovery page (#11989) Improved HCL examples in the service discovery docs page
2022-01-10 19:12:42 +00:00
<CodeTabs heading="Multiple Service Definitions">
<CodeBlockConfig filename="redis-services.hcl">
```hcl
services {
id = "red0"
name = "redis"
tags = [
"primary"
]
address = ""
port = 6000
checks = [
{
args = ["/bin/check_redis", "-p", "6000"]
interval = "5s"
timeout = "20s"
}
]
}
services {
id = "red1"
name = "redis"
tags = [
"delayed",
"secondary"
]
address = ""
port = 7000
checks = [
{
args = ["/bin/check_redis", "-p", "7000"]
interval = "30s"
timeout = "60s"
}
]
}
```
</CodeBlockConfig>
<CodeBlockConfig filename="redis-services.json">
docs: Update code blocks across website * Use CodeTabs for examples in multiple formats. * Ensure correct language on code fences. * Use CodeBlockConfig for examples with filenames, or which need highlighted content.
2021-07-31 01:37:33 +00:00
```json
Add multiple service definition support This change-set adds another key to the configuration decoding called `services`, which is expected to be a list of service definitions. It follows the established convention of only allowing one of the keys: `service`, `check`, `services`. For every entry in the list it calls the corresponding decode method and appends it to the Servics of the resulting Config. While a similar result could be achieved with changing the Services member of the Config struct to have named mapstruct tag it lacks the proper time conversions provided by DecodeServiceDefinition.
2014-10-24 02:22:25 +00:00
{
"services": [
{
"id": "red0",
"name": "redis",
"tags": [
Documentation pass I was reviewing some docs and found a few issues. 1. Fixed some spelling mistakes. 2. Re-formatted some paragraphs. 3. Changed some potentially loaded language. 4. Fixed some grammar issues. 5. Tried to consistently use syntax-highlighting. 6. Fixed post-period spacing. 7. Fixed some formatting issues and inconsistency. 8. All "notes" are either proper notes or re-written.
2016-11-25 16:00:02 +00:00
"primary"
Add multiple service definition support This change-set adds another key to the configuration decoding called `services`, which is expected to be a list of service definitions. It follows the established convention of only allowing one of the keys: `service`, `check`, `services`. For every entry in the list it calls the corresponding decode method and appends it to the Servics of the resulting Config. While a similar result could be achieved with changing the Services member of the Config struct to have named mapstruct tag it lacks the proper time conversions provided by DecodeServiceDefinition.
2014-10-24 02:22:25 +00:00
],
Makes addresses blank in service definition.
2016-11-22 16:29:29 +00:00
"address": "",
Add multiple service definition support This change-set adds another key to the configuration decoding called `services`, which is expected to be a list of service definitions. It follows the established convention of only allowing one of the keys: `service`, `check`, `services`. For every entry in the list it calls the corresponding decode method and appends it to the Servics of the resulting Config. While a similar result could be achieved with changing the Services member of the Config struct to have named mapstruct tag it lacks the proper time conversions provided by DecodeServiceDefinition.
2014-10-24 02:22:25 +00:00
"port": 6000,
agent: support multiple checks per service
2015-01-14 01:52:17 +00:00
"checks": [
{
Remove the script field from checks in favor of args
2018-05-08 22:31:53 +00:00
"args": ["/bin/check_redis", "-p", "6000"],
agent: support multiple checks per service
2015-01-14 01:52:17 +00:00
"interval": "5s",
Document multiple services config in hcl Also change ttl => timeout since ttl doesn't work anymore.
2019-07-16 09:23:49 +00:00
"timeout": "20s"
agent: support multiple checks per service
2015-01-14 01:52:17 +00:00
}
]
Add multiple service definition support This change-set adds another key to the configuration decoding called `services`, which is expected to be a list of service definitions. It follows the established convention of only allowing one of the keys: `service`, `check`, `services`. For every entry in the list it calls the corresponding decode method and appends it to the Servics of the resulting Config. While a similar result could be achieved with changing the Services member of the Config struct to have named mapstruct tag it lacks the proper time conversions provided by DecodeServiceDefinition.
2014-10-24 02:22:25 +00:00
},
{
"id": "red1",
"name": "redis",
"tags": [
"delayed",
Documentation pass I was reviewing some docs and found a few issues. 1. Fixed some spelling mistakes. 2. Re-formatted some paragraphs. 3. Changed some potentially loaded language. 4. Fixed some grammar issues. 5. Tried to consistently use syntax-highlighting. 6. Fixed post-period spacing. 7. Fixed some formatting issues and inconsistency. 8. All "notes" are either proper notes or re-written.
2016-11-25 16:00:02 +00:00
"secondary"
Add multiple service definition support This change-set adds another key to the configuration decoding called `services`, which is expected to be a list of service definitions. It follows the established convention of only allowing one of the keys: `service`, `check`, `services`. For every entry in the list it calls the corresponding decode method and appends it to the Servics of the resulting Config. While a similar result could be achieved with changing the Services member of the Config struct to have named mapstruct tag it lacks the proper time conversions provided by DecodeServiceDefinition.
2014-10-24 02:22:25 +00:00
],
Makes addresses blank in service definition.
2016-11-22 16:29:29 +00:00
"address": "",
Add multiple service definition support This change-set adds another key to the configuration decoding called `services`, which is expected to be a list of service definitions. It follows the established convention of only allowing one of the keys: `service`, `check`, `services`. For every entry in the list it calls the corresponding decode method and appends it to the Servics of the resulting Config. While a similar result could be achieved with changing the Services member of the Config struct to have named mapstruct tag it lacks the proper time conversions provided by DecodeServiceDefinition.
2014-10-24 02:22:25 +00:00
"port": 7000,
agent: support multiple checks per service
2015-01-14 01:52:17 +00:00
"checks": [
{
Remove the script field from checks in favor of args
2018-05-08 22:31:53 +00:00
"args": ["/bin/check_redis", "-p", "7000"],
agent: support multiple checks per service
2015-01-14 01:52:17 +00:00
"interval": "30s",
Document multiple services config in hcl Also change ttl => timeout since ttl doesn't work anymore.
2019-07-16 09:23:49 +00:00
"timeout": "60s"
agent: support multiple checks per service
2015-01-14 01:52:17 +00:00
}
]
Add multiple service definition support This change-set adds another key to the configuration decoding called `services`, which is expected to be a list of service definitions. It follows the established convention of only allowing one of the keys: `service`, `check`, `services`. For every entry in the list it calls the corresponding decode method and appends it to the Servics of the resulting Config. While a similar result could be achieved with changing the Services member of the Config struct to have named mapstruct tag it lacks the proper time conversions provided by DecodeServiceDefinition.
2014-10-24 02:22:25 +00:00
},
...
]
}
```
website: adding tag/service name dns compliance docs
2015-06-25 16:07:55 +00:00
Added HCL examples to service discovery page (#11989) Improved HCL examples in the service discovery docs page
2022-01-10 19:12:42 +00:00
</CodeBlockConfig>
</CodeTabs>
Document multiple services config in hcl Also change ttl => timeout since ttl doesn't work anymore.
2019-07-16 09:23:49 +00:00
website: adding tag/service name dns compliance docs
2015-06-25 16:07:55 +00:00
## Service and Tag Names with DNS
[docs] Change links to the DNS information to the right place (#8675) The redirects were working in many situations but some (INTERNALS.md) was not. This just flips everything over to using the real link.
2020-11-17 15:03:00 +00:00
Consul exposes service definitions and tags over the [DNS](/docs/discovery/dns)
website: adding tag/service name dns compliance docs
2015-06-25 16:07:55 +00:00
interface. DNS queries have a strict set of allowed characters and a
well-defined format that Consul cannot override. While it is possible to
register services or tags with names that don't match the conventions, those
services and tags will not be discoverable via the DNS interface. It is
recommended to always use DNS-compliant service and tag names.
DNS-compliant service and tag names may contain any alpha-numeric characters, as
well as dashes. Dots are not supported because Consul internally uses them to
delimit service tags.
Add Proxy Upstreams to Service Definition (#4639) * Refactor Service Definition ProxyDestination. This includes: - Refactoring all internal structs used - Updated tests for both deprecated and new input for: - Agent Services endpoint response - Agent Service endpoint response - Agent Register endpoint - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Register - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Services endpoint response - Catalog Node endpoint response - Catalog Service endpoint response - Updated API tests for all of the above too (both deprecated and new forms of register) TODO: - config package changes for on-disk service definitions - proxy config endpoint - built-in proxy support for new fields * Agent proxy config endpoint updated with upstreams * Config file changes for upstreams. * Add upstream opaque config and update all tests to ensure it works everywhere. * Built in proxy working with new Upstreams config * Command fixes and deprecations * Fix key translation, upstream type defaults and a spate of other subtele bugs found with ned to end test scripts... TODO: tests still failing on one case that needs a fix. I think it's key translation for upstreams nested in Managed proxy struct. * Fix translated keys in API registration. ≈ * Fixes from docs - omit some empty undocumented fields in API - Bring back ServiceProxyDestination in Catalog responses to not break backwards compat - this was removed assuming it was only used internally. * Documentation updates for Upstreams in service definition * Fixes for tests broken by many refactors. * Enable travis on f-connect branch in this branch too. * Add consistent Deprecation comments to ProxyDestination uses * Update version number on deprecation notices, and correct upstream datacenter field with explanation in docs
2018-09-12 16:07:47 +00:00
## Service Definition Parameter Case
For historical reasons Consul's API uses `CamelCased` parameter names in
docs: all intention documentation updates (#8869)
2020-10-14 15:23:05 +00:00
responses, however its configuration file uses `snake_case` for both HCL and
[WIP] Initial draft of Sidecar Service and Managed Proxy deprecation docs (#4752) * Initial draft of Sidecar Service and Managed Proxy deprecation docs * Service definition deprecation notices and sidecar service * gRPC and sidecar service config options; Deprecate managed proxy options * Envoy Docs: Basic envoy command; envoy getting started/intro * Remove change that snuck in * Envoy custom config example * Add agent/service API docs; deprecate proxy config endpoint * Misc grep cleanup for managed proxies; capitalize Envoy * Updates to getting started guide * Add missing link * Refactor Envoy guide into a separate guide and add bootstrap reference notes. * Add limitations to Envoy docs; Highlight no fixes for known managed proxy issues on deprecation page; clarify snake cae stuff; Sidecar Service lifecycle
2018-10-11 09:44:42 +00:00
JSON representations. For this reason the registration _HTTP APIs_ accept both
name styles for service definition parameters although APIs will return the
Add tagged addresses for services (#5965) This allows addresses to be tagged at the service level similar to what we allow for nodes already. The address translation that can be enabled with the `translate_wan_addrs` config was updated to take these new addresses into account as well.
2019-06-17 14:51:50 +00:00
listings using `CamelCase`.
[WIP] Initial draft of Sidecar Service and Managed Proxy deprecation docs (#4752) * Initial draft of Sidecar Service and Managed Proxy deprecation docs * Service definition deprecation notices and sidecar service * gRPC and sidecar service config options; Deprecate managed proxy options * Envoy Docs: Basic envoy command; envoy getting started/intro * Remove change that snuck in * Envoy custom config example * Add agent/service API docs; deprecate proxy config endpoint * Misc grep cleanup for managed proxies; capitalize Envoy * Updates to getting started guide * Add missing link * Refactor Envoy guide into a separate guide and add bootstrap reference notes. * Add limitations to Envoy docs; Highlight no fixes for known managed proxy issues on deprecation page; clarify snake cae stuff; Sidecar Service lifecycle
2018-10-11 09:44:42 +00:00
Note though that **all config file formats require
`snake_case` fields**. We always document service definition examples using
`snake_case` and JSON since this format works in both config files and API
Update services.html.md
2019-01-24 12:41:43 +00:00
calls.