open-nomad/website/content/docs/job-specification/service.mdx

---
layout: docs
page_title: service Stanza - Job Specification
description: |-
  The "service" stanza instructs Nomad to register the task as a service using
  the Nomad or Consul service discovery integration.
---

# `service` Stanza

<Placement
  groups={[
    ['job', 'group', 'service'],
    ['job', 'group', 'task', 'service'],
  ]}
/>

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" {
  group "example" {
    task "server" {
      service {
        tags = ["leader", "mysql"]

        port = "db"

        provider = "consul"

        meta {
          meta = "for your service"
        }

        check {
          type     = "tcp"
          port     = "db"
          interval = "10s"
          timeout  = "2s"
        }

        check {
          type     = "http"
          name     = "app_health"
          path     = "/health"
          interval = "20s"
          timeout  = "5s"

          check_restart {
            limit = 3
            grace = "90s"
            ignore_warnings = false
          }
        }
      }
    }
  }
}
```

This section of the documentation only cover the job file fields and stanzas
for service discovery. For more details on using Nomad with Consul please see
the [Consul integration documentation][service-discovery].

Nomad 0.10 also allows specifying the `service` stanza at the task group level.
This enables services in the same task group to opt into [Consul
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]: nil)</code> - Specifies a health
  check associated with the service. This can be specified multiple times to
  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 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
  name of the job, group, and task concatenated together with a dash, like
  `"docs-example-server"`. Each service must have a unique name within the
  cluster. Names must adhere to [RFC-1123
  §2.1](https://tools.ietf.org/html/rfc1123#section-2) and are limited to
  alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be less than 64
  characters in length.

  In addition to the standard [Nomad interpolation][interpolation], the
  following keys are also available:

  - `${JOB}` - the name of the job
  - `${GROUP}` - the name of the group
  - `${TASK}` - the name of the task
  - `${BASE}` - shorthand for `${JOB}-${GROUP}-${TASK}`

  Validation of the name occurs in two parts. When the job is registered, an initial validation pass checks that
  the service name adheres to RFC-1123 §2.1 and the length limit, excluding any variables requiring interpolation.
  Once the client receives the service and all interpretable values are available, the service name will be
  interpolated and revalidated. This can cause certain service names to pass validation at submit time but fail
  at runtime.

- `port` `(string: <optional>)` - Specifies the port to advertise for this
  service. The value of `port` depends on which [`address_mode`](#address_mode)
  is being used:

  - `alloc` - Advertise the mapped `to` value of the labeled port and the allocation address.
    If a `to` value is not set, the port falls back to using the allocated host port. The `port`
    field may be a numeric port or a port label specified in the same group's network stanza.

  - `driver` - Advertise the port determined by the driver (e.g. Docker).
    The `port` may be a numeric port or a port label specified in the driver's
    `ports` field.

  - `host` - Advertise the host port for this service. `port` must match a port
    _label_ specified in the [`network`][network] stanza.

- `tags` `(array<string>: [])` - Specifies the list of tags to associate with
  this service. If this is not supplied, no tags will be assigned to the service
  when it is registered.

- `canary_tags` `(array<string>: [])` - Specifies the list of tags to associate with
  this service when the service is part of an allocation that is currently a
  canary. Once the canary is promoted, the registered tags will be updated to
  those specified in the `tags` parameter. If this is not supplied, the
  registered tags will be equal to that of the `tags` parameter.

- `enable_tag_override` `(bool: false)` - Enables users of Consul's Catalog API
  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/concepts/anti-entropy#enable-tag-override)
  for more information. Only available where `provider = "consul"`.

- `address` `(string: <optional>)` - Specifies a custom address to advertise in
  Consul or Nomad service registration. If set, `address_mode` must be in `auto`
  mode. Useful with interpolation - for example to advertise the public IP address
  of an AWS EC2 instance set this to `${attr.unique.platform.aws.public-ipv4}`.

- `tagged_addresses` `(map<string|string>` - Specifies custom [tagged addresses][tagged_addresses] to
  advertise in the Consul service registration. Only available where `provider = "consul"`.

- `address_mode` `(string: "auto")` - Specifies which address (host, alloc or
  driver-specific) this service should advertise. See [below for
  examples.](#using-driver-address-mode) Valid options are:

  - `alloc` - For allocations which create a network namespace, this address mode
    uses the IP address inside the namespace. Can only be used with "bridge" and "cni"
    [networking modes][network_mode]. A numeric port may be specified for situations
    where no port mapping is necessary. This mode can only be set for services which
    are defined in a "group" block.

  - `auto` - Allows the driver to determine whether the host or driver address
    should be used. Defaults to `host` and only implemented by Docker. If you
    use a Docker network plugin such as weave, Docker will automatically use
    its address.

  - `driver` - Use the IP specified by the driver, and the port specified in a
    port map. A numeric port may be specified since port maps aren't required
    by all network plugins. Useful for advertising SDN and overlay network
    addresses. Task will fail if driver network cannot be determined. Only
    implemented for Docker. This mode can only be set for services
    which are defined in a "task" block.

  - `host` - Use the host IP and port.

- `task` `(string: "")` - Specifies the name of the Nomad task associated with
  this service definition. Only available on group services. Must be set if this
  service definition represents a Consul Connect-native service and there is more
  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. 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. 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
  deployment). This allows job submitters to define certain checks as readiness
  checks, progressing a deployment even if the Service's checks are not yet
  healthy. Checks inherit the Service's value by default. The check status is
  not altered in Consul and is only used to determine the check's health during
  an update.

  - `require_healthy` - In order for Nomad to consider the check healthy during
    an update it must report as healthy.

  - `ignore_warnings` - If a Service Check reports as warning, Nomad will treat
    the check as healthy. The Check will still be in a warning state in Consul.

  - `ignore` - Any status will be treated as healthy.

  ~> **Caveat:** `on_update` is only compatible with certain
  [`check_restart`][check_restart_stanza] configurations. `on_update = "ignore_warnings"` requires that `check_restart.ignore_warnings = true`.
  `check_restart` can however specify `ignore_warnings = true` with `on_update = "require_healthy"`. If `on_update` is set to `ignore`, `check_restart` must
  be omitted entirely.


## `service` Lifecycle

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 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 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 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 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
   exit. The task should use this time to gracefully drain and finish any
   existing requests.
4. If the task has not exited after the [`kill_timeout`][killtimeout], Nomad
   will force kill the application.

## `service` Examples

The following examples only show the `service` stanzas. Remember that the
`service` stanza is only valid in the placements listed above.

### Basic Service

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 {
  name = "load-balancer"
  port = "lb"
}
```

These examples must be accompanied by a [`network`][network] stanza which
defines a static or dynamic port labeled "lb". For example:

```hcl
network {
  port "lb" {}
}
```


### Using Driver Address Mode

The [Docker](/docs/drivers/docker#network_mode) driver supports the `driver`
setting for the `address_mode` parameter in both `service` and `check` stanzas.
The driver address mode allows advertising and health checking the IP and port
assigned to a task by the driver. This way, if you're using a network plugin like
Weave with Docker, you can advertise the Weave address in Consul instead of the
host's address.

For example if you were running the example Redis job in an environment with
Weave but Consul was running on the host you could use the following
configuration:

```hcl
job "example" {
  datacenters = ["dc1"]

  group "cache" {
    network {
      port "db" {
        to = 6379
      }
    }

    task "redis" {
      driver = "docker"

      config {
        image = "redis:7"
        network_mode = "weave"
        ports = ["db"]
      }

      resources {
        cpu    = 500 # 500 MHz
        memory = 256 # 256MB
      }

      service {
        name = "weave-redis"
        port = "db"
        check {
          name     = "host-redis-check"
          type     = "tcp"
          interval = "10s"
          timeout  = "2s"
        }
      }
    }
  }
}
```

No explicit `address_mode` required.

Services default to the `auto` address mode. When a Docker network mode other
than `"host"` or `"bridge"` is used, services will automatically advertise the
driver's address (in this case Weave's). The service will advertise the
container's port: 6379.

However since Consul is often run on the host without access to the Weave
network, `check` stanzas default to `host` address mode. The TCP check will run
against the host's IP and the dynamic host port assigned by Nomad.

Note that the `check` still inherits the `service` stanza's `db` port label,
but each will resolve the port label according to their address mode.

If Consul has access to the Weave network the job could be configured like
this:

```hcl
job "example" {
  datacenters = ["dc1"]
  group "cache" {

    task "redis" {
      driver = "docker"

      config {
        image = "redis:7"
        network_mode = "weave"
        # No port map required.
      }

      resources {
        cpu    = 500 # 500 MHz
        memory = 256 # 256MB
      }

      service {
        name = "weave-redis"
        port = 6379
        address_mode = "driver"
        check {
          name     = "host-redis-check"
          type     = "tcp"
          interval = "10s"
          timeout  = "2s"
          port     = 6379

          address_mode = "driver"
        }
      }
    }
  }
}
```

In this case Nomad doesn't need to assign Redis any host ports. The `service`
and `check` stanzas can both specify the port number to advertise and check
directly since Nomad isn't managing any port assignments.

### IPv6 Docker containers

The [Docker](/docs/drivers/docker#advertise_ipv6_address) driver supports the
`advertise_ipv6_address` parameter in its configuration.

Services will automatically advertise the IPv6 address when `advertise_ipv6_address`
is used.

Unlike services, checks do not have an `auto` address mode as there's no way
for Nomad to know which is the best address to use for checks. Consul needs
access to the address for any HTTP or TCP checks.

So you have to set `address_mode` parameter in the `check` stanza to `driver`.

For example using `auto` address mode:

```hcl
job "example" {
  datacenters = ["dc1"]
  group "cache" {

    network {
      port "db" {
        to = 6379
      }
    }


    task "redis" {
      driver = "docker"

      config {
        image = "redis:7"
        advertise_ipv6_address = true
        ports = ["db"]
      }

      resources {
        cpu    = 500 # 500 MHz
        memory = 256 # 256MB
      }

      service {
        name = "ipv6-redis"
        port = "db"
        check {
          name     = "ipv6-redis-check"
          type     = "tcp"
          interval = "10s"
          timeout  = "2s"
          port     = "db"
          address_mode = "driver"
        }
      }
    }
  }
}
```

Or using `address_mode=driver` for `service` and `check` with numeric ports:

```hcl
job "example" {
  datacenters = ["dc1"]

  group "cache" {

    task "redis" {
      driver = "docker"

      config {
        image = "redis:7"
        advertise_ipv6_address = true
        # No port map required.
      }

      resources {
        cpu    = 500 # 500 MHz
        memory = 256 # 256MB
      }

      service {
        name = "ipv6-redis"
        port = 6379
        address_mode = "driver"
        check {
          name     = "ipv6-redis-check"
          type     = "tcp"
          interval = "10s"
          timeout  = "2s"
          port     = 6379
          address_mode = "driver"
        }
      }
    }
  }
}
```

The `service` and `check` stanzas can both specify the port number to
advertise and check directly since Nomad isn't managing any port assignments.

---

[check]: /docs/job-specification/check
[check_restart_stanza]: /docs/job-specification/check_restart
[consul_grpc]: https://www.consul.io/api/agent/check#grpc
[consul_passfail]: https://www.consul.io/docs/agent/checks#success-failures-before-passing-critical
[service-discovery]: /docs/integrations/consul-integration#service-discovery 'Nomad Service Discovery'
[interpolation]: /docs/runtime/interpolation 'Nomad Runtime Interpolation'
[network]: /docs/job-specification/network 'Nomad network Job Specification'
[qemu]: /docs/drivers/qemu 'Nomad QEMU Driver'
[restart_stanza]: /docs/job-specification/restart 'restart stanza'
[connect]: /docs/job-specification/connect 'Nomad Consul Connect Integration'
[type]: /docs/job-specification/service#type
[shutdowndelay]: /docs/job-specification/task#shutdown_delay
[killsignal]: /docs/job-specification/task#kill_signal
[killtimeout]: /docs/job-specification/task#kill_timeout
[service_task]: /docs/job-specification/service#task-1
[network_mode]: /docs/job-specification/network#mode
[on_update]: /docs/job-specification/service#on_update
[tagged_addresses]: https://www.consul.io/docs/discovery/services#tagged-addresses