From 3d92aafe10fcede12339500cfaec1bad0f719511 Mon Sep 17 00:00:00 2001 From: Andrea Mazzotti Date: Wed, 14 Aug 2024 17:57:31 +0200 Subject: [PATCH] Add static network config documentation (#364) Signed-off-by: Andrea Mazzotti --- docs/networking-static.md | 53 ++++++++++++++ docs/networking.md | 3 +- examples/network/yip-nmc-static-config.yaml | 78 +++++++++++++++++++++ sidebars.js | 11 ++- 4 files changed, 143 insertions(+), 2 deletions(-) create mode 100644 docs/networking-static.md create mode 100644 examples/network/yip-nmc-static-config.yaml diff --git a/docs/networking-static.md b/docs/networking-static.md new file mode 100644 index 000000000..6e13e9eac --- /dev/null +++ b/docs/networking-static.md @@ -0,0 +1,53 @@ +--- +sidebar_label: Static Configuration +title: '' +--- + + + + + +import YipNmcStaticConfig from "!!raw-loader!@site/examples/network/yip-nmc-static-config.yaml" + +## Static Network with nm-configurator + +The `nm-configurator` [per node configuration](https://github.com/suse-edge/nm-configurator?tab=readme-ov-file#per-node-configurations) can be used to statically assign IP addresses to individual machines, based on the NIC's MAC addresses. + +This solution does not require a remote IPAM provider, but requires the user to maintain mapping between known MAC addresses and IP Addresses. + +In this example, we are going to customize an Elemental image, and include a [yip config](./cloud-config-reference.md#configuration-syntax) that will apply the static network config early at boot. + +First we can create the yip config: + +{YipNmcStaticConfig} + +Second, we can extend an Elemental image to include this configuration in `/system/oem`. +Any Elemental powered OS, where [Elemental Toolkit](https://github.com/rancher/elemental-toolkit) is running, will evaluate any config in this directory when executing any stage. + +```docker showLineNumbers +# The version of Elemental to modify +FROM registry.suse.com/suse/sl-micro/6.0/baremetal-os-container:latest + +# Install the static network config +COPY 99_static_network_config.yaml /system/oem/99_static_network_config.yaml + +# IMPORTANT: /etc/os-release is used for versioning/upgrade. +ARG IMAGE_REPO=norepo +ARG IMAGE_TAG=latest +RUN \ + sed -i -e "s/^IMAGE_REPO=.*/IMAGE_REPO=\"${IMAGE_REPO}\"/g" /etc/os-release && \ + sed -i -e "s/^IMAGE_TAG=.*/IMAGE_TAG=\"${IMAGE_TAG}\"/g" /etc/os-release && \ + sed -i -e "s/^IMAGE=.*/IMAGE=\"${IMAGE_REPO}:${IMAGE_TAG}\"/g" /etc/os-release + +# IMPORTANT: it is good practice to recreate the initrd and re-apply `elemental-init` +RUN elemental init --force immutable-rootfs,grub-config,dracut-config,cloud-config-essentials,elemental-setup +``` + +You can now [build an ISO container](./custom-images.md#create-a-custom-bootable-installation-iso) from this OS container image. For more information on how to customize Elemental images, please refer to the [documentation](./custom-images.md). +Once the ISO container is published on your registry, you can refer to it in the [SeedImage](./seedimage-reference.md) like any other Elemental distributed ISO image. + +Note that the static network config will be evaluated when the installation media boots, then it will be installed on the system, and finally it will follow the entire machine lifecycle. +This also applies to [upgrades](./upgrade.md), given that the static configuration is always included in upgrade images. +None of the machine phases, from the very first boot, will require a DHCP server. + +Since the configuration is static, be aware that any change (for example to add new nodes) will require you to rebuild and republish your custom images, and rebuild the `SeedImage` too to create a fresh installation media. diff --git a/docs/networking.md b/docs/networking.md index 0c7ec9a76..36240d042 100644 --- a/docs/networking.md +++ b/docs/networking.md @@ -1,5 +1,5 @@ --- -sidebar_label: Declarative Networking +sidebar_label: IPAM Driven Networking title: '' --- @@ -11,6 +11,7 @@ import RegistrationWithNetwork from "!!raw-loader!@site/examples/network/machine import RegistrationWithNetworkNmc from "!!raw-loader!@site/examples/network/machineregistration-nmc.yaml" import RegistrationWithNetworkNmstate from "!!raw-loader!@site/examples/network/machineregistration-nmstate.yaml" import RegistrationWithNetworkNmconnections from "!!raw-loader!@site/examples/network/machineregistration-nmconnections.yaml" +import YipNmcStaticConfig from "!!raw-loader!@site/examples/network/yip-nmc-static-config.yaml" ## Network configuration with Elemental diff --git a/examples/network/yip-nmc-static-config.yaml b/examples/network/yip-nmc-static-config.yaml new file mode 100644 index 000000000..ad1b8801b --- /dev/null +++ b/examples/network/yip-nmc-static-config.yaml @@ -0,0 +1,78 @@ +name: Static nm-configurator config +stages: + initramfs: + - directories: + - path: /tmp/nmc/static/desired-states + permissions: 448 + owner: 0 + group: 0 + - path: /tmp/nmc/static/network-config + permissions: 448 + owner: 0 + group: 0 + files: + - path: /tmp/nmc/static/desired-states/node1.yaml + permissions: 384 + owner: 0 + group: 0 + content: | + dns-resolver: + config: + server: + - 192.168.122.1 + search: [] + routes: + config: + - destination: 0.0.0.0/0 + next-hop-interface: enp1s0 + next-hop-address: 192.168.122.1 + metric: 150 + table-id: 254 + interfaces: + - name: enp1s0 + type: ethernet + state: up + mac-address: 52:54:00:45:14:c5 + ipv4: + address: + - ip: 192.168.122.150 + prefix-length: 24 + enabled: true + ipv6: + enabled: false + encoding: "" + ownerstring: "" + - path: /tmp/nmc/static/desired-states/node2.yaml + permissions: 384 + owner: 0 + group: 0 + content: | + dns-resolver: + config: + server: + - 192.168.122.1 + search: [] + routes: + config: + - destination: 0.0.0.0/0 + next-hop-interface: enp1s0 + next-hop-address: 192.168.122.1 + metric: 150 + table-id: 254 + interfaces: + - name: enp1s0 + type: ethernet + state: up + mac-address: 52:54:00:3a:ae:3b + ipv4: + address: + - ip: 192.168.122.151 + prefix-length: 24 + enabled: true + ipv6: + enabled: false + encoding: "" + ownerstring: "" + commands: + - nmc generate --config-dir /tmp/nmc/static/desired-states --output-dir /tmp/nmc/static/network-config + - nmc apply --config-dir /tmp/nmc/static/network-config diff --git a/sidebars.js b/sidebars.js index b6d0acf86..e459b1ec9 100644 --- a/sidebars.js +++ b/sidebars.js @@ -74,7 +74,16 @@ const sidebars = { "label-templates-random", ] }, - "networking", + { + "type": "category", + "collapsible": true, + "collapsed": true, + "label": "Declarative Networking", + "items": [ + "networking", + "networking-static", + ] + }, { "type": "category", "collapsible": true,