github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/job-specification/network.mdx

---
layout: docs
page_title: network Stanza - Job Specification
description: |-
  The "network" stanza specifies the networking requirements for the task group,
  including networking mode and port allocations.
---

# `network` Stanza

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

The `network` stanza specifies the networking requirements for the task group,
including the network mode and port allocations. When scheduling jobs in
Nomad they are provisioned across your fleet of machines along with other jobs
and services. Because you don't know in advance what host your job will be
provisioned on, Nomad will provide your tasks with network configuration when
they start up.

Note that this document only applies to services that want to _listen_ on a
port. Batch jobs or services that only make outbound connections do not need to
allocate ports, since they will use any available interface to make an outbound
connection.

```hcl
job "docs" {
  group "example" {
    network {
      port "http" {}
      port "https" {}
      port "lb" {
        static = 8889
      }
    }
  }
}
```

### Network modes

When the `network` stanza is defined with `bridge` as the networking mode,
all tasks in the task group share the same network namespace. This is a prerequisite for
[Consul Connect](/docs/integrations/consul-connect). Tasks running within a
network namespace are not visible to applications outside the namespace on the same host.
This allows [Connect][]-enabled applications to bind only to localhost within the shared network stack,
and use the proxy for ingress and egress traffic.

To use `bridge` mode, you must have the [reference CNI
plugins](https://github.com/containernetworking/plugins/releases/tag/v1.0.0)
installed at the location specified by the client's [`cni_path`]
configuration. These plugins are used to create the bridge network and
configure the appropriate iptables rules.

Network modes are only supported in allocations running on Linux clients.
All other operating systems use the `host` networking mode.

## `network` Parameters

- `mbits` <code>([_deprecated_](/docs/upgrade/upgrade-specific#nomad-0-12-0) int: 10)</code> - Specifies the bandwidth required in MBits.

- `port` <code>([Port](#port-parameters): nil)</code> - Specifies a TCP/UDP port
  allocation and can be used to specify both dynamic ports and reserved ports.

- `mode` `(string: "host")` - Mode of the network. This option is only supported
  on Linux clients. The following modes are available:

  - `none` - Task group will have an isolated network without any network interfaces.
  - `bridge` - Task group will have an isolated network namespace with an interface
    that is bridged with the host. Note that bridge networking is only
    currently supported for the `docker`, `exec`, `raw_exec`, and `java` task
    drivers.
  - `host` - Each task will join the host network namespace and a shared network
    namespace is not created. This matches the current behavior in Nomad 0.9.
  - `cni/<cni network name>` - Task group will have an isolated network namespace
    with the network configured by CNI.

- `hostname` `(string: "")` - The hostname assigned to the network namespace. This
  is currently only supported using the [Docker driver][docker-driver] and when the
  [mode](#mode) is set to [`bridge`](#bridge). This parameter supports
  [interpolation](/docs/runtime/interpolation).

- `dns` <code>([DNSConfig](#dns-parameters): nil)</code> - Sets the DNS configuration
  for the allocations. By default all DNS configuration is inherited from the client host.
  DNS configuration is only supported on Linux clients at this time.

### `port` Parameters

- `static` `(int: nil)` - Specifies the static TCP/UDP port to allocate. If omitted, a
  dynamic port is chosen. We **do not recommend** using static ports, except
  for `system` or specialized jobs like load balancers.
- `to` `(string:nil)` - Applicable when using "bridge" mode to configure port
  to map to inside the task's network namespace. Omitting this field or
  setting it to `-1` sets the mapped port equal to the dynamic port allocated
  by the scheduler. The `NOMAD_PORT_<label>` environment variable will contain
  the `to` value.
- `host_network` `(string:nil)` - Designates the host network name to use when allocating
  the port. When port mapping the host port will only forward traffic to the matched host
  network address.

The label assigned to the port is used to identify the port in service
discovery, and used in the name of the environment variable that indicates
which port your application should bind to. For example:

```hcl
port "foo" {}
```

When the task starts, it will be passed the following environment variables:

- <tt>NOMAD_IP_foo</tt> - The IP to bind on for the given port label.
- <tt>NOMAD_PORT_foo</tt> - The port value for the given port label.
- <tt>NOMAD_ADDR_foo</tt> - A combined <tt>ip:port</tt> that can be used for convenience.

The label of the port is just text - it has no special meaning to Nomad.

## `dns` Parameters

- `servers` `(array<string>: nil)` - Sets the DNS nameservers the allocation uses for name resolution.
- `searches` `(array<string>: nil)` - Sets the search list for hostname lookup
- `options` `(array<string>: nil)` - Sets internal resolver variables.

These parameters support [interpolation](/docs/runtime/interpolation).

## `network` Examples

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

### Dynamic Ports

This example specifies a dynamic port allocation for the port labeled "http".
Dynamic ports are allocated in a range from `20000` to `32000`.

Most services run in your cluster should use dynamic ports. This means that the
port will be allocated dynamically by the scheduler, and your service will have
to read an environment variable to know which port to bind to at startup.

```hcl
group "example" {
  network {
    port "http" {}
    port "https" {}
  }
}
```

```hcl
network {
  port "http" {}
}
```

### Static Ports

This example specifies a static port allocation for the port labeled "lb". Static
ports bind your job to a specific port on the host they' are placed on. Since
multiple services cannot share a port, the port must be open in order to place
your task.

```hcl
network {
  port "lb" {
    static = 6539
  }
}
```

### Mapped Ports

Some drivers (such as [Docker][docker-driver] and [QEMU][qemu-driver]) allow you
to map ports. A mapped port means that your application can listen on a fixed
port (it does not need to read the environment variable) and the dynamic port
will be mapped to the port in your container or virtual machine.

```hcl
group "app" {
  network {
    port "http" {
      to = 8080
    }
  }

  task "example" {
    driver = "docker"

    config {
      ports = ["http"]
    }
  }
}
```

The above example is for the Docker driver. The service is listening on port
`8080` inside the container. The driver will automatically map the dynamic port
to this service.

When the task is started, it is passed an additional environment variable named
`NOMAD_HOST_PORT_http` which indicates the host port that the HTTP service is
bound to.

### Bridge Mode

Bridge mode allows compatible tasks to share a networking stack and interfaces. Nomad
can then do port mapping without relying on individual task drivers to implement port
mapping configuration.

The following example is a group level network stanza that uses bridge mode
and port mapping.

```hcl
network {
  mode = "bridge"
  port "http" {
    static = 9002
    to     = 9002
  }
}
```

Using bridge mode can result in failing outbound network requests on hosts that have
[firewalld](https://firewalld.org) enabled. This includes most RHEL-based Linux distributions
like CentOS, Rocky Linux or Oracle Linux. One solution for firewalld to allow network
requsts coming from Nomad jobs is to mark the `nomad` bridge interface as trusted.

```shell-session
$ sudo firewall-cmd --zone=trusted --add-interface=nomad
$ sudo firewall-cmd --zone=trusted --add-interface=nomad --permanent
```

It is neccessary to restart the affected jobs afterwards for them to be able to access
the network. Further details can be found in Docker's documentation under [Docker and iptables](https://docs.docker.com/network/iptables/#integration-with-firewalld).

### DNS

The following example configures the allocation to use Google's DNS resolvers 8.8.8.8 and 8.8.4.4.

```hcl
network {
  dns {
    servers = ["8.8.8.8", "8.8.4.4"]
  }
}
```

### Container Network Interface (CNI)

Nomad supports CNI by fingerprinting each node for [CNI network configurations](https://github.com/containernetworking/cni/blob/v0.8.0/SPEC.md#network-configuration).
These are associated to the node by the `name` field of the CNI configuration.
The `name` can then be used when setting the network `mode` field in the form of `cni/<name>`.

As an example if the following CNI configuration was on a node the proceeding network stanza could be used.

```json
{
  "cniVersion": "0.3.1",
  "name": "mynet",
  "plugins": [
    {
      "type": "ptp",
      "ipMasq": true,
      "ipam": {
        "type": "host-local",
        "subnet": "172.16.30.0/24",
        "routes": [
          {
            "dst": "0.0.0.0/0"
          }
        ]
      }
    },
    {
      "type": "portmap",
      "capabilities": { "portMappings": true }
    }
  ]
}
```

```hcl
network {
  mode = "cni/mynet"
  port "http" {
    to = 8080
  }
}
```

The Nomad client will build the correct [capabilities arguments](https://github.com/containernetworking/cni/blob/v0.8.0/CONVENTIONS.md#well-known-capabilities) for the portmap plugin based on the defined port stanzas.

### Host Networks

In some cases a port should only be allocated to a specific interface or address on the host.
The `host_network` field of a port will constrain port allocation to a single named host network.
If `host_network` is set for a port, Nomad will schedule the allocations on a node which has defined a `host_network` with the given name.
If not set the "default" host network is used which is commonly the address with a default route associated with it.

When Nomad does port mapping for ports with a defined `host_network`, the port mapping rule will use the host address as the destination address.

```hcl
network {
  mode = "bridge"

  # define a port to use for public https traffic
  port "https" {
    static       = 443
    to           = 8080
    host_network = "public"
  }
  # define a port that is only exposed to private traffic
  port "admin" {
    to           = 9000
    host_network = "private"
  }
}
```

### Limitations

- Only one `network` stanza can be specified, when it is defined at the task group level.
- Only the `NOMAD_PORT_<label>` and `NOMAD_HOST_PORT_<label>` environment
  variables are set for group network ports.

[docker-driver]: /docs/drivers/docker 'Nomad Docker Driver'
[qemu-driver]: /docs/drivers/qemu 'Nomad QEMU Driver'
[connect]: /docs/job-specification/connect 'Nomad Consul Connect Integration'
[`cni_path`]: /docs/configuration/client#cni_path