docs: add CNI and host_network docs (#8391)
Co-authored-by: Seth Hoenig <shoenig@hashicorp.com>
This commit is contained in:
Nick Ethier
GitHub
parent
f023df7b68
commit
119ece09a0
|
|
@ -632,6 +632,7 @@ func convertClientConfig(agentConfig *Config) (*clientconfig.Config, error) {
|
|||
|
||||
// Setup networking configuration
|
||||
conf.CNIPath = agentConfig.Client.CNIPath
|
||||
conf.CNIConfigDir = agentConfig.Client.CNIConfigDir
|
||||
conf.BridgeNetworkName = agentConfig.Client.BridgeNetworkName
|
||||
conf.BridgeNetworkAllocSubnet = agentConfig.Client.BridgeNetworkSubnet
|
||||
|
||||
|
|
|
|||
|
|
@ -277,6 +277,10 @@ type ClientConfig struct {
|
|||
// specified colon delimited
|
||||
CNIPath string `hcl:"cni_path"`
|
||||
|
||||
// CNIConfigDir is the directory where CNI network configuration is located. The
|
||||
// client will use this path when fingerprinting CNI networks.
|
||||
CNIConfigDir string `hcl:"cni_config_dir"`
|
||||
|
||||
// BridgeNetworkName is the name of the bridge to create when using the
|
||||
// bridge network mode
|
||||
BridgeNetworkName string `hcl:"bridge_network_name"`
|
||||
|
|
@ -1535,6 +1539,9 @@ func (a *ClientConfig) Merge(b *ClientConfig) *ClientConfig {
|
|||
if b.CNIPath != "" {
|
||||
result.CNIPath = b.CNIPath
|
||||
}
|
||||
if b.CNIConfigDir != "" {
|
||||
result.CNIConfigDir = b.CNIConfigDir
|
||||
}
|
||||
if b.BridgeNetworkName != "" {
|
||||
result.BridgeNetworkName = b.BridgeNetworkName
|
||||
}
|
||||
|
|
|
|||
|
|
@ -320,6 +320,22 @@ $ curl \
|
|||
"Mode": "",
|
||||
"ReservedPorts": null
|
||||
}
|
||||
],
|
||||
"NodeNetworks": [
|
||||
{
|
||||
"Addresses": [
|
||||
{
|
||||
"Address": "127.0.0.1",
|
||||
"Alias": "default",
|
||||
"Family": "ipv4",
|
||||
"Gateway": "",
|
||||
"ReservedPorts": ""
|
||||
}
|
||||
],
|
||||
"Device": "lo",
|
||||
"MacAddress": "00:00:00:00:00:00",
|
||||
"Mode": "host",
|
||||
}
|
||||
]
|
||||
},
|
||||
"Reserved": {
|
||||
|
|
|
|||
|
|
@ -137,6 +137,9 @@ driver) but will be removed in a future release.
|
|||
CNI plugin discovery. Multiple paths can be searched using colon delimited
|
||||
paths
|
||||
|
||||
- `cni_config_dir` `(string: "/opt/cni/config")` - Sets the directory where CNI
|
||||
network configuration is located. The client will use this path when fingerprinting CNI networks.
|
||||
|
||||
- `bridge_network name` `(string: "nomad")` - Sets the name of the bridge to be
|
||||
created by nomad for allocations running with bridge networking mode on the
|
||||
client.
|
||||
|
|
@ -151,6 +154,9 @@ driver) but will be removed in a future release.
|
|||
- `host_volume` <code>([host_volume](#host_volume-stanza): nil)</code> - Exposes
|
||||
paths from the host as volumes that can be mounted into jobs.
|
||||
|
||||
- `host_network` <code>([host_network](#host_network-stanza): nil)</code> - Registers
|
||||
additional host networks with the node that can be selected when port mapping.
|
||||
|
||||
### `chroot_env` Parameters
|
||||
|
||||
Drivers based on [isolated fork/exec](/docs/drivers/exec) implement file
|
||||
|
|
@ -372,6 +378,35 @@ client {
|
|||
- `read_only` `(bool: false)` - Specifies whether the volume should only ever be
|
||||
allowed to be mounted `read_only`, or if it should be writeable.
|
||||
|
||||
### `host_network` Stanza
|
||||
|
||||
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).
|
||||
|
||||
```hcl
|
||||
client {
|
||||
host_network "public" {
|
||||
cidr = "203.0.113.0/24"
|
||||
reserved_ports = "22,80"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `host_network` Parameters
|
||||
|
||||
- `cidr` `(string: "")` - Specifies a cidr block of addresses to match against.
|
||||
If an address is found on the node that is contained by this cidr block, the
|
||||
host network will be registered with it.
|
||||
|
||||
- `interface` `(string: "")` - Filters searching of addresses to a specific interface.
|
||||
|
||||
- `reserved_ports` `(string: "")` - Specifies a comma-separated list of ports to
|
||||
reserve on all fingerprinted network devices. Ranges can be specified by using
|
||||
a hyphen separating the two inclusive ends.
|
||||
|
||||
## `client` Examples
|
||||
|
||||
### Common Setup
|
||||
|
|
|
|||
|
|
@ -14,7 +14,6 @@ description: |-
|
|||
<Placement
|
||||
groups={[
|
||||
['job', 'group', 'network'],
|
||||
['job', 'group', 'task', 'resources', 'network']
|
||||
]}
|
||||
/>
|
||||
|
||||
|
|
@ -73,6 +72,8 @@ job "docs" {
|
|||
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.
|
||||
|
|
@ -80,10 +81,16 @@ job "docs" {
|
|||
|
||||
### `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
|
||||
- `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.
|
||||
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
|
||||
|
|
@ -224,6 +231,74 @@ network {
|
|||
}
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
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.
|
||||
|
||||
|
||||
```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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue