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/.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/_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/_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/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/migrating-from-coreos/_index.md b/content/docs/latest/coreos-migration/_index.md similarity index 96% rename from content/docs/latest/migrating-from-coreos/_index.md rename to content/docs/latest/coreos-migration/_index.md index 694d00915..b94dd7db9 100644 --- a/content/docs/latest/migrating-from-coreos/_index.md +++ b/content/docs/latest/coreos-migration/_index.md @@ -1,9 +1,10 @@ --- title: Migration from CoreOS Container Linux linktitle: Migrating from CoreOS -weight: 110 +weight: 100 aliases: - - os/migrate-from-container-linux + - /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. 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 96% 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..136cb971a 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 --- @@ -109,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/_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..35c36f21b --- /dev/null +++ b/content/docs/latest/deploy/bare-metal/_index.md @@ -0,0 +1,20 @@ +--- +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 +--- + +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 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 96% 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..4e21381fc 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 --- @@ -161,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/installing/bare-metal/booting-with-iso.md b/content/docs/latest/deploy/bare-metal/booting-with-iso.md similarity index 97% 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..95eaafdb2 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 --- @@ -62,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/installing/bare-metal/booting-with-pxe.md b/content/docs/latest/deploy/bare-metal/booting-with-pxe.md similarity index 97% 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..636ab78d3 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 --- @@ -249,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/installing/bare-metal/installing-to-disk.md b/content/docs/latest/deploy/bare-metal/installing-to-disk.md similarity index 97% 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..2255e8124 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 --- @@ -171,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/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/deploy/cloud/_index.md b/content/docs/latest/deploy/cloud/_index.md new file mode 100644 index 000000000..576826fba --- /dev/null +++ b/content/docs/latest/deploy/cloud/_index.md @@ -0,0 +1,28 @@ +--- +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 +--- + +### 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] 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 98% rename from content/docs/latest/installing/cloud/aws-ec2.md rename to content/docs/latest/deploy/cloud/aws-ec2.md index 15bd2c2b0..f180aa126 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 --- @@ -123,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 @@ -217,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. @@ -498,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/installing/cloud/azure.md b/content/docs/latest/deploy/cloud/azure.md similarity index 98% rename from content/docs/latest/installing/cloud/azure.md rename to content/docs/latest/deploy/cloud/azure.md index 536c1b86f..a6ba97e54 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 --- @@ -428,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. @@ -632,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`: @@ -754,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/installing/cloud/brightbox.md b/content/docs/latest/deploy/cloud/brightbox.md similarity index 97% rename from content/docs/latest/installing/cloud/brightbox.md rename to content/docs/latest/deploy/cloud/brightbox.md index 425256f15..37c3795e5 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. @@ -106,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/installing/cloud/digitalocean.md b/content/docs/latest/deploy/cloud/digitalocean.md similarity index 98% rename from content/docs/latest/installing/cloud/digitalocean.md rename to content/docs/latest/deploy/cloud/digitalocean.md index 642fa01d6..073ee01cf 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 --- @@ -46,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 @@ -199,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. @@ -382,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/installing/community-platforms/exoscale.md b/content/docs/latest/deploy/cloud/exoscale.md similarity index 97% rename from content/docs/latest/installing/community-platforms/exoscale.md rename to content/docs/latest/deploy/cloud/exoscale.md index b0f0a4416..8e2cbaa52 100644 --- a/content/docs/latest/installing/community-platforms/exoscale.md +++ b/content/docs/latest/deploy/cloud/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 --- @@ -14,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/installing/cloud/gcp.md b/content/docs/latest/deploy/cloud/gcp.md similarity index 97% rename from content/docs/latest/installing/cloud/gcp.md rename to content/docs/latest/deploy/cloud/gcp.md index edc69a482..74cb93a01 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 --- @@ -98,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 @@ -299,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/installing/cloud/hetzner.md b/content/docs/latest/deploy/cloud/hetzner.md similarity index 97% rename from content/docs/latest/installing/cloud/hetzner.md rename to content/docs/latest/deploy/cloud/hetzner.md index ff6010bbe..89fb4acce 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 --- @@ -185,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 @@ -201,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/installing/community-platforms/oraclecloud.md b/content/docs/latest/deploy/cloud/oraclecloud.md similarity index 100% rename from content/docs/latest/installing/community-platforms/oraclecloud.md rename to content/docs/latest/deploy/cloud/oraclecloud.md diff --git a/content/docs/latest/installing/community-platforms/ovhcloud.md b/content/docs/latest/deploy/cloud/ovhcloud.md similarity index 98% rename from content/docs/latest/installing/community-platforms/ovhcloud.md rename to content/docs/latest/deploy/cloud/ovhcloud.md index 19e484a63..94eba5b8c 100644 --- a/content/docs/latest/installing/community-platforms/ovhcloud.md +++ b/content/docs/latest/deploy/cloud/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. @@ -138,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/installing/community-platforms/scaleway.md b/content/docs/latest/deploy/cloud/scaleway.md similarity index 97% rename from content/docs/latest/installing/community-platforms/scaleway.md rename to content/docs/latest/deploy/cloud/scaleway.md index 6587249f6..2b37f8185 100644 --- a/content/docs/latest/installing/community-platforms/scaleway.md +++ b/content/docs/latest/deploy/cloud/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. @@ -111,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/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 97% rename from content/docs/latest/installing/community-platforms/vmware.md rename to content/docs/latest/deploy/cloud/vmware.md index 4d6b1d2f7..d55a3938b 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 --- @@ -163,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`: @@ -315,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. @@ -357,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]: ../../ @@ -368,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/installing/community-platforms/vultr.md b/content/docs/latest/deploy/cloud/vultr.md similarity index 97% rename from content/docs/latest/installing/community-platforms/vultr.md rename to content/docs/latest/deploy/cloud/vultr.md index 7dd93a704..18394b227 100644 --- a/content/docs/latest/installing/community-platforms/vultr.md +++ b/content/docs/latest/deploy/cloud/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 --- @@ -136,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/installing/community-platforms/_index.md b/content/docs/latest/deploy/virt-options/_index.md similarity index 61% rename from content/docs/latest/installing/community-platforms/_index.md rename to content/docs/latest/deploy/virt-options/_index.md index 1ec500cd4..9be33db0a 100644 --- a/content/docs/latest/installing/community-platforms/_index.md +++ b/content/docs/latest/deploy/virt-options/_index.md @@ -1,15 +1,14 @@ --- -title: Community supported platforms +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 @@ -24,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 -[proxmoxve]: proxmoxve -[vmware]: vmware -[oraclecloud]: oraclecloud + +## 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) diff --git a/content/docs/latest/installing/community-platforms/eucalyptus.md b/content/docs/latest/deploy/virt-options/eucalyptus.md similarity index 97% rename from content/docs/latest/installing/community-platforms/eucalyptus.md rename to content/docs/latest/deploy/virt-options/eucalyptus.md index 353959e49..56c198f9b 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 --- @@ -104,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/installing/vms/hyper-v.md b/content/docs/latest/deploy/virt-options/hyper-v.md similarity index 97% rename from content/docs/latest/installing/vms/hyper-v.md rename to content/docs/latest/deploy/virt-options/hyper-v.md index 10c98b01d..9a62050ef 100644 --- a/content/docs/latest/installing/vms/hyper-v.md +++ b/content/docs/latest/deploy/virt-options/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).)_ @@ -156,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/installing/vms/kubevirt.md b/content/docs/latest/deploy/virt-options/kubevirt.md similarity index 98% rename from content/docs/latest/installing/vms/kubevirt.md rename to content/docs/latest/deploy/virt-options/kubevirt.md index 6f63cca59..f36c08bd2 100644 --- a/content/docs/latest/installing/vms/kubevirt.md +++ b/content/docs/latest/deploy/virt-options/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).)_ @@ -185,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/installing/vms/libvirt.md b/content/docs/latest/deploy/virt-options/libvirt.md similarity index 98% rename from content/docs/latest/installing/vms/libvirt.md rename to content/docs/latest/deploy/virt-options/libvirt.md index 995bfa826..018f82ff3 100644 --- a/content/docs/latest/installing/vms/libvirt.md +++ b/content/docs/latest/deploy/virt-options/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 --- @@ -229,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. @@ -469,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/installing/community-platforms/notes-for-distributors.md b/content/docs/latest/deploy/virt-options/notes-for-distributors.md similarity index 96% 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..306cf58f4 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 --- @@ -42,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 @@ -54,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/installing/cloud/openstack.md b/content/docs/latest/deploy/virt-options/openstack.md similarity index 98% rename from content/docs/latest/installing/cloud/openstack.md rename to content/docs/latest/deploy/virt-options/openstack.md index 3e1fe1620..04b346387 100644 --- a/content/docs/latest/installing/cloud/openstack.md +++ b/content/docs/latest/deploy/virt-options/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 --- @@ -204,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/installing/community-platforms/proxmoxve.md b/content/docs/latest/deploy/virt-options/proxmoxve.md similarity index 97% rename from content/docs/latest/installing/community-platforms/proxmoxve.md rename to content/docs/latest/deploy/virt-options/proxmoxve.md index a30748c5b..b417eb79f 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._ @@ -118,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/installing/vms/qemu.md b/content/docs/latest/deploy/virt-options/qemu.md similarity index 98% rename from content/docs/latest/installing/vms/qemu.md rename to content/docs/latest/deploy/virt-options/qemu.md index d2817d25c..488d02f6f 100644 --- a/content/docs/latest/installing/vms/qemu.md +++ b/content/docs/latest/deploy/virt-options/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 --- @@ -176,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/installing/vms/vagrant.md b/content/docs/latest/deploy/virt-options/vagrant.md similarity index 100% rename from content/docs/latest/installing/vms/vagrant.md rename to content/docs/latest/deploy/virt-options/vagrant.md diff --git a/content/docs/latest/installing/vms/virtualbox.md b/content/docs/latest/deploy/virt-options/virtualbox.md similarity index 98% rename from content/docs/latest/installing/vms/virtualbox.md rename to content/docs/latest/deploy/virt-options/virtualbox.md index 67854ed21..27c999a6e 100644 --- a/content/docs/latest/installing/vms/virtualbox.md +++ b/content/docs/latest/deploy/virt-options/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 --- @@ -155,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/devguide/_index.md b/content/docs/latest/devguide/_index.md new file mode 100644 index 000000000..fdba8ba28 --- /dev/null +++ b/content/docs/latest/devguide/_index.md @@ -0,0 +1,39 @@ +--- +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] + +### 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 +[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/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 96% rename from content/docs/latest/reference/developer-guides/sdk-disk-partitions.md rename to content/docs/latest/devguide/sdk-disk-partitions.md index d431cb450..15df148a1 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 --- @@ -23,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 @@ -53,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/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..72806c6a3 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 --- @@ -807,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/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/diagnostics/_index.md b/content/docs/latest/diagnostics/_index.md new file mode 100644 index 000000000..4145be526 --- /dev/null +++ b/content/docs/latest/diagnostics/_index.md @@ -0,0 +1,17 @@ +--- +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/ +--- + +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] diff --git a/content/docs/latest/setup/debug/btrfs-troubleshooting.md b/content/docs/latest/diagnostics/btrfs-troubleshooting.md similarity index 93% rename from content/docs/latest/setup/debug/btrfs-troubleshooting.md rename to content/docs/latest/diagnostics/btrfs-troubleshooting.md index 2dbd8a583..dea238945 100644 --- a/content/docs/latest/setup/debug/btrfs-troubleshooting.md +++ b/content/docs/latest/diagnostics/btrfs-troubleshooting.md @@ -4,8 +4,9 @@ linktitle: Troubleshooting btrfs description: Tips and tricks for solving issues related to btrfs on Flatcar. weight: 30 aliases: - - ../../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. @@ -79,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/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 91% 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..a10f5156d 100644 --- a/content/docs/latest/setup/debug/reading-the-system-log.md +++ b/content/docs/latest/diagnostics/reading-the-system-log.md @@ -3,7 +3,8 @@ title: Reading the system log description: How to use journalctl to understand what's going on. weight: 15 aliases: - - ../../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: @@ -41,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 @@ -130,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/provisioning/_index.md b/content/docs/latest/fb-provision/_index.md similarity index 75% rename from content/docs/latest/provisioning/_index.md rename to content/docs/latest/fb-provision/_index.md index 28e57afd1..0ffcd1620 100644 --- a/content/docs/latest/provisioning/_index.md +++ b/content/docs/latest/fb-provision/_index.md @@ -1,9 +1,11 @@ --- -title: Provisioning Tools +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: 30 +weight: 20 +aliases: + - /docs/latest/provisioning/ --- diff --git a/content/docs/latest/provisioning/config-transpiler/_index.md b/content/docs/latest/fb-provision/butane/_index.md similarity index 98% rename from content/docs/latest/provisioning/config-transpiler/_index.md rename to content/docs/latest/fb-provision/butane/_index.md index 0c40ff4b9..d536a7f77 100644 --- a/content/docs/latest/provisioning/config-transpiler/_index.md +++ b/content/docs/latest/fb-provision/butane/_index.md @@ -6,6 +6,7 @@ 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 --- 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 97% rename from content/docs/latest/provisioning/config-transpiler/examples.md rename to content/docs/latest/fb-provision/butane/examples.md index cbc70692d..32a61796c 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]. @@ -227,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/provisioning/config-transpiler/getting-started.md b/content/docs/latest/fb-provision/butane/getting-started.md similarity index 93% rename from content/docs/latest/provisioning/config-transpiler/getting-started.md rename to content/docs/latest/fb-provision/butane/getting-started.md index ae93233b9..b5b119c53 100644 --- a/content/docs/latest/provisioning/config-transpiler/getting-started.md +++ b/content/docs/latest/fb-provision/butane/getting-started.md @@ -2,11 +2,11 @@ title: Getting Started weight: 10 aliases: - - ../../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]. @@ -52,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/provisioning/cl-config/_index.md b/content/docs/latest/fb-provision/cl-config/_index.md similarity index 80% rename from content/docs/latest/provisioning/cl-config/_index.md rename to content/docs/latest/fb-provision/cl-config/_index.md index 549034ea4..df1d31b49 100644 --- a/content/docs/latest/provisioning/cl-config/_index.md +++ b/content/docs/latest/fb-provision/cl-config/_index.md @@ -1,13 +1,13 @@ --- 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 + - ../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/provisioning/cl-config/dynamic-data.md b/content/docs/latest/fb-provision/cl-config/dynamic-data.md similarity index 98% rename from content/docs/latest/provisioning/cl-config/dynamic-data.md rename to content/docs/latest/fb-provision/cl-config/dynamic-data.md index 57491d142..037b45d7a 100644 --- a/content/docs/latest/provisioning/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/provisioning/cl-config/examples.md b/content/docs/latest/fb-provision/cl-config/examples.md similarity index 88% rename from content/docs/latest/provisioning/cl-config/examples.md rename to content/docs/latest/fb-provision/cl-config/examples.md index ccb9fa2a1..a3fba62ad 100644 --- a/content/docs/latest/provisioning/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/provisioning/cl-config/from-cloud-config.md b/content/docs/latest/fb-provision/cl-config/from-cloud-config.md similarity index 88% 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 index 38ae4d628..49f05a243 100644 --- a/content/docs/latest/provisioning/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/provisioning/cl-config/operators-notes.md b/content/docs/latest/fb-provision/cl-config/operators-notes.md similarity index 82% rename from content/docs/latest/provisioning/cl-config/operators-notes.md rename to content/docs/latest/fb-provision/cl-config/operators-notes.md index 818b782ae..1de765e63 100644 --- a/content/docs/latest/provisioning/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/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/fb-provision/customize-image/_index.md b/content/docs/latest/fb-provision/customize-image/_index.md new file mode 100644 index 000000000..b61cd6d83 --- /dev/null +++ b/content/docs/latest/fb-provision/customize-image/_index.md @@ -0,0 +1,25 @@ +--- +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/ +--- + +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] 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 98% 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..739f635d7 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. @@ -128,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/provisioning/ignition/_index.md b/content/docs/latest/fb-provision/ignition/_index.md similarity index 99% rename from content/docs/latest/provisioning/ignition/_index.md rename to content/docs/latest/fb-provision/ignition/_index.md index b5a853c49..824f3ca2a 100644 --- a/content/docs/latest/provisioning/ignition/_index.md +++ b/content/docs/latest/fb-provision/ignition/_index.md @@ -6,6 +6,7 @@ description: Provisioning utility specially designed for Container OSs main_menu: true weight: 10 aliases: + - /docs/latest/provisioning/ignition/ - ../ignition/what-is-ignition - ../ignition --- 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 96% rename from content/docs/latest/provisioning/ignition/dynamic-data.md rename to content/docs/latest/fb-provision/ignition/dynamic-data.md index c358a2bde..d52f078a7 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 --- @@ -75,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/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/fb-provision/ignition/specification.md b/content/docs/latest/fb-provision/ignition/specification.md new file mode 100644 index 000000000..503396cbe --- /dev/null +++ b/content/docs/latest/fb-provision/ignition/specification.md @@ -0,0 +1,361 @@ +--- +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. + +## 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: + +```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 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. + +[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]: ../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/provisioning/terraform/_index.md b/content/docs/latest/fb-provision/infrastructure/_index.md similarity index 98% rename from content/docs/latest/provisioning/terraform/_index.md rename to content/docs/latest/fb-provision/infrastructure/_index.md index 08db6c473..ebbda37a2 100644 --- a/content/docs/latest/provisioning/terraform/_index.md +++ b/content/docs/latest/fb-provision/infrastructure/_index.md @@ -1,7 +1,9 @@ --- -title: Terraform +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. @@ -132,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/installing/_index.md b/content/docs/latest/getting-started/_index.md similarity index 89% rename from content/docs/latest/installing/_index.md rename to content/docs/latest/getting-started/_index.md index 86fedf084..68fb21bf7 100644 --- a/content/docs/latest/installing/_index.md +++ b/content/docs/latest/getting-started/_index.md @@ -1,14 +1,16 @@ --- -title: Getting Started with Flatcar Container Linux -linktitle: Installing -weight: 2 +title: Getting Started with Flatcar Container Linux +linktitle: Getting Started +weight: 10 aliases: - - os/quickstart - - quickstart + - /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 @@ -17,6 +19,7 @@ We'll cover 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. @@ -24,14 +27,15 @@ There are two configuration languages to set up Flatcar, aimed at different use 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]. + 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`. @@ -48,12 +52,15 @@ This should work on most Linux systems and assumes you have an SSH key set up fo 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 @@ -61,9 +68,11 @@ wget https://alpha.release.flatcar-linux.net/arm64-usr/current/flatcar_productio 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: @@ -149,6 +158,7 @@ Note that the ignition config will only be processed on the very first boot - th 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 @@ -161,7 +171,6 @@ passwd: 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. @@ -169,7 +178,6 @@ Flatcar instances will download and stage (in the background) new OS versions as 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. @@ -180,25 +188,26 @@ 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] + +- [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 +[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 @@ -214,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/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/_index.md b/content/docs/latest/getting-started/learning-series/_index.md similarity index 96% rename from content/docs/latest/learning-series/_index.md rename to content/docs/latest/getting-started/learning-series/_index.md index 882f46fac..b0bdb61fd 100644 --- a/content/docs/latest/learning-series/_index.md +++ b/content/docs/latest/getting-started/learning-series/_index.md @@ -3,6 +3,8 @@ 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! 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 89% 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..36ca40076 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. @@ -16,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. @@ -30,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. @@ -50,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 @@ -60,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: @@ -108,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. @@ -130,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 ``` @@ -147,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 ``` @@ -155,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 ``` @@ -185,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. @@ -216,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 ``` @@ -230,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! @@ -357,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). @@ -444,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 --- @@ -476,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. @@ -485,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 @@ -594,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 @@ -614,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. @@ -655,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 @@ -683,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 @@ -887,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`). @@ -925,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/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/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/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/orchestrate/_index.md b/content/docs/latest/orchestrate/_index.md new file mode 100644 index 000000000..4bf71603f --- /dev/null +++ b/content/docs/latest/orchestrate/_index.md @@ -0,0 +1,20 @@ +--- +title: Orchestration & Container Runtimes +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] + diff --git a/content/docs/latest/setup/clusters/_index.md b/content/docs/latest/orchestrate/clusters/_index.md similarity index 54% rename from content/docs/latest/setup/clusters/_index.md rename to content/docs/latest/orchestrate/clusters/_index.md index 1d0533ba5..f59bd2a27 100644 --- a/content/docs/latest/setup/clusters/_index.md +++ b/content/docs/latest/orchestrate/clusters/_index.md @@ -6,4 +6,12 @@ description: > cluster architectures that you can choose from, setup cluster discovery and more. 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] diff --git a/content/docs/latest/setup/clusters/architectures.md b/content/docs/latest/orchestrate/clusters/architectures.md similarity index 97% rename from content/docs/latest/setup/clusters/architectures.md rename to content/docs/latest/orchestrate/clusters/architectures.md index cf6530bdb..6047e82e9 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 --- @@ -218,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/setup/clusters/booting-on-ecs.md b/content/docs/latest/orchestrate/clusters/booting-on-ecs.md similarity index 95% rename from content/docs/latest/setup/clusters/booting-on-ecs.md rename to content/docs/latest/orchestrate/clusters/booting-on-ecs.md index 77af0dc2d..e688cdd81 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 --- @@ -95,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/setup/clusters/discovery.md b/content/docs/latest/orchestrate/clusters/discovery.md similarity index 98% rename from content/docs/latest/setup/clusters/discovery.md rename to content/docs/latest/orchestrate/clusters/discovery.md index 21aadf23d..5fea7b57f 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 --- @@ -19,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/container-runtimes/_index.md b/content/docs/latest/orchestrate/containers/_index.md similarity index 88% rename from content/docs/latest/container-runtimes/_index.md rename to content/docs/latest/orchestrate/containers/_index.md index 09837b7e2..bc55d6621 100644 --- a/content/docs/latest/container-runtimes/_index.md +++ b/content/docs/latest/orchestrate/containers/_index.md @@ -6,5 +6,7 @@ description: > 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/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..a0f622d4b 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 --- @@ -379,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/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/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/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/_index.md b/content/docs/latest/os-config/_index.md similarity index 65% rename from content/docs/latest/setup/_index.md rename to content/docs/latest/os-config/_index.md index 28b021e72..c70f5ff0b 100644 --- a/content/docs/latest/setup/_index.md +++ b/content/docs/latest/os-config/_index.md @@ -1,9 +1,11 @@ --- -title: Setup and Operations +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: 50 +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/setup/customization/adding-users.md b/content/docs/latest/os-config/host-config/adding-users.md similarity index 94% rename from content/docs/latest/setup/customization/adding-users.md rename to content/docs/latest/os-config/host-config/adding-users.md index d9e0b9aa8..4bc544c99 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 --- @@ -97,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/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..d1cfade71 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 --- @@ -213,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/setup/systemd/drop-in-units.md b/content/docs/latest/os-config/host-config/drop-in-units.md similarity index 92% 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..2ada29c2f 100644 --- a/content/docs/latest/setup/systemd/drop-in-units.md +++ b/content/docs/latest/os-config/host-config/drop-in-units.md @@ -4,8 +4,9 @@ linktitle: Drop-In Units description: How to customize the running system by using drop-in units. weight: 20 aliases: - - ../../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. @@ -155,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/setup/systemd/environment-variables.md b/content/docs/latest/os-config/host-config/environment-variables.md similarity index 86% rename from content/docs/latest/setup/systemd/environment-variables.md rename to content/docs/latest/os-config/host-config/environment-variables.md index 7d24dcf32..cd0989ce4 100644 --- a/content/docs/latest/setup/systemd/environment-variables.md +++ b/content/docs/latest/os-config/host-config/environment-variables.md @@ -4,8 +4,9 @@ linktitle: Environment Variables description: How to configure and use environment variables in systemd units. weight: 30 aliases: - - ../../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 @@ -109,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 @@ -120,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/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 95% rename from content/docs/latest/setup/customization/power-management.md rename to content/docs/latest/os-config/host-config/power-management.md index 117539e24..3d51468b8 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 --- @@ -54,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/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 95% rename from content/docs/latest/setup/customization/ACPI.md rename to content/docs/latest/os-config/network/ACPI.md index b502386b8..a9b2a5786 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 @@ -67,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/_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/setup/customization/configuring-dns.md b/content/docs/latest/os-config/network/configuring-dns.md similarity index 97% rename from content/docs/latest/setup/customization/configuring-dns.md rename to content/docs/latest/os-config/network/configuring-dns.md index 54b1284fb..6cce10cf9 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 --- @@ -92,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/setup/customization/network-config-with-networkd.md b/content/docs/latest/os-config/network/network-config-with-networkd.md similarity index 95% 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..e21feec69 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,8 +3,9 @@ title: Network configuration with networkd description: How to setup static networking, turn on/off ipv4/ipv6, and debugging tips. weight: 40 aliases: - - ../../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). @@ -173,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 @@ -222,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/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/os-config/storage/_index.md b/content/docs/latest/os-config/storage/_index.md new file mode 100644 index 000000000..6c16922a0 --- /dev/null +++ b/content/docs/latest/os-config/storage/_index.md @@ -0,0 +1,18 @@ +--- +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/ +--- + +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] + 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 97% rename from content/docs/latest/setup/storage/iscsi.md rename to content/docs/latest/os-config/storage/iscsi.md index 3043ea2e1..a03b5672a 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 --- @@ -130,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/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 97% rename from content/docs/latest/setup/storage/mounting-storage.md rename to content/docs/latest/os-config/storage/mounting-storage.md index 50bb1599c..b36bd6813 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 --- @@ -150,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/setup/storage/raid.md b/content/docs/latest/os-config/storage/raid.md similarity index 95% rename from content/docs/latest/setup/storage/raid.md rename to content/docs/latest/os-config/storage/raid.md index 3ad21d966..e86452adc 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 --- @@ -66,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/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/_index.md b/content/docs/latest/os-config/systemd/_index.md similarity index 90% rename from content/docs/latest/setup/systemd/_index.md rename to content/docs/latest/os-config/systemd/_index.md index dd07e3b34..acdf478b7 100644 --- a/content/docs/latest/setup/systemd/_index.md +++ b/content/docs/latest/os-config/systemd/_index.md @@ -7,4 +7,6 @@ description: > 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/setup/systemd/getting-started.md b/content/docs/latest/os-config/systemd/getting-started.md similarity index 74% rename from content/docs/latest/setup/systemd/getting-started.md rename to content/docs/latest/os-config/systemd/getting-started.md index 10636bffd..68dea4c5a 100644 --- a/content/docs/latest/setup/systemd/getting-started.md +++ b/content/docs/latest/os-config/systemd/getting-started.md @@ -4,8 +4,9 @@ linktitle: Getting Started description: An introduction to the most important systemd concepts used in Flatcar. weight: 10 aliases: - - ../../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. @@ -69,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). @@ -125,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). @@ -138,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/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 85% rename from content/docs/latest/setup/systemd/udev-rules.md rename to content/docs/latest/os-config/systemd/udev-rules.md index bbe0d387e..a54298639 100644 --- a/content/docs/latest/setup/systemd/udev-rules.md +++ b/content/docs/latest/os-config/systemd/udev-rules.md @@ -3,8 +3,9 @@ title: Using systemd and udev rules description: How to run units when specific udev events trigger. weight: 35 aliases: - - ../../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`: @@ -74,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/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/ignition/specification.md b/content/docs/latest/provisioning/ignition/specification.md deleted file mode 100644 index f42a35646..000000000 --- a/content/docs/latest/provisioning/ignition/specification.md +++ /dev/null @@ -1,359 +0,0 @@ ---- -title: Ignition Specification -linktitle: Specification -weight: 30 ---- - -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: - -```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 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. - -[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 -[ignition-fs-reuse]: https://github.com/coreos/ignition/blob/main/docs/operator-notes.md#filesystem-reuse-semantics 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/security/_index.md b/content/docs/latest/security/_index.md new file mode 100644 index 000000000..73b58f41a --- /dev/null +++ b/content/docs/latest/security/_index.md @@ -0,0 +1,19 @@ +--- +title: Security +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] diff --git a/content/docs/latest/setup/security/_index.md b/content/docs/latest/security/cert-auth/_index.md similarity index 81% rename from content/docs/latest/setup/security/_index.md rename to content/docs/latest/security/cert-auth/_index.md index 12e2df06f..0336c9fd8 100644 --- a/content/docs/latest/setup/security/_index.md +++ b/content/docs/latest/security/cert-auth/_index.md @@ -1,5 +1,5 @@ --- -title: Additional Security Options +title: Certificates & Authentication linktitle: Security Options description: > Flatcar Container Linux has a number of security measures enabled by @@ -7,5 +7,6 @@ description: > 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/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 79% 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..a709816ec 100644 --- a/content/docs/latest/setup/customization/customize-etcd-unit.md +++ b/content/docs/latest/security/cert-auth/customize-etcd-unit.md @@ -3,8 +3,9 @@ title: Customizing the etcd unit description: How to setup etcd to use client certificates. weight: 50 aliases: - - ../../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. @@ -21,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: @@ -96,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/setup/security/customizing-sshd.md b/content/docs/latest/security/cert-auth/customizing-sshd.md similarity index 98% rename from content/docs/latest/setup/security/customizing-sshd.md rename to content/docs/latest/security/cert-auth/customizing-sshd.md index 7620568f0..9541930c0 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 --- @@ -181,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/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 64% rename from content/docs/latest/reference/constants-and-ids.md rename to content/docs/latest/security/constants-and-ids.md index e7506a31d..d50bf86a4 100644 --- a/content/docs/latest/reference/constants-and-ids.md +++ b/content/docs/latest/security/constants-and-ids.md @@ -2,7 +2,8 @@ title: Constants and IDs weight: 30 aliases: - - ../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. @@ -11,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/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/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/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/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/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/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/provisioning/sysext/_index.md b/content/docs/latest/sys-ext/_index.md similarity index 83% rename from content/docs/latest/provisioning/sysext/_index.md rename to content/docs/latest/sys-ext/_index.md index ea71f5302..343223e07 100644 --- a/content/docs/latest/provisioning/sysext/_index.md +++ b/content/docs/latest/sys-ext/_index.md @@ -1,12 +1,14 @@ --- -title: Systemd-sysext +title: System Extensions description: Extending the base OS with systemd-sysext images -weight: 39 +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`. +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. @@ -15,6 +17,7 @@ While systemd-sysext images are not really good yet at including systemd units, 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/ @@ -25,8 +28,8 @@ 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. + - 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 @@ -38,17 +41,17 @@ Official extensions provided as part of a Flatcar release make Flatcar more modu 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 – … | | ✅ | +| 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 @@ -58,6 +61,7 @@ For now there are no pre-enabled release extensions but once Flatcar would move ### 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 @@ -194,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/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/_index.md b/content/docs/latest/updates-releases/_index.md similarity index 54% rename from content/docs/latest/nebraska/_index.md rename to content/docs/latest/updates-releases/_index.md index f7049351e..b59636af6 100644 --- a/content/docs/latest/nebraska/_index.md +++ b/content/docs/latest/updates-releases/_index.md @@ -1,13 +1,24 @@ --- content_type: nebraska -title: Nebraska +title: Nebraska Update Manager & Releases main_menu: true -weight: 40 +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. + +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] + 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/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/_index.md b/content/docs/latest/updates-releases/nebraska/i18n/_index.md similarity index 95% rename from content/docs/latest/nebraska/i18n/_index.md rename to content/docs/latest/updates-releases/nebraska/i18n/_index.md index 108bb5618..d72bea0fd 100644 --- a/content/docs/latest/nebraska/i18n/_index.md +++ b/content/docs/latest/updates-releases/nebraska/i18n/_index.md @@ -1,6 +1,8 @@ --- title: i18n Internationalization / Localization linkTitle: Internationalization +aliases: + - /docs/latest/nebraska/i18n/ --- Nebraska's internationalization uses the i18next, i18next-parser, and 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/_index.md b/content/docs/latest/updates-releases/releases/_index.md similarity index 88% rename from content/docs/latest/setup/releases/_index.md rename to content/docs/latest/updates-releases/releases/_index.md index 1eafb50ed..844e6e1da 100644 --- a/content/docs/latest/setup/releases/_index.md +++ b/content/docs/latest/updates-releases/releases/_index.md @@ -6,5 +6,6 @@ description: > manually. weight: 20 aliases: + - /docs/latest/setup/releases/ - ../../clusters/management --- 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..efc66d128 100644 --- a/content/docs/latest/setup/releases/update-conf.md +++ b/content/docs/latest/updates-releases/releases/update-conf.md @@ -5,11 +5,12 @@ 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 --- -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/setup/releases/update-strategies.md b/content/docs/latest/updates-releases/releases/update-strategies.md similarity index 94% rename from content/docs/latest/setup/releases/update-strategies.md rename to content/docs/latest/updates-releases/releases/update-strategies.md index 60b45ac85..b841680a5 100644 --- a/content/docs/latest/setup/releases/update-strategies.md +++ b/content/docs/latest/updates-releases/releases/update-strategies.md @@ -3,8 +3,9 @@ title: Update and reboot strategies description: How to configure when you Flatcar instances should reboot. weight: 30 aliases: - - ../../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. @@ -36,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. @@ -241,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): @@ -347,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 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 ---