open-nomad/website/pages/docs/job-specification/group.mdx

260 lines
8.8 KiB
Plaintext
Raw Normal View History

---
2020-02-06 23:45:31 +00:00
layout: docs
page_title: group Stanza - Job Specification
sidebar_title: group
description: |-
The "group" stanza defines a series of tasks that should be co-located on the
same Nomad client. Any task within a group will be placed on the same client.
---
# `group` Stanza
2020-02-06 23:45:31 +00:00
<Placement groups={['job', 'group']} />
The `group` stanza defines a series of tasks that should be co-located on the
same Nomad client. Any [task][] within a group will be placed on the same
client.
```hcl
job "docs" {
group "example" {
# ...
}
}
```
## `group` Parameters
2016-10-28 03:01:11 +00:00
- `constraint` <code>([Constraint][]: nil)</code> -
This can be provided multiple times to define additional constraints.
- `affinity` <code>([Affinity][]: nil)</code> - This can be provided
2020-02-06 23:45:31 +00:00
multiple times to define preferred placement criteria.
2019-01-24 20:58:26 +00:00
- `spread` <code>([Spread][spread]: nil)</code> - This can be provided
multiple times to define criteria for spreading allocations across a
node attribute or metadata. See the
2020-02-06 23:45:31 +00:00
[Nomad spread reference](/docs/job-specification/spread) for more details.
2019-01-24 20:58:26 +00:00
- `count` `(int)` - Specifies the number of instances that should be running
under for this group. This value must be non-negative. This defaults to the
`min` value specified in the [`scaling`](/docs/job-specification/scaling)
block, if present; otherwise, this defaults to `1`.
- `ephemeral_disk` <code>([EphemeralDisk][]: nil)</code> - Specifies the
ephemeral disk requirements of the group. Ephemeral disks can be marked as
sticky and support live data migrations.
2016-10-28 03:01:11 +00:00
- `meta` <code>([Meta][]: nil)</code> - Specifies a key-value map that annotates
with user-defined metadata.
- `migrate` <code>([Migrate][]: nil)</code> - Specifies the group strategy for
migrating off of draining nodes. Only service jobs with a count greater than
1 support migrate stanzas.
- `network` <code>([Network][]: &lt;optional&gt;)</code> - Specifies the network
requirements and configuration, including static and dynamic port allocations,
for the group.
- `reschedule` <code>([Reschedule][]: nil)</code> - Allows to specify a
rescheduling strategy. Nomad will then attempt to schedule the task on another
node if any of the group allocation statuses become "failed".
- `restart` <code>([Restart][]: nil)</code> - Specifies the restart policy for
all tasks in this group. If omitted, a default policy exists for each job
2016-10-28 03:01:11 +00:00
type, which can be found in the [restart stanza documentation][restart].
- `service` <code>([Service][]: nil)</code> - Specifies integrations with
[Consul][] for service discovery. Nomad automatically registers each service when an allocation
is started and de-registers them when the allocation is destroyed.
- `shutdown_delay` `(string: "0s")` - Specifies the duration to wait when
stopping a group's tasks. The delay occurs between Consul deregistration
and sending each task a shutdown signal. Ideally, services would fail
healthchecks once they receive a shutdown signal. Alternatively
2020-11-27 07:37:44 +00:00
`shutdown_delay` may be set to give in-flight requests time to complete
before shutting down. A group level `shutdown_delay` will run regardless
if there are any defined group services. In addition, tasks may have their
2020-02-06 23:45:31 +00:00
own [`shutdown_delay`](/docs/job-specification/task#shutdown_delay)
which waits between deregistering task services and stopping the task.
- `stop_after_client_disconnect` `(string: "")` - Specifies a duration
after which a Nomad client that cannot communicate with the servers
will stop allocations based on this task group. By default, a client
will not stop an allocation until explicitly told to by a server. A
client that fails to heartbeat to a server within the
[`heartbeat_grace`] window and any allocations running on it will be
marked "lost" and Nomad will schedule replacement
allocations. However, these replaced allocations will continue to
run on the non-responsive client; an operator may desire that these
replaced allocations are also stopped in this case — for example,
allocations requiring exclusive access to an external resource. When
specified, the Nomad client will stop them after this duration. The
Nomad client process must be running for this to occur.
2020-02-06 23:45:31 +00:00
- `task` <code>([Task][]: &lt;required&gt;)</code> - Specifies one or more tasks to run
within this group. This can be specified multiple times, to add a task as part
of the group.
2016-11-02 22:29:17 +00:00
- `vault` <code>([Vault][]: nil)</code> - Specifies the set of Vault policies
required by all tasks in this group. Overrides a `vault` block set at the
`job` level.
2016-11-02 22:14:49 +00:00
- `volume` <code>([Volume][]: nil)</code> - Specifies the volumes that are
required by tasks within the group.
## `group` Examples
2016-10-31 00:41:03 +00:00
The following examples only show the `group` stanzas. Remember that the
`group` stanza is only valid in the placements listed above.
### Specifying Count
This example specifies that 5 instances of the tasks within this group should be
running:
```hcl
group "example" {
count = 5
}
```
2016-10-28 03:01:11 +00:00
### Tasks with Constraint
2016-10-28 03:01:11 +00:00
This example shows two abbreviated tasks with a constraint on the group. This
will restrict the tasks to 64-bit operating systems.
```hcl
group "example" {
constraint {
2017-05-02 00:36:20 +00:00
attribute = "${attr.cpu.arch}"
value = "amd64"
}
2016-10-28 03:01:11 +00:00
task "cache" {
# ...
}
task "server" {
# ...
}
}
```
### Metadata
This example show arbitrary user-defined metadata on the group:
```hcl
group "example" {
meta {
"my-key" = "my-value"
}
}
```
### Network
This example shows network constraints as specified in the [network][] stanza
which uses the `bridge` networking mode, dynamically allocates two ports, and
statically allocates one port:
```hcl
group "example" {
network {
mode = "bridge"
port "http" {}
port "https" {}
port "lb" {
static = "8889"
}
}
}
```
### Service Discovery
This example creates a service in Consul. To read more about service discovery
in Nomad, please see the [Nomad service discovery documentation][service_discovery].
```hcl
group "example" {
network {
port "api" {}
}
service {
name = "example"
port = "api"
tags = ["default"]
check {
type = "tcp"
interval = "10s"
timeout = "2s"
}
}
task "api" { ... }
}
```
### Stop After Client Disconnect
This example shows how `stop_after_client_disconnect` interacts with
other stanzas. For the `first` group, after the default 10 second
[`heartbeat_grace`] window expires and 90 more seconds passes, the
server will reschedule the allocation. The client will wait 90 seconds
before sending a stop signal (`SIGTERM`) to the `first-task`
task. After 15 more seconds because of the task's `kill_timeout`, the
client will send `SIGKILL`. The `second` group does not have
`stop_after_client_disconnect`, so the server will reschedule the
allocation after the 10 second [`heartbeat_grace`] expires. It will
not be stopped on the client, regardless of how long the client is out
of touch.
Note that if the server's clocks are not closely synchronized with
each other, the server may reschedule the group before the client has
stopped the allocation. Operators should ensure that clock drift
between servers is as small as possible.
Note also that a group using this feature will be stopped on the
client if the Nomad server cluster fails, since the client will be
unable to contact any server in that case. Groups opting in to this
feature are therefore exposed to an additional runtime dependency and
potential point of failure.
```hcl
group "first" {
stop_after_client_disconnect = "90s"
task "first-task" {
kill_timeout = "15s"
}
}
group "second" {
task "second-task" {
kill_timeout = "5s"
}
}
```
2020-02-06 23:45:31 +00:00
[task]: /docs/job-specification/task 'Nomad task Job Specification'
[job]: /docs/job-specification/job 'Nomad job Job Specification'
[constraint]: /docs/job-specification/constraint 'Nomad constraint Job Specification'
[spread]: /docs/job-specification/spread 'Nomad spread Job Specification'
[affinity]: /docs/job-specification/affinity 'Nomad affinity Job Specification'
[ephemeraldisk]: /docs/job-specification/ephemeral_disk 'Nomad ephemeral_disk Job Specification'
[`heartbeat_grace`]: /docs/configuration/server#heartbeat_grace
2020-02-06 23:45:31 +00:00
[meta]: /docs/job-specification/meta 'Nomad meta Job Specification'
[migrate]: /docs/job-specification/migrate 'Nomad migrate Job Specification'
[network]: /docs/job-specification/network 'Nomad network Job Specification'
2020-02-06 23:45:31 +00:00
[reschedule]: /docs/job-specification/reschedule 'Nomad reschedule Job Specification'
[restart]: /docs/job-specification/restart 'Nomad restart Job Specification'
[service]: /docs/job-specification/service 'Nomad service Job Specification'
[service_discovery]: /docs/integrations/consul-integration#service-discovery 'Nomad Service Discovery'
2020-02-06 23:45:31 +00:00
[vault]: /docs/job-specification/vault 'Nomad vault Job Specification'
[volume]: /docs/job-specification/volume 'Nomad volume Job Specification'