From 683432c3fb385ecfa86ba0cd36a94ecc02abb103 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Wed, 3 Jun 2026 19:37:41 +0100 Subject: [PATCH 01/20] Feat: restructure docs site using new info architecture Signed-off-by: thisisobate --- .../docs/latest/container-runtimes/_index.md | 10 - content/docs/latest/contribute/_index.md | 5 +- .../update-from-container-linux.md | 1 + .../bare-metal/booting-with-ipxe.md | 1 + .../bare-metal/booting-with-iso.md | 1 + .../bare-metal/booting-with-pxe.md | 1 + .../bare-metal/installing-to-disk.md | 1 + .../bare-metal/raspberry-pi.md | 2 + .../{installing => deploy}/cloud/akamai.md | 2 + .../{installing => deploy}/cloud/aws-ec2.md | 1 + .../{installing => deploy}/cloud/azure.md | 1 + .../{installing => deploy}/cloud/brightbox.md | 2 + .../cloud/digitalocean.md | 1 + .../{installing => deploy}/cloud/gcp.md | 1 + .../{installing => deploy}/cloud/hetzner.md | 1 + .../{installing => deploy}/cloud/openstack.md | 1 + .../{installing => deploy}/cloud/stackit.md | 1 + .../cloud/using-google-cloud-launcher.md | 1 + .../cloud}/vmware.md | 1 + .../virt-options}/eucalyptus.md | 1 + .../virt-options}/exoscale.md | 1 + .../virt-options}/notes-for-distributors.md | 1 + .../virt-options}/oraclecloud.md | 0 .../virt-options}/ovhcloud.md | 2 + .../virt-options}/proxmoxve.md | 2 + .../virt-options}/scaleway.md | 2 + .../virt-options}/vultr.md | 1 + .../{reference => devguide}/integrations.md | 0 .../kernel-modules.md | 1 + .../release-guide.md | 0 .../sdk-bootstrapping.md | 2 + .../sdk-building-production-images.md | 1 + .../sdk-disk-partitions.md | 1 + .../sdk-modifying-flatcar.md | 1 + .../sdk-tips-and-tricks.md | 1 + .../btrfs-troubleshooting.md | 1 + .../collecting-crash-logs.md | 1 + .../install-debugging-tools.md | 1 + .../debug => diagnostics}/manual-rollbacks.md | 1 + .../reading-the-system-log.md | 1 + .../butane}/configuration.md | 2 + .../butane}/examples.md | 2 + .../butane}/getting-started.md | 1 + .../cl-config/dynamic-data.md | 0 .../cl-config/examples.md | 0 .../cl-config/from-cloud-config.md | 0 .../cl-config/operators-notes.md | 0 .../cl-config/specification.md | 0 .../customize-image}/customize-the-image.md | 2 + .../ignition/boot-process.md | 1 + .../ignition/dynamic-data.md | 1 + .../ignition/network-configuration.md | 1 + .../ignition/specification.md | 2 + .../vms/hyper-v.md | 2 + .../vms/kubevirt.md | 2 + .../vms/libvirt.md | 1 + .../{installing => fb-provision}/vms/qemu.md | 1 + .../vms/vagrant.md | 0 .../vms/virtualbox.md | 1 + .../latest/getting-started/flatware-apps.md | 6 + .../advanced-service-config.md | 2 + .../learning-series/basics-and-testing.md | 2 + .../immutability-updates-rollbacks.md | 2 + .../learning-series/managing-storage.md | 2 + .../docs/latest/getting-started/quickstart.md | 6 + .../docs/latest/getting-started/roadmap.md | 6 + content/docs/latest/installing/_index.md | 224 ------------------ .../latest/installing/bare-metal/_index.md | 7 - .../docs/latest/installing/cloud/_index.md | 9 - .../installing/community-platforms/_index.md | 41 ---- .../customizing-the-image/_index.md | 7 - content/docs/latest/installing/vms/_index.md | 7 - content/docs/latest/learning-series/_index.md | 21 -- .../latest/migrating-from-coreos/_index.md | 49 ---- content/docs/latest/nebraska/_index.md | 13 - content/docs/latest/nebraska/i18n/_index.md | 31 --- .../clusters/architectures.md | 1 + .../clusters/booting-on-ecs.md | 1 + .../clusters/discovery.md | 1 + .../containers}/customizing-docker.md | 1 + .../getting-started-with-docker.md | 1 + .../containers}/incus.md | 2 + .../containers}/registry-authentication.md | 1 + .../switching-to-unified-cgroups.md | 1 + .../getting-started-with-kubernetes.md | 1 + .../high-availability-kubernetes.md | 2 + .../host-config}/adding-users.md | 1 + .../configuring-date-and-timezone.md | 1 + .../host-config}/drop-in-units.md | 1 + .../host-config}/environment-variables.md | 1 + .../host-config}/other-settings.md | 1 + .../host-config}/power-management.md | 1 + .../host-config}/timers.md | 1 + .../host-config}/using-nvidia.md | 2 + .../network}/ACPI.md | 2 + .../network}/configuring-dns.md | 1 + .../network}/network-config-with-networkd.md | 1 + .../network}/overlaybd-artifact-streaming.md | 2 + .../storage/adding-disk-space.md | 1 + .../storage/adding-swap.md | 1 + .../{setup => os-config}/storage/iscsi.md | 1 + .../{setup => os-config}/storage/lvm.md | 17 +- .../storage/mounting-storage.md | 1 + .../{setup => os-config}/storage/raid.md | 1 + .../{setup => os-config}/storage/zfs.md | 2 + .../systemd/getting-started.md | 1 + .../{setup => os-config}/systemd/systemctl.md | 1 + .../systemd/udev-rules.md | 1 + .../systemd/user-units.md | 2 + content/docs/latest/provisioning/_index.md | 9 - .../latest/provisioning/cl-config/_index.md | 154 ------------ .../provisioning/config-transpiler/_index.md | 80 ------- .../latest/provisioning/ignition/_index.md | 57 ----- .../docs/latest/provisioning/sysext/_index.md | 201 ---------------- .../latest/provisioning/terraform/_index.md | 141 ----------- content/docs/latest/reference/_index.md | 7 - .../reference/developer-guides/_index.md | 28 --- .../adding-certificate-authorities.md | 1 + .../cert-auth}/customize-etcd-unit.md | 1 + .../cert-auth}/customizing-sshd.md | 1 + .../generate-self-signed-certificates.md | 1 + .../security => security/cert-auth}/sssd.md | 1 + .../constants-and-ids.md | 1 + .../security => security/encryption}/luks.md | 2 + .../encryption}/selinux.md | 1 + .../security => security/hardening}/audit.md | 2 + .../hardening}/disabling-smt.md | 1 + .../security => security/hardening}/fips.md | 2 + .../hardening}/hardening-guide.md | 1 + ...trusted-computing-hardware-requirements.md | 1 + .../{reference => security}/supply-chain.md | 2 + content/docs/latest/setup/_index.md | 9 - content/docs/latest/setup/clusters/_index.md | 9 - .../docs/latest/setup/customization/_index.md | 11 - content/docs/latest/setup/debug/_index.md | 7 - content/docs/latest/setup/releases/_index.md | 10 - content/docs/latest/setup/security/_index.md | 11 - content/docs/latest/setup/storage/_index.md | 8 - content/docs/latest/setup/systemd/_index.md | 10 - content/docs/latest/sys-ext/sys-ext.md | 6 + .../nebraska/authorization.md | 2 + .../nebraska/autovacuum-tune.sql | 0 .../nebraska/development.md | 2 + .../nebraska/i18n/contributing.md | 2 + .../images/nebraska-hosts-packages.png | Bin .../nebraska/managing-updates.md | 2 + .../nebraska/migrate-to-older-version.md | 2 + .../nebraska/nebraska-logo.svg | 0 .../releases/switching-channels.md | 1 + .../releases/update-conf.md | 1 + .../releases/update-strategies.md | 1 + .../releases/verify-images.md | 1 + 152 files changed, 172 insertions(+), 1185 deletions(-) delete mode 100644 content/docs/latest/container-runtimes/_index.md rename content/docs/latest/{migrating-from-coreos => coreos-migration}/update-from-container-linux.md (98%) rename content/docs/latest/{installing => deploy}/bare-metal/booting-with-ipxe.md (99%) rename content/docs/latest/{installing => deploy}/bare-metal/booting-with-iso.md (98%) rename content/docs/latest/{installing => deploy}/bare-metal/booting-with-pxe.md (99%) rename content/docs/latest/{installing => deploy}/bare-metal/installing-to-disk.md (99%) rename content/docs/latest/{installing => deploy}/bare-metal/raspberry-pi.md (99%) rename content/docs/latest/{installing => deploy}/cloud/akamai.md (99%) rename content/docs/latest/{installing => deploy}/cloud/aws-ec2.md (99%) rename content/docs/latest/{installing => deploy}/cloud/azure.md (99%) rename content/docs/latest/{installing => deploy}/cloud/brightbox.md (98%) rename content/docs/latest/{installing => deploy}/cloud/digitalocean.md (99%) rename content/docs/latest/{installing => deploy}/cloud/gcp.md (99%) rename content/docs/latest/{installing => deploy}/cloud/hetzner.md (99%) rename content/docs/latest/{installing => deploy}/cloud/openstack.md (99%) rename content/docs/latest/{installing => deploy}/cloud/stackit.md (99%) rename content/docs/latest/{installing => deploy}/cloud/using-google-cloud-launcher.md (98%) rename content/docs/latest/{installing/community-platforms => deploy/cloud}/vmware.md (99%) rename content/docs/latest/{installing/community-platforms => deploy/virt-options}/eucalyptus.md (99%) rename content/docs/latest/{installing/community-platforms => deploy/virt-options}/exoscale.md (99%) rename content/docs/latest/{installing/community-platforms => deploy/virt-options}/notes-for-distributors.md (98%) rename content/docs/latest/{installing/community-platforms => deploy/virt-options}/oraclecloud.md (100%) rename content/docs/latest/{installing/community-platforms => deploy/virt-options}/ovhcloud.md (98%) rename content/docs/latest/{installing/community-platforms => deploy/virt-options}/proxmoxve.md (98%) rename content/docs/latest/{installing/community-platforms => deploy/virt-options}/scaleway.md (98%) rename content/docs/latest/{installing/community-platforms => deploy/virt-options}/vultr.md (99%) rename content/docs/latest/{reference => devguide}/integrations.md (100%) rename content/docs/latest/{reference/developer-guides => devguide}/kernel-modules.md (98%) rename content/docs/latest/{reference/developer-guides => devguide}/release-guide.md (100%) rename content/docs/latest/{reference/developer-guides => devguide}/sdk-bootstrapping.md (98%) rename content/docs/latest/{reference/developer-guides => devguide}/sdk-building-production-images.md (99%) rename content/docs/latest/{reference/developer-guides => devguide}/sdk-disk-partitions.md (98%) rename content/docs/latest/{reference/developer-guides => devguide}/sdk-modifying-flatcar.md (99%) rename content/docs/latest/{reference/developer-guides => devguide}/sdk-tips-and-tricks.md (99%) rename content/docs/latest/{setup/debug => diagnostics}/btrfs-troubleshooting.md (99%) rename content/docs/latest/{setup/debug => diagnostics}/collecting-crash-logs.md (99%) rename content/docs/latest/{setup/debug => diagnostics}/install-debugging-tools.md (98%) rename content/docs/latest/{setup/debug => diagnostics}/manual-rollbacks.md (99%) rename content/docs/latest/{setup/debug => diagnostics}/reading-the-system-log.md (98%) rename content/docs/latest/{provisioning/config-transpiler => fb-provision/butane}/configuration.md (99%) rename content/docs/latest/{provisioning/config-transpiler => fb-provision/butane}/examples.md (99%) rename content/docs/latest/{provisioning/config-transpiler => fb-provision/butane}/getting-started.md (98%) rename content/docs/latest/{provisioning => fb-provision}/cl-config/dynamic-data.md (100%) rename content/docs/latest/{provisioning => fb-provision}/cl-config/examples.md (100%) rename content/docs/latest/{provisioning => fb-provision}/cl-config/from-cloud-config.md (100%) rename content/docs/latest/{provisioning => fb-provision}/cl-config/operators-notes.md (100%) rename content/docs/latest/{provisioning => fb-provision}/cl-config/specification.md (100%) rename content/docs/latest/{installing/customizing-the-image => fb-provision/customize-image}/customize-the-image.md (99%) rename content/docs/latest/{provisioning => fb-provision}/ignition/boot-process.md (99%) rename content/docs/latest/{provisioning => fb-provision}/ignition/dynamic-data.md (98%) rename content/docs/latest/{provisioning => fb-provision}/ignition/network-configuration.md (97%) rename content/docs/latest/{provisioning => fb-provision}/ignition/specification.md (99%) rename content/docs/latest/{installing => fb-provision}/vms/hyper-v.md (99%) rename content/docs/latest/{installing => fb-provision}/vms/kubevirt.md (99%) rename content/docs/latest/{installing => fb-provision}/vms/libvirt.md (99%) rename content/docs/latest/{installing => fb-provision}/vms/qemu.md (99%) rename content/docs/latest/{installing => fb-provision}/vms/vagrant.md (100%) rename content/docs/latest/{installing => fb-provision}/vms/virtualbox.md (99%) create mode 100644 content/docs/latest/getting-started/flatware-apps.md rename content/docs/latest/{ => getting-started}/learning-series/advanced-service-config.md (99%) rename content/docs/latest/{ => getting-started}/learning-series/basics-and-testing.md (99%) rename content/docs/latest/{ => getting-started}/learning-series/immutability-updates-rollbacks.md (99%) rename content/docs/latest/{ => getting-started}/learning-series/managing-storage.md (99%) create mode 100644 content/docs/latest/getting-started/quickstart.md create mode 100644 content/docs/latest/getting-started/roadmap.md delete mode 100644 content/docs/latest/installing/_index.md delete mode 100644 content/docs/latest/installing/bare-metal/_index.md delete mode 100644 content/docs/latest/installing/cloud/_index.md delete mode 100644 content/docs/latest/installing/community-platforms/_index.md delete mode 100644 content/docs/latest/installing/customizing-the-image/_index.md delete mode 100644 content/docs/latest/installing/vms/_index.md delete mode 100644 content/docs/latest/learning-series/_index.md delete mode 100644 content/docs/latest/migrating-from-coreos/_index.md delete mode 100644 content/docs/latest/nebraska/_index.md delete mode 100644 content/docs/latest/nebraska/i18n/_index.md rename content/docs/latest/{setup => orchestrate}/clusters/architectures.md (99%) rename content/docs/latest/{setup => orchestrate}/clusters/booting-on-ecs.md (98%) rename content/docs/latest/{setup => orchestrate}/clusters/discovery.md (99%) rename content/docs/latest/{container-runtimes => orchestrate/containers}/customizing-docker.md (99%) rename content/docs/latest/{container-runtimes => orchestrate/containers}/getting-started-with-docker.md (99%) rename content/docs/latest/{container-runtimes => orchestrate/containers}/incus.md (99%) rename content/docs/latest/{container-runtimes => orchestrate/containers}/registry-authentication.md (99%) rename content/docs/latest/{container-runtimes => orchestrate/containers}/switching-to-unified-cgroups.md (99%) rename content/docs/latest/{container-runtimes => orchestrate/kubernetes}/getting-started-with-kubernetes.md (99%) rename content/docs/latest/{container-runtimes => orchestrate/kubernetes}/high-availability-kubernetes.md (99%) rename content/docs/latest/{setup/customization => os-config/host-config}/adding-users.md (98%) rename content/docs/latest/{setup/customization => os-config/host-config}/configuring-date-and-timezone.md (98%) rename content/docs/latest/{setup/systemd => os-config/host-config}/drop-in-units.md (99%) rename content/docs/latest/{setup/systemd => os-config/host-config}/environment-variables.md (99%) rename content/docs/latest/{setup/customization => os-config/host-config}/other-settings.md (99%) rename content/docs/latest/{setup/customization => os-config/host-config}/power-management.md (97%) rename content/docs/latest/{setup/systemd => os-config/host-config}/timers.md (98%) rename content/docs/latest/{setup/customization => os-config/host-config}/using-nvidia.md (99%) rename content/docs/latest/{setup/customization => os-config/network}/ACPI.md (97%) rename content/docs/latest/{setup/customization => os-config/network}/configuring-dns.md (98%) rename content/docs/latest/{setup/customization => os-config/network}/network-config-with-networkd.md (99%) rename content/docs/latest/{setup/customization => os-config/network}/overlaybd-artifact-streaming.md (98%) rename content/docs/latest/{setup => os-config}/storage/adding-disk-space.md (97%) rename content/docs/latest/{setup => os-config}/storage/adding-swap.md (99%) rename content/docs/latest/{setup => os-config}/storage/iscsi.md (98%) rename content/docs/latest/{setup => os-config}/storage/lvm.md (98%) rename content/docs/latest/{setup => os-config}/storage/mounting-storage.md (99%) rename content/docs/latest/{setup => os-config}/storage/raid.md (98%) rename content/docs/latest/{setup => os-config}/storage/zfs.md (95%) rename content/docs/latest/{setup => os-config}/systemd/getting-started.md (99%) rename content/docs/latest/{setup => os-config}/systemd/systemctl.md (98%) rename content/docs/latest/{setup => os-config}/systemd/udev-rules.md (98%) rename content/docs/latest/{setup => os-config}/systemd/user-units.md (97%) delete mode 100644 content/docs/latest/provisioning/_index.md delete mode 100644 content/docs/latest/provisioning/cl-config/_index.md delete mode 100644 content/docs/latest/provisioning/config-transpiler/_index.md delete mode 100644 content/docs/latest/provisioning/ignition/_index.md delete mode 100644 content/docs/latest/provisioning/sysext/_index.md delete mode 100644 content/docs/latest/provisioning/terraform/_index.md delete mode 100644 content/docs/latest/reference/_index.md delete mode 100644 content/docs/latest/reference/developer-guides/_index.md rename content/docs/latest/{setup/security => security/cert-auth}/adding-certificate-authorities.md (93%) rename content/docs/latest/{setup/customization => security/cert-auth}/customize-etcd-unit.md (98%) rename content/docs/latest/{setup/security => security/cert-auth}/customizing-sshd.md (99%) rename content/docs/latest/{setup/security => security/cert-auth}/generate-self-signed-certificates.md (99%) rename content/docs/latest/{setup/security => security/cert-auth}/sssd.md (96%) rename content/docs/latest/{reference => security}/constants-and-ids.md (97%) rename content/docs/latest/{setup/security => security/encryption}/luks.md (99%) rename content/docs/latest/{setup/security => security/encryption}/selinux.md (98%) rename content/docs/latest/{setup/security => security/hardening}/audit.md (95%) rename content/docs/latest/{setup/security => security/hardening}/disabling-smt.md (98%) rename content/docs/latest/{setup/security => security/hardening}/fips.md (99%) rename content/docs/latest/{setup/security => security/hardening}/hardening-guide.md (98%) rename content/docs/latest/{setup/security => security/hardening}/trusted-computing-hardware-requirements.md (97%) rename content/docs/latest/{reference => security}/supply-chain.md (99%) delete mode 100644 content/docs/latest/setup/_index.md delete mode 100644 content/docs/latest/setup/clusters/_index.md delete mode 100644 content/docs/latest/setup/customization/_index.md delete mode 100644 content/docs/latest/setup/debug/_index.md delete mode 100644 content/docs/latest/setup/releases/_index.md delete mode 100644 content/docs/latest/setup/security/_index.md delete mode 100644 content/docs/latest/setup/storage/_index.md delete mode 100644 content/docs/latest/setup/systemd/_index.md create mode 100644 content/docs/latest/sys-ext/sys-ext.md rename content/docs/latest/{ => updates-releases}/nebraska/authorization.md (99%) rename content/docs/latest/{ => updates-releases}/nebraska/autovacuum-tune.sql (100%) rename content/docs/latest/{ => updates-releases}/nebraska/development.md (99%) rename content/docs/latest/{ => updates-releases}/nebraska/i18n/contributing.md (98%) rename content/docs/latest/{ => updates-releases}/nebraska/images/nebraska-hosts-packages.png (100%) rename content/docs/latest/{ => updates-releases}/nebraska/managing-updates.md (99%) rename content/docs/latest/{ => updates-releases}/nebraska/migrate-to-older-version.md (91%) rename content/docs/latest/{ => updates-releases}/nebraska/nebraska-logo.svg (100%) rename content/docs/latest/{setup => updates-releases}/releases/switching-channels.md (99%) rename content/docs/latest/{setup => updates-releases}/releases/update-conf.md (98%) rename content/docs/latest/{setup => updates-releases}/releases/update-strategies.md (99%) rename content/docs/latest/{setup => updates-releases}/releases/verify-images.md (98%) diff --git a/content/docs/latest/container-runtimes/_index.md b/content/docs/latest/container-runtimes/_index.md deleted file mode 100644 index 09837b7e2..000000000 --- a/content/docs/latest/container-runtimes/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Container Runtimes -description: > - Flatcar Container Linux supports all of the popular methods for running - containers, and you can choose to interact with the containers at a - low-level, or use a higher level orchestration framework. These guides - can help you choose and use the different container runtimes supported. -weight: 60 ---- - diff --git a/content/docs/latest/contribute/_index.md b/content/docs/latest/contribute/_index.md index 03c4f5c2d..2e1cebf8c 100644 --- a/content/docs/latest/contribute/_index.md +++ b/content/docs/latest/contribute/_index.md @@ -1,12 +1,12 @@ --- title: How to Contribute content_type: contribute -weight: 130 +weight: 120 --- Flatcar documentation is released under the [Apache 2.0 License][asl], and we welcome contributions. Check out the [help-wanted tag][help-wanted] in this project's Issues list for good places to start participating. -Submit fixes and additions in the form of [GitHub *Pull Requests* (PRs)][pull-requests]. The general process is the typical git fork-branch-PR-review-merge cycle: +Submit fixes and additions in the form of [GitHub _Pull Requests_ (PRs)][pull-requests]. The general process is the typical git fork-branch-PR-review-merge cycle: 1. Fork this repository into your GitHub account 2. Make changes in a topic branch or your fork's `master` @@ -50,7 +50,6 @@ We happily accept accurate translations. Please send the documents as a pull req 2. Add an explanation about the translated document to the top of the file: "These documents were translated into Esperanto by Community Member and last updated on 2015-12-01. If you find inaccuracies or problems please file an issue on GitHub." - [asl]: https://github.com/flatcar/flatcar-docs/blob/main/LICENSE [flatcar-docs]: https://flatcar.org/docs/latest/ [help-wanted]: https://github.com/flatcar/Flatcar/labels/kind%2Fdocs diff --git a/content/docs/latest/migrating-from-coreos/update-from-container-linux.md b/content/docs/latest/coreos-migration/update-from-container-linux.md similarity index 98% rename from content/docs/latest/migrating-from-coreos/update-from-container-linux.md rename to content/docs/latest/coreos-migration/update-from-container-linux.md index 4a9c62293..d0dafa698 100644 --- a/content/docs/latest/migrating-from-coreos/update-from-container-linux.md +++ b/content/docs/latest/coreos-migration/update-from-container-linux.md @@ -3,6 +3,7 @@ title: Updating from CoreOS Container Linux linktitle: Updating from CoreOS weight: 10 aliases: + - /docs/latest/migrating-from-coreos/update-from-container-linux/ - ../os/update-from-container-linux --- diff --git a/content/docs/latest/installing/bare-metal/booting-with-ipxe.md b/content/docs/latest/deploy/bare-metal/booting-with-ipxe.md similarity index 99% rename from content/docs/latest/installing/bare-metal/booting-with-ipxe.md rename to content/docs/latest/deploy/bare-metal/booting-with-ipxe.md index f527fafbc..efdf93fdd 100644 --- a/content/docs/latest/installing/bare-metal/booting-with-ipxe.md +++ b/content/docs/latest/deploy/bare-metal/booting-with-ipxe.md @@ -3,6 +3,7 @@ title: Booting Flatcar Container Linux via iPXE linktitle: Booting via iPXE weight: 30 aliases: + - /docs/latest/installing/bare-metal/booting-with-ipxe/ - ../../os/booting-with-ipxe - ../../bare-metal/booting-with-ipxe --- diff --git a/content/docs/latest/installing/bare-metal/booting-with-iso.md b/content/docs/latest/deploy/bare-metal/booting-with-iso.md similarity index 98% rename from content/docs/latest/installing/bare-metal/booting-with-iso.md rename to content/docs/latest/deploy/bare-metal/booting-with-iso.md index fbc1d0365..f95d71a07 100644 --- a/content/docs/latest/installing/bare-metal/booting-with-iso.md +++ b/content/docs/latest/deploy/bare-metal/booting-with-iso.md @@ -3,6 +3,7 @@ title: Booting Flatcar Container Linux from an ISO linktitle: Booting from an ISO weight: 10 aliases: + - /docs/latest/installing/bare-metal/booting-with-iso/ - ../../os/booting-with-iso - ../../bare-metal/booting-with-iso --- diff --git a/content/docs/latest/installing/bare-metal/booting-with-pxe.md b/content/docs/latest/deploy/bare-metal/booting-with-pxe.md similarity index 99% rename from content/docs/latest/installing/bare-metal/booting-with-pxe.md rename to content/docs/latest/deploy/bare-metal/booting-with-pxe.md index d03b3795f..4398a2668 100644 --- a/content/docs/latest/installing/bare-metal/booting-with-pxe.md +++ b/content/docs/latest/deploy/bare-metal/booting-with-pxe.md @@ -3,6 +3,7 @@ title: Booting Flatcar Container Linux via PXE linktitle: Booting via PXE weight: 20 aliases: + - /docs/latest/installing/bare-metal/booting-with-pxe/ - ../../os/booting-with-pxe - ../../bare-metal/booting-with-pxe --- diff --git a/content/docs/latest/installing/bare-metal/installing-to-disk.md b/content/docs/latest/deploy/bare-metal/installing-to-disk.md similarity index 99% rename from content/docs/latest/installing/bare-metal/installing-to-disk.md rename to content/docs/latest/deploy/bare-metal/installing-to-disk.md index 8744dd7cc..62e0bcf16 100644 --- a/content/docs/latest/installing/bare-metal/installing-to-disk.md +++ b/content/docs/latest/deploy/bare-metal/installing-to-disk.md @@ -6,6 +6,7 @@ description: > a running system. weight: 40 aliases: + - /docs/latest/installing/bare-metal/installing-to-disk/ - ../../os/installing-to-disk - ../../bare-metal/installing-to-disk --- diff --git a/content/docs/latest/installing/bare-metal/raspberry-pi.md b/content/docs/latest/deploy/bare-metal/raspberry-pi.md similarity index 99% rename from content/docs/latest/installing/bare-metal/raspberry-pi.md rename to content/docs/latest/deploy/bare-metal/raspberry-pi.md index 32ea3c819..476096fa9 100644 --- a/content/docs/latest/installing/bare-metal/raspberry-pi.md +++ b/content/docs/latest/deploy/bare-metal/raspberry-pi.md @@ -2,6 +2,8 @@ title: Running Flatcar Container Linux on Raspberry Pi 4 linktitle: Running on Raspberry Pi 4 weight: 50 +aliases: + - /docs/latest/installing/bare-metal/raspberry-pi/ --- ### Hardware Requirements diff --git a/content/docs/latest/installing/cloud/akamai.md b/content/docs/latest/deploy/cloud/akamai.md similarity index 99% rename from content/docs/latest/installing/cloud/akamai.md rename to content/docs/latest/deploy/cloud/akamai.md index a16d161f8..37fb21ccb 100644 --- a/content/docs/latest/installing/cloud/akamai.md +++ b/content/docs/latest/deploy/cloud/akamai.md @@ -2,6 +2,8 @@ title: Running Flatcar on Akamai Connected Cloud (Linode) linktitle: Running on Akamai weight: 50 +aliases: + - /docs/latest/installing/cloud/akamai/ --- These instructions will walk you throug running Flatcar on [Akamai Connected diff --git a/content/docs/latest/installing/cloud/aws-ec2.md b/content/docs/latest/deploy/cloud/aws-ec2.md similarity index 99% rename from content/docs/latest/installing/cloud/aws-ec2.md rename to content/docs/latest/deploy/cloud/aws-ec2.md index 15bd2c2b0..73fd62529 100644 --- a/content/docs/latest/installing/cloud/aws-ec2.md +++ b/content/docs/latest/deploy/cloud/aws-ec2.md @@ -3,6 +3,7 @@ title: Running Flatcar Container Linux on AWS EC2 linktitle: Running on AWS EC2 weight: 10 aliases: + - /docs/latest/installing/cloud/aws-ec2/ - ../../os/booting-on-ec2 - ../../cloud-providers/booting-on-ec2 --- diff --git a/content/docs/latest/installing/cloud/azure.md b/content/docs/latest/deploy/cloud/azure.md similarity index 99% rename from content/docs/latest/installing/cloud/azure.md rename to content/docs/latest/deploy/cloud/azure.md index 536c1b86f..06dc2cd71 100644 --- a/content/docs/latest/installing/cloud/azure.md +++ b/content/docs/latest/deploy/cloud/azure.md @@ -3,6 +3,7 @@ title: Running Flatcar Container Linux on Microsoft Azure linktitle: Running on Microsoft Azure weight: 15 aliases: + - /docs/latest/installing/cloud/azure/ - ../../os/booting-on-azure - ../../cloud-providers/booting-on-azure --- diff --git a/content/docs/latest/installing/cloud/brightbox.md b/content/docs/latest/deploy/cloud/brightbox.md similarity index 98% rename from content/docs/latest/installing/cloud/brightbox.md rename to content/docs/latest/deploy/cloud/brightbox.md index 425256f15..1970dde08 100644 --- a/content/docs/latest/installing/cloud/brightbox.md +++ b/content/docs/latest/deploy/cloud/brightbox.md @@ -2,6 +2,8 @@ title: Running Flatcar on Brightbox linktitle: Running on Brightbox weight: 45 +aliases: + - /docs/latest/installing/cloud/brightbox/ --- These instructions will walk you through using Flatcar on Brightbox, importing a custom image, and running your first server using the command line interface. Please note that Brightbox is compatible with OpenStack: it is not a mistake if we refer to OpenStack images and specific variables. diff --git a/content/docs/latest/installing/cloud/digitalocean.md b/content/docs/latest/deploy/cloud/digitalocean.md similarity index 99% rename from content/docs/latest/installing/cloud/digitalocean.md rename to content/docs/latest/deploy/cloud/digitalocean.md index 642fa01d6..4ccde99cb 100644 --- a/content/docs/latest/installing/cloud/digitalocean.md +++ b/content/docs/latest/deploy/cloud/digitalocean.md @@ -3,6 +3,7 @@ title: Running Flatcar Container Linux on DigitalOcean linktitle: Running on DigitalOcean weight: 30 aliases: + - /docs/latest/installing/cloud/digitalocean/ - ../../os/booting-on-digitalocean - ../../cloud-providers/booting-on-digitalocean --- diff --git a/content/docs/latest/installing/cloud/gcp.md b/content/docs/latest/deploy/cloud/gcp.md similarity index 99% rename from content/docs/latest/installing/cloud/gcp.md rename to content/docs/latest/deploy/cloud/gcp.md index edc69a482..0ad65c527 100644 --- a/content/docs/latest/installing/cloud/gcp.md +++ b/content/docs/latest/deploy/cloud/gcp.md @@ -3,6 +3,7 @@ title: Running Flatcar Container Linux on Google Compute Engine linktitle: Running on Google Compute Engine weight: 20 aliases: + - /docs/latest/installing/cloud/gcp/ - ../../os/booting-on-google-compute-engine - ../../cloud-providers/booting-on-google-compute-engine --- diff --git a/content/docs/latest/installing/cloud/hetzner.md b/content/docs/latest/deploy/cloud/hetzner.md similarity index 99% rename from content/docs/latest/installing/cloud/hetzner.md rename to content/docs/latest/deploy/cloud/hetzner.md index ff6010bbe..c51ce19de 100644 --- a/content/docs/latest/installing/cloud/hetzner.md +++ b/content/docs/latest/deploy/cloud/hetzner.md @@ -3,6 +3,7 @@ title: Running Flatcar Container Linux on Hetzner linktitle: Running on Hetzner weight: 35 aliases: + - /docs/latest/installing/cloud/hetzner/ - ../../os/booting-on-hetzner - ../../cloud-providers/booting-on-hetzner --- diff --git a/content/docs/latest/installing/cloud/openstack.md b/content/docs/latest/deploy/cloud/openstack.md similarity index 99% rename from content/docs/latest/installing/cloud/openstack.md rename to content/docs/latest/deploy/cloud/openstack.md index 3e1fe1620..3526f4f1f 100644 --- a/content/docs/latest/installing/cloud/openstack.md +++ b/content/docs/latest/deploy/cloud/openstack.md @@ -3,6 +3,7 @@ title: Running Flatcar Container Linux on OpenStack linktitle: Running on OpenStack weight: 40 aliases: + - /docs/latest/installing/cloud/openstack/ - ../../os/booting-on-openstack - ../../cloud-providers/booting-on-openstack --- diff --git a/content/docs/latest/installing/cloud/stackit.md b/content/docs/latest/deploy/cloud/stackit.md similarity index 99% rename from content/docs/latest/installing/cloud/stackit.md rename to content/docs/latest/deploy/cloud/stackit.md index 07b66d4da..81d85c701 100644 --- a/content/docs/latest/installing/cloud/stackit.md +++ b/content/docs/latest/deploy/cloud/stackit.md @@ -3,6 +3,7 @@ title: Running Flatcar on STACKIT linktitle: Running on STACKIT weight: 55 aliases: + - /docs/latest/installing/cloud/stackit/ - ../../os/booting-on-stackit - ../../cloud-providers/booting-on-stackit --- diff --git a/content/docs/latest/installing/cloud/using-google-cloud-launcher.md b/content/docs/latest/deploy/cloud/using-google-cloud-launcher.md similarity index 98% rename from content/docs/latest/installing/cloud/using-google-cloud-launcher.md rename to content/docs/latest/deploy/cloud/using-google-cloud-launcher.md index 7fc0e3005..9db77ec66 100644 --- a/content/docs/latest/installing/cloud/using-google-cloud-launcher.md +++ b/content/docs/latest/deploy/cloud/using-google-cloud-launcher.md @@ -6,6 +6,7 @@ description: > Flatcar Container Linux on GCP weight: 21 aliases: + - /docs/latest/installing/cloud/using-google-cloud-launcher/ - ../../os/using-google-cloud-launcher - ../../cloud-providers/using-google-cloud-launcher --- diff --git a/content/docs/latest/installing/community-platforms/vmware.md b/content/docs/latest/deploy/cloud/vmware.md similarity index 99% rename from content/docs/latest/installing/community-platforms/vmware.md rename to content/docs/latest/deploy/cloud/vmware.md index 4d6b1d2f7..e8d6f082a 100644 --- a/content/docs/latest/installing/community-platforms/vmware.md +++ b/content/docs/latest/deploy/cloud/vmware.md @@ -3,6 +3,7 @@ title: Running Flatcar Container Linux on VMware linktitle: Running on VMware weight: 25 aliases: + - /docs/latest/installing/community-platforms/vmware/ - ../../os/booting-on-vmware - ../../cloud-providers/booting-on-vmware --- diff --git a/content/docs/latest/installing/community-platforms/eucalyptus.md b/content/docs/latest/deploy/virt-options/eucalyptus.md similarity index 99% rename from content/docs/latest/installing/community-platforms/eucalyptus.md rename to content/docs/latest/deploy/virt-options/eucalyptus.md index 353959e49..a5eb756fb 100644 --- a/content/docs/latest/installing/community-platforms/eucalyptus.md +++ b/content/docs/latest/deploy/virt-options/eucalyptus.md @@ -3,6 +3,7 @@ title: Running Flatcar Container Linux on Eucalyptus 3.4 linktitle: Running on Eucalyptus 3.4 weight: 35 aliases: + - /docs/latest/installing/community-platforms/eucalyptus/ - ../../os/booting-on-eucalyptus - ../../community-platforms/booting-on-eucalyptus --- diff --git a/content/docs/latest/installing/community-platforms/exoscale.md b/content/docs/latest/deploy/virt-options/exoscale.md similarity index 99% rename from content/docs/latest/installing/community-platforms/exoscale.md rename to content/docs/latest/deploy/virt-options/exoscale.md index b0f0a4416..0c7e7869d 100644 --- a/content/docs/latest/installing/community-platforms/exoscale.md +++ b/content/docs/latest/deploy/virt-options/exoscale.md @@ -3,6 +3,7 @@ title: Running Flatcar Container Linux on Exoscale linktitle: Running on Exoscale weight: 10 aliases: + - /docs/latest/installing/community-platforms/exoscale/ - ../../os/booting-on-exoscale - ../../community-platforms/booting-on-exoscale --- diff --git a/content/docs/latest/installing/community-platforms/notes-for-distributors.md b/content/docs/latest/deploy/virt-options/notes-for-distributors.md similarity index 98% rename from content/docs/latest/installing/community-platforms/notes-for-distributors.md rename to content/docs/latest/deploy/virt-options/notes-for-distributors.md index d7db82826..7c5253334 100644 --- a/content/docs/latest/installing/community-platforms/notes-for-distributors.md +++ b/content/docs/latest/deploy/virt-options/notes-for-distributors.md @@ -2,6 +2,7 @@ title: Notes for distributors weight: 50 aliases: + - /docs/latest/installing/community-platforms/notes-for-distributors/ - ../../os/notes-for-distributors - ../../bare-metal/notes-for-distributors --- diff --git a/content/docs/latest/installing/community-platforms/oraclecloud.md b/content/docs/latest/deploy/virt-options/oraclecloud.md similarity index 100% rename from content/docs/latest/installing/community-platforms/oraclecloud.md rename to content/docs/latest/deploy/virt-options/oraclecloud.md diff --git a/content/docs/latest/installing/community-platforms/ovhcloud.md b/content/docs/latest/deploy/virt-options/ovhcloud.md similarity index 98% rename from content/docs/latest/installing/community-platforms/ovhcloud.md rename to content/docs/latest/deploy/virt-options/ovhcloud.md index 19e484a63..cf8be61b6 100644 --- a/content/docs/latest/installing/community-platforms/ovhcloud.md +++ b/content/docs/latest/deploy/virt-options/ovhcloud.md @@ -2,6 +2,8 @@ title: Running Flatcar on OVHcloud linktitle: Running on OVHcloud weight: 15 +aliases: + - /docs/latest/installing/community-platforms/ovhcloud/ --- These instructions will walk you through using Flatcar on [OVHcloud][ovhcloud], importing an image, and running your first server using the OpenStack command line interface. Please note that OVHcloud is a community supported platform at the moment which means that the CI does not run on OpenStack images in OVHcloud environment. diff --git a/content/docs/latest/installing/community-platforms/proxmoxve.md b/content/docs/latest/deploy/virt-options/proxmoxve.md similarity index 98% rename from content/docs/latest/installing/community-platforms/proxmoxve.md rename to content/docs/latest/deploy/virt-options/proxmoxve.md index a30748c5b..198343be9 100644 --- a/content/docs/latest/installing/community-platforms/proxmoxve.md +++ b/content/docs/latest/deploy/virt-options/proxmoxve.md @@ -2,6 +2,8 @@ title: Running Flatcar Container Linux on Proxmox VE linktitle: Running on Proxmox VE weight: 40 +aliases: + - /docs/latest/installing/community-platforms/proxmoxve/ --- _Please note that Proxmox VE is not an officially supported platform at this time because the release tests don't run for it._ diff --git a/content/docs/latest/installing/community-platforms/scaleway.md b/content/docs/latest/deploy/virt-options/scaleway.md similarity index 98% rename from content/docs/latest/installing/community-platforms/scaleway.md rename to content/docs/latest/deploy/virt-options/scaleway.md index 6587249f6..19300892e 100644 --- a/content/docs/latest/installing/community-platforms/scaleway.md +++ b/content/docs/latest/deploy/virt-options/scaleway.md @@ -2,6 +2,8 @@ title: Running Flatcar on Scaleway linktitle: Running on Scaleway weight: 25 +aliases: + - /docs/latest/installing/community-platforms/scaleway/ --- These instructions will walk you through using Flatcar on [Scaleway][scaleway], importing an image, and running your first server using the command line interface. Please note that Scaleway is a community supported platform at the moment which means that the CI does not run on Scaleway images. diff --git a/content/docs/latest/installing/community-platforms/vultr.md b/content/docs/latest/deploy/virt-options/vultr.md similarity index 99% rename from content/docs/latest/installing/community-platforms/vultr.md rename to content/docs/latest/deploy/virt-options/vultr.md index 7dd93a704..08afe3e1b 100644 --- a/content/docs/latest/installing/community-platforms/vultr.md +++ b/content/docs/latest/deploy/virt-options/vultr.md @@ -3,6 +3,7 @@ title: Running Flatcar Container Linux on a Vultr VPS linktitle: Running on a Vultr VPS weight: 30 aliases: + - /docs/latest/installing/community-platforms/vultr/ - ../../os/booting-on-vultr - ../../community-platforms/booting-on-vultr --- diff --git a/content/docs/latest/reference/integrations.md b/content/docs/latest/devguide/integrations.md similarity index 100% rename from content/docs/latest/reference/integrations.md rename to content/docs/latest/devguide/integrations.md diff --git a/content/docs/latest/reference/developer-guides/kernel-modules.md b/content/docs/latest/devguide/kernel-modules.md similarity index 98% rename from content/docs/latest/reference/developer-guides/kernel-modules.md rename to content/docs/latest/devguide/kernel-modules.md index c69147922..26ed566b7 100644 --- a/content/docs/latest/reference/developer-guides/kernel-modules.md +++ b/content/docs/latest/devguide/kernel-modules.md @@ -2,6 +2,7 @@ title: Building custom kernel modules weight: 20 aliases: + - /docs/latest/reference/developer-guides/kernel-modules/ - ../../os/kernel-modules --- diff --git a/content/docs/latest/reference/developer-guides/release-guide.md b/content/docs/latest/devguide/release-guide.md similarity index 100% rename from content/docs/latest/reference/developer-guides/release-guide.md rename to content/docs/latest/devguide/release-guide.md diff --git a/content/docs/latest/reference/developer-guides/sdk-bootstrapping.md b/content/docs/latest/devguide/sdk-bootstrapping.md similarity index 98% rename from content/docs/latest/reference/developer-guides/sdk-bootstrapping.md rename to content/docs/latest/devguide/sdk-bootstrapping.md index 1a77ed978..1a65d1ca0 100644 --- a/content/docs/latest/reference/developer-guides/sdk-bootstrapping.md +++ b/content/docs/latest/devguide/sdk-bootstrapping.md @@ -1,6 +1,8 @@ --- title: SDK bootstrap process weight: 40 +aliases: + - /docs/latest/reference/developer-guides/sdk-bootstrapping/ --- ## Introduction diff --git a/content/docs/latest/reference/developer-guides/sdk-building-production-images.md b/content/docs/latest/devguide/sdk-building-production-images.md similarity index 99% rename from content/docs/latest/reference/developer-guides/sdk-building-production-images.md rename to content/docs/latest/devguide/sdk-building-production-images.md index 83f2c9bf0..cfd782a32 100644 --- a/content/docs/latest/reference/developer-guides/sdk-building-production-images.md +++ b/content/docs/latest/devguide/sdk-building-production-images.md @@ -2,6 +2,7 @@ title: Building production images weight: 10 aliases: + - /docs/latest/reference/developer-guides/sdk-building-production-images/ - ../../os/sdk-building-production-images --- diff --git a/content/docs/latest/reference/developer-guides/sdk-disk-partitions.md b/content/docs/latest/devguide/sdk-disk-partitions.md similarity index 98% rename from content/docs/latest/reference/developer-guides/sdk-disk-partitions.md rename to content/docs/latest/devguide/sdk-disk-partitions.md index d431cb450..dd3261dde 100644 --- a/content/docs/latest/reference/developer-guides/sdk-disk-partitions.md +++ b/content/docs/latest/devguide/sdk-disk-partitions.md @@ -2,6 +2,7 @@ title: Flatcar Container Linux disk layout weight: 50 aliases: + - /docs/latest/reference/developer-guides/sdk-disk-partitions/ - ../../os/sdk-disk-partitions --- diff --git a/content/docs/latest/reference/developer-guides/sdk-modifying-flatcar.md b/content/docs/latest/devguide/sdk-modifying-flatcar.md similarity index 99% rename from content/docs/latest/reference/developer-guides/sdk-modifying-flatcar.md rename to content/docs/latest/devguide/sdk-modifying-flatcar.md index 1ee40556a..4f97b1ea1 100644 --- a/content/docs/latest/reference/developer-guides/sdk-modifying-flatcar.md +++ b/content/docs/latest/devguide/sdk-modifying-flatcar.md @@ -2,6 +2,7 @@ title: Guide to building custom Flatcar images from source weight: 5 aliases: + - /docs/latest/reference/developer-guides/sdk-modifying-flatcar/ - ../../os/sdk-modifying-flatcar - ../../os/sdk-modifying-coreos --- diff --git a/content/docs/latest/reference/developer-guides/sdk-tips-and-tricks.md b/content/docs/latest/devguide/sdk-tips-and-tricks.md similarity index 99% rename from content/docs/latest/reference/developer-guides/sdk-tips-and-tricks.md rename to content/docs/latest/devguide/sdk-tips-and-tricks.md index 8fcfaad06..414335ea0 100644 --- a/content/docs/latest/reference/developer-guides/sdk-tips-and-tricks.md +++ b/content/docs/latest/devguide/sdk-tips-and-tricks.md @@ -2,6 +2,7 @@ title: Tips and tricks weight: 30 aliases: + - /docs/latest/reference/developer-guides/sdk-tips-and-tricks/ - ../../os/sdk-tips-and-tricks --- diff --git a/content/docs/latest/setup/debug/btrfs-troubleshooting.md b/content/docs/latest/diagnostics/btrfs-troubleshooting.md similarity index 99% rename from content/docs/latest/setup/debug/btrfs-troubleshooting.md rename to content/docs/latest/diagnostics/btrfs-troubleshooting.md index 2dbd8a583..9ff27dbe1 100644 --- a/content/docs/latest/setup/debug/btrfs-troubleshooting.md +++ b/content/docs/latest/diagnostics/btrfs-troubleshooting.md @@ -4,6 +4,7 @@ linktitle: Troubleshooting btrfs description: Tips and tricks for solving issues related to btrfs on Flatcar. weight: 30 aliases: + - /docs/latest/setup/debug/btrfs-troubleshooting/ - ../../os/btrfs-troubleshooting - ../../clusters/debug/btrfs-troubleshooting --- diff --git a/content/docs/latest/setup/debug/collecting-crash-logs.md b/content/docs/latest/diagnostics/collecting-crash-logs.md similarity index 99% rename from content/docs/latest/setup/debug/collecting-crash-logs.md rename to content/docs/latest/diagnostics/collecting-crash-logs.md index 7ac557d27..076f5c386 100644 --- a/content/docs/latest/setup/debug/collecting-crash-logs.md +++ b/content/docs/latest/diagnostics/collecting-crash-logs.md @@ -4,6 +4,7 @@ linktitle: Collecting crash logs description: How to use pstore to access crash logs. weight: 10 aliases: + - /docs/latest/setup/debug/collecting-crash-logs/ - ../../os/collecting-crash-logs - ../../clusters/debug/collecting-crash-logs --- diff --git a/content/docs/latest/setup/debug/install-debugging-tools.md b/content/docs/latest/diagnostics/install-debugging-tools.md similarity index 98% rename from content/docs/latest/setup/debug/install-debugging-tools.md rename to content/docs/latest/diagnostics/install-debugging-tools.md index 9ef633be5..e59b5446d 100644 --- a/content/docs/latest/setup/debug/install-debugging-tools.md +++ b/content/docs/latest/diagnostics/install-debugging-tools.md @@ -4,6 +4,7 @@ linktitle: Debugging tools description: How to use the Flatcar "toolbox" to debug problems. weight: 10 aliases: + - /docs/latest/setup/debug/install-debugging-tools/ - ../../os/install-debugging-tools - ../../clusters/debug/install-debugging-tools --- diff --git a/content/docs/latest/setup/debug/manual-rollbacks.md b/content/docs/latest/diagnostics/manual-rollbacks.md similarity index 99% rename from content/docs/latest/setup/debug/manual-rollbacks.md rename to content/docs/latest/diagnostics/manual-rollbacks.md index 5754b9b70..1f5d48d0a 100644 --- a/content/docs/latest/setup/debug/manual-rollbacks.md +++ b/content/docs/latest/diagnostics/manual-rollbacks.md @@ -4,6 +4,7 @@ linktitle: Manual version rollbacks description: How to manually rollback to a previous Flatcar version. weight: 20 aliases: + - /docs/latest/setup/debug/manual-rollbacks/ - ../../os/manual-rollbacks - ../../clusters/debug/manual-rollbacks --- diff --git a/content/docs/latest/setup/debug/reading-the-system-log.md b/content/docs/latest/diagnostics/reading-the-system-log.md similarity index 98% rename from content/docs/latest/setup/debug/reading-the-system-log.md rename to content/docs/latest/diagnostics/reading-the-system-log.md index a4327553b..d371741d5 100644 --- a/content/docs/latest/setup/debug/reading-the-system-log.md +++ b/content/docs/latest/diagnostics/reading-the-system-log.md @@ -3,6 +3,7 @@ title: Reading the system log description: How to use journalctl to understand what's going on. weight: 15 aliases: + - /docs/latest/setup/debug/reading-the-system-log/ - ../../os/reading-the-system-log --- diff --git a/content/docs/latest/provisioning/config-transpiler/configuration.md b/content/docs/latest/fb-provision/butane/configuration.md similarity index 99% rename from content/docs/latest/provisioning/config-transpiler/configuration.md rename to content/docs/latest/fb-provision/butane/configuration.md index 6f0441d82..a49075c55 100644 --- a/content/docs/latest/provisioning/config-transpiler/configuration.md +++ b/content/docs/latest/fb-provision/butane/configuration.md @@ -1,6 +1,8 @@ --- title: Butane Configuration Specification weight: 80 +aliases: + - /docs/latest/provisioning/config-transpiler/configuration/ --- The Butane Flatcar variant configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional: diff --git a/content/docs/latest/provisioning/config-transpiler/examples.md b/content/docs/latest/fb-provision/butane/examples.md similarity index 99% rename from content/docs/latest/provisioning/config-transpiler/examples.md rename to content/docs/latest/fb-provision/butane/examples.md index cbc70692d..fce0dae85 100644 --- a/content/docs/latest/provisioning/config-transpiler/examples.md +++ b/content/docs/latest/fb-provision/butane/examples.md @@ -2,6 +2,8 @@ title: Butane Config Examples linktitle: Examples weight: 20 +aliases: + - /docs/latest/provisioning/config-transpiler/examples/ --- Here you can find a bunch of simple examples for using Butane configs, with some explanations about what they do. The examples here are in no way comprehensive, for a full list of all the available fields check out the [Butane specification][spec]. diff --git a/content/docs/latest/provisioning/config-transpiler/getting-started.md b/content/docs/latest/fb-provision/butane/getting-started.md similarity index 98% rename from content/docs/latest/provisioning/config-transpiler/getting-started.md rename to content/docs/latest/fb-provision/butane/getting-started.md index ae93233b9..529e50e66 100644 --- a/content/docs/latest/provisioning/config-transpiler/getting-started.md +++ b/content/docs/latest/fb-provision/butane/getting-started.md @@ -2,6 +2,7 @@ title: Getting Started weight: 10 aliases: + - /docs/latest/provisioning/config-transpiler/getting-started/ - ../../container-linux-config-transpiler/doc/getting-started - ../../container-linux-config-transpiler/getting-started --- diff --git a/content/docs/latest/provisioning/cl-config/dynamic-data.md b/content/docs/latest/fb-provision/cl-config/dynamic-data.md similarity index 100% rename from content/docs/latest/provisioning/cl-config/dynamic-data.md rename to content/docs/latest/fb-provision/cl-config/dynamic-data.md diff --git a/content/docs/latest/provisioning/cl-config/examples.md b/content/docs/latest/fb-provision/cl-config/examples.md similarity index 100% rename from content/docs/latest/provisioning/cl-config/examples.md rename to content/docs/latest/fb-provision/cl-config/examples.md diff --git a/content/docs/latest/provisioning/cl-config/from-cloud-config.md b/content/docs/latest/fb-provision/cl-config/from-cloud-config.md similarity index 100% rename from content/docs/latest/provisioning/cl-config/from-cloud-config.md rename to content/docs/latest/fb-provision/cl-config/from-cloud-config.md diff --git a/content/docs/latest/provisioning/cl-config/operators-notes.md b/content/docs/latest/fb-provision/cl-config/operators-notes.md similarity index 100% rename from content/docs/latest/provisioning/cl-config/operators-notes.md rename to content/docs/latest/fb-provision/cl-config/operators-notes.md diff --git a/content/docs/latest/provisioning/cl-config/specification.md b/content/docs/latest/fb-provision/cl-config/specification.md similarity index 100% rename from content/docs/latest/provisioning/cl-config/specification.md rename to content/docs/latest/fb-provision/cl-config/specification.md diff --git a/content/docs/latest/installing/customizing-the-image/customize-the-image.md b/content/docs/latest/fb-provision/customize-image/customize-the-image.md similarity index 99% rename from content/docs/latest/installing/customizing-the-image/customize-the-image.md rename to content/docs/latest/fb-provision/customize-image/customize-the-image.md index 30ef1313b..dbecbce73 100644 --- a/content/docs/latest/installing/customizing-the-image/customize-the-image.md +++ b/content/docs/latest/fb-provision/customize-image/customize-the-image.md @@ -1,6 +1,8 @@ --- title: Customizing a Flatcar image weight: 30 +aliases: + - /docs/latest/installing/customizing-the-image/customize-the-image/ --- While [Ignition][ignition] cloud instance userdata is the preferred way of customizing an installation, it can be limiting when the customization concerns the kernel boot arguments or when no cloud instance userdata mechanism is in place. diff --git a/content/docs/latest/provisioning/ignition/boot-process.md b/content/docs/latest/fb-provision/ignition/boot-process.md similarity index 99% rename from content/docs/latest/provisioning/ignition/boot-process.md rename to content/docs/latest/fb-provision/ignition/boot-process.md index 60bb9ea8d..509620c8a 100644 --- a/content/docs/latest/provisioning/ignition/boot-process.md +++ b/content/docs/latest/fb-provision/ignition/boot-process.md @@ -3,6 +3,7 @@ title: Flatcar Container Linux startup process linktitle: Boot process overview weight: 10 aliases: + - /docs/latest/provisioning/ignition/boot-process/ - ../../ignition/boot-process --- diff --git a/content/docs/latest/provisioning/ignition/dynamic-data.md b/content/docs/latest/fb-provision/ignition/dynamic-data.md similarity index 98% rename from content/docs/latest/provisioning/ignition/dynamic-data.md rename to content/docs/latest/fb-provision/ignition/dynamic-data.md index c358a2bde..f6511b4a0 100644 --- a/content/docs/latest/provisioning/ignition/dynamic-data.md +++ b/content/docs/latest/fb-provision/ignition/dynamic-data.md @@ -2,6 +2,7 @@ title: Referencing dynamic data weight: 40 aliases: + - /docs/latest/provisioning/ignition/dynamic-data/ - ./metadata - ../../ignition/metadata --- diff --git a/content/docs/latest/provisioning/ignition/network-configuration.md b/content/docs/latest/fb-provision/ignition/network-configuration.md similarity index 97% rename from content/docs/latest/provisioning/ignition/network-configuration.md rename to content/docs/latest/fb-provision/ignition/network-configuration.md index b2dc209f2..e60a6881c 100644 --- a/content/docs/latest/provisioning/ignition/network-configuration.md +++ b/content/docs/latest/fb-provision/ignition/network-configuration.md @@ -2,6 +2,7 @@ title: Network configuration weight: 20 aliases: + - /docs/latest/provisioning/ignition/network-configuration/ - ../../ignition/network-configuration --- diff --git a/content/docs/latest/provisioning/ignition/specification.md b/content/docs/latest/fb-provision/ignition/specification.md similarity index 99% rename from content/docs/latest/provisioning/ignition/specification.md rename to content/docs/latest/fb-provision/ignition/specification.md index f42a35646..adfedbb7a 100644 --- a/content/docs/latest/provisioning/ignition/specification.md +++ b/content/docs/latest/fb-provision/ignition/specification.md @@ -2,6 +2,8 @@ title: Ignition Specification linktitle: Specification weight: 30 +aliases: + - /docs/latest/provisioning/ignition/specification/ --- Ignition uses a JSON format that is specified in several major versions: v1, v2 and v3 (which itself has minor versions like `2.3.0`). While v1 and v2 are still supported in Flatcar Container Linux, from version 3185.0.0, it's recommended to write new configuration with v3. diff --git a/content/docs/latest/installing/vms/hyper-v.md b/content/docs/latest/fb-provision/vms/hyper-v.md similarity index 99% rename from content/docs/latest/installing/vms/hyper-v.md rename to content/docs/latest/fb-provision/vms/hyper-v.md index 10c98b01d..12988d258 100644 --- a/content/docs/latest/installing/vms/hyper-v.md +++ b/content/docs/latest/fb-provision/vms/hyper-v.md @@ -2,6 +2,8 @@ title: Running Flatcar Container Linux on Hyper-V linktitle: Running on Hyper-V weight: 50 +aliases: + - /docs/latest/installing/vms/hyper-v/ --- _While we always welcome community contributions and fixes, please note that Hyper-V is not an officially supported platform at this time because the release tests don't run for it. (See the [platform overview](/#installing-flatcar).)_ diff --git a/content/docs/latest/installing/vms/kubevirt.md b/content/docs/latest/fb-provision/vms/kubevirt.md similarity index 99% rename from content/docs/latest/installing/vms/kubevirt.md rename to content/docs/latest/fb-provision/vms/kubevirt.md index 6f63cca59..3bb16f6e0 100644 --- a/content/docs/latest/installing/vms/kubevirt.md +++ b/content/docs/latest/fb-provision/vms/kubevirt.md @@ -2,6 +2,8 @@ title: Running Flatcar Container Linux on KubeVirt linktitle: Running on KubeVirt weight: 60 +aliases: + - /docs/latest/installing/vms/kubevirt/ --- _While we always welcome community contributions and fixes, please note that KubeVirt is not an officially supported platform at this time because the release tests don't run for it. (See the [platform overview](/#installing-flatcar).)_ diff --git a/content/docs/latest/installing/vms/libvirt.md b/content/docs/latest/fb-provision/vms/libvirt.md similarity index 99% rename from content/docs/latest/installing/vms/libvirt.md rename to content/docs/latest/fb-provision/vms/libvirt.md index 995bfa826..7bacd7df1 100644 --- a/content/docs/latest/installing/vms/libvirt.md +++ b/content/docs/latest/fb-provision/vms/libvirt.md @@ -3,6 +3,7 @@ title: Running Flatcar Container Linux on libvirt linktitle: Running on libvirt weight: 20 aliases: + - /docs/latest/installing/vms/libvirt/ - ../../os/booting-with-libvirt - ../../cloud-providers/booting-with-libvirt --- diff --git a/content/docs/latest/installing/vms/qemu.md b/content/docs/latest/fb-provision/vms/qemu.md similarity index 99% rename from content/docs/latest/installing/vms/qemu.md rename to content/docs/latest/fb-provision/vms/qemu.md index d2817d25c..42aaffd48 100644 --- a/content/docs/latest/installing/vms/qemu.md +++ b/content/docs/latest/fb-provision/vms/qemu.md @@ -2,6 +2,7 @@ title: Running on QEMU weight: 10 aliases: + - /docs/latest/installing/vms/qemu/ - ../../os/booting-with-qemu - ../../cloud-providers/booting-with-qemu --- diff --git a/content/docs/latest/installing/vms/vagrant.md b/content/docs/latest/fb-provision/vms/vagrant.md similarity index 100% rename from content/docs/latest/installing/vms/vagrant.md rename to content/docs/latest/fb-provision/vms/vagrant.md diff --git a/content/docs/latest/installing/vms/virtualbox.md b/content/docs/latest/fb-provision/vms/virtualbox.md similarity index 99% rename from content/docs/latest/installing/vms/virtualbox.md rename to content/docs/latest/fb-provision/vms/virtualbox.md index 67854ed21..d7ce3cf41 100644 --- a/content/docs/latest/installing/vms/virtualbox.md +++ b/content/docs/latest/fb-provision/vms/virtualbox.md @@ -2,6 +2,7 @@ title: Running on VirtualBox weight: 30 aliases: + - /docs/latest/installing/vms/virtualbox/ - ../../os/booting-on-virtualbox - ../../cloud-providers/booting-on-virtualbox --- diff --git a/content/docs/latest/getting-started/flatware-apps.md b/content/docs/latest/getting-started/flatware-apps.md new file mode 100644 index 000000000..0e33b1267 --- /dev/null +++ b/content/docs/latest/getting-started/flatware-apps.md @@ -0,0 +1,6 @@ +--- +title: Flatware Apps +weight: 20 +description: > + Example applications for Flatcar Container Linux. +--- diff --git a/content/docs/latest/learning-series/advanced-service-config.md b/content/docs/latest/getting-started/learning-series/advanced-service-config.md similarity index 99% rename from content/docs/latest/learning-series/advanced-service-config.md rename to content/docs/latest/getting-started/learning-series/advanced-service-config.md index 88fceefbe..a1fc28160 100644 --- a/content/docs/latest/learning-series/advanced-service-config.md +++ b/content/docs/latest/getting-started/learning-series/advanced-service-config.md @@ -3,6 +3,8 @@ title: "Flatcar Self-Paced Learning Series: Advanced Provisioning Configuration" linktitle: Advanced Configuration weight: 2 author: Lexi Nadolski, Thilo Fromm +aliases: + - /docs/latest/learning-series/advanced-service-config/ --- Building on the first session, we’ll dive into Butane configuration and deploy a more elaborate webpage. diff --git a/content/docs/latest/learning-series/basics-and-testing.md b/content/docs/latest/getting-started/learning-series/basics-and-testing.md similarity index 99% rename from content/docs/latest/learning-series/basics-and-testing.md rename to content/docs/latest/getting-started/learning-series/basics-and-testing.md index 531a59e75..aed5e2792 100644 --- a/content/docs/latest/learning-series/basics-and-testing.md +++ b/content/docs/latest/getting-started/learning-series/basics-and-testing.md @@ -3,6 +3,8 @@ title: "Flatcar Self-Paced Learning Series: Basic Operation and Local Testing" linktitle: Basic Configuration and Testing weight: 1 author: Lexi Nadolski, Thilo Fromm +aliases: + - /docs/latest/learning-series/basics-and-testing/ --- Flatcar does only one thing: it runs container workloads. diff --git a/content/docs/latest/learning-series/immutability-updates-rollbacks.md b/content/docs/latest/getting-started/learning-series/immutability-updates-rollbacks.md similarity index 99% rename from content/docs/latest/learning-series/immutability-updates-rollbacks.md rename to content/docs/latest/getting-started/learning-series/immutability-updates-rollbacks.md index 5e542d434..3c6812f0d 100644 --- a/content/docs/latest/learning-series/immutability-updates-rollbacks.md +++ b/content/docs/latest/getting-started/learning-series/immutability-updates-rollbacks.md @@ -3,6 +3,8 @@ title: "Flatcar Self-Paced Learning Series: Immutable OS, Boot Process, In‐Pla linktitle: Updates, Roll-Backs, Immutability weight: 5 author: Lexi Nadolski, Thilo Fromm +aliases: + - /docs/latest/learning-series/immutability-updates-rollbacks/ --- In this session, we’ll do a deep dive into Flatcar's immutability and partition layout, and dissect the operating system's start-up process. diff --git a/content/docs/latest/learning-series/managing-storage.md b/content/docs/latest/getting-started/learning-series/managing-storage.md similarity index 99% rename from content/docs/latest/learning-series/managing-storage.md rename to content/docs/latest/getting-started/learning-series/managing-storage.md index 2c1cf2897..751fe19c6 100644 --- a/content/docs/latest/learning-series/managing-storage.md +++ b/content/docs/latest/getting-started/learning-series/managing-storage.md @@ -3,6 +3,8 @@ title: "Flatcar Self-Paced Learning Series: Managing Storage" linktitle: Managing Storage weight: 3 author: Lexi Nadolski, Thilo Fromm +aliases: + - /docs/latest/learning-series/managing-storage/ --- This session discusses handling additional storage, and customising the file system type used for the root filesystem. diff --git a/content/docs/latest/getting-started/quickstart.md b/content/docs/latest/getting-started/quickstart.md new file mode 100644 index 000000000..0375c3a41 --- /dev/null +++ b/content/docs/latest/getting-started/quickstart.md @@ -0,0 +1,6 @@ +--- +title: Quickstart +weight: 5 +description: > + Get up and running quickly with Flatcar Container Linux. +--- diff --git a/content/docs/latest/getting-started/roadmap.md b/content/docs/latest/getting-started/roadmap.md new file mode 100644 index 000000000..2786a38dd --- /dev/null +++ b/content/docs/latest/getting-started/roadmap.md @@ -0,0 +1,6 @@ +--- +title: Roadmap +weight: 10 +description: > + Flatcar Container Linux development roadmap. +--- diff --git a/content/docs/latest/installing/_index.md b/content/docs/latest/installing/_index.md deleted file mode 100644 index 86fedf084..000000000 --- a/content/docs/latest/installing/_index.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -title: Getting Started with Flatcar Container Linux -linktitle: Installing -weight: 2 -aliases: - - os/quickstart - - quickstart ---- - -This guide aims to get you up and running in a few minutes. -We'll cover -- concepts, configuration, and provisioning -- writing a basic Flatcar configuration and testing it locally with qemu -- further reading - where to go from here after learning the basics - -### Concepts, Configuration, and Provisioning - -Flatcar Container Linux is configured at _provisioning time_. -There are two configuration languages to set up Flatcar, aimed at different use cases: -- [Butane Config][butane-configs] Butane is human-readable / writable YAML and must be converted (transpiled) into Ignition V3 config before Flatcar can use it. It's the successor of [Container Linux Config][cl-configs] which is also still supported (Butane is not supported for LTS-2022). -- [Ignition config][ignition] is machine-readable JSON fed to Flatcar's ignition service. - Ignition is Flatcars "installation service" which configures a Flatcar instance during provisioning. - The config file is passed via the "custom data" or "user data" option of cloud providers, and can be supplied by various mechanisms to private cloud VMs and bare metal. - Ignition config is rarely written by a human; it's usually generated by provisioning automation or transpiled from user-written Butane. - -Use Butane to customise your Flatcar deployment, e.g. to -- add custom users and groups -- create and manage storage devices, file systems, and swap, and create custom files -- customise automatic updates and define reboot windows -- create custom network(d) configurations and systemd units - - Want to e.g. run a custom operation or start a service each time the instance boots? - Define a custom [systemd unit][systemd] via Butane. -All above tasks only take a few lines of YAML and are covered in our [Butane examples][butane-examples]. -For a comprehensive discussion of all options available in Butane have a look at the [Butane specification][butane-spec]. - -To convert Butane into machine-readable Ignition config, just download the latest release of [Butane][butane]. Alternatively, you can use the up-to-date [container image][container-image] with `docker run --rm -i quay.io/coreos/butane:latest`. - -Then, after converting Butane to Ignition config, pass the Ignition config along when provisioning your instance(s). -The config is then passed via "user data" / "custom data" or similar means to the provisioning logic. - -#### Writing your first config and testing it locally in a qemu VM - -The way from a small [Butane Config YAML][butane-configs] or [Ignition JSON][ignition] file to a local [QEMU VM][qemu-docs] on your laptop is not far. -Here we will create a systemd service that starts an NGINX container as example configuration for the VM. -This is a good starting point for you to modify the Butane YAML file (or the Ignition JSON file) and test it by provisioning a temporary QEMU VM. -This should work on most Linux systems and assumes you have an SSH key set up for ssh-agent. - -First download the Flatcar QEMU image and the helper script to start it with QEMU but don't run it yet. - -AMD64: -```shell -wget https://stable.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu.sh -chmod +x flatcar_production_qemu.sh -wget https://stable.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu_image.img -``` -ARM64: -```shell -wget https://alpha.release.flatcar-linux.net/arm64-usr/current/flatcar_production_qemu_uefi.sh -chmod +x flatcar_production_qemu_uefi.sh -wget https://alpha.release.flatcar-linux.net/arm64-usr/current/flatcar_production_qemu_uefi_image.img -wget https://alpha.release.flatcar-linux.net/arm64-usr/current/flatcar_production_qemu_uefi_efi_vars.qcow2 -wget https://alpha.release.flatcar-linux.net/arm64-usr/current/flatcar_production_qemu_uefi_efi_code.qcow2 -``` -For Ignition configurations to be recognized we have to make sure that we always boot an unmodified fresh image because Ignition only runs on first boot. -Therefore, before trying to use an Ignition config we will always discard the image modifications by using a fresh copy. -You can already boot the image with `./flatcar_production_qemu.sh` and have a look around in the OS through the QEMU VGA console - you can close the QEMU window or stop the script with `Ctrl-C`. -```shell -mv flatcar_production_qemu_image.img flatcar_production_qemu_image.img.fresh -# If you want to have a first look, boot it and wait for the autologin to give you a prompt: -cp -i --reflink=auto flatcar_production_qemu_image.img.fresh flatcar_production_qemu_image.img -``` - -Now we will provision the VM on first boot through Ignition. -Instead of writing the JSON config we use Butane YAML and transpile it. -Save the following Butane YAML file as `cl.yaml` (or another name). -It contains directives for setting up a systemd service that runs an NGINX Docker container: - -```yaml -variant: flatcar -version: 1.0.0 -systemd: - units: - - name: nginx.service - enabled: true - contents: | - [Unit] - Description=NGINX example - After=docker.service - Requires=docker.service - [Service] - TimeoutStartSec=0 - ExecStartPre=-/usr/bin/docker rm --force nginx1 - ExecStart=/usr/bin/docker run --name nginx1 --pull always --log-driver=journald --net host docker.io/nginx:1 - ExecStop=/usr/bin/docker stop nginx1 - Restart=always - RestartSec=5s - [Install] - WantedBy=multi-user.target -``` - -Before we can use it we have to transpile the Butane YAML to Ignition JSON: - -```shell -cat cl.yaml | docker run --rm -i quay.io/coreos/butane:latest > ignition.json -``` - -You can also skip this step and copy the resulting JSON file from here to `ignition.json` (or another name): - -``` -{ - "ignition": { - "version": "3.3.0" - }, - "systemd": { - "units": [ - { - "contents": "[Unit]\nDescription=NGINX example\nAfter=docker.service\nRequires=docker.service\n[Service]\nTimeoutStartSec=0\nExecStartPre=-/usr/bin/docker rm --force nginx1\nExecStart=/usr/bin/docker run --name nginx1 --pull always --net host docker.io/nginx:1\nExecStop=/usr/bin/docker stop nginx1\nRestart=always\nRestartSec=5s\n[Install]\nWantedBy=multi-user.target\n", - "enabled": true, - "name": "nginx.service" - } - ] - } -} -``` - -The final step is to boot the VM and make the Ignition configuration available to it. -As said, the provisioning will only be done on first boot and if you want your (changed) Ignition configuration to be used, you have to boot from a fresh copy. -You can repeat these combined steps as often as you want to test your Ignition changes. - -```shell -# Make sure we boot a fresh copy: -cp -i --reflink=auto flatcar_production_qemu_image.img.fresh flatcar_production_qemu_image.img -./flatcar_production_qemu.sh -i ignition.json -# Log in via SSH in a new terminal tab: -ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -p 2222 core@127.0.0.1 -# Check that NGINX is running: -systemctl status nginx -curl http://localhost/ -``` - -_NOTE_: For SSH access, you can also use the `~/.ssh/config` provided in the [QEMU][qemu-ssh] section then simply `ssh flatcar` or `scp my-file flatcar:/home/core` to send a file on the instance over SSH. - -If you have trouble SSHing into the VM, `./flatcar_production_qemu.sh` might have failed to auto-detect your ssh key. -If that happens try with a user-supplied SSH key using the yaml snippet below. -Alternatively, you can interact with the VM via the VGA console - the console has auto-login enabled and drops right into a shell. - -You can reboot and stop the VM if you like - when you start it later with a plain `./flatcar_production_qemu.sh` then our systemd unit will take care of starting NGINX on each boot. -Note that the ignition config will only be processed on the very first boot - that's why we made a copy, so now we can restore our OS image from the pristine copy for successive experiments with Butane. - -As listed in the introduction above there are numerous options available for configuring Flatcar just the way you need it. -For instance, you can specify a custom SSH key instead of your default one from your ssh-agent or from `~/.ssh/` in the Butane config, by adding this section to your YAML file: -```yaml -variant: flatcar -version: 1.0.0 -passwd: - users: - - name: core - ssh_authorized_keys: - - ssh-rsa AAAAB......xyz email@host.net -``` - -Afterwards, transpile it again to Ignition JSON, overwrite `flatcar_production_qemu_image.img` with the fresh image file, and pass the ignition config to `./flatcar_production_qemu.sh` once again. - - -### On automatic updates - -Flatcar has automatic updates enabled by default. -Flatcar instances will download and stage (in the background) new OS versions as well as reboot into the updated OS when a new update becomes available. -To change this default - for instance, to define reboot windows or even disable reboots - check out the [update strategies][update-strategies] doc. -To disable downloading updates altogether either disable the `update-engine` service via a user-supplied systemd config, or use an invalid URL in the `SERVER` field of [`update.conf`][update-conf]. - - -### More on configuring and operating Flatcar Container Linux - -Our [Flatcar learning series][learning-series] has in-depth coverage of specific areas of using Flatcar. - -The documentation includes a whole section on configuration, operation, and maintenance. -Have a look at the [setup guide][setup] for more information. - -### Further reading: Platform / vendor specific information - -Check out the guides on [running Flatcar Container Linux][running-container-linux] on most cloud providers: -* [EC2][ec2-docs] -* [Azure][azure-docs] -* [GCE][gce-docs] -virtualization platforms / private clouds: -* [Vagrant][vagrant-docs] -* [VMware][vmware-docs] -* [VirtualBox][virtualbox-docs] -* [QEMU/KVM][qemu-docs]/[libVirt][libvirt-docs] -and bare metal servers: -* [PXE][pxe-docs] -* [iPXE][ipxe-docs] -* [ISO][iso-docs] -* [Installer][install-docs] - -With any of these guides you will have machines up and running in a few minutes. - -[learning-series]: ../learning-series -[update-strategies]: ../setup/releases/update-strategies -[update-conf]: ../setup/releases/update-conf -[setup]: ../setup -[running-container-linux]: ../#installing-flatcar -[ec2-docs]: cloud/aws-ec2 -[azure-docs]: cloud/azure -[gce-docs]: cloud/gcp -[vagrant-docs]: vms/vagrant -[vmware-docs]: community-platforms/vmware -[virtualbox-docs]: vms/virtualbox -[qemu-docs]: vms/qemu -[qemu-ssh]: vms/qemu#ssh-config -[libvirt-docs]: vms/libvirt -[pxe-docs]: bare-metal/booting-with-pxe -[ipxe-docs]: bare-metal/booting-with-ipxe -[iso-docs]: bare-metal/booting-with-iso -[install-docs]: bare-metal/installing-to-disk -[ignition]: ../provisioning/ignition/ -[cl-configs]: ../provisioning/cl-config -[butane-configs]: ../provisioning/config-transpiler -[butane-examples]: ../provisioning/config-transpiler/examples -[butane-spec]: ../provisioning/config-transpiler/configuration -[systemd]: ../setup/systemd/getting-started -[container-image]: https://quay.io/repository/coreos/butane -[butane]: https://github.com/coreos/butane/releases diff --git a/content/docs/latest/installing/bare-metal/_index.md b/content/docs/latest/installing/bare-metal/_index.md deleted file mode 100644 index ef6271d0f..000000000 --- a/content/docs/latest/installing/bare-metal/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Bare Metal -weight: 30 -description: This section provides information and guidance on running Flatcar instances in bare-metal environments. -aliases: - - ../bare-metal ---- diff --git a/content/docs/latest/installing/cloud/_index.md b/content/docs/latest/installing/cloud/_index.md deleted file mode 100644 index ee8a83718..000000000 --- a/content/docs/latest/installing/cloud/_index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Cloud Providers -weight: 10 -description: > - This section provides information and guidance on running Flatcar - instances in different cloud environments. -aliases: - - ../cloud-providers ---- diff --git a/content/docs/latest/installing/community-platforms/_index.md b/content/docs/latest/installing/community-platforms/_index.md deleted file mode 100644 index 1ec500cd4..000000000 --- a/content/docs/latest/installing/community-platforms/_index.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Community supported platforms -weight: 40 -aliases: - - ../os/community-platforms - - ../community-platforms ---- - -The Flatcar Container Linux community has provided support for Flatcar Container Linux on a number of platforms beyond those [officially supported][official-support] (i.e, fully covered in the automated tests) by Kinvolk. - - - -The platforms and providers listed below each provide support and documentation for running Flatcar Container Linux: - -## Cloud providers - -* [Exoscale][exoscale] -* [OVHcloud][ovhcloud] -* [OracleCloud][oraclecloud] -* [Scaleway][scaleway] -* [VMWare][vmware] -* [Vultr VPS][vultr] - -## Other providers - -* [Eucalyptus][eucalyptus] -* [Proxmox VE][proxmoxve] -* [Vagrant][vagrant] -* [VirtualBox][virtualbox] - -[exoscale]: exoscale -[vultr]: vultr -[eucalyptus]: eucalyptus -[scaleway]: scaleway -[vagrant]: ../vms/vagrant -[virtualbox]: ../vms/virtualbox -[official-support]: ../../ -[ovhcloud]: ovhcloud -[proxmoxve]: proxmoxve -[vmware]: vmware -[oraclecloud]: oraclecloud diff --git a/content/docs/latest/installing/customizing-the-image/_index.md b/content/docs/latest/installing/customizing-the-image/_index.md deleted file mode 100644 index 7d8c2e170..000000000 --- a/content/docs/latest/installing/customizing-the-image/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Customizing the image -description: > - This section provides information and guidance on customizing - Flatcar images by placing files on the root or OEM filesystem or embedding an Ignition config. -weight: 35 ---- diff --git a/content/docs/latest/installing/vms/_index.md b/content/docs/latest/installing/vms/_index.md deleted file mode 100644 index fd010d100..000000000 --- a/content/docs/latest/installing/vms/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Virtual Machines -description: > - This section provides information and guidance on running Flatcar - instances on virtual machines. -weight: 20 ---- diff --git a/content/docs/latest/learning-series/_index.md b/content/docs/latest/learning-series/_index.md deleted file mode 100644 index 882f46fac..000000000 --- a/content/docs/latest/learning-series/_index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Flatcar Self-Paced Learning Series -linktitle: Learning Series -weight: 5 -author: Lexi Nadolski, Thilo Fromm ---- - -Here you'll find a set of in-depth self-paced sessions to deep dive into Flatcar! - -The sessions aim to be fun and useful. -If you feel there's room for improvement, please do provide feedback (and / or consider filing a PR!). -We also continuously improve sessions and extend the series; check back regularly. - -* [Basic Operation and Local Testing](basics-and-testing) starts from scratch and will set you up with a local test environment to play around with Flatcar. - No prerequisite knowledge required. -* [Advanced Provisioning Configuration](advanced-service-config) continues where the first session ended. - We dive into more complex deployments and ways to better manage your node configurations. -* [Managing and Encrypting Storage](managing-storage) discusses adding additional storage for applications and how to keep your data secure at rest, through encryption. -* [Immutable OS, Boot Process, In‐Place Updates, Automating Rollback, and Release Channels](immutability-updates-rollbacks) will dive *deep* into immutability specifics of Flatcar - and how this can help you to make your OS operations safe and secure. - In this low-level session we will cover OS partition immutability, boot specifics, in-place upgrades, and how users can automate rollbacks. diff --git a/content/docs/latest/migrating-from-coreos/_index.md b/content/docs/latest/migrating-from-coreos/_index.md deleted file mode 100644 index 694d00915..000000000 --- a/content/docs/latest/migrating-from-coreos/_index.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Migration from CoreOS Container Linux -linktitle: Migrating from CoreOS -weight: 110 -aliases: - - os/migrate-from-container-linux ---- - -While Flatcar is compatible with CoreOS Container Linux there are some naming differences you need to be aware of. - -**NOTE:** See [Updating from CoreOS Container Linux](update-from-container-linux) -for additional information on updating an existing cluster. - -## Installation - -_Optional:_ Instead of `coreos-installer` you should use `flatcar-installer`. - -## Kernel command line parameters - -_Optional:_ Instead of providing the `coreos.first_boot=1` argument via the boot loader you should provide `flatcar.first_boot=1`. -This forces provisioning via Ignition even if the machine (image) was booted already before. - -_Optional:_ Instead of providing the `coreos.config.url=SOMEURL` argument via the boot loader you should provide `ignition.config.url=SOMEURL` -to tell Ignition to download the configuration. -The change to a more generic name was done upstream by the Ignition project. Version 0.33 still supports both names and we -also do this via the analogous `flatcar.config.url` option but we encourage the generic name because future versions of Ignition -will only support `ignition.config.url`. - -_Optional:_ Instead of providing the `coreos.oem.id=NAME` argument via the boot loader you should provide `flatcar.oem.id=NAME`. -(A change to the more generic name `ignition.platform.id` was done upstream by the Afterburn project but is not part of Container Linux yet.) - -**Recover from or prevent errors with missing OEM settings (e.g., `coreos-metadata-sshkeys@core.service`):** While current releases handle both `coreos.oem` and `flatcar.oem` names, previous releases still required `flatcar.oem.…`. -In that case you need to change the variables in the file `/usr/share/oem/grub.cfg` when you update from CoreOS Container Linux: - -```text -# GRUB settings -set oem_id="myoemvalue" -set linux_append="$linux flatcar.oem.id=myoemvalue" -``` - -## Ignition configuration with QEMU - -_Optional:_ Instead of using `opt/com.coreos/config` in the `-fw_cfg` name-value argument pair for QEMU/KVM or libvirt you need to use `opt/org.flatcar-linux/config`. -The value in the argument pair specifies the Ignition file to use. - -## Ignition configuration with VMware - -_Optional:_ Instead of `coreos.config.data` and `coreos.config.data.encoding` for the VMware `guestinfo.VARIABLE` command line options you should use `ignition.config.data` and `ignition.config.data.encoding`. -Same as for the `ignition.config.url` kernel parameter this change was done upstream by the Ignition project. diff --git a/content/docs/latest/nebraska/_index.md b/content/docs/latest/nebraska/_index.md deleted file mode 100644 index f7049351e..000000000 --- a/content/docs/latest/nebraska/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -content_type: nebraska -title: Nebraska -main_menu: true -weight: 40 -cascade: - github_edit_url: https://github.com/flatcar/flatcar-website/tree/master/content/docs/latest - issues_url: https://github.com/flatcar/nebraska/issues/new ---- - -Nebraska is an update manager for [Flatcar Container Linux](https://flatcar.org/). - -It offers an easy way to monitor and manage the rollout of updates to applications that use the Omaha protocol, with special functionality for Flatcar Container Linux updates. diff --git a/content/docs/latest/nebraska/i18n/_index.md b/content/docs/latest/nebraska/i18n/_index.md deleted file mode 100644 index 108bb5618..000000000 --- a/content/docs/latest/nebraska/i18n/_index.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: i18n Internationalization / Localization -linkTitle: Internationalization ---- - -Nebraska's internationalization uses the i18next, i18next-parser, and -react-i18next libraries. - -## Default language, and locales - -We started with an international English, and that will be the fallback language. - -Now we're starting with locales familiar, and will accept -translations through github. - -## Browser based language detection - -We use -[i18next-browser-languagedetector](https://github.com/i18next/i18next-browser-languageDetector#readme) - -This can select the browser language through various means like through -cookies, the html language tag and other ways. - -One way to change the locale is to use `?lng=en` in the URL. - -## Lazy load locale files - -Dynamic imports and the webpack code splitting feature we -load locale files from `src/js/i18n/locales/{{lng}}/{{ns}}.json` -where {{lng}} is the language code, and {{ns}} is the namespace. - diff --git a/content/docs/latest/setup/clusters/architectures.md b/content/docs/latest/orchestrate/clusters/architectures.md similarity index 99% rename from content/docs/latest/setup/clusters/architectures.md rename to content/docs/latest/orchestrate/clusters/architectures.md index cf6530bdb..bb531e12a 100644 --- a/content/docs/latest/setup/clusters/architectures.md +++ b/content/docs/latest/orchestrate/clusters/architectures.md @@ -4,6 +4,7 @@ linktitle: Architectures description: Understanding different cluster sizes, how they get configured, and how machines interact with each other. weight: 10 aliases: + - /docs/latest/setup/clusters/architectures/ - ../../os/cluster-architectures - ../../clusters/creation/cluster-architectures --- diff --git a/content/docs/latest/setup/clusters/booting-on-ecs.md b/content/docs/latest/orchestrate/clusters/booting-on-ecs.md similarity index 98% rename from content/docs/latest/setup/clusters/booting-on-ecs.md rename to content/docs/latest/orchestrate/clusters/booting-on-ecs.md index 77af0dc2d..6051c9c83 100644 --- a/content/docs/latest/setup/clusters/booting-on-ecs.md +++ b/content/docs/latest/orchestrate/clusters/booting-on-ecs.md @@ -4,6 +4,7 @@ linktitle: Using AWS ECS description: How to setup AWS ECS clusters using Flatcar. weight: 30 aliases: + - /docs/latest/setup/clusters/booting-on-ecs/ - ../../os/booting-on-ecs - ../../clusters/management/booting-on-ecs --- diff --git a/content/docs/latest/setup/clusters/discovery.md b/content/docs/latest/orchestrate/clusters/discovery.md similarity index 99% rename from content/docs/latest/setup/clusters/discovery.md rename to content/docs/latest/orchestrate/clusters/discovery.md index 21aadf23d..ac9da7bf1 100644 --- a/content/docs/latest/setup/clusters/discovery.md +++ b/content/docs/latest/orchestrate/clusters/discovery.md @@ -3,6 +3,7 @@ title: Cluster discovery description: How to configure etcd so that cluster discovery works on your Flatcar clusters. weight: 10 aliases: + - /docs/latest/setup/clusters/discovery/ - ../../os/cluster-discovery - ../../clusters/creation/cluster-discovery --- diff --git a/content/docs/latest/container-runtimes/customizing-docker.md b/content/docs/latest/orchestrate/containers/customizing-docker.md similarity index 99% rename from content/docs/latest/container-runtimes/customizing-docker.md rename to content/docs/latest/orchestrate/containers/customizing-docker.md index 75b432d55..dbcbe90d2 100644 --- a/content/docs/latest/container-runtimes/customizing-docker.md +++ b/content/docs/latest/orchestrate/containers/customizing-docker.md @@ -5,6 +5,7 @@ description: > TCP socket, enable TLS, and other customizations. weight: 30 aliases: + - /docs/latest/container-runtimes/customizing-docker/ - ../os/customizing-docker --- diff --git a/content/docs/latest/container-runtimes/getting-started-with-docker.md b/content/docs/latest/orchestrate/containers/getting-started-with-docker.md similarity index 99% rename from content/docs/latest/container-runtimes/getting-started-with-docker.md rename to content/docs/latest/orchestrate/containers/getting-started-with-docker.md index ca2d03bf9..a0a3ae7c3 100644 --- a/content/docs/latest/container-runtimes/getting-started-with-docker.md +++ b/content/docs/latest/orchestrate/containers/getting-started-with-docker.md @@ -3,6 +3,7 @@ title: Getting started with Docker description: Basic Docker operations on Flatcar weight: 10 aliases: + - /docs/latest/container-runtimes/getting-started-with-docker/ - ../os/getting-started-with-docker --- diff --git a/content/docs/latest/container-runtimes/incus.md b/content/docs/latest/orchestrate/containers/incus.md similarity index 99% rename from content/docs/latest/container-runtimes/incus.md rename to content/docs/latest/orchestrate/containers/incus.md index 04e15d4df..dc25f6ff7 100644 --- a/content/docs/latest/container-runtimes/incus.md +++ b/content/docs/latest/orchestrate/containers/incus.md @@ -2,6 +2,8 @@ title: Incus description: Operate Incus from Flatcar weight: 13 +aliases: + - /docs/latest/container-runtimes/incus/ --- While Flatcar proposes Containerd and Docker by default, [Incus][incus] can be used to run containers. The goal of this guide is not to re-write the Incus documentation but to give key aspects of Incus usage on Flatcar. diff --git a/content/docs/latest/container-runtimes/registry-authentication.md b/content/docs/latest/orchestrate/containers/registry-authentication.md similarity index 99% rename from content/docs/latest/container-runtimes/registry-authentication.md rename to content/docs/latest/orchestrate/containers/registry-authentication.md index c442bcc28..b67160f89 100644 --- a/content/docs/latest/container-runtimes/registry-authentication.md +++ b/content/docs/latest/orchestrate/containers/registry-authentication.md @@ -3,6 +3,7 @@ title: Authenticating to Container Registries description: Configuration examples for authenticating to different container registries. weight: 50 aliases: + - /docs/latest/container-runtimes/registry-authentication/ - ../os/registry-authentication - ../clusters/management/registry-authentication --- diff --git a/content/docs/latest/container-runtimes/switching-to-unified-cgroups.md b/content/docs/latest/orchestrate/containers/switching-to-unified-cgroups.md similarity index 99% rename from content/docs/latest/container-runtimes/switching-to-unified-cgroups.md rename to content/docs/latest/orchestrate/containers/switching-to-unified-cgroups.md index c68a7c981..68afc15fe 100644 --- a/content/docs/latest/container-runtimes/switching-to-unified-cgroups.md +++ b/content/docs/latest/orchestrate/containers/switching-to-unified-cgroups.md @@ -4,6 +4,7 @@ linktitle: Switching to unified cgroups description: Overview of changes necessary to use unified cgroups with Kubernetes weight: 20 aliases: + - /docs/latest/container-runtimes/switching-to-unified-cgroups/ --- Beginning with Flatcar version 2969.0.0, Flatcar Linux has migrated to the unified diff --git a/content/docs/latest/container-runtimes/getting-started-with-kubernetes.md b/content/docs/latest/orchestrate/kubernetes/getting-started-with-kubernetes.md similarity index 99% rename from content/docs/latest/container-runtimes/getting-started-with-kubernetes.md rename to content/docs/latest/orchestrate/kubernetes/getting-started-with-kubernetes.md index 552514e60..1204d40bb 100644 --- a/content/docs/latest/container-runtimes/getting-started-with-kubernetes.md +++ b/content/docs/latest/orchestrate/kubernetes/getting-started-with-kubernetes.md @@ -2,6 +2,7 @@ title: Getting started with Kubernetes description: Operate Kubernetes from Flatcar aliases: + - /docs/latest/container-runtimes/getting-started-with-kubernetes/ - ../os/switching-from-docker-to-containerd-for-kubernetes - ./switching-from-docker-to-containerd-for-kubernetes weight: 11 diff --git a/content/docs/latest/container-runtimes/high-availability-kubernetes.md b/content/docs/latest/orchestrate/kubernetes/high-availability-kubernetes.md similarity index 99% rename from content/docs/latest/container-runtimes/high-availability-kubernetes.md rename to content/docs/latest/orchestrate/kubernetes/high-availability-kubernetes.md index f55810e87..954405f82 100644 --- a/content/docs/latest/container-runtimes/high-availability-kubernetes.md +++ b/content/docs/latest/orchestrate/kubernetes/high-availability-kubernetes.md @@ -3,6 +3,8 @@ title: "High Availability Kubernetes" date: 2025-02-13T16:30:38-05:00 draft: false weight: 12 +aliases: + - /docs/latest/container-runtimes/high-availability-kubernetes/ --- After you have created a kubernetes cluster using the [getting started diff --git a/content/docs/latest/setup/customization/adding-users.md b/content/docs/latest/os-config/host-config/adding-users.md similarity index 98% rename from content/docs/latest/setup/customization/adding-users.md rename to content/docs/latest/os-config/host-config/adding-users.md index d9e0b9aa8..16638b994 100644 --- a/content/docs/latest/setup/customization/adding-users.md +++ b/content/docs/latest/os-config/host-config/adding-users.md @@ -3,6 +3,7 @@ title: Adding users description: How to create additional user accounts, either manually or with Butane configs. weight: 10 aliases: + - /docs/latest/setup/customization/adding-users/ - ../../os/adding-users - ../../clusters/customization/adding-users --- diff --git a/content/docs/latest/setup/customization/configuring-date-and-timezone.md b/content/docs/latest/os-config/host-config/configuring-date-and-timezone.md similarity index 98% rename from content/docs/latest/setup/customization/configuring-date-and-timezone.md rename to content/docs/latest/os-config/host-config/configuring-date-and-timezone.md index 227c559b4..d95ed9056 100644 --- a/content/docs/latest/setup/customization/configuring-date-and-timezone.md +++ b/content/docs/latest/os-config/host-config/configuring-date-and-timezone.md @@ -3,6 +3,7 @@ title: Configuring date and time zone description: How to configure date, timezone and time synchronization. weight: 20 aliases: + - /docs/latest/setup/customization/configuring-date-and-timezone/ - ../../os/configuring-date-and-timezone - ../../clusters/customization/configuring-date-and-timezone --- diff --git a/content/docs/latest/setup/systemd/drop-in-units.md b/content/docs/latest/os-config/host-config/drop-in-units.md similarity index 99% rename from content/docs/latest/setup/systemd/drop-in-units.md rename to content/docs/latest/os-config/host-config/drop-in-units.md index 233f544b1..749978499 100644 --- a/content/docs/latest/setup/systemd/drop-in-units.md +++ b/content/docs/latest/os-config/host-config/drop-in-units.md @@ -4,6 +4,7 @@ linktitle: Drop-In Units description: How to customize the running system by using drop-in units. weight: 20 aliases: + - /docs/latest/setup/systemd/drop-in-units/ - ../../os/using-systemd-drop-in-units - ../../clusters/customization/using-systemd-drop-in-units --- diff --git a/content/docs/latest/setup/systemd/environment-variables.md b/content/docs/latest/os-config/host-config/environment-variables.md similarity index 99% rename from content/docs/latest/setup/systemd/environment-variables.md rename to content/docs/latest/os-config/host-config/environment-variables.md index 7d24dcf32..1d4b6203b 100644 --- a/content/docs/latest/setup/systemd/environment-variables.md +++ b/content/docs/latest/os-config/host-config/environment-variables.md @@ -4,6 +4,7 @@ linktitle: Environment Variables description: How to configure and use environment variables in systemd units. weight: 30 aliases: + - /docs/latest/setup/systemd/environment-variables/ - ../../os/using-environment-variables-in-systemd-units - ../../clusters/customization/using-environment-variables-in-systemd-units --- diff --git a/content/docs/latest/setup/customization/other-settings.md b/content/docs/latest/os-config/host-config/other-settings.md similarity index 99% rename from content/docs/latest/setup/customization/other-settings.md rename to content/docs/latest/os-config/host-config/other-settings.md index 9a46828b7..5cb89778c 100644 --- a/content/docs/latest/setup/customization/other-settings.md +++ b/content/docs/latest/os-config/host-config/other-settings.md @@ -3,6 +3,7 @@ title: Kernel modules and other settings description: How to configure kernel modules, sysctl parameters, and other common Flatcar settings. weight: 30 aliases: + - /docs/latest/setup/customization/other-settings/ - ../../os/other-settings - ../../clusters/customization/other-settings --- diff --git a/content/docs/latest/setup/customization/power-management.md b/content/docs/latest/os-config/host-config/power-management.md similarity index 97% rename from content/docs/latest/setup/customization/power-management.md rename to content/docs/latest/os-config/host-config/power-management.md index 117539e24..3c46dcc42 100644 --- a/content/docs/latest/setup/customization/power-management.md +++ b/content/docs/latest/os-config/host-config/power-management.md @@ -4,6 +4,7 @@ linktitle: Power Management description: How to choose the CPU governor to use. weight: 50 aliases: + - /docs/latest/setup/customization/power-management/ - ../../os/power-management - ../../clusters/scaling/power-management --- diff --git a/content/docs/latest/setup/systemd/timers.md b/content/docs/latest/os-config/host-config/timers.md similarity index 98% rename from content/docs/latest/setup/systemd/timers.md rename to content/docs/latest/os-config/host-config/timers.md index de0eae4cc..2cd8bc1b4 100644 --- a/content/docs/latest/setup/systemd/timers.md +++ b/content/docs/latest/os-config/host-config/timers.md @@ -4,6 +4,7 @@ linktitle: Timers description: How to schedule recurring tasks with systemd timers. weight: 25 aliases: + - /docs/latest/setup/systemd/timers/ - ../../os/scheduling-tasks-with-systemd-timers - ../../clusters/management/scheduling-tasks-with-systemd-timers --- diff --git a/content/docs/latest/setup/customization/using-nvidia.md b/content/docs/latest/os-config/host-config/using-nvidia.md similarity index 99% rename from content/docs/latest/setup/customization/using-nvidia.md rename to content/docs/latest/os-config/host-config/using-nvidia.md index 2b2122ad4..ab962a4d9 100644 --- a/content/docs/latest/setup/customization/using-nvidia.md +++ b/content/docs/latest/os-config/host-config/using-nvidia.md @@ -2,6 +2,8 @@ title: Using NVIDIA GPUs on Flatcar description: How to use and customize the NVIDIA driver on Flatcar weight: 30 +aliases: + - /docs/latest/setup/customization/using-nvidia/ --- ### Installation diff --git a/content/docs/latest/setup/customization/ACPI.md b/content/docs/latest/os-config/network/ACPI.md similarity index 97% rename from content/docs/latest/setup/customization/ACPI.md rename to content/docs/latest/os-config/network/ACPI.md index b502386b8..317928dec 100644 --- a/content/docs/latest/setup/customization/ACPI.md +++ b/content/docs/latest/os-config/network/ACPI.md @@ -3,6 +3,8 @@ title: Handle ACPI events linktitle: ACPI description: Enable acpid and handle ACPI events weight: 60 +aliases: + - /docs/latest/setup/customization/ACPI/ --- ## acpid diff --git a/content/docs/latest/setup/customization/configuring-dns.md b/content/docs/latest/os-config/network/configuring-dns.md similarity index 98% rename from content/docs/latest/setup/customization/configuring-dns.md rename to content/docs/latest/os-config/network/configuring-dns.md index 54b1284fb..34178853a 100644 --- a/content/docs/latest/setup/customization/configuring-dns.md +++ b/content/docs/latest/os-config/network/configuring-dns.md @@ -3,6 +3,7 @@ title: DNS Configuration description: How DNS resolution works and how to setup local DNS caching. weight: 30 aliases: + - /docs/latest/setup/customization/configuring-dns/ - ../../os/configuring-dns - ../../clusters/customization/configuring-dns --- diff --git a/content/docs/latest/setup/customization/network-config-with-networkd.md b/content/docs/latest/os-config/network/network-config-with-networkd.md similarity index 99% rename from content/docs/latest/setup/customization/network-config-with-networkd.md rename to content/docs/latest/os-config/network/network-config-with-networkd.md index 6a78f1c67..29e5c3eec 100644 --- a/content/docs/latest/setup/customization/network-config-with-networkd.md +++ b/content/docs/latest/os-config/network/network-config-with-networkd.md @@ -3,6 +3,7 @@ title: Network configuration with networkd description: How to setup static networking, turn on/off ipv4/ipv6, and debugging tips. weight: 40 aliases: + - /docs/latest/setup/customization/network-config-with-networkd/ - ../../os/network-config-with-networkd - ../../clusters/customization/network-config-with-networkd --- diff --git a/content/docs/latest/setup/customization/overlaybd-artifact-streaming.md b/content/docs/latest/os-config/network/overlaybd-artifact-streaming.md similarity index 98% rename from content/docs/latest/setup/customization/overlaybd-artifact-streaming.md rename to content/docs/latest/os-config/network/overlaybd-artifact-streaming.md index 01a055dba..9193dc015 100644 --- a/content/docs/latest/setup/customization/overlaybd-artifact-streaming.md +++ b/content/docs/latest/os-config/network/overlaybd-artifact-streaming.md @@ -2,6 +2,8 @@ title: OverlayBD Artifact Streaming description: How to use and customize overlaybd and accelerated container image artifact streaming weight: 30 +aliases: + - /docs/latest/setup/customization/overlaybd-artifact-streaming/ --- ### Installation diff --git a/content/docs/latest/setup/storage/adding-disk-space.md b/content/docs/latest/os-config/storage/adding-disk-space.md similarity index 97% rename from content/docs/latest/setup/storage/adding-disk-space.md rename to content/docs/latest/os-config/storage/adding-disk-space.md index 03ee01877..4f5bc822f 100644 --- a/content/docs/latest/setup/storage/adding-disk-space.md +++ b/content/docs/latest/os-config/storage/adding-disk-space.md @@ -4,6 +4,7 @@ linktitle: Additional disk space description: How to increase available disk space, depending on the platform. weight: 10 aliases: + - /docs/latest/setup/storage/adding-disk-space/ - ../../os/adding-disk-space - ../../clusters/scaling/adding-disk-space --- diff --git a/content/docs/latest/setup/storage/adding-swap.md b/content/docs/latest/os-config/storage/adding-swap.md similarity index 99% rename from content/docs/latest/setup/storage/adding-swap.md rename to content/docs/latest/os-config/storage/adding-swap.md index a5793ac68..6372eb2f9 100644 --- a/content/docs/latest/setup/storage/adding-swap.md +++ b/content/docs/latest/os-config/storage/adding-swap.md @@ -4,6 +4,7 @@ linktitle: Managing swap space description: How to create swapfiles, turn swap on/off, tune swap parameters and debug swap issues. weight: 40 aliases: + - /docs/latest/setup/storage/adding-swap/ - ../../os/adding-swap - ../../clusters/management/adding-swap --- diff --git a/content/docs/latest/setup/storage/iscsi.md b/content/docs/latest/os-config/storage/iscsi.md similarity index 98% rename from content/docs/latest/setup/storage/iscsi.md rename to content/docs/latest/os-config/storage/iscsi.md index 3043ea2e1..fe881dd5a 100644 --- a/content/docs/latest/setup/storage/iscsi.md +++ b/content/docs/latest/os-config/storage/iscsi.md @@ -4,6 +4,7 @@ linktitle: Configuring iSCSI description: How to configure the iSCSI daemon, either manually or automatically. weight: 30 aliases: + - /docs/latest/setup/storage/iscsi/ - ../../os/iscsi - ../../clusters/management/iscsi --- diff --git a/content/docs/latest/setup/storage/lvm.md b/content/docs/latest/os-config/storage/lvm.md similarity index 98% rename from content/docs/latest/setup/storage/lvm.md rename to content/docs/latest/os-config/storage/lvm.md index 5f988eb52..77cc9c181 100644 --- a/content/docs/latest/setup/storage/lvm.md +++ b/content/docs/latest/os-config/storage/lvm.md @@ -1,11 +1,12 @@ --- title: Use LVM on Flatcar Container Linux linktitle: Using LVM -description: How to use LVM to extend a logical volume across multiple disks +description: How to use LVM to extend a logical volume across multiple disks weight: 30 aliases: -- ../../os/lvm -- ../../clusters/management/lvm + - /docs/latest/setup/storage/lvm/ + - ../../os/lvm + - ../../clusters/management/lvm --- LVM - Logical Volume Management - allows you to create logical volumes, for example to use multiple physical disks as @@ -14,7 +15,6 @@ one volume. This allows you to make the full use of all attached disks. Flatcar Linux has built-in support for LVM. This guide covers creation of logical volumes using LVM and how to use them. - ## Creating LVM There are two main ways to do this: create everything manually or use an Ignition config. We will first cover @@ -47,8 +47,7 @@ sdd 8:48 0 223.6G 0 disk ``` Now we know that we have `/dev/sda`, `/dev/sdb`, `/dev/sdc`, `/dev/sdd` available. However, we cannot use `/dev/sda` in -this scenario, but we can work with the others. - +this scenario, but we can work with the others. ```shell # pvcreate /dev/sdb /dev/sdc /dev/sdd @@ -66,7 +65,7 @@ You can verify that everything worked with the following commands: /dev/sdb lvm2 --- 447.13g 447.13g /dev/sdc lvm2 --- 447.13g 447.13g /dev/sdd lvm2 --- 223.57g 223.57g - + # pvdisplay "/dev/sdd" is a new physical volume of "223.57 GiB" --- NEW Physical volume --- @@ -116,7 +115,6 @@ You need to specify the name of the group and the volumes you want to add to it ``` - Now you can go ahead and create a logical volume. We recommend to name it according to its purpose as in this example: ```shell @@ -167,7 +165,6 @@ Creating journal (262144 blocks): done Writing superblocks and filesystem accounting information: done ``` - Now you can for example mount the volume for use with docker, by mounting it to `/var/lib/docker` like so: ```shell @@ -177,7 +174,6 @@ Now you can for example mount the volume for use with docker, by mounting it to ### Ignition - In your Ignition config you will need two units: one to create the volume group and one to mount the volume. Additionally, you will also need a script that executes all the required commands. @@ -314,7 +310,6 @@ storage: mkfs.ext4 /dev/vg-root/vol_root ``` - As mentioned before, we need to still transpile from a butane yaml to an Ignition config like so: ```Bash diff --git a/content/docs/latest/setup/storage/mounting-storage.md b/content/docs/latest/os-config/storage/mounting-storage.md similarity index 99% rename from content/docs/latest/setup/storage/mounting-storage.md rename to content/docs/latest/os-config/storage/mounting-storage.md index 50bb1599c..3fb9cb0f5 100644 --- a/content/docs/latest/setup/storage/mounting-storage.md +++ b/content/docs/latest/os-config/storage/mounting-storage.md @@ -3,6 +3,7 @@ title: Mounting storage description: How to format and attach additional storage devices. weight: 10 aliases: + - /docs/latest/setup/storage/mounting-storage/ - ../../os/mounting-storage - ../../clusters/scaling/mounting-storage --- diff --git a/content/docs/latest/setup/storage/raid.md b/content/docs/latest/os-config/storage/raid.md similarity index 98% rename from content/docs/latest/setup/storage/raid.md rename to content/docs/latest/os-config/storage/raid.md index 3ad21d966..c1e250450 100644 --- a/content/docs/latest/setup/storage/raid.md +++ b/content/docs/latest/os-config/storage/raid.md @@ -3,6 +3,7 @@ title: Configuring RAID on Flatcar Container Linux linktitle: Configuring RAID weight: 10 aliases: + - /docs/latest/setup/storage/raid/ - ../../os/root-filesystem-placement - ../../bare-metal/root-filesystem-placement --- diff --git a/content/docs/latest/setup/storage/zfs.md b/content/docs/latest/os-config/storage/zfs.md similarity index 95% rename from content/docs/latest/setup/storage/zfs.md rename to content/docs/latest/os-config/storage/zfs.md index 1db1f8170..41e0550ea 100644 --- a/content/docs/latest/setup/storage/zfs.md +++ b/content/docs/latest/os-config/storage/zfs.md @@ -3,6 +3,8 @@ title: ZFS Extension for Flatcar Container Linux linktitle: ZFS Extension description: How to set up storage with the Flatcar ZFS extension. weight: 40 +aliases: + - /docs/latest/setup/storage/zfs/ --- The Flatcar ZFS extension was the first Flatcar extension published, introduced with Flatcar version 3913.0.0 in the Alpha channel. It provides the ZFS Linux kernel modules and the ZFS CLI tools. diff --git a/content/docs/latest/setup/systemd/getting-started.md b/content/docs/latest/os-config/systemd/getting-started.md similarity index 99% rename from content/docs/latest/setup/systemd/getting-started.md rename to content/docs/latest/os-config/systemd/getting-started.md index 10636bffd..aaf1f52c5 100644 --- a/content/docs/latest/setup/systemd/getting-started.md +++ b/content/docs/latest/os-config/systemd/getting-started.md @@ -4,6 +4,7 @@ linktitle: Getting Started description: An introduction to the most important systemd concepts used in Flatcar. weight: 10 aliases: + - /docs/latest/setup/systemd/getting-started/ - ../../os/getting-started-with-systemd - ../../clusters/management/getting-started-with-systemd --- diff --git a/content/docs/latest/setup/systemd/systemctl.md b/content/docs/latest/os-config/systemd/systemctl.md similarity index 98% rename from content/docs/latest/setup/systemd/systemctl.md rename to content/docs/latest/os-config/systemd/systemctl.md index c96cf0579..3295ca441 100644 --- a/content/docs/latest/setup/systemd/systemctl.md +++ b/content/docs/latest/os-config/systemd/systemctl.md @@ -4,6 +4,7 @@ linktitle: Using systemctl description: The most common operations done with systemctl in Flatcar. weight: 15 aliases: + - /docs/latest/setup/systemd/systemctl/ - ../../os/overview-of-systemctl - ../../clusters/management/overview-of-systemctl --- diff --git a/content/docs/latest/setup/systemd/udev-rules.md b/content/docs/latest/os-config/systemd/udev-rules.md similarity index 98% rename from content/docs/latest/setup/systemd/udev-rules.md rename to content/docs/latest/os-config/systemd/udev-rules.md index bbe0d387e..18816be4b 100644 --- a/content/docs/latest/setup/systemd/udev-rules.md +++ b/content/docs/latest/os-config/systemd/udev-rules.md @@ -3,6 +3,7 @@ title: Using systemd and udev rules description: How to run units when specific udev events trigger. weight: 35 aliases: + - /docs/latest/setup/systemd/udev-rules/ - ../../os/using-systemd-and-udev-rules - ../../clusters/management/using-systemd-and-udev-rules --- diff --git a/content/docs/latest/setup/systemd/user-units.md b/content/docs/latest/os-config/systemd/user-units.md similarity index 97% rename from content/docs/latest/setup/systemd/user-units.md rename to content/docs/latest/os-config/systemd/user-units.md index 03e29ae97..62d6d2c46 100644 --- a/content/docs/latest/setup/systemd/user-units.md +++ b/content/docs/latest/os-config/systemd/user-units.md @@ -3,6 +3,8 @@ title: User Units linktitle: User Units description: Systemd User Units weight: 40 +aliases: + - /docs/latest/setup/systemd/user-units/ --- Flatcar Container Linux supports the use of systemd user units. These are unit files located in a users home directory, managed by the user, and executed with their permission. diff --git a/content/docs/latest/provisioning/_index.md b/content/docs/latest/provisioning/_index.md deleted file mode 100644 index 28e57afd1..000000000 --- a/content/docs/latest/provisioning/_index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Provisioning Tools -description: > - Several different tools can be used to automate the provisioning of - Flatcar Container Linux images. These guides can help you understand what - each of the tools do, as well as provide plenty of examples of how to use - them. -weight: 30 ---- diff --git a/content/docs/latest/provisioning/cl-config/_index.md b/content/docs/latest/provisioning/cl-config/_index.md deleted file mode 100644 index 549034ea4..000000000 --- a/content/docs/latest/provisioning/cl-config/_index.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: "[DEPRECATED / EOL] Container Linux Config Transpiler" -description: YAML configuration format used to generate Ignition configs. -weight: 20 -aliases: - - ../os/provisioning - - ../reference/migrating-to-clcs/provisioning ---- - -:warning: TL; DR: Use [Butane](../config-transpiler). While Flatcar does support both Ignition spec version (2.x and 3.x), we encourage folks to use [Butane](../config-transpiler) first but we still maintain / document backward compatibility for users who still rely on Ignition 2.x. :warning: - -Flatcar Container Linux automates machine provisioning with a specialized system for applying initial configuration. This system implements a process of (trans)compilation and validation for machine configs, and an atomic service to apply validated configurations to machines. - -## Container Linux Config - -Flatcar Container Linux admins define these configurations in a format called the [Container Linux Config][clc], which was originally designed for CoreOS Container Linux, but works perfectly well with Flatcar Container Linux. Container Linux Configs are structured as YAML, and intended to be human-readable. The Container Linux Config has features devoted to configuring Flatcar Container Linux services such as [etcd][etcd], [rkt][rkt], Docker, [flannel][flannel], and [locksmith][locksmith]. **The defining feature of the config is that it cannot be sent directly to a Flatcar Container Linux provisioning target**. Instead, it is first validated and transformed into a machine-readable and wire-efficient form. - -The following examples demonstrate the simplicity of the Container Linux Config format. - -This extremely simple Container Linux Config will fetch and run the current release of etcd: - -```yaml -etcd: {} -``` - -Extend the definition to specify the version of etcd to run. The following example will provision a new Flatcar Container Linux machine to fetch and run the etcd service, version 3.1.6: - -```yaml -etcd: - version: 3.1.6 -``` - -Use variable replacement to configure the etcd service with the provisioning target's public and private IPv4 addresses, making it repeatable across a group of machines. - -```yaml -etcd: - advertise_client_urls: http://{PUBLIC_IPV4}:2379 - initial_advertise_peer_urls: http://{PRIVATE_IPV4}:2380 - listen_client_urls: http://0.0.0.0:2379 - listen_peer_urls: http://{PRIVATE_IPV4}:2380 - discovery: https://discovery.etcd.io/ -``` - -`PUBLIC_IPV4` and `PRIVATE_IPV4` are automatically populated from the environment in which Flatcar Container Linux runs, if this metadata exists. Given the many different environments in which Flatcar Container Linux can run, it's difficult if not impossible to accurately determine these variables in every instance. Be certain to check this value as a troubleshooting measure. - -For example, the default metadata for an EC2 environment would be used: `public_ipv4` and `local_ipv4`. On Azure, *either* the virtual IP or public IP could be used for the `PUBLIC_IPV4` (`ct` makes a best guess and uses the virtual IP, but this could change in the future), and the dynamic IP would be used for the `PRIVATE_IPV4`. On bare metal, this information cannot be reliably derived in a general manner, so these variables cannot be used. - -Because variable expansion is unpredictable and complex, and because it is also common for users to inadvertently write invalid configs, the use of a transformation tool is strongly encouraged. The default tool recommended for this task is the [Config Transpiler][ct] (ct for short). The Config Transpiler will validate and transform a Container Linux Config into the format that Flatcar Container Linux can consume: the Ignition Config. - -## Ignition Config - -Ignition, the utility in Flatcar Container Linux responsible for provisioning the machine, fetches and executes the Ignition Config. Flatcar Container Linux directly consumes the Ignition Config configuration format. - -Ignition Configs are mostly static, distro-agnostic, and meant to be generated by a machine rather than a human. While they can be written directly by users, it is highly discouraged due to the ease with which errors may be introduced. Rather than writing Ignition Configs directly, users are encouraged to use provisioning tools like [Matchbox][matchbox], which transparently translate Container Linux Configs to Ignition Configs, or to use the Config Transpiler itself. - -![visual overview of the alternate ct workflows](../../img/ct-workflow.svg) - -As shown in this diagram, `ct` is manually invoked only when users are manually provisioning machines. If a provisioning tool like Matchbox is used, `ct` will transparently be incorporated into the deployment pipeline. In which case, the user only needs to prepare a Container Linux Config - Ignition and the Ignition Config are merely an implementation detail. - -## Config Transpiler - -The Container Linux Config Transpiler abstracts the details of configuring Flatcar Container Linux. It's responsible for transforming a Container Linux Config written by a user into an Ignition Config to be consumed by instances of Flatcar Container Linux. - -The Container Linux Config Transpiler command line interface, `ct` for short, can be downloaded from its [GitHub Releases page][download-ct] or used via Docker (`cat example.yaml | docker run --rm -i --platform=YOURPLATFORM ghcr.io/flatcar/ct:latest`). - -The following config will configure an etcd cluster using the machine's public and private IP addresses: - -```yaml -etcd: - advertise_client_urls: http://{PUBLIC_IPV4}:2379 - initial_advertise_peer_urls: http://{PRIVATE_IPV4}:2380 - listen_client_urls: http://0.0.0.0:2379 - listen_peer_urls: http://{PRIVATE_IPV4}:2380 - discovery: https://discovery.etcd.io/ -``` - -As suggested earlier, `ct` requires information about the target environment before it can transform configs which use templating. If this config is passed to `ct` without any other arguments, `ct` fails with the following error message: - -```shell -$ ct < example.yml -error: platform must be specified to use templating -``` - -This message states that because the config takes advantage of templating (in this case, `PUBLIC_IPV4`), `ct` must be invoked with the `--platform` argument. This extra information is used by `ct` to make the platform-specific customizations necessary. Keeping the Container Linux Config and the invocation arguments separate allows the Container Linux Config to remain largely platform independent. - -CT can be invoked again and given Amazon EC2 as an example: - -```shell -$ ct --platform=ec2 < example.yml -{"ignition":{"version":"2.0.0","config"... -``` - -This time, `ct` successfully runs and produces the following Ignition Config: - -```json -{ - "ignition": { "version": "2.0.0" }, - "systemd": { - "units": [{ - "name": "etcd-member.service", - "enable": true, - "dropins": [{ - "name": "20-clct-etcd-member.conf", - "contents": "[Unit]\nRequires=coreos-metadata.service\nAfter=coreos-metadata.service\n\n[Service]\nEnvironmentFile=/run/metadata/coreos\nExecStart=\nExecStart=/usr/lib/flatcar/etcd-wrapper $ETCD_OPTS \\\n --listen-peer-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2380\" \\\n --listen-client-urls=\"http://0.0.0.0:2379\" \\\n --initial-advertise-peer-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2380\" \\\n --advertise-client-urls=\"http://${COREOS_EC2_IPV4_PUBLIC}:2379\" \\\n --discovery=\"https://discovery.etcd.io/\u003ctoken\u003e\"" - }] - }] - } -} -``` - -This Ignition Config enables and configures etcd as specified in the above Container Linux Config. This can be more easily seen if the contents of the etcd drop-in are formatted nicely: - -```ini -[Unit] -Requires=coreos-metadata.service -After=coreos-metadata.service - -[Service] -EnvironmentFile=/run/metadata/coreos -ExecStart= -ExecStart=/usr/lib/flatcar/etcd-wrapper $ETCD_OPTS \ - --listen-peer-urls="http://${COREOS_EC2_IPV4_LOCAL}:2380" \ - --listen-client-urls="http://0.0.0.0:2379" \ - --initial-advertise-peer-urls="http://${COREOS_EC2_IPV4_LOCAL}:2380" \ - --advertise-client-urls="http://${COREOS_EC2_IPV4_PUBLIC}:2379" \ - --discovery="https://discovery.etcd.io/" -``` - -The details of these changes are covered in depth in Ignition's [metadata documentation][metadata], but the gist is that `coreos-metadata` is used to fetch the IP addresses from the Amazon APIs and then `systemd` is leveraged to substitute the IP addresses into the invocation of etcd. The result is that even though Ignition only runs once, `coreos-metadata` fetches the IP addresses whenever etcd is run, allowing etcd to use IP addresses that have the potential to change. - -## Migrating from cloud configs - -Previously, the recommended way to provision a Flatcar Container Linux machine was with a cloud-config. These configs would be given to a Flatcar Container Linux machine and a utility called [coreos-cloudinit][cloudinit] would read this file and apply the configuration on every boot. - -For a [number of reasons][vs], coreos-cloudinit has been deprecated in favor of Container Linux Configs and Ignition. For help migrating from these legacy cloud-configs to Container Linux Configs, refer to the [migration guide][migrating]. - -## Using Container Linux Configs - -Now that the basics of Container Linux Configs have been covered, a good next step is to read through the [examples][examples] and start experimenting. The [troubleshooting guide][troubleshooting] is a good reference for debugging issues. - -[clc]: ../config-transpiler/configuration -[cloudinit]: https://github.com/kinvolk/coreos-cloudinit -[ct]: ../config-transpiler/ -[download-ct]: https://github.com/flatcar/container-linux-config-transpiler/releases -[etcd]: https://github.com/etcd-io/etcd -[examples]: examples -[flannel]: https://github.com/coreos/flannel -[locksmith]: https://github.com/kinvolk/locksmith -[matchbox]: https://github.com/coreos/matchbox -[metadata]: ../ignition/metadata -[migrating]: from-cloud-config -[rkt]: https://github.com/rkt/rkt -[troubleshooting]: https://github.com/kinvolk/ignition/blob/master/doc/getting-started.md#troubleshooting -[vs]: ../ignition/#ignition-vs-coreos-cloudinit diff --git a/content/docs/latest/provisioning/config-transpiler/_index.md b/content/docs/latest/provisioning/config-transpiler/_index.md deleted file mode 100644 index 0c40ff4b9..000000000 --- a/content/docs/latest/provisioning/config-transpiler/_index.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -content_type: butane -title: Butane Config Transpiler -linktitle: Butane Config Transpiler -description: Transforms Butane files into Ignition configuration -main_menu: true -weight: 30 -aliases: - - ../container-linux-config-transpiler/doc/overview - - ../container-linux-config-transpiler ---- - -Butane is the utility responsible for transforming a user-provided Butane Configuration into an [Ignition][ignition] configuration. The resulting Ignition config can then be provided to a Container Linux machine when it first boots in order to provision it. - -The Butane Config is intended to be human-friendly, and is thus in YAML. The syntax is rather forgiving, and things like references and multi-line strings are supported. - -The resulting Ignition config is very much not intended to be human-friendly. It is an artifact produced by butane that users should simply pass along to their machines. JSON was chosen over a binary format to make the process more transparent and to allow power users to inspect/modify what butane produces, but it would have worked fine if the result from butane had not been human readable at all. - -[butane]: https://github.com/coreos/butane/ -[ignition]: https://github.com/coreos/ignition - -**Note:** Butane is utilized to generate Ignition v3+ configurations. If you are still utilizing a version of Container Linux that requires Ignition v2, you can refer to the [Container Linux Config Transpiler][cl-config] documentation. - -## Why a two-step process? - -There are a couple factors motivating the decision to not incorporate support for Butane Configs directly into the boot process of Container Linux (as in, the ability to provide a Butane Config directly to a booting machine, instead of an Ignition config). - -- By making users run their configs through butane before they attempt to boot a machine, issues with their configs can be caught before any machine attempts to boot. This will save users time, as they can much more quickly find problems with their configs. Were users to provide Butane Configs directly to machines at first boot, they would need to find a way to extract the Ignition logs from a machine that may have failed to boot, which can be a slow and tedious process. -- YAML parsing is a complex process that in the past has been rather error-prone. By only doing JSON parsing in the boot path, we can guarantee that the utilities necessary for a machine to boot are simpler and more reliable. We want to allow users to use YAML however, as it's much more human-friendly than JSON, hence the decision to have a tool separate from the boot path to "transpile" YAML configurations to machine-appropriate JSON ones. - -## Tell me more about Ignition - -[Ignition][ignition] is the utility inside of a Container Linux image that is responsible for setting up a machine. It takes in a configuration, written in JSON, that instructs it to do things like add users, format disks, and install systemd units. The artifacts that butane produces are Ignition configs. All of this should be an implementation detail however, users are encouraged to write Butane Configs for butane, and to simply pass along the produced JSON file to their machines. - -## How similar are Butane Configs and Ignition configs? - -Some features in Butane Configs and Ignition configs are identical. Both support listing users for creation, systemd unit dropins for installation, and files for writing. - -All of the differences stem from the fact that Ignition configs are distribution agnostic. An Ignition config can't just tell Ignition to enable etcd, because Ignition doesn't know what etcd is. The config must tell Ignition what systemd unit to enable, and provide a systemd dropin to configure etcd. - -Butane on the other hand _does_ understand the specifics of Flatcar Container Linux. A user currently can't specify Clevis options on Flatcar and Butane does these sanity checks for the user. - -## Example Butane Config - -The following small example of a Butane Config will ensure that the default core user exists and adds a specified public key - -```yaml -variant: flatcar -version: 1.0.0 -passwd: - users: - - name: core - ssh_authorized_keys: - - ssh-rsa AAAAB......xyz email@host.net -``` - -To turn this Butane Config into a usable Ignition Config, we can then run: `docker run --rm -i quay.io/coreos/butane:latest < your_config.yaml > your_config.json`. This will result in the above YAML being turned into the below JSON - -```json -{ - "ignition": { - "version": "3.3.0" - }, - "passwd": { - "users": [ - { - "name": "core", - "sshAuthorizedKeys": [ - "ssh-rsa AAAAB......xyz email@host.net" - ] - } - ] - } -} -``` - -To learn more about Butane and the configurations that are available, you can refer to the latest [Butane Spec][butane-spec]. - -[butane-spec]: https://coreos.github.io/butane -[cl-config]: ../cl-config diff --git a/content/docs/latest/provisioning/ignition/_index.md b/content/docs/latest/provisioning/ignition/_index.md deleted file mode 100644 index b5a853c49..000000000 --- a/content/docs/latest/provisioning/ignition/_index.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -content_type: ignition -title: Ignition -linktitle: Ignition -description: Provisioning utility specially designed for Container OSs -main_menu: true -weight: 10 -aliases: - - ../ignition/what-is-ignition - - ../ignition ---- - -Ignition is a new provisioning utility designed specifically for container OSs like Flatcar Container Linux, which allows you to manipulate disks during early boot. This includes partitioning disks, formatting partitions, writing files (regular files, systemd units, networkd units, and more), and configuring users. On the first boot, Ignition reads its configuration from a source-of-truth (remote URL, network metadata service, or hypervisor bridge, for example) and applies the configuration. - -A [series of example configs][examples] are provided for reference. The specification can be found [here][ignition-specification]. - -## Ignition vs coreos-cloudinit - -Ignition solves many of the same problems as [coreos-cloudinit][cloudinit] but in a simpler, more predictable, and more flexible manner. This is achieved with two major changes: Ignition only runs once and it does not handle variable substitution. Ignition has also fixed a number of pain points with regard to configuration. - -Instead of YAML, Ignition uses JSON for its configuration format. JSON's typing immediately eliminates problems like "off" being rewritten as "false", the "#cloud-config" header being stripped because comments *shouldn't* have meaning, and confusion around whether those file permissions were written in octal or decimal. Ignition's configuration is also versioned, which allows future development without persistent backward compatibility. - -### Ignition only runs once - -Even though Ignition only runs once, during the first boot of the system, it packs a powerful punch. Because Ignition runs so early in the boot process (in the initramfs, to be exact), it is able to repartition disks, format filesystems, create users, and write files, all before the userspace begins to boot. - -Because Ignition runs so early in the boot process, the network config is available for networkd to read when it first starts, and systemd services are already written to disk when systemd starts. [Configuring the network][network-config] is no longer an issue. This results in a simple startup, a faster startup, and the ability to accurately inspect the unit dependency graphs. - -### No variable substitution - -Because Ignition only runs once, there's no reason for it to incorporate dynamic data (like floating IP addresses, or compute regions). - -Instead, use Ignition to write static files and leverage systemd's environment variable expansion to insert dynamic data. The Ignition config should install a service which fetches the necessary runtime data, then any services which need this data (such as etcd or fleet) can rely on the installed service and source in their output. The result is that the data is only collected if and when it is needed. For supported platforms, Flatcar Container Linux provides a small utility (`coreos-metadata.service`) to help fetch this data. - -### When is Ignition executed - -On boot, GRUB checks the EFI System Partition for a file at `flatcar/first_boot` (or `coreos/first_boot` if the machine was updated from CoreOS CL) and sets `flatcar.first_boot=detected` if found. The `flatcar.first_boot` parameter is processed by a [systemd-generator] in the [initramfs] and if the parameter value is non-zero, the Ignition units are set as dependencies of `initrd.target`, causing Ignition to run. If the parameter is set to the special value `detected`, the `flatcar/first_boot` (or `coreos/first_boot`) file is deleted after Ignition runs successfully. You can schedule a re-run of Ignition with the `flatcar-reset` tool (available since Alpha 3535.0.0), which also takes care of cleaning up old rootfs state and keeping only the data from the rootfs you want to keep. - -Note that [PXE][supported-platforms] deployments don't use GRUB to boot, so `flatcar.first_boot=1` must be added to the boot arguments in order for Ignition to run. `detected` should not be specified so Ignition will not attempt to delete `flatcar/first_boot` (or `coreos/first_boot`). - -## Providing Ignition a config - -Ignition can read its config from a number of different locations, but only from one at a time. When running Flatcar Container Linux on the supported cloud providers, Ignition will read its config from the instance's userdata. This means that if Ignition is being used, it will not be possible to use other tools which also use this userdata (such as coreos-cloudinit). Bare metal installations and PXE boots can use the kernel boot parameters to point Ignition at the config. - -## Where is Ignition supported? - -In addition to providers supported by [upstream Ignition][ignition-supported], Flatcar [supports](https://github.com/flatcar/scripts/blob/main/sdk_container/src/third_party/coreos-overlay/sys-apps/ignition/files/0018-revert-internal-oem-drop-noop-OEMs.patch) cloudsigma, hyperv, interoute, niftycloud, rackspace[-onmetal], and vagrant. - -Ignition is under active development. Expect to see support for more images in the coming months. - -[examples]: https://github.com/coreos/ignition/blob/main/docs/examples.md -[ignition-specification]: specification -[cloudinit]: https://github.com/flatcar/coreos-cloudinit -[network-config]: network-configuration -[supported-platforms]: https://github.com/coreos/ignition/blob/main/docs/supported-platforms.md -[systemd-generator]: http://www.freedesktop.org/software/systemd/man/systemd.generator.html -[initramfs]: https://www.kernel.org/doc/Documentation/filesystems/ramfs-rootfs-initramfs.txt diff --git a/content/docs/latest/provisioning/sysext/_index.md b/content/docs/latest/provisioning/sysext/_index.md deleted file mode 100644 index ea71f5302..000000000 --- a/content/docs/latest/provisioning/sysext/_index.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -title: Systemd-sysext -description: Extending the base OS with systemd-sysext images -weight: 39 ---- - -Flatcar Container Linux bundles various software components with fixed versions together into one release. -For users that require a particular version of a software component this means that the software needs to be supplied out of band and overwrite the built-in software copy. -Another approach we recommended was to [store binaries in `/opt/bin`](../../container-runtimes/use-a-custom-docker-or-containerd-version/) and prefer them in the `PATH`. - -For long time already, the systemd project provided the portable services feature to address deploying custom services. -However, since it only covered the service itself without making the client binaries available on the user, it didn't really fit the use case fully. -The systemd-sysext feature finally provides a way to extend the base OS with a `/usr` overlay, thereby making custom binaries available to the user. -While systemd-sysext images are not really good yet at including systemd units, Flatcar ships `ensure-sysext.service` as workaround to automatically load the image's services. -Systemd-sysext is supported in Flatcar versions ≥ 3185.0.0 for user provided sysext images. - -Here's some blog posts you can read for more context: -1. https://www.flatcar.org/blog/2024/04/os-innovation-with-systemd-sysext/ -2. https://www.flatcar.org/blog/2023/07/summer-2023-my-internship-experience/ -3. https://www.flatcar.org/blog/2023/12/extending-flatcar-say-goodbye-to-torcx-and-hello-to-systemd-sysext/ - -## Types of systemd-sysext images - -For Flatcar, two types of systemd-sysext images are provided: - -- Official: - - enabled: These are extensions that are shipped along with the base image like Docker, Containerd, OEM partition. These are "opt-out". - - disabled: These are "opt-in" like ZFS, Podman or Python and one needs to write the extension name in `/etc/flatcar/enabled-sysext.conf` to pull the extension at boot. Similar to enabled extensions, those are built in Flatcar's CI and are distributed from the release servers. -- Community supported: These are extensions from the Flatcar [sysext-bakery releases](https://github.com/flatcar/sysext-bakery/releases) and they are not tested in CI. - -## OEM software as systemd-sysext images - -The Flatcar cloud images differ in the OEM vendor tools they provide in addition to the base image. In the past this was done through binaries on the OEM partition. Since Flatcar version 3760.0.0 most OEM images have been converted to use systemd-sysext images stored on the OEM. They are covered by the Flatcar A/B update mechanism because they are bound to the OS version they were released and tested with, also due to dynamic linking. Those users that run their own Nebraska update server need to make sure that they have a recent version that provides the OEM payloads. - -## Flatcar Release Extensions ("official") - -Official extensions provided as part of a Flatcar release make Flatcar more modular. Users have different demands while the base image should stay small. Certain software is bound to a particular OS version and can't be provided as out-of-band extension because it needs to be updated together with the OS. In the past this meant we had to find a compromise but soon Flatcar can support more use cases and might even reduce the base image contents further. Those users that run their own Nebraska update server need to make sure that they have a recent version that provides the Flatcar extension payloads. - -The table below give an overview on the supported Flatcar extensions. - -| Name in `/etc/flatcar/enabled-sysext.conf`| Sysext name on the instance | Availability | Documentation | Enabled by default | -|-------------------------------------------|--------------------------------------|---------------------|---------------------------|-------------------------| -| n/a[^1] | `containerd-flatcar` | 3794.0.0 – … | | ✅ | -| n/a[^1] | `docker-flatcar` | 3794.0.0 – … | | ✅ | -| `incus` | `flatcar-incus` | 4285.0.0 – … | [Incus][incusextension] | | -| `nvidia-drivers-*` | `flatcar-nvidia-drivers-*` | 4344.0.0 – … | [NVIDIA][nvidiaextension] | | -| `overlaybd` | `flatcar-overlaybd` | 4426.0.0 – … | [OverlayBD][overlaybdext] | | -| `podman` | `flatcar-podman` | 3941.0.0 – … | | | -| `python` | `flatcar-python` | 4012.0.0 – … | | | -| `zfs` | `flatcar-zfs` | 3913.0.0 – … | [Storage][zfsextension] | | -| n/a[^1] | `oem-*` | 3760.2.0 – … | | ✅ | - -[^1]: n/a here because those sysexts are already enabled by default - -Users can enable Flatcar extensions by writing one name per line to `/etc/flatcar/enabled-sysext.conf`. -For now there are no pre-enabled release extensions but once Flatcar would move parts of the base image out into extensions, these would be pre-enabled as entries in `/usr/share/flatcar/enabled-sysext.conf`. They can be disabled with a `-NAME` entry in `/etc/flatcar/enabled-sysext.conf`. - -### Remove Docker and / or Containerd from Flatcar - -If Flatcar is used as a Kubernetes node or one wants to try a different version of Docker or Containerd, it is possible to remove those extensions from Flatcar at boot using this configuration: -```yaml -variant: flatcar -version: 1.0.0 -storage: - links: - - path: /etc/extensions/docker-flatcar.raw - target: /dev/null - overwrite: true - - path: /etc/extensions/containerd-flatcar.raw - target: /dev/null - overwrite: true -``` - -## Community supported extensions ("community supported") - -A simple way to extend Flatcar is to use the systemd-sysext images from the [sysext-bakery GitHub repo](https://github.com/flatcar/sysext-bakery). It [publishes prebuilt images](https://github.com/flatcar/sysext-bakery/releases) that bundle third-party binaries. The repo README provides a Butane config example for updating the extensions with `systemd-sysupdate`. - -[Here's](https://flatcar.github.io/sysext-bakery/#what-extensions-are-available) a matrix for the community-supported extensions. - -## Bundle extensions in a Flatcar image - -The [`bake_flatcar_image.sh`](https://flatcar.github.io/sysext-bakery/#baking-sysexts-into-flatcar-os-images) helper in the [sysext-bakery GitHub repo](https://github.com/flatcar/sysext-bakery) can be used to customize a Flatcar release image by adding your extension images into the rootfs. - -## The sysext format - -Sysext images can be disk image files or simple folders (details in [`man systemd-sysext`](https://www.freedesktop.org/software/systemd/man/systemd-sysext.html)). -They get loaded by `systemd-sysext.service` which looks for them in `/etc/extensions/` or `/var/lib/extensions` among others. -An image must be named `NAME.raw` while a plain folder just uses `NAME` as name. -The image can be a plain ext4 or btrfs filesystem image but squashfs images are a useful format to consider because besides the compression it offers, the `mksquashfs` tool simply takes a directory as input and doesn't need loop devices and mounting of an image file. - -Inside the image or folder structure there must be a file `usr/lib/extension-release.d/extension-release.NAME` with metadata used for version matching. -The basic matching that needs to be there is `ID=flatcar` plus one of `VERSION_ID` or `SYSEXT_LEVEL`. -If your binaries link against Flatcar's binaries under `/usr`, you must couple your sysext image to the Flatcar version by specyfing `VERSION_ID=MAJOR.MINOR.PATCH` in `extension-release.NAME` to match the `VERSION_ID` field from `/etc/os-release`. -This means that the sysext image won't be loaded anymore after an OS update. -Therefore, it is recommended that you try to use static binaries which lifts the requirement of having to couple the versions. -In this case you can specify `SYSEXT_LEVEL=1.0` instead of `VERSION_ID`. -The matching semantics for `SYSEXT_LEVEL` are limited at the moment and the use case for bumping the version are not there yet. -In summary, this is what you will normally write to the metadata file: - -``` -ID=flatcar -SYSEXT_LEVEL=1.0 -``` - -Then place your binaries under `usr/bin/` and your systemd units under `usr/lib/systemd/system/`. -While Flatcar currently allows you to enable systemd units by including the symlinks it would generate when enabling the units, e.g., `sockets.target.wants/my.socket` → `../my.socket`, this is not recommended. -The recommended way is to ship drop-ins for the target units that start your unit, e.g., `usr/lib/systemd/system/sockets.target.d/10-docker-socket.conf` with the following content (similar for `multi-user.target` and a `.service` unit): - -```ini -[Unit] -Upholds=docker.socket -``` - -## Supplying your sysext image from Ignition - -The following Butane Config YAML can be be transpiled to Ignition JSON and will download a custom Docker+containerd sysext image on first boot. -It also takes care of disabling built-in Docker and containerd sysext images (to revert this, you can find the original target of the symlinks in `/usr/share/flatcar/etc/extensions/`). - -```yaml -variant: flatcar -version: 1.0.0 -storage: - files: - - path: /etc/extensions/mydocker.raw - mode: 0644 - contents: - source: https://myserver.net/mydocker.raw - links: - - path: /etc/extensions/docker-flatcar.raw - target: /dev/null - overwrite: true - - path: /etc/extensions/containerd-flatcar.raw - target: /dev/null - overwrite: true -``` - -After boot you can see it loaded in the output of the `systemd-sysext` command: - -``` -HIERARCHY EXTENSIONS SINCE -/opt none - -/usr mydocker Wed 2022-03-23 14:16:37 UTC -``` - -You can reload the sysext images at runtime by executing `systemctl restart systemd-sysext`. -In Flatcar this also triggers `ensure-sysext.service` to reload the unit files from disk (in the future this may be covered by `systemd-sysext` itself). -As an additional workaround, Flatcar currently also reevaluates `multi-user.target`, `sockets.target`, and `timers.target`, to make sure your enabled systemd units run, but for units started by `Upholds=` drop-ins that wouldn't be needed. -A manual `systemd-sysext refresh` is not recommended. - -## Creating custom sysext images - -The [`sysext-bakery`][sysext-bakery] repository under the Flatcar GitHub organization serves as a central point for sysext building tools. -Please reach out if your use case isn't covered and work with us to include it there. - -### Upstream Docker sysext images - -The Docker releases publish static binaries including containerd and the only missing piece are the systemd units. -To ease the process, the [`create_docker_sysext.sh`](https://raw.githubusercontent.com/flatcar/sysext-bakery/main/create_docker_sysext.sh) helper script takes care of downloading the release binaries and adding the systemd unit files, and creates a combined Docker+containerd sysext image: - -``` -./create_docker_sysext.sh 20.10.13 mydocker -[… writes mydocker.raw into current directory …] -``` - -## Updating custom sysext images - -From Flatcar 3510.2.0, it is possible to use the `systemd-sysupdate` tool that covers the task of downloading newer versions of your sysext image at runtime from a location you specify. - -The [sysext-bakery documentation][sysext-bakery] has examples for Butane configs that consume the `sysext-bakery` images and keep them up-to-date with `systemd-sysupdate`. You can adapt the examples to other images of the `systemd-bakery` repo or to your custom images hosted elsewhere. An easy method is to fork the repo and tweak the list of released images to your liking. - -## Debugging - -The `systemd-dissect` tool gives a quick overview for a systemd-sysext image: - -``` -sudo systemd-dissect docker-compose.raw -``` - -You can list the contents of a systemd-sysext image with the `--list` flag (or `--mtree` for a detailed view): - -``` -sudo systemd-dissect --list docker-compose.raw -``` - -A single file can be extracted with: - -``` -sudo systemd-dissect --with docker-compose.raw cat usr/lib/extension-release.d/extension-release.docker-compose -``` - -To get more information about found incompatibilities during merging, enable the debug output: - -``` -sudo SYSTEMD_LOG_LEVEL=debug systemd-sysext refresh -``` - -[incusextension]: ../../container-runtimes/incus -[sysext-bakery]: https://flatcar.github.io/sysext-bakery -[nvidiaextension]: ../../setup/customization/using-nvidia -[overlaybdext]: ../../setup/customization/overlaybd-artifact-streaming -[zfsextension]: ../../setup/storage/zfs diff --git a/content/docs/latest/provisioning/terraform/_index.md b/content/docs/latest/provisioning/terraform/_index.md deleted file mode 100644 index 08db6c473..000000000 --- a/content/docs/latest/provisioning/terraform/_index.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Terraform -description: Provision Flatcar Container Linux with an Ignition configuration through Terraform -weight: 40 ---- - -Flatcar Container Linux fits well with Terraform for the principle of Immutable Infrastructure where you deploy a node and, instead of making changes via SSH, you destroy it and deploy a new node. -The big advantages compared to other OSes are the inbuilt support for declarative configuration with Ignition on first boot and the automatic OS updates. - -Many cloud services allow to provide _User Data_ for a node in an extra attribute. Ignition will fetch the configuration from this place and apply it. No Terraform SSH provisioning commands are needed. - -## Terraform Providers for the different Cloud Services - -How to use the Terraform Providers of each cloud service is explained on the respective documentation page under [Cloud Providers][cloud]. - -## Changing the Ignition Configuration - -Changes to the User Data attribute should normally destroy the node and recreate it so that Ignition runs again on the first boot. -However, this behavior depends on the Terraform provider for your cloud service. -Some cloud services allow to update the attribute in-place without destroying the node but Ignition won't run again by default and even if you triggered it, you would have to be careful as this is not recommended (more on this at the end of this document). -You can also tell Terraform not ignore attribute changes (set `ignore_changes`) and thus delay the change until you manually destroy the node and recreate it with Terraform. -This is sometimes useful but may be a source of errors when you don't know that a node still runs an old configuration. - -To make the recreation of a node less disruptive, you can architect your setup to accept a node to exist twice at the same time and set `create_before_destroy` to let Terraform first create the replacement node and then destroy the old node. -On AWS, it's also possible to use Auto Scaling Groups instead of directly operating on instances. In this case, to update the User Data you can replace the Auto Scaling Group, and the new one will take care of creating new nodes and the old one deletes the old ones. -An advanced scheme of this on AWS can use Auto Scaling Groups instead of directly operating on instances, and to change the User Data you replace the Auto Scaling Group and the new one takes care of creating new nodes and the old one deletes the old ones. -It is also advisable to separate the persistent data from the disposable nodes to external data volumes or to use a backup mechanism and inject the backup on the first boot. - -## Generating the Ignition Configuration within Terraform - -To convert the Butane Config in YAML to the final Igniton Config in JSON you don't need to run [`butane`][butane-configs] manually. Instead, you can directly do this within Terraform, through the [`terraform-ct-provider`][terraform-ct-provider] (starting from v0.12.0). -Combined with the `template-provider` you can reference Terraform variables in the YAML template. - -An alternative is the [`terraform-ignition-provider`][terraform-ignition-provider] that allows to assemble the Ignition Config from Terraform declarations. - -The following snippet demonstrates the use of the `terraform-ct-provider` and the `template-provider` to specify the User Data attribute on a Packet (now Equinix Metal) instance: - -``` -resource "packet_device" "machine" { - operating_system = "flatcar_stable" - user_data = data.ct_config.machine-ignition.rendered - [...] -} - -data "ct_config" "machine-ignition" { - content = data.template_file.machine-cl-config.rendered -} - -data "template_file" "machine-cl-config" { - template = file("${path.module}/machine.yaml.tmpl") - vars = { something = var.something } -} -``` - -When using a template be careful to refer to the Terraform variables via `${variable}` while shell variables in scripts used at OS runtime need to be quoted like `$${variable}` or need to use the `$variable` syntax. - -## Updating the User Data in-place and rerunning Ignition instead of destroying nodes - -Sometimes you want to take the declarative approach of Terraform but can't accept that nodes are destroyed and recreated for configuration changes. -This is the case for nodes that have a manual or slow bring-up process, much data that can't be moved easily, or where the IP address should not change. - -Ignition can be told to run again through `flatcar-reset` (available since Alpha 3535.0.0), which also takes care of cleaning up old rootfs state and keeping only the rootfs data you want to keep. - -A Terraform setup that runs `flatcar-reset` when the cloud instance userdata changes can be found in the [flatcar-terraform repository][example-repo]. -The list of paths in the rootfs to keep can be configured. - -### Reformatting - -Another alternative to `flatcar-reset` is to reformat the root filesystem with Ignition to ensure that no old state is present, or use cloud-provider [reinstall options like on Equinix Metal](https://registry.terraform.io/providers/equinix/equinix/latest/docs/resources/equinix_metal_device#reinstall). -Persistent data should be stored on another partition which should be set to be kept. - -We can also preserve the machine ID by setting it as kernel cmdline parameter (it must not be kept as file on the root filesystem because that prevents the systemd first-boot semantics to enable units through the preset Ignition creates). - -This Container Linux Config snippet takes care of reformating the root filesystem and places a reprovisioning helper script on the OEM partition: - -```yaml -storage: - files: - - path: /reprovision - filesystem: oem - mode: 0755 - contents: - inline: | - #!/bin/bash - set -euo pipefail - touch /usr/share/oem/grub.cfg - sed -i "/linux_append systemd.machine_id=.*/d" /usr/share/oem/grub.cfg - echo "set linux_append=\"\$linux_append systemd.machine_id=$(cat /etc/machine-id)\"" >> /usr/share/oem/grub.cfg - touch /boot/flatcar/first_boot - filesystems: - - name: root - mount: - device: /dev/disk/by-label/ROOT - format: ext4 - wipe_filesystem: true - label: ROOT - - name: oem - mount: - device: /dev/disk/by-label/OEM - format: btrfs - label: OEM -``` - -The final User Data needs to be stored on a place where modifications are allowed without destroying the node. -For some Terraform providers it is directly possible to allow changes but that is not always the case. -A good option then could be AWS S3 or other similar cloud storage solutions. -The real User Data of the node is just an Ignition Config that references the external User Data: - -``` -{ "ignition": { "version": "2.1.0", "config": { "replace": { "source": "s3://..." } } } } -``` - -Under these conditions it is possible to run `sudo /usr/share/oem/reprovision` on the node and trigger reboot for the new Ignition Config to take effect (assuming data in S3): - -``` -resource "null_resource" "reboot-when-ignition-changes" { - for_each = toset(var.machines) - # Triggered when the Ignition Config changes - triggers = { - ignition_config = data.ct_config.machine-ignitions[each.key].rendered - } - # Wait for the new Ignition config object to be ready before rebooting - depends_on = [aws_s3_bucket_object.object] - # Trigger running Ignition on the next reboot and reboot the instance (current limitation: also runs on the first provisioning) - provisioner "local-exec" { - command = "while ! ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null core@${packet_device.machine[each.key].access_public_ipv4} sudo /usr/share/oem/reprovision ; do sleep 1; done; while ! ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null core@${packet_device.machine[each.key].access_public_ipv4} sudo systemctl reboot; do sleep 1; done" - } -} -``` - -## Examples - -You can find the full code for working examples in this [git repository][example-repo]. - - -[cloud]: ../../installing/cloud/ -[butane-configs]: ../config-transpiler -[terraform-ct-provider]: https://registry.terraform.io/providers/poseidon/ct/latest -[terraform-ignition-provider]: https://registry.terraform.io/providers/community-terraform-providers/ignition/latest -[boot-process]: ../ignition/boot-process/#reprovisioning -[example-repo]: https://github.com/flatcar/flatcar-terraform diff --git a/content/docs/latest/reference/_index.md b/content/docs/latest/reference/_index.md deleted file mode 100644 index 31fd786ab..000000000 --- a/content/docs/latest/reference/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -content_type: reference -title: Reference -description: > - Processes, concepts, APIs and troubleshooting guides for working with Flatcar Container Linux. -weight: 120 ---- diff --git a/content/docs/latest/reference/developer-guides/_index.md b/content/docs/latest/reference/developer-guides/_index.md deleted file mode 100644 index 7957f35f5..000000000 --- a/content/docs/latest/reference/developer-guides/_index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Developer Guides -weight: 10 -aliases: - - ../os/developer-guides ---- - -This section is aimed at curious developers interested in building Flatcar Container Linux from source and/or in modifying the OS. -We provide a containerised SDK that allows you to extend Flatcar and to build your own OS images. -We also provide OEM functionality for cloud providers and similar use cases to customize Flatcar Container Linux to run within their environment. - -* [Guide to building custom Flatcar images from source][mod-cl] -* [Vending production images / CI integration][production-images] -* [Building custom kernel modules][kernel-modules] -* [SDK tips and tricks][sdk-tips] -* [SDK build process][sdk-bootstrapping] -* [Disk layout][disk-layout] -* [Kola integration testing framework][mantle-utils] -* [Release guide][release-guide] - -[sdk-tips]: sdk-tips-and-tricks -[disk-layout]: sdk-disk-partitions -[production-images]: sdk-building-production-images -[mod-cl]: sdk-modifying-flatcar -[kernel-modules]: kernel-modules -[sdk-bootstrapping]: sdk-bootstrapping -[mantle-utils]: https://github.com/flatcar/mantle/blob/flatcar-master/README.md#kola -[release-guide]: release-guide diff --git a/content/docs/latest/setup/security/adding-certificate-authorities.md b/content/docs/latest/security/cert-auth/adding-certificate-authorities.md similarity index 93% rename from content/docs/latest/setup/security/adding-certificate-authorities.md rename to content/docs/latest/security/cert-auth/adding-certificate-authorities.md index 144115685..246db9428 100644 --- a/content/docs/latest/setup/security/adding-certificate-authorities.md +++ b/content/docs/latest/security/cert-auth/adding-certificate-authorities.md @@ -3,6 +3,7 @@ title: Custom certificate authorities description: How to add and configure your own CAs. weight: 30 aliases: + - /docs/latest/setup/security/adding-certificate-authorities/ - ../../os/adding-certificate-authorities - ../../clusters/securing/adding-certificate-authorities --- diff --git a/content/docs/latest/setup/customization/customize-etcd-unit.md b/content/docs/latest/security/cert-auth/customize-etcd-unit.md similarity index 98% rename from content/docs/latest/setup/customization/customize-etcd-unit.md rename to content/docs/latest/security/cert-auth/customize-etcd-unit.md index e5bf52fa8..f46e7f473 100644 --- a/content/docs/latest/setup/customization/customize-etcd-unit.md +++ b/content/docs/latest/security/cert-auth/customize-etcd-unit.md @@ -3,6 +3,7 @@ title: Customizing the etcd unit description: How to setup etcd to use client certificates. weight: 50 aliases: + - /docs/latest/setup/customization/customize-etcd-unit/ - ../../os/customize-etcd-unit - ../../clusters/customization/customize-etcd-unit --- diff --git a/content/docs/latest/setup/security/customizing-sshd.md b/content/docs/latest/security/cert-auth/customizing-sshd.md similarity index 99% rename from content/docs/latest/setup/security/customizing-sshd.md rename to content/docs/latest/security/cert-auth/customizing-sshd.md index 7620568f0..80200c866 100644 --- a/content/docs/latest/setup/security/customizing-sshd.md +++ b/content/docs/latest/security/cert-auth/customizing-sshd.md @@ -3,6 +3,7 @@ title: Customizing the SSH daemon description: How to change the way SSH runs. weight: 10 aliases: + - /docs/latest/setup/security/customizing-sshd/ - ../../os/customizing-sshd - ../../clusters/securing/customizing-sshd --- diff --git a/content/docs/latest/setup/security/generate-self-signed-certificates.md b/content/docs/latest/security/cert-auth/generate-self-signed-certificates.md similarity index 99% rename from content/docs/latest/setup/security/generate-self-signed-certificates.md rename to content/docs/latest/security/cert-auth/generate-self-signed-certificates.md index e94c20d2f..cbe05fb39 100644 --- a/content/docs/latest/setup/security/generate-self-signed-certificates.md +++ b/content/docs/latest/security/cert-auth/generate-self-signed-certificates.md @@ -3,6 +3,7 @@ title: Generate self-signed certificates description: How to create a certificate authority and generate certificates for servers, peers, and clients. weight: 30 aliases: + - /docs/latest/setup/security/generate-self-signed-certificates/ - ../../os/generate-self-signed-certificates - ../../container-runtimes/generate-self-signed-certificates --- diff --git a/content/docs/latest/setup/security/sssd.md b/content/docs/latest/security/cert-auth/sssd.md similarity index 96% rename from content/docs/latest/setup/security/sssd.md rename to content/docs/latest/security/cert-auth/sssd.md index 2eb889607..1e251be78 100644 --- a/content/docs/latest/setup/security/sssd.md +++ b/content/docs/latest/security/cert-auth/sssd.md @@ -4,6 +4,7 @@ linktitle: Configuring SSSD description: Using the System Security Service Daemon to integrate with enterprise authentication services. weight: 10 aliases: + - /docs/latest/setup/security/sssd/ - ../../os/sssd - ../../clusters/securing/sssd --- diff --git a/content/docs/latest/reference/constants-and-ids.md b/content/docs/latest/security/constants-and-ids.md similarity index 97% rename from content/docs/latest/reference/constants-and-ids.md rename to content/docs/latest/security/constants-and-ids.md index e7506a31d..b718b2855 100644 --- a/content/docs/latest/reference/constants-and-ids.md +++ b/content/docs/latest/security/constants-and-ids.md @@ -2,6 +2,7 @@ title: Constants and IDs weight: 30 aliases: + - /docs/latest/reference/constants-and-ids/ - ../os/constants-and-ids --- diff --git a/content/docs/latest/setup/security/luks.md b/content/docs/latest/security/encryption/luks.md similarity index 99% rename from content/docs/latest/setup/security/luks.md rename to content/docs/latest/security/encryption/luks.md index 0a05e263d..d688a341c 100644 --- a/content/docs/latest/setup/security/luks.md +++ b/content/docs/latest/security/encryption/luks.md @@ -3,6 +3,8 @@ title: Setting up LUKS disk encryption linktitle: Setting up LUKS disk encryption description: Setting up LUKS disk encryption with automatic unlocking using systemd-cryptenroll or Clevis weight: 10 +aliases: + - /docs/latest/setup/security/luks/ --- Depending on where you run Flatcar Container Linux you might want to protect the data on disk against attackers that could pull out a hard disk or get access to a snapshot copy of it. diff --git a/content/docs/latest/setup/security/selinux.md b/content/docs/latest/security/encryption/selinux.md similarity index 98% rename from content/docs/latest/setup/security/selinux.md rename to content/docs/latest/security/encryption/selinux.md index 4b8a18178..7f865b6ad 100644 --- a/content/docs/latest/setup/security/selinux.md +++ b/content/docs/latest/security/encryption/selinux.md @@ -4,6 +4,7 @@ linktitle: SELinux description: How to configure, enable or disable SELinux. weight: 10 aliases: + - /docs/latest/setup/security/selinux/ - ../../os/selinux - ../../clusters/securing/selinux --- diff --git a/content/docs/latest/setup/security/audit.md b/content/docs/latest/security/hardening/audit.md similarity index 95% rename from content/docs/latest/setup/security/audit.md rename to content/docs/latest/security/hardening/audit.md index 9e2d33488..9c09785b1 100644 --- a/content/docs/latest/setup/security/audit.md +++ b/content/docs/latest/security/hardening/audit.md @@ -3,6 +3,8 @@ title: Setting up the Linux Auditing System linktitle: Set up audit description: Setting up the Linux Auditing System. weight: 20 +aliases: + - /docs/latest/setup/security/audit/ --- On Flatcar Container Linux `audit-rules.service` loads the audit rules to set up the logging filters for the kernel messages. diff --git a/content/docs/latest/setup/security/disabling-smt.md b/content/docs/latest/security/hardening/disabling-smt.md similarity index 98% rename from content/docs/latest/setup/security/disabling-smt.md rename to content/docs/latest/security/hardening/disabling-smt.md index 3fc7448aa..c299e9654 100644 --- a/content/docs/latest/setup/security/disabling-smt.md +++ b/content/docs/latest/security/hardening/disabling-smt.md @@ -4,6 +4,7 @@ linktitle: Disabling SMT description: How to disable Simultaneous Multi-Threading. weight: 60 aliases: + - /docs/latest/setup/security/disabling-smt/ - ../../os/disabling-smt - ../../clusters/securing/disabling-smt --- diff --git a/content/docs/latest/setup/security/fips.md b/content/docs/latest/security/hardening/fips.md similarity index 99% rename from content/docs/latest/setup/security/fips.md rename to content/docs/latest/security/hardening/fips.md index f1e13c5ab..aa33ea9b4 100644 --- a/content/docs/latest/setup/security/fips.md +++ b/content/docs/latest/security/hardening/fips.md @@ -3,6 +3,8 @@ title: Flatcar Container Linux FIPS guide linktitle: FIPS mode description: Enabling FIPS mode. weight: 20 +aliases: + - /docs/latest/setup/security/fips/ --- FIPS stands for Federal Information Processing Standards, a set of standards issued by the National Institute of Standards and Technology (NIST). While Flatcar is not officially FIPS certified, it is possible to deploy it so that it is compliant with two of these standards: diff --git a/content/docs/latest/setup/security/hardening-guide.md b/content/docs/latest/security/hardening/hardening-guide.md similarity index 98% rename from content/docs/latest/setup/security/hardening-guide.md rename to content/docs/latest/security/hardening/hardening-guide.md index 461340cd5..235c7c9fc 100644 --- a/content/docs/latest/setup/security/hardening-guide.md +++ b/content/docs/latest/security/hardening/hardening-guide.md @@ -4,6 +4,7 @@ linktitle: Hardening options description: Disabling unnecessary services and other hardening options. weight: 20 aliases: + - /docs/latest/setup/security/hardening-guide/ - ../../os/hardening-guide - ../../clusters/securing/hardening-guide --- diff --git a/content/docs/latest/setup/security/trusted-computing-hardware-requirements.md b/content/docs/latest/security/hardening/trusted-computing-hardware-requirements.md similarity index 97% rename from content/docs/latest/setup/security/trusted-computing-hardware-requirements.md rename to content/docs/latest/security/hardening/trusted-computing-hardware-requirements.md index 3e7213f0f..a4d55f1b8 100644 --- a/content/docs/latest/setup/security/trusted-computing-hardware-requirements.md +++ b/content/docs/latest/security/hardening/trusted-computing-hardware-requirements.md @@ -4,6 +4,7 @@ linktitle: Trusted Computing description: How to check for hardware and firmware support for using Trusted Computing. weight: 20 aliases: + - /docs/latest/setup/security/trusted-computing-hardware-requirements/ - ../../os/trusted-computing-hardware-requirements - ../../clusters/securing/trusted-computing-hardware-requirements --- diff --git a/content/docs/latest/reference/supply-chain.md b/content/docs/latest/security/supply-chain.md similarity index 99% rename from content/docs/latest/reference/supply-chain.md rename to content/docs/latest/security/supply-chain.md index 6e035995a..c6088d884 100644 --- a/content/docs/latest/reference/supply-chain.md +++ b/content/docs/latest/security/supply-chain.md @@ -1,6 +1,8 @@ --- title: Supply chain security mechanisms weight: 40 +aliases: + - /docs/latest/reference/supply-chain/ --- diff --git a/content/docs/latest/setup/_index.md b/content/docs/latest/setup/_index.md deleted file mode 100644 index 28b021e72..000000000 --- a/content/docs/latest/setup/_index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Setup and Operations -description: > - Follow these guides to connect your machines together as a cluster. - Configure machine parameters, create users, inject multiple SSH keys, and - more with Butane configs. -weight: 50 ---- - diff --git a/content/docs/latest/setup/clusters/_index.md b/content/docs/latest/setup/clusters/_index.md deleted file mode 100644 index 1d0533ba5..000000000 --- a/content/docs/latest/setup/clusters/_index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Managing Clusters -description: > - One of the most common uses of Flatcar Container Linux is to create - clusters of machines. These guides will help you understand the different - cluster architectures that you can choose from, setup cluster discovery and - more. -weight: 40 ---- diff --git a/content/docs/latest/setup/customization/_index.md b/content/docs/latest/setup/customization/_index.md deleted file mode 100644 index 5ae4278d1..000000000 --- a/content/docs/latest/setup/customization/_index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Customizing Flatcar -linktitle: Common Customizations -description: > - Guides and examples on typical customizations done on Flatcar instances. - Including managing users, the DNS configuration, kernel modules, network - parameters and more. -weight: 10 -aliases: - - ../clusters/customization ---- diff --git a/content/docs/latest/setup/debug/_index.md b/content/docs/latest/setup/debug/_index.md deleted file mode 100644 index 52e73b6ca..000000000 --- a/content/docs/latest/setup/debug/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Debugging -description: > - Useful tools and techniques to understand what's going on inside a - Flatcar instance when things don't work as expected. -weight: 50 ---- diff --git a/content/docs/latest/setup/releases/_index.md b/content/docs/latest/setup/releases/_index.md deleted file mode 100644 index 1eafb50ed..000000000 --- a/content/docs/latest/setup/releases/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Managing Releases -description: > - Guides to help you select which Flatcar release to run on your instances, - how to set the update configuration, verify the image if you download it - manually. -weight: 20 -aliases: - - ../../clusters/management ---- diff --git a/content/docs/latest/setup/security/_index.md b/content/docs/latest/setup/security/_index.md deleted file mode 100644 index 12e2df06f..000000000 --- a/content/docs/latest/setup/security/_index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Additional Security Options -linktitle: Security Options -description: > - Flatcar Container Linux has a number of security measures enabled by - default, but there's always more things that can be enabled if desired. - These guides provide information on what additional options can be set. -weight: 45 -aliases: - - ../clusters/securing ---- diff --git a/content/docs/latest/setup/storage/_index.md b/content/docs/latest/setup/storage/_index.md deleted file mode 100644 index 49c0b0c67..000000000 --- a/content/docs/latest/setup/storage/_index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Managing Storage on Flatcar Container Linux -linktitle: Storage Setup -description: Adding, Extending and Configuring Storage on Flatcar. -weight: 25 -aliases: - - ../clusters/scaling/ ---- diff --git a/content/docs/latest/setup/systemd/_index.md b/content/docs/latest/setup/systemd/_index.md deleted file mode 100644 index dd07e3b34..000000000 --- a/content/docs/latest/setup/systemd/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Using Systemd on Flatcar Container Linux -linktitle: Using Systemd -description: > - Flatcar makes heavy use of systemd services and customization techniques. - Understanding core concepts like drop-in units, timers and embedding - environment variables, make it easier to apply the right changes to an - instance being deployed. These guides can help you get up to speed. -weight: 5 ---- diff --git a/content/docs/latest/sys-ext/sys-ext.md b/content/docs/latest/sys-ext/sys-ext.md new file mode 100644 index 000000000..474586639 --- /dev/null +++ b/content/docs/latest/sys-ext/sys-ext.md @@ -0,0 +1,6 @@ +--- +title: System Extensions for Flatcar +weight: 10 +description: > + Extending the base OS with systemd-sysext images. +--- diff --git a/content/docs/latest/nebraska/authorization.md b/content/docs/latest/updates-releases/nebraska/authorization.md similarity index 99% rename from content/docs/latest/nebraska/authorization.md rename to content/docs/latest/updates-releases/nebraska/authorization.md index 4b0787244..d8b969a1e 100644 --- a/content/docs/latest/nebraska/authorization.md +++ b/content/docs/latest/updates-releases/nebraska/authorization.md @@ -1,6 +1,8 @@ --- title: Deployment & Authorization weight: 10 +aliases: + - /docs/latest/nebraska/authorization/ --- Nebraska uses either a noop authentication or OIDC to authenticate and authorize users. diff --git a/content/docs/latest/nebraska/autovacuum-tune.sql b/content/docs/latest/updates-releases/nebraska/autovacuum-tune.sql similarity index 100% rename from content/docs/latest/nebraska/autovacuum-tune.sql rename to content/docs/latest/updates-releases/nebraska/autovacuum-tune.sql diff --git a/content/docs/latest/nebraska/development.md b/content/docs/latest/updates-releases/nebraska/development.md similarity index 99% rename from content/docs/latest/nebraska/development.md rename to content/docs/latest/updates-releases/nebraska/development.md index f0a3d6ab3..5ccf5ff88 100644 --- a/content/docs/latest/nebraska/development.md +++ b/content/docs/latest/updates-releases/nebraska/development.md @@ -1,6 +1,8 @@ --- title: Development weight: 20 +aliases: + - /docs/latest/nebraska/development/ --- This section shows how to set up a development environment for Nebraska. diff --git a/content/docs/latest/nebraska/i18n/contributing.md b/content/docs/latest/updates-releases/nebraska/i18n/contributing.md similarity index 98% rename from content/docs/latest/nebraska/i18n/contributing.md rename to content/docs/latest/updates-releases/nebraska/i18n/contributing.md index dd4e64c5b..1da8b2f3f 100644 --- a/content/docs/latest/nebraska/i18n/contributing.md +++ b/content/docs/latest/updates-releases/nebraska/i18n/contributing.md @@ -1,6 +1,8 @@ --- title: Contributing to Internationalization linkTitle: Contributing +aliases: + - /docs/latest/nebraska/i18n/contributing/ --- This section introduces some concepts for contributing translations, and is diff --git a/content/docs/latest/nebraska/images/nebraska-hosts-packages.png b/content/docs/latest/updates-releases/nebraska/images/nebraska-hosts-packages.png similarity index 100% rename from content/docs/latest/nebraska/images/nebraska-hosts-packages.png rename to content/docs/latest/updates-releases/nebraska/images/nebraska-hosts-packages.png diff --git a/content/docs/latest/nebraska/managing-updates.md b/content/docs/latest/updates-releases/nebraska/managing-updates.md similarity index 99% rename from content/docs/latest/nebraska/managing-updates.md rename to content/docs/latest/updates-releases/nebraska/managing-updates.md index 97ab539bf..1fa12690b 100644 --- a/content/docs/latest/nebraska/managing-updates.md +++ b/content/docs/latest/updates-releases/nebraska/managing-updates.md @@ -1,6 +1,8 @@ --- title: Managing Flatcar updates weight: 10 +aliases: + - /docs/latest/nebraska/managing-updates/ --- Once you have Nebraska up and running, a common use-case is to manage Flatcar Container Linux updates. diff --git a/content/docs/latest/nebraska/migrate-to-older-version.md b/content/docs/latest/updates-releases/nebraska/migrate-to-older-version.md similarity index 91% rename from content/docs/latest/nebraska/migrate-to-older-version.md rename to content/docs/latest/updates-releases/nebraska/migrate-to-older-version.md index 700dd7022..b8537318a 100644 --- a/content/docs/latest/nebraska/migrate-to-older-version.md +++ b/content/docs/latest/updates-releases/nebraska/migrate-to-older-version.md @@ -1,6 +1,8 @@ --- title: Migrating to older version of Nebraska. weight: 11 +aliases: + - /docs/latest/nebraska/migrate-to-older-version/ --- diff --git a/content/docs/latest/nebraska/nebraska-logo.svg b/content/docs/latest/updates-releases/nebraska/nebraska-logo.svg similarity index 100% rename from content/docs/latest/nebraska/nebraska-logo.svg rename to content/docs/latest/updates-releases/nebraska/nebraska-logo.svg diff --git a/content/docs/latest/setup/releases/switching-channels.md b/content/docs/latest/updates-releases/releases/switching-channels.md similarity index 99% rename from content/docs/latest/setup/releases/switching-channels.md rename to content/docs/latest/updates-releases/releases/switching-channels.md index 626c00acc..74f7e698b 100644 --- a/content/docs/latest/setup/releases/switching-channels.md +++ b/content/docs/latest/updates-releases/releases/switching-channels.md @@ -3,6 +3,7 @@ title: Switching release channels description: How to switch to a different release channel. weight: 10 aliases: + - /docs/latest/setup/releases/switching-channels/ - ../../os/switching-channels - ../../clusters/management/switching-channels --- diff --git a/content/docs/latest/setup/releases/update-conf.md b/content/docs/latest/updates-releases/releases/update-conf.md similarity index 98% rename from content/docs/latest/setup/releases/update-conf.md rename to content/docs/latest/updates-releases/releases/update-conf.md index 158563429..e92073524 100644 --- a/content/docs/latest/setup/releases/update-conf.md +++ b/content/docs/latest/updates-releases/releases/update-conf.md @@ -5,6 +5,7 @@ linktitle: update.conf description: Fields and Location of the Flatcar update configuration file. weight: 100 aliases: + - /docs/latest/setup/releases/update-conf/ - ../../os/update-conf - ../../clusters/management/update-conf --- diff --git a/content/docs/latest/setup/releases/update-strategies.md b/content/docs/latest/updates-releases/releases/update-strategies.md similarity index 99% rename from content/docs/latest/setup/releases/update-strategies.md rename to content/docs/latest/updates-releases/releases/update-strategies.md index 60b45ac85..5f1e29a4e 100644 --- a/content/docs/latest/setup/releases/update-strategies.md +++ b/content/docs/latest/updates-releases/releases/update-strategies.md @@ -3,6 +3,7 @@ title: Update and reboot strategies description: How to configure when you Flatcar instances should reboot. weight: 30 aliases: + - /docs/latest/setup/releases/update-strategies/ - ../../os/update-strategies - ../../clusters/creation/update-strategies --- diff --git a/content/docs/latest/setup/releases/verify-images.md b/content/docs/latest/updates-releases/releases/verify-images.md similarity index 98% rename from content/docs/latest/setup/releases/verify-images.md rename to content/docs/latest/updates-releases/releases/verify-images.md index 80476459f..95bb1a34b 100644 --- a/content/docs/latest/setup/releases/verify-images.md +++ b/content/docs/latest/updates-releases/releases/verify-images.md @@ -4,6 +4,7 @@ linktitle: Verifying Images description: How to verify the authenticity of Flatcar Container Linux images, using GPG. weight: 40 aliases: + - /docs/latest/setup/releases/verify-images/ - ../../os/verify-images - ../../clusters/creation/verify-images --- From cd000ab35e51bd2f9b6f3668794426c61bf89557 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Wed, 3 Jun 2026 20:37:27 +0100 Subject: [PATCH 02/20] fix: track _index.md section files (fix sidebar collapse on staging) Signed-off-by: thisisobate --- content/docs/.gitignore | 2 +- .../docs/latest/coreos-migration/_index.md | 50 ++++ content/docs/latest/deploy/_index.md | 6 + .../docs/latest/deploy/bare-metal/_index.md | 8 + content/docs/latest/deploy/cloud/_index.md | 10 + .../docs/latest/deploy/virt-options/_index.md | 42 ++++ content/docs/latest/devguide/_index.md | 30 +++ content/docs/latest/diagnostics/_index.md | 9 + content/docs/latest/fb-provision/_index.md | 11 + .../docs/latest/fb-provision/butane/_index.md | 81 ++++++ .../latest/fb-provision/cl-config/_index.md | 154 ++++++++++++ .../fb-provision/customize-image/_index.md | 9 + .../latest/fb-provision/ignition/_index.md | 58 +++++ .../fb-provision/infrastructure/_index.md | 143 +++++++++++ .../docs/latest/fb-provision/vms/_index.md | 190 ++++++++++++++ content/docs/latest/getting-started/_index.md | 233 ++++++++++++++++++ .../getting-started/learning-series/_index.md | 23 ++ content/docs/latest/orchestrate/_index.md | 6 + .../latest/orchestrate/clusters/_index.md | 11 + .../latest/orchestrate/containers/_index.md | 12 + .../latest/orchestrate/kubernetes/_index.md | 6 + content/docs/latest/os-config/_index.md | 11 + .../latest/os-config/host-config/_index.md | 6 + .../docs/latest/os-config/network/_index.md | 6 + .../docs/latest/os-config/storage/_index.md | 9 + .../docs/latest/os-config/systemd/_index.md | 12 + content/docs/latest/security/_index.md | 6 + .../docs/latest/security/cert-auth/_index.md | 12 + .../docs/latest/security/encryption/_index.md | 6 + .../docs/latest/security/hardening/_index.md | 6 + content/docs/latest/sys-ext/_index.md | 205 +++++++++++++++ .../docs/latest/updates-releases/_index.md | 15 ++ .../updates-releases/nebraska/_index.md | 6 + .../updates-releases/nebraska/i18n/_index.md | 33 +++ .../updates-releases/releases/_index.md | 11 + 35 files changed, 1437 insertions(+), 1 deletion(-) create mode 100644 content/docs/latest/coreos-migration/_index.md create mode 100644 content/docs/latest/deploy/_index.md create mode 100644 content/docs/latest/deploy/bare-metal/_index.md create mode 100644 content/docs/latest/deploy/cloud/_index.md create mode 100644 content/docs/latest/deploy/virt-options/_index.md create mode 100644 content/docs/latest/devguide/_index.md create mode 100644 content/docs/latest/diagnostics/_index.md create mode 100644 content/docs/latest/fb-provision/_index.md create mode 100644 content/docs/latest/fb-provision/butane/_index.md create mode 100644 content/docs/latest/fb-provision/cl-config/_index.md create mode 100644 content/docs/latest/fb-provision/customize-image/_index.md create mode 100644 content/docs/latest/fb-provision/ignition/_index.md create mode 100644 content/docs/latest/fb-provision/infrastructure/_index.md create mode 100644 content/docs/latest/fb-provision/vms/_index.md create mode 100644 content/docs/latest/getting-started/_index.md create mode 100644 content/docs/latest/getting-started/learning-series/_index.md create mode 100644 content/docs/latest/orchestrate/_index.md create mode 100644 content/docs/latest/orchestrate/clusters/_index.md create mode 100644 content/docs/latest/orchestrate/containers/_index.md create mode 100644 content/docs/latest/orchestrate/kubernetes/_index.md create mode 100644 content/docs/latest/os-config/_index.md create mode 100644 content/docs/latest/os-config/host-config/_index.md create mode 100644 content/docs/latest/os-config/network/_index.md create mode 100644 content/docs/latest/os-config/storage/_index.md create mode 100644 content/docs/latest/os-config/systemd/_index.md create mode 100644 content/docs/latest/security/_index.md create mode 100644 content/docs/latest/security/cert-auth/_index.md create mode 100644 content/docs/latest/security/encryption/_index.md create mode 100644 content/docs/latest/security/hardening/_index.md create mode 100644 content/docs/latest/sys-ext/_index.md create mode 100644 content/docs/latest/updates-releases/_index.md create mode 100644 content/docs/latest/updates-releases/nebraska/_index.md create mode 100644 content/docs/latest/updates-releases/nebraska/i18n/_index.md create mode 100644 content/docs/latest/updates-releases/releases/_index.md diff --git a/content/docs/.gitignore b/content/docs/.gitignore index f20385a1a..51527e2bf 100644 --- a/content/docs/.gitignore +++ b/content/docs/.gitignore @@ -1 +1 @@ -_index.md +/_index.md diff --git a/content/docs/latest/coreos-migration/_index.md b/content/docs/latest/coreos-migration/_index.md new file mode 100644 index 000000000..b94dd7db9 --- /dev/null +++ b/content/docs/latest/coreos-migration/_index.md @@ -0,0 +1,50 @@ +--- +title: Migration from CoreOS Container Linux +linktitle: Migrating from CoreOS +weight: 100 +aliases: + - /docs/latest/migrating-from-coreos/ + - os/migrate-from-container-linux +--- + +While Flatcar is compatible with CoreOS Container Linux there are some naming differences you need to be aware of. + +**NOTE:** See [Updating from CoreOS Container Linux](update-from-container-linux) +for additional information on updating an existing cluster. + +## Installation + +_Optional:_ Instead of `coreos-installer` you should use `flatcar-installer`. + +## Kernel command line parameters + +_Optional:_ Instead of providing the `coreos.first_boot=1` argument via the boot loader you should provide `flatcar.first_boot=1`. +This forces provisioning via Ignition even if the machine (image) was booted already before. + +_Optional:_ Instead of providing the `coreos.config.url=SOMEURL` argument via the boot loader you should provide `ignition.config.url=SOMEURL` +to tell Ignition to download the configuration. +The change to a more generic name was done upstream by the Ignition project. Version 0.33 still supports both names and we +also do this via the analogous `flatcar.config.url` option but we encourage the generic name because future versions of Ignition +will only support `ignition.config.url`. + +_Optional:_ Instead of providing the `coreos.oem.id=NAME` argument via the boot loader you should provide `flatcar.oem.id=NAME`. +(A change to the more generic name `ignition.platform.id` was done upstream by the Afterburn project but is not part of Container Linux yet.) + +**Recover from or prevent errors with missing OEM settings (e.g., `coreos-metadata-sshkeys@core.service`):** While current releases handle both `coreos.oem` and `flatcar.oem` names, previous releases still required `flatcar.oem.…`. +In that case you need to change the variables in the file `/usr/share/oem/grub.cfg` when you update from CoreOS Container Linux: + +```text +# GRUB settings +set oem_id="myoemvalue" +set linux_append="$linux flatcar.oem.id=myoemvalue" +``` + +## Ignition configuration with QEMU + +_Optional:_ Instead of using `opt/com.coreos/config` in the `-fw_cfg` name-value argument pair for QEMU/KVM or libvirt you need to use `opt/org.flatcar-linux/config`. +The value in the argument pair specifies the Ignition file to use. + +## Ignition configuration with VMware + +_Optional:_ Instead of `coreos.config.data` and `coreos.config.data.encoding` for the VMware `guestinfo.VARIABLE` command line options you should use `ignition.config.data` and `ignition.config.data.encoding`. +Same as for the `ignition.config.url` kernel parameter this change was done upstream by the Ignition project. diff --git a/content/docs/latest/deploy/_index.md b/content/docs/latest/deploy/_index.md new file mode 100644 index 000000000..0bb6f1fc7 --- /dev/null +++ b/content/docs/latest/deploy/_index.md @@ -0,0 +1,6 @@ +--- +title: Deployments +weight: 50 +description: > + Deploy Flatcar Container Linux to cloud providers, virtualization platforms, and bare metal. +--- diff --git a/content/docs/latest/deploy/bare-metal/_index.md b/content/docs/latest/deploy/bare-metal/_index.md new file mode 100644 index 000000000..4cec1840f --- /dev/null +++ b/content/docs/latest/deploy/bare-metal/_index.md @@ -0,0 +1,8 @@ +--- +title: Bare Metal +weight: 30 +description: This section provides information and guidance on running Flatcar instances in bare-metal environments. +aliases: + - /docs/latest/installing/bare-metal/ + - ../bare-metal +--- diff --git a/content/docs/latest/deploy/cloud/_index.md b/content/docs/latest/deploy/cloud/_index.md new file mode 100644 index 000000000..1882f04cd --- /dev/null +++ b/content/docs/latest/deploy/cloud/_index.md @@ -0,0 +1,10 @@ +--- +title: Cloud Providers +weight: 10 +description: > + This section provides information and guidance on running Flatcar + instances in different cloud environments. +aliases: + - /docs/latest/installing/cloud/ + - ../cloud-providers +--- diff --git a/content/docs/latest/deploy/virt-options/_index.md b/content/docs/latest/deploy/virt-options/_index.md new file mode 100644 index 000000000..62f4cfd30 --- /dev/null +++ b/content/docs/latest/deploy/virt-options/_index.md @@ -0,0 +1,42 @@ +--- +title: Virtualization Options +weight: 40 +aliases: + - /docs/latest/installing/community-platforms/ + - ../os/community-platforms + - ../community-platforms +--- + +The Flatcar Container Linux community has provided support for Flatcar Container Linux on a number of platforms beyond those [officially supported][official-support] (i.e, fully covered in the automated tests) by Kinvolk. + + + +The platforms and providers listed below each provide support and documentation for running Flatcar Container Linux: + +## Cloud providers + +* [Exoscale][exoscale] +* [OVHcloud][ovhcloud] +* [Rackspace Cloud][rackspace] +* [Scaleway][scaleway] +* [VMWare][vmware] +* [Vultr VPS][vultr] + +## Other providers + +* [Eucalyptus][eucalyptus] +* [Proxmox VE][proxmoxve] +* [Vagrant][vagrant] +* [VirtualBox][virtualbox] + +[exoscale]: exoscale +[rackspace]: rackspace +[vultr]: vultr +[eucalyptus]: eucalyptus +[scaleway]: scaleway +[vagrant]: ../vms/vagrant +[virtualbox]: ../vms/virtualbox +[official-support]: ../../ +[ovhcloud]: ovhcloud +[proxmoxve]: proxmoxve +[vmware]: vmware diff --git a/content/docs/latest/devguide/_index.md b/content/docs/latest/devguide/_index.md new file mode 100644 index 000000000..d155a5330 --- /dev/null +++ b/content/docs/latest/devguide/_index.md @@ -0,0 +1,30 @@ +--- +title: Developer Guides +weight: 110 +aliases: + - /docs/latest/reference/developer-guides/ + - /docs/latest/reference/ + - ../os/developer-guides +--- + +This section is aimed at curious developers interested in building Flatcar Container Linux from source and/or in modifying the OS. +We provide a containerised SDK that allows you to extend Flatcar and to build your own OS images. +We also provide OEM functionality for cloud providers and similar use cases to customize Flatcar Container Linux to run within their environment. + +- [Guide to building custom Flatcar images from source][mod-cl] +- [Vending production images / CI integration][production-images] +- [Building custom kernel modules][kernel-modules] +- [SDK tips and tricks][sdk-tips] +- [SDK build process][sdk-bootstrapping] +- [Disk layout][disk-layout] +- [Kola integration testing framework][mantle-utils] +- [Release guide][release-guide] + +[sdk-tips]: sdk-tips-and-tricks +[disk-layout]: sdk-disk-partitions +[production-images]: sdk-building-production-images +[mod-cl]: sdk-modifying-flatcar +[kernel-modules]: kernel-modules +[sdk-bootstrapping]: sdk-bootstrapping +[mantle-utils]: https://github.com/flatcar/mantle/blob/flatcar-master/README.md#kola +[release-guide]: release-guide diff --git a/content/docs/latest/diagnostics/_index.md b/content/docs/latest/diagnostics/_index.md new file mode 100644 index 000000000..417ab85cd --- /dev/null +++ b/content/docs/latest/diagnostics/_index.md @@ -0,0 +1,9 @@ +--- +title: Diagnostics and Fixing Issues +description: > + Useful tools and techniques to understand what's going on inside a + Flatcar instance when things don't work as expected. +weight: 70 +aliases: + - /docs/latest/setup/debug/ +--- diff --git a/content/docs/latest/fb-provision/_index.md b/content/docs/latest/fb-provision/_index.md new file mode 100644 index 000000000..0ffcd1620 --- /dev/null +++ b/content/docs/latest/fb-provision/_index.md @@ -0,0 +1,11 @@ +--- +title: First Boot & Provisioning +description: > + Several different tools can be used to automate the provisioning of + Flatcar Container Linux images. These guides can help you understand what + each of the tools do, as well as provide plenty of examples of how to use + them. +weight: 20 +aliases: + - /docs/latest/provisioning/ +--- diff --git a/content/docs/latest/fb-provision/butane/_index.md b/content/docs/latest/fb-provision/butane/_index.md new file mode 100644 index 000000000..d536a7f77 --- /dev/null +++ b/content/docs/latest/fb-provision/butane/_index.md @@ -0,0 +1,81 @@ +--- +content_type: butane +title: Butane Config Transpiler +linktitle: Butane Config Transpiler +description: Transforms Butane files into Ignition configuration +main_menu: true +weight: 30 +aliases: + - /docs/latest/provisioning/config-transpiler/ + - ../container-linux-config-transpiler/doc/overview + - ../container-linux-config-transpiler +--- + +Butane is the utility responsible for transforming a user-provided Butane Configuration into an [Ignition][ignition] configuration. The resulting Ignition config can then be provided to a Container Linux machine when it first boots in order to provision it. + +The Butane Config is intended to be human-friendly, and is thus in YAML. The syntax is rather forgiving, and things like references and multi-line strings are supported. + +The resulting Ignition config is very much not intended to be human-friendly. It is an artifact produced by butane that users should simply pass along to their machines. JSON was chosen over a binary format to make the process more transparent and to allow power users to inspect/modify what butane produces, but it would have worked fine if the result from butane had not been human readable at all. + +[butane]: https://github.com/coreos/butane/ +[ignition]: https://github.com/coreos/ignition + +**Note:** Butane is utilized to generate Ignition v3+ configurations. If you are still utilizing a version of Container Linux that requires Ignition v2, you can refer to the [Container Linux Config Transpiler][cl-config] documentation. + +## Why a two-step process? + +There are a couple factors motivating the decision to not incorporate support for Butane Configs directly into the boot process of Container Linux (as in, the ability to provide a Butane Config directly to a booting machine, instead of an Ignition config). + +- By making users run their configs through butane before they attempt to boot a machine, issues with their configs can be caught before any machine attempts to boot. This will save users time, as they can much more quickly find problems with their configs. Were users to provide Butane Configs directly to machines at first boot, they would need to find a way to extract the Ignition logs from a machine that may have failed to boot, which can be a slow and tedious process. +- YAML parsing is a complex process that in the past has been rather error-prone. By only doing JSON parsing in the boot path, we can guarantee that the utilities necessary for a machine to boot are simpler and more reliable. We want to allow users to use YAML however, as it's much more human-friendly than JSON, hence the decision to have a tool separate from the boot path to "transpile" YAML configurations to machine-appropriate JSON ones. + +## Tell me more about Ignition + +[Ignition][ignition] is the utility inside of a Container Linux image that is responsible for setting up a machine. It takes in a configuration, written in JSON, that instructs it to do things like add users, format disks, and install systemd units. The artifacts that butane produces are Ignition configs. All of this should be an implementation detail however, users are encouraged to write Butane Configs for butane, and to simply pass along the produced JSON file to their machines. + +## How similar are Butane Configs and Ignition configs? + +Some features in Butane Configs and Ignition configs are identical. Both support listing users for creation, systemd unit dropins for installation, and files for writing. + +All of the differences stem from the fact that Ignition configs are distribution agnostic. An Ignition config can't just tell Ignition to enable etcd, because Ignition doesn't know what etcd is. The config must tell Ignition what systemd unit to enable, and provide a systemd dropin to configure etcd. + +Butane on the other hand _does_ understand the specifics of Flatcar Container Linux. A user currently can't specify Clevis options on Flatcar and Butane does these sanity checks for the user. + +## Example Butane Config + +The following small example of a Butane Config will ensure that the default core user exists and adds a specified public key + +```yaml +variant: flatcar +version: 1.0.0 +passwd: + users: + - name: core + ssh_authorized_keys: + - ssh-rsa AAAAB......xyz email@host.net +``` + +To turn this Butane Config into a usable Ignition Config, we can then run: `docker run --rm -i quay.io/coreos/butane:latest < your_config.yaml > your_config.json`. This will result in the above YAML being turned into the below JSON + +```json +{ + "ignition": { + "version": "3.3.0" + }, + "passwd": { + "users": [ + { + "name": "core", + "sshAuthorizedKeys": [ + "ssh-rsa AAAAB......xyz email@host.net" + ] + } + ] + } +} +``` + +To learn more about Butane and the configurations that are available, you can refer to the latest [Butane Spec][butane-spec]. + +[butane-spec]: https://coreos.github.io/butane +[cl-config]: ../cl-config diff --git a/content/docs/latest/fb-provision/cl-config/_index.md b/content/docs/latest/fb-provision/cl-config/_index.md new file mode 100644 index 000000000..549034ea4 --- /dev/null +++ b/content/docs/latest/fb-provision/cl-config/_index.md @@ -0,0 +1,154 @@ +--- +title: "[DEPRECATED / EOL] Container Linux Config Transpiler" +description: YAML configuration format used to generate Ignition configs. +weight: 20 +aliases: + - ../os/provisioning + - ../reference/migrating-to-clcs/provisioning +--- + +:warning: TL; DR: Use [Butane](../config-transpiler). While Flatcar does support both Ignition spec version (2.x and 3.x), we encourage folks to use [Butane](../config-transpiler) first but we still maintain / document backward compatibility for users who still rely on Ignition 2.x. :warning: + +Flatcar Container Linux automates machine provisioning with a specialized system for applying initial configuration. This system implements a process of (trans)compilation and validation for machine configs, and an atomic service to apply validated configurations to machines. + +## Container Linux Config + +Flatcar Container Linux admins define these configurations in a format called the [Container Linux Config][clc], which was originally designed for CoreOS Container Linux, but works perfectly well with Flatcar Container Linux. Container Linux Configs are structured as YAML, and intended to be human-readable. The Container Linux Config has features devoted to configuring Flatcar Container Linux services such as [etcd][etcd], [rkt][rkt], Docker, [flannel][flannel], and [locksmith][locksmith]. **The defining feature of the config is that it cannot be sent directly to a Flatcar Container Linux provisioning target**. Instead, it is first validated and transformed into a machine-readable and wire-efficient form. + +The following examples demonstrate the simplicity of the Container Linux Config format. + +This extremely simple Container Linux Config will fetch and run the current release of etcd: + +```yaml +etcd: {} +``` + +Extend the definition to specify the version of etcd to run. The following example will provision a new Flatcar Container Linux machine to fetch and run the etcd service, version 3.1.6: + +```yaml +etcd: + version: 3.1.6 +``` + +Use variable replacement to configure the etcd service with the provisioning target's public and private IPv4 addresses, making it repeatable across a group of machines. + +```yaml +etcd: + advertise_client_urls: http://{PUBLIC_IPV4}:2379 + initial_advertise_peer_urls: http://{PRIVATE_IPV4}:2380 + listen_client_urls: http://0.0.0.0:2379 + listen_peer_urls: http://{PRIVATE_IPV4}:2380 + discovery: https://discovery.etcd.io/ +``` + +`PUBLIC_IPV4` and `PRIVATE_IPV4` are automatically populated from the environment in which Flatcar Container Linux runs, if this metadata exists. Given the many different environments in which Flatcar Container Linux can run, it's difficult if not impossible to accurately determine these variables in every instance. Be certain to check this value as a troubleshooting measure. + +For example, the default metadata for an EC2 environment would be used: `public_ipv4` and `local_ipv4`. On Azure, *either* the virtual IP or public IP could be used for the `PUBLIC_IPV4` (`ct` makes a best guess and uses the virtual IP, but this could change in the future), and the dynamic IP would be used for the `PRIVATE_IPV4`. On bare metal, this information cannot be reliably derived in a general manner, so these variables cannot be used. + +Because variable expansion is unpredictable and complex, and because it is also common for users to inadvertently write invalid configs, the use of a transformation tool is strongly encouraged. The default tool recommended for this task is the [Config Transpiler][ct] (ct for short). The Config Transpiler will validate and transform a Container Linux Config into the format that Flatcar Container Linux can consume: the Ignition Config. + +## Ignition Config + +Ignition, the utility in Flatcar Container Linux responsible for provisioning the machine, fetches and executes the Ignition Config. Flatcar Container Linux directly consumes the Ignition Config configuration format. + +Ignition Configs are mostly static, distro-agnostic, and meant to be generated by a machine rather than a human. While they can be written directly by users, it is highly discouraged due to the ease with which errors may be introduced. Rather than writing Ignition Configs directly, users are encouraged to use provisioning tools like [Matchbox][matchbox], which transparently translate Container Linux Configs to Ignition Configs, or to use the Config Transpiler itself. + +![visual overview of the alternate ct workflows](../../img/ct-workflow.svg) + +As shown in this diagram, `ct` is manually invoked only when users are manually provisioning machines. If a provisioning tool like Matchbox is used, `ct` will transparently be incorporated into the deployment pipeline. In which case, the user only needs to prepare a Container Linux Config - Ignition and the Ignition Config are merely an implementation detail. + +## Config Transpiler + +The Container Linux Config Transpiler abstracts the details of configuring Flatcar Container Linux. It's responsible for transforming a Container Linux Config written by a user into an Ignition Config to be consumed by instances of Flatcar Container Linux. + +The Container Linux Config Transpiler command line interface, `ct` for short, can be downloaded from its [GitHub Releases page][download-ct] or used via Docker (`cat example.yaml | docker run --rm -i --platform=YOURPLATFORM ghcr.io/flatcar/ct:latest`). + +The following config will configure an etcd cluster using the machine's public and private IP addresses: + +```yaml +etcd: + advertise_client_urls: http://{PUBLIC_IPV4}:2379 + initial_advertise_peer_urls: http://{PRIVATE_IPV4}:2380 + listen_client_urls: http://0.0.0.0:2379 + listen_peer_urls: http://{PRIVATE_IPV4}:2380 + discovery: https://discovery.etcd.io/ +``` + +As suggested earlier, `ct` requires information about the target environment before it can transform configs which use templating. If this config is passed to `ct` without any other arguments, `ct` fails with the following error message: + +```shell +$ ct < example.yml +error: platform must be specified to use templating +``` + +This message states that because the config takes advantage of templating (in this case, `PUBLIC_IPV4`), `ct` must be invoked with the `--platform` argument. This extra information is used by `ct` to make the platform-specific customizations necessary. Keeping the Container Linux Config and the invocation arguments separate allows the Container Linux Config to remain largely platform independent. + +CT can be invoked again and given Amazon EC2 as an example: + +```shell +$ ct --platform=ec2 < example.yml +{"ignition":{"version":"2.0.0","config"... +``` + +This time, `ct` successfully runs and produces the following Ignition Config: + +```json +{ + "ignition": { "version": "2.0.0" }, + "systemd": { + "units": [{ + "name": "etcd-member.service", + "enable": true, + "dropins": [{ + "name": "20-clct-etcd-member.conf", + "contents": "[Unit]\nRequires=coreos-metadata.service\nAfter=coreos-metadata.service\n\n[Service]\nEnvironmentFile=/run/metadata/coreos\nExecStart=\nExecStart=/usr/lib/flatcar/etcd-wrapper $ETCD_OPTS \\\n --listen-peer-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2380\" \\\n --listen-client-urls=\"http://0.0.0.0:2379\" \\\n --initial-advertise-peer-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2380\" \\\n --advertise-client-urls=\"http://${COREOS_EC2_IPV4_PUBLIC}:2379\" \\\n --discovery=\"https://discovery.etcd.io/\u003ctoken\u003e\"" + }] + }] + } +} +``` + +This Ignition Config enables and configures etcd as specified in the above Container Linux Config. This can be more easily seen if the contents of the etcd drop-in are formatted nicely: + +```ini +[Unit] +Requires=coreos-metadata.service +After=coreos-metadata.service + +[Service] +EnvironmentFile=/run/metadata/coreos +ExecStart= +ExecStart=/usr/lib/flatcar/etcd-wrapper $ETCD_OPTS \ + --listen-peer-urls="http://${COREOS_EC2_IPV4_LOCAL}:2380" \ + --listen-client-urls="http://0.0.0.0:2379" \ + --initial-advertise-peer-urls="http://${COREOS_EC2_IPV4_LOCAL}:2380" \ + --advertise-client-urls="http://${COREOS_EC2_IPV4_PUBLIC}:2379" \ + --discovery="https://discovery.etcd.io/" +``` + +The details of these changes are covered in depth in Ignition's [metadata documentation][metadata], but the gist is that `coreos-metadata` is used to fetch the IP addresses from the Amazon APIs and then `systemd` is leveraged to substitute the IP addresses into the invocation of etcd. The result is that even though Ignition only runs once, `coreos-metadata` fetches the IP addresses whenever etcd is run, allowing etcd to use IP addresses that have the potential to change. + +## Migrating from cloud configs + +Previously, the recommended way to provision a Flatcar Container Linux machine was with a cloud-config. These configs would be given to a Flatcar Container Linux machine and a utility called [coreos-cloudinit][cloudinit] would read this file and apply the configuration on every boot. + +For a [number of reasons][vs], coreos-cloudinit has been deprecated in favor of Container Linux Configs and Ignition. For help migrating from these legacy cloud-configs to Container Linux Configs, refer to the [migration guide][migrating]. + +## Using Container Linux Configs + +Now that the basics of Container Linux Configs have been covered, a good next step is to read through the [examples][examples] and start experimenting. The [troubleshooting guide][troubleshooting] is a good reference for debugging issues. + +[clc]: ../config-transpiler/configuration +[cloudinit]: https://github.com/kinvolk/coreos-cloudinit +[ct]: ../config-transpiler/ +[download-ct]: https://github.com/flatcar/container-linux-config-transpiler/releases +[etcd]: https://github.com/etcd-io/etcd +[examples]: examples +[flannel]: https://github.com/coreos/flannel +[locksmith]: https://github.com/kinvolk/locksmith +[matchbox]: https://github.com/coreos/matchbox +[metadata]: ../ignition/metadata +[migrating]: from-cloud-config +[rkt]: https://github.com/rkt/rkt +[troubleshooting]: https://github.com/kinvolk/ignition/blob/master/doc/getting-started.md#troubleshooting +[vs]: ../ignition/#ignition-vs-coreos-cloudinit diff --git a/content/docs/latest/fb-provision/customize-image/_index.md b/content/docs/latest/fb-provision/customize-image/_index.md new file mode 100644 index 000000000..1273d2a71 --- /dev/null +++ b/content/docs/latest/fb-provision/customize-image/_index.md @@ -0,0 +1,9 @@ +--- +title: Image Customization +description: > + This section provides information and guidance on customizing + Flatcar images by placing files on the root or OEM filesystem or embedding an Ignition config. +weight: 35 +aliases: + - /docs/latest/installing/customizing-the-image/ +--- diff --git a/content/docs/latest/fb-provision/ignition/_index.md b/content/docs/latest/fb-provision/ignition/_index.md new file mode 100644 index 000000000..824f3ca2a --- /dev/null +++ b/content/docs/latest/fb-provision/ignition/_index.md @@ -0,0 +1,58 @@ +--- +content_type: ignition +title: Ignition +linktitle: Ignition +description: Provisioning utility specially designed for Container OSs +main_menu: true +weight: 10 +aliases: + - /docs/latest/provisioning/ignition/ + - ../ignition/what-is-ignition + - ../ignition +--- + +Ignition is a new provisioning utility designed specifically for container OSs like Flatcar Container Linux, which allows you to manipulate disks during early boot. This includes partitioning disks, formatting partitions, writing files (regular files, systemd units, networkd units, and more), and configuring users. On the first boot, Ignition reads its configuration from a source-of-truth (remote URL, network metadata service, or hypervisor bridge, for example) and applies the configuration. + +A [series of example configs][examples] are provided for reference. The specification can be found [here][ignition-specification]. + +## Ignition vs coreos-cloudinit + +Ignition solves many of the same problems as [coreos-cloudinit][cloudinit] but in a simpler, more predictable, and more flexible manner. This is achieved with two major changes: Ignition only runs once and it does not handle variable substitution. Ignition has also fixed a number of pain points with regard to configuration. + +Instead of YAML, Ignition uses JSON for its configuration format. JSON's typing immediately eliminates problems like "off" being rewritten as "false", the "#cloud-config" header being stripped because comments *shouldn't* have meaning, and confusion around whether those file permissions were written in octal or decimal. Ignition's configuration is also versioned, which allows future development without persistent backward compatibility. + +### Ignition only runs once + +Even though Ignition only runs once, during the first boot of the system, it packs a powerful punch. Because Ignition runs so early in the boot process (in the initramfs, to be exact), it is able to repartition disks, format filesystems, create users, and write files, all before the userspace begins to boot. + +Because Ignition runs so early in the boot process, the network config is available for networkd to read when it first starts, and systemd services are already written to disk when systemd starts. [Configuring the network][network-config] is no longer an issue. This results in a simple startup, a faster startup, and the ability to accurately inspect the unit dependency graphs. + +### No variable substitution + +Because Ignition only runs once, there's no reason for it to incorporate dynamic data (like floating IP addresses, or compute regions). + +Instead, use Ignition to write static files and leverage systemd's environment variable expansion to insert dynamic data. The Ignition config should install a service which fetches the necessary runtime data, then any services which need this data (such as etcd or fleet) can rely on the installed service and source in their output. The result is that the data is only collected if and when it is needed. For supported platforms, Flatcar Container Linux provides a small utility (`coreos-metadata.service`) to help fetch this data. + +### When is Ignition executed + +On boot, GRUB checks the EFI System Partition for a file at `flatcar/first_boot` (or `coreos/first_boot` if the machine was updated from CoreOS CL) and sets `flatcar.first_boot=detected` if found. The `flatcar.first_boot` parameter is processed by a [systemd-generator] in the [initramfs] and if the parameter value is non-zero, the Ignition units are set as dependencies of `initrd.target`, causing Ignition to run. If the parameter is set to the special value `detected`, the `flatcar/first_boot` (or `coreos/first_boot`) file is deleted after Ignition runs successfully. You can schedule a re-run of Ignition with the `flatcar-reset` tool (available since Alpha 3535.0.0), which also takes care of cleaning up old rootfs state and keeping only the data from the rootfs you want to keep. + +Note that [PXE][supported-platforms] deployments don't use GRUB to boot, so `flatcar.first_boot=1` must be added to the boot arguments in order for Ignition to run. `detected` should not be specified so Ignition will not attempt to delete `flatcar/first_boot` (or `coreos/first_boot`). + +## Providing Ignition a config + +Ignition can read its config from a number of different locations, but only from one at a time. When running Flatcar Container Linux on the supported cloud providers, Ignition will read its config from the instance's userdata. This means that if Ignition is being used, it will not be possible to use other tools which also use this userdata (such as coreos-cloudinit). Bare metal installations and PXE boots can use the kernel boot parameters to point Ignition at the config. + +## Where is Ignition supported? + +In addition to providers supported by [upstream Ignition][ignition-supported], Flatcar [supports](https://github.com/flatcar/scripts/blob/main/sdk_container/src/third_party/coreos-overlay/sys-apps/ignition/files/0018-revert-internal-oem-drop-noop-OEMs.patch) cloudsigma, hyperv, interoute, niftycloud, rackspace[-onmetal], and vagrant. + +Ignition is under active development. Expect to see support for more images in the coming months. + +[examples]: https://github.com/coreos/ignition/blob/main/docs/examples.md +[ignition-specification]: specification +[cloudinit]: https://github.com/flatcar/coreos-cloudinit +[network-config]: network-configuration +[supported-platforms]: https://github.com/coreos/ignition/blob/main/docs/supported-platforms.md +[systemd-generator]: http://www.freedesktop.org/software/systemd/man/systemd.generator.html +[initramfs]: https://www.kernel.org/doc/Documentation/filesystems/ramfs-rootfs-initramfs.txt diff --git a/content/docs/latest/fb-provision/infrastructure/_index.md b/content/docs/latest/fb-provision/infrastructure/_index.md new file mode 100644 index 000000000..f53d67be3 --- /dev/null +++ b/content/docs/latest/fb-provision/infrastructure/_index.md @@ -0,0 +1,143 @@ +--- +title: Infrastructure as Code +description: Provision Flatcar Container Linux with an Ignition configuration through Terraform +weight: 40 +aliases: + - /docs/latest/provisioning/terraform/ +--- + +Flatcar Container Linux fits well with Terraform for the principle of Immutable Infrastructure where you deploy a node and, instead of making changes via SSH, you destroy it and deploy a new node. +The big advantages compared to other OSes are the inbuilt support for declarative configuration with Ignition on first boot and the automatic OS updates. + +Many cloud services allow to provide _User Data_ for a node in an extra attribute. Ignition will fetch the configuration from this place and apply it. No Terraform SSH provisioning commands are needed. + +## Terraform Providers for the different Cloud Services + +How to use the Terraform Providers of each cloud service is explained on the respective documentation page under [Cloud Providers][cloud]. + +## Changing the Ignition Configuration + +Changes to the User Data attribute should normally destroy the node and recreate it so that Ignition runs again on the first boot. +However, this behavior depends on the Terraform provider for your cloud service. +Some cloud services allow to update the attribute in-place without destroying the node but Ignition won't run again by default and even if you triggered it, you would have to be careful as this is not recommended (more on this at the end of this document). +You can also tell Terraform not ignore attribute changes (set `ignore_changes`) and thus delay the change until you manually destroy the node and recreate it with Terraform. +This is sometimes useful but may be a source of errors when you don't know that a node still runs an old configuration. + +To make the recreation of a node less disruptive, you can architect your setup to accept a node to exist twice at the same time and set `create_before_destroy` to let Terraform first create the replacement node and then destroy the old node. +On AWS, it's also possible to use Auto Scaling Groups instead of directly operating on instances. In this case, to update the User Data you can replace the Auto Scaling Group, and the new one will take care of creating new nodes and the old one deletes the old ones. +An advanced scheme of this on AWS can use Auto Scaling Groups instead of directly operating on instances, and to change the User Data you replace the Auto Scaling Group and the new one takes care of creating new nodes and the old one deletes the old ones. +It is also advisable to separate the persistent data from the disposable nodes to external data volumes or to use a backup mechanism and inject the backup on the first boot. + +## Generating the Ignition Configuration within Terraform + +To convert the Butane Config in YAML to the final Igniton Config in JSON you don't need to run [`butane`][butane-configs] manually. Instead, you can directly do this within Terraform, through the [`terraform-ct-provider`][terraform-ct-provider] (starting from v0.12.0). +Combined with the `template-provider` you can reference Terraform variables in the YAML template. + +An alternative is the [`terraform-ignition-provider`][terraform-ignition-provider] that allows to assemble the Ignition Config from Terraform declarations. + +The following snippet demonstrates the use of the `terraform-ct-provider` and the `template-provider` to specify the User Data attribute on a Packet (now Equinix Metal) instance: + +``` +resource "packet_device" "machine" { + operating_system = "flatcar_stable" + user_data = data.ct_config.machine-ignition.rendered + [...] +} + +data "ct_config" "machine-ignition" { + content = data.template_file.machine-cl-config.rendered +} + +data "template_file" "machine-cl-config" { + template = file("${path.module}/machine.yaml.tmpl") + vars = { something = var.something } +} +``` + +When using a template be careful to refer to the Terraform variables via `${variable}` while shell variables in scripts used at OS runtime need to be quoted like `$${variable}` or need to use the `$variable` syntax. + +## Updating the User Data in-place and rerunning Ignition instead of destroying nodes + +Sometimes you want to take the declarative approach of Terraform but can't accept that nodes are destroyed and recreated for configuration changes. +This is the case for nodes that have a manual or slow bring-up process, much data that can't be moved easily, or where the IP address should not change. + +Ignition can be told to run again through `flatcar-reset` (available since Alpha 3535.0.0), which also takes care of cleaning up old rootfs state and keeping only the rootfs data you want to keep. + +A Terraform setup that runs `flatcar-reset` when the cloud instance userdata changes can be found in the [flatcar-terraform repository][example-repo]. +The list of paths in the rootfs to keep can be configured. + +### Reformatting + +Another alternative to `flatcar-reset` is to reformat the root filesystem with Ignition to ensure that no old state is present, or use cloud-provider [reinstall options like on Equinix Metal](https://registry.terraform.io/providers/equinix/equinix/latest/docs/resources/equinix_metal_device#reinstall). +Persistent data should be stored on another partition which should be set to be kept. + +We can also preserve the machine ID by setting it as kernel cmdline parameter (it must not be kept as file on the root filesystem because that prevents the systemd first-boot semantics to enable units through the preset Ignition creates). + +This Container Linux Config snippet takes care of reformating the root filesystem and places a reprovisioning helper script on the OEM partition: + +```yaml +storage: + files: + - path: /reprovision + filesystem: oem + mode: 0755 + contents: + inline: | + #!/bin/bash + set -euo pipefail + touch /usr/share/oem/grub.cfg + sed -i "/linux_append systemd.machine_id=.*/d" /usr/share/oem/grub.cfg + echo "set linux_append=\"\$linux_append systemd.machine_id=$(cat /etc/machine-id)\"" >> /usr/share/oem/grub.cfg + touch /boot/flatcar/first_boot + filesystems: + - name: root + mount: + device: /dev/disk/by-label/ROOT + format: ext4 + wipe_filesystem: true + label: ROOT + - name: oem + mount: + device: /dev/disk/by-label/OEM + format: btrfs + label: OEM +``` + +The final User Data needs to be stored on a place where modifications are allowed without destroying the node. +For some Terraform providers it is directly possible to allow changes but that is not always the case. +A good option then could be AWS S3 or other similar cloud storage solutions. +The real User Data of the node is just an Ignition Config that references the external User Data: + +``` +{ "ignition": { "version": "2.1.0", "config": { "replace": { "source": "s3://..." } } } } +``` + +Under these conditions it is possible to run `sudo /usr/share/oem/reprovision` on the node and trigger reboot for the new Ignition Config to take effect (assuming data in S3): + +``` +resource "null_resource" "reboot-when-ignition-changes" { + for_each = toset(var.machines) + # Triggered when the Ignition Config changes + triggers = { + ignition_config = data.ct_config.machine-ignitions[each.key].rendered + } + # Wait for the new Ignition config object to be ready before rebooting + depends_on = [aws_s3_bucket_object.object] + # Trigger running Ignition on the next reboot and reboot the instance (current limitation: also runs on the first provisioning) + provisioner "local-exec" { + command = "while ! ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null core@${packet_device.machine[each.key].access_public_ipv4} sudo /usr/share/oem/reprovision ; do sleep 1; done; while ! ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null core@${packet_device.machine[each.key].access_public_ipv4} sudo systemctl reboot; do sleep 1; done" + } +} +``` + +## Examples + +You can find the full code for working examples in this [git repository][example-repo]. + + +[cloud]: ../../installing/cloud/ +[butane-configs]: ../config-transpiler +[terraform-ct-provider]: https://registry.terraform.io/providers/poseidon/ct/latest +[terraform-ignition-provider]: https://registry.terraform.io/providers/community-terraform-providers/ignition/latest +[boot-process]: ../ignition/boot-process/#reprovisioning +[example-repo]: https://github.com/flatcar/flatcar-terraform diff --git a/content/docs/latest/fb-provision/vms/_index.md b/content/docs/latest/fb-provision/vms/_index.md new file mode 100644 index 000000000..cfd8c17ea --- /dev/null +++ b/content/docs/latest/fb-provision/vms/_index.md @@ -0,0 +1,190 @@ +--- +title: Virtual Machines +linktitle: Running on Vagrant +weight: 40 +aliases: + - /docs/latest/installing/vms/vagrant/ + - ../../os/booting-on-vagrant + - ../../cloud-providers/booting-on-vagrant +--- + +_While we always welcome community contributions and fixes, please note that Vagrant is not an officially supported platform at this time. (See the [platform overview](/#installing-flatcar).)_ + +Running Flatcar Container Linux with Vagrant is one way to bring up a single machine or virtualize an entire cluster on your laptop. Since the true power of Flatcar Container Linux can be seen with a cluster, we're going to concentrate on that. Instructions for a single machine can be found [towards the end](#single-machine) of the guide. + +You can direct questions to the [Discord server][discord] or [mailing list][flatcar-dev]. + +## Install Vagrant and VirtualBox + +Vagrant is a simple-to-use command line virtual machine manager. There are install packages available for Windows, Linux and OS X. Find the latest installer on the [Vagrant downloads page][vagrant]. Be sure to get version 2.0.4 or greater, to be able to detect Flatcar images correctly. + +[vagrant]: http://www.vagrantup.com/downloads.html + +Vagrant can use either the free VirtualBox provider or the commercial VMware provider. Instructions for both are below. For the VirtualBox provider, version 4.3.10 or greater is required. + +## Install Flatcar Container Linux + +You can import the flatcar box and boot it with Vagrant. +You'll find it in `https://${CHANNEL}.release.flatcar-linux.net/amd64-usr/${VERSION}/flatcar_production_vagrant.box`. +Make sure you download the signature (it's available in `https://${CHANNEL}.release.flatcar-linux.net/amd64-usr/${VERSION}/flatcar_production_vagrant.box.sig`) and check it before proceeding. + +For example, to get the latest alpha: + +```shell +$ wget https://alpha.release.flatcar-linux.net/amd64-usr/current/flatcar_production_vagrant.box +$ wget https://alpha.release.flatcar-linux.net/amd64-usr/current/flatcar_production_vagrant.box.sig +$ gpg --verify flatcar_production_vagrant.box.sig +gpg: assuming signed data in 'flatcar_production_vagrant.box' +gpg: Signature made Thu 15 Mar 2018 10:29:23 AM CET +gpg: using RSA key A621F1DA96C93C639506832D603443A1D0FC498C +gpg: Good signature from "Flatcar Buildbot (Official Builds) " [ultimate] +$ vagrant box add flatcar-alpha flatcar_production_vagrant.box +==> box: Box file was not detected as metadata. Adding it directly... +==> box: Adding box 'flatcar-alpha' (v0) for provider: + box: Unpacking necessary files from: file:///tmp/flatcar_production_vagrant.box +==> box: Successfully added box 'flatcar-alpha' (v0) for 'virtualbox'! +$ vagrant init flatcar-alpha +A `Vagrantfile` has been placed in this directory. You are now +ready to `vagrant up` your first virtual environment! Please read +the comments in the Vagrantfile as well as documentation on +`vagrantup.com` for more information on using Vagrant. +$ vagrant up +Bringing machine 'default' up with 'virtualbox' provider... +==> default: Importing base box 'flatcar-alpha'... +==> default: Matching MAC address for NAT networking... +==> default: Setting the name of the VM: vagrant_default_1520510346048_14823 +==> default: Clearing any previously set network interfaces... +==> default: Preparing network interfaces based on configuration... + default: Adapter 1: nat +==> default: Forwarding ports... + default: 22 (guest) => 2222 (host) (adapter 1) +==> default: Running 'pre-boot' VM customizations... +==> default: Booting VM... +==> default: Waiting for machine to boot. This may take a few minutes... + default: SSH address: 127.0.0.1:2222 + default: SSH username: core + default: SSH auth method: private key +==> default: Machine booted and ready! +$ vagrant ssh +Last login: Thu Mar 15 17:02:25 UTC 2018 from 10.0.2.2 on ssh +Flatcar Container Linux by Kinvolk alpha (1702.1.0) +core@localhost ~ $ +``` + +## Starting a cluster + +You can configure your Vagrant machine by having a `Vagrantfile` example file: + +```ruby +ENV["TERM"] = "xterm-256color" +ENV["LC_ALL"] = "en_US.UTF-8" + +Vagrant.require_version '>= 2.0.4' + +Vagrant.configure('2') do |config| + config.ssh.username = 'core' + config.ssh.insert_key = true + config.vm.box = 'flatcar-alpha' + config.vm.synced_folder '.', '/vagrant', disabled: true + config.vm.provider :virtualbox do |v| + v.check_guest_additions = false + v.functional_vboxsf = false + v.cpus = 2 + v.memory = 2048 + end + config.vm.define 'core-01' do |c| + end + config.vm.define 'core-02' do |c| + end + config.vm.define 'core-03' do |c| + end +end +``` + +### Start machines using Vagrant's default VirtualBox provider + +Start the machine(s): + +```shell +vagrant up +``` + +List the status of the running machines: + +```shell +$ vagrant status +Current machine states: + +core-01 running (virtualbox) +core-02 running (virtualbox) +core-03 running (virtualbox) + +This environment represents multiple VMs. The VMs are all listed +above with their current state. For more information about a specific +VM, run `vagrant status NAME`. +``` + +Connect to one of the machines: + +```shell +vagrant ssh core-01 -- -A +``` + +### Start machines using Vagrant's VMware provider + +If you have purchased the [VMware Vagrant provider](http://www.vagrantup.com/vmware), run the following commands: + +```shell +vagrant up --provider vmware_fusion +vagrant ssh core-01 -- -A +``` + +## Single machine + +To start a single machine, we need to provide some config parameters in cloud-config format via the `user-data` file. + +Start the machine: + +```shell +vagrant up +``` + +Connect to the machine: + +```shell +vagrant ssh core-01 -- -A +``` + +## Shared folder setup + +Optionally, you can share a folder from your laptop into the virtual machine. This is useful for easily getting code and Dockerfiles into Flatcar Container Linux. + +```ini +config.vm.synced_folder ".", "/home/core/share", id: "core", :nfs => true, :mount_options => ['nolock,vers=3,udp'] +``` + +After a 'vagrant reload' you will be prompted for your local machine password. + +## New box versions + +Flatcar Container Linux is a rolling release distribution and versions that are out of date will automatically update. If you want to start from the most up to date version you will need to make sure that you have the latest box file of Flatcar Container Linux. You can do this using `vagrant box update` - or, simply remove the old box file and Vagrant will download the latest one the next time you `vagrant up`. + +```shell +vagrant box remove flatcar-alpha vmware_fusion +vagrant box remove flatcar-alpha virtualbox +``` + +If you'd like to download the box separately, you can download the URL contained in the Vagrantfile and add it manually: + +```shell +vagrant box add flatcar-alpha +``` + +## Using Flatcar Container Linux + +Now that you have a machine booted it is time to play around. Check out the [Flatcar Container Linux Quickstart][quickstart] guide, learn about [CoreOS Container Linux clustering with Vagrant](https://coreos.com/blog/coreos-clustering-with-vagrant/), or dig into [more specific topics][doc-index]. + +[flatcar-dev]: https://groups.google.com/forum/#!forum/flatcar-linux-dev +[discord]: https://discord.gg/PMYjFUsJyq +[quickstart]: ../ +[doc-index]: ../../ diff --git a/content/docs/latest/getting-started/_index.md b/content/docs/latest/getting-started/_index.md new file mode 100644 index 000000000..5a8a0a5e6 --- /dev/null +++ b/content/docs/latest/getting-started/_index.md @@ -0,0 +1,233 @@ +--- +title: Getting Started with Flatcar Container Linux +linktitle: Getting Started +weight: 10 +aliases: + - /docs/latest/installing/ + - os/quickstart + - quickstart +--- + +This guide aims to get you up and running in a few minutes. +We'll cover + +- concepts, configuration, and provisioning +- writing a basic Flatcar configuration and testing it locally with qemu +- further reading - where to go from here after learning the basics + +### Concepts, Configuration, and Provisioning + +Flatcar Container Linux is configured at _provisioning time_. +There are two configuration languages to set up Flatcar, aimed at different use cases: + +- [Butane Config][butane-configs] Butane is human-readable / writable YAML and must be converted (transpiled) into Ignition V3 config before Flatcar can use it. It's the successor of [Container Linux Config][cl-configs] which is also still supported (Butane is not supported for LTS-2022). +- [Ignition config][ignition] is machine-readable JSON fed to Flatcar's ignition service. + Ignition is Flatcars "installation service" which configures a Flatcar instance during provisioning. + The config file is passed via the "custom data" or "user data" option of cloud providers, and can be supplied by various mechanisms to private cloud VMs and bare metal. + Ignition config is rarely written by a human; it's usually generated by provisioning automation or transpiled from user-written Butane. + +Use Butane to customise your Flatcar deployment, e.g. to + +- add custom users and groups +- create and manage storage devices, file systems, and swap, and create custom files +- customise automatic updates and define reboot windows +- create custom network(d) configurations and systemd units + - Want to e.g. run a custom operation or start a service each time the instance boots? + Define a custom [systemd unit][systemd] via Butane. + All above tasks only take a few lines of YAML and are covered in our [Butane examples][butane-examples]. + For a comprehensive discussion of all options available in Butane have a look at the [Butane specification][butane-spec]. + +To convert Butane into machine-readable Ignition config, just download the latest release of [Butane][butane]. Alternatively, you can use the up-to-date [container image][container-image] with `docker run --rm -i quay.io/coreos/butane:latest`. + +Then, after converting Butane to Ignition config, pass the Ignition config along when provisioning your instance(s). +The config is then passed via "user data" / "custom data" or similar means to the provisioning logic. + +#### Writing your first config and testing it locally in a qemu VM + +The way from a small [Butane Config YAML][butane-configs] or [Ignition JSON][ignition] file to a local [QEMU VM][qemu-docs] on your laptop is not far. +Here we will create a systemd service that starts an NGINX container as example configuration for the VM. +This is a good starting point for you to modify the Butane YAML file (or the Ignition JSON file) and test it by provisioning a temporary QEMU VM. +This should work on most Linux systems and assumes you have an SSH key set up for ssh-agent. + +First download the Flatcar QEMU image and the helper script to start it with QEMU but don't run it yet. + +AMD64: + +```shell +wget https://stable.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu.sh +chmod +x flatcar_production_qemu.sh +wget https://stable.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu_image.img +``` + +ARM64: + +```shell +wget https://alpha.release.flatcar-linux.net/arm64-usr/current/flatcar_production_qemu_uefi.sh +chmod +x flatcar_production_qemu_uefi.sh +wget https://alpha.release.flatcar-linux.net/arm64-usr/current/flatcar_production_qemu_uefi_image.img +wget https://alpha.release.flatcar-linux.net/arm64-usr/current/flatcar_production_qemu_uefi_efi_vars.qcow2 +wget https://alpha.release.flatcar-linux.net/arm64-usr/current/flatcar_production_qemu_uefi_efi_code.qcow2 +``` + +For Ignition configurations to be recognized we have to make sure that we always boot an unmodified fresh image because Ignition only runs on first boot. +Therefore, before trying to use an Ignition config we will always discard the image modifications by using a fresh copy. +You can already boot the image with `./flatcar_production_qemu.sh` and have a look around in the OS through the QEMU VGA console - you can close the QEMU window or stop the script with `Ctrl-C`. + +```shell +mv flatcar_production_qemu_image.img flatcar_production_qemu_image.img.fresh +# If you want to have a first look, boot it and wait for the autologin to give you a prompt: +cp -i --reflink=auto flatcar_production_qemu_image.img.fresh flatcar_production_qemu_image.img +``` + +Now we will provision the VM on first boot through Ignition. +Instead of writing the JSON config we use Butane YAML and transpile it. +Save the following Butane YAML file as `cl.yaml` (or another name). +It contains directives for setting up a systemd service that runs an NGINX Docker container: + +```yaml +variant: flatcar +version: 1.0.0 +systemd: + units: + - name: nginx.service + enabled: true + contents: | + [Unit] + Description=NGINX example + After=docker.service + Requires=docker.service + [Service] + TimeoutStartSec=0 + ExecStartPre=-/usr/bin/docker rm --force nginx1 + ExecStart=/usr/bin/docker run --name nginx1 --pull always --log-driver=journald --net host docker.io/nginx:1 + ExecStop=/usr/bin/docker stop nginx1 + Restart=always + RestartSec=5s + [Install] + WantedBy=multi-user.target +``` + +Before we can use it we have to transpile the Butane YAML to Ignition JSON: + +```shell +cat cl.yaml | docker run --rm -i quay.io/coreos/butane:latest > ignition.json +``` + +You can also skip this step and copy the resulting JSON file from here to `ignition.json` (or another name): + +``` +{ + "ignition": { + "version": "3.3.0" + }, + "systemd": { + "units": [ + { + "contents": "[Unit]\nDescription=NGINX example\nAfter=docker.service\nRequires=docker.service\n[Service]\nTimeoutStartSec=0\nExecStartPre=-/usr/bin/docker rm --force nginx1\nExecStart=/usr/bin/docker run --name nginx1 --pull always --net host docker.io/nginx:1\nExecStop=/usr/bin/docker stop nginx1\nRestart=always\nRestartSec=5s\n[Install]\nWantedBy=multi-user.target\n", + "enabled": true, + "name": "nginx.service" + } + ] + } +} +``` + +The final step is to boot the VM and make the Ignition configuration available to it. +As said, the provisioning will only be done on first boot and if you want your (changed) Ignition configuration to be used, you have to boot from a fresh copy. +You can repeat these combined steps as often as you want to test your Ignition changes. + +```shell +# Make sure we boot a fresh copy: +cp -i --reflink=auto flatcar_production_qemu_image.img.fresh flatcar_production_qemu_image.img +./flatcar_production_qemu.sh -i ignition.json +# Log in via SSH in a new terminal tab: +ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -p 2222 core@127.0.0.1 +# Check that NGINX is running: +systemctl status nginx +curl http://localhost/ +``` + +_NOTE_: For SSH access, you can also use the `~/.ssh/config` provided in the [QEMU][qemu-ssh] section then simply `ssh flatcar` or `scp my-file flatcar:/home/core` to send a file on the instance over SSH. + +If you have trouble SSHing into the VM, `./flatcar_production_qemu.sh` might have failed to auto-detect your ssh key. +If that happens try with a user-supplied SSH key using the yaml snippet below. +Alternatively, you can interact with the VM via the VGA console - the console has auto-login enabled and drops right into a shell. + +You can reboot and stop the VM if you like - when you start it later with a plain `./flatcar_production_qemu.sh` then our systemd unit will take care of starting NGINX on each boot. +Note that the ignition config will only be processed on the very first boot - that's why we made a copy, so now we can restore our OS image from the pristine copy for successive experiments with Butane. + +As listed in the introduction above there are numerous options available for configuring Flatcar just the way you need it. +For instance, you can specify a custom SSH key instead of your default one from your ssh-agent or from `~/.ssh/` in the Butane config, by adding this section to your YAML file: + +```yaml +variant: flatcar +version: 1.0.0 +passwd: + users: + - name: core + ssh_authorized_keys: + - ssh-rsa AAAAB......xyz email@host.net +``` + +Afterwards, transpile it again to Ignition JSON, overwrite `flatcar_production_qemu_image.img` with the fresh image file, and pass the ignition config to `./flatcar_production_qemu.sh` once again. + +### On automatic updates + +Flatcar has automatic updates enabled by default. +Flatcar instances will download and stage (in the background) new OS versions as well as reboot into the updated OS when a new update becomes available. +To change this default - for instance, to define reboot windows or even disable reboots - check out the [update strategies][update-strategies] doc. +To disable downloading updates altogether either disable the `update-engine` service via a user-supplied systemd config, or use an invalid URL in the `SERVER` field of [`update.conf`][update-conf]. + +### More on configuring and operating Flatcar Container Linux + +Our [Flatcar learning series][learning-series] has in-depth coverage of specific areas of using Flatcar. + +The documentation includes a whole section on configuration, operation, and maintenance. +Have a look at the [setup guide][setup] for more information. + +### Further reading: Platform / vendor specific information + +Check out the guides on [running Flatcar Container Linux][running-container-linux] on most cloud providers: + +- [EC2][ec2-docs] +- [Azure][azure-docs] +- [GCE][gce-docs] + virtualization platforms / private clouds: +- [Vagrant][vagrant-docs] +- [VMware][vmware-docs] +- [VirtualBox][virtualbox-docs] +- [QEMU/KVM][qemu-docs]/[libVirt][libvirt-docs] + and bare metal servers: +- [PXE][pxe-docs] +- [iPXE][ipxe-docs] +- [ISO][iso-docs] +- [Installer][install-docs] + +With any of these guides you will have machines up and running in a few minutes. + +[learning-series]: ../learning-series +[update-strategies]: ../setup/releases/update-strategies +[update-conf]: ../setup/releases/update-conf +[setup]: ../setup +[running-container-linux]: ../#installing-flatcar +[ec2-docs]: cloud/aws-ec2 +[azure-docs]: cloud/azure +[gce-docs]: cloud/gcp +[vagrant-docs]: vms/vagrant +[vmware-docs]: community-platforms/vmware +[virtualbox-docs]: vms/virtualbox +[qemu-docs]: vms/qemu +[qemu-ssh]: vms/qemu#ssh-config +[libvirt-docs]: vms/libvirt +[pxe-docs]: bare-metal/booting-with-pxe +[ipxe-docs]: bare-metal/booting-with-ipxe +[iso-docs]: bare-metal/booting-with-iso +[install-docs]: bare-metal/installing-to-disk +[ignition]: ../provisioning/ignition/ +[cl-configs]: ../provisioning/cl-config +[butane-configs]: ../provisioning/config-transpiler +[butane-examples]: ../provisioning/config-transpiler/examples +[butane-spec]: ../provisioning/config-transpiler/configuration +[systemd]: ../setup/systemd/getting-started +[container-image]: https://quay.io/repository/coreos/butane +[butane]: https://github.com/coreos/butane/releases diff --git a/content/docs/latest/getting-started/learning-series/_index.md b/content/docs/latest/getting-started/learning-series/_index.md new file mode 100644 index 000000000..b0bdb61fd --- /dev/null +++ b/content/docs/latest/getting-started/learning-series/_index.md @@ -0,0 +1,23 @@ +--- +title: Flatcar Self-Paced Learning Series +linktitle: Learning Series +weight: 5 +author: Lexi Nadolski, Thilo Fromm +aliases: + - /docs/latest/learning-series/ +--- + +Here you'll find a set of in-depth self-paced sessions to deep dive into Flatcar! + +The sessions aim to be fun and useful. +If you feel there's room for improvement, please do provide feedback (and / or consider filing a PR!). +We also continuously improve sessions and extend the series; check back regularly. + +* [Basic Operation and Local Testing](basics-and-testing) starts from scratch and will set you up with a local test environment to play around with Flatcar. + No prerequisite knowledge required. +* [Advanced Provisioning Configuration](advanced-service-config) continues where the first session ended. + We dive into more complex deployments and ways to better manage your node configurations. +* [Managing and Encrypting Storage](managing-storage) discusses adding additional storage for applications and how to keep your data secure at rest, through encryption. +* [Immutable OS, Boot Process, In‐Place Updates, Automating Rollback, and Release Channels](immutability-updates-rollbacks) will dive *deep* into immutability specifics of Flatcar + and how this can help you to make your OS operations safe and secure. + In this low-level session we will cover OS partition immutability, boot specifics, in-place upgrades, and how users can automate rollbacks. diff --git a/content/docs/latest/orchestrate/_index.md b/content/docs/latest/orchestrate/_index.md new file mode 100644 index 000000000..7c692d41a --- /dev/null +++ b/content/docs/latest/orchestrate/_index.md @@ -0,0 +1,6 @@ +--- +title: Orchestration & Container Runtimes +weight: 60 +description: > + Manage clusters, Kubernetes, and container runtimes on Flatcar Container Linux. +--- diff --git a/content/docs/latest/orchestrate/clusters/_index.md b/content/docs/latest/orchestrate/clusters/_index.md new file mode 100644 index 000000000..890568348 --- /dev/null +++ b/content/docs/latest/orchestrate/clusters/_index.md @@ -0,0 +1,11 @@ +--- +title: Managing Clusters +description: > + One of the most common uses of Flatcar Container Linux is to create + clusters of machines. These guides will help you understand the different + cluster architectures that you can choose from, setup cluster discovery and + more. +weight: 40 +aliases: + - /docs/latest/setup/clusters/ +--- diff --git a/content/docs/latest/orchestrate/containers/_index.md b/content/docs/latest/orchestrate/containers/_index.md new file mode 100644 index 000000000..bc55d6621 --- /dev/null +++ b/content/docs/latest/orchestrate/containers/_index.md @@ -0,0 +1,12 @@ +--- +title: Container Runtimes +description: > + Flatcar Container Linux supports all of the popular methods for running + containers, and you can choose to interact with the containers at a + low-level, or use a higher level orchestration framework. These guides + can help you choose and use the different container runtimes supported. +weight: 60 +aliases: + - /docs/latest/container-runtimes/ +--- + diff --git a/content/docs/latest/orchestrate/kubernetes/_index.md b/content/docs/latest/orchestrate/kubernetes/_index.md new file mode 100644 index 000000000..540e78ff3 --- /dev/null +++ b/content/docs/latest/orchestrate/kubernetes/_index.md @@ -0,0 +1,6 @@ +--- +title: Kubernetes +weight: 20 +description: > + Running Kubernetes on Flatcar Container Linux. +--- diff --git a/content/docs/latest/os-config/_index.md b/content/docs/latest/os-config/_index.md new file mode 100644 index 000000000..c70f5ff0b --- /dev/null +++ b/content/docs/latest/os-config/_index.md @@ -0,0 +1,11 @@ +--- +title: OS Configuration +description: > + Follow these guides to connect your machines together as a cluster. + Configure machine parameters, create users, inject multiple SSH keys, and + more with Butane configs. +weight: 30 +aliases: + - /docs/latest/setup/ + - /docs/latest/setup/customization/ +--- diff --git a/content/docs/latest/os-config/host-config/_index.md b/content/docs/latest/os-config/host-config/_index.md new file mode 100644 index 000000000..b768483d5 --- /dev/null +++ b/content/docs/latest/os-config/host-config/_index.md @@ -0,0 +1,6 @@ +--- +title: Host Configuration +weight: 20 +description: > + Configure users, environment variables, kernel modules, and other host settings. +--- diff --git a/content/docs/latest/os-config/network/_index.md b/content/docs/latest/os-config/network/_index.md new file mode 100644 index 000000000..cf6090a66 --- /dev/null +++ b/content/docs/latest/os-config/network/_index.md @@ -0,0 +1,6 @@ +--- +title: Networking & Remote Access +weight: 30 +description: > + Network configuration, DNS, and remote access on Flatcar Container Linux. +--- diff --git a/content/docs/latest/os-config/storage/_index.md b/content/docs/latest/os-config/storage/_index.md new file mode 100644 index 000000000..d3fab592e --- /dev/null +++ b/content/docs/latest/os-config/storage/_index.md @@ -0,0 +1,9 @@ +--- +title: Managing Storage on Flatcar Container Linux +linktitle: Storage Setup +description: Adding, Extending and Configuring Storage on Flatcar. +weight: 25 +aliases: + - /docs/latest/setup/storage/ + - ../clusters/scaling/ +--- diff --git a/content/docs/latest/os-config/systemd/_index.md b/content/docs/latest/os-config/systemd/_index.md new file mode 100644 index 000000000..acdf478b7 --- /dev/null +++ b/content/docs/latest/os-config/systemd/_index.md @@ -0,0 +1,12 @@ +--- +title: Using Systemd on Flatcar Container Linux +linktitle: Using Systemd +description: > + Flatcar makes heavy use of systemd services and customization techniques. + Understanding core concepts like drop-in units, timers and embedding + environment variables, make it easier to apply the right changes to an + instance being deployed. These guides can help you get up to speed. +weight: 5 +aliases: + - /docs/latest/setup/systemd/ +--- diff --git a/content/docs/latest/security/_index.md b/content/docs/latest/security/_index.md new file mode 100644 index 000000000..1cb6664dd --- /dev/null +++ b/content/docs/latest/security/_index.md @@ -0,0 +1,6 @@ +--- +title: Security +weight: 90 +description: > + Security hardening, encryption, and authentication for Flatcar Container Linux. +--- diff --git a/content/docs/latest/security/cert-auth/_index.md b/content/docs/latest/security/cert-auth/_index.md new file mode 100644 index 000000000..0336c9fd8 --- /dev/null +++ b/content/docs/latest/security/cert-auth/_index.md @@ -0,0 +1,12 @@ +--- +title: Certificates & Authentication +linktitle: Security Options +description: > + Flatcar Container Linux has a number of security measures enabled by + default, but there's always more things that can be enabled if desired. + These guides provide information on what additional options can be set. +weight: 45 +aliases: + - /docs/latest/setup/security/ + - ../clusters/securing +--- diff --git a/content/docs/latest/security/encryption/_index.md b/content/docs/latest/security/encryption/_index.md new file mode 100644 index 000000000..facf29be5 --- /dev/null +++ b/content/docs/latest/security/encryption/_index.md @@ -0,0 +1,6 @@ +--- +title: Encryption & Storage Security +weight: 20 +description: > + Disk encryption and security-enhanced Linux configuration. +--- diff --git a/content/docs/latest/security/hardening/_index.md b/content/docs/latest/security/hardening/_index.md new file mode 100644 index 000000000..c0f5ad882 --- /dev/null +++ b/content/docs/latest/security/hardening/_index.md @@ -0,0 +1,6 @@ +--- +title: Hardening & Compliance +weight: 10 +description: > + Security hardening guides and compliance information. +--- diff --git a/content/docs/latest/sys-ext/_index.md b/content/docs/latest/sys-ext/_index.md new file mode 100644 index 000000000..e5da970a8 --- /dev/null +++ b/content/docs/latest/sys-ext/_index.md @@ -0,0 +1,205 @@ +--- +title: System Extensions +description: Extending the base OS with systemd-sysext images +weight: 40 +aliases: + - /docs/latest/provisioning/sysext/ +--- + +Flatcar Container Linux bundles various software components with fixed versions together into one release. +For users that require a particular version of a software component this means that the software needs to be supplied out of band and overwrite the built-in software copy. +Another approach we recommended was to [store binaries in `/opt/bin`](../../container-runtimes/use-a-custom-docker-or-containerd-version/) and prefer them in the `PATH`. + +For long time already, the systemd project provided the portable services feature to address deploying custom services. +However, since it only covered the service itself without making the client binaries available on the user, it didn't really fit the use case fully. +The systemd-sysext feature finally provides a way to extend the base OS with a `/usr` overlay, thereby making custom binaries available to the user. +While systemd-sysext images are not really good yet at including systemd units, Flatcar ships `ensure-sysext.service` as workaround to automatically load the image's services. +Systemd-sysext is supported in Flatcar versions ≥ 3185.0.0 for user provided sysext images. + +Here's some blog posts you can read for more context: + +1. https://www.flatcar.org/blog/2024/04/os-innovation-with-systemd-sysext/ +2. https://www.flatcar.org/blog/2023/07/summer-2023-my-internship-experience/ +3. https://www.flatcar.org/blog/2023/12/extending-flatcar-say-goodbye-to-torcx-and-hello-to-systemd-sysext/ + +## Types of systemd-sysext images + +For Flatcar, two types of systemd-sysext images are provided: + +- Official: + - enabled: These are extensions that are shipped along with the base image like Docker, Containerd, OEM partition. These are "opt-out". + - disabled: These are "opt-in" like ZFS, Podman or Python and one needs to write the extension name in `/etc/flatcar/enabled-sysext.conf` to pull the extension at boot. Similar to enabled extensions, those are built in Flatcar's CI and are distributed from the release servers. +- Community supported: These are extensions from the Flatcar [sysext-bakery releases](https://github.com/flatcar/sysext-bakery/releases) and they are not tested in CI. + +## OEM software as systemd-sysext images + +The Flatcar cloud images differ in the OEM vendor tools they provide in addition to the base image. In the past this was done through binaries on the OEM partition. Since Flatcar version 3760.0.0 most OEM images have been converted to use systemd-sysext images stored on the OEM. They are covered by the Flatcar A/B update mechanism because they are bound to the OS version they were released and tested with, also due to dynamic linking. Those users that run their own Nebraska update server need to make sure that they have a recent version that provides the OEM payloads. + +## Flatcar Release Extensions ("official") + +Official extensions provided as part of a Flatcar release make Flatcar more modular. Users have different demands while the base image should stay small. Certain software is bound to a particular OS version and can't be provided as out-of-band extension because it needs to be updated together with the OS. In the past this meant we had to find a compromise but soon Flatcar can support more use cases and might even reduce the base image contents further. Those users that run their own Nebraska update server need to make sure that they have a recent version that provides the Flatcar extension payloads. + +The table below give an overview on the supported Flatcar extensions. + +| Name in `/etc/flatcar/enabled-sysext.conf` | Sysext name on the instance | Availability | Documentation | Enabled by default | +| ------------------------------------------ | --------------------------- | ------------ | ------------------------- | ------------------ | +| n/a[^1] | `containerd-flatcar` | 3794.0.0 – … | | ✅ | +| n/a[^1] | `docker-flatcar` | 3794.0.0 – … | | ✅ | +| `incus` | `flatcar-incus` | 4285.0.0 – … | [Incus][incusextension] | | +| `nvidia-drivers-*` | `flatcar-nvidia-drivers-*` | 4344.0.0 – … | [NVIDIA][nvidiaextension] | | +| `overlaybd` | `flatcar-overlaybd` | 4426.0.0 – … | [OverlayBD][overlaybdext] | | +| `podman` | `flatcar-podman` | 3941.0.0 – … | | | +| `python` | `flatcar-python` | 4012.0.0 – … | | | +| `zfs` | `flatcar-zfs` | 3913.0.0 – … | [Storage][zfsextension] | | +| n/a[^1] | `oem-*` | 3760.2.0 – … | | ✅ | + +[^1]: n/a here because those sysexts are already enabled by default + +Users can enable Flatcar extensions by writing one name per line to `/etc/flatcar/enabled-sysext.conf`. +For now there are no pre-enabled release extensions but once Flatcar would move parts of the base image out into extensions, these would be pre-enabled as entries in `/usr/share/flatcar/enabled-sysext.conf`. They can be disabled with a `-NAME` entry in `/etc/flatcar/enabled-sysext.conf`. + +### Remove Docker and / or Containerd from Flatcar + +If Flatcar is used as a Kubernetes node or one wants to try a different version of Docker or Containerd, it is possible to remove those extensions from Flatcar at boot using this configuration: + +```yaml +variant: flatcar +version: 1.0.0 +storage: + links: + - path: /etc/extensions/docker-flatcar.raw + target: /dev/null + overwrite: true + - path: /etc/extensions/containerd-flatcar.raw + target: /dev/null + overwrite: true +``` + +## Community supported extensions ("community supported") + +A simple way to extend Flatcar is to use the systemd-sysext images from the [sysext-bakery GitHub repo](https://github.com/flatcar/sysext-bakery). It [publishes prebuilt images](https://github.com/flatcar/sysext-bakery/releases) that bundle third-party binaries. The repo README provides a Butane config example for updating the extensions with `systemd-sysupdate`. + +[Here's](https://flatcar.github.io/sysext-bakery/#what-extensions-are-available) a matrix for the community-supported extensions. + +## Bundle extensions in a Flatcar image + +The [`bake_flatcar_image.sh`](https://flatcar.github.io/sysext-bakery/#baking-sysexts-into-flatcar-os-images) helper in the [sysext-bakery GitHub repo](https://github.com/flatcar/sysext-bakery) can be used to customize a Flatcar release image by adding your extension images into the rootfs. + +## The sysext format + +Sysext images can be disk image files or simple folders (details in [`man systemd-sysext`](https://www.freedesktop.org/software/systemd/man/systemd-sysext.html)). +They get loaded by `systemd-sysext.service` which looks for them in `/etc/extensions/` or `/var/lib/extensions` among others. +An image must be named `NAME.raw` while a plain folder just uses `NAME` as name. +The image can be a plain ext4 or btrfs filesystem image but squashfs images are a useful format to consider because besides the compression it offers, the `mksquashfs` tool simply takes a directory as input and doesn't need loop devices and mounting of an image file. + +Inside the image or folder structure there must be a file `usr/lib/extension-release.d/extension-release.NAME` with metadata used for version matching. +The basic matching that needs to be there is `ID=flatcar` plus one of `VERSION_ID` or `SYSEXT_LEVEL`. +If your binaries link against Flatcar's binaries under `/usr`, you must couple your sysext image to the Flatcar version by specyfing `VERSION_ID=MAJOR.MINOR.PATCH` in `extension-release.NAME` to match the `VERSION_ID` field from `/etc/os-release`. +This means that the sysext image won't be loaded anymore after an OS update. +Therefore, it is recommended that you try to use static binaries which lifts the requirement of having to couple the versions. +In this case you can specify `SYSEXT_LEVEL=1.0` instead of `VERSION_ID`. +The matching semantics for `SYSEXT_LEVEL` are limited at the moment and the use case for bumping the version are not there yet. +In summary, this is what you will normally write to the metadata file: + +``` +ID=flatcar +SYSEXT_LEVEL=1.0 +``` + +Then place your binaries under `usr/bin/` and your systemd units under `usr/lib/systemd/system/`. +While Flatcar currently allows you to enable systemd units by including the symlinks it would generate when enabling the units, e.g., `sockets.target.wants/my.socket` → `../my.socket`, this is not recommended. +The recommended way is to ship drop-ins for the target units that start your unit, e.g., `usr/lib/systemd/system/sockets.target.d/10-docker-socket.conf` with the following content (similar for `multi-user.target` and a `.service` unit): + +```ini +[Unit] +Upholds=docker.socket +``` + +## Supplying your sysext image from Ignition + +The following Butane Config YAML can be be transpiled to Ignition JSON and will download a custom Docker+containerd sysext image on first boot. +It also takes care of disabling built-in Docker and containerd sysext images (to revert this, you can find the original target of the symlinks in `/usr/share/flatcar/etc/extensions/`). + +```yaml +variant: flatcar +version: 1.0.0 +storage: + files: + - path: /etc/extensions/mydocker.raw + mode: 0644 + contents: + source: https://myserver.net/mydocker.raw + links: + - path: /etc/extensions/docker-flatcar.raw + target: /dev/null + overwrite: true + - path: /etc/extensions/containerd-flatcar.raw + target: /dev/null + overwrite: true +``` + +After boot you can see it loaded in the output of the `systemd-sysext` command: + +``` +HIERARCHY EXTENSIONS SINCE +/opt none - +/usr mydocker Wed 2022-03-23 14:16:37 UTC +``` + +You can reload the sysext images at runtime by executing `systemctl restart systemd-sysext`. +In Flatcar this also triggers `ensure-sysext.service` to reload the unit files from disk (in the future this may be covered by `systemd-sysext` itself). +As an additional workaround, Flatcar currently also reevaluates `multi-user.target`, `sockets.target`, and `timers.target`, to make sure your enabled systemd units run, but for units started by `Upholds=` drop-ins that wouldn't be needed. +A manual `systemd-sysext refresh` is not recommended. + +## Creating custom sysext images + +The [`sysext-bakery`][sysext-bakery] repository under the Flatcar GitHub organization serves as a central point for sysext building tools. +Please reach out if your use case isn't covered and work with us to include it there. + +### Upstream Docker sysext images + +The Docker releases publish static binaries including containerd and the only missing piece are the systemd units. +To ease the process, the [`create_docker_sysext.sh`](https://raw.githubusercontent.com/flatcar/sysext-bakery/main/create_docker_sysext.sh) helper script takes care of downloading the release binaries and adding the systemd unit files, and creates a combined Docker+containerd sysext image: + +``` +./create_docker_sysext.sh 20.10.13 mydocker +[… writes mydocker.raw into current directory …] +``` + +## Updating custom sysext images + +From Flatcar 3510.2.0, it is possible to use the `systemd-sysupdate` tool that covers the task of downloading newer versions of your sysext image at runtime from a location you specify. + +The [sysext-bakery documentation][sysext-bakery] has examples for Butane configs that consume the `sysext-bakery` images and keep them up-to-date with `systemd-sysupdate`. You can adapt the examples to other images of the `systemd-bakery` repo or to your custom images hosted elsewhere. An easy method is to fork the repo and tweak the list of released images to your liking. + +## Debugging + +The `systemd-dissect` tool gives a quick overview for a systemd-sysext image: + +``` +sudo systemd-dissect docker-compose.raw +``` + +You can list the contents of a systemd-sysext image with the `--list` flag (or `--mtree` for a detailed view): + +``` +sudo systemd-dissect --list docker-compose.raw +``` + +A single file can be extracted with: + +``` +sudo systemd-dissect --with docker-compose.raw cat usr/lib/extension-release.d/extension-release.docker-compose +``` + +To get more information about found incompatibilities during merging, enable the debug output: + +``` +sudo SYSTEMD_LOG_LEVEL=debug systemd-sysext refresh +``` + +[incusextension]: ../../container-runtimes/incus +[sysext-bakery]: https://flatcar.github.io/sysext-bakery +[nvidiaextension]: ../../setup/customization/using-nvidia +[overlaybdext]: ../../setup/customization/overlaybd-artifact-streaming +[zfsextension]: ../../setup/storage/zfs diff --git a/content/docs/latest/updates-releases/_index.md b/content/docs/latest/updates-releases/_index.md new file mode 100644 index 000000000..70cd83b01 --- /dev/null +++ b/content/docs/latest/updates-releases/_index.md @@ -0,0 +1,15 @@ +--- +content_type: nebraska +title: Nebraska Update Manager & Releases +main_menu: true +weight: 80 +cascade: + github_edit_url: https://github.com/flatcar/flatcar-website/tree/master/content/docs/latest + issues_url: https://github.com/flatcar/nebraska/issues/new +aliases: + - /docs/latest/nebraska/ +--- + +Nebraska is an update manager for [Flatcar Container Linux](https://flatcar.org/). + +It offers an easy way to monitor and manage the rollout of updates to applications that use the Omaha protocol, with special functionality for Flatcar Container Linux updates. diff --git a/content/docs/latest/updates-releases/nebraska/_index.md b/content/docs/latest/updates-releases/nebraska/_index.md new file mode 100644 index 000000000..00b8f2a0a --- /dev/null +++ b/content/docs/latest/updates-releases/nebraska/_index.md @@ -0,0 +1,6 @@ +--- +title: Nebraska Update Manager +weight: 10 +description: > + Monitor and manage the rollout of updates using the Nebraska update manager. +--- diff --git a/content/docs/latest/updates-releases/nebraska/i18n/_index.md b/content/docs/latest/updates-releases/nebraska/i18n/_index.md new file mode 100644 index 000000000..d72bea0fd --- /dev/null +++ b/content/docs/latest/updates-releases/nebraska/i18n/_index.md @@ -0,0 +1,33 @@ +--- +title: i18n Internationalization / Localization +linkTitle: Internationalization +aliases: + - /docs/latest/nebraska/i18n/ +--- + +Nebraska's internationalization uses the i18next, i18next-parser, and +react-i18next libraries. + +## Default language, and locales + +We started with an international English, and that will be the fallback language. + +Now we're starting with locales familiar, and will accept +translations through github. + +## Browser based language detection + +We use +[i18next-browser-languagedetector](https://github.com/i18next/i18next-browser-languageDetector#readme) + +This can select the browser language through various means like through +cookies, the html language tag and other ways. + +One way to change the locale is to use `?lng=en` in the URL. + +## Lazy load locale files + +Dynamic imports and the webpack code splitting feature we +load locale files from `src/js/i18n/locales/{{lng}}/{{ns}}.json` +where {{lng}} is the language code, and {{ns}} is the namespace. + diff --git a/content/docs/latest/updates-releases/releases/_index.md b/content/docs/latest/updates-releases/releases/_index.md new file mode 100644 index 000000000..844e6e1da --- /dev/null +++ b/content/docs/latest/updates-releases/releases/_index.md @@ -0,0 +1,11 @@ +--- +title: Managing Releases +description: > + Guides to help you select which Flatcar release to run on your instances, + how to set the update configuration, verify the image if you download it + manually. +weight: 20 +aliases: + - /docs/latest/setup/releases/ + - ../../clusters/management +--- From 1689f205dcdfc34e86572a7bb519f7144f187465 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 9 Jun 2026 23:10:08 +0100 Subject: [PATCH 03/20] chore: nit fixes Signed-off-by: thisisobate --- content/docs/latest/fb-provision/cl-config/_index.md | 2 +- content/docs/latest/fb-provision/vms/_index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/latest/fb-provision/cl-config/_index.md b/content/docs/latest/fb-provision/cl-config/_index.md index 549034ea4..6ea8dd1a9 100644 --- a/content/docs/latest/fb-provision/cl-config/_index.md +++ b/content/docs/latest/fb-provision/cl-config/_index.md @@ -1,7 +1,7 @@ --- title: "[DEPRECATED / EOL] Container Linux Config Transpiler" description: YAML configuration format used to generate Ignition configs. -weight: 20 +weight: 45 aliases: - ../os/provisioning - ../reference/migrating-to-clcs/provisioning diff --git a/content/docs/latest/fb-provision/vms/_index.md b/content/docs/latest/fb-provision/vms/_index.md index cfd8c17ea..df4ebd1ff 100644 --- a/content/docs/latest/fb-provision/vms/_index.md +++ b/content/docs/latest/fb-provision/vms/_index.md @@ -1,6 +1,6 @@ --- title: Virtual Machines -linktitle: Running on Vagrant +linktitle: Virtual Machines weight: 40 aliases: - /docs/latest/installing/vms/vagrant/ From 70af24613ce32014baa1cf5ec9a0214e9cad9985 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Thu, 11 Jun 2026 13:44:14 +0100 Subject: [PATCH 04/20] chore: fix relative linking in docs Signed-off-by: thisisobate --- content/docs/latest/_index.md | 184 ++--- content/docs/latest/contribute/docs.md | 2 +- .../update-from-container-linux.md | 2 +- .../deploy/bare-metal/booting-with-ipxe.md | 10 +- .../deploy/bare-metal/booting-with-iso.md | 2 +- .../deploy/bare-metal/booting-with-pxe.md | 8 +- .../deploy/bare-metal/installing-to-disk.md | 6 +- content/docs/latest/deploy/cloud/aws-ec2.md | 8 +- content/docs/latest/deploy/cloud/azure.md | 10 +- content/docs/latest/deploy/cloud/brightbox.md | 2 +- .../docs/latest/deploy/cloud/digitalocean.md | 6 +- content/docs/latest/deploy/cloud/gcp.md | 8 +- content/docs/latest/deploy/cloud/hetzner.md | 4 +- content/docs/latest/deploy/cloud/openstack.md | 4 +- content/docs/latest/deploy/cloud/vmware.md | 10 +- .../latest/deploy/virt-options/eucalyptus.md | 2 +- .../latest/deploy/virt-options/exoscale.md | 4 +- .../virt-options/notes-for-distributors.md | 4 +- .../latest/deploy/virt-options/ovhcloud.md | 2 +- .../latest/deploy/virt-options/proxmoxve.md | 2 +- .../latest/deploy/virt-options/scaleway.md | 2 +- .../docs/latest/deploy/virt-options/vultr.md | 4 +- .../latest/devguide/sdk-disk-partitions.md | 4 +- .../latest/devguide/sdk-modifying-flatcar.md | 2 +- .../diagnostics/btrfs-troubleshooting.md | 8 +- .../diagnostics/reading-the-system-log.md | 11 +- .../latest/fb-provision/butane/examples.md | 4 +- .../fb-provision/butane/getting-started.md | 11 +- .../latest/fb-provision/cl-config/_index.md | 50 +- .../fb-provision/cl-config/dynamic-data.md | 2 +- .../latest/fb-provision/cl-config/examples.md | 30 +- .../cl-config/from-cloud-config.md | 60 +- .../fb-provision/cl-config/operators-notes.md | 2 +- .../customize-image/customize-the-image.md | 2 +- .../fb-provision/ignition/dynamic-data.md | 2 +- .../fb-provision/ignition/specification.md | 640 +++++++++--------- .../fb-provision/infrastructure/_index.md | 7 +- .../docs/latest/fb-provision/vms/hyper-v.md | 4 +- .../docs/latest/fb-provision/vms/kubevirt.md | 2 +- .../docs/latest/fb-provision/vms/libvirt.md | 6 +- content/docs/latest/fb-provision/vms/qemu.md | 4 +- .../latest/fb-provision/vms/virtualbox.md | 2 +- content/docs/latest/getting-started/_index.md | 18 +- .../immutability-updates-rollbacks.md | 183 ++--- .../orchestrate/clusters/architectures.md | 12 +- .../orchestrate/clusters/booting-on-ecs.md | 6 +- .../latest/orchestrate/clusters/discovery.md | 2 +- .../containers/customizing-docker.md | 2 +- .../os-config/host-config/adding-users.md | 6 +- .../configuring-date-and-timezone.md | 2 +- .../os-config/host-config/drop-in-units.md | 12 +- .../host-config/environment-variables.md | 26 +- .../os-config/host-config/power-management.md | 2 +- content/docs/latest/os-config/network/ACPI.md | 2 +- .../os-config/network/configuring-dns.md | 2 +- .../network/network-config-with-networkd.md | 15 +- .../docs/latest/os-config/storage/iscsi.md | 2 +- .../os-config/storage/mounting-storage.md | 4 +- content/docs/latest/os-config/storage/raid.md | 4 +- .../os-config/systemd/getting-started.md | 46 +- .../latest/os-config/systemd/udev-rules.md | 16 +- .../security/cert-auth/customize-etcd-unit.md | 38 +- .../security/cert-auth/customizing-sshd.md | 2 +- .../docs/latest/security/constants-and-ids.md | 24 +- content/docs/latest/sys-ext/_index.md | 10 +- .../updates-releases/releases/update-conf.md | 2 +- .../releases/update-strategies.md | 27 +- 67 files changed, 811 insertions(+), 793 deletions(-) diff --git a/content/docs/latest/_index.md b/content/docs/latest/_index.md index b8a117931..59ce8f59d 100644 --- a/content/docs/latest/_index.md +++ b/content/docs/latest/_index.md @@ -193,96 +193,96 @@ APIs and troubleshooting guides for working with Flatcar Container Linux. * [Migrating from cloud-config to Container Linux Config][migrating-from-cloud-config] * [Flatcar Supply Chain Security (SLSA and SPDX SBOM)][supply-chain-security] detailing security mechanisms employed at build / release time as well as at run-time to ensure validity of inputs processed and outputs shipped. -[quick-start]: installing -[learning-series]: learning-series -[supply-chain-security]: reference/supply-chain -[ignition-what]: provisioning/ignition/ -[ignition-boot]: provisioning/ignition/boot-process -[ignition-network]: provisioning/ignition/network-configuration -[ignition-metadata]: provisioning/ignition/dynamic-data -[container-linux-config]: provisioning/cl-config/ -[config-transpiler]: provisioning/config-transpiler/ -[config-intro]: provisioning/config-transpiler/getting-started -[config-dynamic-data]: provisioning/config-transpiler/dynamic-data -[config-examples]: provisioning/config-transpiler/examples +[quick-start]: ./getting-started +[learning-series]: ./getting-started/learning-series +[supply-chain-security]: ./security/supply-chain +[ignition-what]: ./fb-provision/ignition/ +[ignition-boot]: ./fb-provision/ignition/boot-process +[ignition-network]: ./fb-provision/ignition/network-configuration +[ignition-metadata]: ./fb-provision/ignition/dynamic-data +[container-linux-config]: ./fb-provision/cl-config/ +[config-transpiler]: ./fb-provision/butane/ +[config-intro]: ./fb-provision/butane/getting-started +[config-dynamic-data]: ./fb-provision/butane/dynamic-data +[config-examples]: ./fb-provision/butane/examples [matchbox]: https://matchbox.psdn.io/ -[ipxe]: installing/bare-metal/booting-with-ipxe -[pxe]: installing/bare-metal/booting-with-pxe -[install-to-disk]: installing/bare-metal/installing-to-disk -[boot-iso]: installing/bare-metal/booting-with-iso -[filesystem-placement]: setup/storage/raid -[migrate-from-container-linux]: migrating-from-coreos/ -[update-from-container-linux]: migrating-from-coreos/update-from-container-linux -[ec2]: installing/cloud/aws-ec2 -[digital-ocean]: installing/cloud/digitalocean -[gce]: installing/cloud/gcp -[azure]: installing/cloud/azure -[qemu]: installing/vms/qemu -[libvirt]: installing/vms/libvirt -[virtualbox]: installing/vms/virtualbox -[vagrant]: installing/vms/vagrant -[hyper-v]: installing/vms/hyper-v -[kubevirt]: installing/vms/kubevirt -[proxmoxve]: installing/community-platforms/proxmoxve -[vmware]: installing/community-platforms/vmware -[cluster-architectures]: setup/clusters/architectures -[update-strategies]: setup/releases/update-strategies -[clustering-machines]: setup/clusters/discovery -[verify-container-linux]: setup/releases/verify-images -[networkd-customize]: setup/customization/network-config-with-networkd -[systemd-drop-in]: setup/systemd/drop-in-units -[environment-variables-systemd]: setup/systemd/environment-variables -[dns]: setup/customization/configuring-dns -[date-timezone]: setup/customization/configuring-date-and-timezone -[users]: setup/customization/adding-users -[parameters]: setup/customization/other-settings -[disk-space]: setup/storage/adding-disk-space -[mounting-storage]: setup/storage/mounting-storage -[power-management]: setup/customization/power-management -[registry-authentication]: container-runtimes/registry-authentication -[iscsi]: setup/storage/iscsi -[swap]: setup/storage/adding-swap -[zfsextension]: setup/storage/zfs -[ec2-container-service]: setup/clusters/booting-on-ecs/ -[manage-docker-containers]: setup/systemd/getting-started -[udev-rules]: setup/systemd/udev-rules -[update-conf]: setup/releases/update-conf -[release-channels]: setup/releases/switching-channels -[tasks-with-systemd]: setup/systemd/timers -[luks-encryption]: setup/security/luks -[ssh-daemon]: setup/security/customizing-sshd -[sssd-container-linux]: setup/security/sssd -[hardening-container-linux]: setup/security/hardening-guide -[hardware-requirements]: setup/security/trusted-computing-hardware-requirements -[cert-authorities]: setup/security/adding-certificate-authorities -[selinux]: setup/security/selinux -[disabling-smt]: setup/security/disabling-smt -[enabling-fips]: setup/security/fips -[audit-system]: setup/security/audit -[debugging-tools]: setup/debug/install-debugging-tools -[btrfs]: setup/debug/btrfs-troubleshooting -[system-log]: setup/debug/reading-the-system-log -[crash-log]: setup/debug/collecting-crash-logs -[container-linux-rollbacks]: setup/debug/manual-rollbacks -[docker]: container-runtimes/getting-started-with-docker -[customizing-docker]: container-runtimes/customizing-docker -[use-a-custom-docker-or-containerd-version]: container-runtimes/use-a-custom-docker-or-containerd-version -[developer-guides]: reference/developer-guides/ -[integrations]: reference/integrations/ -[migrating-from-cloud-config]: provisioning/cl-config/from-cloud-config -[containerd-for-kubernetes]: container-runtimes/switching-from-docker-to-containerd-for-kubernetes -[terraform]: provisioning/terraform/ -[hetzner]: installing/cloud/hetzner -[sysext]: provisioning/sysext/ -[acpi]: setup/customization/ACPI -[openstack]: installing/cloud/openstack -[brightbox]: installing/cloud/brightbox -[kubernetes]: container-runtimes/getting-started-with-kubernetes -[ha-kubernetes]: container-runtimes/high-availability-kubernetes -[using-nvidia]: setup/customization/using-nvidia -[scaleway]: installing/community-platforms/scaleway -[oraclecloud]: installing/community-platforms/oraclecloud -[ovhcloud]: installing/community-platforms/ovhcloud -[akamai]: installing/cloud/akamai -[nebraska]: nebraska -[stackit]: installing/cloud/stackit +[ipxe]: ./deploy/bare-metal/booting-with-ipxe +[pxe]: ./deploy/bare-metal/booting-with-pxe +[install-to-disk]: ./deploy/bare-metal/installing-to-disk +[boot-iso]: ./deploy/bare-metal/booting-with-iso +[filesystem-placement]: ./os-config/storage/raid +[migrate-from-container-linux]: ./coreos-migration/ +[update-from-container-linux]: ./coreos-migration/update-from-container-linux +[ec2]: ./deploy/cloud/aws-ec2 +[digital-ocean]: ./deploy/cloud/digitalocean +[gce]: ./deploy/cloud/gcp +[azure]: ./deploy/cloud/azure +[qemu]: ./fb-provision/vms/qemu +[libvirt]: ./fb-provision/vms/libvirt +[virtualbox]: ./fb-provision/vms/virtualbox +[vagrant]: ./fb-provision/vms +[hyper-v]: ./fb-provision/vms/hyper-v +[kubevirt]: ./fb-provision/vms/kubevirt +[proxmoxve]: ./deploy/virt-options/proxmoxve +[vmware]: ./deploy/cloud/vmware +[cluster-architectures]: ./orchestrate/clusters/architectures +[update-strategies]: ./updates-releases/releases/update-strategies +[clustering-machines]: ./orchestrate/clusters/discovery +[verify-container-linux]: ./updates-releases/releases/verify-images +[networkd-customize]: ./os-config/network/network-config-with-networkd +[systemd-drop-in]: ./os-config/host-config/drop-in-units +[environment-variables-systemd]: ./os-config/host-config/environment-variables +[dns]: ./os-config/network/configuring-dns +[date-timezone]: ./os-config/host-config/configuring-date-and-timezone +[users]: ./os-config/host-config/adding-users +[parameters]: ./os-config/host-config/other-settings +[disk-space]: ./os-config/storage/adding-disk-space +[mounting-storage]: ./os-config/storage/mounting-storage +[power-management]: ./os-config/host-config/power-management +[registry-authentication]: ./orchestrate/containers/registry-authentication +[iscsi]: ./os-config/storage/iscsi +[swap]: ./os-config/storage/adding-swap +[zfsextension]: ./os-config/storage/zfs +[ec2-container-service]: ./orchestrate/clusters/booting-on-ecs/ +[manage-docker-containers]: ./os-config/systemd/getting-started +[udev-rules]: ./os-config/systemd/udev-rules +[update-conf]: ./updates-releases/releases/update-conf +[release-channels]: ./updates-releases/releases/switching-channels +[tasks-with-systemd]: ./os-config/host-config/timers +[luks-encryption]: ./security/encryption/luks +[ssh-daemon]: ./security/cert-auth/customizing-sshd +[sssd-container-linux]: ./security/cert-auth/sssd +[hardening-container-linux]: ./security/hardening/hardening-guide +[hardware-requirements]: ./security/hardening/trusted-computing-hardware-requirements +[cert-authorities]: ./security/cert-auth/adding-certificate-authorities +[selinux]: ./security/encryption/selinux +[disabling-smt]: ./security/hardening/disabling-smt +[enabling-fips]: ./security/hardening/fips +[audit-system]: ./security/hardening/audit +[debugging-tools]: ./diagnostics/install-debugging-tools +[btrfs]: ./diagnostics/btrfs-troubleshooting +[system-log]: ./diagnostics/reading-the-system-log +[crash-log]: ./diagnostics/collecting-crash-logs +[container-linux-rollbacks]: ./diagnostics/manual-rollbacks +[docker]: ./orchestrate/containers/getting-started-with-docker +[customizing-docker]: ./orchestrate/containers/customizing-docker +[use-a-custom-docker-or-containerd-version]: ./orchestrate/containers/use-a-custom-docker-or-containerd-version +[developer-guides]: ./devguide/ +[integrations]: ./devguide/integrations/ +[migrating-from-cloud-config]: ./fb-provision/cl-config/from-cloud-config +[containerd-for-kubernetes]: ./orchestrate/containers/switching-from-docker-to-containerd-for-kubernetes +[terraform]: ./fb-provision/infrastructure/ +[hetzner]: ./deploy/cloud/hetzner +[sysext]: ./sys-ext/ +[acpi]: ./os-config/network/ACPI +[openstack]: ./deploy/cloud/openstack +[brightbox]: ./deploy/cloud/brightbox +[kubernetes]: ./orchestrate/kubernetes/getting-started-with-kubernetes +[ha-kubernetes]: ./orchestrate/kubernetes/high-availability-kubernetes +[using-nvidia]: ./os-config/host-config/using-nvidia +[scaleway]: ./deploy/virt-options/scaleway +[oraclecloud]: ./deploy/virt-options/oraclecloud +[ovhcloud]: ./deploy/virt-options/ovhcloud +[akamai]: ./deploy/cloud/akamai +[nebraska]: ./updates-releases/nebraska +[stackit]: ./deploy/cloud/stackit diff --git a/content/docs/latest/contribute/docs.md b/content/docs/latest/contribute/docs.md index e6be29cf0..84cd784f3 100644 --- a/content/docs/latest/contribute/docs.md +++ b/content/docs/latest/contribute/docs.md @@ -248,7 +248,7 @@ Some file types are commonly identified with more than one file name extension. [command-line-grammar]: #command-line-grammar -[configuring-dns]: ../../setup/customization/configuring-dns +[configuring-dns]: ../os-config/network/configuring-dns [flatcar-docs]: https://docs.flatcar-linux.org/ [economist-hyphens]: http://www.economist.com/news/books-and-arts/21723088-hyphens-can-be-tricky-they-need-not-drive-you-crazy-hysteria-over-hyphens [eos]: https://faculty.washington.edu/heagerty/Courses/b572/public/StrunkWhite.pdf "The Elements of Style" diff --git a/content/docs/latest/coreos-migration/update-from-container-linux.md b/content/docs/latest/coreos-migration/update-from-container-linux.md index d0dafa698..136cb971a 100644 --- a/content/docs/latest/coreos-migration/update-from-container-linux.md +++ b/content/docs/latest/coreos-migration/update-from-container-linux.md @@ -110,4 +110,4 @@ sudo update_engine_client -update ``` [migrate-from-container-linux]: _index.md -[manual-rollback]: ../setup/debug/manual-rollbacks/#performing-a-manual-rollback +[manual-rollback]: ../diagnostics/manual-rollbacks#performing-a-manual-rollback diff --git a/content/docs/latest/deploy/bare-metal/booting-with-ipxe.md b/content/docs/latest/deploy/bare-metal/booting-with-ipxe.md index efdf93fdd..4e21381fc 100644 --- a/content/docs/latest/deploy/bare-metal/booting-with-ipxe.md +++ b/content/docs/latest/deploy/bare-metal/booting-with-ipxe.md @@ -162,13 +162,13 @@ Similar to the [OEM partition][oem] in Flatcar Container Linux disk images, iPXE Now that you have a machine booted it is time to play around. Check out the [Flatcar Container Linux Quickstart][quickstart] guide or dig into [more specific topics][doc-index]. -[cl-configs]: ../../provisioning/cl-config -[butane-configs]: ../../provisioning/config-transpiler -[ignition]: ../../provisioning/ignition -[ignition-kargs-ip]: ../../provisioning/ignition/network-configuration/#using-static-ip-addresses-with-ignition +[cl-configs]: ../../fb-provision/cl-config +[butane-configs]: ../../fb-provision/butane +[ignition]: ../../fb-provision/ignition +[ignition-kargs-ip]: ../../fb-provision/ignition/network-configuration#using-static-ip-addresses-with-ignition [oem]: ../community-platforms/notes-for-distributors#image-customization [installing-to-disk]: installing-to-disk -[update-strategies]: ../../setup/releases/update-strategies +[update-strategies]: ../../updates-releases/releases/update-strategies [release-notes]: https://flatcar-linux.org/releases [pxe-installation]: booting-with-pxe#installation [pxe-custom-oem]: booting-with-pxe#adding-a-custom-oem diff --git a/content/docs/latest/deploy/bare-metal/booting-with-iso.md b/content/docs/latest/deploy/bare-metal/booting-with-iso.md index f95d71a07..95eaafdb2 100644 --- a/content/docs/latest/deploy/bare-metal/booting-with-iso.md +++ b/content/docs/latest/deploy/bare-metal/booting-with-iso.md @@ -63,5 +63,5 @@ The most common use-case for this ISO is to install Flatcar Container Linux to d The ISO is configured to start a shell on the console without prompting for a password. This is convenient for installation and troubleshooting, but use caution. -[cl-configs]: ../../provisioning/cl-config +[cl-configs]: ../../fb-provision/cl-config [installing-to-disk]: installing-to-disk diff --git a/content/docs/latest/deploy/bare-metal/booting-with-pxe.md b/content/docs/latest/deploy/bare-metal/booting-with-pxe.md index 4398a2668..636ab78d3 100644 --- a/content/docs/latest/deploy/bare-metal/booting-with-pxe.md +++ b/content/docs/latest/deploy/bare-metal/booting-with-pxe.md @@ -250,12 +250,12 @@ Now that you have a machine booted it is time to play around. Check out the [Fla [append-initrd]: http://www.syslinux.org/wiki/index.php?title=SYSLINUX#INITRD_initrd_file [flatcar-user]: https://groups.google.com/forum/#!forum/flatcar-linux-user [discord]: https://discord.gg/PMYjFUsJyq -[butane-configs]: ../../provisioning/config-transpiler -[ignition]: ../../provisioning/ignition -[ignition-kargs-ip]: ../../provisioning/ignition/network-configuration/#using-static-ip-addresses-with-ignition +[butane-configs]: ../../fb-provision/butane +[ignition]: ../../fb-provision/ignition +[ignition-kargs-ip]: ../../fb-provision/ignition/network-configuration#using-static-ip-addresses-with-ignition [oem]: ../community-platforms/notes-for-distributors#image-customization [installing-to-disk]: installing-to-disk -[update-strategies]: ../../setup/releases/update-strategies +[update-strategies]: ../../updates-releases/releases/update-strategies [release-notes]: https://flatcar-linux.org/releases [quickstart]: ../ [doc-index]: ../../ diff --git a/content/docs/latest/deploy/bare-metal/installing-to-disk.md b/content/docs/latest/deploy/bare-metal/installing-to-disk.md index 62e0bcf16..2255e8124 100644 --- a/content/docs/latest/deploy/bare-metal/installing-to-disk.md +++ b/content/docs/latest/deploy/bare-metal/installing-to-disk.md @@ -172,10 +172,10 @@ Now that you have a machine booted it is time to play around. Check out the [Fla [quickstart]: ../ [docs-root]: ../../ -[update-strategies]: ../../setup/releases/update-strategies +[update-strategies]: ../../updates-releases/releases/update-strategies [release-notes]: https://flatcar-linux.org/releases [flatcar-iso]: booting-with-iso [butane-section]: #butane-configs [flatcar-install]: https://raw.githubusercontent.com/flatcar/init/flatcar-master/bin/flatcar-install -[cl-configs]: ../../provisioning/cl-config -[butane]: ../../provisioning/config-transpiler +[cl-configs]: ../../fb-provision/cl-config +[butane]: ../../fb-provision/butane diff --git a/content/docs/latest/deploy/cloud/aws-ec2.md b/content/docs/latest/deploy/cloud/aws-ec2.md index 73fd62529..f180aa126 100644 --- a/content/docs/latest/deploy/cloud/aws-ec2.md +++ b/content/docs/latest/deploy/cloud/aws-ec2.md @@ -124,7 +124,7 @@ systemd: RequiredBy=local-fs.target ``` -For more information about mounting storage, Amazon's [own documentation](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html) is the best source. You can also read about [mounting storage on Flatcar Container Linux](../../setup/storage/mounting-storage). +For more information about mounting storage, Amazon's [own documentation](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html) is the best source. You can also read about [mounting storage on Flatcar Container Linux](../../os-config/storage/mounting-storage). ### Adding more machines @@ -218,7 +218,7 @@ Now that you have a machine booted it is time to play around. Check out the [Fla ## Terraform The [`aws`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) Terraform Provider allows to deploy machines in a declarative way. -Read more about using Terraform and Flatcar [here](../../provisioning/terraform/). +Read more about using Terraform and Flatcar [here](../../fb-provision/infrastructure/). The following Terraform v0.13 module may serve as a base for your own setup. It will also take care of registering your SSH key at AWS EC2 and managing the network environment with Terraform. @@ -499,8 +499,8 @@ You can find this Terraform module in the repository for [Flatcar Terraform exam [flatcar-user]: https://groups.google.com/forum/#!forum/flatcar-linux-user [docker-docs]: https://docs.docker.io [etcd-docs]: https://etcd.io/docs -[update-strategies]: ../../setup/releases/update-strategies +[update-strategies]: ../../updates-releases/releases/update-strategies [discord]: https://discord.gg/PMYjFUsJyq [release-notes]: https://flatcar-linux.org/releases [ec2-user-data]: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../../fb-provision/butane diff --git a/content/docs/latest/deploy/cloud/azure.md b/content/docs/latest/deploy/cloud/azure.md index 06dc2cd71..a6ba97e54 100644 --- a/content/docs/latest/deploy/cloud/azure.md +++ b/content/docs/latest/deploy/cloud/azure.md @@ -429,7 +429,7 @@ For information on using Flatcar Container Linux check out the [Flatcar Containe ## Terraform The [`azurerm`](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs) Terraform Provider allows to deploy machines in a declarative way. -Read more about using Terraform and Flatcar [here](../../provisioning/terraform/). +Read more about using Terraform and Flatcar [here](../../fb-provision/infrastructure/). The following Terraform v0.13 module may serve as a base for your own setup. @@ -633,7 +633,7 @@ You can resolve the latest Flatcar Stable version with this shell command: curl -sSfL https://stable.release.flatcar-linux.net/amd64-usr/current/version.txt | grep -m 1 FLATCAR_VERSION_ID= | cut -d = -f 2 ``` -The machine name listed in the `machines` variable is used to retrieve the corresponding [Container Linux Config](../../provisioning/config-transpiler/configuration) template from the `cl/` subfolder. +The machine name listed in the `machines` variable is used to retrieve the corresponding [Container Linux Config](../../fb-provision/butane/configuration) template from the `cl/` subfolder. For each machine in the list, you should have a `machine-NAME.yaml.tmpl` file with a corresponding name. Create the configuration for `mynode` in the file `cl/machine-mynode.yaml.tmpl`: @@ -755,13 +755,13 @@ storage: [flatcar-user]: https://groups.google.com/forum/#!forum/flatcar-linux-user [etcd-docs]: https://etcd.io/docs [quickstart]: ../ -[reboot-docs]: ../../setup/releases/update-strategies +[reboot-docs]: ../../updates-releases/releases/update-strategies [azure-cli]: https://docs.microsoft.com/en-us/cli/azure/overview -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../../fb-provision/butane [irc]: irc://irc.freenode.org:6667/#flatcar [docs]: ../../ [resource-group]: https://docs.microsoft.com/en-us/azure/architecture/best-practices/naming-conventions#naming-rules-and-restrictions [storage-account]: https://docs.microsoft.com/en-us/azure/storage/common/storage-account-overview#naming-storage-accounts [azure-flatcar-image-upload]: https://github.com/flatcar/flatcar-cloud-image-uploader [release-notes]: https://flatcar.org/releases -[update-docs]: ../../setup/releases/update-strategies +[update-docs]: ../../updates-releases/releases/update-strategies diff --git a/content/docs/latest/deploy/cloud/brightbox.md b/content/docs/latest/deploy/cloud/brightbox.md index 1970dde08..37c3795e5 100644 --- a/content/docs/latest/deploy/cloud/brightbox.md +++ b/content/docs/latest/deploy/cloud/brightbox.md @@ -108,7 +108,7 @@ core@srv-f0lo3 ~ $ systemctl status nginx Now that you have a machine booted it is time to play around. Check out the [Flatcar Container Linux Quickstart][quickstart] guide or dig into [more specific topics][doc-index]. -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../../fb-provision/butane [brightbox]: https://cloud.brightbox.com/ [cli]: https://www.brightbox.com/docs/reference/cli [doc-index]: ../../ diff --git a/content/docs/latest/deploy/cloud/digitalocean.md b/content/docs/latest/deploy/cloud/digitalocean.md index 4ccde99cb..073ee01cf 100644 --- a/content/docs/latest/deploy/cloud/digitalocean.md +++ b/content/docs/latest/deploy/cloud/digitalocean.md @@ -47,7 +47,7 @@ At the end of the document there are instructions for deploying with Terraform. --> -[reboot-docs]: ../../setup/releases/update-strategies +[reboot-docs]: ../../updates-releases/releases/update-strategies [release-notes]: https://www.flatcar-linux.org/releases/ ## Butane Configs @@ -200,7 +200,7 @@ Now that you have a machine booted it is time to play around. Check out the [Fla ## Terraform The [`digitalocean`](https://registry.terraform.io/providers/digitalocean/digitalocean/latest/docs) Terraform Provider allows to deploy machines in a declarative way. -Read more about using Terraform and Flatcar [here](../../provisioning/terraform/). +Read more about using Terraform and Flatcar [here](../../fb-provision/infrastructure/). The following Terraform v0.13 module may serve as a base for your own setup. It will also take care of registering your SSH key at Digital Ocean and creating a custom image. @@ -383,7 +383,7 @@ When you make a change to `machine-mynode.yaml.tmpl` and run `terraform apply` a You can find this Terraform module in the repository for [Flatcar Terraform examples](https://github.com/flatcar/flatcar-terraform/tree/main/digitalocean). -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../../fb-provision/butane [do-api-docs]: https://developers.digitalocean.com/documentation/v2/ [do-keys-docs]: https://developers.digitalocean.com/documentation/v2/#ssh-keys [do-list-keys-docs]: https://developers.digitalocean.com/documentation/v2/#list-all-keys diff --git a/content/docs/latest/deploy/cloud/gcp.md b/content/docs/latest/deploy/cloud/gcp.md index 0ad65c527..74cb93a01 100644 --- a/content/docs/latest/deploy/cloud/gcp.md +++ b/content/docs/latest/deploy/cloud/gcp.md @@ -99,7 +99,7 @@ The Dockerfile for the `quay.io/kinvolk/google-cloud-flatcar-image-upload` image ## Upgrade from CoreOS Container Linux -You can also [upgrade from an existing CoreOS Container Linux system](../../migrating-from-coreos/update-from-container-linux). +You can also [upgrade from an existing CoreOS Container Linux system](../../coreos-migration/update-from-container-linux). ## Butane Config @@ -300,8 +300,8 @@ The resulting image can then be deployed to a container on each Flatcar node. Now that you have a machine booted it is time to play around. Check out the [Flatcar Container Linux Quickstart][quickstart] guide or dig into [more specific topics][doc-index]. -[mounting-storage]: ../../setup/storage/mounting-storage +[mounting-storage]: ../../os-config/storage/mounting-storage [quickstart]: ../ [doc-index]: ../../ -[update-strategies]: ../../setup/releases/update-strategies -[cl-configs]: ../../provisioning/config-transpiler +[update-strategies]: ../../updates-releases/releases/update-strategies +[cl-configs]: ../../fb-provision/butane diff --git a/content/docs/latest/deploy/cloud/hetzner.md b/content/docs/latest/deploy/cloud/hetzner.md index c51ce19de..89fb4acce 100644 --- a/content/docs/latest/deploy/cloud/hetzner.md +++ b/content/docs/latest/deploy/cloud/hetzner.md @@ -186,7 +186,7 @@ ID TYPE NAME DESCRIPTION ARCHITECTURE IMAGE SIZE ### Requirements -- [Butane](../../provisioning/config-transpiler/) +- [Butane](../../fb-provision/butane/) - [Hetzner Cloud CLI](https://github.com/hetznercloud/cli) (`hcloud`) - Snapshots from the previous section - SSH Key @@ -202,7 +202,7 @@ hcloud ssh-key create --public-key-from-file ~/.ssh/.pub --name my ### Server configuration -Flatcar allows you to configure machine parameters, launch systemd units on startup and more via [Butane Configs](../../provisioning/config-transpiler/). These configs are then transpiled into Ignition JSON configs and given to booting machines. +Flatcar allows you to configure machine parameters, launch systemd units on startup and more via [Butane Configs](../../fb-provision/butane/). These configs are then transpiled into Ignition JSON configs and given to booting machines. We're going to provide our Butane Config to Hetzner via the user-data flag. The `coreos-metadata.service` saves metadata variables to `/run/metadata/flatcar`. Systemd units can use them with `EnvironmentFile=/run/metadata/flatcar` in the `[Service]` section when setting `Requires=coreos-metadata.service` and `After=coreos-metadata.service` in the `[Unit]` section. diff --git a/content/docs/latest/deploy/cloud/openstack.md b/content/docs/latest/deploy/cloud/openstack.md index 3526f4f1f..04b346387 100644 --- a/content/docs/latest/deploy/cloud/openstack.md +++ b/content/docs/latest/deploy/cloud/openstack.md @@ -205,8 +205,8 @@ openstack server create \ Now that you have a machine booted it is time to play around. Check out the [Flatcar Container Linux Quickstart][quickstart] guide or dig into [more specific topics][doc-index]. -[update-strategies]: ../../setup/releases/update-strategies +[update-strategies]: ../../updates-releases/releases/update-strategies [release-notes]: https://flatcar-linux.org/releases [quickstart]: ../ [doc-index]: ../../ -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../../fb-provision/butane diff --git a/content/docs/latest/deploy/cloud/vmware.md b/content/docs/latest/deploy/cloud/vmware.md index e8d6f082a..d55a3938b 100644 --- a/content/docs/latest/deploy/cloud/vmware.md +++ b/content/docs/latest/deploy/cloud/vmware.md @@ -164,7 +164,7 @@ IP configuration specified via `guestinfo.interface.*` and `guestinfo.dns.*` var ### Templating with Butane Configs and setting up metadata -On many cloud providers Ignition will run the [`coreos-metadata.service`](../../provisioning/ignition/dynamic-data) (which runs `afterburn`) to set up [node metadata](../../provisioning/cl-config/dynamic-data). This is not the case with VMware because the network setup is defined by you and nothing generic that `afterburn` would know about. +On many cloud providers Ignition will run the [`coreos-metadata.service`](../../fb-provision/ignition/dynamic-data) (which runs `afterburn`) to set up [node metadata](../../fb-provision/cl-config/dynamic-data). This is not the case with VMware because the network setup is defined by you and nothing generic that `afterburn` would know about. Here's a Butane configuration example to setup an `etcd` instance with a custom `coreos-metadata.service`: @@ -316,7 +316,7 @@ kernel_arguments: With `should_exist` instead of `should_not_exist` the argument would be added if it isn't set in `grub.cfg` already. -Read more about setting kernel command line parameters this way [here](../../../setup/customization/other-settings/#adding-custom-kernel-boot-options). +Read more about setting kernel command line parameters this way [here](../../os-config/host-config/other-settings#adding-custom-kernel-boot-options). In case you want to disable the autologin on the console with Ignition v2 where no `kernelArguments` directive exists, you can use the following directive in your Container Linux Config YAML. To take effect it requires an additional reboot. @@ -358,8 +358,8 @@ systemd: Now that you have a machine booted, it's time to explore. Check out the [Flatcar Container Linux Quickstart][quickstart] guide, or dig into [more specific topics][docs]. -[cl-configs]: ../../provisioning/cl-config -[update-strategies]: ../../setup/releases/update-strategies +[cl-configs]: ../../fb-provision/cl-config +[update-strategies]: ../../updates-releases/releases/update-strategies [release-notes]: https://flatcar-linux.org/releases [quickstart]: ../ [docs]: ../../ @@ -369,5 +369,5 @@ Now that you have a machine booted, it's time to explore. Check out the [Flatcar [vcloud director]: http://blogs.vmware.com/vsphere/2012/06/leveraging-vapp-vm-custom-properties-in-vcloud-director.html [ovf-selfconfig]: http://blogs.vmware.com/vapp/2009/07/selfconfiguration-and-the-ovf-environment.html [guestinfo]: #defining-the-ignition-config-or-coreos-cloudinit-cloud-config-in-guestinfo -[transpiler]: ../../provisioning/config-transpiler/ +[transpiler]: ../../fb-provision/butane/ [ovftool]: https://www.vmware.com/support/developer/ovf/ diff --git a/content/docs/latest/deploy/virt-options/eucalyptus.md b/content/docs/latest/deploy/virt-options/eucalyptus.md index a5eb756fb..56c198f9b 100644 --- a/content/docs/latest/deploy/virt-options/eucalyptus.md +++ b/content/docs/latest/deploy/virt-options/eucalyptus.md @@ -105,7 +105,7 @@ core@10-0-0-3 ~ $ Now that you have a machine booted it is time to play around. Check out the [Flatcar Container Linux Quickstart][quickstart] guide or dig into [more specific topics][doc-index]. -[update-strategies]: ../../setup/releases/update-strategies +[update-strategies]: ../../updates-releases/releases/update-strategies [release-notes]: https://flatcar-linux.org/releases [quickstart]: ../ [doc-index]: ../../ diff --git a/content/docs/latest/deploy/virt-options/exoscale.md b/content/docs/latest/deploy/virt-options/exoscale.md index 0c7e7869d..8e2cbaa52 100644 --- a/content/docs/latest/deploy/virt-options/exoscale.md +++ b/content/docs/latest/deploy/virt-options/exoscale.md @@ -15,8 +15,8 @@ Flatcar Container Linux is designed to be updated automatically with different s The Exoscale Flatcar Container Linux image is built officially and each instance deployment is a unique fresh instance. By default, only the stable channel is deployed on Exoscale, you can easily [switch to Beta or Alpha channel][switching-channels]. -[reboot-docs]: ../../setup/releases/update-strategies -[switching-channels]: ../../setup/releases/switching-channels +[reboot-docs]: ../../updates-releases/releases/update-strategies +[switching-channels]: ../../updates-releases/releases/switching-channels [release-notes]: https://flatcar-linux.org/releases [cloud-config-docs]: https://github.com/flatcar/coreos-cloudinit/blob/master/Documentation/cloud-config.md diff --git a/content/docs/latest/deploy/virt-options/notes-for-distributors.md b/content/docs/latest/deploy/virt-options/notes-for-distributors.md index 7c5253334..306cf58f4 100644 --- a/content/docs/latest/deploy/virt-options/notes-for-distributors.md +++ b/content/docs/latest/deploy/virt-options/notes-for-distributors.md @@ -43,7 +43,7 @@ There are two predominant ways that a Flatcar Container Linux image can be easil It is recommended that providers ensure that [Afterburn][coreos-metadata] has support for their platform. This will allow a nicer user experience, as Afterburn will be able to install users' ssh keys and users will be able to reference metadata variables in their systemd units. -[ignition]: ../../provisioning/ignition +[ignition]: ../../fb-provision/ignition [coreos-metadata]: https://github.com/coreos/afterburn/ ### Cloud config @@ -55,7 +55,7 @@ Providers that previously supported cloud-config should continue to do so, as no Flatcar Container Linux will automatically parse and execute `/usr/share/oem/cloud-config.yml` if it exists. [ignition-blog]: https://www.toddpigram.com/2016/04/introducing-ignition-new-coreos-machine.html -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../../fb-provision/butane ## Handling end-user Ignition files diff --git a/content/docs/latest/deploy/virt-options/ovhcloud.md b/content/docs/latest/deploy/virt-options/ovhcloud.md index cf8be61b6..94eba5b8c 100644 --- a/content/docs/latest/deploy/virt-options/ovhcloud.md +++ b/content/docs/latest/deploy/virt-options/ovhcloud.md @@ -140,7 +140,7 @@ $ systemctl status nginx Now that you have a machine booted it is time to play around. Check out the [Flatcar Container Linux Quickstart][quickstart] guide or dig into [more specific topics][doc-index]. -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../../fb-provision/butane [doc-index]: ../../ [ovhcloud]: https://www.ovhcloud.com/en/ [ovhcloud-documentation-create]: https://help.ovhcloud.com/csm/en-public-cloud-compute-getting-started?id=kb_article_view&sysparm_article=KB0051009 diff --git a/content/docs/latest/deploy/virt-options/proxmoxve.md b/content/docs/latest/deploy/virt-options/proxmoxve.md index 198343be9..b417eb79f 100644 --- a/content/docs/latest/deploy/virt-options/proxmoxve.md +++ b/content/docs/latest/deploy/virt-options/proxmoxve.md @@ -120,7 +120,7 @@ qm set $VM_ID --cicustom "user=local:snippets/user-data" Now that you have a machine booted it is time to play around. Check out the [Flatcar Container Linux Quickstart][quickstart] guide or dig into [more specific topics][doc-index]. -[update-strategies]: ../../setup/releases/update-strategies +[update-strategies]: ../../updates-releases/releases/update-strategies [release-notes]: https://flatcar-linux.org/releases [quickstart]: ../ [doc-index]: ../../ diff --git a/content/docs/latest/deploy/virt-options/scaleway.md b/content/docs/latest/deploy/virt-options/scaleway.md index 19300892e..2b37f8185 100644 --- a/content/docs/latest/deploy/virt-options/scaleway.md +++ b/content/docs/latest/deploy/virt-options/scaleway.md @@ -113,7 +113,7 @@ Terraform examples are available here: https://github.com/flatcar/flatcar-terraf Kosmos is a Scaleway service that deploys a Kubernetes control plane on Scaleway and allows you to add nodes outside of Scaleway (other cloud providers, on-premise, etc.). At this moment, the Scaleway Node Agent used to join the existing cluster is not open-source and does not yet support immutable OS. A request has been made to support OS where Kubeadm and Kubelet would be already available in the path. -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../../fb-provision/butane [cli]: https://github.com/scaleway/scaleway-cli [doc-index]: ../../ [quickstart]: ../ diff --git a/content/docs/latest/deploy/virt-options/vultr.md b/content/docs/latest/deploy/virt-options/vultr.md index 08afe3e1b..18394b227 100644 --- a/content/docs/latest/deploy/virt-options/vultr.md +++ b/content/docs/latest/deploy/virt-options/vultr.md @@ -137,8 +137,8 @@ core@localhost ~ $ Now that you have a machine booted it is time to play around. Check out the [Flatcar Container Linux Quickstart][quickstart] guide or dig into [more specific topics][doc-index]. -[update-strategies]: ../../setup/releases/update-strategies +[update-strategies]: ../../updates-releases/releases/update-strategies [release-notes]: https://flatcar-linux.org/releases [quickstart]: ../ [doc-index]: ../../ -[booting-with-ipxe]: ../../installing/bare-metal/booting-with-ipxe +[booting-with-ipxe]: ../bare-metal/booting-with-ipxe diff --git a/content/docs/latest/devguide/sdk-disk-partitions.md b/content/docs/latest/devguide/sdk-disk-partitions.md index dd3261dde..15df148a1 100644 --- a/content/docs/latest/devguide/sdk-disk-partitions.md +++ b/content/docs/latest/devguide/sdk-disk-partitions.md @@ -24,7 +24,7 @@ Flatcar Container Linux is designed to be reliably updated via a continuous stre For more information, [read more about the disk layout][chromium disk format] used by Chromium and ChromeOS, which inspired the layout used by Flatcar Container Linux. -[OEM docs]: ../../installing/community-platforms/notes-for-distributors +[OEM docs]: ../deploy/virt-options/notes-for-distributors [chromium disk format]: https://www.chromium.org/chromium-os/developer-library/reference/device/disk-format/ ## Mounted filesystems @@ -54,7 +54,7 @@ The chosen partition is initially mounted at `/sysusr` by the initrd using [Flat The OEM partition is mounted at `/usr/share/oem`. -[manual rollback docs]: ../../setup/debug/manual-rollbacks +[manual rollback docs]: ../diagnostics/manual-rollbacks [GRUB patches]: https://github.com/flatcar/scripts/tree/main/sdk_container/src/third_party/coreos-overlay/coreos/user-patches/sys-boot/grub [supply chain docs]: ../supply-chain [verity hash code]: https://github.com/flatcar/scripts/blob/17ea3f2265df0c146b4b811eb9fad1abe35b21a2/build_library/build_image_util.sh#L820-L827 diff --git a/content/docs/latest/devguide/sdk-modifying-flatcar.md b/content/docs/latest/devguide/sdk-modifying-flatcar.md index 4f97b1ea1..72806c6a3 100644 --- a/content/docs/latest/devguide/sdk-modifying-flatcar.md +++ b/content/docs/latest/devguide/sdk-modifying-flatcar.md @@ -808,4 +808,4 @@ Take a look at the [SDK bootstrap process](sdk-bootstrapping) to learn how to bu [mantle]: https://github.com/flatcar/mantle [prodimages]: sdk-building-production-images [sdktips]: sdk-tips-and-tricks -[booting-qemu]: ../../installing/vms/qemu/#ssh-keys +[booting-qemu]: ../fb-provision/vms/qemu#ssh-keys diff --git a/content/docs/latest/diagnostics/btrfs-troubleshooting.md b/content/docs/latest/diagnostics/btrfs-troubleshooting.md index 9ff27dbe1..dea238945 100644 --- a/content/docs/latest/diagnostics/btrfs-troubleshooting.md +++ b/content/docs/latest/diagnostics/btrfs-troubleshooting.md @@ -4,9 +4,9 @@ linktitle: Troubleshooting btrfs description: Tips and tricks for solving issues related to btrfs on Flatcar. weight: 30 aliases: - - /docs/latest/setup/debug/btrfs-troubleshooting/ - - ../../os/btrfs-troubleshooting - - ../../clusters/debug/btrfs-troubleshooting + - /docs/latest/setup/debug/btrfs-troubleshooting/ + - ../../os/btrfs-troubleshooting + - ../../clusters/debug/btrfs-troubleshooting --- btrfs is a copy-on-write filesystem with full support in the upstream Linux kernel and several desirable features. In the past, Flatcar Container Linux shipped with a btrfs root filesystem to support Docker filesystem requirements at the time. As of version 561.0.0, Flatcar Container Linux ships with ext4 as the default root filesystem by default while still supporting Docker. Btrfs is still supported and works with the latest Flatcar Container Linux releases and Docker, but we recommend using ext4. @@ -80,7 +80,7 @@ Balance on '/' is running ## Adding a new physical disk -New physical disks can be added to an existing btrfs filesystem. The first step is to have the new block device [mounted on the machine](../storage/mounting-storage). Afterwards, let btrfs know about the new device and re-balance the file system. The key step here is re-balancing, which will move the data and metadata across both block devices. Expect this process to take some time: +New physical disks can be added to an existing btrfs filesystem. The first step is to have the new block device [mounted on the machine](../os-config/storage/mounting-storage). Afterwards, let btrfs know about the new device and re-balance the file system. The key step here is re-balancing, which will move the data and metadata across both block devices. Expect this process to take some time: ```shell btrfs device add /dev/sdc / diff --git a/content/docs/latest/diagnostics/reading-the-system-log.md b/content/docs/latest/diagnostics/reading-the-system-log.md index d371741d5..a10f5156d 100644 --- a/content/docs/latest/diagnostics/reading-the-system-log.md +++ b/content/docs/latest/diagnostics/reading-the-system-log.md @@ -3,8 +3,8 @@ title: Reading the system log description: How to use journalctl to understand what's going on. weight: 15 aliases: - - /docs/latest/setup/debug/reading-the-system-log/ - - ../../os/reading-the-system-log + - /docs/latest/setup/debug/reading-the-system-log/ + - ../../os/reading-the-system-log --- `journalctl` is your interface into a single machine's journal/logging. All service files insert data into the systemd journal. There are a few helpful commands to read the journal: @@ -42,6 +42,7 @@ Dec 22 12:32:39 localhost docker[9772]: apache2: Could not reliably determine th ## Read the user journal from the current user It might be required to add a user different from `core` user to the `systemd-journal` group to read the user journal. It can be done with this Butane config: + ```yaml variant: flatcar version: 1.0.0 @@ -131,9 +132,9 @@ systemd: ``` [drop-ins]: ../systemd/drop-in-units -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../fb-provision/butane ## More information -Getting Started with systemd -Network Configuration with networkd +Getting Started with systemd +Network Configuration with networkd diff --git a/content/docs/latest/fb-provision/butane/examples.md b/content/docs/latest/fb-provision/butane/examples.md index fce0dae85..32a61796c 100644 --- a/content/docs/latest/fb-provision/butane/examples.md +++ b/content/docs/latest/fb-provision/butane/examples.md @@ -229,5 +229,5 @@ This example creates a networkd unit to set the IP address on the `enp2s0` inter [spec]: ./configuration -[dropins]: ../../setup/systemd/drop-in-units -[networkd]: ../../setup/customization/network-config-with-networkd +[dropins]: ../../os-config/host-config/drop-in-units +[networkd]: ../../os-config/network/network-config-with-networkd diff --git a/content/docs/latest/fb-provision/butane/getting-started.md b/content/docs/latest/fb-provision/butane/getting-started.md index 529e50e66..b5b119c53 100644 --- a/content/docs/latest/fb-provision/butane/getting-started.md +++ b/content/docs/latest/fb-provision/butane/getting-started.md @@ -2,12 +2,11 @@ title: Getting Started weight: 10 aliases: - - /docs/latest/provisioning/config-transpiler/getting-started/ - - ../../container-linux-config-transpiler/doc/getting-started - - ../../container-linux-config-transpiler/getting-started + - /docs/latest/provisioning/config-transpiler/getting-started/ + - ../../container-linux-config-transpiler/doc/getting-started + - ../../container-linux-config-transpiler/getting-started --- - `butane` is a tool that will consume a Butane configuration and produce an Ignition configuration file that can be given to a Container Linux machine when it first boots to set the machine up. Using this config, a machine can be told to create users, format the root filesystem, set up the network, install systemd units, and more. Butane configuration are YAML files conforming to Butane's schema. For more information on the schema, take a look at [configuration][1]. @@ -53,9 +52,9 @@ While quite similar, there are some changes needed to migrate a Container Linux - File entries can't specify filesystems anymore as was done with `filesystem: root` or `filesystem: oem`. Instead, they use the full path, and which filesystem this is depends on whether and how the initrd mount path is set for each specified filesystem. - Units only have the `enabled` field, support for `enable` got removed. -[1]: ../config-transpiler/configuration +[1]: ../butane/configuration [2]: https://coreos.github.io/ignition/supported-platforms/ [3]: https://coreos.github.io/butane/examples/ [4]: https://github.com/coreos/butane/releases [dynamic]: ../ignition/dynamic-data/ -[cluster]: ../../setup/clusters/ +[cluster]: ../../orchestrate/clusters/ diff --git a/content/docs/latest/fb-provision/cl-config/_index.md b/content/docs/latest/fb-provision/cl-config/_index.md index 6ea8dd1a9..df1d31b49 100644 --- a/content/docs/latest/fb-provision/cl-config/_index.md +++ b/content/docs/latest/fb-provision/cl-config/_index.md @@ -3,11 +3,11 @@ title: "[DEPRECATED / EOL] Container Linux Config Transpiler" description: YAML configuration format used to generate Ignition configs. weight: 45 aliases: - - ../os/provisioning - - ../reference/migrating-to-clcs/provisioning + - ../os/provisioning + - ../reference/migrating-to-clcs/provisioning --- -:warning: TL; DR: Use [Butane](../config-transpiler). While Flatcar does support both Ignition spec version (2.x and 3.x), we encourage folks to use [Butane](../config-transpiler) first but we still maintain / document backward compatibility for users who still rely on Ignition 2.x. :warning: +:warning: TL; DR: Use [Butane](../butane). While Flatcar does support both Ignition spec version (2.x and 3.x), we encourage folks to use [Butane](../butane) first but we still maintain / document backward compatibility for users who still rely on Ignition 2.x. :warning: Flatcar Container Linux automates machine provisioning with a specialized system for applying initial configuration. This system implements a process of (trans)compilation and validation for machine configs, and an atomic service to apply validated configurations to machines. @@ -34,16 +34,16 @@ Use variable replacement to configure the etcd service with the provisioning tar ```yaml etcd: - advertise_client_urls: http://{PUBLIC_IPV4}:2379 + advertise_client_urls: http://{PUBLIC_IPV4}:2379 initial_advertise_peer_urls: http://{PRIVATE_IPV4}:2380 - listen_client_urls: http://0.0.0.0:2379 - listen_peer_urls: http://{PRIVATE_IPV4}:2380 - discovery: https://discovery.etcd.io/ + listen_client_urls: http://0.0.0.0:2379 + listen_peer_urls: http://{PRIVATE_IPV4}:2380 + discovery: https://discovery.etcd.io/ ``` `PUBLIC_IPV4` and `PRIVATE_IPV4` are automatically populated from the environment in which Flatcar Container Linux runs, if this metadata exists. Given the many different environments in which Flatcar Container Linux can run, it's difficult if not impossible to accurately determine these variables in every instance. Be certain to check this value as a troubleshooting measure. -For example, the default metadata for an EC2 environment would be used: `public_ipv4` and `local_ipv4`. On Azure, *either* the virtual IP or public IP could be used for the `PUBLIC_IPV4` (`ct` makes a best guess and uses the virtual IP, but this could change in the future), and the dynamic IP would be used for the `PRIVATE_IPV4`. On bare metal, this information cannot be reliably derived in a general manner, so these variables cannot be used. +For example, the default metadata for an EC2 environment would be used: `public_ipv4` and `local_ipv4`. On Azure, _either_ the virtual IP or public IP could be used for the `PUBLIC_IPV4` (`ct` makes a best guess and uses the virtual IP, but this could change in the future), and the dynamic IP would be used for the `PRIVATE_IPV4`. On bare metal, this information cannot be reliably derived in a general manner, so these variables cannot be used. Because variable expansion is unpredictable and complex, and because it is also common for users to inadvertently write invalid configs, the use of a transformation tool is strongly encouraged. The default tool recommended for this task is the [Config Transpiler][ct] (ct for short). The Config Transpiler will validate and transform a Container Linux Config into the format that Flatcar Container Linux can consume: the Ignition Config. @@ -67,11 +67,11 @@ The following config will configure an etcd cluster using the machine's public a ```yaml etcd: - advertise_client_urls: http://{PUBLIC_IPV4}:2379 + advertise_client_urls: http://{PUBLIC_IPV4}:2379 initial_advertise_peer_urls: http://{PRIVATE_IPV4}:2380 - listen_client_urls: http://0.0.0.0:2379 - listen_peer_urls: http://{PRIVATE_IPV4}:2380 - discovery: https://discovery.etcd.io/ + listen_client_urls: http://0.0.0.0:2379 + listen_peer_urls: http://{PRIVATE_IPV4}:2380 + discovery: https://discovery.etcd.io/ ``` As suggested earlier, `ct` requires information about the target environment before it can transform configs which use templating. If this config is passed to `ct` without any other arguments, `ct` fails with the following error message: @@ -81,7 +81,7 @@ $ ct < example.yml error: platform must be specified to use templating ``` -This message states that because the config takes advantage of templating (in this case, `PUBLIC_IPV4`), `ct` must be invoked with the `--platform` argument. This extra information is used by `ct` to make the platform-specific customizations necessary. Keeping the Container Linux Config and the invocation arguments separate allows the Container Linux Config to remain largely platform independent. +This message states that because the config takes advantage of templating (in this case, `PUBLIC_IPV4`), `ct` must be invoked with the `--platform` argument. This extra information is used by `ct` to make the platform-specific customizations necessary. Keeping the Container Linux Config and the invocation arguments separate allows the Container Linux Config to remain largely platform independent. CT can be invoked again and given Amazon EC2 as an example: @@ -96,14 +96,18 @@ This time, `ct` successfully runs and produces the following Ignition Config: { "ignition": { "version": "2.0.0" }, "systemd": { - "units": [{ - "name": "etcd-member.service", - "enable": true, - "dropins": [{ - "name": "20-clct-etcd-member.conf", - "contents": "[Unit]\nRequires=coreos-metadata.service\nAfter=coreos-metadata.service\n\n[Service]\nEnvironmentFile=/run/metadata/coreos\nExecStart=\nExecStart=/usr/lib/flatcar/etcd-wrapper $ETCD_OPTS \\\n --listen-peer-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2380\" \\\n --listen-client-urls=\"http://0.0.0.0:2379\" \\\n --initial-advertise-peer-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2380\" \\\n --advertise-client-urls=\"http://${COREOS_EC2_IPV4_PUBLIC}:2379\" \\\n --discovery=\"https://discovery.etcd.io/\u003ctoken\u003e\"" - }] - }] + "units": [ + { + "name": "etcd-member.service", + "enable": true, + "dropins": [ + { + "name": "20-clct-etcd-member.conf", + "contents": "[Unit]\nRequires=coreos-metadata.service\nAfter=coreos-metadata.service\n\n[Service]\nEnvironmentFile=/run/metadata/coreos\nExecStart=\nExecStart=/usr/lib/flatcar/etcd-wrapper $ETCD_OPTS \\\n --listen-peer-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2380\" \\\n --listen-client-urls=\"http://0.0.0.0:2379\" \\\n --initial-advertise-peer-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2380\" \\\n --advertise-client-urls=\"http://${COREOS_EC2_IPV4_PUBLIC}:2379\" \\\n --discovery=\"https://discovery.etcd.io/\u003ctoken\u003e\"" + } + ] + } + ] } } ``` @@ -138,9 +142,9 @@ For a [number of reasons][vs], coreos-cloudinit has been deprecated in favor of Now that the basics of Container Linux Configs have been covered, a good next step is to read through the [examples][examples] and start experimenting. The [troubleshooting guide][troubleshooting] is a good reference for debugging issues. -[clc]: ../config-transpiler/configuration +[clc]: ../butane/configuration [cloudinit]: https://github.com/kinvolk/coreos-cloudinit -[ct]: ../config-transpiler/ +[ct]: ../butane/ [download-ct]: https://github.com/flatcar/container-linux-config-transpiler/releases [etcd]: https://github.com/etcd-io/etcd [examples]: examples diff --git a/content/docs/latest/fb-provision/cl-config/dynamic-data.md b/content/docs/latest/fb-provision/cl-config/dynamic-data.md index 57491d142..037b45d7a 100644 --- a/content/docs/latest/fb-provision/cl-config/dynamic-data.md +++ b/content/docs/latest/fb-provision/cl-config/dynamic-data.md @@ -79,7 +79,7 @@ etcd: initial_cluster: "{HOSTNAME}=http://{PRIVATE_IPV4}:2380" ``` -You can find another example in the [VMware docs](../../installing/cloud/vmware.md). +You can find another example in the [VMware docs](../../deploy/cloud/vmware.md). ## Behind the scenes diff --git a/content/docs/latest/fb-provision/cl-config/examples.md b/content/docs/latest/fb-provision/cl-config/examples.md index ccb9fa2a1..a3fba62ad 100644 --- a/content/docs/latest/fb-provision/cl-config/examples.md +++ b/content/docs/latest/fb-provision/cl-config/examples.md @@ -3,8 +3,8 @@ title: Container Linux Config Examples linktitle: Examples weight: 20 aliases: - - ../../container-linux-config-transpiler/doc/examples - - ../../container-linux-config-transpiler/examples + - ../../container-linux-config-transpiler/doc/examples + - ../../container-linux-config-transpiler/examples --- Here you can find a bunch of simple examples for using Container Linux configs, with some explanations about what they do. The examples here are in no way comprehensive, for a full list of all the available fields check out the [config-transpiler specification][spec]. @@ -72,7 +72,7 @@ python -c "import crypt,random,string; print(crypt.crypt(input('clear-text passw perl -e 'print crypt("password","\$6\$SALT\$") . "\n"' ``` -Using a higher number of rounds will help create more secure passwords, but given enough time, password hashes can be reversed. On most RPM based distributions there is a tool called mkpasswd available in the `expect` package, but this does not handle "rounds" nor advanced hashing algorithms. +Using a higher number of rounds will help create more secure passwords, but given enough time, password hashes can be reversed. On most RPM based distributions there is a tool called mkpasswd available in the `expect` package, but this does not handle "rounds" nor advanced hashing algorithms. ## Storage and files @@ -182,13 +182,13 @@ This example creates a networkd unit to set the IP address on the `enp2s0` inter ```yaml etcd: - version: "3.0.15" - name: "{HOSTNAME}" - advertise_client_urls: "http://{PRIVATE_IPV4}:2379" + version: "3.0.15" + name: "{HOSTNAME}" + advertise_client_urls: "http://{PRIVATE_IPV4}:2379" initial_advertise_peer_urls: "http://{PRIVATE_IPV4}:2380" - listen_client_urls: "http://0.0.0.0:2379" - listen_peer_urls: "http://{PRIVATE_IPV4}:2380" - initial_cluster: "{HOSTNAME}=http://{PRIVATE_IPV4}:2380" + listen_client_urls: "http://0.0.0.0:2379" + listen_peer_urls: "http://{PRIVATE_IPV4}:2380" + initial_cluster: "{HOSTNAME}=http://{PRIVATE_IPV4}:2380" ``` This example will create a dropin for the `etcd-member` systemd unit, configuring it to use the specified version and adding all the specified options. This will also enable the `etcd-member` unit. @@ -199,16 +199,16 @@ This is referencing dynamic data that isn't known until an instance is booted. F ```yaml update: - group: "beta" + group: "beta" locksmith: reboot_strategy: "etcd-lock" - window_start: "Sun 1:00" - window_length: "2h" + window_start: "Sun 1:00" + window_length: "2h" ``` This example configures the Container Linux instance to be a member of the beta group, configures locksmithd to acquire a lock in etcd before rebooting for an update, and only allows reboots during a 2 hour window starting at 1 AM on Sundays. -[spec]: ../config-transpiler/configuration -[dropins]: ../../setup/systemd/drop-in-units -[networkd]: ../../setup/customization/network-config-with-networkd +[spec]: ../butane/configuration +[dropins]: ../../os-config/host-config/drop-in-units +[networkd]: ../../os-config/network/network-config-with-networkd [dynamic-data]: ../dynamic-data diff --git a/content/docs/latest/fb-provision/cl-config/from-cloud-config.md b/content/docs/latest/fb-provision/cl-config/from-cloud-config.md index 38ae4d628..49f05a243 100644 --- a/content/docs/latest/fb-provision/cl-config/from-cloud-config.md +++ b/content/docs/latest/fb-provision/cl-config/from-cloud-config.md @@ -3,9 +3,9 @@ title: Migrating from cloud-config to Container Linux Config linktitle: Migrating from cloud-config weight: 40 aliases: - - ../../os/migrating-to-clcs - - ../../reference/migrating-to-clcs - - migrating-to-clcs + - ../../os/migrating-to-clcs + - ../../reference/migrating-to-clcs + - migrating-to-clcs --- Flatcar Container Linux started as a fork of CoreOS Container Linux. Historically, the recommended way to provision a CoreOS Container Linux machine was with a cloud-config. This was a YAML file specifying things like systemd units to run, users that should exist, and files that should be written. This file would be given to a CoreOS Container Linux machine, and saved on disk. Then a utility called coreos-cloudinit running in a systemd unit would read this file, look at the system state, and make necessary changes on every boot. @@ -27,11 +27,11 @@ In a cloud-config, etcd version 2 can be enabled and configured by using the `co coreos: etcd2: - discovery: "https://discovery.etcd.io/" - advertise-client-urls: "http://$public_ipv4:2379" + discovery: "https://discovery.etcd.io/" + advertise-client-urls: "http://$public_ipv4:2379" initial-advertise-peer-urls: "http://$private_ipv4:2380" - listen-client-urls: "http://0.0.0.0:2379,http://0.0.0.0:4001" - listen-peer-urls: "http://$private_ipv4:2380,http://$private_ipv4:7001" + listen-client-urls: "http://0.0.0.0:2379,http://0.0.0.0:4001" + listen-peer-urls: "http://$private_ipv4:2380,http://$private_ipv4:7001" ``` etcd can be configured in a more general way with a Container Linux Config. This CL Config will use the etcd-member.service systemd unit rather than the etcd2 service understood by cloud-config and coreos-cloudinit. The etcd-member service will download a version of etcd of the user's choosing and run it. This means that in a Container Linux Config both etcd v2 and v3 can be configured. @@ -40,7 +40,7 @@ This is done under the etcd section: ```yaml etcd: - version: 3.1.6 + version: 3.1.6 ``` Omitting the version specification declares that the unit file should use the version of etcd matching the running version of Flatcar Container Linux. @@ -49,12 +49,12 @@ Configuration options in this section can be provided the same way as they were ```yaml etcd: - name: "{HOSTNAME}" - advertise_client_urls: "{PRIVATE_IPV4}:2379" + name: "{HOSTNAME}" + advertise_client_urls: "{PRIVATE_IPV4}:2379" initial_advertise_peer_urls: "{PRIVATE_IPV4}:2380" - listen_client_urls: "http://0.0.0.0:2379" - listen_peer_urls: "http://{PRIVATE_IPV4}:2380" - initial_cluster: "%m=http://{PRIVATE_IPV4}:2380" + listen_client_urls: "http://0.0.0.0:2379" + listen_peer_urls: "http://{PRIVATE_IPV4}:2380" + initial_cluster: "%m=http://{PRIVATE_IPV4}:2380" ``` ## flannel @@ -66,14 +66,14 @@ Flannel is easily configurable in a cloud-config the same way etcd is, by using coreos: flannel: - etcd_prefix: "/coreos.com/network2" + etcd_prefix: "/coreos.com/network2" ``` The flannel section in a Container Linux Config is used the same way, and a version can optionally be specified for flannel as well. ```yaml flannel: - version: 0.7.0 + version: 0.7.0 etcd_prefix: "/coreos.com/network2" ``` @@ -86,7 +86,7 @@ The `coreos.locksmith.*` section in a cloud-config can be used to configure the coreos: locksmith: - endpoint: "http://example.com:2379" + endpoint: "http://example.com:2379" ``` Locksmith can be configured in the same way under the locksmith section of a Container Linux Config, but some of the accepted options are slightly different. Also the reboot strategy is set in the locksmith section, instead of the update section. Check out the [Container Linux Config schema][ct-config] to see what options are available. @@ -94,7 +94,7 @@ Locksmith can be configured in the same way under the locksmith section of a Con ```yaml locksmith: reboot_strategy: "reboot" - etcd_endpoints: "http://example.com:2379" + etcd_endpoints: "http://example.com:2379" ``` ## update @@ -106,15 +106,15 @@ The `coreos.update.*` section can be used to configure the reboot strategy, upda coreos: update: reboot-strategy: "etcd-lock" - group: "stable" - server: "https://public.update.flatcar-linux.net/v1/update/" + group: "stable" + server: "https://public.update.flatcar-linux.net/v1/update/" ``` In the update section in a Container Linux Config the group and server can be configured, but the reboot-strategy option has been moved under the locksmith section. ```yaml update: - group: "stable" + group: "stable" server: "https://public.update.flatcar-linux.net/v1/update/" ``` @@ -250,8 +250,8 @@ The Container Linux Config is intentionally more generalized than a cloud-config storage: files: - filesystem: "root" - path: "/etc/hostname" - mode: 0644 + path: "/etc/hostname" + mode: 0644 contents: inline: coreos1 ``` @@ -278,7 +278,7 @@ This same information can be added to the Container Linux Config in the `passwd. ```yaml passwd: users: - - name: "elroy" + - name: "elroy" password_hash: "$6$5s2u6/jR$un0AvWnqilcgaNB3Mkxd5yYv6mTlWfOoCYHZmfi3LDKVltj.E8XNKEcwWm..." ssh_authorized_keys: - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC0g+ZTxC7weoIJLUafOgrm+h..." @@ -294,9 +294,9 @@ The `write_files` section in a cloud-config can be used to specify files and the ```yaml #cloud-config write_files: - - path: "/etc/resolv.conf" + - path: "/etc/resolv.conf" permissions: "0644" - owner: "root" + owner: "root" content: | nameserver 8.8.8.8 ``` @@ -307,8 +307,8 @@ This can be done in a Container Linux Config with the `storage.files.*` section. storage: files: - filesystem: "root" - path: "/etc/resolv.conf" - mode: 0644 + path: "/etc/resolv.conf" + mode: 0644 contents: inline: | nameserver 8.8.8.8 @@ -334,8 +334,8 @@ There is no analogous section in a Container Linux Config, however the `/etc/hos storage: files: - filesystem: "root" - path: "/etc/hosts" - mode: 0644 + path: "/etc/hosts" + mode: 0644 contents: inline: | 127.0.0.1 localhost @@ -345,5 +345,5 @@ storage: [provisioning]: _index.md [dynamic-data]: ../dynamic-data -[ct-config]: ../config-transpiler/configuration +[ct-config]: ../butane/configuration [ignition]: ../ignition diff --git a/content/docs/latest/fb-provision/cl-config/operators-notes.md b/content/docs/latest/fb-provision/cl-config/operators-notes.md index 818b782ae..1de765e63 100644 --- a/content/docs/latest/fb-provision/cl-config/operators-notes.md +++ b/content/docs/latest/fb-provision/cl-config/operators-notes.md @@ -17,4 +17,4 @@ The Config Transpiler supports several aliases for GPT partition type GUIDs. The | `swap_partition` | `0657fd6d-a4ab-43c4-84e5-0933c84b4f4f` | | `raid_partition` | `a19d880f-05fc-4d3b-a006-743f0f84911e` | -See the [Using RAID for the Root Filesystem](../../setup/storage/raid/) documentation for when to use `raid_containing_root`. +See the [Using RAID for the Root Filesystem](../../os-config/storage/raid/) documentation for when to use `raid_containing_root`. diff --git a/content/docs/latest/fb-provision/customize-image/customize-the-image.md b/content/docs/latest/fb-provision/customize-image/customize-the-image.md index dbecbce73..739f635d7 100644 --- a/content/docs/latest/fb-provision/customize-image/customize-the-image.md +++ b/content/docs/latest/fb-provision/customize-image/customize-the-image.md @@ -130,4 +130,4 @@ Another problem are the generated SSH host keys which you have to delete, otherw More problems come with weak account credentials used for the setup, e.g., when you have a dummy account with a password you have to remove the account again, and if you set up dummy SSH keys for the `core` user as common with Vagrant, you have to remove them, too. If for bootstrapping you used a `config.ign` file in the OEM partition, this, too, has to be removed. You can have a look at the [`image-builder`](https://github.com/kubernetes-sigs/image-builder) Packer and Ansible configuration which avoids most of the common pitfalls but, again, this is not a complete list because it depends on the software components you interact with. -[ignition]: ../../provisioning/ignition +[ignition]: ../ignition diff --git a/content/docs/latest/fb-provision/ignition/dynamic-data.md b/content/docs/latest/fb-provision/ignition/dynamic-data.md index f6511b4a0..d52f078a7 100644 --- a/content/docs/latest/fb-provision/ignition/dynamic-data.md +++ b/content/docs/latest/fb-provision/ignition/dynamic-data.md @@ -76,7 +76,7 @@ systemd: WantedBy=multi-user.target ``` -You can find another example in the [VMware docs](../../installing/cloud/vmware.md). +You can find another example in the [VMware docs](../../deploy/cloud/vmware.md). [afterburndocs]: https://github.com/coreos/afterburn/blob/main/docs/usage/attributes.md#metadata-attributes diff --git a/content/docs/latest/fb-provision/ignition/specification.md b/content/docs/latest/fb-provision/ignition/specification.md index adfedbb7a..503396cbe 100644 --- a/content/docs/latest/fb-provision/ignition/specification.md +++ b/content/docs/latest/fb-provision/ignition/specification.md @@ -3,19 +3,19 @@ title: Ignition Specification linktitle: Specification weight: 30 aliases: - - /docs/latest/provisioning/ignition/specification/ + - /docs/latest/provisioning/ignition/specification/ --- Ignition uses a JSON format that is specified in several major versions: v1, v2 and v3 (which itself has minor versions like `2.3.0`). While v1 and v2 are still supported in Flatcar Container Linux, from version 3185.0.0, it's recommended to write new configuration with v3. - ## Ignition v3 Starting from release 3185.0.0, Ignition v3 (specification 3.3.0) is supported in addition of Ignition v2. There are some things to be aware of: -* v1 and v2 are still supported and get translated at runtime; while this is tested well there may be corner cases where the v2 config relied on unspecified behavior -* `clevis` is not supported -* `kernelArguments` are supported and will persist the changes in `/usr/share/oem/grub.cfg` before the reboot but it only works for unconditional `set linux_append` statements in grub.cfg and `linux_console` is not considered -* The high-level [Butane YAML format][butane-spec] can be used to generate Ignition v3 configs: + +- v1 and v2 are still supported and get translated at runtime; while this is tested well there may be corner cases where the v2 config relied on unspecified behavior +- `clevis` is not supported +- `kernelArguments` are supported and will persist the changes in `/usr/share/oem/grub.cfg` before the reboot but it only works for unconditional `set linux_append` statements in grub.cfg and `linux_console` is not considered +- The high-level [Butane YAML format][butane-spec] can be used to generate Ignition v3 configs: ```bash cat > config.yml < ignition.json ``` -* **ignition** (object): metadata about the configuration itself. - * **version** (string): the semantic version number of the spec. The spec version must be compatible with the latest version (`3.3.0`). Compatibility requires the major versions to match and the spec version be less than or equal to the latest version. `-experimental` versions compare less than the final version with the same number, and previous experimental versions are not accepted. - * **_config_** (objects): options related to the configuration. - * **_merge_** (list of objects): a list of the configs to be merged to the current config. - * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. - * **_compression_** (string): the type of compression used on the config (null or gzip). Compression cannot be used with S3. - * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. - * **name** (string): the header name. - * **_value_** (string): the header contents. - * **_verification_** (object): options related to the verification of the config. - * **_hash_** (string): the hash of the config, in the form `-` where type is either `sha512` or `sha256`. - * **_replace_** (object): the config that will replace the current. - * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. - * **_compression_** (string): the type of compression used on the config (null or gzip). Compression cannot be used with S3. - * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. - * **name** (string): the header name. - * **_value_** (string): the header contents. - * **_verification_** (object): options related to the verification of the config. - * **_hash_** (string): the hash of the config, in the form `-` where type is either `sha512` or `sha256`. - * **_timeouts_** (object): options relating to `http` timeouts when fetching files over `http` or `https`. - * **_httpResponseHeaders_** (integer) the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds. - * **_httpTotal_** (integer) the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0. - * **_security_** (object): options relating to network security. - * **_tls_** (object): options relating to TLS when fetching resources over `https`. - * **_certificateAuthorities_** (list of objects): the list of additional certificate authorities (in addition to the system authorities) to be used for TLS verification when fetching over `https`. All certificate authorities must have a unique `source`. - * **source** (string): the URL of the certificate bundle (in PEM format). The bundle can contain multiple concatenated certificates. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. - * **_compression_** (string): the type of compression used on the certificate (null or gzip). Compression cannot be used with S3. - * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. - * **name** (string): the header name. - * **_value_** (string): the header contents. - * **_verification_** (object): options related to the verification of the certificate. - * **_hash_** (string): the hash of the certificate, in the form `-` where type is either `sha512` or `sha256`. - * **_proxy_** (object): options relating to setting an `HTTP(S)` proxy when fetching resources. - * **_httpProxy_** (string): will be used as the proxy URL for HTTP requests unless overridden by `noProxy`. - * **_httpsProxy_** (string): will be used as the proxy URL for HTTPS requests unless overridden by `noProxy`. - * **_noProxy_** (list of strings): specifies a list of strings to hosts that should be excluded from proxying. Each value is represented by an `IP address prefix (1.2.3.4)`, `an IP address prefix in CIDR notation (1.2.3.4/8)`, `a domain name`, or `a special DNS label (*)`. An IP address prefix and domain name can also include a literal port number `(1.2.3.4:80)`. A domain name matches that name and all subdomains. A domain name with a leading `.` matches subdomains only. For example `foo.com` matches `foo.com` and `bar.foo.com`; `.y.com` matches `x.y.com` but not `y.com`. A single asterisk `(*)` indicates that no proxying should be done. -* **_storage_** (object): describes the desired state of the system's storage devices. - * **_disks_** (list of objects): the list of disks to be configured and their options. Every entry must have a unique `device`. - * **device** (string): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. - * **_wipeTable_** (boolean): whether or not the partition tables shall be wiped. When true, the partition tables are erased before any further manipulation. Otherwise, the existing entries are left intact. - * **_partitions_** (list of objects): the list of partitions and their configuration for this particular disk. Every partition must have a unique `number`, or if 0 is specified, a unique `label`. - * **_label_** (string): the PARTLABEL for the partition. - * **_number_** (integer): the partition number, which dictates its position in the partition table (one-indexed). If zero, use the next available partition slot. - * **_sizeMiB_** (integer): the size of the partition (in mebibytes). If zero, the partition will be made as large as possible. - * **_startMiB_** (integer): the start of the partition (in mebibytes). If zero, the partition will be positioned at the start of the largest block available. - * **_typeGuid_** (string): the GPT [partition type GUID][part-types]. If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). - * **_guid_** (string): the GPT unique partition GUID. - * **_wipePartitionEntry_** (boolean) if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. - * **_shouldExist_** (boolean) whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. - * **_resize_** (boolean) whether or not the existing partition should be resized. If omitted, it defaults to false. If true, Ignition will resize an existing partition if it matches the config in all respects except the partition size. - * **_raid_** (list of objects): the list of RAID arrays to be configured. Every RAID array must have a unique `name`. - * **name** (string): the name to use for the resulting md device. - * **level** (string): the redundancy level of the array (e.g. linear, raid1, raid5, etc.). - * **devices** (list of strings): the list of devices (referenced by their absolute path) in the array. - * **_spares_** (integer): the number of spares (if applicable) in the array. - * **_options_** (list of strings): any additional options to be passed to mdadm. - * **_filesystems_** (list of objects): the list of filesystems to be configured. `device` and `format` need to be specified. Every filesystem must have a unique `device`. - * **device** (string): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. - * **format** (string): the filesystem format (ext4, btrfs, xfs, vfat, swap, or none). - * **_path_** (string): the mount-point of the filesystem while Ignition is running relative to where the root filesystem will be mounted. This is not necessarily the same as where it should be mounted in the real root, but it is encouraged to make it the same. - * **_wipeFilesystem_** (boolean): whether or not to wipe the device before filesystem creation, see [the documentation on filesystems][ignition-fs-reuse] for more information. Defaults to false. - * **_label_** (string): the label of the filesystem. - * **_uuid_** (string): the uuid of the filesystem. - * **_options_** (list of strings): any additional options to be passed to the format-specific mkfs utility. - * **_mountOptions_** (list of strings): any special options to be passed to the mount command. - * **_files_** (list of objects): the list of files to be written. Every file, directory and link must have a unique `path`. - * **path** (string): the absolute path to the file. - * **_overwrite_** (boolean): whether to delete preexisting nodes at the path. `contents.source` must be specified if `overwrite` is true. Defaults to false. - * **_contents_** (object): options related to the contents of the file. - * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created. - * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. - * **name** (string): the header name. - * **_value_** (string): the header contents. - * **_verification_** (object): options related to the verification of the file contents. - * **_hash_** (string): the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. - * **_append_** (list of objects): list of contents to be appended to the file. Follows the same stucture as `contents` - * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. - * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. - * **name** (string): the header name. - * **_value_** (string): the header contents. - * **_verification_** (object): options related to the verification of the appended contents. - * **_hash_** (string): the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. - * **_mode_** (integer): the file's permission mode. Note that the mode must be properly specified as a **decimal** value (i.e. 0644 -> 420). If not specified, the permission mode for files defaults to 0644 or the existing file's permissions if `overwrite` is false, `contents.source` is unspecified, and a file already exists at the path. - * **_user_** (object): specifies the file's owner. - * **_id_** (integer): the user ID of the owner. - * **_name_** (string): the user name of the owner. - * **_group_** (object): specifies the group of the owner. - * **_id_** (integer): the group ID of the owner. - * **_name_** (string): the group name of the owner. - * **_directories_** (list of objects): the list of directories to be created. Every file, directory, and link must have a unique `path`. - * **path** (string): the absolute path to the directory. - * **_overwrite_** (boolean): whether to delete preexisting nodes at the path. If false and a directory already exists at the path, Ignition will only set its permissions. If false and a non-directory exists at that path, Ignition will fail. Defaults to false. - * **_mode_** (integer): the directory's permission mode. Note that the mode must be properly specified as a **decimal** value (i.e. 0755 -> 493). If not specified, the permission mode for directories defaults to 0755 or the mode of an existing directory if `overwrite` is false and a directory already exists at the path. - * **_user_** (object): specifies the directory's owner. - * **_id_** (integer): the user ID of the owner. - * **_name_** (string): the user name of the owner. - * **_group_** (object): specifies the group of the owner. - * **_id_** (integer): the group ID of the owner. - * **_name_** (string): the group name of the owner. - * **_links_** (list of objects): the list of links to be created. Every file, directory, and link must have a unique `path`. - * **path** (string): the absolute path to the link - * **_overwrite_** (boolean): whether to delete preexisting nodes at the path. If overwrite is false and a matching link exists at the path, Ignition will only set the owner and group. Defaults to false. - * **_user_** (object): specifies the symbolic link's owner. - * **_id_** (integer): the user ID of the owner. - * **_name_** (string): the user name of the owner. - * **_group_** (object): specifies the group of the owner. - * **_id_** (integer): the group ID of the owner. - * **_name_** (string): the group name of the owner. - * **target** (string): the target path of the link - * **_hard_** (boolean): a symbolic link is created if this is false, a hard one if this is true. - * **_luks_** (list of objects): the list of luks devices to be created. Every device must have a unique `name`. - * **name** (string): the name of the luks device. - * **device** (string): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. - * **_keyFile_** (string): options related to the contents of the key file. - * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. - * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. - * **name** (string): the header name. - * **_value_** (string): the header contents. - * **_verification_** (object): options related to the verification of the key file. - * **_hash_** (string): the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. - * **_label_** (string): the label of the luks device. - * **_uuid_** (string): the uuid of the luks device. - * **_options_** (list of strings): any additional options to be passed to the cryptsetup utility. - * **_wipeVolume_** (boolean): whether or not to wipe the device before volume creation, see [the documentation on filesystems][ignition-fs-reuse] for more information. - * **_clevis_** (object): describes the clevis configuration for the luks device. - * **_tang_** (list of objects): describes a tang server. Every server must have a unique `url`. - * **url** (string): url of the tang server. - * **thumbprint** (string): thumbprint of a trusted signing key. - * **_tpm2_** (bool): whether or not to use a tpm2 device. - * **_threshold_** (int): sets the minimum number of pieces required to decrypt the device. Default is 1. - * **_custom_** (object): overrides the clevis configuration. The `pin` & `config` will be passed directly to `clevis luks bind`. If specified, all other clevis options must be omitted. - * **pin** (string): the clevis pin. - * **config** (string): the clevis configuration JSON. - * **_needsNetwork_** (bool): whether or not the device requires networking. -* **_systemd_** (object): describes the desired state of the systemd units. - * **_units_** (list of objects): the list of systemd units. Every unit must have a unique `name`. - * **name** (string): the name of the unit. This must be suffixed with a valid unit type (e.g. "thing.service"). - * **_enabled_** (boolean): whether or not the service shall be enabled. When true, the service is enabled. When false, the service is disabled. When omitted, the service is unmodified. In order for this to have any effect, the unit must have an install section. - * **_mask_** (boolean): whether or not the service shall be masked. When true, the service is masked by symlinking it to `/dev/null`. When false, the service is unmasked by deleting the symlink to `/dev/null` if it exists. - * **_contents_** (string): the contents of the unit. - * **_dropins_** (list of objects): the list of drop-ins for the unit. Every drop-in must have a unique `name`. - * **name** (string): the name of the drop-in. This must be suffixed with ".conf". - * **_contents_** (string): the contents of the drop-in. -* **_passwd_** (object): describes the desired additions to the passwd database. - * **_users_** (list of objects): the list of accounts that shall exist. All users must have a unique `name`. - * **name** (string): the username for the account. - * **_passwordHash_** (string): the encrypted password for the account. - * **_sshAuthorizedKeys_** (list of strings): a list of SSH keys to be added as an SSH key fragment at `.ssh/authorized_keys.d/ignition` in the user's home directory. All SSH keys must be unique. - * **_uid_** (integer): the user ID of the account. - * **_gecos_** (string): the GECOS field of the account. - * **_homeDir_** (string): the home directory of the account. - * **_noCreateHome_** (boolean): whether or not to create the user's home directory. This only has an effect if the account doesn't exist yet. - * **_primaryGroup_** (string): the name of the primary group of the account. - * **_groups_** (list of strings): the list of supplementary groups of the account. - * **_noUserGroup_** (boolean): whether or not to create a group with the same name as the user. This only has an effect if the account doesn't exist yet. - * **_noLogInit_** (boolean): whether or not to add the user to the lastlog and faillog databases. This only has an effect if the account doesn't exist yet. - * **_shell_** (string): the login shell of the new account. - * **_shouldExist_** (boolean) whether or not the user with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified user. - * **_system_** (bool): whether or not this account should be a system account. This only has an effect if the account doesn't exist yet. - * **_groups_** (list of objects): the list of groups to be added. All groups must have a unique `name`. - * **name** (string): the name of the group. - * **_gid_** (integer): the group ID of the new group. - * **_passwordHash_** (string): the encrypted password of the new group. - * **_shouldExist_** (boolean) whether or not the group with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified group. - * **_system_** (bool): whether or not the group should be a system group. This only has an effect if the group doesn't exist yet. -* **_kernelArguments_** (object): describes the desired kernel arguments. - * **_shouldExist_** (list of strings): the list of kernel arguments that should exist. - * **_shouldNotExist_** (list of strings): the list of kernel arguments that should not exist. +- **ignition** (object): metadata about the configuration itself. + - **version** (string): the semantic version number of the spec. The spec version must be compatible with the latest version (`3.3.0`). Compatibility requires the major versions to match and the spec version be less than or equal to the latest version. `-experimental` versions compare less than the final version with the same number, and previous experimental versions are not accepted. + - **_config_** (objects): options related to the configuration. + - **_merge_** (list of objects): a list of the configs to be merged to the current config. + - **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + - **_compression_** (string): the type of compression used on the config (null or gzip). Compression cannot be used with S3. + - **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. + - **name** (string): the header name. + - **_value_** (string): the header contents. + - **_verification_** (object): options related to the verification of the config. + - **_hash_** (string): the hash of the config, in the form `-` where type is either `sha512` or `sha256`. + - **_replace_** (object): the config that will replace the current. + - **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + - **_compression_** (string): the type of compression used on the config (null or gzip). Compression cannot be used with S3. + - **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. + - **name** (string): the header name. + - **_value_** (string): the header contents. + - **_verification_** (object): options related to the verification of the config. + - **_hash_** (string): the hash of the config, in the form `-` where type is either `sha512` or `sha256`. + - **_timeouts_** (object): options relating to `http` timeouts when fetching files over `http` or `https`. + - **_httpResponseHeaders_** (integer) the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds. + - **_httpTotal_** (integer) the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0. + - **_security_** (object): options relating to network security. + - **_tls_** (object): options relating to TLS when fetching resources over `https`. + - **_certificateAuthorities_** (list of objects): the list of additional certificate authorities (in addition to the system authorities) to be used for TLS verification when fetching over `https`. All certificate authorities must have a unique `source`. + - **source** (string): the URL of the certificate bundle (in PEM format). The bundle can contain multiple concatenated certificates. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + - **_compression_** (string): the type of compression used on the certificate (null or gzip). Compression cannot be used with S3. + - **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. + - **name** (string): the header name. + - **_value_** (string): the header contents. + - **_verification_** (object): options related to the verification of the certificate. + - **_hash_** (string): the hash of the certificate, in the form `-` where type is either `sha512` or `sha256`. + - **_proxy_** (object): options relating to setting an `HTTP(S)` proxy when fetching resources. + - **_httpProxy_** (string): will be used as the proxy URL for HTTP requests unless overridden by `noProxy`. + - **_httpsProxy_** (string): will be used as the proxy URL for HTTPS requests unless overridden by `noProxy`. + - **_noProxy_** (list of strings): specifies a list of strings to hosts that should be excluded from proxying. Each value is represented by an `IP address prefix (1.2.3.4)`, `an IP address prefix in CIDR notation (1.2.3.4/8)`, `a domain name`, or `a special DNS label (*)`. An IP address prefix and domain name can also include a literal port number `(1.2.3.4:80)`. A domain name matches that name and all subdomains. A domain name with a leading `.` matches subdomains only. For example `foo.com` matches `foo.com` and `bar.foo.com`; `.y.com` matches `x.y.com` but not `y.com`. A single asterisk `(*)` indicates that no proxying should be done. +- **_storage_** (object): describes the desired state of the system's storage devices. + - **_disks_** (list of objects): the list of disks to be configured and their options. Every entry must have a unique `device`. + - **device** (string): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. + - **_wipeTable_** (boolean): whether or not the partition tables shall be wiped. When true, the partition tables are erased before any further manipulation. Otherwise, the existing entries are left intact. + - **_partitions_** (list of objects): the list of partitions and their configuration for this particular disk. Every partition must have a unique `number`, or if 0 is specified, a unique `label`. + - **_label_** (string): the PARTLABEL for the partition. + - **_number_** (integer): the partition number, which dictates its position in the partition table (one-indexed). If zero, use the next available partition slot. + - **_sizeMiB_** (integer): the size of the partition (in mebibytes). If zero, the partition will be made as large as possible. + - **_startMiB_** (integer): the start of the partition (in mebibytes). If zero, the partition will be positioned at the start of the largest block available. + - **_typeGuid_** (string): the GPT [partition type GUID][part-types]. If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). + - **_guid_** (string): the GPT unique partition GUID. + - **_wipePartitionEntry_** (boolean) if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. + - **_shouldExist_** (boolean) whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. + - **_resize_** (boolean) whether or not the existing partition should be resized. If omitted, it defaults to false. If true, Ignition will resize an existing partition if it matches the config in all respects except the partition size. + - **_raid_** (list of objects): the list of RAID arrays to be configured. Every RAID array must have a unique `name`. + - **name** (string): the name to use for the resulting md device. + - **level** (string): the redundancy level of the array (e.g. linear, raid1, raid5, etc.). + - **devices** (list of strings): the list of devices (referenced by their absolute path) in the array. + - **_spares_** (integer): the number of spares (if applicable) in the array. + - **_options_** (list of strings): any additional options to be passed to mdadm. + - **_filesystems_** (list of objects): the list of filesystems to be configured. `device` and `format` need to be specified. Every filesystem must have a unique `device`. + - **device** (string): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. + - **format** (string): the filesystem format (ext4, btrfs, xfs, vfat, swap, or none). + - **_path_** (string): the mount-point of the filesystem while Ignition is running relative to where the root filesystem will be mounted. This is not necessarily the same as where it should be mounted in the real root, but it is encouraged to make it the same. + - **_wipeFilesystem_** (boolean): whether or not to wipe the device before filesystem creation, see [the documentation on filesystems][ignition-fs-reuse] for more information. Defaults to false. + - **_label_** (string): the label of the filesystem. + - **_uuid_** (string): the uuid of the filesystem. + - **_options_** (list of strings): any additional options to be passed to the format-specific mkfs utility. + - **_mountOptions_** (list of strings): any special options to be passed to the mount command. + - **_files_** (list of objects): the list of files to be written. Every file, directory and link must have a unique `path`. + - **path** (string): the absolute path to the file. + - **_overwrite_** (boolean): whether to delete preexisting nodes at the path. `contents.source` must be specified if `overwrite` is true. Defaults to false. + - **_contents_** (object): options related to the contents of the file. + - **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. + - **_source_** (string): the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created. + - **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. + - **name** (string): the header name. + - **_value_** (string): the header contents. + - **_verification_** (object): options related to the verification of the file contents. + - **_hash_** (string): the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. + - **_append_** (list of objects): list of contents to be appended to the file. Follows the same stucture as `contents` + - **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. + - **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + - **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. + - **name** (string): the header name. + - **_value_** (string): the header contents. + - **_verification_** (object): options related to the verification of the appended contents. + - **_hash_** (string): the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. + - **_mode_** (integer): the file's permission mode. Note that the mode must be properly specified as a **decimal** value (i.e. 0644 -> 420). If not specified, the permission mode for files defaults to 0644 or the existing file's permissions if `overwrite` is false, `contents.source` is unspecified, and a file already exists at the path. + - **_user_** (object): specifies the file's owner. + - **_id_** (integer): the user ID of the owner. + - **_name_** (string): the user name of the owner. + - **_group_** (object): specifies the group of the owner. + - **_id_** (integer): the group ID of the owner. + - **_name_** (string): the group name of the owner. + - **_directories_** (list of objects): the list of directories to be created. Every file, directory, and link must have a unique `path`. + - **path** (string): the absolute path to the directory. + - **_overwrite_** (boolean): whether to delete preexisting nodes at the path. If false and a directory already exists at the path, Ignition will only set its permissions. If false and a non-directory exists at that path, Ignition will fail. Defaults to false. + - **_mode_** (integer): the directory's permission mode. Note that the mode must be properly specified as a **decimal** value (i.e. 0755 -> 493). If not specified, the permission mode for directories defaults to 0755 or the mode of an existing directory if `overwrite` is false and a directory already exists at the path. + - **_user_** (object): specifies the directory's owner. + - **_id_** (integer): the user ID of the owner. + - **_name_** (string): the user name of the owner. + - **_group_** (object): specifies the group of the owner. + - **_id_** (integer): the group ID of the owner. + - **_name_** (string): the group name of the owner. + - **_links_** (list of objects): the list of links to be created. Every file, directory, and link must have a unique `path`. + - **path** (string): the absolute path to the link + - **_overwrite_** (boolean): whether to delete preexisting nodes at the path. If overwrite is false and a matching link exists at the path, Ignition will only set the owner and group. Defaults to false. + - **_user_** (object): specifies the symbolic link's owner. + - **_id_** (integer): the user ID of the owner. + - **_name_** (string): the user name of the owner. + - **_group_** (object): specifies the group of the owner. + - **_id_** (integer): the group ID of the owner. + - **_name_** (string): the group name of the owner. + - **target** (string): the target path of the link + - **_hard_** (boolean): a symbolic link is created if this is false, a hard one if this is true. + - **_luks_** (list of objects): the list of luks devices to be created. Every device must have a unique `name`. + - **name** (string): the name of the luks device. + - **device** (string): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. + - **_keyFile_** (string): options related to the contents of the key file. + - **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. + - **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + - **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. + - **name** (string): the header name. + - **_value_** (string): the header contents. + - **_verification_** (object): options related to the verification of the key file. + - **_hash_** (string): the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. + - **_label_** (string): the label of the luks device. + - **_uuid_** (string): the uuid of the luks device. + - **_options_** (list of strings): any additional options to be passed to the cryptsetup utility. + - **_wipeVolume_** (boolean): whether or not to wipe the device before volume creation, see [the documentation on filesystems][ignition-fs-reuse] for more information. + - **_clevis_** (object): describes the clevis configuration for the luks device. + - **_tang_** (list of objects): describes a tang server. Every server must have a unique `url`. + - **url** (string): url of the tang server. + - **thumbprint** (string): thumbprint of a trusted signing key. + - **_tpm2_** (bool): whether or not to use a tpm2 device. + - **_threshold_** (int): sets the minimum number of pieces required to decrypt the device. Default is 1. + - **_custom_** (object): overrides the clevis configuration. The `pin` & `config` will be passed directly to `clevis luks bind`. If specified, all other clevis options must be omitted. + - **pin** (string): the clevis pin. + - **config** (string): the clevis configuration JSON. + - **_needsNetwork_** (bool): whether or not the device requires networking. +- **_systemd_** (object): describes the desired state of the systemd units. + - **_units_** (list of objects): the list of systemd units. Every unit must have a unique `name`. + - **name** (string): the name of the unit. This must be suffixed with a valid unit type (e.g. "thing.service"). + - **_enabled_** (boolean): whether or not the service shall be enabled. When true, the service is enabled. When false, the service is disabled. When omitted, the service is unmodified. In order for this to have any effect, the unit must have an install section. + - **_mask_** (boolean): whether or not the service shall be masked. When true, the service is masked by symlinking it to `/dev/null`. When false, the service is unmasked by deleting the symlink to `/dev/null` if it exists. + - **_contents_** (string): the contents of the unit. + - **_dropins_** (list of objects): the list of drop-ins for the unit. Every drop-in must have a unique `name`. + - **name** (string): the name of the drop-in. This must be suffixed with ".conf". + - **_contents_** (string): the contents of the drop-in. +- **_passwd_** (object): describes the desired additions to the passwd database. + - **_users_** (list of objects): the list of accounts that shall exist. All users must have a unique `name`. + - **name** (string): the username for the account. + - **_passwordHash_** (string): the encrypted password for the account. + - **_sshAuthorizedKeys_** (list of strings): a list of SSH keys to be added as an SSH key fragment at `.ssh/authorized_keys.d/ignition` in the user's home directory. All SSH keys must be unique. + - **_uid_** (integer): the user ID of the account. + - **_gecos_** (string): the GECOS field of the account. + - **_homeDir_** (string): the home directory of the account. + - **_noCreateHome_** (boolean): whether or not to create the user's home directory. This only has an effect if the account doesn't exist yet. + - **_primaryGroup_** (string): the name of the primary group of the account. + - **_groups_** (list of strings): the list of supplementary groups of the account. + - **_noUserGroup_** (boolean): whether or not to create a group with the same name as the user. This only has an effect if the account doesn't exist yet. + - **_noLogInit_** (boolean): whether or not to add the user to the lastlog and faillog databases. This only has an effect if the account doesn't exist yet. + - **_shell_** (string): the login shell of the new account. + - **_shouldExist_** (boolean) whether or not the user with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified user. + - **_system_** (bool): whether or not this account should be a system account. This only has an effect if the account doesn't exist yet. + - **_groups_** (list of objects): the list of groups to be added. All groups must have a unique `name`. + - **name** (string): the name of the group. + - **_gid_** (integer): the group ID of the new group. + - **_passwordHash_** (string): the encrypted password of the new group. + - **_shouldExist_** (boolean) whether or not the group with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified group. + - **_system_** (bool): whether or not the group should be a system group. This only has an effect if the group doesn't exist yet. +- **_kernelArguments_** (object): describes the desired kernel arguments. + - **_shouldExist_** (list of strings): the list of kernel arguments that should exist. + - **_shouldNotExist_** (list of strings): the list of kernel arguments that should not exist. ## Ignition v2 Ignition v2 is not developed anymore but still supported (specification 2.3.0), the high-level [Container Linux Config YAML format][ct-config] can be used to emit Ignition v2 configs: -* **ignition** (object): metadata about the configuration itself. - * **version** (string): the semantic version number of the spec. The spec version must be compatible with the latest version (`2.3.0`). Compatibility requires the major versions to match and the spec version be less than or equal to the latest version. `-experimental` versions compare less than the final version with the same number, and previous experimental versions are not accepted. - * **_config_** (objects): options related to the configuration. - * **_append_** (list of objects): a list of the configs to be appended to the current config. - * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. - * **_verification_** (object): options related to the verification of the config. - * **_hash_** (string): the hash of the config, in the form `-` where type is `sha512`. - * **_replace_** (object): the config that will replace the current. - * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. - * **_verification_** (object): options related to the verification of the config. - * **_hash_** (string): the hash of the config, in the form `-` where type is `sha512`. - * **_timeouts_** (object): options relating to `http` timeouts when fetching files over `http` or `https`. - * **_httpResponseHeaders_** (integer) the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds. - * **_httpTotal_** (integer) the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0. - * **_security_** (object): options relating to network security. - * **_tls_** (object): options relating to TLS when fetching resources over `https`. - * **_certificateAuthorities_** (list of objects): the list of additional certificate authorities (in addition to the system authorities) to be used for TLS verification when fetching over `https`. - * **source** (string): the URL of the certificate (in PEM format). Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. - * **_verification_** (object): options related to the verification of the certificate. - * **_hash_** (string): the hash of the certificate, in the form `-` where type is sha512. -* **_storage_** (object): describes the desired state of the system's storage devices. - * **_disks_** (list of objects): the list of disks to be configured and their options. - * **device** (string): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. - * **_wipeTable_** (boolean): whether or not the partition tables shall be wiped. When true, the partition tables are erased before any further manipulation. Otherwise, the existing entries are left intact. - * **_partitions_** (list of objects): the list of partitions and their configuration for this particular disk. - * **_label_** (string): the PARTLABEL for the partition. - * **_number_** (integer): the partition number, which dictates it's position in the partition table (one-indexed). If zero, use the next available partition slot. - * **_sizeMiB_** (integer): the size of the partition (in mebibytes). If zero, the partition will be made as large as possible. - * **_startMiB_** (integer): the start of the partition (in mebibytes). If zero, the partition will be positioned at the start of the largest block available. - * **_size_** (integer, DEPRECATED): the size of the partition (in device logical sectors, 512 or 4096 bytes). If zero, the partition will be made as large as possible. This object has been marked for deprecation, please use **_sizeMiB_** field instead. - * **_start_** (integer, DEPRECATED): the start of the partition (in device logical sectors). If zero, the partition will be positioned at the start of the largest block available. This object has been marked for deprecation, please use **_startMiB_** field instead. - * **_typeGuid_** (string): the GPT [partition type GUID][part-types]. If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). - * **_guid_** (string): the GPT unique partition GUID. - * **_wipePartitionEntry_** (boolean) if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. - * **_shouldExist_** (boolean) whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. - * **_raid_** (list of objects): the list of RAID arrays to be configured. - * **name** (string): the name to use for the resulting md device. - * **level** (string): the redundancy level of the array (e.g. linear, raid1, raid5, etc.). - * **devices** (list of strings): the list of devices (referenced by their absolute path) in the array. - * **_spares_** (integer): the number of spares (if applicable) in the array. - * **_options_** (list of strings): any additional options to be passed to mdadm. - * **_filesystems_** (list of objects): the list of filesystems to be configured and/or used in the "files" section. Either "mount" or "path" needs to be specified. - * **_name_** (string): the identifier for the filesystem, internal to Ignition. This is only required if the filesystem needs to be referenced in the "files" section. - * **_mount_** (object): contains the set of mount and formatting options for the filesystem. A non-null entry indicates that the filesystem should be mounted before it is used by Ignition. - * **device** (string): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. - * **format** (string): the filesystem format (ext4, btrfs, xfs, vfat, or swap). - * **_wipeFilesystem_** (boolean): whether or not to wipe the device before filesystem creation, see [the documentation on filesystems][ignition-fs-reuse] for more information. - * **_label_** (string): the label of the filesystem. - * **_uuid_** (string): the uuid of the filesystem. - * **_options_** (list of strings): any additional options to be passed to the format-specific mkfs utility. - * **_create_** (object, DEPRECATED): contains the set of options to be used when creating the filesystem. - * **_force_** (boolean, DEPRECATED): whether or not the create operation shall overwrite an existing filesystem. - * **_options_** (list of strings, DEPRECATED): any additional options to be passed to the format-specific mkfs utility. - * **_path_** (string): the mount-point of the filesystem. A non-null entry indicates that the filesystem has already been mounted by the system at the specified path. This is really only useful for "/sysroot". - * **_files_** (list of objects): the list of files to be written. - * **filesystem** (string): the internal identifier of the filesystem in which to write the file. This matches the last filesystem with the given identifier. - * **path** (string): the absolute path to the file. - * **_overwrite_** (boolean): whether to delete preexisting nodes at the path. Defaults to true. - * **_append_** (boolean): whether to append to the specified file. Creates a new file if nothing exists at the path. Cannot be set if overwrite is set to true. - * **_contents_** (object): options related to the contents of the file. - * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. - * **_verification_** (object): options related to the verification of the file contents. - * **_hash_** (string): the hash of the config, in the form `-` where type is `sha512`. - * **_mode_** (integer): the file's permission mode. Note that the mode must be properly specified as a **decimal** value (i.e. 0644 -> 420). - * **_user_** (object): specifies the file's owner. - * **_id_** (integer): the user ID of the owner. - * **_name_** (string): the user name of the owner. - * **_group_** (object): specifies the group of the owner. - * **_id_** (integer): the group ID of the owner. - * **_name_** (string): the group name of the owner. - * **_directories_** (list of objects): the list of directories to be created. - * **filesystem** (string): the internal identifier of the filesystem in which to create the directory. This matches the last filesystem with the given identifier. - * **path** (string): the absolute path to the directory. - * **_overwrite_** (boolean): whether to delete preexisting nodes at the path. - * **_mode_** (integer): the directory's permission mode. Note that the mode must be properly specified as a **decimal** value (i.e. 0755 -> 493). - * **_user_** (object): specifies the directory's owner. - * **_id_** (integer): the user ID of the owner. - * **_name_** (string): the user name of the owner. - * **_group_** (object): specifies the group of the owner. - * **_id_** (integer): the group ID of the owner. - * **_name_** (string): the group name of the owner. - * **_links_** (list of objects): the list of links to be created - * **filesystem** (string): the internal identifier of the filesystem in which to write the link. This matches the last filesystem with the given identifier. - * **path** (string): the absolute path to the link - * **_overwrite_** (boolean): whether to delete preexisting nodes at the path. - * **_user_** (object): specifies the symbolic link's owner. - * **_id_** (integer): the user ID of the owner. - * **_name_** (string): the user name of the owner. - * **_group_** (object): specifies the group of the owner. - * **_id_** (integer): the group ID of the owner. - * **_name_** (string): the group name of the owner. - * **target** (string): the target path of the link - * **_hard_** (boolean): a symbolic link is created if this is false, a hard one if this is true. -* **_systemd_** (object): describes the desired state of the systemd units. - * **_units_** (list of objects): the list of systemd units. - * **name** (string): the name of the unit. This must be suffixed with a valid unit type (e.g. "thing.service"). - * **_enable_** (boolean, DEPRECATED): whether or not the service shall be enabled. When true, the service is enabled. In order for this to have any effect, the unit must have an install section. - * **_enabled_** (boolean): whether or not the service shall be enabled. When true, the service is enabled. When false, the service is disabled. When omitted, the service is unmodified. In order for this to have any effect, the unit must have an install section. - * **_mask_** (boolean): whether or not the service shall be masked. When true, the service is masked by symlinking it to `/dev/null`. - * **_contents_** (string): the contents of the unit. - * **_dropins_** (list of objects): the list of drop-ins for the unit. - * **name** (string): the name of the drop-in. This must be suffixed with ".conf". - * **_contents_** (string): the contents of the drop-in. -* **_networkd_** (object): describes the desired state of the networkd files. - * **_units_** (list of objects): the list of networkd files. - * **name** (string): the name of the file. This must be suffixed with a valid unit type (e.g. "00-eth0.network"). - * **_contents_** (string): the contents of the networkd file. - * **_dropins_** (list of objects): the list of drop-ins for the unit. - * **name** (string): the name of the drop-in. This must be suffixed with ".conf". - * **_contents_** (string): the contents of the drop-in. -* **_passwd_** (object): describes the desired additions to the passwd database. - * **_users_** (list of objects): the list of accounts that shall exist. - * **name** (string): the username for the account. - * **_passwordHash_** (string): the encrypted password for the account. - * **_sshAuthorizedKeys_** (list of strings): a list of SSH keys to be added to the user's authorized_keys. - * **_uid_** (integer): the user ID of the account. - * **_gecos_** (string): the GECOS field of the account. - * **_homeDir_** (string): the home directory of the account. - * **_noCreateHome_** (boolean): whether or not to create the user's home directory. This only has an effect if the account doesn't exist yet. - * **_primaryGroup_** (string): the name of the primary group of the account. - * **_groups_** (list of strings): the list of supplementary groups of the account. - * **_noUserGroup_** (boolean): whether or not to create a group with the same name as the user. This only has an effect if the account doesn't exist yet. - * **_noLogInit_** (boolean): whether or not to add the user to the lastlog and faillog databases. This only has an effect if the account doesn't exist yet. - * **_shell_** (string): the login shell of the new account. - * **_system_** (bool): whether or not this account should be a system account. This only has an effect if the account doesn't exist yet. - * **_create_** (object, DEPRECATED): contains the set of options to be used when creating the user. A non-null entry indicates that the user account shall be created. This object has been marked for deprecation, please use the **_users_** level fields instead. - * **_uid_** (integer): the user ID of the new account. - * **_gecos_** (string): the GECOS field of the new account. - * **_homeDir_** (string): the home directory of the new account. - * **_noCreateHome_** (boolean): whether or not to create the user's home directory. - * **_primaryGroup_** (string): the name or ID of the primary group of the new account. - * **_groups_** (list of strings): the list of supplementary groups of the new account. - * **_noUserGroup_** (boolean): whether or not to create a group with the same name as the user. - * **_noLogInit_** (boolean): whether or not to add the user to the lastlog and faillog databases. - * **_shell_** (string): the login shell of the new account. - * **_system_** (bool): whether or not to make the user a system user. - * **_groups_** (list of objects): the list of groups to be added. - * **name** (string): the name of the group. - * **_gid_** (integer): the group ID of the new group. - * **_passwordHash_** (string): the encrypted password of the new group. - * **_system_** (bool): whether or not the group should be a system group. This only has an effect if the group doesn't exist yet. +- **ignition** (object): metadata about the configuration itself. + - **version** (string): the semantic version number of the spec. The spec version must be compatible with the latest version (`2.3.0`). Compatibility requires the major versions to match and the spec version be less than or equal to the latest version. `-experimental` versions compare less than the final version with the same number, and previous experimental versions are not accepted. + - **_config_** (objects): options related to the configuration. + - **_append_** (list of objects): a list of the configs to be appended to the current config. + - **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + - **_verification_** (object): options related to the verification of the config. + - **_hash_** (string): the hash of the config, in the form `-` where type is `sha512`. + - **_replace_** (object): the config that will replace the current. + - **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + - **_verification_** (object): options related to the verification of the config. + - **_hash_** (string): the hash of the config, in the form `-` where type is `sha512`. + - **_timeouts_** (object): options relating to `http` timeouts when fetching files over `http` or `https`. + - **_httpResponseHeaders_** (integer) the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds. + - **_httpTotal_** (integer) the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0. + - **_security_** (object): options relating to network security. + - **_tls_** (object): options relating to TLS when fetching resources over `https`. + - **_certificateAuthorities_** (list of objects): the list of additional certificate authorities (in addition to the system authorities) to be used for TLS verification when fetching over `https`. + - **source** (string): the URL of the certificate (in PEM format). Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + - **_verification_** (object): options related to the verification of the certificate. + - **_hash_** (string): the hash of the certificate, in the form `-` where type is sha512. +- **_storage_** (object): describes the desired state of the system's storage devices. + - **_disks_** (list of objects): the list of disks to be configured and their options. + - **device** (string): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. + - **_wipeTable_** (boolean): whether or not the partition tables shall be wiped. When true, the partition tables are erased before any further manipulation. Otherwise, the existing entries are left intact. + - **_partitions_** (list of objects): the list of partitions and their configuration for this particular disk. + - **_label_** (string): the PARTLABEL for the partition. + - **_number_** (integer): the partition number, which dictates it's position in the partition table (one-indexed). If zero, use the next available partition slot. + - **_sizeMiB_** (integer): the size of the partition (in mebibytes). If zero, the partition will be made as large as possible. + - **_startMiB_** (integer): the start of the partition (in mebibytes). If zero, the partition will be positioned at the start of the largest block available. + - **_size_** (integer, DEPRECATED): the size of the partition (in device logical sectors, 512 or 4096 bytes). If zero, the partition will be made as large as possible. This object has been marked for deprecation, please use **_sizeMiB_** field instead. + - **_start_** (integer, DEPRECATED): the start of the partition (in device logical sectors). If zero, the partition will be positioned at the start of the largest block available. This object has been marked for deprecation, please use **_startMiB_** field instead. + - **_typeGuid_** (string): the GPT [partition type GUID][part-types]. If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). + - **_guid_** (string): the GPT unique partition GUID. + - **_wipePartitionEntry_** (boolean) if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. + - **_shouldExist_** (boolean) whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. + - **_raid_** (list of objects): the list of RAID arrays to be configured. + - **name** (string): the name to use for the resulting md device. + - **level** (string): the redundancy level of the array (e.g. linear, raid1, raid5, etc.). + - **devices** (list of strings): the list of devices (referenced by their absolute path) in the array. + - **_spares_** (integer): the number of spares (if applicable) in the array. + - **_options_** (list of strings): any additional options to be passed to mdadm. + - **_filesystems_** (list of objects): the list of filesystems to be configured and/or used in the "files" section. Either "mount" or "path" needs to be specified. + - **_name_** (string): the identifier for the filesystem, internal to Ignition. This is only required if the filesystem needs to be referenced in the "files" section. + - **_mount_** (object): contains the set of mount and formatting options for the filesystem. A non-null entry indicates that the filesystem should be mounted before it is used by Ignition. + - **device** (string): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. + - **format** (string): the filesystem format (ext4, btrfs, xfs, vfat, or swap). + - **_wipeFilesystem_** (boolean): whether or not to wipe the device before filesystem creation, see [the documentation on filesystems][ignition-fs-reuse] for more information. + - **_label_** (string): the label of the filesystem. + - **_uuid_** (string): the uuid of the filesystem. + - **_options_** (list of strings): any additional options to be passed to the format-specific mkfs utility. + - **_create_** (object, DEPRECATED): contains the set of options to be used when creating the filesystem. + - **_force_** (boolean, DEPRECATED): whether or not the create operation shall overwrite an existing filesystem. + - **_options_** (list of strings, DEPRECATED): any additional options to be passed to the format-specific mkfs utility. + - **_path_** (string): the mount-point of the filesystem. A non-null entry indicates that the filesystem has already been mounted by the system at the specified path. This is really only useful for "/sysroot". + - **_files_** (list of objects): the list of files to be written. + - **filesystem** (string): the internal identifier of the filesystem in which to write the file. This matches the last filesystem with the given identifier. + - **path** (string): the absolute path to the file. + - **_overwrite_** (boolean): whether to delete preexisting nodes at the path. Defaults to true. + - **_append_** (boolean): whether to append to the specified file. Creates a new file if nothing exists at the path. Cannot be set if overwrite is set to true. + - **_contents_** (object): options related to the contents of the file. + - **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. + - **_source_** (string): the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + - **_verification_** (object): options related to the verification of the file contents. + - **_hash_** (string): the hash of the config, in the form `-` where type is `sha512`. + - **_mode_** (integer): the file's permission mode. Note that the mode must be properly specified as a **decimal** value (i.e. 0644 -> 420). + - **_user_** (object): specifies the file's owner. + - **_id_** (integer): the user ID of the owner. + - **_name_** (string): the user name of the owner. + - **_group_** (object): specifies the group of the owner. + - **_id_** (integer): the group ID of the owner. + - **_name_** (string): the group name of the owner. + - **_directories_** (list of objects): the list of directories to be created. + - **filesystem** (string): the internal identifier of the filesystem in which to create the directory. This matches the last filesystem with the given identifier. + - **path** (string): the absolute path to the directory. + - **_overwrite_** (boolean): whether to delete preexisting nodes at the path. + - **_mode_** (integer): the directory's permission mode. Note that the mode must be properly specified as a **decimal** value (i.e. 0755 -> 493). + - **_user_** (object): specifies the directory's owner. + - **_id_** (integer): the user ID of the owner. + - **_name_** (string): the user name of the owner. + - **_group_** (object): specifies the group of the owner. + - **_id_** (integer): the group ID of the owner. + - **_name_** (string): the group name of the owner. + - **_links_** (list of objects): the list of links to be created + - **filesystem** (string): the internal identifier of the filesystem in which to write the link. This matches the last filesystem with the given identifier. + - **path** (string): the absolute path to the link + - **_overwrite_** (boolean): whether to delete preexisting nodes at the path. + - **_user_** (object): specifies the symbolic link's owner. + - **_id_** (integer): the user ID of the owner. + - **_name_** (string): the user name of the owner. + - **_group_** (object): specifies the group of the owner. + - **_id_** (integer): the group ID of the owner. + - **_name_** (string): the group name of the owner. + - **target** (string): the target path of the link + - **_hard_** (boolean): a symbolic link is created if this is false, a hard one if this is true. +- **_systemd_** (object): describes the desired state of the systemd units. + - **_units_** (list of objects): the list of systemd units. + - **name** (string): the name of the unit. This must be suffixed with a valid unit type (e.g. "thing.service"). + - **_enable_** (boolean, DEPRECATED): whether or not the service shall be enabled. When true, the service is enabled. In order for this to have any effect, the unit must have an install section. + - **_enabled_** (boolean): whether or not the service shall be enabled. When true, the service is enabled. When false, the service is disabled. When omitted, the service is unmodified. In order for this to have any effect, the unit must have an install section. + - **_mask_** (boolean): whether or not the service shall be masked. When true, the service is masked by symlinking it to `/dev/null`. + - **_contents_** (string): the contents of the unit. + - **_dropins_** (list of objects): the list of drop-ins for the unit. + - **name** (string): the name of the drop-in. This must be suffixed with ".conf". + - **_contents_** (string): the contents of the drop-in. +- **_networkd_** (object): describes the desired state of the networkd files. + - **_units_** (list of objects): the list of networkd files. + - **name** (string): the name of the file. This must be suffixed with a valid unit type (e.g. "00-eth0.network"). + - **_contents_** (string): the contents of the networkd file. + - **_dropins_** (list of objects): the list of drop-ins for the unit. + - **name** (string): the name of the drop-in. This must be suffixed with ".conf". + - **_contents_** (string): the contents of the drop-in. +- **_passwd_** (object): describes the desired additions to the passwd database. + - **_users_** (list of objects): the list of accounts that shall exist. + - **name** (string): the username for the account. + - **_passwordHash_** (string): the encrypted password for the account. + - **_sshAuthorizedKeys_** (list of strings): a list of SSH keys to be added to the user's authorized_keys. + - **_uid_** (integer): the user ID of the account. + - **_gecos_** (string): the GECOS field of the account. + - **_homeDir_** (string): the home directory of the account. + - **_noCreateHome_** (boolean): whether or not to create the user's home directory. This only has an effect if the account doesn't exist yet. + - **_primaryGroup_** (string): the name of the primary group of the account. + - **_groups_** (list of strings): the list of supplementary groups of the account. + - **_noUserGroup_** (boolean): whether or not to create a group with the same name as the user. This only has an effect if the account doesn't exist yet. + - **_noLogInit_** (boolean): whether or not to add the user to the lastlog and faillog databases. This only has an effect if the account doesn't exist yet. + - **_shell_** (string): the login shell of the new account. + - **_system_** (bool): whether or not this account should be a system account. This only has an effect if the account doesn't exist yet. + - **_create_** (object, DEPRECATED): contains the set of options to be used when creating the user. A non-null entry indicates that the user account shall be created. This object has been marked for deprecation, please use the **_users_** level fields instead. + - **_uid_** (integer): the user ID of the new account. + - **_gecos_** (string): the GECOS field of the new account. + - **_homeDir_** (string): the home directory of the new account. + - **_noCreateHome_** (boolean): whether or not to create the user's home directory. + - **_primaryGroup_** (string): the name or ID of the primary group of the new account. + - **_groups_** (list of strings): the list of supplementary groups of the new account. + - **_noUserGroup_** (boolean): whether or not to create a group with the same name as the user. + - **_noLogInit_** (boolean): whether or not to add the user to the lastlog and faillog databases. + - **_shell_** (string): the login shell of the new account. + - **_system_** (bool): whether or not to make the user a system user. + - **_groups_** (list of objects): the list of groups to be added. + - **name** (string): the name of the group. + - **_gid_** (integer): the group ID of the new group. + - **_passwordHash_** (string): the encrypted password of the new group. + - **_system_** (bool): whether or not the group should be a system group. This only has an effect if the group doesn't exist yet. [part-types]: http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs [rfc2397]: https://tools.ietf.org/html/rfc2397 [butane-spec]: https://coreos.github.io/butane/config-flatcar-v1_0/ -[ct-config]: ../config-transpiler/configuration +[ct-config]: ../butane/configuration [ignition-fs-reuse]: https://github.com/coreos/ignition/blob/main/docs/operator-notes.md#filesystem-reuse-semantics diff --git a/content/docs/latest/fb-provision/infrastructure/_index.md b/content/docs/latest/fb-provision/infrastructure/_index.md index f53d67be3..ebbda37a2 100644 --- a/content/docs/latest/fb-provision/infrastructure/_index.md +++ b/content/docs/latest/fb-provision/infrastructure/_index.md @@ -3,7 +3,7 @@ title: Infrastructure as Code description: Provision Flatcar Container Linux with an Ignition configuration through Terraform weight: 40 aliases: - - /docs/latest/provisioning/terraform/ + - /docs/latest/provisioning/terraform/ --- Flatcar Container Linux fits well with Terraform for the principle of Immutable Infrastructure where you deploy a node and, instead of making changes via SSH, you destroy it and deploy a new node. @@ -134,9 +134,8 @@ resource "null_resource" "reboot-when-ignition-changes" { You can find the full code for working examples in this [git repository][example-repo]. - -[cloud]: ../../installing/cloud/ -[butane-configs]: ../config-transpiler +[cloud]: ../../deploy/cloud/ +[butane-configs]: ../butane [terraform-ct-provider]: https://registry.terraform.io/providers/poseidon/ct/latest [terraform-ignition-provider]: https://registry.terraform.io/providers/community-terraform-providers/ignition/latest [boot-process]: ../ignition/boot-process/#reprovisioning diff --git a/content/docs/latest/fb-provision/vms/hyper-v.md b/content/docs/latest/fb-provision/vms/hyper-v.md index 12988d258..9a62050ef 100644 --- a/content/docs/latest/fb-provision/vms/hyper-v.md +++ b/content/docs/latest/fb-provision/vms/hyper-v.md @@ -158,8 +158,8 @@ Start-VM -Name $vmName Now that you have a machine booted it is time to play around. Check out the [Flatcar Container Linux Quickstart][quickstart] guide or dig into [more specific topics][doc-index]. -[update-strategies]: ../../setup/releases/update-strategies -[security-luks]: ../../setup/security/luks +[update-strategies]: ../../updates-releases/releases/update-strategies +[security-luks]: ../../security/encryption/luks [release-notes]: https://flatcar-linux.org/releases [quickstart]: ../ [doc-index]: ../../ diff --git a/content/docs/latest/fb-provision/vms/kubevirt.md b/content/docs/latest/fb-provision/vms/kubevirt.md index 3bb16f6e0..f36c08bd2 100644 --- a/content/docs/latest/fb-provision/vms/kubevirt.md +++ b/content/docs/latest/fb-provision/vms/kubevirt.md @@ -187,7 +187,7 @@ kubectl apply -f vm-flatcar-ignition.yaml Now that you have a KubeVirt machine booted it is time to play around. Check out the [Flatcar Container Linux Quickstart][quickstart] guide or dig into [more specific topics][doc-index]. -[update-strategies]: ../../setup/releases/update-strategies +[update-strategies]: ../../updates-releases/releases/update-strategies [release-notes]: https://flatcar-linux.org/releases [quickstart]: ../ [doc-index]: ../../ diff --git a/content/docs/latest/fb-provision/vms/libvirt.md b/content/docs/latest/fb-provision/vms/libvirt.md index 7bacd7df1..018f82ff3 100644 --- a/content/docs/latest/fb-provision/vms/libvirt.md +++ b/content/docs/latest/fb-provision/vms/libvirt.md @@ -230,7 +230,7 @@ Now that you have a machine booted it is time to play around. Check out the [Fla ## Terraform The [`libvirt` Terraform Provider](https://github.com/dmacvicar/terraform-provider-libvirt/) lets you describe Flatcar machines declaratively, powering automation that can be reused across bare metal, virtualization, and cloud environments. -Read more about using Terraform and Flatcar [here](../../provisioning/terraform/). +Read more about using Terraform and Flatcar [here](../infrastructure/). The following snippet shows the simplest working configuration: it downloads the Stable channel image, keeps it immutable, creates a CoW layer for the writable system disk, renders Ignition, and feeds it to the guest via fw_cfg so you can provision a single VM in just a few commands. @@ -470,8 +470,8 @@ Run `terraform init && terraform plan` followed by `terraform apply` to create ( [flatcar-dev]: https://groups.google.com/forum/#!forum/flatcar-linux-dev [discord]: https://discord.gg/PMYjFUsJyq -[config-transpiler]: ../../provisioning/config-transpiler -[update-strategies]: ../../setup/releases/update-strategies +[config-transpiler]: ../butane +[update-strategies]: ../../updates-releases/releases/update-strategies [release-notes]: https://flatcar-linux.org/releases [quickstart]: ../ [doc-index]: ../../ diff --git a/content/docs/latest/fb-provision/vms/qemu.md b/content/docs/latest/fb-provision/vms/qemu.md index 42aaffd48..488d02f6f 100644 --- a/content/docs/latest/fb-provision/vms/qemu.md +++ b/content/docs/latest/fb-provision/vms/qemu.md @@ -177,10 +177,10 @@ This will pass the contents of `config.ign` through to Ignition, which runs in t Now that you have a machine booted it is time to play around. Check out the [Flatcar Container Linux Quickstart][quickstart] guide or dig into [more specific topics][doc-index]. -[update-strategies]: ../../setup/releases/update-strategies +[update-strategies]: ../../updates-releases/releases/update-strategies [release-notes]: https://flatcar-linux.org/releases [quickstart]: ../ [doc-index]: ../../ [flatcar-dev]: https://groups.google.com/forum/#!forum/flatcar-linux-dev [discord]: https://discord.gg/PMYjFUsJyq -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../butane diff --git a/content/docs/latest/fb-provision/vms/virtualbox.md b/content/docs/latest/fb-provision/vms/virtualbox.md index d7ce3cf41..27c999a6e 100644 --- a/content/docs/latest/fb-provision/vms/virtualbox.md +++ b/content/docs/latest/fb-provision/vms/virtualbox.md @@ -156,7 +156,7 @@ ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -l core -p 2222 Now that you have a machine booted it is time to play around. Check out the [Flatcar Container Linux Quickstart][quickstart] guide or dig into [more specific topics][doc-index]. -[update-strategies]: ../../setup/releases/update-strategies +[update-strategies]: ../../updates-releases/releases/update-strategies [release-notes]: https://flatcar-linux.org/releases [butane-configs]: ../../provisioning/config-transpiler [quickstart]: ../ diff --git a/content/docs/latest/getting-started/_index.md b/content/docs/latest/getting-started/_index.md index 5a8a0a5e6..68fb21bf7 100644 --- a/content/docs/latest/getting-started/_index.md +++ b/content/docs/latest/getting-started/_index.md @@ -205,9 +205,9 @@ Check out the guides on [running Flatcar Container Linux][running-container-linu With any of these guides you will have machines up and running in a few minutes. -[learning-series]: ../learning-series -[update-strategies]: ../setup/releases/update-strategies -[update-conf]: ../setup/releases/update-conf +[learning-series]: ./learning-series +[update-strategies]: ../updates-releases/releases/update-strategies +[update-conf]: ../updates-releases/releases/update-conf [setup]: ../setup [running-container-linux]: ../#installing-flatcar [ec2-docs]: cloud/aws-ec2 @@ -223,11 +223,11 @@ With any of these guides you will have machines up and running in a few minutes. [ipxe-docs]: bare-metal/booting-with-ipxe [iso-docs]: bare-metal/booting-with-iso [install-docs]: bare-metal/installing-to-disk -[ignition]: ../provisioning/ignition/ -[cl-configs]: ../provisioning/cl-config -[butane-configs]: ../provisioning/config-transpiler -[butane-examples]: ../provisioning/config-transpiler/examples -[butane-spec]: ../provisioning/config-transpiler/configuration -[systemd]: ../setup/systemd/getting-started +[ignition]: ../fb-provision/ignition/ +[cl-configs]: ../fb-provision/cl-config +[butane-configs]: ../fb-provision/butane +[butane-examples]: ../fb-provision/butane/examples +[butane-spec]: ../fb-provision/butane/configuration +[systemd]: ../os-config/systemd/getting-started [container-image]: https://quay.io/repository/coreos/butane [butane]: https://github.com/coreos/butane/releases diff --git a/content/docs/latest/getting-started/learning-series/immutability-updates-rollbacks.md b/content/docs/latest/getting-started/learning-series/immutability-updates-rollbacks.md index 3c6812f0d..36ca40076 100644 --- a/content/docs/latest/getting-started/learning-series/immutability-updates-rollbacks.md +++ b/content/docs/latest/getting-started/learning-series/immutability-updates-rollbacks.md @@ -4,7 +4,7 @@ linktitle: Updates, Roll-Backs, Immutability weight: 5 author: Lexi Nadolski, Thilo Fromm aliases: - - /docs/latest/learning-series/immutability-updates-rollbacks/ + - /docs/latest/learning-series/immutability-updates-rollbacks/ --- In this session, we’ll do a deep dive into Flatcar's immutability and partition layout, and dissect the operating system's start-up process. @@ -18,12 +18,13 @@ While a bit dry, these are necessary to understand the innerworks of in-place up The session builds on the session "Basic Operation and Local Testing". It assumes you + - have created a local test environment. - are able to start ephemeral Flatcar VMs. - know how to transpile Butane YAML to Ignition JSON. - pass Ignition JSON configuration to a VM at launch. -## Download a *previous* OS release +## Download a _previous_ OS release In the Basics session, we downloaded the latest Alpha. Since we want to perform live in-place updates in this session, we need to use a less-than-latest release. @@ -32,10 +33,10 @@ Go to https://www.flatcar.org/releases/#alpha-release, scroll down a bit until y As before, download -* `flatcar_production_qemu_uefi.sh` which we also need to make executable -* `flatcar_production_qemu_uefi_efi_code.qcow2` -* `flatcar_production_qemu_uefi_efi_vars.qcow2` -* `flatcar_production_qemu_uefi_image.img` +- `flatcar_production_qemu_uefi.sh` which we also need to make executable +- `flatcar_production_qemu_uefi_efi_code.qcow2` +- `flatcar_production_qemu_uefi_efi_vars.qcow2` +- `flatcar_production_qemu_uefi_image.img` Or use the bash automation below. Adjust `release` and `arch` to your needs. @@ -52,7 +53,7 @@ Then run ```sh wget https://alpha.release.flatcar-linux.net/"${arch}"-usr/"${release}"/{flatcar_production_qemu_uefi.sh,flatcar_production_qemu_uefi_efi_code.qcow2,flatcar_production_qemu_uefi_efi_vars.qcow2,flatcar_production_qemu_uefi_image.img} -chmod 755 flatcar_production_qemu_uefi.sh +chmod 755 flatcar_production_qemu_uefi.sh ``` ## Flatcar Partition Layout @@ -62,6 +63,7 @@ It will check for updates regularly, and stage and reboot by default. We can avoid that by simply not starting the update client. ```yaml + ... systemd: units: @@ -110,16 +112,19 @@ systemd:
Then transpile and start. + ```sh -cat nginx.yaml | docker run --rm -i quay.io/coreos/butane:latest > nginx.json +cat nginx.yaml | docker run --rm -i quay.io/coreos/butane:latest > nginx.json ./flatcar_production_qemu_uefi.sh -i nginx.json -f 12345:80 -- -nographic -snapshot ``` **NOTE** We'll require `root` access for most of what we do in this session, as we're introspecting sensitive areas of the system. Once the VM finished booting, use + ```sh sudo -i ``` + to switch to the root account. Leave the VM running for interactively exploring the Flatcar OS. @@ -132,16 +137,19 @@ Everything else is either sym-linked into `/usr`- like `/bin`, `/sbin`, `/lib`, Or it is generated at first boot (see the tmpfiles step below). Check it out! + ```sh ls -la / ``` Try creating a file in `/usr`: + ```sh echo 'test' > /usr/testfile ``` Let's check out how the OS disk is used. Which partitions of the OS disk are mounted? + ```sh mount | grep vda ``` @@ -149,7 +157,8 @@ mount | grep vda Wait, `/` and `/oem` are there, but not `/usr`? Well, this needs a bit of detective work. -First, we can verify `/usr` *is*, in fact, based on a partition on `/dev/vda`: +First, we can verify `/usr` _is_, in fact, based on a partition on `/dev/vda`: + ```sh rootdev -s /usr ``` @@ -157,26 +166,31 @@ rootdev -s /usr returns `vda3`. But why doesn't it show up in our mounts? Let's check what is actually mounted on `/usr`: + ```sh mount | grep -w /usr ``` Let's ignore the `systemd-sysext` line for now; we'll elaborate on this in a later session. So `/usr` is handled by devicemapper, more specifically + ```sh ls -la /dev/mapper/usr ``` it's `dm-0`. Let's ask the device mapper about it, then: + ```sh dmsetup status /dev/dm-0 ``` OOOoohh, it's a [dm-verity](https://docs.kernel.org/admin-guide/device-mapper/verity.html) device! + - DM-Verity is a special Device Mapper storage that is guaranteed to be read-only - in fact, verity of the storage bits is guarded by cryptographic checksums. -- DM-Verity was added to the Linux kernel in 2011 by [Netflix and Google](https://lwn.net/Articles/459420/), and is used in Chromebooks - which share ancestry with Flatcar. +- DM-Verity was added to the Linux kernel in 2011 by [Netflix and Google](https://lwn.net/Articles/459420/), and is used in Chromebooks - which share ancestry with Flatcar. So let's see which partition `dm-0` is actually using: + ```sh veritysetup status usr ``` @@ -187,11 +201,11 @@ So dm-verity inserts itself by means of a device mapper layer between the physic For now we have: -* `/` backed by `vda9`- the root partition. This is populated at first boot; we'll discuss in a second how exactly that happens. There's also a reason why it is the last partition in the table. Find out more below. -* `/oem` backed by `vda6` contains vendor specific tools (think `wa-agent` in the Azure image, or `amazon-ssm-agent` for AWS). -* `/usr` is a device mapper storage - * backed by `dm-0`, the verity layer, which is - * backed by `vda3`, the currently active OS partition. +- `/` backed by `vda9`- the root partition. This is populated at first boot; we'll discuss in a second how exactly that happens. There's also a reason why it is the last partition in the table. Find out more below. +- `/oem` backed by `vda6` contains vendor specific tools (think `wa-agent` in the Azure image, or `amazon-ssm-agent` for AWS). +- `/usr` is a device mapper storage + - backed by `dm-0`, the verity layer, which is + - backed by `vda3`, the currently active OS partition. There are other partitions, some of which are reserved and are currently not in use. EFI-SYSTEM, ROOT, USR-A / USR-B, and OEM are the most interesting ones. @@ -218,7 +232,7 @@ user space release #A] USR4b[USR-B user space release #B] ROOT[Pivot to root w/ USR-A or USR-B mounted to /usr] - EFI1 --> EFI2 + EFI1 --> EFI2 EFI2 --Partition A is active--> EFI3a --> USR4a --> ROOT EFI2 --Partition B is active--> EFI3b --> USR4b --> ROOT ``` @@ -232,7 +246,7 @@ The boot process is quite similar to regular Linux start-up, with minor Flatcar 5. Ignition finishes, root is switched from the initrd to the root filesystem, and systemd reloads all services. 6. `ROOT` and `USR-*` Regular system services start. -Flatcar's OS disk (see [partition table](../developer-guides/sdk-disk-partitions/#partition-table) in our public docs) contains 2 separate partitions for OS user spaces. The respective two kernel+initrd blobs are stored together in the `EFI-SYSTEM` partition. +Flatcar's OS disk (see [partition table](../../devguide/sdk-disk-partitions/#partition-table) in our public docs) contains 2 separate partitions for OS user spaces. The respective two kernel+initrd blobs are stored together in the `EFI-SYSTEM` partition. Let's explore ourselves! @@ -359,8 +373,8 @@ Services and modifications to services (drop-ins, masks, enablement) shipped wit - **100% reversible**. You can roll back to the previous version in case of issues, to boot into a known-good environment. Roll-backs are automatable / customisable to your needs, and atomic too. - **Update from any version to any (newer) version**. Flatcar can be updated from any previous release to the latest release. -After all that theory we'll now *FINALLY* get back to some more hands-on stuff. -This is the reason we downloaded a *previous* OS release. +After all that theory we'll now _FINALLY_ get back to some more hands-on stuff. +This is the reason we downloaded a _previous_ OS release. So let's go and update! First, open a browser and point it to [http://localhost:12345](http://localhost:12345). @@ -446,13 +460,13 @@ Lastly, let's consult partition table attributes: cgpt show /dev/vda ``` -We see that `USR-B` now is active (higher priority than `USR-A`) *and* "successful". +We see that `USR-B` now is active (higher priority than `USR-A`) _and_ "successful". This is because `update_engine` makes sure the `successful` attribute is set when it starts. ### Critical Services and Updates: Automating Roll-Backs The above discusses OS mechanism to boot into new OS versions and declare the new OS release stable - solely based on the successful start-up of `update_engine`. -It's quite easy to build on this and to devise a set-up that ensures critical services come up *before* a new release is declared stable. +It's quite easy to build on this and to devise a set-up that ensures critical services come up _before_ a new release is declared stable. ```mermaid --- @@ -478,6 +492,7 @@ Otherwise we risk ending up in a reboot loop when our "critical services" don't A respective dependency chain can be built with systemd units and seamlessly integrated into the generic Flatcar start-up. For this, we want: + 1. A check for determining if this is the first boot after an upgrade. It should declare the system "healthy" straight away only if this is not a first boot after upgrade. We can build this in a short shell script from what we've learned about Flatcars partition labels above. @@ -487,7 +502,6 @@ For this, we want: 3. A trigger for `update_engine` to only start when either 1. or 2. marked the boot as healthy. 4. A timer that triggers a reboot if neither 1. nor 2. concluded successfully. - ```mermaid --- title: Flatcar First-boot after update @@ -596,15 +610,15 @@ The script will generate a file `/run/first-boot-healthy` only if this is NOT th We also need a corresponding service definition to run it. ```yaml - - name: is-first-boot-after-upgrade.service - enabled: true - contents: | - [Unit] - Description=Detect if this is a first boot after an OS upgrade. - [Service] - ExecStart=/opt/detect-first-boot-after-upgrade.sh - [Install] - WantedBy=multi-user.target +- name: is-first-boot-after-upgrade.service + enabled: true + contents: | + [Unit] + Description=Detect if this is a first boot after an OS upgrade. + [Service] + ExecStart=/opt/detect-first-boot-after-upgrade.sh + [Install] + WantedBy=multi-user.target ``` #### 2. Force a health check that ensures our critical service is running @@ -616,19 +630,19 @@ Users can then make their critical services depend on this unit, so all these ne Consider this service definition: ```yaml - - name: first-boot-healtcheck.service - enabled: true - contents: | - [Unit] - Description=Meta service to mark the first boot after an OS upgrade as healthy. - After=is-first-boot-after-upgrade.service - Requires=is-first-boot-after-upgrade.service - ConditionPathExists=!/run/first-boot-healthy - [Service] - ExecStartPre=/usr/bin/echo "All critical services are up, start-up is healthy." - ExecStart=/usr/bin/touch /run/first-boot-healthy - [Install] - WantedBy=multi-user.target +- name: first-boot-healtcheck.service + enabled: true + contents: | + [Unit] + Description=Meta service to mark the first boot after an OS upgrade as healthy. + After=is-first-boot-after-upgrade.service + Requires=is-first-boot-after-upgrade.service + ConditionPathExists=!/run/first-boot-healthy + [Service] + ExecStartPre=/usr/bin/echo "All critical services are up, start-up is healthy." + ExecStart=/usr/bin/touch /run/first-boot-healthy + [Install] + WantedBy=multi-user.target ``` It runs after `is-first-boot-after-upgrade.service`, and it will only run when `/run/first-boot-healthy` hasn't been created yet. @@ -657,27 +671,27 @@ Fortunately, path units can be used to work around this, and to start arbitrary Let's add a path unit that starts `update_engine` for us when our flag file is created ```yaml - - name: first-boot-healthy.path - enabled: true - contents: | - [Unit] - Description=Triggers either after the first boot after an OS upgrade was healthy or if there was no OS upgrade. - [Path] - PathExists=/run/first-boot-healthy - Unit=update-engine.service - [Install] - WantedBy=multi-user.target +- name: first-boot-healthy.path + enabled: true + contents: | + [Unit] + Description=Triggers either after the first boot after an OS upgrade was healthy or if there was no OS upgrade. + [Path] + PathExists=/run/first-boot-healthy + Unit=update-engine.service + [Install] + WantedBy=multi-user.target ``` -And ensure it does *not* start when the flag file does not exists - this effectively covers all `wants:` and `requires:` dependencies of other units on `update_engine` spread across Flatcar. +And ensure it does _not_ start when the flag file does not exists - this effectively covers all `wants:` and `requires:` dependencies of other units on `update_engine` spread across Flatcar. ```yaml - - name: update-engine.service - dropins: - - name: first-boot-healthy-must-exist.conf - contents: | - [Unit] - ConditionPathExists=/run/first-boot-healthy +- name: update-engine.service + dropins: + - name: first-boot-healthy-must-exist.conf + contents: | + [Unit] + ConditionPathExists=/run/first-boot-healthy ``` #### 4. Reboot after timeout if healthy flag was not set @@ -685,28 +699,28 @@ And ensure it does *not* start when the flag file does not exists - this effecti Lastly, we define a timer unit that waits a set amount of time after systemd started, before starting a service which, if `/run/first-boot-healthy` does not exist, triggers a reboot. ```yaml - - name: reboot-after-unhealthy-upgrade.timer - enabled: true - contents: | - [Unit] - Description=Triggers a reboot (causing a rollback) when the OS is unhealthy after an upgrade - [Timer] - OnStartupSec=60 - [Install] - WantedBy=timers.target - - - name: reboot-after-unhealthy-upgrade.service - contents: | - [Unit] - Description=Triggers a reboot (causing a rollback) when the OS is unhealthy after an upgrade - ConditionPathExists=!/run/first-boot-healthy - [Service] - ExecStartPre=/usr/bin/echo "WARNING: unclean boot detected after OS upgrade." - ExecStartPre=/usr/bin/echo "WARNING: Rebooting to trigger a roll-back." - ExecStart=/usr/bin/reboot -``` - -**Note** that the timeout is *very* tight - 60 seconds - in this example. +- name: reboot-after-unhealthy-upgrade.timer + enabled: true + contents: | + [Unit] + Description=Triggers a reboot (causing a rollback) when the OS is unhealthy after an upgrade + [Timer] + OnStartupSec=60 + [Install] + WantedBy=timers.target + +- name: reboot-after-unhealthy-upgrade.service + contents: | + [Unit] + Description=Triggers a reboot (causing a rollback) when the OS is unhealthy after an upgrade + ConditionPathExists=!/run/first-boot-healthy + [Service] + ExecStartPre=/usr/bin/echo "WARNING: unclean boot detected after OS upgrade." + ExecStartPre=/usr/bin/echo "WARNING: Rebooting to trigger a roll-back." + ExecStart=/usr/bin/reboot +``` + +**Note** that the timeout is _very_ tight - 60 seconds - in this example. This is for Demo purposes; in production environments this should align to the expected critical service start-up time, likely 10 minutes or more. #### Finishing touches and test run @@ -889,7 +903,7 @@ After boot, become root (`sudo -i`). Check the NGINX web server from your local browser, and check the status of the various services we defined: ```sh -systemctl status nginx.service update-engine.service is-first-boot-after-upgrade.service first-boot-healtcheck.service reboot-after-unhealthy-upgrade.service -l --no-pager +systemctl status nginx.service update-engine.service is-first-boot-after-upgrade.service first-boot-healtcheck.service reboot-after-unhealthy-upgrade.service -l --no-pager ``` Among other things, we can see that `reboot-after-unhealthy-upgrade.service` tried to start 60 seconds after boot, but fortunately did not trigger a reboot as its precondition was not met (the non-existence of `/run/first-boot-healthy`). @@ -927,7 +941,6 @@ Flatcar Container Linux by Kinvolk alpha YYY for QEMU `XXXX` should be the Alpha release we downloaded at the beginning of this session. - Rollback successful! Since we're now back to the previous version, step #1 above should mark the boot as healthy (so the instance does not continue to reboot). diff --git a/content/docs/latest/orchestrate/clusters/architectures.md b/content/docs/latest/orchestrate/clusters/architectures.md index bb531e12a..6047e82e9 100644 --- a/content/docs/latest/orchestrate/clusters/architectures.md +++ b/content/docs/latest/orchestrate/clusters/architectures.md @@ -219,14 +219,14 @@ storage: [butane-download]: https://github.com/coreos/butane/releases [ignition-getting-started]: https://github.com/coreos/ignition/blob/main/docs/getting-started.md [ignition-supported]: https://github.com/coreos/ignition/blob/main/docs/supported-platforms.md -[flatcar-qemu]: ../../installing/vms/qemu +[flatcar-qemu]: ../../fb-provision/vms/qemu [minikube]: https://github.com/kubernetes/minikube [nebraska-update]: https://github.com/kinvolk/nebraska [flatcar-channels]: https://www.flatcar-linux.org/releases/ [flatcar-supported]: ../../ -[flatcar-ec2]: ../../installing/cloud/aws-ec2 -[flatcar-azure]: ../../installing/cloud/azure -[flatcar-gce]: ../../installing/cloud/gcp -[flatcar-do]: ../../installing/cloud/digitalocean -[flatcar-bm]: ../../installing/bare-metal/booting-with-ipxe +[flatcar-ec2]: ../../deploy/cloud/aws-ec2 +[flatcar-azure]: ../../deploy/cloud/azure +[flatcar-gce]: ../../deploy/cloud/gcp +[flatcar-do]: ../../deploy/cloud/digitalocean +[flatcar-bm]: ../../deploy/bare-metal/booting-with-ipxe [typhoon]: https://github.com/poseidon/typhoon diff --git a/content/docs/latest/orchestrate/clusters/booting-on-ecs.md b/content/docs/latest/orchestrate/clusters/booting-on-ecs.md index 6051c9c83..e688cdd81 100644 --- a/content/docs/latest/orchestrate/clusters/booting-on-ecs.md +++ b/content/docs/latest/orchestrate/clusters/booting-on-ecs.md @@ -96,7 +96,7 @@ If you want to configure SSH keys in order to log in, mount disks or configure o For more information on using ECS, check out the [official Amazon documentation][ecs-docs]. [aws-ecs]: http://aws.amazon.com/ecs/ -[boot-ec2]: ../../installing/cloud/aws-ec2 -[butane-configs]: ../../provisioning/config-transpiler -[ignition-docs]: ../../provisioning/ignition +[boot-ec2]: ../../deploy/cloud/aws-ec2 +[butane-configs]: ../../fb-provision/butane +[ignition-docs]: ../../fb-provision/ignition [ecs-docs]: http://aws.amazon.com/documentation/ecs/ diff --git a/content/docs/latest/orchestrate/clusters/discovery.md b/content/docs/latest/orchestrate/clusters/discovery.md index ac9da7bf1..5fea7b57f 100644 --- a/content/docs/latest/orchestrate/clusters/discovery.md +++ b/content/docs/latest/orchestrate/clusters/discovery.md @@ -20,7 +20,7 @@ https://discovery.etcd.io/6a28e078895c5ec737174db2419bb2f3 ``` The discovery URL can be provided to each Flatcar Container Linux machine -via [Butane Configs](../../provisioning/config-transpiler). The rest of this guide will +via [Butane Configs](../../fb-provision/butane). The rest of this guide will explain what's happening behind the scenes, but if you're trying to get clustered as quickly as possible, all you need to do is provide a _fresh, unique_ discovery token in your config. diff --git a/content/docs/latest/orchestrate/containers/customizing-docker.md b/content/docs/latest/orchestrate/containers/customizing-docker.md index dbcbe90d2..a0f622d4b 100644 --- a/content/docs/latest/orchestrate/containers/customizing-docker.md +++ b/content/docs/latest/orchestrate/containers/customizing-docker.md @@ -380,4 +380,4 @@ A json file `.dockercfg` can be created in your home directory that holds authen [self-signed-certs]: ../setup/security/generate-self-signed-certificates [systemd-socket]: https://www.freedesktop.org/software/systemd/man/systemd.socket.html [systemd-env-vars]: ../setup/systemd/environment-variables/#system-wide-environment-variables -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../../fb-provision/butane diff --git a/content/docs/latest/os-config/host-config/adding-users.md b/content/docs/latest/os-config/host-config/adding-users.md index 16638b994..4bc544c99 100644 --- a/content/docs/latest/os-config/host-config/adding-users.md +++ b/content/docs/latest/os-config/host-config/adding-users.md @@ -98,7 +98,7 @@ $ sudo cat /etc/sudoers.d/user1 user1 ALL=(ALL) NOPASSWD: ALL ``` -[butane-configs]: ../../provisioning/config-transpiler -[cl-config]: ../../provisioning/config-transpiler -[config-spec]: ../../provisioning/config-transpiler/configuration +[butane-configs]: ../../fb-provision/butane +[cl-config]: ../../fb-provision/butane +[config-spec]: ../../fb-provision/butane/configuration [systemd-userdb]: https://www.freedesktop.org/software/systemd/man/systemd-userdbd.service.html diff --git a/content/docs/latest/os-config/host-config/configuring-date-and-timezone.md b/content/docs/latest/os-config/host-config/configuring-date-and-timezone.md index d95ed9056..d1cfade71 100644 --- a/content/docs/latest/os-config/host-config/configuring-date-and-timezone.md +++ b/content/docs/latest/os-config/host-config/configuring-date-and-timezone.md @@ -214,4 +214,4 @@ storage: [systemd-timesyncd]: http://www.freedesktop.org/software/systemd/man/systemd-timesyncd.service.html [systemd.network]: http://www.freedesktop.org/software/systemd/man/systemd.network.html [timesyncd.conf]: http://www.freedesktop.org/software/systemd/man/timesyncd.conf.html -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../../fb-provision/butane diff --git a/content/docs/latest/os-config/host-config/drop-in-units.md b/content/docs/latest/os-config/host-config/drop-in-units.md index 749978499..2ada29c2f 100644 --- a/content/docs/latest/os-config/host-config/drop-in-units.md +++ b/content/docs/latest/os-config/host-config/drop-in-units.md @@ -4,9 +4,9 @@ linktitle: Drop-In Units description: How to customize the running system by using drop-in units. weight: 20 aliases: - - /docs/latest/setup/systemd/drop-in-units/ - - ../../os/using-systemd-drop-in-units - - ../../clusters/customization/using-systemd-drop-in-units + - /docs/latest/setup/systemd/drop-in-units/ + - ../../os/using-systemd-drop-in-units + - ../../clusters/customization/using-systemd-drop-in-units --- There are two methods of overriding default Flatcar Container Linux settings in unit files: copying the unit file from `/usr/lib64/systemd/system` to `/etc/systemd/system` and modifying the chosen settings. Alternatively, one can create a directory named `unit.d` within `/etc/systemd/system` and place a drop-in file `name.conf` there that only changes the specific settings one is interested in. Note that multiple such drop-in files are read if present. @@ -156,9 +156,9 @@ systemd-delta --type=extended For more examples using systemd customization, check out these documents: - * [Customizing Docker](../../container-runtimes/customizing-docker#using-a-dockercfg-file-for-authentication) - * [Customizing the SSH Daemon](../security/customizing-sshd#changing-the-sshd-port) - * [Using Environment Variables in systemd Units](../environment-variables) +- [Customizing Docker](../../orchestrate/containers/customizing-docker#using-a-dockercfg-file-for-authentication) +- [Customizing the SSH Daemon](../../security/cert-auth/customizing-sshd#changing-the-sshd-port) +- [Using Environment Variables in systemd Units](../environment-variables) ## More Information diff --git a/content/docs/latest/os-config/host-config/environment-variables.md b/content/docs/latest/os-config/host-config/environment-variables.md index 1d4b6203b..cd0989ce4 100644 --- a/content/docs/latest/os-config/host-config/environment-variables.md +++ b/content/docs/latest/os-config/host-config/environment-variables.md @@ -4,9 +4,9 @@ linktitle: Environment Variables description: How to configure and use environment variables in systemd units. weight: 30 aliases: - - /docs/latest/setup/systemd/environment-variables/ - - ../../os/using-environment-variables-in-systemd-units - - ../../clusters/customization/using-environment-variables-in-systemd-units + - /docs/latest/setup/systemd/environment-variables/ + - ../../os/using-environment-variables-in-systemd-units + - ../../clusters/customization/using-environment-variables-in-systemd-units --- ## Environment directive @@ -110,8 +110,8 @@ storage: Where: -* `/etc/systemd/system.conf.d/10-default-env.conf` config file will set default environment variables for all systemd units. -* `/etc/profile.env` will set environment variables for all users logged in Flatcar Container Linux. +- `/etc/systemd/system.conf.d/10-default-env.conf` config file will set default environment variables for all systemd units. +- `/etc/profile.env` will set environment variables for all users logged in Flatcar Container Linux. ### etcd2.service unit advanced example @@ -121,16 +121,16 @@ A [complete example][etcd-cluster-reconfiguration] of combining environment vari For more systemd examples, check out these documents: - * [Customizing Docker][customizing-docker] - * [Customizing the SSH Daemon][customizing-sshd] - * [Using systemd Drop-In Units][drop-in] - * [etcd Cluster Runtime Reconfiguration on Flatcar Container Linux][etcd-cluster-reconfiguration] +- [Customizing Docker][customizing-docker] +- [Customizing the SSH Daemon][customizing-sshd] +- [Using systemd Drop-In Units][drop-in] +- [etcd Cluster Runtime Reconfiguration on Flatcar Container Linux][etcd-cluster-reconfiguration] [drop-in]: drop-in-units -[customizing-sshd]: ../security/customizing-sshd#changing-the-sshd-port -[customizing-etcd]: ../customization/customize-etcd-unit -[customizing-docker]: ../../container-runtimes/customizing-docker#using-a-dockercfg-file-for-authentication -[butane-configs]: ../../provisioning/config-transpiler +[customizing-sshd]: ../../security/cert-auth/customizing-sshd#changing-the-sshd-port +[customizing-etcd]: ../../security/cert-auth/customize-etcd-unit +[customizing-docker]: ../../orchestrate/containers/customizing-docker#using-a-dockercfg-file-for-authentication +[butane-configs]: ../../fb-provision/butane [etcd-discovery]: ../clusters/cluster-discovery [systemd-udev]: udev-rules [etcd-cluster-reconfiguration]: https://github.com/coreos/docs/blob/master/etcd/etcd-live-cluster-reconfiguration.md diff --git a/content/docs/latest/os-config/host-config/power-management.md b/content/docs/latest/os-config/host-config/power-management.md index 3c46dcc42..3d51468b8 100644 --- a/content/docs/latest/os-config/host-config/power-management.md +++ b/content/docs/latest/os-config/host-config/power-management.md @@ -55,4 +55,4 @@ systemd: More information on further tuning each governor is available in the [Kernel Documentation](https://www.kernel.org/doc/Documentation/cpu-freq/governors.txt) -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../../fb-provision/butane diff --git a/content/docs/latest/os-config/network/ACPI.md b/content/docs/latest/os-config/network/ACPI.md index 317928dec..a9b2a5786 100644 --- a/content/docs/latest/os-config/network/ACPI.md +++ b/content/docs/latest/os-config/network/ACPI.md @@ -69,4 +69,4 @@ May 24 14:30:20 localhost systemd[1]: Stopped ACPI event daemon. Beginning with Flatcar major release 3402, qemu-guest-agent is part of all images and can handle certain lifecycle operations without acpid. The agent service will automatically be enabled if a virtio-port with the name `org.qemu.guest_agent.0` is detected. For Openstack it is necessary to launch the instance with `hw_qemu_guest_agent=yes` set. For Proxmox, you have to set "QEMU Guest Agent" to "Enabled" in Virtual Machine Options. -[butane]: ../../provisioning/ignition/specification/#ignition-v3 +[butane]: ../../fb-provision/ignition/specification#ignition-v3 diff --git a/content/docs/latest/os-config/network/configuring-dns.md b/content/docs/latest/os-config/network/configuring-dns.md index 34178853a..6cce10cf9 100644 --- a/content/docs/latest/os-config/network/configuring-dns.md +++ b/content/docs/latest/os-config/network/configuring-dns.md @@ -93,6 +93,6 @@ storage: [systemd-networkd]: http://www.freedesktop.org/software/systemd/man/systemd-networkd.service.html [resolved.conf]: http://www.freedesktop.org/software/systemd/man/resolved.conf.html [nsswitch.conf]: http://man7.org/linux/man-pages/man5/nsswitch.conf.5.html -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../../fb-provision/butane [networkd-config]: network-config-with-networkd [kubernetes]: https://kubernetes.io/docs/tasks/administer-cluster/dns-debugging-resolution/#known-issues diff --git a/content/docs/latest/os-config/network/network-config-with-networkd.md b/content/docs/latest/os-config/network/network-config-with-networkd.md index 29e5c3eec..e21feec69 100644 --- a/content/docs/latest/os-config/network/network-config-with-networkd.md +++ b/content/docs/latest/os-config/network/network-config-with-networkd.md @@ -3,9 +3,9 @@ title: Network configuration with networkd description: How to setup static networking, turn on/off ipv4/ipv6, and debugging tips. weight: 40 aliases: - - /docs/latest/setup/customization/network-config-with-networkd/ - - ../../os/network-config-with-networkd - - ../../clusters/customization/network-config-with-networkd + - /docs/latest/setup/customization/network-config-with-networkd/ + - ../../os/network-config-with-networkd + - ../../clusters/customization/network-config-with-networkd --- Flatcar Container Linux machines are preconfigured with [networking customized][notes-for-distributors] for each platform. You can write your own networkd units to replace or override the units created for each platform. This article covers a subset of networkd functionality. You can view the [full docs here](http://www.freedesktop.org/software/systemd/man/systemd-networkd.service.html). @@ -174,7 +174,8 @@ $ ip -4 addr show dev eth0 valid_lft forever preferred_lft forever inet 10.0.1.101/24 brd 10.0.1.255 scope global secondary eth0 valid_lft forever preferred_lft forever - ``` +``` + By executing the command `ip -4 addr show dev `, you can obtain detailed information about the eth0 interface. The output includes the interface's state, such as whether it is UP or DOWN, its assigned IP addresses, the corresponding subnet masks, and other relevant details. ## Debugging networkd @@ -223,8 +224,8 @@ systemd: - [networkd full documentation](http://www.freedesktop.org/software/systemd/man/systemd-networkd.service.html) - [Getting Started with systemd](../systemd/getting-started) -- [Reading the System Log](../debug/reading-the-system-log) +- [Reading the System Log](../../diagnostics/reading-the-system-log) -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../../fb-provision/butane [drop-ins]: ../systemd/drop-in-units -[notes-for-distributors]: ../../installing/community-platforms/notes-for-distributors +[notes-for-distributors]: ../../deploy/virt-options/notes-for-distributors diff --git a/content/docs/latest/os-config/storage/iscsi.md b/content/docs/latest/os-config/storage/iscsi.md index fe881dd5a..a03b5672a 100644 --- a/content/docs/latest/os-config/storage/iscsi.md +++ b/content/docs/latest/os-config/storage/iscsi.md @@ -131,4 +131,4 @@ See the [mounting storage docs][mounting-storage] for an example. [iscsi-wiki]: https://en.wikipedia.org/wiki/ISCSI [mounting-storage]: mounting-storage -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../../fb-provision/butane diff --git a/content/docs/latest/os-config/storage/mounting-storage.md b/content/docs/latest/os-config/storage/mounting-storage.md index 3fb9cb0f5..b36bd6813 100644 --- a/content/docs/latest/os-config/storage/mounting-storage.md +++ b/content/docs/latest/os-config/storage/mounting-storage.md @@ -151,6 +151,6 @@ If the mount fails, dependent units will not start. Check the [`systemd mount` docs][systemd-mount-man] to learn about the available options. Examples specific to [EC2][ec2-disk], [Google Compute Engine][gcp-disk] can be used as a starting point. -[ec2-disk]: ../../installing/cloud/aws-ec2#instance-storage -[gcp-disk]: ../../installing/cloud/gcp#additional-storage +[ec2-disk]: ../../deploy/cloud/aws-ec2#instance-storage +[gcp-disk]: ../../deploy/cloud/gcp#additional-storage [systemd-mount-man]: http://www.freedesktop.org/software/systemd/man/systemd.mount.html diff --git a/content/docs/latest/os-config/storage/raid.md b/content/docs/latest/os-config/storage/raid.md index c1e250450..e86452adc 100644 --- a/content/docs/latest/os-config/storage/raid.md +++ b/content/docs/latest/os-config/storage/raid.md @@ -67,5 +67,5 @@ storage: * `/etc/mdadm.conf` cannot be used to configure a RAID array containing the root filesystem. * Since Ignition cannot modify the type GUID of existing partitions, the default `ROOT` partition cannot be reused as a component of a RAID array. A future version of Ignition will support resizing the `ROOT` partition and changing its type GUID, allowing it to be used as part of a RAID array. -[butane-configs]: ../../provisioning/config-transpiler -[partition-table]: ../../reference/developer-guides/sdk-disk-partitions/#partition-table +[butane-configs]: ../../fb-provision/butane +[partition-table]: ../../devguide/sdk-disk-partitions#partition-table diff --git a/content/docs/latest/os-config/systemd/getting-started.md b/content/docs/latest/os-config/systemd/getting-started.md index aaf1f52c5..68dea4c5a 100644 --- a/content/docs/latest/os-config/systemd/getting-started.md +++ b/content/docs/latest/os-config/systemd/getting-started.md @@ -4,9 +4,9 @@ linktitle: Getting Started description: An introduction to the most important systemd concepts used in Flatcar. weight: 10 aliases: - - /docs/latest/setup/systemd/getting-started/ - - ../../os/getting-started-with-systemd - - ../../clusters/management/getting-started-with-systemd + - /docs/latest/setup/systemd/getting-started/ + - ../../os/getting-started-with-systemd + - ../../clusters/management/getting-started-with-systemd --- systemd is an init system that provides many powerful features for starting, stopping, and managing processes. Within Flatcar Container Linux, you will almost exclusively use systemd to manage the lifecycle of your Docker containers. @@ -70,21 +70,21 @@ Feb 11 17:46:28 localhost docker[23470]: Hello World ``` - [Overview of systemctl](systemctl) -- [Reading the System Log](../debug/reading-the-system-log) +- [Reading the System Log](../../diagnostics/reading-the-system-log) ## Advanced unit files systemd provides a high degree of functionality in your unit files. Here's a curated list of useful features listed in the order they'll occur in the lifecycle of a unit: -| Name | Description | -|---------|-------------| -| ExecStartPre | Commands that will run before `ExecStart`. | -| ExecStart | Main commands to run for this unit. | -| ExecStartPost | Commands that will run after all `ExecStart` commands have completed. | -| ExecReload | Commands that will run when this unit is reloaded via `systemctl reload foo.service` | -| ExecStop | Commands that will run when this unit is considered failed or if it is stopped via `systemctl stop foo.service` | -| ExecStopPost | Commands that will run after `ExecStop` has completed. | -| RestartSec | The amount of time to sleep before restarting a service. Useful to prevent your failed service from attempting to restart itself every 100ms. | +| Name | Description | +| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| ExecStartPre | Commands that will run before `ExecStart`. | +| ExecStart | Main commands to run for this unit. | +| ExecStartPost | Commands that will run after all `ExecStart` commands have completed. | +| ExecReload | Commands that will run when this unit is reloaded via `systemctl reload foo.service` | +| ExecStop | Commands that will run when this unit is considered failed or if it is stopped via `systemctl stop foo.service` | +| ExecStopPost | Commands that will run after `ExecStop` has completed. | +| RestartSec | The amount of time to sleep before restarting a service. Useful to prevent your failed service from attempting to restart itself every 100ms. | The full list is located on the [systemd man page](http://www.freedesktop.org/software/systemd/man/systemd.service.html). @@ -126,12 +126,12 @@ While it's possible to manage the starting, stopping, and removal of the contain In our last example we had to hardcode our IP address when we announced our container in etcd. That's not scalable and systemd has a few variables built in to help us out. Here's a few of the most useful: -| Variable | Meaning | Description | -|----------|---------|-------------| -| `%n` | Full unit name | Useful if the name of your unit is unique enough to be used as an argument on a command. | -| `%m` | Machine ID | Useful for namespacing etcd keys by machine. Example: `/machines/%m/units` | -| `%b` | BootID | Similar to the machine ID, but this value is random and changes on each boot | -| `%H` | Hostname | Allows you to run the same unit file across many machines. Useful for service discovery. Example: `/domains/example.com/%H:8081` | +| Variable | Meaning | Description | +| -------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `%n` | Full unit name | Useful if the name of your unit is unique enough to be used as an argument on a command. | +| `%m` | Machine ID | Useful for namespacing etcd keys by machine. Example: `/machines/%m/units` | +| `%b` | BootID | Similar to the machine ID, but this value is random and changes on each boot | +| `%H` | Hostname | Allows you to run the same unit file across many machines. Useful for service discovery. Example: `/domains/example.com/%H:8081` | A full list of specifiers can be found on the [systemd man page](http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Specifiers). @@ -139,10 +139,10 @@ A full list of specifiers can be found on the [systemd man page](http://www.free Since systemd is based on symlinks, there are a few interesting tricks you can leverage that are very powerful when used with containers. If you create multiple symlinks to the same unit file, the following variables become available to you: -| Variable | Meaning | Description | -|----------|---------|-------------| -| `%p` | Prefix name | Refers to any string before `@` in your unit name. | -| `%i` | Instance name | Refers to the string between the `@` and the suffix. | +| Variable | Meaning | Description | +| -------- | ------------- | ---------------------------------------------------- | +| `%p` | Prefix name | Refers to any string before `@` in your unit name. | +| `%i` | Instance name | Refers to the string between the `@` and the suffix. | In our earlier example we had to hardcode our IP address when registering within etcd: diff --git a/content/docs/latest/os-config/systemd/udev-rules.md b/content/docs/latest/os-config/systemd/udev-rules.md index 18816be4b..a54298639 100644 --- a/content/docs/latest/os-config/systemd/udev-rules.md +++ b/content/docs/latest/os-config/systemd/udev-rules.md @@ -3,9 +3,9 @@ title: Using systemd and udev rules description: How to run units when specific udev events trigger. weight: 35 aliases: - - /docs/latest/setup/systemd/udev-rules/ - - ../../os/using-systemd-and-udev-rules - - ../../clusters/management/using-systemd-and-udev-rules + - /docs/latest/setup/systemd/udev-rules/ + - ../../os/using-systemd-and-udev-rules + - ../../clusters/management/using-systemd-and-udev-rules --- In our example we will use libvirt VM with Flatcar Container Linux and run systemd unit on disk attach event. First of all we have to create systemd unit file `/etc/systemd/system/device-attach.service`: @@ -75,13 +75,13 @@ systemd: For more systemd examples, check out these documents: - * [Customizing Docker][customizing-docker] - * [Customizing the SSH Daemon][customizing-sshd] - * [Using systemd Drop-In Units][drop-in] +- [Customizing Docker][customizing-docker] +- [Customizing the SSH Daemon][customizing-sshd] +- [Using systemd Drop-In Units][drop-in] [drop-in]: drop-in-units -[customizing-sshd]: ../security/customizing-sshd#changing-the-sshd-port -[customizing-docker]: ../../container-runtimes/customizing-docker#using-a-dockercfg-file-for-authentication +[customizing-sshd]: ../../security/cert-auth/customizing-sshd#changing-the-sshd-port +[customizing-docker]: ../../orchestrate/containers/customizing-docker#using-a-dockercfg-file-for-authentication ## More information diff --git a/content/docs/latest/security/cert-auth/customize-etcd-unit.md b/content/docs/latest/security/cert-auth/customize-etcd-unit.md index f46e7f473..a709816ec 100644 --- a/content/docs/latest/security/cert-auth/customize-etcd-unit.md +++ b/content/docs/latest/security/cert-auth/customize-etcd-unit.md @@ -3,9 +3,9 @@ title: Customizing the etcd unit description: How to setup etcd to use client certificates. weight: 50 aliases: - - /docs/latest/setup/customization/customize-etcd-unit/ - - ../../os/customize-etcd-unit - - ../../clusters/customization/customize-etcd-unit + - /docs/latest/setup/customization/customize-etcd-unit/ + - ../../os/customize-etcd-unit + - ../../clusters/customization/customize-etcd-unit --- The etcd systemd unit can be customized by overriding the unit that ships with the default Flatcar Container Linux settings. Common use-cases for doing this are covered below. @@ -22,21 +22,21 @@ Note that more etcd settings are needed for a proper configuration. variant: flatcar version: 1.0.0 systemd: - units: - - name: etcd-member.service - enabled: true - dropins: - - name: 20-clct-etcd-member.conf - contents: | - [Service] - ExecStart= - ExecStart=/usr/lib/coreos/etcd-wrapper $ETCD_OPTS \ - --ca-file="/path/to/CA.pem" \ - --cert-file="/path/to/server.crt" \ - --key-file="/path/to/server.key" \ - --peer-ca-file="/path/to/CA.pem" \ - --peer-cert-file="/path/to/peers.crt" \ - --peer-key-file="/path/to/peers.key" + units: + - name: etcd-member.service + enabled: true + dropins: + - name: 20-clct-etcd-member.conf + contents: | + [Service] + ExecStart= + ExecStart=/usr/lib/coreos/etcd-wrapper $ETCD_OPTS \ + --ca-file="/path/to/CA.pem" \ + --cert-file="/path/to/server.crt" \ + --key-file="/path/to/server.key" \ + --peer-ca-file="/path/to/CA.pem" \ + --peer-cert-file="/path/to/peers.crt" \ + --peer-key-file="/path/to/peers.key" storage: files: @@ -97,4 +97,4 @@ storage: -----END RSA PRIVATE KEY----- ``` -[self-signed-howto]: ../security/generate-self-signed-certificates +[self-signed-howto]: ./generate-self-signed-certificates diff --git a/content/docs/latest/security/cert-auth/customizing-sshd.md b/content/docs/latest/security/cert-auth/customizing-sshd.md index 80200c866..9541930c0 100644 --- a/content/docs/latest/security/cert-auth/customizing-sshd.md +++ b/content/docs/latest/security/cert-auth/customizing-sshd.md @@ -182,4 +182,4 @@ For more information about configuring Flatcar Container Linux hosts with `syste [systemd-getting-started]: ../systemd/getting-started [openssh-manual]: http://www.openssh.com/cgi-bin/man.cgi?query=sshd_config [mozilla-ssh-rec]: https://wiki.mozilla.org/Security/Guidelines/OpenSSH#Modern_.28OpenSSH_6.7.2B.29 -[butane-configs]: ../../provisioning/config-transpiler +[butane-configs]: ../../fb-provision/butane diff --git a/content/docs/latest/security/constants-and-ids.md b/content/docs/latest/security/constants-and-ids.md index b718b2855..d50bf86a4 100644 --- a/content/docs/latest/security/constants-and-ids.md +++ b/content/docs/latest/security/constants-and-ids.md @@ -2,8 +2,8 @@ title: Constants and IDs weight: 30 aliases: - - /docs/latest/reference/constants-and-ids/ - - ../os/constants-and-ids + - /docs/latest/reference/constants-and-ids/ + - ../os/constants-and-ids --- This document contains well-known constants and IDs used by Flatcar Container Linux. @@ -12,24 +12,24 @@ This document contains well-known constants and IDs used by Flatcar Container Li This UUID is used to identify Container Linux to the update service, i.e. as an `appid` over the [Omaha protocol][omaha]. -| Label | Value | Notes | -|------------------|----------------------------------------|-------| -| Container Linux | `e96281a6-d1af-4bde-9a0a-97b76e56dc57` | - | +| Label | Value | Notes | +| --------------- | -------------------------------------- | ----- | +| Container Linux | `e96281a6-d1af-4bde-9a0a-97b76e56dc57` | - | ## GPT partition types These GUIDs are dedicated [GPT partition types][GPT-types] for specific Container Linux usages. -| Label | Value | Notes | -|--------------------|----------------------------------------|-------| -| `coreos-usr` | `5dfbf5f4-2848-4bac-aa5e-0d9a20b745a6` | Alias for historical `coreos-rootfs`, currently used for `/usr` only | -| `coreos-resize` | `3884dd41-8582-4404-b9a8-e9b84f2df50e` | Support for auto-resizing via `extend-filesystems`, current default type for `/` | -| `coreos-reserved` | `c95dc21a-df0e-4340-8d7b-26cbfa9a03e0` | Reserved for OEM usage, support for customizations via `OEM-CONFIG` partition | +| Label | Value | Notes | +| ------------------ | -------------------------------------- | ----------------------------------------------------------------------------------------- | +| `coreos-usr` | `5dfbf5f4-2848-4bac-aa5e-0d9a20b745a6` | Alias for historical `coreos-rootfs`, currently used for `/usr` only | +| `coreos-resize` | `3884dd41-8582-4404-b9a8-e9b84f2df50e` | Support for auto-resizing via `extend-filesystems`, current default type for `/` | +| `coreos-reserved` | `c95dc21a-df0e-4340-8d7b-26cbfa9a03e0` | Reserved for OEM usage, support for customizations via `OEM-CONFIG` partition | | `coreos-root-raid` | `be9067b9-ea49-4f15-b4f6-f36f8c9e1818` | RAID partition containing a rootfs, see [notes][raid-storage] for details and limitations | For more information on the partitioning scheme used by Flatcar Container Linux, read the [disk layout][disk-layout] documentation. [omaha]: https://github.com/google/omaha/ [GPT-types]: https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs -[raid-storage]: ../setup/storage/raid -[disk-layout]: ../developer-guides/sdk-disk-partitions +[raid-storage]: ../os-config/storage/raid +[disk-layout]: ../devguide/sdk-disk-partitions diff --git a/content/docs/latest/sys-ext/_index.md b/content/docs/latest/sys-ext/_index.md index e5da970a8..343223e07 100644 --- a/content/docs/latest/sys-ext/_index.md +++ b/content/docs/latest/sys-ext/_index.md @@ -8,7 +8,7 @@ aliases: Flatcar Container Linux bundles various software components with fixed versions together into one release. For users that require a particular version of a software component this means that the software needs to be supplied out of band and overwrite the built-in software copy. -Another approach we recommended was to [store binaries in `/opt/bin`](../../container-runtimes/use-a-custom-docker-or-containerd-version/) and prefer them in the `PATH`. +Another approach we recommended was to [store binaries in `/opt/bin`](../orchestrate/containers/use-a-custom-docker-or-containerd-version/) and prefer them in the `PATH`. For long time already, the systemd project provided the portable services feature to address deploying custom services. However, since it only covered the service itself without making the client binaries available on the user, it didn't really fit the use case fully. @@ -198,8 +198,8 @@ To get more information about found incompatibilities during merging, enable the sudo SYSTEMD_LOG_LEVEL=debug systemd-sysext refresh ``` -[incusextension]: ../../container-runtimes/incus +[incusextension]: ../orchestrate/containers/incus [sysext-bakery]: https://flatcar.github.io/sysext-bakery -[nvidiaextension]: ../../setup/customization/using-nvidia -[overlaybdext]: ../../setup/customization/overlaybd-artifact-streaming -[zfsextension]: ../../setup/storage/zfs +[nvidiaextension]: ../os-config/host-config/using-nvidia +[overlaybdext]: ../os-config/network/overlaybd-artifact-streaming +[zfsextension]: ../os-config/storage/zfs diff --git a/content/docs/latest/updates-releases/releases/update-conf.md b/content/docs/latest/updates-releases/releases/update-conf.md index e92073524..efc66d128 100644 --- a/content/docs/latest/updates-releases/releases/update-conf.md +++ b/content/docs/latest/updates-releases/releases/update-conf.md @@ -10,7 +10,7 @@ aliases: - ../../clusters/management/update-conf --- -Flatcar Container Linux uses [`update_engine`][update_engine] to check and fetch new updates from the [Nebraska Update Service](../../nebraska). +Flatcar Container Linux uses [`update_engine`][update_engine] to check and fetch new updates from the [Nebraska Update Service](../nebraska). ## Location diff --git a/content/docs/latest/updates-releases/releases/update-strategies.md b/content/docs/latest/updates-releases/releases/update-strategies.md index 5f1e29a4e..b841680a5 100644 --- a/content/docs/latest/updates-releases/releases/update-strategies.md +++ b/content/docs/latest/updates-releases/releases/update-strategies.md @@ -3,9 +3,9 @@ title: Update and reboot strategies description: How to configure when you Flatcar instances should reboot. weight: 30 aliases: - - /docs/latest/setup/releases/update-strategies/ - - ../../os/update-strategies - - ../../clusters/creation/update-strategies + - /docs/latest/setup/releases/update-strategies/ + - ../../os/update-strategies + - ../../clusters/creation/update-strategies --- The overarching goal of Flatcar Container Linux is to secure the Internet's backend infrastructure. We believe that automatically updating the operating system is one of the best tools to achieve this goal. @@ -37,11 +37,11 @@ The `update-engine.service` responsible for downloading and applying the updates These locksmithd strategies control how a reboot occurs when update-engine indicates that one is needed: -| Strategy | Description | -|---------------|------------------------------------------------------------------------------| -| `etcd-lock` | Reboot after first taking a distributed lock in etcd (reboot window applies) | -| `reboot` | Reboot immediately after an update is applied (reboot window applies) | -| `off` | Do not reboot after updates are applied | +| Strategy | Description | +| ----------- | ---------------------------------------------------------------------------- | +| `etcd-lock` | Reboot after first taking a distributed lock in etcd (reboot window applies) | +| `reboot` | Reboot immediately after an update is applied (reboot window applies) | +| `off` | Do not reboot after updates are applied | You can configure a reboot window in which reboots are allowed to happen through one of the strategies. @@ -242,6 +242,7 @@ echo "$VER" # or if you know which version to update to, set it like VER=3033.2.1 (no channel info needed) wget "https://update.release.flatcar-linux.net/${ARCH}-usr/${VER}/flatcar_production_update.gz" ``` + If you run a Flatcar cloud vendor image that needs OEM tools, also download the `oem-NAME.gz` file from the subfolder in the above URL, same for Flatcar extensions which need the `flatcar-NAME.gz` files. On the airgapped machine (here with the file `flatcar_production_update.gz` in the current folder): @@ -348,9 +349,9 @@ storage: touch /run/reboot-required ``` -[ipxe-boot-script]: ../../installing/bare-metal/booting-with-ipxe#setting-up-ipxe-boot-script -[rollback]: ../debug/manual-rollbacks +[ipxe-boot-script]: ../../deploy/bare-metal/booting-with-ipxe#setting-up-ipxe-boot-script +[rollback]: ../../diagnostics/manual-rollbacks [reboot-windows]: https://github.com/flatcar/locksmith#reboot-windows -[systemd-env-vars]: ../systemd/environment-variables/#system-wide-environment-variables -[transpiler]: ../../provisioning/config-transpiler/ -[update-from-container-linux]: ../../migrating-from-coreos/update-from-container-linux +[systemd-env-vars]: ../../os-config/host-config/environment-variables/#system-wide-environment-variables +[transpiler]: ../../fb-provision/butane/ +[update-from-container-linux]: ../../coreos-migration/update-from-container-linux From e27d6716f66632f17d887fb75f45535ba8c02244 Mon Sep 17 00:00:00 2001 From: Jan Bronicki Date: Fri, 19 Jun 2026 00:24:54 +0200 Subject: [PATCH 05/20] docs: port main's OracleCloud/Rackspace updates to new virt-options index MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The restructure of the docs site re-created the section index at the new path (content/docs/latest/deploy/virt-options/_index.md) using the listing as it existed before main's recent changes. Apply main's edits — drop Rackspace, add OracleCloud — to the new index so it stays consistent with the rest of the site. Signed-off-by: Jan Bronicki --- .gitignore | 1 + content/docs/latest/deploy/virt-options/_index.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 771ac766e..76b0ffc24 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ themes/flatcar/yarn.lock themes/flatcar/static/css/.sass-cache external-docs/ resources/ +.hvm # Temporary lock file while building /.hugo_build.lock diff --git a/content/docs/latest/deploy/virt-options/_index.md b/content/docs/latest/deploy/virt-options/_index.md index 62f4cfd30..6fde75ba7 100644 --- a/content/docs/latest/deploy/virt-options/_index.md +++ b/content/docs/latest/deploy/virt-options/_index.md @@ -17,7 +17,7 @@ The platforms and providers listed below each provide support and documentation * [Exoscale][exoscale] * [OVHcloud][ovhcloud] -* [Rackspace Cloud][rackspace] +* [OracleCloud][oraclecloud] * [Scaleway][scaleway] * [VMWare][vmware] * [Vultr VPS][vultr] @@ -30,7 +30,6 @@ The platforms and providers listed below each provide support and documentation * [VirtualBox][virtualbox] [exoscale]: exoscale -[rackspace]: rackspace [vultr]: vultr [eucalyptus]: eucalyptus [scaleway]: scaleway @@ -38,5 +37,6 @@ The platforms and providers listed below each provide support and documentation [virtualbox]: ../vms/virtualbox [official-support]: ../../ [ovhcloud]: ovhcloud +[oraclecloud]: oraclecloud [proxmoxve]: proxmoxve [vmware]: vmware From 4fcb2f1347a55b2fe08505a096f415d7920ac10b Mon Sep 17 00:00:00 2001 From: Jan Bronicki Date: Fri, 19 Jun 2026 09:17:14 +0200 Subject: [PATCH 06/20] Add documentation for deploying Flatcar Container Linux on various virtualization platforms - Create new documentation for running Flatcar Container Linux on OpenStack. - Create new documentation for running Flatcar Container Linux on QEMU. - Create new documentation for running Flatcar Container Linux on Vagrant. - Create new documentation for running Flatcar Container Linux on VirtualBox. - Remove outdated virtual machines index documentation. Signed-off-by: Jan Bronicki --- .../{virt-options => cloud}/exoscale.md | 0 .../{virt-options => cloud}/oraclecloud.md | 0 .../{virt-options => cloud}/ovhcloud.md | 0 .../{virt-options => cloud}/scaleway.md | 0 .../deploy/{virt-options => cloud}/vultr.md | 0 .../vms => deploy/virt-options}/hyper-v.md | 0 .../vms => deploy/virt-options}/kubevirt.md | 0 .../vms => deploy/virt-options}/libvirt.md | 0 .../{cloud => virt-options}/openstack.md | 0 .../vms => deploy/virt-options}/qemu.md | 0 .../vms => deploy/virt-options}/vagrant.md | 0 .../vms => deploy/virt-options}/virtualbox.md | 0 .../docs/latest/fb-provision/vms/_index.md | 190 ------------------ 13 files changed, 190 deletions(-) rename content/docs/latest/deploy/{virt-options => cloud}/exoscale.md (100%) rename content/docs/latest/deploy/{virt-options => cloud}/oraclecloud.md (100%) rename content/docs/latest/deploy/{virt-options => cloud}/ovhcloud.md (100%) rename content/docs/latest/deploy/{virt-options => cloud}/scaleway.md (100%) rename content/docs/latest/deploy/{virt-options => cloud}/vultr.md (100%) rename content/docs/latest/{fb-provision/vms => deploy/virt-options}/hyper-v.md (100%) rename content/docs/latest/{fb-provision/vms => deploy/virt-options}/kubevirt.md (100%) rename content/docs/latest/{fb-provision/vms => deploy/virt-options}/libvirt.md (100%) rename content/docs/latest/deploy/{cloud => virt-options}/openstack.md (100%) rename content/docs/latest/{fb-provision/vms => deploy/virt-options}/qemu.md (100%) rename content/docs/latest/{fb-provision/vms => deploy/virt-options}/vagrant.md (100%) rename content/docs/latest/{fb-provision/vms => deploy/virt-options}/virtualbox.md (100%) delete mode 100644 content/docs/latest/fb-provision/vms/_index.md diff --git a/content/docs/latest/deploy/virt-options/exoscale.md b/content/docs/latest/deploy/cloud/exoscale.md similarity index 100% rename from content/docs/latest/deploy/virt-options/exoscale.md rename to content/docs/latest/deploy/cloud/exoscale.md diff --git a/content/docs/latest/deploy/virt-options/oraclecloud.md b/content/docs/latest/deploy/cloud/oraclecloud.md similarity index 100% rename from content/docs/latest/deploy/virt-options/oraclecloud.md rename to content/docs/latest/deploy/cloud/oraclecloud.md diff --git a/content/docs/latest/deploy/virt-options/ovhcloud.md b/content/docs/latest/deploy/cloud/ovhcloud.md similarity index 100% rename from content/docs/latest/deploy/virt-options/ovhcloud.md rename to content/docs/latest/deploy/cloud/ovhcloud.md diff --git a/content/docs/latest/deploy/virt-options/scaleway.md b/content/docs/latest/deploy/cloud/scaleway.md similarity index 100% rename from content/docs/latest/deploy/virt-options/scaleway.md rename to content/docs/latest/deploy/cloud/scaleway.md diff --git a/content/docs/latest/deploy/virt-options/vultr.md b/content/docs/latest/deploy/cloud/vultr.md similarity index 100% rename from content/docs/latest/deploy/virt-options/vultr.md rename to content/docs/latest/deploy/cloud/vultr.md diff --git a/content/docs/latest/fb-provision/vms/hyper-v.md b/content/docs/latest/deploy/virt-options/hyper-v.md similarity index 100% rename from content/docs/latest/fb-provision/vms/hyper-v.md rename to content/docs/latest/deploy/virt-options/hyper-v.md diff --git a/content/docs/latest/fb-provision/vms/kubevirt.md b/content/docs/latest/deploy/virt-options/kubevirt.md similarity index 100% rename from content/docs/latest/fb-provision/vms/kubevirt.md rename to content/docs/latest/deploy/virt-options/kubevirt.md diff --git a/content/docs/latest/fb-provision/vms/libvirt.md b/content/docs/latest/deploy/virt-options/libvirt.md similarity index 100% rename from content/docs/latest/fb-provision/vms/libvirt.md rename to content/docs/latest/deploy/virt-options/libvirt.md diff --git a/content/docs/latest/deploy/cloud/openstack.md b/content/docs/latest/deploy/virt-options/openstack.md similarity index 100% rename from content/docs/latest/deploy/cloud/openstack.md rename to content/docs/latest/deploy/virt-options/openstack.md diff --git a/content/docs/latest/fb-provision/vms/qemu.md b/content/docs/latest/deploy/virt-options/qemu.md similarity index 100% rename from content/docs/latest/fb-provision/vms/qemu.md rename to content/docs/latest/deploy/virt-options/qemu.md diff --git a/content/docs/latest/fb-provision/vms/vagrant.md b/content/docs/latest/deploy/virt-options/vagrant.md similarity index 100% rename from content/docs/latest/fb-provision/vms/vagrant.md rename to content/docs/latest/deploy/virt-options/vagrant.md diff --git a/content/docs/latest/fb-provision/vms/virtualbox.md b/content/docs/latest/deploy/virt-options/virtualbox.md similarity index 100% rename from content/docs/latest/fb-provision/vms/virtualbox.md rename to content/docs/latest/deploy/virt-options/virtualbox.md diff --git a/content/docs/latest/fb-provision/vms/_index.md b/content/docs/latest/fb-provision/vms/_index.md deleted file mode 100644 index df4ebd1ff..000000000 --- a/content/docs/latest/fb-provision/vms/_index.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: Virtual Machines -linktitle: Virtual Machines -weight: 40 -aliases: - - /docs/latest/installing/vms/vagrant/ - - ../../os/booting-on-vagrant - - ../../cloud-providers/booting-on-vagrant ---- - -_While we always welcome community contributions and fixes, please note that Vagrant is not an officially supported platform at this time. (See the [platform overview](/#installing-flatcar).)_ - -Running Flatcar Container Linux with Vagrant is one way to bring up a single machine or virtualize an entire cluster on your laptop. Since the true power of Flatcar Container Linux can be seen with a cluster, we're going to concentrate on that. Instructions for a single machine can be found [towards the end](#single-machine) of the guide. - -You can direct questions to the [Discord server][discord] or [mailing list][flatcar-dev]. - -## Install Vagrant and VirtualBox - -Vagrant is a simple-to-use command line virtual machine manager. There are install packages available for Windows, Linux and OS X. Find the latest installer on the [Vagrant downloads page][vagrant]. Be sure to get version 2.0.4 or greater, to be able to detect Flatcar images correctly. - -[vagrant]: http://www.vagrantup.com/downloads.html - -Vagrant can use either the free VirtualBox provider or the commercial VMware provider. Instructions for both are below. For the VirtualBox provider, version 4.3.10 or greater is required. - -## Install Flatcar Container Linux - -You can import the flatcar box and boot it with Vagrant. -You'll find it in `https://${CHANNEL}.release.flatcar-linux.net/amd64-usr/${VERSION}/flatcar_production_vagrant.box`. -Make sure you download the signature (it's available in `https://${CHANNEL}.release.flatcar-linux.net/amd64-usr/${VERSION}/flatcar_production_vagrant.box.sig`) and check it before proceeding. - -For example, to get the latest alpha: - -```shell -$ wget https://alpha.release.flatcar-linux.net/amd64-usr/current/flatcar_production_vagrant.box -$ wget https://alpha.release.flatcar-linux.net/amd64-usr/current/flatcar_production_vagrant.box.sig -$ gpg --verify flatcar_production_vagrant.box.sig -gpg: assuming signed data in 'flatcar_production_vagrant.box' -gpg: Signature made Thu 15 Mar 2018 10:29:23 AM CET -gpg: using RSA key A621F1DA96C93C639506832D603443A1D0FC498C -gpg: Good signature from "Flatcar Buildbot (Official Builds) " [ultimate] -$ vagrant box add flatcar-alpha flatcar_production_vagrant.box -==> box: Box file was not detected as metadata. Adding it directly... -==> box: Adding box 'flatcar-alpha' (v0) for provider: - box: Unpacking necessary files from: file:///tmp/flatcar_production_vagrant.box -==> box: Successfully added box 'flatcar-alpha' (v0) for 'virtualbox'! -$ vagrant init flatcar-alpha -A `Vagrantfile` has been placed in this directory. You are now -ready to `vagrant up` your first virtual environment! Please read -the comments in the Vagrantfile as well as documentation on -`vagrantup.com` for more information on using Vagrant. -$ vagrant up -Bringing machine 'default' up with 'virtualbox' provider... -==> default: Importing base box 'flatcar-alpha'... -==> default: Matching MAC address for NAT networking... -==> default: Setting the name of the VM: vagrant_default_1520510346048_14823 -==> default: Clearing any previously set network interfaces... -==> default: Preparing network interfaces based on configuration... - default: Adapter 1: nat -==> default: Forwarding ports... - default: 22 (guest) => 2222 (host) (adapter 1) -==> default: Running 'pre-boot' VM customizations... -==> default: Booting VM... -==> default: Waiting for machine to boot. This may take a few minutes... - default: SSH address: 127.0.0.1:2222 - default: SSH username: core - default: SSH auth method: private key -==> default: Machine booted and ready! -$ vagrant ssh -Last login: Thu Mar 15 17:02:25 UTC 2018 from 10.0.2.2 on ssh -Flatcar Container Linux by Kinvolk alpha (1702.1.0) -core@localhost ~ $ -``` - -## Starting a cluster - -You can configure your Vagrant machine by having a `Vagrantfile` example file: - -```ruby -ENV["TERM"] = "xterm-256color" -ENV["LC_ALL"] = "en_US.UTF-8" - -Vagrant.require_version '>= 2.0.4' - -Vagrant.configure('2') do |config| - config.ssh.username = 'core' - config.ssh.insert_key = true - config.vm.box = 'flatcar-alpha' - config.vm.synced_folder '.', '/vagrant', disabled: true - config.vm.provider :virtualbox do |v| - v.check_guest_additions = false - v.functional_vboxsf = false - v.cpus = 2 - v.memory = 2048 - end - config.vm.define 'core-01' do |c| - end - config.vm.define 'core-02' do |c| - end - config.vm.define 'core-03' do |c| - end -end -``` - -### Start machines using Vagrant's default VirtualBox provider - -Start the machine(s): - -```shell -vagrant up -``` - -List the status of the running machines: - -```shell -$ vagrant status -Current machine states: - -core-01 running (virtualbox) -core-02 running (virtualbox) -core-03 running (virtualbox) - -This environment represents multiple VMs. The VMs are all listed -above with their current state. For more information about a specific -VM, run `vagrant status NAME`. -``` - -Connect to one of the machines: - -```shell -vagrant ssh core-01 -- -A -``` - -### Start machines using Vagrant's VMware provider - -If you have purchased the [VMware Vagrant provider](http://www.vagrantup.com/vmware), run the following commands: - -```shell -vagrant up --provider vmware_fusion -vagrant ssh core-01 -- -A -``` - -## Single machine - -To start a single machine, we need to provide some config parameters in cloud-config format via the `user-data` file. - -Start the machine: - -```shell -vagrant up -``` - -Connect to the machine: - -```shell -vagrant ssh core-01 -- -A -``` - -## Shared folder setup - -Optionally, you can share a folder from your laptop into the virtual machine. This is useful for easily getting code and Dockerfiles into Flatcar Container Linux. - -```ini -config.vm.synced_folder ".", "/home/core/share", id: "core", :nfs => true, :mount_options => ['nolock,vers=3,udp'] -``` - -After a 'vagrant reload' you will be prompted for your local machine password. - -## New box versions - -Flatcar Container Linux is a rolling release distribution and versions that are out of date will automatically update. If you want to start from the most up to date version you will need to make sure that you have the latest box file of Flatcar Container Linux. You can do this using `vagrant box update` - or, simply remove the old box file and Vagrant will download the latest one the next time you `vagrant up`. - -```shell -vagrant box remove flatcar-alpha vmware_fusion -vagrant box remove flatcar-alpha virtualbox -``` - -If you'd like to download the box separately, you can download the URL contained in the Vagrantfile and add it manually: - -```shell -vagrant box add flatcar-alpha -``` - -## Using Flatcar Container Linux - -Now that you have a machine booted it is time to play around. Check out the [Flatcar Container Linux Quickstart][quickstart] guide, learn about [CoreOS Container Linux clustering with Vagrant](https://coreos.com/blog/coreos-clustering-with-vagrant/), or dig into [more specific topics][doc-index]. - -[flatcar-dev]: https://groups.google.com/forum/#!forum/flatcar-linux-dev -[discord]: https://discord.gg/PMYjFUsJyq -[quickstart]: ../ -[doc-index]: ../../ From 29068c633b232dc186c158573cd463b2c6a636a3 Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Tue, 30 Jun 2026 00:16:55 -0700 Subject: [PATCH 07/20] move links to cloud providers Signed-off-by: Seth McEvoy --- content/docs/latest/deploy/cloud/_index.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/content/docs/latest/deploy/cloud/_index.md b/content/docs/latest/deploy/cloud/_index.md index 1882f04cd..576826fba 100644 --- a/content/docs/latest/deploy/cloud/_index.md +++ b/content/docs/latest/deploy/cloud/_index.md @@ -8,3 +8,21 @@ aliases: - /docs/latest/installing/cloud/ - ../cloud-providers --- + +### Cloud Providers + +Flatcar runs on these Cloud Providers: + + * [Amazon EC2][ec2] + * [Microsoft Azure][azure] + * [Google Compute Engine][gce] + * [VMware][vmware] + * [DigitalOcean][digital-ocean] + * [Hetzner][hetzner] + * [OpenStack][openstack] + * [Brightbox][brightbox] + * [Scaleway][scaleway] (community support) + * [OracleCloud][oraclecloud] (community support) + * [OVHcloud][ovhcloud] (community support) + * [Akamai/Linode][akamai] + * [STACKIT][stackit] From a145a34c5c13372ee060433f045a321c0937b8db Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Tue, 30 Jun 2026 00:46:23 -0700 Subject: [PATCH 08/20] move links to virtualizatin options Signed-off-by: Seth McEvoy --- .../docs/latest/deploy/virt-options/_index.md | 27 +++++++------------ 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/content/docs/latest/deploy/virt-options/_index.md b/content/docs/latest/deploy/virt-options/_index.md index 6fde75ba7..9be33db0a 100644 --- a/content/docs/latest/deploy/virt-options/_index.md +++ b/content/docs/latest/deploy/virt-options/_index.md @@ -9,8 +9,6 @@ aliases: The Flatcar Container Linux community has provided support for Flatcar Container Linux on a number of platforms beyond those [officially supported][official-support] (i.e, fully covered in the automated tests) by Kinvolk. - - The platforms and providers listed below each provide support and documentation for running Flatcar Container Linux: ## Cloud providers @@ -25,18 +23,13 @@ The platforms and providers listed below each provide support and documentation ## Other providers * [Eucalyptus][eucalyptus] -* [Proxmox VE][proxmoxve] -* [Vagrant][vagrant] -* [VirtualBox][virtualbox] - -[exoscale]: exoscale -[vultr]: vultr -[eucalyptus]: eucalyptus -[scaleway]: scaleway -[vagrant]: ../vms/vagrant -[virtualbox]: ../vms/virtualbox -[official-support]: ../../ -[ovhcloud]: ovhcloud -[oraclecloud]: oraclecloud -[proxmoxve]: proxmoxve -[vmware]: vmware + +## Flatcar provides the following Virtualization Options: + + * [QEMU][qemu] + * [libVirt][libvirt] + * [VirtualBox][virtualbox] (community support) + * [Vagrant][vagrant] (community support) + * [Hyper-V][hyper-v] (community support) + * [KubeVirt][kubevirt] (community support) + * [Proxmox VE][proxmoxve] (community support) From 90be49037543d2c08c6438f871f3fe71fb6335ff Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Tue, 30 Jun 2026 01:03:11 -0700 Subject: [PATCH 09/20] move links to bare metal Signed-off-by: Seth McEvoy --- content/docs/latest/deploy/bare-metal/_index.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/content/docs/latest/deploy/bare-metal/_index.md b/content/docs/latest/deploy/bare-metal/_index.md index 4cec1840f..d794d780d 100644 --- a/content/docs/latest/deploy/bare-metal/_index.md +++ b/content/docs/latest/deploy/bare-metal/_index.md @@ -6,3 +6,15 @@ aliases: - /docs/latest/installing/bare-metal/ - ../bare-metal --- + +You can install Flatcar on bare metal machines in different ways: using ISO +images, booting from PXE or iPXE, and even by running an installation +script on an existing Linux system. + + * [Installing from ISO images][boot-iso] + * [Booting with PXE][pxe] + * [Booting with iPXE][ipxe] + * [Installing with flatcar-install][install-to-disk] + * [ Raspberry Pi 4][running-flatcar-container-linux-on-raspberry-Pi-4] + + \ No newline at end of file From 228b44ae411e0d241942fcf2a6d3b4fe749742fb Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Tue, 30 Jun 2026 01:22:18 -0700 Subject: [PATCH 10/20] move links to image customization Signed-off-by: Seth McEvoy --- .../fb-provision/customize-image/_index.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/content/docs/latest/fb-provision/customize-image/_index.md b/content/docs/latest/fb-provision/customize-image/_index.md index 1273d2a71..b61cd6d83 100644 --- a/content/docs/latest/fb-provision/customize-image/_index.md +++ b/content/docs/latest/fb-provision/customize-image/_index.md @@ -7,3 +7,19 @@ weight: 35 aliases: - /docs/latest/installing/customizing-the-image/ --- + +Customize Flatcar images using these techniques: + + * [Using networkd to customize networking][networkd-customize] + * [Using systemd drop-in units][systemd-drop-in] + * [Using environment variables in systemd units][environment-variables-systemd] + * [Using systemd and udev rules][udev-rules] + * [Using NVIDIA GPUs on Flatcar][using-nvidia] + * [Scheduling tasks with systemd timers][tasks-with-systemd] + * [Configuring DNS][dns] + * [Configuring date & timezone][date-timezone] + * [Adding users][users] + * [Kernel modules / sysctl parameters][parameters] + * [Adding swap][swap] + * [Power management][power-management] + * [ACPI][acpi] From f3cee24c66ae9e044c65b2f54d1f88dcd5a6e005 Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Tue, 30 Jun 2026 01:39:39 -0700 Subject: [PATCH 11/20] move links to updates and releases Signed-off-by: Seth McEvoy --- content/docs/latest/updates-releases/_index.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/content/docs/latest/updates-releases/_index.md b/content/docs/latest/updates-releases/_index.md index 70cd83b01..b59636af6 100644 --- a/content/docs/latest/updates-releases/_index.md +++ b/content/docs/latest/updates-releases/_index.md @@ -13,3 +13,12 @@ aliases: Nebraska is an update manager for [Flatcar Container Linux](https://flatcar.org/). It offers an easy way to monitor and manage the rollout of updates to applications that use the Omaha protocol, with special functionality for Flatcar Container Linux updates. + +Manage releases and updates with these techniques: + + * [Switching release channels][release-channels] + * [Configuring the update strategy][update-strategies] + * [Flatcar update configuration specification][update-conf] + * [Verifying Flatcar Images with GPG][verify-container-linux] + * [Nebraska][nebraska] + From c386d8bc8d80aa1cc70e9635a63a3d29987367a3 Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Tue, 30 Jun 2026 01:50:46 -0700 Subject: [PATCH 12/20] move links to managing clusters Signed-off-by: Seth McEvoy --- content/docs/latest/orchestrate/clusters/_index.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/content/docs/latest/orchestrate/clusters/_index.md b/content/docs/latest/orchestrate/clusters/_index.md index 890568348..f59bd2a27 100644 --- a/content/docs/latest/orchestrate/clusters/_index.md +++ b/content/docs/latest/orchestrate/clusters/_index.md @@ -9,3 +9,9 @@ weight: 40 aliases: - /docs/latest/setup/clusters/ --- + +Manage clusters with these technologies: + + * [Cluster architectures][cluster-architectures] + * [Clustering machines][clustering-machines] + * [Using Amazon EC2 Container Service][ec2-container-service] From 0baed67b565e01c1bb706a14262dc0c6bf19c8d4 Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Tue, 30 Jun 2026 02:01:31 -0700 Subject: [PATCH 13/20] move links to storage setup Signed-off-by: Seth McEvoy --- content/docs/latest/os-config/storage/_index.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/content/docs/latest/os-config/storage/_index.md b/content/docs/latest/os-config/storage/_index.md index d3fab592e..6c16922a0 100644 --- a/content/docs/latest/os-config/storage/_index.md +++ b/content/docs/latest/os-config/storage/_index.md @@ -7,3 +7,12 @@ aliases: - /docs/latest/setup/storage/ - ../clusters/scaling/ --- + +Manage storage systems with these technologies: + + * [Using RAID for the root filesystem][filesystem-placement] + * [Adding disk space][disk-space] + * [Mounting storage][mounting-storage] + * [iSCSI configuration][iscsi] + * [ZFS Extension][zfsextension] + From a309937c2069159c660fe43733a89ad666b52a75 Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Tue, 30 Jun 2026 02:11:12 -0700 Subject: [PATCH 14/20] move links to security Signed-off-by: Seth McEvoy --- content/docs/latest/security/_index.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/content/docs/latest/security/_index.md b/content/docs/latest/security/_index.md index 1cb6664dd..73b58f41a 100644 --- a/content/docs/latest/security/_index.md +++ b/content/docs/latest/security/_index.md @@ -4,3 +4,16 @@ weight: 90 description: > Security hardening, encryption, and authentication for Flatcar Container Linux. --- + +See these technologies for Flatcar security options: + + * [Setting up LUKS disk encryption][luks-encryption] + * [Customizing the SSH daemon][ssh-daemon] + * [Configuring SSSD on Flatcar Container Linux][sssd-container-linux] + * [Hardening a Flatcar Container Linux machine][hardening-container-linux] + * [Trusted Computing Hardware Requirements][hardware-requirements] + * [Adding Cert Authorities][cert-authorities] + * [Using SELinux][selinux] + * [Disabling SMT][disabling-smt] + * [Enabling FIPS][enabling-fips] + * [Using the audit subsystem][audit-system] From add2a71ca9158caf187c272d9cda7247ad862bfe Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Tue, 30 Jun 2026 02:30:25 -0700 Subject: [PATCH 15/20] move links to debugging Signed-off-by: Seth McEvoy --- content/docs/latest/diagnostics/_index.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/content/docs/latest/diagnostics/_index.md b/content/docs/latest/diagnostics/_index.md index 417ab85cd..4145be526 100644 --- a/content/docs/latest/diagnostics/_index.md +++ b/content/docs/latest/diagnostics/_index.md @@ -7,3 +7,11 @@ weight: 70 aliases: - /docs/latest/setup/debug/ --- + +Use the following tools to diagnose and debug Flatcar: + + * [Install debugging tools][debugging-tools] + * [Working with btrfs][btrfs] + * [Reading the system log][system-log] + * [Collecting crash logs][crash-log] + * [Manual Flatcar Container Linux rollbacks][container-linux-rollbacks] From cee2ed1dab9be74cd56e82af90871ea514b7b723 Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Tue, 30 Jun 2026 02:44:20 -0700 Subject: [PATCH 16/20] move links to container runtimes Signed-off-by: Seth McEvoy --- content/docs/latest/orchestrate/_index.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/content/docs/latest/orchestrate/_index.md b/content/docs/latest/orchestrate/_index.md index 7c692d41a..4bf71603f 100644 --- a/content/docs/latest/orchestrate/_index.md +++ b/content/docs/latest/orchestrate/_index.md @@ -4,3 +4,17 @@ weight: 60 description: > Manage clusters, Kubernetes, and container runtimes on Flatcar Container Linux. --- + +Flatcar Container Linux supports all of the popular methods for running +containers, and you can choose to interact with the containers at a +low-level, or use a higher level orchestration framework. Listed below are +some guides to help you choose and make use of the different runtimes. + + * [Getting started with Docker][docker] + * [Customizing Docker][customizing-docker] + * [Using systemd to manage Docker containers][manage-docker-containers] + * [Use a custom Docker or containerd version][use-a-custom-docker-or-containerd-version] + * [Authenticating to Container registries][registry-authentication] + * [Getting started with Kubernetes][kubernetes] + * [High availability Kubernetes][ha-kubernetes] + From 9b49c72ceb89b05d2411005df53a35711e7d8f8a Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Tue, 30 Jun 2026 02:59:07 -0700 Subject: [PATCH 17/20] move links to dev guide Signed-off-by: Seth McEvoy --- content/docs/latest/devguide/_index.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/content/docs/latest/devguide/_index.md b/content/docs/latest/devguide/_index.md index d155a5330..46bb28614 100644 --- a/content/docs/latest/devguide/_index.md +++ b/content/docs/latest/devguide/_index.md @@ -20,6 +20,14 @@ We also provide OEM functionality for cloud providers and similar use cases to c - [Kola integration testing framework][mantle-utils] - [Release guide][release-guide] +### APIs and troubleshooting guides for working with Flatcar Container Linux. + +* [Developer guides][developer-guides]: Comprehensive guides on developing for Flatcar, working with the SDK, and on building and extending OS images. +* [Integrations][integrations] +* [Migrating from cloud-config to Container Linux Config][migrating-from-cloud-config] +* [Flatcar Supply Chain Security (SLSA and SPDX SBOM)][supply-chain-security] detailing security mechanisms employed at build / release time as well as at run-time to ensure validity of inputs processed and outputs shipped. + + [sdk-tips]: sdk-tips-and-tricks [disk-layout]: sdk-disk-partitions [production-images]: sdk-building-production-images From 2d9ea7f2b65fb4174cff82df138e28a7e7a68994 Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Tue, 30 Jun 2026 03:04:03 -0700 Subject: [PATCH 18/20] move links to dev guides part two Signed-off-by: Seth McEvoy --- content/docs/latest/devguide/_index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/docs/latest/devguide/_index.md b/content/docs/latest/devguide/_index.md index 46bb28614..20ff6a53f 100644 --- a/content/docs/latest/devguide/_index.md +++ b/content/docs/latest/devguide/_index.md @@ -27,6 +27,8 @@ We also provide OEM functionality for cloud providers and similar use cases to c * [Migrating from cloud-config to Container Linux Config][migrating-from-cloud-config] * [Flatcar Supply Chain Security (SLSA and SPDX SBOM)][supply-chain-security] detailing security mechanisms employed at build / release time as well as at run-time to ensure validity of inputs processed and outputs shipped. +- + [sdk-tips]: sdk-tips-and-tricks [disk-layout]: sdk-disk-partitions From 29215157f62f6b72d4e9b8bdf8eb183e970df7f0 Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Tue, 30 Jun 2026 03:07:05 -0700 Subject: [PATCH 19/20] move links to developer guides mixed in Signed-off-by: Seth McEvoy --- content/docs/latest/devguide/_index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/docs/latest/devguide/_index.md b/content/docs/latest/devguide/_index.md index 20ff6a53f..fdba8ba28 100644 --- a/content/docs/latest/devguide/_index.md +++ b/content/docs/latest/devguide/_index.md @@ -27,7 +27,6 @@ We also provide OEM functionality for cloud providers and similar use cases to c * [Migrating from cloud-config to Container Linux Config][migrating-from-cloud-config] * [Flatcar Supply Chain Security (SLSA and SPDX SBOM)][supply-chain-security] detailing security mechanisms employed at build / release time as well as at run-time to ensure validity of inputs processed and outputs shipped. -- [sdk-tips]: sdk-tips-and-tricks From 74fdd7b2dce55cce6e7f7186e9e7bb31da3a24ef Mon Sep 17 00:00:00 2001 From: Jan Bronicki Date: Tue, 30 Jun 2026 13:39:52 +0200 Subject: [PATCH 20/20] Update content/docs/latest/deploy/bare-metal/_index.md Signed-off-by: Jan Bronicki --- content/docs/latest/deploy/bare-metal/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/latest/deploy/bare-metal/_index.md b/content/docs/latest/deploy/bare-metal/_index.md index d794d780d..35c36f21b 100644 --- a/content/docs/latest/deploy/bare-metal/_index.md +++ b/content/docs/latest/deploy/bare-metal/_index.md @@ -15,6 +15,6 @@ script on an existing Linux system. * [Booting with PXE][pxe] * [Booting with iPXE][ipxe] * [Installing with flatcar-install][install-to-disk] - * [ Raspberry Pi 4][running-flatcar-container-linux-on-raspberry-Pi-4] + * [Raspberry Pi 4][running-flatcar-container-linux-on-raspberry-Pi-4] \ No newline at end of file