Merge branch 'master' of https://github.com/metal-stack/docs into mep-13

metal-stack · Dec 20, 2024 · 21862d2 · 21862d2
2 parents 35a1811 + fd9e485
commit 21862d2
Show file tree

Hide file tree

Showing 16 changed files with 1,169 additions and 48 deletions.
diff --git a/Makefile b/Makefile
@@ -1,5 +1,5 @@
 .DEFAULT_GOAL := build
-RELEASE_VERSION := $(or ${RELEASE_VERSION},"v0.18.16")
+RELEASE_VERSION := $(or ${RELEASE_VERSION},"v0.19.2")
 
 ifeq ($(CI),true)
 DOCKER_TTY_ARG=

diff --git a/docs/src/development/proposals/MEP14/README.md b/docs/src/development/proposals/MEP14/README.md
@@ -9,6 +9,7 @@ So far, the following components have been identified as requiring changes:
 - metal-images
 
 More components are likely to be added to the list during processing.
+For DNS and NTP servers it should be possible to provide default values within a partition. They can either be inherited from machines and firewalls or overwritten with own ones.
 
 ## pixiecore
 
@@ -22,4 +23,8 @@ If using a self-deployed NTP server, also the metal-hammer need to be configured
 
 Configurations for the `metal-images` are different for machines and firewalls.
 
+## metalctl
+
+In order to pass DNS and NTP servers to partitions and machines while creating them, the flags `dnsservers` and `ntpservers` need to be added.
+
 The implementation of this MEP will make metal-stack possible to create and maintain machines without requiring an internet connection.
diff --git a/docs/src/external/metalctl/docs/metalctl_firewall_create.md b/docs/src/external/metalctl/docs/metalctl_firewall_create.md
@@ -11,6 +11,7 @@ metalctl firewall create [flags]
 ```
       --bulk-output                  when used with --file (bulk operation): prints results at the end as a list. default is printing results intermediately during the operation, which causes single entities to be printed in a row.
   -d, --description string           Description of the firewall to create. [optional]
+      --dnsservers strings           dns servers to add to the machine or firewall. [optional]
   -f, --file string                  filename of the create or update request in yaml format, or - for stdin.
                                      
                                      Example:
@@ -85,6 +86,7 @@ metalctl firewall create [flags]
                                      MODE can be omitted or one of:
                                      	auto	IP address is automatically acquired from the given network
                                      	noauto	No automatic IP address acquisition
+      --ntpservers strings           ntp servers to add to the machine or firewall. [optional]
   -S, --partition string             partition/datacenter where the firewall is created. [required, except for reserved machines]
   -P, --project string               Project where the firewall should belong to. [required]
   -s, --size string                  Size of the firewall. [required, except for reserved machines]

diff --git a/docs/src/external/metalctl/docs/metalctl_machine_create.md b/docs/src/external/metalctl/docs/metalctl_machine_create.md
@@ -51,6 +51,7 @@ Once created the machine installation can not be modified anymore.
 ```
       --bulk-output               when used with --file (bulk operation): prints results at the end as a list. default is printing results intermediately during the operation, which causes single entities to be printed in a row.
   -d, --description string        Description of the machine to create. [optional]
+      --dnsservers strings        dns servers to add to the machine or firewall. [optional]
   -f, --file string               filename of the create or update request in yaml format, or - for stdin.
                                   
                                   Example:
@@ -77,6 +78,7 @@ Once created the machine installation can not be modified anymore.
                                   MODE cane be omitted or one of:
                                   	auto	IP address is automatically acquired from the given network
                                   	noauto	IP address for the given network must be provided via --ips
+      --ntpservers strings        ntp servers to add to the machine or firewall. [optional]
   -S, --partition string          partition/datacenter where the machine is created. [required, except for reserved machines]
   -P, --project string            Project where the machine should belong to. [required]
   -s, --size string               Size of the machine. [required, except for reserved machines]

diff --git a/docs/src/external/metalctl/docs/metalctl_partition_capacity.md b/docs/src/external/metalctl/docs/metalctl_partition_capacity.md
@@ -9,10 +9,11 @@ metalctl partition capacity [flags]
 ## Options
 
 ```
-  -h, --help              help for capacity
-      --id string         filter on partition id. [optional]
-      --size string       filter on size id. [optional]
-      --sort-by strings   order by (comma separated) column(s), sort direction can be changed by appending :asc or :desc behind the column identifier. possible values: description|id|name
+  -h, --help                help for capacity
+      --id string           filter on partition id. [optional]
+      --project-id string   consider project-specific counts, e.g. size reservations. [optional]
+      --size string         filter on size id. [optional]
+      --sort-by strings     order by (comma separated) column(s), sort direction can be changed by appending :asc or :desc behind the column identifier. possible values: description|id|name
 ```
 
 ## Options inherited from parent commands

diff --git a/docs/src/external/metalctl/docs/metalctl_partition_create.md b/docs/src/external/metalctl/docs/metalctl_partition_create.md
@@ -12,6 +12,7 @@ metalctl partition create [flags]
       --bulk-output             when used with --file (bulk operation): prints results at the end as a list. default is printing results intermediately during the operation, which causes single entities to be printed in a row.
       --cmdline string          kernel commandline for the metal-hammer in the partition. [required]
   -d, --description string      Description of the partition. [required]
+      --dnsservers string       dns servers for the machines and firewalls in the partition. [optional]
   -f, --file string             filename of the create or update request in yaml format, or - for stdin.
                                 
                                 Example:
@@ -30,6 +31,7 @@ metalctl partition create [flags]
       --kernelurl string        kernel url for the metal-hammer in the partition. [required]
       --mgmtserver string       management server address in the partition. [required]
   -n, --name string             Name of the partition. [optional]
+      --ntpservers string       ntp servers for the machines and firewalls in the partition. [optional]
       --skip-security-prompts   skips security prompt for bulk operations
       --timestamps              when used with --file (bulk operation): prints timestamps in-between the operations
 ```

diff --git a/docs/src/external/metalctl/docs/metalctl_switch.md b/docs/src/external/metalctl/docs/metalctl_switch.md
@@ -50,6 +50,7 @@ switch are the leaf switches in the data center that are controlled by metal-sta
 * [metalctl switch detail](metalctl_switch_detail.md)	 - switch details
 * [metalctl switch edit](metalctl_switch_edit.md)	 - edit the switch through an editor and update
 * [metalctl switch list](metalctl_switch_list.md)	 - list all switches
+* [metalctl switch migrate](metalctl_switch_migrate.md)	 - migrate machine connections and other configuration from one switch to another
 * [metalctl switch port](metalctl_switch_port.md)	 - sets the given switch port state up or down
 * [metalctl switch replace](metalctl_switch_replace.md)	 - put a leaf switch into replace mode in preparation for physical replacement. For a description of the steps involved see the long help.
 * [metalctl switch ssh](metalctl_switch_ssh.md)	 - connect to the switch via ssh

diff --git a/docs/src/external/metalctl/docs/metalctl_switch_migrate.md b/docs/src/external/metalctl/docs/metalctl_switch_migrate.md
@@ -0,0 +1,46 @@
+# metalctl switch migrate
+
+migrate machine connections and other configuration from one switch to another
+
+```
+metalctl switch migrate <oldSwitchID> <newSwitchID> [flags]
+```
+
+## Options
+
+```
+  -h, --help   help for migrate
+```
+
+## Options inherited from parent commands
+
+```
+      --api-token string       api token to authenticate. Can be specified with METALCTL_API_TOKEN environment variable.
+      --api-url string         api server address. Can be specified with METALCTL_API_URL environment variable.
+  -c, --config string          alternative config file path, (default is ~/.metalctl/config.yaml).
+                               Example config.yaml:
+                               
+                               ---
+                               apitoken: "alongtoken"
+                               ...
+                               
+                               
+      --debug                  debug output
+      --force-color            force colored output even without tty
+      --kubeconfig string      Path to the kube-config to use for authentication and authorization. Is updated by login. Uses default path if not specified.
+      --no-headers             do not print headers of table output format (default print headers)
+  -o, --output-format string   output format (table|wide|markdown|json|yaml|template), wide is a table with more columns. (default "table")
+      --template string        output template for template output-format, go template format.
+                               For property names inspect the output of -o json or -o yaml for reference.
+                               Example for machines:
+                               
+                               metalctl machine list -o template --template "{{ .id }}:{{ .size.id  }}"
+                               
+                               
+      --yes-i-really-mean-it   skips security prompts (which can be dangerous to set blindly because actions can lead to data loss or additional costs)
+```
+
+## SEE ALSO
+
+* [metalctl switch](metalctl_switch.md)	 - manage switch entities
+
diff --git a/docs/src/external/mini-lab/README.md b/docs/src/external/mini-lab/README.md
@@ -193,16 +193,15 @@ docker compose run --rm metalctl machine rm e0ab02d2-27cd-5a5e-8efc-080ba80cf258
 
 ## Flavors
 
-There's few versions of mini-lab environment that you can run. We call them flavors. There's 2 flavors at the moment:
+There are two versions, or flavors, of the mini-lab environment which differ in regards to the NOS running on the leaves:
 
-- `default` -- runs 2 machines.
-- `cluster-api` -- runs 3 machines. Useful for testing Control plane and worker node deployment with [Cluster API provider](https://github.com/metal-stack/cluster-api-provider-metalstack).
-- `sonic` -- use SONiC as network operating system for the leaves
+- `cumulus` -- runs 2 Cumulus switches.
+- `sonic` -- runs 2 SONiC switches
 
 In order to start specific flavor, you can define the flavor as follows:
 
 ```bash
-export MINI_LAB_FLAVOR=cluster-api
+export MINI_LAB_FLAVOR=sonic
 make
 ```
 

diff --git a/docs/src/installation/updates.md b/docs/src/installation/updates.md
@@ -14,14 +14,32 @@ markdownTemplate(t, version)
 
 Releases and integration tests are published through our [release repository](https://github.com/metal-stack/releases). You can also find the [release notes](https://github.com/metal-stack/releases/releases) for this metal-stack version in there. The release notes contain information about new features, upgrade paths and bug fixes.
 
+A release is created in the following way:
+
+- Individual repository maintainers within the metal-stack Github Org can publish a release of their component.
+- This release is automatically pushed to the `develop` branch of the release repository by the metal-robot.
+- The push triggers a small release integration test through the mini-lab.
+- To contribute components that are not directly part of the release vector, a pull request must be made against the `develop` branch of the release repository. Release maintainers may push directly to the `develop` branch.
+- The release maintainers can `/freeze` the `develop` branch, effectively stopping the metal-robot from pushing component releases to this branch.
+- The `develop` branch is tagged by a release maintainer with a `-rc.x` suffix to create a __release candidate__.
+- The release candidate must pass a large integration test suite on a real environment, which is currently run by FI-TS. It tests the entire machine provisioning engine including the integration with Gardener, the deployment, metal-images and Kubernetes conformance tests.
+- If the integration tests pass, the PR of the `develop` branch must be approved by at least two release maintainers.
+- A release is created via Github releases, including all release notes, with a tag on the `main` branch.
+
 If you want, you can sign up at our Slack channel where we are announcing every new release. Often, we provide additional information for metal-stack administrators and adopters at this place, too.
 
 ## Update Policy
 
-For new features and breaking changes we create a new minor release of metal-stack. For every minor release we present excerpts of the changes in a corresponding blog article published on metal-stack.io. It is not necessary to cycle through the patch releases if you depend on the pure metal-stack components.
+For new features and breaking changes we create a new minor release of metal-stack.
+For every minor release we present excerpts of the changes in a corresponding blog article published on metal-stack.io.
+
+It is not strictly necessary to cycle through the patch releases if you depend on the pure metal-stack components.
+However, it is important to go through all the patch releases and apply all required actions from the release notes.
+Therefore, we recommend to just install every patch release one by one in order to minimize possible problems during the update process.
 
-In case you depend on the Gardener integration though, especially when using metal-stack roles for deploying Gardener, it may be necessary to cycle through the patch release versions of our metal-stack releases. We regularly increment our Gardener dependency version by version which is the recommended way to update Gardener.
+In case you depend on the Gardener integration, especially when using metal-stack roles for deploying Gardener, we strongly recommend installing every patch release version.
+We increment our Gardener dependency version by version following the Gardener update policy. Jumping versions may lead to severe problems with the installation and should only be done if you really know what you are doing.
 
-!!! warning
+!!! info
 
-    If you use the Gardener integration of metal-stack do not skip patch releases.
+    If you use the Gardener integration of metal-stack do not skip any patch releases. You may skip patch releases if you depend on metal-stack only, but we recommend to just deploy every patch release one by one for the best possible upgrade experience.
diff --git a/docs/src/overview/architecture.md b/docs/src/overview/architecture.md
@@ -123,3 +123,30 @@ Here is a video showing a screen capture of a machine's serial console while run
 <iframe src="https://www.youtube-nocookie.com/embed/3oEhInk6BaU" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 </div>
 ```
+
+## Offline Resilience
+
+It is possible to use metal-stack without any external network dependencies by integrating your own DNS and NTP configuration into the stack. This feature is great for workloads requiring strong independence and reliability. Even in case of an internet connection failure, your infrastructure remains operational. Existing machines do not encounter any downtime as well as new machines can be provisioned. All you need to have in place is a DNS and NTP server configured and accessible for metal-stack.
+
+NTP servers need to be configured on the pixiecore and the metal-hammer microservices. This can be achieved by providing a list of NTP servers with the following Ansible variable through metal-roles:
+
+```yaml
+pixiecore_metal_hammer_ntp_servers: []
+```
+
+In the background, the pixiecore is taking the NTP servers and passing it via the `MetalConfig` to the metal-hammer. When booting bare-metal servers, the metal-hammer needs to configure NTP servers. It recognises the ones from the `MetalConfig` and configures itself accordingly.
+If no NTP servers are passed along, the following standard servers are used:
+
+- 0.de.pool.ntp.org
+- 1.de.pool.ntp.org
+- 2.de.pool.ntp.org
+
+Moreover, machine and firewall images need to be configured with your custom DNS and NTP servers. The customisation can be made via the fields `ntp_servers` an `dns_servers` and specifying a list of servers in the creation request for the machine or firewall.
+
+Within a partition default values for DNS and NTP servers can be configured. They are applied to all machines and firewalls within this partition, but can be replaced by specifying different ones inside the machine allocation request.
+
+Thus, for creating a partition as well as a machine or a firewall, the flags `dnsservers` and `ntpservers` can be provided within the `metalctl` command.
+
+In order to be fully offline resilient, make sure to check out `metal-image-cache-sync`. This component provides copies of `metal-images`, `metal-kernel` and `metal-hammer`.
+
+This feature is related to [MEP14](https://docs.metal-stack.io/dev/development/proposals/MEP14/README/).
diff --git a/docs/src/overview/hardware.md b/docs/src/overview/hardware.md
@@ -16,7 +16,7 @@ The following server types are officially supported and verified by the metal-st
 | Supermicro | SuperServer | 2029UZ-TN20R25M  | X11DPU         | stable      |
 | Supermicro | SuperServer | SYS-621C-TN12R   | X13DDW-A       | stable      |
 | Supermicro | Microcloud  | 5039MD8-H8TNR    | X11SDD-8C-F    | stable      |
-| Supermicro | Microcloud  | SYS-531MC-H8TNR  | X13SCD-F       | coming soon |
+| Supermicro | Microcloud  | SYS-531MC-H8TNR  | X13SCD-F       | stable      |
 | Supermicro | Microcloud  | 3015MR-H8TNR     | H13SRD-F       | coming soon |
 | Lenovo     | ThinkSystem | SD530            |                | alpha       |
 

diff --git a/docs/src/overview/isolated-kubernetes.md b/docs/src/overview/isolated-kubernetes.md
@@ -297,25 +297,23 @@ If a cluster is either configured with `restricted` or `forbidden`, the configur
 config.toml
 
 ```toml
-imports = ["/etc/containerd/conf.d/*.toml"]
+# Generated by os-extension-metal
 version = 2
+imports = ["/etc/containerd/conf.d/*.toml"]
 
+disabled_plugins = []
 [plugins."io.containerd.grpc.v1.cri".registry]
-  [plugins."io.containerd.grpc.v1.cri".reg
-    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
-      endpoint = ["https://some.private.registry"]
-    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."quay.io"]
-      endpoint = ["https://some.private.registry"]
-    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.lightbitslabs.com"]
-      endpoint = ["https://some.private.registry"]
-    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."eu.gcr.io"]
-      endpoint = ["https://some.private.registry"]
-    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."ghcr.io"]
-      endpoint = ["https://some.private.registry"]
-    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."registry.k8s.io"]
-      endpoint = ["https://some.private.registry"]
-    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."r.metal-stack.io"]
-      endpoint = ["https://some.private.registry"]
+  config_path = "/etc/containerd/certs.d"
+```
+
+And for every registry mirror an additional `certs.d/$HOST/hosts.yaml` will be created. This is in line with [Gardener's containerd Registry Configuration](https://gardener.cloud/docs/gardener/advanced/containerd-registry-configuration/).
+
+```toml
+# certs.d/docker.io/hosts.yaml
+
+server = "https://docker.io"
+[host."https://some.private.registry"]
+  capabilities = ["pull", "resolve"]
 ```
 
 DNS and NTP must also be adopted according to the configuration in the CloudProfile.