Add static network config documentation (#364)

Signed-off-by: Andrea Mazzotti <[email protected]>
rancher · Aug 14, 2024 · 3d92aaf · 3d92aaf
1 parent ddc30e2
commit 3d92aaf
Show file tree

Hide file tree

Showing 4 changed files with 143 additions and 2 deletions.
diff --git a/docs/networking-static.md b/docs/networking-static.md
@@ -0,0 +1,53 @@
+---
+sidebar_label: Static Configuration
+title: ''
+---
+
+<head>
+  <link rel="canonical" href="https://elemental.docs.rancher.com/networking"/>
+</head>
+
+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:  
+
+<CodeBlock language="yaml" title="99_static_network_config.yaml" showLineNumbers>{YipNmcStaticConfig}</CodeBlock>
+
+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
@@ -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
@@ -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
@@ -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,