torcx: mark as deprecated / end of life (flatcar#343)

This change marks torcx as deprecated / end of life, and calls out major
versions after 3760 will not ship torcx anymore.

Signed-off-by: Thilo Fromm <[email protected]>

content/docs/latest/container-runtimes/customizing-docker.md

@@ -15,7 +15,9 @@ 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.
-Then create a `/etc/systemd/system/containerd.service.d/10-use-custom-config.conf` unit drop-in file to select the new configuration:
+**NOTE** that newer Flatcar major releases (above major release version 3760) ship the default configuration under `/usr/share/containerd/config.toml`.
+
+Create a `/etc/systemd/system/containerd.service.d/10-use-custom-config.conf` unit drop-in file to select the new configuration:
 
 ```ini
 [Service]

content/docs/latest/container-runtimes/getting-started-with-docker.md

@@ -99,6 +99,24 @@ This requires the Docker service to get started on boot instead of using the def
 
 Here is a Butane Config to enable the Docker service while disabling socket activation:
 
+```yaml
+variant: flatcar
+version: 1.0.0
+systemd:
+  units:
+    # Ensure docker starts automatically instead of being only socket-activated
+    - name: docker.service
+      enabled: true
+storage:
+  links:
+  - path: /etc/systemd/system/multi-user.target.wants/docker.service
+    target: /usr/lib/systemd/system/docker.service
+    hard: false
+    overwrite: true
+```
+
+**NOTE** for Flatcar versions prior to (older than) the 3761 major release the soft link is unnecessary. The following configuration suffices:
+
 ```yaml
 variant: flatcar
 version: 1.0.0

content/docs/latest/container-runtimes/getting-started-with-kubernetes.md

@@ -333,9 +333,12 @@ 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`:
-
-- `/run/torcx/unpack/docker/bin/containerd-shim-runc-v1`
-- `/run/torcx/unpack/docker/bin/containerd-shim-runc-v2`
+- 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`
 
 Finally, tell `kubelet` to use containerd by adding to it the following flags:
 - `--container-runtime=remote`

content/docs/latest/container-runtimes/use-a-custom-docker-or-containerd-version.md

@@ -1,5 +1,5 @@
 ---
-title: Using a custom Docker or containerd version
+title: Using a custom Docker or containerd version (LEGACY)
 linktitle: Using custom versions
 description: How to download and run a different version of docker or containerd than the one shipped by Flatcar.
 weight: 30
@@ -9,9 +9,9 @@ aliases:
 
 Some system tooling can't be run on Container Linux via containers and this is especially true for the container runtime itself.
 As with other special binaries you want to bring to the system you can use an Ignition config that downloads the binaries.
-Starting from Flatcar version ≥ 3185.0.0 you can also bundle your binaries into [systemd-sysext images](../provisioning/sysext/).
+Starting from Flatcar version ≥ 3185.0.0 a [systemd-sysext images](../provisioning/sysext/) should be used instead of the below.
 
-For custom Docker/containerd binaries sysext images are the recommended way as soon as the Flatcar version in the Stable channel supports them.
+For custom Docker/containerd binaries sysext images are the recommended way.
 However, the Flatcar versions below 3185.0.0 don't support it yet, and even in case support is there you may find it too complicated to build a sysext image and host it elsewhere.
 In this case you can directly place the custom binaries to `/opt/bin/` as done by the following Butane Config which you can transpile to an Ignition config with [`butane`](../provisioning/config-transpiler/).
 
@@ -149,5 +149,7 @@ export PATH="/opt/bin:$PATH"
 ```
 
 The empty file `/etc/systemd/system-generators/torcx-generator` serves the purpose of disabling Torcx to make sure it is not used accidentally in case `/opt/bin` was missing from the `PATH` variable.
+Flatcar releases newer than major release 3760 do not ship torcx so that line can as well be removed from the above config.
+However, leaving it in does not have any side effects.
 
 The `/etc/extensions/` symlinks make sure that the future built-in Docker/containerd sysext images won't be enabled.

content/docs/latest/provisioning/sysext/_index.md

@@ -17,7 +17,7 @@ Systemd-sysext is supported in Flatcar versions ≥ 3185.0.0 for user provided s
 
 ## Torcx deprecation
 
-Since systemd-sysext is a more generic and maintained solution than Torcx, it will replace Torcx and Torcx is scheduled for removal from Flatcar at some point in the future (no date or major release version yet).
+Since systemd-sysext is a more generic and maintained solution than Torcx, it will replace Torcx. Flatcar releases after major version 3760 will not ship torcx at all.
 Starting from Flatcar version 3185.0.0 we encourage you to migrate any Torcx usage and convert your Torcx image with the `convert_torcx_image.sh` helper script from the [`sysext-bakery`][sysext-bakery] repository, mentioned later in this document.
 
 ## The sysext format

content/docs/latest/provisioning/torcx/_index.md

@@ -1,5 +1,5 @@
 ---
-title: Torcx
+title: [DEPRECATED / EOL] Torcx
 description: Addon manager for applying ephemeral changes
 weight: 100
 aliases:
@@ -11,6 +11,8 @@ aliases:
 
 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).