kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-04 17:35:43 +03:00
Code Issues Packages Projects Releases Wiki Activity

website: add initial website docs for Nomad service discovery. (#12456)

Browse Source
This commit is contained in:
James Rasell
2022-04-06 18:51:14 +02:00
committed by GitHub
parent 8f331fe7b3
commit 9e20a34d75
9 changed files with 431 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
website/content/api-docs/events.mdx
View File

@@ -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

158
website/content/api-docs/services.mdx Normal file
View File

@@ -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: <required>)` - 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: <required>)` - Specifies the service name. This is
specified as part of the path.
- `:service_id` `(string: <required>)` - 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
```

39
website/content/docs/commands/service/delete.mdx Normal file
View File

@@ -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. <em>This command is not expected to be used during normal
operations of Nomad and should be used with caution.</em>
~> Service commands are new in Nomad 1.3.
## Usage
```plaintext
nomad service delete [options] <service_name> <service_id>
```
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
```

27
website/content/docs/commands/service/index.mdx Normal file
View File

@@ -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 <subcommand> [options]`
Run `nomad service <subcommand> -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

73
website/content/docs/commands/service/info.mdx Normal file
View File

@@ -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] <service_name>
```
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]
```

56
website/content/docs/commands/service/list.mdx Normal file
View File

@@ -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 []
```

68
website/content/docs/job-specification/service.mdx
View File

@@ -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` <code>([Check](#check-parameters): nil)</code> - 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`<sup><small>1</small></sup>, 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`<sup><small>1</small></sup>, 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: "<job>-<group>-<task>")` - 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` <code>([Meta][]: nil)</code> - 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` <code>([Meta][]: nil)</code> - 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 {

4
website/data/api-docs-nav-data.json
View File

@@ -122,6 +122,10 @@
"title": "Sentinel Policies",
"path": "sentinel-policies"
},
{
"title": "Services",
"path": "services"
},
{
"title": "Status",
"path": "status"

21
website/data/docs-nav-data.json
View File

@@ -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"