From b72c79ebb9b5e053230a1c19996e9dc4fa505577 Mon Sep 17 00:00:00 2001 From: Luiz Aoqui Date: Fri, 6 Jan 2023 11:47:10 -0500 Subject: [PATCH] docs: networking (#15358) Co-authored-by: Charlie Voiselle <464492+angrycub@users.noreply.github.com> --- website/content/docs/concepts/plugins/cni.mdx | 64 ++++ website/content/docs/configuration/client.mdx | 4 +- .../docs/job-specification/network.mdx | 6 + website/content/docs/networking/cni.mdx | 217 ++++++++++++ website/content/docs/networking/index.mdx | 331 ++++++++++++++++++ .../docs/networking/service-discovery.mdx | 144 ++++++++ .../content/docs/networking/service-mesh.mdx | 162 +++++++++ website/content/docs/runtime/environment.mdx | 4 - website/content/partials/envvars.mdx | 106 +++--- website/data/docs-nav-data.json | 25 ++ website/public/img/networking/bridge.png | Bin 0 -> 143244 bytes .../public/img/networking/docker_bridge.png | Bin 0 -> 309318 bytes .../public/img/networking/port_mapping.png | Bin 0 -> 119895 bytes website/public/img/nomad-bridge-network.png | Bin 0 -> 38077 bytes 14 files changed, 1011 insertions(+), 52 deletions(-) create mode 100644 website/content/docs/concepts/plugins/cni.mdx create mode 100644 website/content/docs/networking/cni.mdx create mode 100644 website/content/docs/networking/index.mdx create mode 100644 website/content/docs/networking/service-discovery.mdx create mode 100644 website/content/docs/networking/service-mesh.mdx create mode 100644 website/public/img/networking/bridge.png create mode 100644 website/public/img/networking/docker_bridge.png create mode 100644 website/public/img/networking/port_mapping.png create mode 100644 website/public/img/nomad-bridge-network.png diff --git a/website/content/docs/concepts/plugins/cni.mdx b/website/content/docs/concepts/plugins/cni.mdx new file mode 100644 index 000000000..695074bc9 --- /dev/null +++ b/website/content/docs/concepts/plugins/cni.mdx @@ -0,0 +1,64 @@ +--- +layout: docs +page_title: Network Plugins +description: Learn how Nomad manages custom user-specified network configurations. +--- + +# Network plugins + +Nomad has built-in support for scheduling compute resources such as +CPU, memory, and networking. Nomad's network plugin support extends +this to allow scheduling tasks with purpose-created or specialty network +configurations. Network plugins are third-party plugins that conform to the +[Container Network Interface (CNI)][cni_spec] specification. + +Network plugins need to be installed and configured on each client. The [Nomad +installation instructions][nomad_install] recommend installing the [CNI +reference plugins][cni_ref] because certain Nomad networking features, like +`bridge` network mode and Consul service mesh, leverage them to provide an +operating-system agnostic interface to configure workload networking. + +Custom networking in Nomad is accomplished with a combination of CNI plugin +binaries and CNI configuration files. + +## CNI plugins + +Spec-compliant plugins should work with Nomad, however, it's possible a plugin +vendor has implemented their plugin to make non-standard API calls, or it is +otherwise non-compliant with the CNI specification. In those situations the +plugin may not function correctly in a Nomad environment. You should verify +plugin compatibility with Nomad before deploying in production. + +CNI plugins are installed and configured on a per-client basis. Nomad consults +the path given in the client's [`cni_path`][] to find CNI plugin executables. + +## CNI configuration files + +CNI defines a network configuration format for administrators. It contains +directives for both the orchestrator and the plugins to consume. +At plugin execution time, this configuration format is interpreted by the +runtime and transformed in to a form to be passed to the plugins. + +Nomad reads the following extensions from the [`cni_config_dir`][]— +`/opt/cni/config` by default: + +* `.conflist` files are loaded as [network + configurations][cni_spec_net_config] that contain a list of plugin + configurations. + +* `.conf` and `.json` files are loaded as individual [plugin + configurations][cni_spec_plugin_config] for a specific network. + +## Further reading + +You can read more about how Nomad uses CNI plugins in the [CNI section of the +Nomad Networking documentation](/docs/networking/cni). + +[3rd_party_cni]: https://www.cni.dev/docs/#3rd-party-plugins +[`cni_config_dir`]: /docs/configuration/client#cni_config_dir +[`cni_path`]: /docs/configuration/client#cni_path +[cni_ref]: https://github.com/containernetworking/plugins +[cni_spec]: https://www.cni.dev/docs/spec/ +[cni_spec_net_config]: https://github.com/containernetworking/cni/blob/main/SPEC.md#configuration-format +[cni_spec_plugin_config]: https://github.com/containernetworking/cni/blob/main/SPEC.md#plugin-configuration-objects +[nomad_install]: https://developer.hashicorp.com/nomad/tutorials/get-started/get-started-install#post-installation-steps diff --git a/website/content/docs/configuration/client.mdx b/website/content/docs/configuration/client.mdx index 827e3361c..0a2fe0ebf 100644 --- a/website/content/docs/configuration/client.mdx +++ b/website/content/docs/configuration/client.mdx @@ -133,7 +133,9 @@ client { - `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. Filenames should use the `.conflist` extension. + CNI networks. Filenames should use the `.conflist` extension. Filenames with + the `.conf` or `.json` extensions are loaded as individual plugin + configuration. - `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 diff --git a/website/content/docs/job-specification/network.mdx b/website/content/docs/job-specification/network.mdx index 23eaa6766..89428e608 100644 --- a/website/content/docs/job-specification/network.mdx +++ b/website/content/docs/job-specification/network.mdx @@ -54,6 +54,11 @@ configure the appropriate iptables rules. Network modes are only supported in allocations running on Linux clients. All other operating systems use the `host` networking mode. +~> **Warning:** To prevent any type of external access when using `bridge` + network mode make sure to bind your workloads to the loopback interface + only. Refer to the [Bridge networking][docs_networking_bridge] documentation + for more information. + ## `network` Parameters - `mbits` ([_deprecated_](/docs/upgrade/upgrade-specific#nomad-0-12-0) int: 10) - Specifies the bandwidth required in MBits. @@ -320,6 +325,7 @@ network { - Only the `NOMAD_PORT_