From 23a3f6c2b0e6bf6f3a08c0376dd4e5c85575ceee Mon Sep 17 00:00:00 2001 From: George Date: Wed, 27 Nov 2024 18:50:34 +0100 Subject: [PATCH 1/5] Adding a Tips and Tricks section to Edge Book and adding the first page for EIB --- asciidoc/edge-book/edge.adoc | 14 ++++- asciidoc/tricks/eib.adoc | 112 +++++++++++++++++++++++++++++++++++ 2 files changed, 125 insertions(+), 1 deletion(-) create mode 100644 asciidoc/tricks/eib.adoc diff --git a/asciidoc/edge-book/edge.adoc b/asciidoc/edge-book/edge.adoc index cbf43eab..68d07bed 100755 --- a/asciidoc/edge-book/edge.adoc +++ b/asciidoc/edge-book/edge.adoc @@ -84,7 +84,7 @@ include::../components/system-upgrade-controller.adoc[leveloffset=+1] include::../components/upgrade-controller.adoc[leveloffset=+1] //-------------------------------------------- -// Third-Party Integration +// How-To Guides //-------------------------------------------- = How-To Guides @@ -98,6 +98,18 @@ include::../guides/metallb-kube-api.adoc[leveloffset=+1] include::../guides/air-gapped-eib-deployments.adoc[leveloffset=+1] +//-------------------------------------------- +// Tips and Tricks +//-------------------------------------------- + += Tips and Tricks + +[partintro] +Tips and tricks for Edge components + +include::../tricks/eib.adoc[leveloffset=+1] + + //-------------------------------------------- // Third-Party Integration //-------------------------------------------- diff --git a/asciidoc/tricks/eib.adoc b/asciidoc/tricks/eib.adoc new file mode 100644 index 00000000..c0b7a102 --- /dev/null +++ b/asciidoc/tricks/eib.adoc @@ -0,0 +1,112 @@ += *Edge Image Builder* + + +.Common +- If you are in a non-Linux OS, then you are running podman via a podman machine. This machine is low on resources on it's default settings and can cause Edge Image Builder to hung for resource intense operations, such as downloading RPMs. + You will need to adjust the resources of the podman machine, either by using Podman Desktop (settings cogwheel -> podman machine edit icon) or directly via the `podman-machine-set` https://docs.podman.io/en/stable/markdown/podman-machine-set.1.html[command] +- To avoid any complications, the image architecture being built must match the one on the system running the Edge Image Builder container, for example if you are using an Apple Silicon MacBook, then you should be building only `aarch64` images: + +---- +image: + arch: aarch64 + imageType: iso + baseImage: slemicro.iso + outputImageName: single-node-k3s.iso +---- + +.Kubernetes +- You can't create an image for a multi node kubernetes cluster without setting up a networking section in your definition file, more information https://github.com/suse-edge/edge-image-builder/blob/main/docs/building-images.md#kubernetes[here] +- You can't create an image for a multi node kubernetes cluster without setting up an `kubernetes.network.apiVIP` parameter (even better add an `kubernetes.network.apiHost` parameter to the setup as well) in the network section of your definition file, more information https://github.com/suse-edge/edge-image-builder/blob/main/docs/building-images.md#kubernetes[here] + +---- +kubernetes: + version: v1.31.1+k3s1 + network: + apiVIP: 192.168.64.11 + apiHost: 192.168.64.11 +---- + +- When creating an image for a multi node kubernetes cluster you need to have a way to declare which machine gets which hostname and if it's a server or agent. While the server/agent configuration is managed in the definition file, for the general networking and setting up proper hostnames for the machines you should add the network configuration files in a networking directory. The easiest approach is to use the https://github.com/suse-edge/nm-configurator[nm-configurator] approach + +---- +Example: +Definition file excerpt: + +--- +kubernetes: + version: v1.30.4+k3s1 + network: + apiVIP: 192.168.64.11 + nodes: + - hostname: node1.suse.com + type: server + initializer: true + - hostname: node2.suse.com + type: agent +--- + +- Network files location: +├── definition.yaml +└── network + ├── node1.suse.com.yaml + └── node2.suse.com.yaml + +node1.suse.com.yaml contents: +--- +routes: + config: + - destination: 0.0.0.0/0 + metric: 100 + next-hop-address: 192.168.64.1 + next-hop-interface: eth0 + table-id: 254 +dns-resolver: + config: + server: + - 192.168.64.1 + - 8.8.8.8 +interfaces: +- name: eth0 + type: ethernet + state: up + mac-address: 34:8A:B1:4B:16:E1 + ipv4: + address: + - ip: 192.168.64.21 + prefix-length: 24 + dhcp: false + enabled: true + ipv6: + enabled: false +--- + +node2.suse.com.yaml contents: +--- +routes: + config: + - destination: 0.0.0.0/0 + metric: 100 + next-hop-address: 192.168.64.1 + next-hop-interface: eth0 + table-id: 254 +dns-resolver: + config: + server: + - 192.168.64.1 + - 8.8.8.8 +interfaces: +- name: eth0 + type: ethernet + state: up + mac-address: 34:8A:B1:4B:16:E2 + ipv4: + address: + - ip: 192.168.64.22 + prefix-length: 24 + dhcp: false + enabled: true + ipv6: + enabled: false +--- + +---- From 1abc24d1fa2f83d171870ab3b715ba14dc09a3c5 Mon Sep 17 00:00:00 2001 From: George Date: Thu, 28 Nov 2024 14:39:07 +0100 Subject: [PATCH 2/5] Updating document as per comments --- asciidoc/components/edge-image-builder.adoc | 3 + asciidoc/tips/eib.adoc | 141 ++++++++++++++++++++ asciidoc/tricks/eib.adoc | 112 ---------------- 3 files changed, 144 insertions(+), 112 deletions(-) create mode 100644 asciidoc/tips/eib.adoc delete mode 100644 asciidoc/tricks/eib.adoc diff --git a/asciidoc/components/edge-image-builder.adoc b/asciidoc/components/edge-image-builder.adoc index 30d06d43..5fa771e7 100644 --- a/asciidoc/components/edge-image-builder.adoc +++ b/asciidoc/components/edge-image-builder.adoc @@ -11,11 +11,14 @@ ifdef::env-github[] endif::[] See the https://github.com/suse-edge/edge-image-builder[Official Repository]. + Edge Image Builder (EIB) is a tool that streamlines the generation of Customized, Ready-to-Boot (CRB) disk images for bootstrapping machines. These images enable the end-to-end deployment of the entire SUSE software stack with a single image. Whilst EIB can create CRB images for all provisioning scenarios, EIB demonstrates a tremendous value in air-gapped deployments with limited or completely isolated networks. +link:../tips/eib.adoc[Read more EIB tips here] + == How does SUSE Edge use Edge Image Builder? diff --git a/asciidoc/tips/eib.adoc b/asciidoc/tips/eib.adoc new file mode 100644 index 00000000..e1b10e2d --- /dev/null +++ b/asciidoc/tips/eib.adoc @@ -0,0 +1,141 @@ += *Edge Image Builder* + + +.Common +- If you are in a non-Linux environment, then you are running `Podman` via a virtual machine. This machine is low on resources on its default settings and can cause `Edge Image Builder` to require unreasonable amount of time for resource intensive operations, such as the RPM resolution process. You will need to adjust the resources of the podman machine, either by using Podman Desktop (settings cogwheel -> podman machine edit icon) or directly via the `podman-machine-set` https://docs.podman.io/en/stable/markdown/podman-machine-set.1.html[command] +- At this point in time, the `Edge Image Builder` is not able to build images in a cross architecture setup, i.e. you have to run it on: + * `aarch64` systems (such as Apple Silicon) to build SL Micro `aarch64` images + * `x86_64` systems (such as Intel) to build SL Micro `x86_64` images. + + +.Kubernetes +- Creating multi node Kubernetes clusters requires adjusting the `kubernetes` section in the definition file to: + * list all server and agent nodes under `kubernetes.nodes` + * set a virtual IP address that would be used for all non-initializer nodes to join the cluster under `kubernetes.network.apiVIP` + * optionally, set an API host to specify a domain address for accessing the cluster under `kubernetes.network.apiHost` +To learn more about this configuration, please refer to the https://github.com/suse-edge/edge-image-builder/blob/main/docs/building-images.md#kubernetes[Kubernetes section docs]. + + +- `Edge Image Builder` relies on the hostnames of the different nodes to determine their Kubernetes type (`server` or `agent`). While this configuration is managed in the definition file, for the general networking setup of the machines we can utilize either DHCP or the https://github.com/suse-edge/nm-configurator[nm-configurator component]. + +.Simple example of image creation for a multi server node RKE2 cluster with Rancher Prime: +**definition file:** + +[source] +apiVersion: 1.1 +image: + arch: aarch64 + imageType: iso + baseImage: SL-Micro.aarch64-6.0-Base-SelfInstall-GM2.install.iso + outputImageName: rke2-ha.iso +operatingSystem: + isoConfiguration: + installDevice: /dev/vda + users: + - username: root + encryptedPassword: # Add an encrypted password [1] + createHomeDir: true + - username: george + encryptedPassword: # Add an encrypted password [1] + sshKeys: + - # Add ssh key for user george + createHomeDir: true + keymap: us + time: + timezone: "Europe/Prague" + kernelArgs: + - foo=bar # dummy value for testing + packages: + packageList: + - lshw + sccRegistrationCode: # Add your SCC Registration Code +kubernetes: + version: v1.30.3+rke2r1 + network: + apiVIP: api.cluster01.edge.suse.com + apiHost: api.cluster01.edge.suse.com + nodes: # Multi server cluster + - hostname: node01.cluster01.edge.suse.com + type: server + initializer: true + - hostname: node02.cluster01.edge.suse.com + type: server + - hostname: node03.cluster01.edge.suse.com + type: server + helm: + charts: + - name: cert-manager + version: 1.16.1 + repositoryName: jetstack + targetNamespace: cert-manager + createNamespace: true + valuesFile: cert-manager.yaml + - name: rancher + version: 2.9.1 + repositoryName: rancher-prime + targetNamespace: cattle-system + createNamespace: true + valuesFile: rancher-prime.yaml + repositories: + - name: jetstack + url: https://charts.jetstack.io + - name: rancher-prime + url: https://charts.rancher.com/server-charts/prime + + + + +[IMPORTANT] +==== +. link:https://documentation.suse.com/suse-edge/3.1/html/edge/quickstart-eib.html#id-configuring-os-users[Create an encrypted password] +. Read more on link:https://github.com/suse-edge/edge-image-builder/blob/main/docs/building-images.md#network-configuration[Network Configuration] +==== + +**network files:** + +[source] +-> file node01.cluster01.edge.suse.com: +interfaces: +- name: eth0 + type: ethernet + state: up + mac-address: 00:00:00:00:00:01 + ipv4: + dhcp: true + enabled: true + ipv6: + enabled: false +-> file node02.cluster01.edge.suse.com: + interfaces: +- name: eth0 + type: ethernet + state: up + mac-address: 00:00:00:00:00:02 + ipv4: + dhcp: true + enabled: true + ipv6: + enabled: false +-> file node03.cluster01.edge.suse.com: +interfaces: +- name: eth0 + type: ethernet + state: up + mac-address: 00:00:00:00:00:03 + ipv4: + dhcp: true + enabled: true + ipv6: + enabled: false + +**helm values files:** + +[source] +-> cert-manager.yaml: +installCRDs: true +-> rancher-prime.yaml: +hostname: "node01.cluster01.edge.suse.com" +replicas: 1 +bootstrapPassword: Admin +global.cattle.psp.enabled: "false" + diff --git a/asciidoc/tricks/eib.adoc b/asciidoc/tricks/eib.adoc deleted file mode 100644 index c0b7a102..00000000 --- a/asciidoc/tricks/eib.adoc +++ /dev/null @@ -1,112 +0,0 @@ -= *Edge Image Builder* - - -.Common -- If you are in a non-Linux OS, then you are running podman via a podman machine. This machine is low on resources on it's default settings and can cause Edge Image Builder to hung for resource intense operations, such as downloading RPMs. - You will need to adjust the resources of the podman machine, either by using Podman Desktop (settings cogwheel -> podman machine edit icon) or directly via the `podman-machine-set` https://docs.podman.io/en/stable/markdown/podman-machine-set.1.html[command] -- To avoid any complications, the image architecture being built must match the one on the system running the Edge Image Builder container, for example if you are using an Apple Silicon MacBook, then you should be building only `aarch64` images: - ----- -image: - arch: aarch64 - imageType: iso - baseImage: slemicro.iso - outputImageName: single-node-k3s.iso ----- - -.Kubernetes -- You can't create an image for a multi node kubernetes cluster without setting up a networking section in your definition file, more information https://github.com/suse-edge/edge-image-builder/blob/main/docs/building-images.md#kubernetes[here] -- You can't create an image for a multi node kubernetes cluster without setting up an `kubernetes.network.apiVIP` parameter (even better add an `kubernetes.network.apiHost` parameter to the setup as well) in the network section of your definition file, more information https://github.com/suse-edge/edge-image-builder/blob/main/docs/building-images.md#kubernetes[here] - ----- -kubernetes: - version: v1.31.1+k3s1 - network: - apiVIP: 192.168.64.11 - apiHost: 192.168.64.11 ----- - -- When creating an image for a multi node kubernetes cluster you need to have a way to declare which machine gets which hostname and if it's a server or agent. While the server/agent configuration is managed in the definition file, for the general networking and setting up proper hostnames for the machines you should add the network configuration files in a networking directory. The easiest approach is to use the https://github.com/suse-edge/nm-configurator[nm-configurator] approach - ----- -Example: -Definition file excerpt: - ---- -kubernetes: - version: v1.30.4+k3s1 - network: - apiVIP: 192.168.64.11 - nodes: - - hostname: node1.suse.com - type: server - initializer: true - - hostname: node2.suse.com - type: agent ---- - -- Network files location: -├── definition.yaml -└── network - ├── node1.suse.com.yaml - └── node2.suse.com.yaml - -node1.suse.com.yaml contents: ---- -routes: - config: - - destination: 0.0.0.0/0 - metric: 100 - next-hop-address: 192.168.64.1 - next-hop-interface: eth0 - table-id: 254 -dns-resolver: - config: - server: - - 192.168.64.1 - - 8.8.8.8 -interfaces: -- name: eth0 - type: ethernet - state: up - mac-address: 34:8A:B1:4B:16:E1 - ipv4: - address: - - ip: 192.168.64.21 - prefix-length: 24 - dhcp: false - enabled: true - ipv6: - enabled: false ---- - -node2.suse.com.yaml contents: ---- -routes: - config: - - destination: 0.0.0.0/0 - metric: 100 - next-hop-address: 192.168.64.1 - next-hop-interface: eth0 - table-id: 254 -dns-resolver: - config: - server: - - 192.168.64.1 - - 8.8.8.8 -interfaces: -- name: eth0 - type: ethernet - state: up - mac-address: 34:8A:B1:4B:16:E2 - ipv4: - address: - - ip: 192.168.64.22 - prefix-length: 24 - dhcp: false - enabled: true - ipv6: - enabled: false ---- - ----- From dddb783c4966d3ce13ee1c16ed3582f23493c534 Mon Sep 17 00:00:00 2001 From: George Date: Thu, 28 Nov 2024 14:42:57 +0100 Subject: [PATCH 3/5] typo --- asciidoc/edge-book/edge.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/asciidoc/edge-book/edge.adoc b/asciidoc/edge-book/edge.adoc index 68d07bed..d54ff2a2 100755 --- a/asciidoc/edge-book/edge.adoc +++ b/asciidoc/edge-book/edge.adoc @@ -107,7 +107,7 @@ include::../guides/air-gapped-eib-deployments.adoc[leveloffset=+1] [partintro] Tips and tricks for Edge components -include::../tricks/eib.adoc[leveloffset=+1] +include::../tips/eib.adoc[leveloffset=+1] //-------------------------------------------- From 465532c4a6840c334b14f925c7bfd33dec2852b4 Mon Sep 17 00:00:00 2001 From: George Date: Tue, 17 Dec 2024 13:45:22 +0100 Subject: [PATCH 4/5] updating EIB tips and tricks document --- asciidoc/components/edge-image-builder.adoc | 4 +- asciidoc/tips/eib.adoc | 124 +------------------- 2 files changed, 3 insertions(+), 125 deletions(-) diff --git a/asciidoc/components/edge-image-builder.adoc b/asciidoc/components/edge-image-builder.adoc index 5fa771e7..dd708406 100644 --- a/asciidoc/components/edge-image-builder.adoc +++ b/asciidoc/components/edge-image-builder.adoc @@ -17,8 +17,6 @@ Edge Image Builder (EIB) is a tool that streamlines the generation of Customized Whilst EIB can create CRB images for all provisioning scenarios, EIB demonstrates a tremendous value in air-gapped deployments with limited or completely isolated networks. -link:../tips/eib.adoc[Read more EIB tips here] - == How does SUSE Edge use Edge Image Builder? @@ -43,6 +41,8 @@ Comprehensive documentation for the usage and testing of Edge Image Builder can Additionally, here is a <> for Edge Image Builder covering a basic deployment scenario. +Once you are familiar with this tool, please find some more useful information on our link:../tips/eib.adoc[Tips and tricks] page. + == Known issues * EIB air-gaps Helm charts through templating the Helm charts and parsing all the images within the template. If a Helm chart does not keep all of its images within the template and instead side-loads the images, EIB will not be able to air-gap those images automatically. The solution to this is to manually add any undetected images to the `embeddedArtifactRegistry` section of the definition file. diff --git a/asciidoc/tips/eib.adoc b/asciidoc/tips/eib.adoc index e1b10e2d..b0b5da37 100644 --- a/asciidoc/tips/eib.adoc +++ b/asciidoc/tips/eib.adoc @@ -2,7 +2,7 @@ .Common -- If you are in a non-Linux environment, then you are running `Podman` via a virtual machine. This machine is low on resources on its default settings and can cause `Edge Image Builder` to require unreasonable amount of time for resource intensive operations, such as the RPM resolution process. You will need to adjust the resources of the podman machine, either by using Podman Desktop (settings cogwheel -> podman machine edit icon) or directly via the `podman-machine-set` https://docs.podman.io/en/stable/markdown/podman-machine-set.1.html[command] +- If you are in a non-Linux environment and following these instructions to build an image, then you are likely running `Podman` via a virtual machine. By default, this virtual machine will be configured to have a small amount of system resources allocated to it and can cause instability for `Edge Image Builder` during resource intensive operations, such as the RPM resolution process. You will need to adjust the resources of the podman machine, either by using Podman Desktop (settings cogwheel -> podman machine edit icon) or directly via the `podman-machine-set` https://docs.podman.io/en/stable/markdown/podman-machine-set.1.html[command] - At this point in time, the `Edge Image Builder` is not able to build images in a cross architecture setup, i.e. you have to run it on: * `aarch64` systems (such as Apple Silicon) to build SL Micro `aarch64` images * `x86_64` systems (such as Intel) to build SL Micro `x86_64` images. @@ -17,125 +17,3 @@ To learn more about this configuration, please refer to the https://github.com/s - `Edge Image Builder` relies on the hostnames of the different nodes to determine their Kubernetes type (`server` or `agent`). While this configuration is managed in the definition file, for the general networking setup of the machines we can utilize either DHCP or the https://github.com/suse-edge/nm-configurator[nm-configurator component]. - -.Simple example of image creation for a multi server node RKE2 cluster with Rancher Prime: -**definition file:** - -[source] -apiVersion: 1.1 -image: - arch: aarch64 - imageType: iso - baseImage: SL-Micro.aarch64-6.0-Base-SelfInstall-GM2.install.iso - outputImageName: rke2-ha.iso -operatingSystem: - isoConfiguration: - installDevice: /dev/vda - users: - - username: root - encryptedPassword: # Add an encrypted password [1] - createHomeDir: true - - username: george - encryptedPassword: # Add an encrypted password [1] - sshKeys: - - # Add ssh key for user george - createHomeDir: true - keymap: us - time: - timezone: "Europe/Prague" - kernelArgs: - - foo=bar # dummy value for testing - packages: - packageList: - - lshw - sccRegistrationCode: # Add your SCC Registration Code -kubernetes: - version: v1.30.3+rke2r1 - network: - apiVIP: api.cluster01.edge.suse.com - apiHost: api.cluster01.edge.suse.com - nodes: # Multi server cluster - - hostname: node01.cluster01.edge.suse.com - type: server - initializer: true - - hostname: node02.cluster01.edge.suse.com - type: server - - hostname: node03.cluster01.edge.suse.com - type: server - helm: - charts: - - name: cert-manager - version: 1.16.1 - repositoryName: jetstack - targetNamespace: cert-manager - createNamespace: true - valuesFile: cert-manager.yaml - - name: rancher - version: 2.9.1 - repositoryName: rancher-prime - targetNamespace: cattle-system - createNamespace: true - valuesFile: rancher-prime.yaml - repositories: - - name: jetstack - url: https://charts.jetstack.io - - name: rancher-prime - url: https://charts.rancher.com/server-charts/prime - - - - -[IMPORTANT] -==== -. link:https://documentation.suse.com/suse-edge/3.1/html/edge/quickstart-eib.html#id-configuring-os-users[Create an encrypted password] -. Read more on link:https://github.com/suse-edge/edge-image-builder/blob/main/docs/building-images.md#network-configuration[Network Configuration] -==== - -**network files:** - -[source] --> file node01.cluster01.edge.suse.com: -interfaces: -- name: eth0 - type: ethernet - state: up - mac-address: 00:00:00:00:00:01 - ipv4: - dhcp: true - enabled: true - ipv6: - enabled: false --> file node02.cluster01.edge.suse.com: - interfaces: -- name: eth0 - type: ethernet - state: up - mac-address: 00:00:00:00:00:02 - ipv4: - dhcp: true - enabled: true - ipv6: - enabled: false --> file node03.cluster01.edge.suse.com: -interfaces: -- name: eth0 - type: ethernet - state: up - mac-address: 00:00:00:00:00:03 - ipv4: - dhcp: true - enabled: true - ipv6: - enabled: false - -**helm values files:** - -[source] --> cert-manager.yaml: -installCRDs: true --> rancher-prime.yaml: -hostname: "node01.cluster01.edge.suse.com" -replicas: 1 -bootstrapPassword: Admin -global.cattle.psp.enabled: "false" - From 80add27de906b9593cee94363e582f1841c0eed4 Mon Sep 17 00:00:00 2001 From: George Date: Thu, 2 Jan 2025 14:11:06 +0100 Subject: [PATCH 5/5] Updating Networking link in EIB tips document --- asciidoc/tips/eib.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/asciidoc/tips/eib.adoc b/asciidoc/tips/eib.adoc index b0b5da37..bc7c65d2 100644 --- a/asciidoc/tips/eib.adoc +++ b/asciidoc/tips/eib.adoc @@ -16,4 +16,4 @@ To learn more about this configuration, please refer to the https://github.com/suse-edge/edge-image-builder/blob/main/docs/building-images.md#kubernetes[Kubernetes section docs]. -- `Edge Image Builder` relies on the hostnames of the different nodes to determine their Kubernetes type (`server` or `agent`). While this configuration is managed in the definition file, for the general networking setup of the machines we can utilize either DHCP or the https://github.com/suse-edge/nm-configurator[nm-configurator component]. +- `Edge Image Builder` relies on the hostnames of the different nodes to determine their Kubernetes type (`server` or `agent`). While this configuration is managed in the definition file, for the general networking setup of the machines we can utilize either DHCP or the https://documentation.suse.com/suse-edge/3.1/html/edge/components-nmc.html[Edge Networking page]. \ No newline at end of file