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"