Skip to content

Commit f11dba8

Browse files
anmazzottianmazzotti
authored
Add dev iso build and documentation (#1203)
* Add dev iso build and documentation Signed-off-by: Andrea Mazzotti <andrea.mazzotti@suse.com>
1 parent 537e9d9 commit f11dba8

7 files changed

+391
-0
lines changed

‎Dockerfile.dev.iso

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
ARG ELEMENTAL_OS_IMAGE
2+
3+
FROM ${ELEMENTAL_OS_IMAGE} as os
4+
5+
COPY manifest.yaml manifest.yaml
6+
RUN elemental --debug --config-dir . build-iso -o /output -n "elemental-dev" dir:/
7+
8+
FROM busybox:stable
9+
10+
COPY --from=os /output /elemental-iso

‎Dockerfile.dev.os

+80
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
ARG ELEMENTAL_TOOLKIT
2+
ARG ELEMENTAL_REGISTER
3+
4+
FROM ${ELEMENTAL_REGISTER} as register
5+
FROM ${ELEMENTAL_TOOLKIT} as toolkit
6+
7+
# OS base image of our choice
8+
FROM registry.opensuse.org/opensuse/leap:15.5 as OS
9+
10+
ARG RANCHER_SYSTEM_AGENT_VERSION
11+
12+
# install kernel, systemd, dracut, grub2 and other required tools
13+
RUN ARCH=$(uname -m); \
14+
[[ "${ARCH}" == "aarch64" ]] && ARCH="arm64"; \
15+
zypper --non-interactive install --no-recommends -- \
16+
kernel-default \
17+
device-mapper \
18+
dracut \
19+
grub2 \
20+
grub2-${ARCH}-efi \
21+
shim \
22+
haveged \
23+
systemd \
24+
NetworkManager \
25+
openssh-server \
26+
openssh-clients \
27+
timezone \
28+
parted \
29+
e2fsprogs \
30+
dosfstools \
31+
mtools \
32+
xorriso \
33+
findutils \
34+
gptfdisk \
35+
rsync \
36+
squashfs \
37+
lvm2 \
38+
tar \
39+
gzip \
40+
vim \
41+
which \
42+
less \
43+
sudo \
44+
curl \
45+
iproute2 \
46+
podman \
47+
sed
48+
49+
# elemental-register dependencies
50+
RUN ARCH=$(uname -m); \
51+
[[ "${ARCH}" == "aarch64" ]] && ARCH="arm64"; \
52+
zypper --non-interactive install --no-recommends -- \
53+
dmidecode
54+
55+
# Add system files
56+
COPY framework/files/ /
57+
# Add elemental-register
58+
COPY --from=register /usr/sbin/elemental-register /usr/sbin/elemental-register
59+
COPY --from=register /usr/sbin/elemental-support /usr/sbin/elemental-support
60+
# Add the elemental cli
61+
COPY --from=toolkit /usr/bin/elemental /usr/bin/elemental
62+
63+
# Add the elemental-system-agent
64+
ADD --chmod=0755 https://github.com/rancher/system-agent/releases/download/${RANCHER_SYSTEM_AGENT_VERSION}/rancher-system-agent-amd64 /usr/sbin/elemental-system-agent
65+
66+
# Enable essential services
67+
RUN systemctl enable NetworkManager.service
68+
69+
# Enable /tmp to be on tmpfs
70+
RUN cp /usr/share/systemd/tmp.mount /etc/systemd/system
71+
72+
# Generate initrd with required elemental services
73+
RUN elemental init --debug --force
74+
75+
# Update os-release file with some metadata
76+
RUN echo TIMESTAMP="`date +'%Y%m%d%H%M%S'`" >> /etc/os-release && \
77+
echo GRUB_ENTRY_NAME=\"Elemental Dev\" >> /etc/os-release
78+
79+
# Good for validation after the build
80+
CMD /bin/bash

‎Makefile

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
DOCKER?=docker
2+
ELEMENTAL_OS_IMAGE?=docker.io/local/elemental-os:dev
3+
ELEMENTAL_ISO_IMAGE?=docker.io/local/elemental-iso:dev
4+
ELEMENTAL_REGISTER?=docker.io/local/elemental-register:dev
5+
ELEMENTAL_TOOLKIT?=docker.io/local/elemental-toolkit:dev
6+
7+
RANCHER_SYSTEM_AGENT_VERSION?=v0.3.4
8+
9+
.PHONY: build-dev-os
10+
build-dev-os:
11+
$(DOCKER) build \
12+
--build-arg ELEMENTAL_TOOLKIT=$(ELEMENTAL_TOOLKIT) \
13+
--build-arg ELEMENTAL_REGISTER=$(ELEMENTAL_REGISTER) \
14+
--build-arg RANCHER_SYSTEM_AGENT_VERSION=$(RANCHER_SYSTEM_AGENT_VERSION) \
15+
-t $(ELEMENTAL_OS_IMAGE) \
16+
-f Dockerfile.dev.os .
17+
18+
.PHONY: build-dev-iso
19+
build-dev-iso: build-dev-os
20+
$(DOCKER) build \
21+
--build-arg ELEMENTAL_OS_IMAGE=$(ELEMENTAL_OS_IMAGE) \
22+
-t $(ELEMENTAL_ISO_IMAGE) \
23+
-f Dockerfile.dev.iso .
24+
25+
.PHONY: kind-load-dev-iso
26+
kind-load-dev-iso: build-dev-iso
27+
kind load docker-image $(ELEMENTAL_ISO_IMAGE) --name operator-e2e

‎doc/DEVELOPMENT.md

+163
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# Elemental Stack Development
2+
3+
## Pre-requisites
4+
5+
Clone the following repositories in your development environment:
6+
7+
- <https://github.com/rancher/elemental>
8+
9+
This repo is needed to build a development Elemental image that includes the `elemental-register` and it's ready to be used with the `elemental-operator`.
10+
11+
- <https://github.com/rancher/elemental-toolkit>
12+
13+
This repo is needed to build a development image containing the `elemental-toolkit` binary.
14+
This image can be then referenced when building a development Elemental iso.
15+
16+
- <https://github.com/rancher/elemental-operator>
17+
18+
This repo is needed to build a development image containing the `elemental-registry` binary.
19+
It also contains a convenient test cluster that can be automatically provisioned.
20+
The test cluster includes a locally built version of the `elemental-operator`, a version of Rancher, and a test registry that can be used when testing Elemental [upgrades](https://elemental.docs.rancher.com/upgrade) through a `ManagedOSImage`.
21+
22+
## Setup a development environment
23+
24+
1. Provision the test cluster
25+
26+
Using the `elemental-operator` repo:
27+
28+
```bash
29+
make setup-full-cluster
30+
```
31+
32+
If everything succeeded, you should be able to login into Rancher at: <https://172.18.0.2.sslip.io>
33+
The password is `rancherpassword`.
34+
Note that it uses a self-signed certificate.
35+
36+
At this stage you may want to enable Extensions and install the Elemental extension from the Rancher web UI.
37+
38+
1. Build a local image containing the `elemental-register` binary
39+
40+
Using the `elemental-operator` repo:
41+
42+
```bash
43+
make build-docker-register
44+
```
45+
46+
This will build a `docker.io/local/elemental-register:dev` image that can be referenced in the following steps.
47+
Note that before building this image you are free to checkout a different version of the `elemental-operator`, for example to test compatibility issues between mismatching `elemental-operator` and `elemental-register` versions.
48+
49+
1. Build a local image containing the `elemental-toolkit`
50+
51+
Using the `elemental-toolkit` repo:
52+
53+
```bash
54+
make VERSION=dev build
55+
```
56+
57+
This will build a `docker.io/local/elemental-toolkit:dev` image that can be referenced in the following steps.
58+
Note that before building this image you are free to checkout a different version of the `elemental-toolkit`, in order to generate *old* or *new* OS images that can be used to test downgrade/upgrade scenarios.
59+
60+
1. Build and load the Elemental Dev ISO into the test cluster
61+
62+
Using the `elemental` repo:
63+
64+
```bash
65+
make kind-load-dev-iso
66+
```
67+
68+
By default this will use the previously built `docker.io/local/elemental-register:dev` and `docker.io/local/elemental-toolkit:dev` to generate a `docker.io/local/elemental-iso:dev` that can be used as a base Elemental image.
69+
Since the image is also loaded into the test cluster, you can easily reference it in your `SeedImage` definition, for example:
70+
71+
```yaml
72+
apiVersion: elemental.cattle.io/v1beta1
73+
kind: SeedImage
74+
metadata:
75+
name: fire-img
76+
namespace: fleet-default
77+
spec:
78+
type: iso
79+
baseImage: docker.io/local/elemental-iso:dev
80+
registrationRef:
81+
apiVersion: elemental.cattle.io/v1beta1
82+
kind: MachineRegistration
83+
name: fire-nodes
84+
namespace: fleet-default
85+
```
86+
87+
1. Apply a test Elemental manifest and download the Dev ISO
88+
89+
Using the `elemental` repo:
90+
91+
```bash
92+
kubectl apply -f tests/manifests/elemental-dev-example.yaml
93+
```
94+
95+
```bash
96+
kubectl wait --for=condition=ready pod -n fleet-default fire-img
97+
```
98+
99+
```bash
100+
wget --no-check-certificate `kubectl get seedimage -n fleet-default fire-img -o jsonpath="{.status.downloadURL}"` -O elemental-dev.x86_64.iso
101+
```
102+
103+
You can now use this ISO to provision Elemental machines, for example using an hypervisor on your dev environment.
104+
The machines must be able to connect to the test Rancher environment `172.18.0.2:443`, and to the test registry when testing upgrade/downgrade scenarios `172.18.0.2:30000`.
105+
106+
## Testing an Elemental upgrade scenario
107+
108+
Given that the development environment is ready and an Elemental machine was already provisioned, you can prepare a test OS version and use it for upgrades.
109+
The steps are equivalent for downgrades, by just checking out older versions of the components.
110+
111+
1. Build local images containing the `elemental-register` and/or the `elemental-toolkit` on your next feature branch
112+
113+
Using the `elemental-operator` repo:
114+
115+
```bash
116+
git checkout my-next-feature-branch
117+
make build-docker-register
118+
```
119+
120+
Using the `elemental-toolkit` repo:
121+
122+
```bash
123+
git checkout my-next-feature-branch
124+
make VERSION=dev build
125+
```
126+
127+
1. Build a local OS image and push it to the test registry
128+
129+
Using the `elemental` repo:
130+
131+
```bash
132+
ELEMENTAL_OS_IMAGE="172.18.0.2:30000/elemental-os:dev-next" make build-dev-os
133+
```
134+
135+
In order to push this image to the test registry, you have add this in your Docker config: `/etc/docker/daemon.json`
136+
137+
```json
138+
{ "insecure-registries":["172.18.0.2:30000"] }
139+
```
140+
141+
Then restart docker:
142+
143+
```bash
144+
sudo systemctl restart docker
145+
```
146+
147+
Finally push the OS image to the test registry:
148+
149+
```bash
150+
docker push 172.18.0.2:30000/elemental-os:dev-next
151+
```
152+
153+
1. Trigger the upgrade (on a Cluster level)
154+
155+
Using the `elemental` repo:
156+
157+
```bash
158+
kubectl apply -f tests/manifests/elemental-dev-upgrade-example.yaml
159+
```
160+
161+
1. Troubleshoot eventual issues
162+
163+
In case of errors, refer to the [upgrade troubleshooting documentation](https://elemental.docs.rancher.com/troubleshooting-upgrade).

‎manifest.yaml

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
iso:
2+
bootloader-in-rootfs: true
3+
grub-entry-name: "Elemental Dev Install"
4+
5+
squash-no-compression: true

‎tests/manifests/elemental-dev-example.yaml

+96
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
apiVersion: elemental.cattle.io/v1beta1
2+
kind: MachineInventorySelectorTemplate
3+
metadata:
4+
name: fire-machine-selector
5+
namespace: fleet-default
6+
spec:
7+
template:
8+
spec:
9+
selector:
10+
matchExpressions:
11+
- key: element
12+
operator: In
13+
values: [ 'fire' ]
14+
---
15+
kind: Cluster
16+
apiVersion: provisioning.cattle.io/v1
17+
metadata:
18+
name: volcano
19+
namespace: fleet-default
20+
spec:
21+
rkeConfig:
22+
machineGlobalConfig:
23+
etcd-expose-metrics: false
24+
profile: null
25+
machinePools:
26+
- controlPlaneRole: true
27+
etcdRole: true
28+
machineConfigRef:
29+
apiVersion: elemental.cattle.io/v1beta1
30+
kind: MachineInventorySelectorTemplate
31+
name: fire-machine-selector
32+
name: fire-pool
33+
quantity: 1
34+
unhealthyNodeTimeout: 0s
35+
workerRole: true
36+
machineSelectorConfig:
37+
- config:
38+
protect-kernel-defaults: false
39+
registries:
40+
mirrors:
41+
"172.18.0.2:30000":
42+
endpoint:
43+
- "http://172.18.0.2:30000"
44+
configs:
45+
"172.18.0.2:30000":
46+
insecureSkipVerify: true
47+
kubernetesVersion: v1.27.10+k3s1
48+
---
49+
apiVersion: elemental.cattle.io/v1beta1
50+
kind: MachineRegistration
51+
metadata:
52+
name: fire-nodes
53+
namespace: fleet-default
54+
spec:
55+
machineName: test-${System Information/UUID}
56+
config:
57+
cloud-config:
58+
users:
59+
- name: root
60+
passwd: root
61+
elemental:
62+
reset:
63+
debug: true
64+
enabled: true
65+
reset-persistent: true
66+
reset-oem: true
67+
install:
68+
reboot: true
69+
device-selector:
70+
- key: Name
71+
operator: In
72+
values:
73+
- /dev/sda
74+
- /dev/vda
75+
- /dev/nvme0
76+
debug: true
77+
machineInventoryLabels:
78+
element: fire
79+
manufacturer: "${System Information/Manufacturer}"
80+
productName: "${System Information/Product Name}"
81+
serialNumber: "${System Information/Serial Number}"
82+
machineUUID: "${System Information/UUID}"
83+
---
84+
apiVersion: elemental.cattle.io/v1beta1
85+
kind: SeedImage
86+
metadata:
87+
name: fire-img
88+
namespace: fleet-default
89+
spec:
90+
type: iso
91+
baseImage: docker.io/local/elemental-iso:dev
92+
registrationRef:
93+
apiVersion: elemental.cattle.io/v1beta1
94+
kind: MachineRegistration
95+
name: fire-nodes
96+
namespace: fleet-default

‎tests/manifests/elemental-dev-upgrade-example.yaml

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
apiVersion: elemental.cattle.io/v1beta1
2+
kind: ManagedOSImage
3+
metadata:
4+
name: dev-upgrade
5+
namespace: fleet-default
6+
spec:
7+
# Set to the new Elemental version you would like to upgrade to or track the latest tag
8+
osImage: "172.18.0.2:30000/elemental-os:dev-next"
9+
clusterTargets:
10+
- clusterName: volcano

0 commit comments

Comments
 (0)