diff --git a/content/docs/latest/deploy/bare-metal/booting-with-ipxe.md b/content/docs/latest/deploy/bare-metal/booting-with-ipxe.md index b8775cfac..f25ab5391 100644 --- a/content/docs/latest/deploy/bare-metal/booting-with-ipxe.md +++ b/content/docs/latest/deploy/bare-metal/booting-with-ipxe.md @@ -29,7 +29,7 @@ When configuring the Flatcar Container Linux iPXE boot script there are a few ke - **sshkey**: Add the given SSH public key to the `core` user's `authorized_keys` file. Replace the example key below with your own (it is usually in `~/.ssh/id_rsa.pub`) - **console**: Enable kernel output and a login prompt on a given tty. The default, `tty0`, generally maps to VGA. Can be used multiple times, e.g. `console=tty0 console=ttyS0` - **flatcar.autologin**: Drop directly to a shell on a given console without prompting for a password. Useful for troubleshooting but use with caution. For any console that doesn't normally get a login prompt by default be sure to combine with the `console` option, e.g. `console=tty0 console=ttyS0 flatcar.autologin=tty1 flatcar.autologin=ttyS0`. Without any argument it enables access on all consoles. Note that for the VGA console the login prompts are on virtual terminals (`tty1`, `tty2`, etc), not the VGA console itself (`tty0`). -- **flatcar.first_boot=1**: Download an Ignition config and use it to provision your booted system. Ignition configs are generated from Container Linux Configs. See the [config transpiler documentation][cl-configs] for more information. If a local filesystem is used for the root partition, pass this parameter only on the first boot. +- **flatcar.first_boot=1**: Download an Ignition config and use it to provision your booted system. Ignition configs are generated from Butane Configs. See the [Butane documentation][butane-docs] for more information. If a local filesystem is used for the root partition, pass this parameter only on the first boot. - **ignition.config.url**: Download the Ignition config from the specified URL. `http`, `https`, `s3`, and `tftp` schemes are supported. - **ip**: Configure temporary static networking for initramfs. This parameter does not influence the final network configuration of the node and is mostly useful for first-boot provisioning of systems in DHCP-less environments. See [Ignition documentation][ignition-kargs-ip] for the complete syntax. @@ -165,7 +165,7 @@ 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]: ../../fb-provision/cl-config +[butane-docs]: ../../fb-provision/butane [butane-configs]: ../../fb-provision/butane [ignition]: ../../fb-provision/ignition [ignition-kargs-ip]: ../../fb-provision/ignition/network-configuration#using-static-ip-addresses-with-ignition diff --git a/content/docs/latest/deploy/bare-metal/booting-with-iso.md b/content/docs/latest/deploy/bare-metal/booting-with-iso.md index 913754c5c..628f4e768 100644 --- a/content/docs/latest/deploy/bare-metal/booting-with-iso.md +++ b/content/docs/latest/deploy/bare-metal/booting-with-iso.md @@ -50,7 +50,7 @@ The latest Flatcar Container Linux ISOs can be downloaded from the image storage ## Known limitations 1. UEFI boot is not currently supported. Boot the system in BIOS compatibility mode. -2. There is no straightforward way to provide an [Ignition config][cl-configs]. +2. There is no straightforward way to provide an [Ignition config][ignition-docs]. As a workaround though, it is possible to leverage the vga console to assign a password to the core user (sudo passwd core). Once a password is set, it would be possible to provide a Butane or an Ignition file via SSH/SCP. 3. A minimum of 2 GB of RAM is required to boot Flatcar Container Linux via ISO. @@ -63,5 +63,5 @@ The most common use-case for this ISO is to install Flatcar Container Linux to d The ISO is configured to start a shell on the console without prompting for a password. This is convenient for installation and troubleshooting, but use caution. -[cl-configs]: ../../fb-provision/cl-config +[ignition-docs]: ../../fb-provision/ignition/ [installing-to-disk]: installing-to-disk diff --git a/content/docs/latest/deploy/bare-metal/installing-to-disk.md b/content/docs/latest/deploy/bare-metal/installing-to-disk.md index 25b204af4..2efe86245 100644 --- a/content/docs/latest/deploy/bare-metal/installing-to-disk.md +++ b/content/docs/latest/deploy/bare-metal/installing-to-disk.md @@ -183,5 +183,4 @@ Now that you have a machine booted it is time to play around. Check out the [Fla [flatcar-iso]: booting-with-iso [butane-section]: #butane-configs [flatcar-install]: https://raw.githubusercontent.com/flatcar/init/flatcar-master/bin/flatcar-install -[cl-configs]: ../../fb-provision/cl-config [butane]: ../../fb-provision/butane diff --git a/content/docs/latest/deploy/cloud/aws-ec2.md b/content/docs/latest/deploy/cloud/aws-ec2.md index 54913a011..37a3bd573 100644 --- a/content/docs/latest/deploy/cloud/aws-ec2.md +++ b/content/docs/latest/deploy/cloud/aws-ec2.md @@ -444,7 +444,7 @@ output "ip-addresses" { } ``` -Now you can use the module by declaring the variables and a Container Linux Configuration for a machine. +Now you can use the module by declaring the variables and a Butane Configuration for a machine. First create a `terraform.tfvars` file with your settings: ``` @@ -453,7 +453,7 @@ machines = ["mynode"] ssh_keys = ["ssh-rsa AA... me@mail.net"] ``` -The machine name listed in the `machines` variable is used to retrieve the corresponding [Container Linux Config](../../fb-provision/cl-config/). +The machine name listed in the `machines` variable is used to retrieve the corresponding [Butane Config](../../fb-provision/butane/). For each machine in the list, you should have a `machine-NAME.yaml.tmpl` file with a corresponding name. For example, create the configuration for `mynode` in the file `machine-mynode.yaml.tmpl` (The SSH key used there is not really necessary since we already set it as VM attribute): @@ -474,7 +474,7 @@ storage: inline: | #!/bin/bash set -euo pipefail - # This script demonstrates how templating and variable substitution works when using Terraform templates for Container Linux Configs. + # This script demonstrates how templating and variable substitution works when using Terraform templates for Butane Configs. hostname="$(hostname)" echo My name is ${name} and the hostname is $${hostname} ``` diff --git a/content/docs/latest/deploy/cloud/azure.md b/content/docs/latest/deploy/cloud/azure.md index 2c4696517..121d074cc 100644 --- a/content/docs/latest/deploy/cloud/azure.md +++ b/content/docs/latest/deploy/cloud/azure.md @@ -609,7 +609,7 @@ output "ip-addresses" { } ``` -Now you can use the module by declaring the variables and a Container Linux Configuration for a machine. +Now you can use the module by declaring the variables and a Butane Configuration for a machine. First create a `terraform.tfvars` file with your settings: ``` @@ -626,7 +626,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](../../fb-provision/butane/configuration) template from the `cl/` subfolder. +The machine name listed in the `machines` variable is used to retrieve the corresponding [Butane 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`: @@ -646,7 +646,7 @@ storage: inline: | #!/bin/bash set -euo pipefail - # This script demonstrates how templating and variable substitution works when using Terraform templates for Container Linux Configs. + # This script demonstrates how templating and variable substitution works when using Terraform templates for Butane Configs. hostname="$(hostname)" echo My name is ${name} and the hostname is $${hostname} ``` diff --git a/content/docs/latest/deploy/cloud/digitalocean.md b/content/docs/latest/deploy/cloud/digitalocean.md index 705415d3e..49f90580c 100644 --- a/content/docs/latest/deploy/cloud/digitalocean.md +++ b/content/docs/latest/deploy/cloud/digitalocean.md @@ -326,7 +326,7 @@ output "ip-addresses" { } ``` -Now you can use the module by declaring the variables and a Container Linux Configuration for a machine. +Now you can use the module by declaring the variables and a Butane Configuration for a machine. First create a `terraform.tfvars` file with your settings: ``` @@ -364,7 +364,7 @@ storage: inline: | #!/bin/bash set -euo pipefail - # This script demonstrates how templating and variable substitution works when using Terraform templates for Container Linux Configs. + # This script demonstrates how templating and variable substitution works when using Terraform templates for Butane Configs. hostname="$(hostname)" echo My name is ${name} and the hostname is $${hostname} ``` diff --git a/content/docs/latest/deploy/cloud/gcp.md b/content/docs/latest/deploy/cloud/gcp.md index 224f87079..44824a556 100644 --- a/content/docs/latest/deploy/cloud/gcp.md +++ b/content/docs/latest/deploy/cloud/gcp.md @@ -127,7 +127,7 @@ You can also [upgrade from an existing CoreOS Container Linux system](../../core ## Butane Config -Flatcar Container Linux allows you to configure machine parameters, configure networking, launch systemd units on startup, and more via Butane Configs. These configs are then transpiled into Ignition configs and given to booting machines. Head over to the [docs to learn about the supported features][cl-configs]. +Flatcar Container Linux allows you to configure machine parameters, configure networking, launch systemd units on startup, and more via Butane Configs. These configs are then transpiled into Ignition configs and given to booting machines. Head over to the [docs to learn about the supported features][butane-docs]. You can provide a raw Ignition JSON config to Flatcar Container Linux via the Google Cloud console's metadata field `user-data` or via a flag using `gcloud`. @@ -328,4 +328,4 @@ Now that you have a machine booted it is time to play around. Check out the [Fla [quickstart]: ../../getting-started/quickstart [doc-index]: ../../ [update-strategies]: ../../updates-releases/releases/update-strategies -[cl-configs]: ../../fb-provision/butane +[butane-docs]: ../../fb-provision/butane diff --git a/content/docs/latest/deploy/cloud/vmware.md b/content/docs/latest/deploy/cloud/vmware.md index 4de38699b..c4cf2a3d4 100644 --- a/content/docs/latest/deploy/cloud/vmware.md +++ b/content/docs/latest/deploy/cloud/vmware.md @@ -172,7 +172,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`](../../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. +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/ignition/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`: @@ -326,7 +326,7 @@ With `should_exist` instead of `should_not_exist` the argument would be added if 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. +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 Butane Config YAML. To take effect it requires an additional reboot. ```yaml @@ -347,7 +347,7 @@ storage: set linux_append="" ``` -To take effect directly on first boot, the alternative is to create a `getty@.service` drop-in, here a CLC snippet: +To take effect directly on first boot, the alternative is to create a `getty@.service` drop-in, here a Butane snippet: ``` systemd: @@ -366,7 +366,6 @@ 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]: ../../fb-provision/cl-config [update-strategies]: ../../updates-releases/releases/update-strategies [release-notes]: https://flatcar-linux.org/releases [quickstart]: ../../getting-started/quickstart diff --git a/content/docs/latest/fb-provision/_index.md b/content/docs/latest/fb-provision/_index.md index b909d217a..58d8f064e 100644 --- a/content/docs/latest/fb-provision/_index.md +++ b/content/docs/latest/fb-provision/_index.md @@ -18,4 +18,3 @@ Flatcar is configured declaratively at first boot. This section introduces the p | [Ignition](./ignition/) | Apply first-boot configuration to a new Flatcar instance. | | [Infrastructure](./infrastructure/) | Use infrastructure tooling such as Terraform with Flatcar. | | [Image Customization](./customize-image/) | Customize images before first boot when needed. | -| [cl-config](./cl-config/) | Legacy configuration tooling retained for historical reference. | diff --git a/content/docs/latest/fb-provision/butane/_index.md b/content/docs/latest/fb-provision/butane/_index.md index d536a7f77..197289470 100644 --- a/content/docs/latest/fb-provision/butane/_index.md +++ b/content/docs/latest/fb-provision/butane/_index.md @@ -20,7 +20,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. +**Note:** Butane is utilized to generate Ignition v3+ configurations. The legacy Container Linux Config Transpiler (used for Ignition v2) has reached end of life and its documentation has been removed; if you're still using it, please migrate to Butane. ## Why a two-step process? @@ -78,4 +78,3 @@ To turn this Butane Config into a usable Ignition Config, we can then run: `dock To learn more about Butane and the configurations that are available, you can refer to the latest [Butane Spec][butane-spec]. [butane-spec]: https://coreos.github.io/butane -[cl-config]: ../cl-config diff --git a/content/docs/latest/fb-provision/cl-config/_index.md b/content/docs/latest/fb-provision/cl-config/_index.md deleted file mode 100644 index fbb59ac75..000000000 --- a/content/docs/latest/fb-provision/cl-config/_index.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: "[DEPRECATED / EOL] Container Linux Config Transpiler" -description: YAML configuration format used to generate Ignition configs. -weight: 45 -aliases: - - ../os/provisioning - - ../reference/migrating-to-clcs/provisioning - - /docs/latest/provisioning/cl-config/ ---- - -: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. - -## Container Linux Config - -Flatcar Container Linux admins define these configurations in a format called the [Container Linux Config][clc], which was originally designed for CoreOS Container Linux, but works perfectly well with Flatcar Container Linux. Container Linux Configs are structured as YAML, and intended to be human-readable. The Container Linux Config has features devoted to configuring Flatcar Container Linux services such as [etcd][etcd], [rkt][rkt], Docker, [flannel][flannel], and [locksmith][locksmith]. **The defining feature of the config is that it cannot be sent directly to a Flatcar Container Linux provisioning target**. Instead, it is first validated and transformed into a machine-readable and wire-efficient form. - -The following examples demonstrate the simplicity of the Container Linux Config format. - -This extremely simple Container Linux Config will fetch and run the current release of etcd: - -```yaml -etcd: {} -``` - -Extend the definition to specify the version of etcd to run. The following example will provision a new Flatcar Container Linux machine to fetch and run the etcd service, version 3.1.6: - -```yaml -etcd: - version: 3.1.6 -``` - -Use variable replacement to configure the etcd service with the provisioning target's public and private IPv4 addresses, making it repeatable across a group of machines. - -```yaml -etcd: - advertise_client_urls: http://{PUBLIC_IPV4}:2379 - initial_advertise_peer_urls: http://{PRIVATE_IPV4}:2380 - listen_client_urls: http://0.0.0.0:2379 - listen_peer_urls: http://{PRIVATE_IPV4}:2380 - discovery: https://discovery.etcd.io/ -``` - -`PUBLIC_IPV4` and `PRIVATE_IPV4` are automatically populated from the environment in which Flatcar Container Linux runs, if this metadata exists. Given the many different environments in which Flatcar Container Linux can run, it's difficult if not impossible to accurately determine these variables in every instance. Be certain to check this value as a troubleshooting measure. - -For example, the default metadata for an EC2 environment would be used: `public_ipv4` and `local_ipv4`. On Azure, _either_ the virtual IP or public IP could be used for the `PUBLIC_IPV4` (`ct` makes a best guess and uses the virtual IP, but this could change in the future), and the dynamic IP would be used for the `PRIVATE_IPV4`. On bare metal, this information cannot be reliably derived in a general manner, so these variables cannot be used. - -Because variable expansion is unpredictable and complex, and because it is also common for users to inadvertently write invalid configs, the use of a transformation tool is strongly encouraged. The default tool recommended for this task is the [Config Transpiler][ct] (ct for short). The Config Transpiler will validate and transform a Container Linux Config into the format that Flatcar Container Linux can consume: the Ignition Config. - -## Ignition Config - -Ignition, the utility in Flatcar Container Linux responsible for provisioning the machine, fetches and executes the Ignition Config. Flatcar Container Linux directly consumes the Ignition Config configuration format. - -Ignition Configs are mostly static, distro-agnostic, and meant to be generated by a machine rather than a human. While they can be written directly by users, it is highly discouraged due to the ease with which errors may be introduced. Rather than writing Ignition Configs directly, users are encouraged to use provisioning tools like [Matchbox][matchbox], which transparently translate Container Linux Configs to Ignition Configs, or to use the Config Transpiler itself. - -![visual overview of the alternate ct workflows](../../img/ct-workflow.svg) - -As shown in this diagram, `ct` is manually invoked only when users are manually provisioning machines. If a provisioning tool like Matchbox is used, `ct` will transparently be incorporated into the deployment pipeline. In which case, the user only needs to prepare a Container Linux Config - Ignition and the Ignition Config are merely an implementation detail. - -## Config Transpiler - -The Container Linux Config Transpiler abstracts the details of configuring Flatcar Container Linux. It's responsible for transforming a Container Linux Config written by a user into an Ignition Config to be consumed by instances of Flatcar Container Linux. - -The Container Linux Config Transpiler command line interface, `ct` for short, can be downloaded from its [GitHub Releases page][download-ct] or used via Docker (`cat example.yaml | docker run --rm -i --platform=YOURPLATFORM ghcr.io/flatcar/ct:latest`). - -The following config will configure an etcd cluster using the machine's public and private IP addresses: - -```yaml -etcd: - advertise_client_urls: http://{PUBLIC_IPV4}:2379 - initial_advertise_peer_urls: http://{PRIVATE_IPV4}:2380 - listen_client_urls: http://0.0.0.0:2379 - listen_peer_urls: http://{PRIVATE_IPV4}:2380 - discovery: https://discovery.etcd.io/ -``` - -As suggested earlier, `ct` requires information about the target environment before it can transform configs which use templating. If this config is passed to `ct` without any other arguments, `ct` fails with the following error message: - -```shell -$ ct < example.yml -error: platform must be specified to use templating -``` - -This message states that because the config takes advantage of templating (in this case, `PUBLIC_IPV4`), `ct` must be invoked with the `--platform` argument. This extra information is used by `ct` to make the platform-specific customizations necessary. Keeping the Container Linux Config and the invocation arguments separate allows the Container Linux Config to remain largely platform independent. - -CT can be invoked again and given Amazon EC2 as an example: - -```shell -$ ct --platform=ec2 < example.yml -{"ignition":{"version":"2.0.0","config"... -``` - -This time, `ct` successfully runs and produces the following Ignition Config: - -```json -{ - "ignition": { "version": "2.0.0" }, - "systemd": { - "units": [ - { - "name": "etcd-member.service", - "enable": true, - "dropins": [ - { - "name": "20-clct-etcd-member.conf", - "contents": "[Unit]\nRequires=coreos-metadata.service\nAfter=coreos-metadata.service\n\n[Service]\nEnvironmentFile=/run/metadata/coreos\nExecStart=\nExecStart=/usr/lib/flatcar/etcd-wrapper $ETCD_OPTS \\\n --listen-peer-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2380\" \\\n --listen-client-urls=\"http://0.0.0.0:2379\" \\\n --initial-advertise-peer-urls=\"http://${COREOS_EC2_IPV4_LOCAL}:2380\" \\\n --advertise-client-urls=\"http://${COREOS_EC2_IPV4_PUBLIC}:2379\" \\\n --discovery=\"https://discovery.etcd.io/\u003ctoken\u003e\"" - } - ] - } - ] - } -} -``` - -This Ignition Config enables and configures etcd as specified in the above Container Linux Config. This can be more easily seen if the contents of the etcd drop-in are formatted nicely: - -```ini -[Unit] -Requires=coreos-metadata.service -After=coreos-metadata.service - -[Service] -EnvironmentFile=/run/metadata/coreos -ExecStart= -ExecStart=/usr/lib/flatcar/etcd-wrapper $ETCD_OPTS \ - --listen-peer-urls="http://${COREOS_EC2_IPV4_LOCAL}:2380" \ - --listen-client-urls="http://0.0.0.0:2379" \ - --initial-advertise-peer-urls="http://${COREOS_EC2_IPV4_LOCAL}:2380" \ - --advertise-client-urls="http://${COREOS_EC2_IPV4_PUBLIC}:2379" \ - --discovery="https://discovery.etcd.io/" -``` - -The details of these changes are covered in depth in Ignition's [metadata documentation][metadata], but the gist is that `coreos-metadata` is used to fetch the IP addresses from the Amazon APIs and then `systemd` is leveraged to substitute the IP addresses into the invocation of etcd. The result is that even though Ignition only runs once, `coreos-metadata` fetches the IP addresses whenever etcd is run, allowing etcd to use IP addresses that have the potential to change. - -## Migrating from cloud configs - -Previously, the recommended way to provision a Flatcar Container Linux machine was with a cloud-config. These configs would be given to a Flatcar Container Linux machine and a utility called [coreos-cloudinit][cloudinit] would read this file and apply the configuration on every boot. - -For a [number of reasons][vs], coreos-cloudinit has been deprecated in favor of Container Linux Configs and Ignition. For help migrating from these legacy cloud-configs to Container Linux Configs, refer to the [migration guide][migrating]. - -## Using Container Linux Configs - -Now that the basics of Container Linux Configs have been covered, a good next step is to read through the [examples][examples] and start experimenting. The [troubleshooting guide][troubleshooting] is a good reference for debugging issues. - -[clc]: ../butane/configuration -[cloudinit]: https://github.com/kinvolk/coreos-cloudinit -[ct]: ../butane/ -[download-ct]: https://github.com/flatcar/container-linux-config-transpiler/releases -[etcd]: https://github.com/etcd-io/etcd -[examples]: examples -[flannel]: https://github.com/coreos/flannel -[locksmith]: https://github.com/kinvolk/locksmith -[matchbox]: https://github.com/coreos/matchbox -[metadata]: ../ignition/metadata -[migrating]: from-cloud-config -[rkt]: https://github.com/rkt/rkt -[troubleshooting]: https://github.com/kinvolk/ignition/blob/master/doc/getting-started.md#troubleshooting -[vs]: ../ignition/#ignition-vs-coreos-cloudinit diff --git a/content/docs/latest/fb-provision/cl-config/dynamic-data.md b/content/docs/latest/fb-provision/cl-config/dynamic-data.md deleted file mode 100644 index c525984a9..000000000 --- a/content/docs/latest/fb-provision/cl-config/dynamic-data.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Referencing dynamic data -weight: 40 -aliases: - - ../../container-linux-config-transpiler/doc/dynamic-data - - ../../container-linux-config-transpiler/dynamic-data - - /docs/latest/provisioning/cl-config/dynamic-data/ ---- - -## Overview - -Sometimes it can be useful to refer to data in a Container Linux Config that isn't known until a machine boots, like its network address. This can be accomplished with [afterburn][afterburn] (previously called `coreos-metadata`). Afterburn is a very basic utility that fetches information about the current machine and makes it available for consumption. By making it a dependency of services which requires this information, systemd will ensure that coreos-metadata has successfully completed before starting these services. These services can then simply source the fetched information and let systemd perform the environment variable expansions. - -While the `coreos-metadata.service` runs afterburn, it will not set the hostname. The hostname is set either through an OEM agent or for particular platforms through afterburn in the initramfs. If afterburn supports your platform and is not invoked in the initramfs by default, you can run it later to set the hostname (`--hostname=/etc/hostname`). - -As of version 0.2.0, ct has support for making this easy for users. In specific sections of a config, users can enter in dynamic data between `{}`, and ct will handle enabling the coreos-metadata service and using the information it provides. - -The available information varies by provider, and is expressed in different variables by coreos-metadata. If this feature is used a `--provider` flag must be passed to ct. Currently, the `etcd` and `flannel` sections are the only ones which support this feature. - -[afterburn]: https://github.com/coreos/afterburn/ - -## Supported data by provider - -This is the information available in each provider. - -| | `HOSTNAME` | `PRIVATE_IPV4` | `PUBLIC_IPV4` | `PRIVATE_IPV6` | `PUBLIC_IPV6` | -|--------------------|------------|----------------|---------------|----------------|---------------| -| Azure | | ✓ | ✓ | | | -| Digital Ocean | ✓ | ✓ | ✓ | ✓ | ✓ | -| EC2 | ✓ | ✓ | ✓ | | | -| GCE | ✓ | ✓ | ✓ | | | -| OpenStack-Metadata | ✓ | ✓ | ✓ | | | - -## Custom metadata providers - -`ct` also supports custom metadata providers. To use the `custom` platform, create a coreos-metadata service unit to execute your own custom metadata fetcher. The custom metadata fetcher must write an environment file `/run/metadata/coreos` defining a `COREOS_CUSTOM_*` environment variable for every piece of dynamic data used in the specified Container Linux Config. The environment variables are the same as in the Container Linux Config, but prefixed with `COREOS_CUSTOM_`. - -### Example - -Assume `https://example.com/metadata-script.sh` is a script which communicates with a metadata service and then writes the following file to `/run/metadata/coreos`: -``` -COREOS_CUSTOM_HOSTNAME=foobar -COREOS_CUSTOM_PRIVATE_IPV4= -COREOS_CUSTOM_PUBLIC_IPV4= -``` - -The following Container Linux Config downloads the metadata fetching script, replaces the ExecStart line in `coreos-metadata` service to use the script instead, and configures etcd using the metadata provided. Use the `--platform=custom` flag when transpiling. -```yaml -storage: - files: - - filesystem: "root" - path: "/opt/get-metadata.sh" - mode: 0755 - contents: - remote: - url: "https://example.com/metadata-script.sh" - -systemd: - units: - - name: "coreos-metadata.service" - contents: | - [Unit] - Description=Metadata agent - After=nss-lookup.target - After=network-online.target - Wants=network-online.target - [Service] - Type=oneshot - Restart=on-failure - RemainAfterExit=yes - ExecStart=/opt/get-metadata.sh - -etcd: - 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" -``` - -You can find another example in the [VMware docs](../../deploy/cloud/vmware.md). - -## Behind the scenes - -For a more in-depth walk through of how this feature works, let's look at the etcd example from the [examples document][examples]. - -```yaml -etcd: - 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" -``` - -If we give this example to ct with the `--platform=ec2` tag, it produces the following drop-in: - -``` -[Unit] -Requires=coreos-metadata.service -After=coreos-metadata.service - -[Service] -EnvironmentFile=/run/metadata/coreos -Environment="ETCD_IMAGE_TAG=v3.0.15" -ExecStart= -ExecStart=/usr/lib/coreos/etcd-wrapper $ETCD_OPTS \ - --name="${COREOS_EC2_HOSTNAME}" \ - --listen-peer-urls="http://${COREOS_EC2_IPV4_LOCAL}:2380" \ - --listen-client-urls="http://0.0.0.0:2379" \ - --initial-advertise-peer-urls="http://${COREOS_EC2_IPV4_LOCAL}:2380" \ - --initial-cluster="${COREOS_EC2_HOSTNAME}=http://${COREOS_EC2_IPV4_LOCAL}:2380" \ - --advertise-client-urls="http://${COREOS_EC2_IPV4_LOCAL}:2379" -``` - -This drop-in specifies that etcd should run after the coreos-metadata service, and it uses `/run/metadata/coreos` as an `EnvironmentFile`. This enables the coreos-metadata service, and puts the information it discovers into environment variables. These environment variables are then expanded by systemd when the service starts, inserting the dynamic data into the command-line flags to etcd. - -[examples]: #example diff --git a/content/docs/latest/fb-provision/cl-config/examples.md b/content/docs/latest/fb-provision/cl-config/examples.md deleted file mode 100644 index 98847fe4c..000000000 --- a/content/docs/latest/fb-provision/cl-config/examples.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Container Linux Config Examples -linktitle: Examples -weight: 20 -aliases: - - ../../container-linux-config-transpiler/doc/examples - - ../../container-linux-config-transpiler/examples - - /docs/latest/provisioning/cl-config/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]. - -## Users and groups - -```yaml -passwd: - users: - - name: core - password_hash: "$6$43y3tkl..." - ssh_authorized_keys: - - key1 -``` - -This example modifies the existing `core` user, giving it a known password hash (this will enable login via password), and setting its ssh key. - -```yaml -passwd: - users: - - name: user1 - password_hash: "$6$43y3tkl..." - ssh_authorized_keys: - - key1 - - key2 - - name: user2 - ssh_authorized_keys: - - key3 -``` - -This example will create two users, `user1` and `user2`. The first user has a password set and two ssh public keys authorized to log in as the user. The second user doesn't have a password set (so log in via password will be disabled), but have one ssh key. - -```yaml -passwd: - users: - - name: user1 - password_hash: "$6$43y3tkl..." - ssh_authorized_keys: - - key1 - home_dir: /home/user1 - no_create_home: true - groups: - - wheel - - plugdev - shell: /bin/bash -``` - -This example creates one user, `user1`, with the password hash `$6$43y3tkl...`, and sets up one ssh public key for the user. The user is also given the home directory `/home/user1`, but it's not created, the user is added to the `wheel` and `plugdev` groups, and the user's shell is set to `/bin/bash`. - -### Generating a password hash - -If you choose to use a password instead of an SSH key, generating a safe hash is extremely important to the security of your system. Simplified hashes like md5crypt are trivial to crack on modern GPU hardware. Here are a few ways to generate secure hashes: - -``` -# On Debian/Ubuntu (via the package "whois") -mkpasswd --method=SHA-512 --rounds=4096 - -# OpenSSL (note: this will only make md5crypt. While better than plantext it should not be considered fully secure) -openssl passwd -1 - -# Python -python -c "import crypt,random,string; print(crypt.crypt(input('clear-text password: '), '\$6\$' + ''.join([random.choice(string.ascii_letters + string.digits) for _ in range(16)])))" - -# Perl (change password and salt values) -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. - -## Storage and files - -### Files - -```yaml -storage: - files: - - path: /opt/file - filesystem: root - contents: - inline: Hello, world! - mode: 0644 - user: - id: 500 - group: - id: 501 -``` - -This example creates a file at `/opt/file` with the contents `Hello, world!`, permissions 0644 (so readable and writable by the owner, and only readable by everyone else), and the file is owned by user uid 500 and gid 501. - -```yaml -storage: - files: - - path: /opt/file2 - filesystem: root - contents: - remote: - url: http://example.com/file2 - compression: gzip - verification: - hash: - function: sha512 - sum: 4ee6a9d20cc0e6c7ee187daffa6822bdef7f4cebe109eff44b235f97e45dc3d7a5bb932efc841192e46618f48a6f4f5bc0d15fd74b1038abf46bf4b4fd409f2e - mode: 0644 -``` - -This example fetches a gzip-compressed file from `http://example.com/file2`, makes sure that it matches the provided sha512 hash, and writes it to `/opt/file2`. - -### Filesystems - -```yaml -storage: - filesystems: - - name: filesystem1 - mount: - device: /dev/disk/by-partlabel/ROOT - format: btrfs - wipe_filesystem: true - label: ROOT -``` - -This example formats the root filesystem to be `btrfs`, and names it `filesystem1` (primarily for use in the `files` section). - -## systemd units - -```yaml -systemd: - units: - - name: etcd-member.service - dropins: - - name: conf1.conf - contents: | - [Service] - Environment="ETCD_NAME=infra0" -``` - -This example adds a drop-in for the `etcd-member` unit, setting the name for etcd to `infra0` with an environment variable. More information on systemd dropins can be found in [the docs][dropins]. - -```yaml -systemd: - units: - - name: hello.service - enabled: true - contents: | - [Unit] - Description=A hello world unit! - - [Service] - Type=oneshot - ExecStart=/usr/bin/echo "Hello, World!" - - [Install] - WantedBy=multi-user.target -``` - -This example creates a new systemd unit called hello.service, enables it so it will run on boot, and defines the contents to simply echo `"Hello, World!"`. - -## networkd units - -```yaml -networkd: - units: - - name: static.network - contents: | - [Match] - Name=enp2s0 - - [Network] - Address=192.168.0.15/24 - Gateway=192.168.0.1 -``` - -This example creates a networkd unit to set the IP address on the `enp2s0` interface to the static address `192.168.0.15/24`, and sets an appropriate gateway. More information on networkd units in CoreOS can be found in [the docs][networkd]. - -## etcd - -```yaml -etcd: - 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" -``` - -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. - -This is referencing dynamic data that isn't known until an instance is booted. For more information on how this works, please take a look at the [referencing dynamic data][dynamic-data] document. - -## Updates and Locksmithd - -```yaml -update: - group: "beta" -locksmith: - reboot_strategy: "etcd-lock" - 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]: ../butane/configuration -[dropins]: ../../os-config/host-config/drop-in-units -[networkd]: ../../os-config/network/network-config-with-networkd -[dynamic-data]: ../dynamic-data diff --git a/content/docs/latest/fb-provision/cl-config/from-cloud-config.md b/content/docs/latest/fb-provision/cl-config/from-cloud-config.md deleted file mode 100644 index bd056cfee..000000000 --- a/content/docs/latest/fb-provision/cl-config/from-cloud-config.md +++ /dev/null @@ -1,350 +0,0 @@ ---- -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 - - /docs/latest/provisioning/cl-config/from-cloud-config/ ---- - -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. - -The current recommended method is provisioning with Container Linux Configs. - -This document details how to convert an existing cloud-config into a Container Linux Config. Once a Container Linux Config has been written, it is given to the Config Transpiler to be converted into an Ignition Config. This Ignition Config can then be provided to a booting machine. For more information on this process, take a look at the [provisioning guide][provisioning]. - -The etcd and flannel examples shown in this document will use dynamic data in the Container Linux Config (anything looking like this: `{PRIVATE_IPV4}`). Not all types of dynamic data are supported on all cloud providers, and if the machine is not on a cloud provider this feature cannot be used. Please see [here][dynamic-data] for more information. - -To see all supported options available in a Container Linux Config, please look at the [Container Linux Config schema][ct-config]. - -## etcd2 - -In a cloud-config, etcd version 2 can be enabled and configured by using the `coreos.etcd2.*` section. As an example of this: - -```yaml -#cloud-config - -coreos: - etcd2: - 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" -``` - -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. - -This is done under the etcd section: - -```yaml -etcd: - 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. - -Configuration options in this section can be provided the same way as they were in a cloud-config, with the exception of dashes (`-`) being replaced with underscores (`_`) in key names. - -```yaml -etcd: - 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" -``` - -## flannel - -Flannel is easily configurable in a cloud-config the same way etcd is, by using the `coreos.flannel.*` section. - -```yaml -#cloud-config - -coreos: - flannel: - 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 - etcd_prefix: "/coreos.com/network2" -``` - -## locksmith - -The `coreos.locksmith.*` section in a cloud-config can be used to configure the locksmith daemon via environment variables. - -```yaml -#cloud-config - -coreos: - locksmith: - 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. - -```yaml -locksmith: - reboot_strategy: "reboot" - etcd_endpoints: "http://example.com:2379" -``` - -## update - -The `coreos.update.*` section can be used to configure the reboot strategy, update group, and update server in a cloud-config. - -```yaml -#cloud-config -coreos: - update: - reboot-strategy: "etcd-lock" - 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" - server: "https://public.update.flatcar-linux.net/v1/update/" -``` - -## units - -The `coreos.units.*` section in a cloud-config can define arbitrary systemd units that should be started after booting. - -```yaml -#cloud-config - -coreos: - units: - - name: "docker-redis.service" - command: "start" - content: | - [Unit] - Description=Redis container - Author=Me - After=docker.service - - [Service] - Restart=always - ExecStart=/usr/bin/docker start -a redis_server - ExecStop=/usr/bin/docker stop -t 2 redis_server -``` - -This section could also be used to define systemd drop-in files for existing units. - -```yaml -#cloud-config - -coreos: - units: - - name: "docker.service" - drop-ins: - - name: "50-insecure-registry.conf" - content: | - [Service] - Environment=DOCKER_OPTS='--insecure-registry="10.0.1.0/24"' -``` - -And existing units could also be started without any further configuration. - -```yaml -#cloud-config - -coreos: - units: - - name: "etcd2.service" - command: "start" -``` - -One big difference in Container Linux Config compared to cloud-configs is that the configuration is applied via [Ignition][ignition] before the machine has fully booted, as opposed to coreos-cloudinit that runs after the machine has fully booted. As a result units cannot be directly started in a Container Linux Config, the unit is instead enabled so that systemd will begin the unit once systemd starts. - -_Note: in this example an `[Install]` section has been added so that the unit can be enabled._ - -```yaml -systemd: - units: - - name: "docker-redis.service" - enable: true - contents: | - [Unit] - Description=Redis container - Author=Me - After=docker.service - - [Service] - Restart=always - ExecStart=/usr/bin/docker start -a redis_server - ExecStop=/usr/bin/docker stop -t 2 redis_server - - [Install] - WantedBy=multi-user.target -``` - -Drop-in files can be provided for units in a Container Linux Config just like in a cloud-config. - -```yaml -systemd: - units: - - name: "docker.service" - dropins: - - name: "50-insecure-registry.conf" - contents: | - [Service] - Environment=DOCKER_OPTS='--insecure-registry="10.0.1.0/24"' -``` - -Existing units can also be enabled without configuration. - -```yaml -systemd: - units: - - name: "etcd-member.service" - enable: true -``` - -### ssh_authorized_keys - -In a cloud-config the `ssh_authorized_keys` section can be used to add ssh public keys to the `core` user. - -```yaml -#cloud-config - -ssh_authorized_keys: - - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC0g+ZTxC7weoIJLUafOgrm+h..." -``` - -In a Container Linux Config there is no analogous section to `ssh_authorized_keys`, but ssh keys for the core user can be set just as easily using the `passwd.users.*` section: - -```yaml -passwd: - users: - - name: core - ssh_authorized_keys: - - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC0g+ZTxC7weoIJLUafOgrm+h..." -``` - -### hostname - -In a cloud-config the `hostname` section can be used to set a machine's hostname. - -```yaml -#cloud-config - -hostname: "coreos1" -``` - -The Container Linux Config is intentionally more generalized than a cloud-config, and there is no equivalent hostname section understood in a CL Config. Instead, set the hostname by writing it to `/etc/hostname` in a CL Config `storage.files.*` section. - -```yaml -storage: - files: - - filesystem: "root" - path: "/etc/hostname" - mode: 0644 - contents: - inline: coreos1 -``` - -### users - -The `users` section in a cloud-config can be used to add users and specify many properties about them, from groups the user should be in to what the user's shell should be. - -```yaml -#cloud-config - -users: - - name: "elroy" - passwd: "$6$5s2u6/jR$un0AvWnqilcgaNB3Mkxd5yYv6mTlWfOoCYHZmfi3LDKVltj.E8XNKEcwWm..." - groups: - - "sudo" - - "docker" - ssh-authorized-keys: - - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC0g+ZTxC7weoIJLUafOgrm+h..." -``` - -This same information can be added to the Container Linux Config in the `passwd.users.*` section. - -```yaml -passwd: - users: - - name: "elroy" - password_hash: "$6$5s2u6/jR$un0AvWnqilcgaNB3Mkxd5yYv6mTlWfOoCYHZmfi3LDKVltj.E8XNKEcwWm..." - ssh_authorized_keys: - - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC0g+ZTxC7weoIJLUafOgrm+h..." - groups: - - "sudo" - - "docker" -``` - -### write_files - -The `write_files` section in a cloud-config can be used to specify files and their contents that should be written to disk on the machine. - -```yaml -#cloud-config -write_files: - - path: "/etc/resolv.conf" - permissions: "0644" - owner: "root" - content: | - nameserver 8.8.8.8 -``` - -This can be done in a Container Linux Config with the `storage.files.*` section. - -```yaml -storage: - files: - - filesystem: "root" - path: "/etc/resolv.conf" - mode: 0644 - contents: - inline: | - nameserver 8.8.8.8 -``` - -File specifications in this section of a CL Config must define the target filesystem and the file's path relative to the root of that filesystem. This allows files to be written to filesystems other than the root filesystem. - -Under the `contents` section, the file contents are under a sub-section called `inline`. This is because a file's contents can be remote by replacing the `inline` section with a `remote` section. To see what options are available under the `remote` section, look at the [Container Linux Config schema][ct-config]. - -### manage_etc_hosts - -The `manage_etcd_hosts` section in a cloud-config can be used to configure the contents of the `/etc/hosts` file. Currently only one value is supported, `"localhost"`, which will cause your system's hostname to resolve to `127.0.0.1`. - -```yaml -#cloud-config - -manage_etc_hosts: "localhost" -``` - -There is no analogous section in a Container Linux Config, however the `/etc/hosts` file can be written in the `storage.files.*` section. - -```yaml -storage: - files: - - filesystem: "root" - path: "/etc/hosts" - mode: 0644 - contents: - inline: | - 127.0.0.1 localhost - ::1 localhost - 127.0.0.1 example.com -``` - -[provisioning]: _index.md -[dynamic-data]: ../dynamic-data -[ct-config]: ../butane/configuration -[ignition]: ../ignition diff --git a/content/docs/latest/fb-provision/cl-config/operators-notes.md b/content/docs/latest/fb-provision/cl-config/operators-notes.md deleted file mode 100644 index fee62cb34..000000000 --- a/content/docs/latest/fb-provision/cl-config/operators-notes.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Operator Notes -weight: 70 -aliases: - - ../../container-linux-config-transpiler/doc/operators-notes - - ../../container-linux-config-transpiler/operators-notes - - /docs/latest/provisioning/cl-config/operators-notes/ ---- - -## Type GUID aliases - -The Config Transpiler supports several aliases for GPT partition type GUIDs. They are as follows: - -| Alias Name | Resolved Type GUID | -| -- | -- | -| `raid_containing_root` | `be9067b9-ea49-4f15-b4f6-f36f8c9e1818` | -| `linux_filesystem_data` | `0fc63daf-8483-4772-8e79-3d69d8477de4` | -| `swap_partition` | `0657fd6d-a4ab-43c4-84e5-0933c84b4f4f` | -| `raid_partition` | `a19d880f-05fc-4d3b-a006-743f0f84911e` | - -See the [Using RAID for the Root Filesystem](../../os-config/storage/raid/) documentation for when to use `raid_containing_root`. diff --git a/content/docs/latest/fb-provision/cl-config/specification.md b/content/docs/latest/fb-provision/cl-config/specification.md deleted file mode 100644 index fac823769..000000000 --- a/content/docs/latest/fb-provision/cl-config/specification.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: CL Configuration Specification -weight: 80 -aliases: - - ../../container-linux-config-transpiler/doc/configuration - - ../../container-linux-config-transpiler/configuration - - /docs/latest/provisioning/cl-config/specification/ ---- - -A Container Linux Configuration, to be processed by `ct`, is a YAML document conforming to the following specification: - -_Note: all fields are optional unless otherwise marked_ - -* **ignition** (object): metadata about the configuration itself. - * **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, required): 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** (object): the hash of the config - * **function** (string): the function used to hash the config. Supported functions are sha512. - * **sum** (string): the resulting sum of the hash applied to the contents. - * **replace** (object): the config that will replace the current. - * **source** (string, required): 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** (object): the hash of the config - * **function** (string): the function used to hash the config. Supported functions are sha512. - * **sum** (string): the resulting sum of the hash applied to the contents. - * **timeouts** (object): options relating to http timeouts when fetching files over http or https. - * **http_response_headers** (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. - * **http_total** (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`. - * **certificate_authorities** (object): the list of additional certificate authorities (in addition to the system authorities) to be used for TLS verification when fetching over `https`. - * **source** (string, required): 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, required): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. - * **wipe_table** (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. - * **size** (string): the size of the partition with a unit (KiB, MiB, GiB). If zero, the partition will fill the remainder of the disk. - * **start** (string): the start of the partition with a unit (KiB, MiB, GiB). If zero, the partition will be positioned at the earliest available part of the disk. - * **type_guid** (string): the GPT [partition type GUID][part-types]. If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). The keywords `linux_filesystem_data`, `raid_partition`, `swap_partition`, and `raid_containing_root` can also be used. - * **guid** (string): the GPT unique partition GUID. - * **raid** (list of objects): the list of RAID arrays to be configured. - * **name** (string, required): the name to use for the resulting md device. - * **level** (string, required): the redundancy level of the array (e.g. linear, raid1, raid5, etc.). - * **devices** (list of strings, required): 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, required): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. - * **format** (string, required): the filesystem format (ext4, btrfs, or xfs). - * **wipe_filesystem** (boolean): whether or not to wipe the device before filesystem creation, see [Ignition's 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. A non-null entry indicates that the filesystem shall be created. - * **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, rooted in this particular filesystem, to be written. - * **filesystem** (string, required): the internal identifier of the filesystem. This matches the last filesystem with the given identifier. - * **path** (string, required): 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. - * **inline** (string): the contents of the file. - * **local** (string): the path to a local file, relative to the `--files-dir` directory. When using local files, the `--files-dir` flag must be passed to `ct`. The file contents are included in the generated config. - * **remote** (object): options related to the fetching of remote file contents. Remote files are fetched by Ignition when Ignition runs, the contents are not included in the generated config. - * **compression** (string): the type of compression used on the contents (null or gzip) - * **url** (string): the URL of the file contents. Supported schemes are http, https, tftp, s3, 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 file contents. - * **hash** (object): the hash of the config - * **function** (string): the function used to hash the config. Supported functions are sha512. - * **sum** (string): the resulting sum of the hash applied to the contents. - * **mode** (integer): the file's permission mode. - * **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, required): the internal identifier of the filesystem in which to create the directory. This matches the last filesystem with the given identifier. - * **path** (string, required): the absolute path to the directory. - * **overwrite** (boolean): whether to delete preexisting nodes at the path. - * **mode** (integer): the directory's permission mode. - * **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, required): the internal identifier of the filesystem in which to write the link. This matches the last filesystem with the given identifier. - * **path** (string, required): 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, required): 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, required): 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, required): 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, required): 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, required): 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, required): the username for the account. - * **password_hash** (string): the encrypted password for the account. - * **ssh_authorized_keys** (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. - * **home_dir** (string): the home directory of the account. - * **no_create_home** (boolean): whether or not to create the user's home directory. This only has an effect if the account doesn't exist yet. - * **primary_group** (string): the name of the primary group of the account. - * **groups** (list of strings): the list of supplementary groups of the account. - * **no_user_group** (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. - * **no_log_init** (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 to make the account 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. - * **uid** (integer, DEPRECATED): the user ID of the new account. - * **gecos** (string, DEPRECATED): the GECOS field of the new account. - * **home_dir** (string, DEPRECATED): the home directory of the new account. - * **no_create_home** (boolean, DEPRECATED): whether or not to create the user's home directory. - * **primary_group** (string, DEPRECATED): the name or ID of the primary group of the new account. - * **groups** (list of strings, DEPRECATED): the list of supplementary groups of the new account. - * **no_user_group** (boolean, DEPRECATED): whether or not to create a group with the same name as the user. - * **no_log_init** (boolean, DEPRECATED): whether or not to add the user to the lastlog and faillog databases. - * **shell** (string, DEPRECATED): the login shell of the new account. - * **groups** (list of objects): the list of groups to be added. - * **name** (string, required): the name of the group. - * **gid** (integer): the group ID of the new group. - * **password_hash** (string): the encrypted password of the new group. -* **etcd** - * **version** (string): the version of etcd to be run - * **_other options_** (string): this section accepts any valid etcd options for the version of etcd specified. For a comprehensive list, please consult etcd's documentation. Note all options here should be in snake_case, not spine-case. -* **flannel** - * **version** (string): the version of flannel to be run - * **network_config** (string): the flannel configuration to be written into etcd before flannel starts. - * **_other options_** (string): this section accepts any valid flannel options for the version of flannel specified. For a comprehensive list, please consult flannel's documentation. Note all options here should be in snake_case, not spine-case. -* **docker** - * **flags** (list of strings): additional flags to pass to the docker daemon when it is started -* **update** - * **group** (string): the update group to follow. Most users will want one of: stable, beta, alpha. - * **server** (string): the server to fetch updates from. - * **pcr_policy_server** (string): the server to receive posted TPM PCR policy from. - * **download_user** (string): the authentication user to fetch the update. - * **download_password** (string): the authentication password to fetch the update - * **machine_alias** (string): human readable machine alias to be displayed in the update server UI. -* **locksmith** - * **reboot_strategy** (string): the reboot strategy for locksmithd to follow. Must be one of: reboot, etcd-lock, off. - * **window_start** (string, required if window-length isn't empty): the start of the window that locksmithd can reboot the machine during - * **window_length** (string, required if window-start isn't empty): the duration of the window that locksmithd can reboot the machine during - * **group** (string): the locksmith etcd group to be part of for reboot control - * **etcd_endpoints** (string): the endpoints of etcd locksmith should use - * **etcd_cafile** (string): the tls CA file to use when communicating with etcd - * **etcd_certfile** (string): the tls cert file to use when communicating with etcd - * **etcd_keyfile** (string): the tls key file to use when communicating with etcd - -[part-types]: http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs -[rfc2397]: https://tools.ietf.org/html/rfc2397 -[ignition-fs-reuse]: https://github.com/coreos/ignition/blob/main/docs/operator-notes.md#filesystem-reuse-semantics diff --git a/content/docs/latest/fb-provision/ignition/specification.md b/content/docs/latest/fb-provision/ignition/specification.md index 503396cbe..0d10c8b61 100644 --- a/content/docs/latest/fb-provision/ignition/specification.md +++ b/content/docs/latest/fb-provision/ignition/specification.md @@ -209,7 +209,7 @@ podman run -i --rm quay.io/coreos/butane:release --pretty --strict < config.yml ## 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 v2 is not developed anymore but still supported (specification 2.3.0), the high-level [Butane 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. diff --git a/content/docs/latest/fb-provision/infrastructure/_index.md b/content/docs/latest/fb-provision/infrastructure/_index.md index ebbda37a2..530f9e8f1 100644 --- a/content/docs/latest/fb-provision/infrastructure/_index.md +++ b/content/docs/latest/fb-provision/infrastructure/_index.md @@ -45,10 +45,10 @@ resource "packet_device" "machine" { } data "ct_config" "machine-ignition" { - content = data.template_file.machine-cl-config.rendered + content = data.template_file.machine-config.rendered } -data "template_file" "machine-cl-config" { +data "template_file" "machine-config" { template = file("${path.module}/machine.yaml.tmpl") vars = { something = var.something } } @@ -73,7 +73,7 @@ Persistent data should be stored on another partition which should be set to be We can also preserve the machine ID by setting it as kernel cmdline parameter (it must not be kept as file on the root filesystem because that prevents the systemd first-boot semantics to enable units through the preset Ignition creates). -This Container Linux Config snippet takes care of reformating the root filesystem and places a reprovisioning helper script on the OEM partition: +This Butane config snippet takes care of reformating the root filesystem and places a reprovisioning helper script on the OEM partition: ```yaml storage: diff --git a/content/docs/latest/getting-started/_index.md b/content/docs/latest/getting-started/_index.md index b3db7a6c2..b9769582e 100644 --- a/content/docs/latest/getting-started/_index.md +++ b/content/docs/latest/getting-started/_index.md @@ -20,7 +20,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). +- [Butane Config][butane-configs] Butane is human-readable / writable YAML and must be converted (transpiled) into Ignition V3 config before Flatcar can use it (Butane is not supported for LTS-2022). - [Ignition config][ignition] is machine-readable JSON fed to Flatcar's ignition service. Ignition is Flatcars "installation service" which configures a Flatcar instance during provisioning. The config file is passed via the "custom data" or "user data" option of cloud providers, and can be supplied by various mechanisms to private cloud VMs and bare metal. @@ -224,7 +224,6 @@ With any of these guides you will have machines up and running in a few minutes. [iso-docs]: ../deploy/bare-metal/booting-with-iso [install-docs]: ../deploy/bare-metal/installing-to-disk [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 diff --git a/content/docs/latest/os-config/host-config/adding-users.md b/content/docs/latest/os-config/host-config/adding-users.md index 4bc544c99..532e4e1a3 100644 --- a/content/docs/latest/os-config/host-config/adding-users.md +++ b/content/docs/latest/os-config/host-config/adding-users.md @@ -99,6 +99,5 @@ user1 ALL=(ALL) NOPASSWD: ALL ``` [butane-configs]: ../../fb-provision/butane -[cl-config]: ../../fb-provision/butane [config-spec]: ../../fb-provision/butane/configuration [systemd-userdb]: https://www.freedesktop.org/software/systemd/man/systemd-userdbd.service.html diff --git a/content/docs/latest/os-config/host-config/other-settings.md b/content/docs/latest/os-config/host-config/other-settings.md index 5cb89778c..8e9fd4899 100644 --- a/content/docs/latest/os-config/host-config/other-settings.md +++ b/content/docs/latest/os-config/host-config/other-settings.md @@ -124,10 +124,9 @@ kernel_arguments: ``` Instead of using `kernelArguments` you can also use the plain file directive in Ignition to write to `/usr/share/oem/grub.cfg`. -However, because Ignition runs after GRUB, the GRUB configuration won't take effect until the next reboot of the node. This is particularly -useful if you are bound to use Ignition V2 (which requires the use of `ct` instead of `butane`). +However, because Ignition runs after GRUB, the GRUB configuration won't take effect until the next reboot of the node. -Here's an example Container Linux Configuration for using the plain file directive (this YAML content has to be transpiled to Ignition JSON with `ct`): +Here's an example Butane Config for using the plain file directive: ```yaml storage: @@ -146,7 +145,7 @@ storage: set linux_append="$linux_append flatcar.autologin=tty1" ``` -To take effect directly on first boot, the alternative is to create a `getty@.service` drop-in, here a snippet that will work with `ct` and `butane`: +To take effect directly on first boot, the alternative is to create a `getty@.service` drop-in, here a snippet that will work with `butane`: ``` systemd: diff --git a/content/docs/latest/os-config/systemd/udev-rules.md b/content/docs/latest/os-config/systemd/udev-rules.md index 60865c7e5..674c850c9 100644 --- a/content/docs/latest/os-config/systemd/udev-rules.md +++ b/content/docs/latest/os-config/systemd/udev-rules.md @@ -47,7 +47,7 @@ That rule means that udev will trigger `device-attach.service` systemd unit on a ## Butane Config example -To use the unit and udev rule with a Container Linux Config, modify this example as needed: +To use the unit and udev rule with a Butane Config, modify this example as needed: ```yaml variant: flatcar diff --git a/content/docs/latest/updates-releases/nebraska/managing-updates.md b/content/docs/latest/updates-releases/nebraska/managing-updates.md index 1fa12690b..c9fe0c28f 100644 --- a/content/docs/latest/updates-releases/nebraska/managing-updates.md +++ b/content/docs/latest/updates-releases/nebraska/managing-updates.md @@ -12,7 +12,7 @@ manage their updates. The process for doing so is slightly different depending o ## New machines -For new machines, you can set up the updates server in their Container Linux Configuration. Here is a small example of how to do it: +For new machines, you can set up the updates server in their Butane Configuration. Here is a small example of how to do it: ```yaml @@ -48,7 +48,7 @@ storage: **Note**: The sample Nebraska containers provided use the `port 8000` by default (**plain HTTP, no SSL**). Please adjust the update URL setup in your servers to match your Nebraska deployment. -**Note**: You must not combine the special `locksmith:` CLC section with the above CLC `files:` section (or a similar one with `/etc/coreos/update.conf`) because it results in a conflict where only one entry wins. +**Note**: You must not combine setting the update server via the legacy `locksmith` mechanism with the above `files:` section (or a similar one with `/etc/coreos/update.conf`) because it results in a conflict where only one entry wins. More documentation for the `update.conf` file is [on the Flatcar website](https://www.flatcar.org/docs/latest/setup/releases/update-conf/). @@ -68,7 +68,7 @@ The machine alias is an additional name an instance can use when registering in Since the field is supplied by the instance itself, it's not necessarily unique and can contain arbitrary data. In the instance list it is shown instead of the instance ID, while on the instance page it is shown in addition to the instance ID. -To add a machine alias to your Flatcar Container Linux instance, you can edit the `/etc/flatcar/update.conf` file or create it on deployment through a Container Linux Configuration: +To add a machine alias to your Flatcar Container Linux instance, you can edit the `/etc/flatcar/update.conf` file or create it on deployment through a Butane Configuration: ```yaml variant: flatcar