From bc86002be9efae4a202226b2c7529f12758722a1 Mon Sep 17 00:00:00 2001 From: John Cowen Date: Wed, 15 Jan 2020 15:36:17 +0000 Subject: [PATCH] docs: Add note about using valid DNS labels for service names (#7035) Add note about using valid DNS labels for service names --- website/source/api/agent/service.html.md | 9 ++++++--- website/source/api/catalog.html.md | 6 ++++-- website/source/docs/agent/services.html.md | 3 +++ 3 files changed, 13 insertions(+), 5 deletions(-) diff --git a/website/source/api/agent/service.html.md b/website/source/api/agent/service.html.md index ee73f87366..32e6cd80a4 100644 --- a/website/source/api/agent/service.html.md +++ b/website/source/api/agent/service.html.md @@ -495,14 +495,17 @@ Note that this endpoint, unlike most also [supports `snake_case`](/docs/agent/se service definition keys for compatibility with the config file format. - `Name` `(string: )` - Specifies the logical name of the service. - Many service instances may share the same logical service name. + Many service instances may share the same logical service name. We recommend using + [valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames) + for [compatibility with external DNS](/docs/agent/services.html#service-and-tag-names-with-dns). - `ID` `(string: "")` - Specifies a unique ID for this service. This must be unique per _agent_. This defaults to the `Name` parameter if not provided. - `Tags` `(array: nil)` - Specifies a list of tags to assign to the - service. These tags can be used for later filtering and are exposed via the - APIs. + service. These tags can be used for later filtering and are exposed via the APIs. + We recommend using [valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames) + for [compatibility with external DNS](/docs/agent/services.html#service-and-tag-names-with-dns) - `Address` `(string: "")` - Specifies the address of the service. If not provided, the agent's address is used as the address for the service during diff --git a/website/source/api/catalog.html.md b/website/source/api/catalog.html.md index cad0bd970c..1af47298b9 100644 --- a/website/source/api/catalog.html.md +++ b/website/source/api/catalog.html.md @@ -53,8 +53,10 @@ The table below shows this endpoint's support for - `Service` `(Service: nil)` - Specifies to register a service. If `ID` is not provided, it will be defaulted to the value of the `Service.Service` property. - Only one service with a given `ID` may be present per node. The service - `Tags`, `Address`, `Meta`, and `Port` fields are all optional. For more + Only one service with a given `ID` may be present per node. We recommend using + [valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames) + for service definition names for [compatibility with external DNS](/docs/agent/services.html#service-and-tag-names-with-dns). + The service `Tags`, `Address`, `Meta`, and `Port` fields are all optional. For more information about these fields and the implications of setting them, see the [Service - Agent API](/api/agent/service.html) page as registering services differs between using this or the Services Agent endpoint. diff --git a/website/source/docs/agent/services.html.md b/website/source/docs/agent/services.html.md index 6c7afd4e15..b6d5e7c73a 100644 --- a/website/source/docs/agent/services.html.md +++ b/website/source/docs/agent/services.html.md @@ -109,6 +109,9 @@ The `tags` property is a list of values that are opaque to Consul but can be used to distinguish between `primary` or `secondary` nodes, different versions, or any other service level labels. +We recommend using [valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames) +for service definition names and tags for [compatibility with external DNS](/docs/agent/services.html#service-and-tag-names-with-dns) + The `address` field can be used to specify a service-specific IP address. By default, the IP address of the agent is used, and this does not need to be provided. The `port` field can be used as well to make a service-oriented architecture