github.com/smintz/nomad@v0.8.3/website/source/docs/job-specification/network.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "network Stanza - Job Specification" 4 sidebar_current: "docs-job-specification-network" 5 description: |- 6 The "network" stanza specifies the networking requirements for the task, 7 including the minimum bandwidth and port allocations. 8 --- 9 10 # `network` Stanza 11 12 <table class="table table-bordered table-striped"> 13 <tr> 14 <th width="120">Placement</th> 15 <td> 16 <code>job -> group -> task -> resources -> **network**</code> 17 </td> 18 </tr> 19 </table> 20 21 The `network` stanza specifies the networking requirements for the task, 22 including the minimum bandwidth and port allocations. When scheduling jobs in 23 Nomad they are provisioned across your fleet of machines along with other jobs 24 and services. Because you don't know in advance what host your job will be 25 provisioned on, Nomad will provide your tasks with network configuration when 26 they start up. 27 28 Note that this document only applies to services that want to _listen_ on a 29 port. Batch jobs or services that only make outbound connections do not need to 30 allocate ports, since they will use any available interface to make an outbound 31 connection. 32 33 34 ```hcl 35 job "docs" { 36 group "example" { 37 task "server" { 38 resources { 39 network { 40 mbits = 200 41 port "http" {} 42 port "https" {} 43 port "lb" { 44 static = "8889" 45 } 46 } 47 } 48 } 49 } 50 } 51 ``` 52 53 ## `network` Parameters 54 55 - `mbits` `(int: 10)` - Specifies the bandwidth required in MBits. 56 57 - `port` <code>([Port](#port-parameters): nil)</code> - Specifies a TCP/UDP port 58 allocation and can be used to specify both dynamic ports and reserved ports. 59 60 ### `port` Parameters 61 62 - `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 63 for `system` or specialized jobs like load balancers. 64 65 The label assigned to the port is used to identify the port in service 66 discovery, and used in the name of the environment variable that indicates 67 which port your application should bind to. For example: 68 69 ```hcl 70 port "foo" {} 71 ``` 72 73 When the task starts, it will be passed the following environment variables: 74 75 - <tt>NOMAD_IP_foo</tt> - The IP to bind on for the given port label. 76 - <tt>NOMAD_PORT_foo</tt> - The port value for the given port label. 77 - <tt>NOMAD_ADDR_foo</tt> - A combined <tt>ip:port</tt> that can be used for convenience. 78 79 The label of the port is just text - it has no special meaning to Nomad. 80 81 ## `network` Examples 82 83 The following examples only show the `network` stanzas. Remember that the 84 `network` stanza is only valid in the placements listed above. 85 86 ### Bandwidth 87 88 This example specifies a resource requirement of 1 Gbit in bandwidth: 89 90 ```hcl 91 network { 92 mbits = 1000 93 } 94 ``` 95 96 ### Dynamic Ports 97 98 This example specifies a dynamic port allocation for the port labeled "http". 99 Dynamic ports are allocated in a range from `20000` to `32000`. 100 101 Most services run in your cluster should use dynamic ports. This means that the 102 port will be allocated dynamically by the scheduler, and your service will have 103 to read an environment variable to know which port to bind to at startup. 104 105 ```hcl 106 task "example" { 107 resources { 108 network { 109 port "http" {} 110 port "https" {} 111 } 112 } 113 } 114 ``` 115 116 ```hcl 117 network { 118 port "http" {} 119 } 120 ``` 121 122 ### Static Ports 123 124 This example specifies a static port allocation for the port labeled "lb". Static 125 ports bind your job to a specific port on the host they' are placed on. Since 126 multiple services cannot share a port, the port must be open in order to place 127 your task. 128 129 ```hcl 130 network { 131 port "lb" { 132 static = 6539 133 } 134 } 135 ``` 136 137 ### Mapped Ports 138 139 Some drivers (such as [Docker][docker-driver] and [QEMU][qemu-driver]) allow you 140 to map ports. A mapped port means that your application can listen on a fixed 141 port (it does not need to read the environment variable) and the dynamic port 142 will be mapped to the port in your container or virtual machine. 143 144 ```hcl 145 task "example" { 146 driver = "docker" 147 148 config { 149 port_map = { 150 http = 8080 151 } 152 } 153 154 resources { 155 network { 156 port "http" {} 157 } 158 } 159 } 160 ``` 161 162 The above example is for the Docker driver. The service is listening on port 163 `8080` inside the container. The driver will automatically map the dynamic port 164 to this service. 165 166 When the task is started, it is passed an additional environment variable named 167 `NOMAD_HOST_PORT_http` which indicates the host port that the HTTP service is 168 bound to. 169 170 171 [docker-driver]: /docs/drivers/docker.html "Nomad Docker Driver" 172 [qemu-driver]: /docs/drivers/qemu.html "Nomad QEMU Driver"