301 lines
9.4 KiB
Plaintext
301 lines
9.4 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: network Stanza - Job Specification
|
|
sidebar_title: network
|
|
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.
|
|
|
|
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.
|
|
|
|
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` 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. 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.
|
|
|
|
- `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. `-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.
|
|
|
|
## `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" {}
|
|
}
|
|
|
|
task "example" {
|
|
driver = "docker"
|
|
|
|
config {
|
|
port_map = {
|
|
http = 8080
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
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
|
|
}
|
|
}
|
|
```
|
|
|
|
### 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.
|
|
|
|
*Host networks does not currently support task based mapped ports such as the Docker driver's `port_map` configuration.
|
|
|
|
|
|
```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'
|