From 5167bae0d57f8ed8120a61611aea148f04eac819 Mon Sep 17 00:00:00 2001 From: Nick Ethier Date: Thu, 23 Jul 2020 09:18:59 -0400 Subject: [PATCH] website: remove usage of task network stanza (#8498) * website: remove usage of task network stanza and add documentation for group network and service stanzas * docs: fix broken link in client config * Update website/pages/docs/job-specification/group.mdx Co-authored-by: Seth Hoenig * Update website/pages/docs/job-specification/group.mdx Co-authored-by: Seth Hoenig Co-authored-by: Seth Hoenig --- website/pages/docs/configuration/client.mdx | 2 +- .../pages/docs/job-specification/group.mdx | 57 +++++++++++++ .../pages/docs/job-specification/network.mdx | 80 ++++++++----------- .../docs/job-specification/resources.mdx | 35 +------- website/pages/docs/job-specification/task.mdx | 6 +- 5 files changed, 96 insertions(+), 84 deletions(-) diff --git a/website/pages/docs/configuration/client.mdx b/website/pages/docs/configuration/client.mdx index 64f693a45..40eea277f 100644 --- a/website/pages/docs/configuration/client.mdx +++ b/website/pages/docs/configuration/client.mdx @@ -384,7 +384,7 @@ The `host_network` stanza is used to register additional host networks with the node that can be used when port mapping. The key of the stanza corresponds to the name of the network used in the -[`host_network`](/docs/job-specification/network#host-network). +[`host_network`](/docs/job-specification/network#host-networks). ```hcl client { diff --git a/website/pages/docs/job-specification/group.mdx b/website/pages/docs/job-specification/group.mdx index 644a977a1..7a51438d6 100644 --- a/website/pages/docs/job-specification/group.mdx +++ b/website/pages/docs/job-specification/group.mdx @@ -52,6 +52,10 @@ job "docs" { migrating off of draining nodes. Only service jobs with a count greater than 1 support migrate stanzas. +- `network` ([Network][]: <optional>) - Specifies the network + requirements and configuration, including static and dynamic port allocations, + for the group. + - `reschedule` ([Reschedule][]: nil) - 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". @@ -60,6 +64,10 @@ job "docs" { all tasks in this group. If omitted, a default policy exists for each job type, which can be found in the [restart stanza documentation][restart]. +- `service` ([Service][]: nil) - 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 @@ -145,6 +153,52 @@ group "example" { } ``` +### 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 @@ -196,7 +250,10 @@ group "second" { [`heartbeat_grace`]: /docs/configuration/server/#heartbeat_grace [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' [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' [vault]: /docs/job-specification/vault 'Nomad vault Job Specification' [volume]: /docs/job-specification/volume 'Nomad volume Job Specification' diff --git a/website/pages/docs/job-specification/network.mdx b/website/pages/docs/job-specification/network.mdx index 4a3723d17..200c78a52 100644 --- a/website/pages/docs/job-specification/network.mdx +++ b/website/pages/docs/job-specification/network.mdx @@ -3,10 +3,8 @@ layout: docs page_title: network Stanza - Job Specification sidebar_title: network description: |- - The "network" stanza specifies the networking requirements for the task, - including the minimum bandwidth and port allocations. The network stanza - can be specified at the task group level to enable all tasks in the task - group to share the same network namespace. + The "network" stanza specifies the networking requirements for the task group, + including networking mode and port allocations. --- # `network` Stanza @@ -17,15 +15,14 @@ description: |- ]} /> -The `network` stanza specifies the networking requirements for the task, -including the minimum bandwidth and port allocations. When scheduling jobs in +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. -Nomad 0.10 enables support for the `network` stanza at the task group level. When -the `network` stanza is defined at the group level with `bridge` as the networking mode, +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. @@ -40,16 +37,11 @@ connection. ```hcl job "docs" { group "example" { - task "server" { - resources { - network { - mbits = 200 - port "http" {} - port "https" {} - port "lb" { - static = 8889 - } - } + network { + port "http" {} + port "https" {} + port "lb" { + static = 8889 } } } @@ -58,8 +50,6 @@ job "docs" { ## `network` Parameters -- `mbits` `(int: 10)` - Specifies the bandwidth required in MBits. - - `port` ([Port](#port-parameters): nil) - Specifies a TCP/UDP port allocation and can be used to specify both dynamic ports and reserved ports. @@ -120,16 +110,6 @@ The label of the port is just text - it has no special meaning to Nomad. The following examples only show the `network` stanzas. Remember that the `network` stanza is only valid in the placements listed above. -### Bandwidth - -This example specifies a resource requirement of 1 Gbit in bandwidth: - -```hcl -network { - mbits = 1000 -} -``` - ### Dynamic Ports This example specifies a dynamic port allocation for the port labeled "http". @@ -140,12 +120,10 @@ 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 -task "example" { - resources { - network { - port "http" {} - port "https" {} - } +group "example" { + network { + port "http" {} + port "https" {} } } ``` @@ -179,18 +157,18 @@ 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 -task "example" { - driver = "docker" - - config { - port_map = { - http = 8080 - } +group "app" { + network { + port "http" {} } - resources { - network { - port "http" {} + task "example" { + driver = "docker" + + config { + port_map = { + http = 8080 + } } } } @@ -206,6 +184,10 @@ 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. @@ -277,9 +259,15 @@ The Nomad client will build the correct [capabilities arguments](https://github. ### 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 { diff --git a/website/pages/docs/job-specification/resources.mdx b/website/pages/docs/job-specification/resources.mdx index a0f6d5fdf..c92b6033b 100644 --- a/website/pages/docs/job-specification/resources.mdx +++ b/website/pages/docs/job-specification/resources.mdx @@ -4,7 +4,7 @@ page_title: resources Stanza - Job Specification sidebar_title: resources description: |- The "resources" stanza describes the requirements a task needs to execute. - Resource requirements include memory, network, cpu, and more. + Resource requirements include memory, cpu, and more. --- # `resources` Stanza @@ -12,7 +12,7 @@ description: |- The `resources` stanza describes the requirements a task needs to execute. -Resource requirements include memory, network, CPU, and more. +Resource requirements include memory, CPU, and more. ```hcl job "docs" { @@ -22,14 +22,6 @@ job "docs" { cpu = 100 memory = 256 - network { - mbits = 100 - port "http" {} - port "ssh" { - static = 22 - } - } - device "nvidia/gpu" { count = 2 } @@ -45,9 +37,6 @@ job "docs" { - `memory` `(int: 300)` - Specifies the memory required in MB -- `network` ([Network][]: <optional>) - Specifies the network - requirements, including static and dynamic port allocations. - - `device` ([Device][]: <optional>) - Specifies the device requirements. This may be repeated to request multiple device types. @@ -67,25 +56,6 @@ resources { } ``` -### Network - -This example shows network constraints as specified in the [network][] stanza -which require 1 Gbit of bandwidth, dynamically allocates two ports, and -statically allocates one port: - -```hcl -resources { - network { - mbits = 1000 - port "http" {} - port "https" {} - port "lb" { - static = "8889" - } - } -} -``` - ### Devices This example shows a device constraints as specified in the [device][] stanza @@ -99,5 +69,4 @@ resources { } ``` -[network]: /docs/job-specification/network 'Nomad network Job Specification' [device]: /docs/job-specification/device 'Nomad device Job Specification' diff --git a/website/pages/docs/job-specification/task.mdx b/website/pages/docs/job-specification/task.mdx index ffcb8189b..90cb88933 100644 --- a/website/pages/docs/job-specification/task.mdx +++ b/website/pages/docs/job-specification/task.mdx @@ -77,7 +77,7 @@ job "docs" { with user-defined metadata. - `resources` ([Resources][]: <required>) - Specifies the minimum - resource requirements such as RAM, CPU and network. + resource requirements such as RAM, CPU and devices. - `service` ([Service][]: nil) - Specifies integrations with [Consul][] for service discovery. Nomad automatically registers when a task @@ -130,9 +130,7 @@ task "server" { } resources { - network { - mbits = 250 - } + cpu = 20 } } ```