From 9e20a34d7553e90e5fbeb47266520ef74526cd5e Mon Sep 17 00:00:00 2001 From: James Rasell Date: Wed, 6 Apr 2022 18:51:14 +0200 Subject: [PATCH] website: add initial website docs for Nomad service discovery. (#12456) --- website/content/api-docs/events.mdx | 10 +- website/content/api-docs/services.mdx | 158 ++++++++++++++++++ .../content/docs/commands/service/delete.mdx | 39 +++++ .../content/docs/commands/service/index.mdx | 27 +++ .../content/docs/commands/service/info.mdx | 73 ++++++++ .../content/docs/commands/service/list.mdx | 56 +++++++ .../docs/job-specification/service.mdx | 68 +++++--- website/data/api-docs-nav-data.json | 4 + website/data/docs-nav-data.json | 21 +++ 9 files changed, 431 insertions(+), 25 deletions(-) create mode 100644 website/content/api-docs/services.mdx create mode 100644 website/content/docs/commands/service/delete.mdx create mode 100644 website/content/docs/commands/service/index.mdx create mode 100644 website/content/docs/commands/service/info.mdx create mode 100644 website/content/docs/commands/service/list.mdx diff --git a/website/content/api-docs/events.mdx b/website/content/api-docs/events.mdx index 5cf0b0cdf..7a9b5bef0 100644 --- a/website/content/api-docs/events.mdx +++ b/website/content/api-docs/events.mdx @@ -14,8 +14,8 @@ The `/event/stream` endpoint is used to stream events generated by Nomad. This endpoint streams a server's backlog of events as well as new events as they occur. The stream will be kept alive until the connection is closed. The format of the response body will be valid [ndjson](http://ndjson.org/). This means splitting the streaming -response at every `\n` character will guarantee each message is a valid JSON object. -Note that each JSON object may include multiple events (high server activity) or no +response at every `\n` character will guarantee each message is a valid JSON object. +Note that each JSON object may include multiple events (high server activity) or no events (heartbeating to keep the connection open). | Method | Path | Produces | @@ -38,6 +38,7 @@ by default, requiring a management token. | `Deployment` | `namespace:read-job` | | `Evaluation` | `namespace:read-job` | | `Node` | `node:read` | +| `Service` | `namespace:read-job` | ### Parameters @@ -47,7 +48,7 @@ by default, requiring a management token. - `namespace` `(string: "default")` - Specifies the target namespace to filter on. Specifying `*` includes all namespaces for event types that support - namespaces. If you specify all namespaces (`*`) you'll either need a management + namespaces. If you specify all namespaces (`*`) you'll either need a management token, or an ACL Policy that explicitly applies to all namespaces (`*`). - `topic` `(topic:filter_key: "*:*")` - Specifies a topic to subscribe to and @@ -72,6 +73,7 @@ by default, requiring a management token. | Deployment | Deployment | | Node | Node | | NodeDrain | Node | +| Service | Service Registrations | ### Event Types @@ -97,6 +99,8 @@ by default, requiring a management token. | NodeDrain | | NodeEvent | | PlanResult | +| ServiceRegistration | +| ServiceDeregistration | ### Sample Request diff --git a/website/content/api-docs/services.mdx b/website/content/api-docs/services.mdx new file mode 100644 index 000000000..ca883557b --- /dev/null +++ b/website/content/api-docs/services.mdx @@ -0,0 +1,158 @@ +--- +layout: api +page_title: Services - HTTP API +description: >- + The /service endpoints are used to query and interact with Nomad services. +--- + +# Service HTTP API + +The `/service` endpoints are used to query and interact with Nomad services. + +## List Services + +This endpoint lists all the currently available Nomad services. + +| Method | Path | Produces | +| ------ | -------------- | ------------------ | +| `GET` | `/v1/services` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api-docs#blocking-queries) and +[required ACLs](/api-docs#acls). + +| Blocking Queries | ACL Required | +| ---------------- | -------------------- | +| `YES` | `namespace:read-job` | + +### Sample Request + +```shell-session +$ curl \ + https://localhost:4646/v1/services +``` + +```shell-session +$ curl \ + https://localhost:4646/v1/services?namespace=* +``` + +### Sample Response + +```json +[ + { + "Namespace": "default", + "Services": [ + { + "ServiceName": "example-cache-redis", + "Tags": [ + "cache", + "db" + ] + } + ] + } +] +``` + +## Read Service + +This endpoint reads a specific service. + +| Method | Path | Produces | +| ------ | ------------------------ | ------------------ | +| `GET` | `/service/:service_name` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api-docs#blocking-queries), [consistency modes](/api-docs#consistency-modes) and +[required ACLs](/api-docs#acls). + +| Blocking Queries | Consistency Modes | ACL Required | +| ---------------- | ----------------- | -------------------- | +| `YES` | `all` | `namespace:read-job` | + +### Parameters + +- `:service_name` `(string: )` - Specifies the service name. This is + specified as part of the path. + +### Sample Request + +```shell-session +$ curl \ + https://localhost:4646/v1/service/example-cache-redis +``` + +### Sample Response + +```json +[ + { + "Address": "127.0.0.1", + "AllocID": "177160af-26f6-619f-9c9f-5e46d1104395", + "CreateIndex": 14, + "Datacenter": "dc1", + "ID": "_nomad-task-177160af-26f6-619f-9c9f-5e46d1104395-redis-example-cache-redis-db", + "JobID": "example", + "ModifyIndex": 24, + "Namespace": "default", + "NodeID": "7406e90b-de16-d118-80fe-60d0f2730cb3", + "Port": 29702, + "ServiceName": "example-cache-redis", + "Tags": [ + "db", + "cache" + ] + }, + { + "Address": "127.0.0.1", + "AllocID": "ba731da0-6df9-9858-ef23-806e9758a899", + "CreateIndex": 35, + "Datacenter": "dc1", + "ID": "_nomad-task-ba731da0-6df9-9858-ef23-806e9758a899-redis-example-cache-redis-db", + "JobID": "example", + "ModifyIndex": 35, + "Namespace": "default", + "NodeID": "7406e90b-de16-d118-80fe-60d0f2730cb3", + "Port": 27232, + "ServiceName": "example-cache-redis", + "Tags": [ + "db", + "cache" + ] + } +] +``` + +## Delete Service Registration + +This endpoint is used to delete an individual service registration. + +| Method | Path | Produces | +| -------- | --------------------------------------- | ------------------ | +| `DELETE` | `/v1/service/:service_name/:service_id` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api-docs#blocking-queries) and +[required ACLs](/api-docs#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ---------------------- | +| `NO` | `namespace:submit-job` | + +### Parameters + +- `:service_name` `(string: )` - Specifies the service name. This is + specified as part of the path. + +- `:service_id` `(string: )` - Specifies the service ID. This is + specified as part of the path. + +### Sample Request + +```shell-session +$ curl \ + --request DELETE \ + https://localhost:4646/v1/service/example-cache-redis/_nomad-task-ba731da0-6df9-9858-ef23-806e9758a899-redis-example-cache-redis-db +``` diff --git a/website/content/docs/commands/service/delete.mdx b/website/content/docs/commands/service/delete.mdx new file mode 100644 index 000000000..dac630038 --- /dev/null +++ b/website/content/docs/commands/service/delete.mdx @@ -0,0 +1,39 @@ +--- +layout: docs +page_title: 'Commands: service delete' +description: | + The service delete command is used to delete Nomad service registrations. +--- + +# Command: service delete + +The `service delete` command is used to delete an individual service +registration. This command is not expected to be used during normal +operations of Nomad and should be used with caution. + +~> Service commands are new in Nomad 1.3. + +## Usage + +```plaintext +nomad service delete [options] +``` + +The `service delete` command requires two arguments, the name of the service +and the ID of the individual registration to delete. + +When ACLs are enabled, this command requires a token with the `submit-job` +capability for the service registration namespace. + +## General Options + +@include 'general_options.mdx' + +## Examples + +Delete a service registration: + +```shell-session +$ nomad service delete delete example-cache-redis _nomad-task-a831f7f2-4c01-39dc-c742-f2b8ca178a49-redis-example-cache-redis-db +Successfully deleted service registration +``` diff --git a/website/content/docs/commands/service/index.mdx b/website/content/docs/commands/service/index.mdx new file mode 100644 index 000000000..39ebc8ccb --- /dev/null +++ b/website/content/docs/commands/service/index.mdx @@ -0,0 +1,27 @@ +--- +layout: docs +page_title: 'Commands: service' +description: | + The service command is used to interact with the service API. +--- + +# Command: service + +The `service` command is used to interact with the service API. + +~> Service commands are new in Nomad 1.3. + +## Usage + +Usage: `nomad service [options]` + +Run `nomad service -h` for help on that subcommand. The following +subcommands are available: + +- [`service delete`][servicedelete] - Deregister a registered service +- [`service info`][serviceinfo] - Display an individual Nomad service registration +- [`service list`][servicelist] - Display all registered Nomad services + +[servicedelete]: /docs/commands/service/delete +[serviceinfo]: /docs/commands/service/info +[servicelist]: /docs/commands/service/list diff --git a/website/content/docs/commands/service/info.mdx b/website/content/docs/commands/service/info.mdx new file mode 100644 index 000000000..6ff9e2bb9 --- /dev/null +++ b/website/content/docs/commands/service/info.mdx @@ -0,0 +1,73 @@ +--- +layout: docs +page_title: 'Commands: service info' +description: | + The service info command is used to read the specified Nomad registered + service by name. +--- + +# Command: service info + +The `service info` command is used to read the specified Nomad registered +service by name. + +~> Service commands are new in Nomad 1.3. + +## Usage + +```plaintext +nomad service info [options] +``` + +The `service info` command requires a single argument, a service name. + +When ACLs are enabled, this command requires a token with the `read-job` +capability for the service's namespace. + +## General Options + +@include 'general_options.mdx' + +## Info Options + +- `-json` : Output the service registrations in JSON format. + +- `-t` : Format and display the service registrations using a Go template. + +- `verbose` : Display full information. + +## Examples + +View the information of a specific service: + +```shell-session +$ nomad service info example-cache-redis +Job ID Address Tags Node ID Alloc ID +example 127.0.0.1:22686 [db,cache] 7406e90b 5f0730ca +example 127.0.0.1:25854 [db,cache] 7406e90b a831f7f2 +``` + +View the verbose information of a specific service: + +```shell-session +$ nomad service info -verbose example-cache-redis +ID = _nomad-task-5f0730ca-b055-52ac-f56e-358f3f7412f6-redis-example-cache-redis-db +Service Name = example-cache-redis +Namespace = default +Job ID = example +Alloc ID = 5f0730ca-b055-52ac-f56e-358f3f7412f6 +Node ID = 7406e90b-de16-d118-80fe-60d0f2730cb3 +Datacenter = dc1 +Address = 127.0.0.1:22686 +Tags = [db,cache] + +ID = _nomad-task-a831f7f2-4c01-39dc-c742-f2b8ca178a49-redis-example-cache-redis-db +Service Name = example-cache-redis +Namespace = default +Job ID = example +Alloc ID = a831f7f2-4c01-39dc-c742-f2b8ca178a49 +Node ID = 7406e90b-de16-d118-80fe-60d0f2730cb3 +Datacenter = dc1 +Address = 127.0.0.1:25854 +Tags = [db,cache] +``` diff --git a/website/content/docs/commands/service/list.mdx b/website/content/docs/commands/service/list.mdx new file mode 100644 index 000000000..7c09b6acb --- /dev/null +++ b/website/content/docs/commands/service/list.mdx @@ -0,0 +1,56 @@ +--- +layout: docs +page_title: 'Commands: service list' +description: | + The service list command is used to list the registered Nomad services. +--- + +# Command: service list + +The `service list` command is used to list the registered Nomad services. + +~> Service commands are new in Nomad 1.3. + +## Usage + +```plaintext +nomad service list [options] +``` + +The `service list` command requires no arguments. + +When ACLs are enabled, this command requires a token with the `read-job` +capability for the namespace being queried. + +The command supports the wildcard namespace identifier. Any namespaces that +the token does not have access to will have its services filtered from the +results. + +## General Options + +@include 'general_options.mdx' + +## List Options + +- `-json`: Output the services in its JSON format. + +- `-t`: Format and display the services using a Go template. + +## Examples + +List all services in the `default` namespace: + +```shell-session +$ nomad service list +Service Name Tags +example-cache-redis [cache,db] +``` + +List all services in all namespaces: + +```shell-session +$ nomad service list -namespace="*" +Service Name Namespace Tags +example-cache-redis default [cache,db] +platform-example-cache-redis platform [] +``` diff --git a/website/content/docs/job-specification/service.mdx b/website/content/docs/job-specification/service.mdx index 2f8b5c129..e886e97cc 100644 --- a/website/content/docs/job-specification/service.mdx +++ b/website/content/docs/job-specification/service.mdx @@ -15,10 +15,11 @@ description: |- ]} /> -The `service` stanza instructs Nomad to register a service with Consul. This -section of the documentation will discuss the configuration, but please also -read the [Nomad service discovery documentation][service-discovery] for more -detailed information about the integration. +The `service` stanza instructs Nomad to register a service with the specified +provider; Nomad or Consul. This section of the documentation will discuss the +configuration, but please also read the +[Nomad service discovery documentation][service-discovery] for more detailed +information about the external integrations. ```hcl job "docs" { @@ -70,13 +71,21 @@ Connect][connect] integration. ## `service` Parameters +- `provider` `(string: "consul")` - Specifies the service registration provider + to use for service registrations. Valid options are either `consul` or + `nomad`. All services within a single task group must utilise the same + provider value. + - `check` ([Check](#check-parameters): nil) - Specifies a health check associated with the service. This can be specified multiple times to - define multiple checks for the service. At this time, Nomad supports the - `grpc`, `http`, `script`1, and `tcp` checks. + define multiple checks for the service. Only available where + `provider = "consul"`. + + At this time, the Consul integration supports the `grpc`, `http`, + `script`1, and `tcp` checks. - `connect` - Configures the [Consul Connect][connect] integration. Only - available on group services. + available on group services and where `provider = "consul"`. - `name` `(string: "--")` - Specifies the name this service will be advertised as in Consul. If not supplied, this will default to the @@ -130,7 +139,7 @@ Connect][connect] integration. to make changes to the tags of a service without having those changes be overwritten by Consul's anti-entropy mechanism. See Consul [documentation](https://www.consul.io/docs/internals/anti-entropy#enable-tag-override) - for more information. + for more information. Only available where `provider = "consul"`. - `address_mode` `(string: "auto")` - Specifies which address (host, alloc or driver-specific) this service should advertise. This setting is supported in @@ -163,14 +172,15 @@ Connect][connect] integration. than one task in the task group. - `meta` ([Meta][]: nil) - Specifies a key-value map that annotates - the Consul service with user-defined metadata. + the Consul service with user-defined metadata. Only available where + `provider = "consul"`. - `canary_meta` ([Meta][]: nil) - Specifies a key-value map that annotates the Consul service with user-defined metadata when the service is part of an allocation that is currently a canary. Once the canary is promoted, the registered meta will be updated to those specified in the `meta` parameter. If this is not supplied, the registered meta will be set to - that of the `meta` parameter. + that of the `meta` parameter. Only available where `provider = "consul"`. - `on_update` `(string: "require_healthy")` - Specifies how checks should be evaluated when determining deployment health (including a job's initial @@ -348,29 +358,31 @@ service { ## `service` Lifecycle -Nomad manages registering, updating, and deregistering services with Consul. It -is important to understand when each of these steps happens and how they can be -customized. +Nomad manages registering, updating, and deregistering services with the +service provider. It is important to understand when each of these steps +happens and how they can be customized. **Registration**: Nomad will register `group` services and checks _before_ starting any tasks. Services and checks for a specific `task` are registered _after_ the task has started. **Updating**: If a service or check definition is updated, Nomad will update -the service in Consul as well. Consul is updated without restarting a task. +the service in the provider as well. This update happens without restarting a +task. **Deregistering**: If a running task with a service stanza exits, the services -and checks are immediately deregistered from Consul without delay. If however -Nomad needs to kill a running task, the task is killed in the following order: +and checks are immediately deregistered from the provider without delay. If, +however, Nomad needs to kill a running task, the task is killed in the +following order: -1. Immediately remove the services and checks from Consul. This stops new +1. Immediately remove the services and checks from the provider. This stops new traffic from being routed to the task that is being killed. 2. If [`shutdown_delay`][shutdowndelay] is set, wait the configured duration before proceeding to step 3. Setting a [`shutdown_delay`][shutdowndelay] can be useful if the application itself doesn't handle graceful shutdowns based on the [`kill_signal`][killsignal]. The configured delay will provide a - period of time in which the service is no longer registered in Consul, and - thus is not receiving additional requests, but hasn't been signalled to + period of time in which the service is no longer registered in the provider, + and thus is not receiving additional requests, but hasn't been signalled to shutdown. This allows the application time to complete the requests and become idle. 3. Send the [`kill_signal`][killsignal] to the task and wait for the task to @@ -386,7 +398,19 @@ The following examples only show the `service` stanzas. Remember that the ### Basic Service -This example registers a service named "load-balancer" with no health checks. +This example registers a service named "load-balancer" with no health checks +using the Nomad provider: + +```hcl +service { + name = "load-balancer" + port = "lb" + provider = "nomad" +} +``` + +This example registers a service named "load-balancer" with no health checks +using the Consul provider: ```hcl service { @@ -395,8 +419,8 @@ service { } ``` -This example must be accompanied by a [`network`][network] stanza which defines -a static or dynamic port labeled "lb". For example: +These examples must be accompanied by a [`network`][network] stanza which +defines a static or dynamic port labeled "lb". For example: ```hcl network { diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json index a864be853..95efba8cc 100644 --- a/website/data/api-docs-nav-data.json +++ b/website/data/api-docs-nav-data.json @@ -122,6 +122,10 @@ "title": "Sentinel Policies", "path": "sentinel-policies" }, + { + "title": "Services", + "path": "services" + }, { "title": "Status", "path": "status" diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 6ba02c93b..1d01c6787 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -741,6 +741,27 @@ } ] }, + { + "title": "service", + "routes": [ + { + "title": "Overview", + "path": "commands/service" + }, + { + "title": "service delete", + "path": "commands/service/delete" + }, + { + "title": "service info", + "path": "commands/service/info" + }, + { + "title": "service list", + "path": "commands/service/list" + } + ] + }, { "title": "status", "path": "commands/status"