Introduced version attributes to the documentation - Part 1 (#495)

* initial framework for attribute-based versions

* migrated metal3 quickstart to use version attributes

* simplified attributes file until we find a better reason to split them

* migrated the elemental quickstart to use version attributes

* explicitly mark chart versions as compared to component

* migrated the eib quickstart to use version attributes

* migrated the rancher extensions component guide to use version attributes

* changed eib link handling to use the explicit links instead of deriving

* renamed version-edge-chart-repo to version-edge-registry

* migrated the sl micro component guide to use version attributes

* minor reformatting to metal3 guide

* migrated EIB component guide to use version attributes

* migrated the networking component guide to user version attributes

asciidoc/components/edge-image-builder.adoc

@@ -36,7 +36,7 @@ SUSE Edge uses EIB for the simplified and quick configuration of customized SLE
 
 == Getting started
 
-Comprehensive documentation for the usage and testing of Edge Image Builder can be found https://github.com/suse-edge/edge-image-builder/tree/release-1.1/docs[here].
+Comprehensive documentation for the usage and testing of Edge Image Builder can be found {link-eib-docs}[here].
 
 Additionally, here is a <<quickstart-eib,quick start guide>> for Edge Image Builder covering a basic deployment scenario.
 

asciidoc/components/metal3.adoc

@@ -20,7 +20,7 @@ which support management via out-of-band protocols such as https://www.dmtf.org/
 It also has mature support for https://cluster-api.sigs.k8s.io/[Cluster API (CAPI)] which enables management
 of infrastructure resources across multiple infrastructure providers via broadly adopted vendor-neutral APIs.
 
-== How does SUSE Edge use Metal3?
+== How does SUSE Edge use Metal^3^?
 
 This method is useful for scenarios where the target hardware supports out-of-band management, and a fully automated
 infrastructure management flow is desired.

asciidoc/components/networking.adoc

@@ -20,7 +20,7 @@ NetworkManager is a tool that manages the primary network connection and other c
 NetworkManager stores network configurations as connection files that contain the desired state.
 These connections are stored as files in the `/etc/NetworkManager/system-connections/` directory.
 
-Details about NetworkManager can be found in the https://documentation.suse.com/sle-micro/6.0/html/Micro-network-configuration/index.html[SLE Micro documentation].
+Details about NetworkManager can be found in the {link-micro-networkmanager}[SLE Micro documentation].
 
 == Overview of nmstate
 
@@ -54,15 +54,15 @@ If you're following this guide, it's assumed that you've got the following alrea
 
 * An x86_64 physical host (or virtual machine) running SLES 15 SP6 or openSUSE Leap 15.6
 * An available container runtime (e.g. Podman)
-* A copy of the SL Micro 6.0 RAW image found https://www.suse.com/download/sle-micro/[here]
+* A copy of the SL Micro {version-operatingsystem} RAW image found https://www.suse.com/download/sle-micro/[here]
 
 === Getting the Edge Image Builder container image
 
 The EIB container image is publicly available and can be downloaded from the SUSE Edge registry by running:
 
-[,shell]
+[,shell,subs="attributes"]
 ----
-podman pull registry.suse.com/edge/3.1/edge-image-builder:1.1.0
+podman pull registry.suse.com/edge/{version-edge-registry}/edge-image-builder:{version-eib}
 ----
 
 === Creating the image configuration directory [[image-config-dir-creation]]
@@ -77,19 +77,19 @@ mkdir -p $CONFIG_DIR/base-images
 
 We will now ensure that the downloaded base image copy is moved over to the configuration directory:
 
-[,shell]
+[,shell,subs="attributes"]
 ----
-mv /path/to/downloads/SL-Micro.x86_64-6.0-Base-GM2.raw $CONFIG_DIR/base-images/
+mv /path/to/downloads/{micro-base-image} $CONFIG_DIR/base-images/
 ----
 
-> NOTE: EIB is never going to modify the base image input.
+> NOTE: EIB is never going to modify the base image input. It will create a new image with its modifications.
 
 The configuration directory at this point should look like the following:
 
-[,console]
+[,console,subs="attributes"]
 ----
 └── base-images/
-    └── SL-Micro.x86_64-6.0-Base-GM2.raw
+    └── {micro-base-image}
 ----
 
 === Creating the image definition file
@@ -98,14 +98,14 @@ The definition file describes the majority of configurable options that the Edge
 
 Let's start with a very basic definition file for our OS image:
 
-[,shell]
+[,shell,subs="attributes,specialchars"]
 ----
 cat << EOF > $CONFIG_DIR/definition.yaml
-apiVersion: 1.0
+apiVersion: {version-eib-api-latest}
 image:
   arch: x86_64
   imageType: raw
-  baseImage: SL-Micro.x86_64-6.0-Base-GM2.raw
+  baseImage: {micro-base-image}
   outputImageName: modified-image.raw
 operatingSystem:
   users:
@@ -121,11 +121,11 @@ The `operatingSystem` section is optional, and contains configuration to enable
 
 The configuration directory at this point should look like the following:
 
-[,console]
+[,console,subs="attributes"]
 ----
 ├── definition.yaml
 └── base-images/
-    └── SL-Micro.x86_64-6.0-Base-GM2.raw
+    └── {micro-base-image}
 ----
 
 === Defining the network configurations [[default-network-definition]]
@@ -337,15 +337,15 @@ EOF
 
 The configuration directory at this point should look like the following:
 
-[,console]
+[,console,subs="attributes"]
 ----
 ├── definition.yaml
 ├── network/
 │   │── node1.suse.com.yaml
 │   │── node2.suse.com.yaml
 │   └── node3.suse.com.yaml
 └── base-images/
-    └── SL-Micro.x86_64-6.0-Base-GM2.raw
+    └── {micro-base-image}
 ----
 
 > NOTE: The names of the files under the `network/` directory are intentional.
@@ -355,9 +355,9 @@ They correspond to the hostnames which will be set during the provisioning proce
 
 Now that all the necessary configurations are in place, we can build the image by simply running:
 
-[,shell]
+[,shell,subs="attributes"]
 ----
-podman run --rm -it -v $CONFIG_DIR:/eib registry.suse.com/edge/3.1/edge-image-builder:1.1.0 build --definition-file definition.yaml
+podman run --rm -it -v $CONFIG_DIR:/eib registry.suse.com/edge/{version-edge-registry}/edge-image-builder:{version-eib} build --definition-file definition.yaml
 ----
 
 The output should be similar to the following:
@@ -740,9 +740,9 @@ EOF
 
 Let's build the image:
 
-[,shell]
+[,shell,subs="attributes"]
 ----
-podman run --rm -it -v $CONFIG_DIR:/eib registry.suse.com/edge/3.1/edge-image-builder:1.1.0 build --definition-file definition.yaml
+podman run --rm -it -v $CONFIG_DIR:/eib registry.suse.com/edge/{version-edge-registry}/edge-image-builder:{version-eib} build --definition-file definition.yaml
 ----
 
 Once the image is successfully built, let's create a virtual machine using it:
@@ -924,7 +924,7 @@ It is NOT possible to configure a network by working with both static configurat
 
 The configuration directory at this point should look like the following:
 
-[,console]
+[,console,subs="attributes"]
 ----
 ├── definition.yaml
 ├── custom/
@@ -933,14 +933,14 @@ The configuration directory at this point should look like the following:
 ├── network/
 │   └── configure-network.sh
 └── base-images/
-    └── SL-Micro.x86_64-6.0-Base-GM2.raw
+    └── {micro-base-image}
 ----
 
 Let's build the image:
 
-[,shell]
+[,shell,subs="attributes"]
 ----
-podman run --rm -it -v $CONFIG_DIR:/eib registry.suse.com/edge/3.1/edge-image-builder:1.1.0 build --definition-file definition.yaml
+podman run --rm -it -v $CONFIG_DIR:/eib registry.suse.com/edge/{version-edge-registry}/edge-image-builder:{version-eib} build --definition-file definition.yaml
 ----
 
 Once the image is successfully built, let's create a virtual machine using it:

asciidoc/components/rancher-dashboard-extensions.adoc

@@ -13,11 +13,11 @@ endif::[]
 
 Extensions allow users, developers, partners, and customers to extend and enhance the Rancher UI. SUSE Edge 3.1 provides KubeVirt and Akri dashboard extensions.
 
-See `https://ranchermanager.docs.rancher.com/v2.9/integrations-in-rancher/rancher-extensions[Rancher documentation]` for general information about Rancher Dashboard Extensions.
+See `{link-rancher-extensions}[Rancher documentation]` for general information about Rancher Dashboard Extensions.
 
 == Installation
 
-All SUSE Edge 3.1 components including dashboard extensions are distributed as OCI artifacts. To install SUSE Edge Extensions you can use Rancher Dashboard UI, Helm or Fleet:
+All of the SUSE Edge {version-edge} components, including dashboard extensions, are distributed as OCI artifacts. To install SUSE Edge Extensions you can use Rancher Dashboard UI, Helm or Fleet:
 
 === Installing with Rancher Dashboard UI
 
@@ -30,10 +30,10 @@ Each extension is distributed via it's own OCI artefact. Therefore, you need to
 . In the form, specify the repository name and OCI artifact URL, and click `Create`.
 +
 Akri Dashboard Extension Repository URL:
-`oci://registry.suse.com/edge/3.1/akri-dashboard-extension-chart`
+`oci://registry.suse.com/edge/{version-edge-registry}/akri-dashboard-extension-chart`
 +
 KubeVirt Dashboard Extension Repository URL:
-`oci://registry.suse.com/edge/3.1/kubevirt-dashboard-extension-chart`
+`oci://registry.suse.com/edge/{version-edge-registry}/kubevirt-dashboard-extension-chart`
 +
 image::dashboard-extensions-create-oci-repository.png[]
 
@@ -55,13 +55,13 @@ Once the extension is installed Rancher UI prompts to reload the page as describ
 
 === Installing with Helm
 
-[,bash]
+[,bash,subs="attributes"]
 ----
 # KubeVirt extension
-helm install kubevirt-dashboard-extension oci://registry.suse.com/edge/3.1/kubevirt-dashboard-extension-chart --version 1.1.0 --namespace cattle-ui-plugin-system
+helm install kubevirt-dashboard-extension oci://registry.suse.com/edge/{version-edge-registry}/kubevirt-dashboard-extension-chart --version {version-kubevirt-dashboard-extension-chart} --namespace cattle-ui-plugin-system
 
 # Akri extension
-helm install akri-dashboard-extension oci://registry.suse.com/edge/3.1/akri-dashboard-extension-chart --version 1.1.0 --namespace cattle-ui-plugin-system
+helm install akri-dashboard-extension oci://registry.suse.com/edge/{version-edge-registry}/akri-dashboard-extension-chart --version {version-akri-dashboard-extension-chart} --namespace cattle-ui-plugin-system
 ----
 
 [NOTE]
@@ -78,24 +78,24 @@ After an extension is installed, Rancher Dashboard UI needs to be reloaded.
 
 Installing Dashboard Extensions with Fleet requires defining a `gitRepo` resource which points to a Git repository with custom `fleet.yaml` bundle configuration file(s).
 
-[,yaml]
+[,yaml,subs="attributes"]
 ----
 # KubeVirt extension fleet.yaml
 defaultNamespace: cattle-ui-plugin-system
 helm:
   releaseName: kubevirt-dashboard-extension
-  chart: oci://registry.suse.com/edge/3.1/kubevirt-dashboard-extension-chart
-  version: "1.1.0"
+  chart: oci://registry.suse.com/edge/{version-edge-registry}/kubevirt-dashboard-extension-chart
+  version: "{version-kubevirt-dashboard-extension-chart}"
 ----
 
-[,yaml]
+[,yaml,subs="attributes"]
 ----
 # Akri extension fleet.yaml
 defaultNamespace: cattle-ui-plugin-system
 helm:
   releaseName: akri-dashboard-extension
-  chart: oci://registry.suse.com/edge/3.1/akri-dashboard-extension-chart
-  version: "1.1.0"
+  chart: oci://registry.suse.com/edge/{version-edge-registry}/akri-dashboard-extension-chart
+  version: "{version-akri-dashboard-extension-chart}"
 ----
 
 [NOTE]

asciidoc/components/sle-micro.adoc

@@ -12,7 +12,7 @@ ifdef::env-github[]
 endif::[]
 
 
-See https://documentation.suse.com/sle-micro/6.0/[SLE Micro official documentation]
+See {link-micro-official-docs}[SLE Micro official documentation]
 
 [quote]
 ____

asciidoc/edge-book/edge.adoc

@@ -5,7 +5,6 @@
 //:doctype: book
 //:partnum:
 
-
 ifdef::env-github[]
 :imagesdir: ../images/
 :tip-caption: :bulb:
@@ -15,6 +14,9 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 
+include::./versions.adoc[]
+include::./links.adoc[]
+
 [preface]
 include::./welcome.adoc[leveloffset=+1]
 

asciidoc/edge-book/links.adoc

@@ -0,0 +1,16 @@
+// The following are links tied to a particular version of a component (i.e. EIB, Rancher)
+// Rather than derive them based on the version number, these are kept separate so they
+// can be verified to not have broken in the new version documentation.
+
+:link-rancher-extensions: https://ranchermanager.docs.rancher.com/v2.9/integrations-in-rancher/rancher-extensions
+
+:eib-release-tag: release-1.1
+:link-eib-docs: https://github.com/suse-edge/edge-image-builder/tree/{eib-release-tag}/docs
+:link-eib-full-example: https://github.com/suse-edge/edge-image-builder/blob/{eib-release-tag}/pkg/image/testdata/full-valid-example.yaml
+:link-eib-building-images: https://github.com/suse-edge/edge-image-builder/blob/{eib-release-tag}/docs/building-images.md
+:link-eib-installing-packages: https://github.com/suse-edge/edge-image-builder/blob/{eib-release-tag}/docs/installing-packages.md
+:link-eib-debugging: https://github.com/suse-edge/edge-image-builder/blob/{eib-release-tag}/docs/debugging.md
+:link-eib-testing: https://github.com/suse-edge/edge-image-builder/blob/{eib-release-tag}/docs/testing-guide.md
+
+:link-micro-official-docs: https://documentation.suse.com/sle-micro/6.0/
+:link-micro-networkmanager: https://documentation.suse.com/sle-micro/6.0/html/Micro-network-configuration/index.html

asciidoc/edge-book/versions.adoc

@@ -0,0 +1,37 @@
+:version-edge: 3.1.0
+:version-edge-registry: 3.1
+
+:version-eib: 1.1.0
+:version-eib-api-latest: 1.1
+
+:version-rancher-chart-prime: 2.9.3
+
+:micro-base-image: SL-Micro.x86_64-6.0-Base-GM2.raw
+
+// Release Manifest Versions
+// The following are derived from the `releaseName` field of the release manifest
+
+:version-kubernetes-k3s: v1.30.5+k3s1
+:version-kubernetes-rke2: v1.30.5+rke2r1
+
+:version-operatingsystem: 6.0
+
+:version-rancher-chart: v2.9.3
+:version-longhorn-chart: 104.2.0+up1.7.1
+:version-longhorn-crd-chart: 104.2.0+up1.7.1
+:version-metallb-chart: 0.14.9
+:version-cdi-chart: 0.4.0
+:version-kubevirt-chart: 0.4.0
+:version-kubevirt-dashboard-extension-chart: 1.1.0
+:version-neuvector-chart: 104.0.2+up2.8.0
+:version-neuvector-crd-chart: 104.0.2+up2.8.0
+:version-neuvector-dashboard-extension-chart: 2.0.0
+:version-endpoint-copier-operator-chart: 0.2.1
+:version-elemental-operator-chart: 1.6.4
+:version-elemental-operator-crds-chart: 1.6.4
+:version-sriov-network-operator-chart: 1.3.0
+:version-sriov-crd-chart: 1.3.0
+:version-akri-chart: 0.12.20
+:version-akri-dashboard-extension-chart: 1.1.0
+:version-metal3-chart: 0.8.3
+:version-rancher-turtles: 0.3.3

asciidoc/edge-book/welcome.adoc

@@ -1,4 +1,4 @@
-= SUSE Edge Documentation
+= SUSE Edge {version-edge} Documentation
 
 ifdef::env-github[]
 :imagesdir: ../images/