diff --git a/content/docs/latest/container-runtimes/customizing-docker.md b/content/docs/latest/container-runtimes/customizing-docker.md index ea418528..75b432d5 100644 --- a/content/docs/latest/container-runtimes/customizing-docker.md +++ b/content/docs/latest/container-runtimes/customizing-docker.md @@ -14,8 +14,7 @@ For switching to using containerd with Kubernetes, there is an [extra guide](../ ## Use a custom containerd configuration -The default configuration under `/run/torcx/unpack/docker/usr/share/containerd/config.toml` can't be changed but you can copy it to `/etc/containerd/config.toml` and modify it. -**NOTE** that newer Flatcar major releases (above major release version 3760) ship the default configuration under `/usr/share/containerd/config.toml`. +The default configuration under `/usr/share/containerd/config.toml` can't be changed but you can copy it to `/etc/containerd/config.toml` and modify it. Create a `/etc/systemd/system/containerd.service.d/10-use-custom-config.conf` unit drop-in file to select the new configuration: diff --git a/content/docs/latest/container-runtimes/getting-started-with-kubernetes.md b/content/docs/latest/container-runtimes/getting-started-with-kubernetes.md index 14d81463..b08d9bf9 100644 --- a/content/docs/latest/container-runtimes/getting-started-with-kubernetes.md +++ b/content/docs/latest/container-runtimes/getting-started-with-kubernetes.md @@ -358,10 +358,6 @@ to the following directories on the host file system: - `/var/lib/containerd/` And that it has access to the following binaries on the host file system and that they are included in `PATH`: -- For Flatcar releases until major version 3760: - - `/run/torcx/unpack/docker/bin/containerd-shim-runc-v1` - - `/run/torcx/unpack/docker/bin/containerd-shim-runc-v2` -- For Flatcar releases above major version 3760: - `/usr/bin/containerd-shim-runc-v1` - `/usr/bin/containerd-shim-runc-v2` diff --git a/content/docs/latest/installing/cloud/vmware.md b/content/docs/latest/installing/cloud/vmware.md index c7d3f318..18b60597 100644 --- a/content/docs/latest/installing/cloud/vmware.md +++ b/content/docs/latest/installing/cloud/vmware.md @@ -157,7 +157,7 @@ For DHCP you don't need to specify any networkd units. After transpilation, the resulting JSON content can be used in `guestinfo.ignition.config.data` after encoding it to base64 and setting `guestinfo.ignition.config.data.encoding` to `base64`. If DHCP is used, the JSON file can also be uploaded to a web server and fetched by Ignition if the HTTP(s) URL is given in `guestinfo.ignition.config.url`. -Beginning with Flatcar major version 3248, fetching remote resources in Ignition or with torcx is not only supported with DHCP but also by using `guestinfo.afterburn.initrd.network-kargs` to define a custom network configuration, here an [example for a static IP address](https://coreos.github.io/afterburn/usage/initrd-network-cmdline/#vmware). +Beginning with Flatcar major version 3248, fetching remote resources in Ignition is not only supported with DHCP but also by using `guestinfo.afterburn.initrd.network-kargs` to define a custom network configuration, here an [example for a static IP address](https://coreos.github.io/afterburn/usage/initrd-network-cmdline/#vmware). IP configuration specified via `guestinfo.interface.*` and `guestinfo.dns.*` variables is currently not supported with Ignition and will only work if you provide coreos-cloudinit data (cloud-config or a script) as userdata. diff --git a/content/docs/latest/provisioning/cl-config/_index.md b/content/docs/latest/provisioning/cl-config/_index.md index 21c7ddfe..549034ea 100644 --- a/content/docs/latest/provisioning/cl-config/_index.md +++ b/content/docs/latest/provisioning/cl-config/_index.md @@ -1,6 +1,5 @@ --- -title: Container Linux Config Transpiler -linktitle: Container Linux Config Transpiler +title: "[DEPRECATED / EOL] Container Linux Config Transpiler" description: YAML configuration format used to generate Ignition configs. weight: 20 aliases: @@ -8,6 +7,8 @@ aliases: - ../reference/migrating-to-clcs/provisioning --- +:warning: TL; DR: Use [Butane](../config-transpiler). While Flatcar does support both Ignition spec version (2.x and 3.x), we encourage folks to use [Butane](../config-transpiler) first but we still maintain / document backward compatibility for users who still rely on Ignition 2.x. :warning: + Flatcar Container Linux automates machine provisioning with a specialized system for applying initial configuration. This system implements a process of (trans)compilation and validation for machine configs, and an atomic service to apply validated configurations to machines. ## Container Linux Config diff --git a/content/docs/latest/provisioning/config-transpiler/_index.md b/content/docs/latest/provisioning/config-transpiler/_index.md index bd18f08e..0c40ff4b 100644 --- a/content/docs/latest/provisioning/config-transpiler/_index.md +++ b/content/docs/latest/provisioning/config-transpiler/_index.md @@ -19,7 +19,7 @@ The resulting Ignition config is very much not intended to be human-friendly. It [butane]: https://github.com/coreos/butane/ [ignition]: https://github.com/coreos/ignition -**Note:**: Butane is utilized to generate Ignition v3+ configurations. If you are still utilizing a version of Container Linux that requires Ignition v2, you can refer to the [Container Linux Config Transpiler][cl-config] documentation. This particularly applies to those using the current LTS releases. +**Note:** Butane is utilized to generate Ignition v3+ configurations. If you are still utilizing a version of Container Linux that requires Ignition v2, you can refer to the [Container Linux Config Transpiler][cl-config] documentation. ## Why a two-step process? diff --git a/content/docs/latest/provisioning/sysext/_index.md b/content/docs/latest/provisioning/sysext/_index.md index d6f9156d..ea71f530 100644 --- a/content/docs/latest/provisioning/sysext/_index.md +++ b/content/docs/latest/provisioning/sysext/_index.md @@ -6,7 +6,6 @@ weight: 39 Flatcar Container Linux bundles various software components with fixed versions together into one release. For users that require a particular version of a software component this means that the software needs to be supplied out of band and overwrite the built-in software copy. -In the past Torcx was introduced as a way to switch between Docker versions. Another approach we recommended was to [store binaries in `/opt/bin`](../../container-runtimes/use-a-custom-docker-or-containerd-version/) and prefer them in the `PATH`. For long time already, the systemd project provided the portable services feature to address deploying custom services. @@ -20,11 +19,6 @@ Here's some blog posts you can read for more context: 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/ -## Torcx deprecation - -Since systemd-sysext is a more generic and maintained solution than Torcx, it replaced Torcx since Flatcar version 3794.0.0 and the last major version to include Torcx was 3760. -Any Torcx usage should be migrated by converting your Torcx image with the `convert_torcx_image.sh` helper script from the [`sysext-bakery`][sysext-bakery] repository, mentioned later in this document. The inbuilt Docker and containerd versions can be disabled which is also showed further below. - ## Types of systemd-sysext images For Flatcar, two types of systemd-sysext images are provided: @@ -120,7 +114,7 @@ Upholds=docker.socket ## Supplying your sysext image from Ignition The following Butane Config YAML can be be transpiled to Ignition JSON and will download a custom Docker+containerd sysext image on first boot. -It also takes care of disabling Torcx and future built-in Docker and containerd sysext images we plan to ship in Flatcar (to revert this, you can find the original target of the symlinks in `/usr/share/flatcar/etc/extensions/` - as said, this is not yet shipped). +It also takes care of disabling built-in Docker and containerd sysext images (to revert this, you can find the original target of the symlinks in `/usr/share/flatcar/etc/extensions/`). ```yaml variant: flatcar @@ -131,7 +125,6 @@ storage: mode: 0644 contents: source: https://myserver.net/mydocker.raw - - path: /etc/systemd/system-generators/torcx-generator links: - path: /etc/extensions/docker-flatcar.raw target: /dev/null @@ -169,17 +162,6 @@ To ease the process, the [`create_docker_sysext.sh`](https://raw.githubuserconte [… writes mydocker.raw into current directory …] ``` -## Converting a Torcx image - -In case you have an existing Torcx image you can convert it with the [`convert_torcx_image.sh`](https://raw.githubusercontent.com/flatcar/sysext-bakery/main/convert_torcx_image.sh) helper script (Currently only Torcx tar balls are supported and the conversion is done on best effort): - -``` -./convert_torcx_image.sh TORCXTAR SYSEXTNAME -[… writes SYSEXTNAME.raw into the current directory …] -``` - -Please make also sure that your don't have a `containerd.service` drop in file under `/etc` that uses Torcx paths. - ## Updating custom sysext images From Flatcar 3510.2.0, it is possible to use the `systemd-sysupdate` tool that covers the task of downloading newer versions of your sysext image at runtime from a location you specify. diff --git a/content/docs/latest/provisioning/torcx/_index.md b/content/docs/latest/provisioning/torcx/_index.md deleted file mode 100644 index 919b6f94..00000000 --- a/content/docs/latest/provisioning/torcx/_index.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: "[DEPRECATED / EOL] Torcx" -description: Addon manager for applying ephemeral changes -weight: 100 -aliases: - - ../os/torcx-overview - - ../torcx ---- - -## Deprecation Notice - -As of 2023, torcx on Flatcar is in deprecation and is in the process of being replaced by [systemd-sysext][sysext]. - -**Releases after major version 3760 do not ship torcx. If you are using torcx for managing add-ons please migrate to sysext before upgrading to a major release higher than 3760.** - -## Torcx overview - -[Torcx][gh-torcx] is a boot-time addon manager designed specifically for container OSs like Flatcar Container Linux. At the most basic level, it is a tool for applying ephemeral changes to an immutable system during early boot. This includes providing third-party binary addons and installing systemd units, which can vary across environments and boots. On every boot, Torcx reads its configuration from local disk and propagates specific assets provided by addon packages (which must be available in local stores). - -Torcx complements both the [Ignition][ignition] provisioning utility and [systemd][systemd]. Torcx allows customization of Flatcar Container Linux systems without requiring the compilation of custom system images. This goal is achieved by following two main principles: customizations are ephemeral, and they are applied exactly once per boot. Torcx also has a very simple design, with the aim of providing a small low-level system utility which can be driven by more advanced and higher-level tools. - -### Torcx execution model and systemd generators - -Early in the boot process, execution starts in a minimal initramfs environment where systemd, Ignition, and other boot utilities run. Once up, execution continues by pivoting into the real root file system and by running all [systemd generators][systemd-generator], including the main torcx component, `torcx-generator`. -`torcx-generator` runs serially before any other service starts to guarantee it does not race with other startup processes. However, this restricts Torcx to using only local resources. Torcx cannot access configuration or addons from remote file systems or network locations. - -### Profiles and addons - -Torcx customizations are applied via local addon packages, which are referenced by profiles. Addons are simple tar-gzipped archives containing binary assets and a manifest. A user profile (upper profile) can be supplied by the administrator to be merged on top of hard-coded vendor and OEM profiles (lower profiles). Torcx will take care of computing and applying the resulting list of addons on the system. - -### Boot-time customizations - -Torcx guarantees that customizations are applied at most once per boot, before any other service has been considered for startup. This provides a mechanism to customize most aspects of a Flatcar Container Linux system in a reliable way, and avoids runtime upgrading/downgrading issues. Changes applied by Torcx are not persisted to disk, and therefore last exactly for the lifetime of a single boot of an instance. - -By the same token, this should be read as a warning against abusing Torcx in the role of a general purpose container, service, or package manager. Torcx's boot-transient model consumes memory with each addon, and, worse, would require system reboots for even simple upgrades. - -## Further design details - -For further details on design and goals, Torcx repository contains extensive [developer documentation][devdocs]. - -[gh-torcx]: https://github.com/flatcar/torcx -[ignition]: ../ignition -[sysext]: ../sysext -[systemd]: https://www.freedesktop.org/wiki/Software/systemd/ -[systemd-generator]: http://www.freedesktop.org/software/systemd/man/systemd.generator.html -[devdocs]: https://github.com/flatcar/torcx/blob/master/Documentation diff --git a/content/docs/latest/provisioning/torcx/metadata-and-systemd-target.md b/content/docs/latest/provisioning/torcx/metadata-and-systemd-target.md deleted file mode 100644 index 19b5a4ce..00000000 --- a/content/docs/latest/provisioning/torcx/metadata-and-systemd-target.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Torcx metadata and systemd target -linktitle: Metadata and systemd target -weight: 10 -aliases: - - ../../os/torcx-metadata-and-systemd-target - - ../../torcx/torcx-metadata-and-systemd-target ---- - -In many cases, it is desirable to inspect the state of a system booted with Torcx and to verify the details of the configuration that has been applied. -For this purpose, Torcx comes with additional facilities to integrate with systemd-based workflows: a custom target and a metadata file containing environment flags. - -## Metadata entries and environment flags - -In order to signal a successful run, Torcx writes a metadata file at most once per boot. The format of this file is suitable for consumption by the systemd `EnvironmentFile=` [directive][systemd-exec] and can be used to introspect the booted configuration at runtime. - -The metadata file is written to `/run/metadata/torcx` and contains a list of key-value pairs: - -```shell -$ cat /run/metadata/torcx - -TORCX_LOWER_PROFILES="vendor" -TORCX_UPPER_PROFILE="custom-demo" -TORCX_PROFILE_PATH="/run/torcx/profile.json" -TORCX_BINDIR="/run/torcx/bin" -TORCX_UNPACKDIR="/run/torcx/unpack" -``` - -These values can be used to detect where assets have been unpacked and propagated (shown above as "unpack" and "bin" entries), which profiles have been sourced (both vendor- and user-provided), and what is the resulting profile that has been applied. - -Finally, the runtime profile can be inspected to detect which addons (and versions) are currently applied: - -```shell -$ cat /run/torcx/profile.json - -{ - "kind": "profile-manifest-v0", - "value": { - "images": [] - } -} -``` - -## Torcx target unit - -System services may depend on successful execution of Torcx generator. As such, `torcx.target` is provided as a target unit which is only reachable if the generator successfully ran and sealed the system. - -This target is not enabled by default, but can be referenced as a dependency by other units who want to introspect system status: - -```shell -$ sudo systemctl cat torcx-echo.service - -[Unit] -Description=Sample unit relying on torcx run -After=torcx.target -Requires=torcx.target - -[Service] -EnvironmentFile=/run/metadata/torcx -Type=oneshot -ExecStart=/usr/bin/echo "torcx: applied ${TORCX_UPPER_PROFILE}" - -[Install] -WantedBy=multi-user.target -``` - -```shell -$ sudo systemctl status torcx.target - -● torcx.target - Verify torcx succeeded - Loaded: loaded (/usr/lib/systemd/system/torcx.target; disabled; vendor preset: disabled) - Active: active since [...] -``` - -```shell -$ sudo journalctl -u torcx-echo.service - -localhost systemd[1]: Starting Sample unit relying on torcx run... -localhost echo[756]: torcx: applied custom-demo -localhost systemd[1]: Started Sample unit relying on torcx run. -``` - -[systemd-exec]: https://www.freedesktop.org/software/systemd/man/systemd.exec.html#EnvironmentFile= diff --git a/content/docs/latest/provisioning/torcx/troubleshooting.md b/content/docs/latest/provisioning/torcx/troubleshooting.md deleted file mode 100644 index 681c99fe..00000000 --- a/content/docs/latest/provisioning/torcx/troubleshooting.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Troubleshooting Torcx -linktitle: Troubleshooting -weight: 20 -aliases: - - ../../os/torcx-troubleshooting - - ../../torcx/torcx-troubleshooting ---- - -Torcx generator runs early in the boot, when other system facilities are not yet set up and available for use. In case of errors, troubleshooting and debugging can be performed following the suggestions described here. - -## Checking for failures - -In case of errors, Torcx stops before sealing the new system state. This means that in order to check for correct execution, it is sufficient to verify that the metadata file exists: - -```shell -test -f /run/metadata/torcx || echo 'torcx failed' -``` - -On failures, the metadata seal file will not exist, and `torcx failed` will be printed. Verify failure at boot time using the `torcx.target` unit: - -```shell -$ sudo systemctl start torcx.target ; sudo systemctl status torcx.target - -Assertion failed on job for torcx.target. - -* torcx.target - Verify torcx succeeded - Loaded: loaded (/usr/lib/systemd/system/torcx.target; disabled; vendor preset: disabled) - Active: inactive (dead) since [...] - Assert: start assertion failed at [...] - AssertPathExists=/run/metadata/torcx was not met -``` - -## Gathering logs - -The single most useful piece of information needed when troubleshooting failure is the log from `torcx-generator`. This binary does not run as a typical systemd service, thus log filtering must be done via its syslog identifier. -With systemd-journald, this can be accomplished with the following command: - -```shell -journalctl --boot 0 --identifier /usr/lib64/systemd/system-generators/torcx-generator -``` - -If this doesn't yield results, run as root. There may be instances in which the journal isn't owned by the systemd-journal group, or the current user is not part of that group. - -## Validating the configuration - -One common cause for Torcx failure is a malformed configuration (such as a mis-assembled profile, or a syntax error). In other cases, the active profile might reference addon images which are no longer available on the system.