From c9cffa76b0f57043cc6189e7995459862772130c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Ravier?= Date: Thu, 14 Mar 2024 11:19:48 +0100 Subject: [PATCH 1/2] Remove 'simple', 'good practice' and related terms Things are generally not 'simple' thus the need for documentation. Let's remove those terms from our docs as much as possible. --- modules/ROOT/pages/bare-metal.adoc | 2 +- modules/ROOT/pages/getting-started.adoc | 2 +- modules/ROOT/pages/live-booting.adoc | 2 +- modules/ROOT/pages/producing-ign.adoc | 4 ++-- modules/ROOT/pages/provisioning-vmware.adoc | 6 +++--- modules/ROOT/pages/proxy.adoc | 2 +- modules/ROOT/pages/storage.adoc | 4 ++-- modules/ROOT/pages/tutorial-autologin.adoc | 4 ++-- modules/ROOT/pages/tutorial-services.adoc | 2 +- 9 files changed, 14 insertions(+), 14 deletions(-) diff --git a/modules/ROOT/pages/bare-metal.adoc b/modules/ROOT/pages/bare-metal.adoc index 2405e757..b6b5ec91 100644 --- a/modules/ROOT/pages/bare-metal.adoc +++ b/modules/ROOT/pages/bare-metal.adoc @@ -36,7 +36,7 @@ sudo coreos-installer install /dev/sda \ --ignition-url https://example.com/example.ign ---- -Once the installation is complete, you can simply `sudo reboot`. After rebooting, the first boot process begins. It is at this time that Ignition ingests the configuration file and provisions the system as specified. +Once the installation is complete, you can reboot the system using `sudo reboot`. After rebooting, the first boot process begins. It is at this time that Ignition ingests the configuration file and provisions the system as specified. For more advanced ISO installs, including automation, see below. For more about the live ISO image, see the xref:live-reference.adoc[live image reference]. diff --git a/modules/ROOT/pages/getting-started.adoc b/modules/ROOT/pages/getting-started.adoc index e44d2eb3..e34570b2 100644 --- a/modules/ROOT/pages/getting-started.adoc +++ b/modules/ROOT/pages/getting-started.adoc @@ -8,7 +8,7 @@ There are three Fedora CoreOS (FCOS) update streams available: `stable`, `testin Each stream has a canonical URL representing its current state in JSON format, known as "stream metadata". For example, the stream metadata URL for `stable` is: https://builds.coreos.fedoraproject.org/streams/stable.json -For automating Fedora CoreOS installations, it is expected that you will interact with stream metadata. While Fedora CoreOS does automatic in-place updates, it is generally a good practice to start provisioning new machines from the latest images. +For automating Fedora CoreOS installations, it is expected that you will interact with stream metadata. While Fedora CoreOS does automatic in-place updates, it is generally recommended to start provisioning new machines from the latest images. For more information on using stream metadata, see xref:stream-metadata.adoc[Stream Metadata]. For more about the available streams, see xref:update-streams.adoc[Update Streams]. diff --git a/modules/ROOT/pages/live-booting.adoc b/modules/ROOT/pages/live-booting.adoc index d885859a..72f36986 100644 --- a/modules/ROOT/pages/live-booting.adoc +++ b/modules/ROOT/pages/live-booting.adoc @@ -123,6 +123,6 @@ In particular, note the following guidelines: Since the traditional FCOS upgrade process requires a disk, the live environment is not able to auto-update in place. For this reason, Zincati is not running there. -For PXE-booted systems, it is recommended that images referenced in the PXE configuration are regularly refreshed. Once infrastructure and configurations are updated, the live PXE instance simply needs to be rebooted in order to start running the new FCOS version. +For PXE-booted systems, it is recommended that images referenced in the PXE configuration are regularly refreshed. Once infrastructure and configurations are updated, the live PXE instance only needs to be rebooted in order to start running the new FCOS version. For ISO-booted systems, the ISO image used to boot the live environment should be periodically refreshed, and the instance rebooted to update the running OS. diff --git a/modules/ROOT/pages/producing-ign.adoc b/modules/ROOT/pages/producing-ign.adoc index 63e4d1ab..5f86e8da 100644 --- a/modules/ROOT/pages/producing-ign.adoc +++ b/modules/ROOT/pages/producing-ign.adoc @@ -17,7 +17,7 @@ During the transpilation process, Butane verifies the syntax of the YAML file, w Once you have an Ignition (`.ign`) file, you can use it to boot an FCOS system in a VM or install it on bare metal. -TIP: Try to plan your configuration with the full set of customization details before provisioning a Fedora CoreOS instance. But don't worry if you forgot something as you can simply fix the configuration and re-deploy the instance from a fresh image. +TIP: Try to plan your configuration with the full set of customization details before provisioning a Fedora CoreOS instance. But don't worry if you forgot something as you can fix the configuration and re-deploy the instance from a fresh image. == Getting Butane @@ -166,7 +166,7 @@ Invoke-RestMethod -Uri https://fedoraproject.org/fedora.gpg | gpg --import gpg --verify butane-x86_64-pc-windows-gnu.exe.asc ---- -== A simple example +== Example Create a basic Ignition config that modifies the default Fedora CoreOS user `core` to allow this user to log in with an SSH key. diff --git a/modules/ROOT/pages/provisioning-vmware.adoc b/modules/ROOT/pages/provisioning-vmware.adoc index 67876043..386613f6 100644 --- a/modules/ROOT/pages/provisioning-vmware.adoc +++ b/modules/ROOT/pages/provisioning-vmware.adoc @@ -52,7 +52,7 @@ CONFIG_ENCODED=$(cat example.ign | gzip -9 | base64 -w0 -) If your generated Ignition configuration is still too large, you will encounter an `Argument list too long` error or similar. The solution to that problem depends on whether you are working with vSphere or Workstation/Fusion. -For vSphere the solution is simple because instead of inlining the configuration file within your shell, `govc` allows you to specify a path to a local file instead with the https://github.com/vmware/govmomi/blob/main/govc/USAGE.md#vmchange[`vm.change`]-command and will handle reading and writing it internally, circumventing any shell limitations. +For vSphere, instead of inlining the configuration file within your shell, `govc` allows you to specify a path to a local file with the https://github.com/vmware/govmomi/blob/main/govc/USAGE.md#vmchange[`vm.change`]-command and will handle reading and writing it internally, circumventing any shell limitations. [source, bash] ---- @@ -208,7 +208,7 @@ For further information on first-boot networking, see https://coreos.github.io/a You may encounter problems with your Ignition configuration that require access to the system log which appears during first-boot. To make a copy of the system log you can attach a serial device to the VM before booting. vSphere as well as Workstation and Fusion allow this and will save the output to a file of your choice. -To attach a serial device simply modify the hardware settings of the powered off VM and add a `Serial Port`. Select the destination and name of the file to be created. Afterwards power on the VM. When encountering an error, check the file you initially specified - it should contain a copy of the system log. +To attach a serial device, modify the hardware settings of the powered off VM and add a `Serial Port`. Select the destination and name of the file to be created. Afterwards power on the VM. When encountering an error, check the file you initially specified - it should contain a copy of the system log. The serial device can also be added to the VM via `govc` as described in the https://github.com/vmware/govmomi/blob/master/govc/USAGE.md#deviceserialconnect[official usage documentation]: @@ -235,7 +235,7 @@ that may not be compatible with older, unsupported VMware products. However, you can modify the image's OVF metadata to specify an older virtual hardware version. -The VMware OVA is simply a tarball that contains the files `disk.vmdk` and +The VMware OVA is a tarball that contains the files `disk.vmdk` and `coreos.ovf`. In order to edit the metadata used by FCOS as a guest VM, you should untar the OVA artifact, edit the OVF file, then create a new OVA file. diff --git a/modules/ROOT/pages/proxy.adoc b/modules/ROOT/pages/proxy.adoc index 97ad128c..8c4cf38b 100644 --- a/modules/ROOT/pages/proxy.adoc +++ b/modules/ROOT/pages/proxy.adoc @@ -6,7 +6,7 @@ This is best done by defining a single file with required environment variables == Defining common proxy environment variables -This common file has to be subsequently referenced explicitly by each service that requires internet access thereby encouraging least privilege best practices. +This common file has to be subsequently referenced explicitly by each service that requires internet access. [source,yaml,subs="attributes"] ---- diff --git a/modules/ROOT/pages/storage.adoc b/modules/ROOT/pages/storage.adoc index 2103cece..79ea964c 100644 --- a/modules/ROOT/pages/storage.adoc +++ b/modules/ROOT/pages/storage.adoc @@ -17,9 +17,9 @@ Many of the examples below will reference a block device, such as `/dev/vda`. Th If your disk configuration is simple and uses the same disk the OS was booted from then the `/dev/disk/by-id/coreos-boot-disk` link can be used to conveniently refer to that device. This link is only available during provisioning for the purpose of making it easy to refer to the same disk the OS was booted from. -In cases where you need to access other disks, the simplest thing to do is to boot a single machine with an Ignition configuration that just gives you SSH access, and inspect the block devices via e.g. the `lsblk` command. +If you need to access other disks, you can boot a single machine with an Ignition configuration with only SSH access, and then inspect the block devices via e.g. the `lsblk` command. -For physical hardware, a good best practice is to reference devices via the `/dev/disk/by-id/` or `/dev/disk/by-path` links. +For physical hardware, it is recommended to reference devices via the `/dev/disk/by-id/` or `/dev/disk/by-path` links. == Setting up separate /var mounts diff --git a/modules/ROOT/pages/tutorial-autologin.adoc b/modules/ROOT/pages/tutorial-autologin.adoc index 54c91acb..e8cb5b35 100644 --- a/modules/ROOT/pages/tutorial-autologin.adoc +++ b/modules/ROOT/pages/tutorial-autologin.adoc @@ -6,11 +6,11 @@ NOTE: Make sure that you have completed the steps described in the xref:tutorial Fedora CoreOS does not have a separate install disk. Instead, every instance starts from a generic disk image which is customized on first boot via https://github.com/coreos/ignition[Ignition]. -Ignition config files are written in JSON but are typically not user-friendly. Configurations are thus written in a simpler format, the Butane config, that is then converted into an Ignition config. The tool responsible for converting Butane configs into Ignition configs is naturally called Butane. +Ignition config files are written in JSON but are typically not user-friendly. Configurations are thus written in a simpler format, the Butane config, that is then converted into an Ignition config. The tool responsible for converting Butane configs into Ignition configs is called Butane. == First Ignition config via Butane -Let's create a very simple Butane config that will perform the following actions: +Let's create a small Butane config that will perform the following actions: * Add a systemd dropin to override the default `serial-getty@ttyS0.service`. * The override will make the service automatically log the `core` user in to the serial console of the booted machine. diff --git a/modules/ROOT/pages/tutorial-services.adoc b/modules/ROOT/pages/tutorial-services.adoc index 8ce271b7..a82e99ad 100644 --- a/modules/ROOT/pages/tutorial-services.adoc +++ b/modules/ROOT/pages/tutorial-services.adoc @@ -9,7 +9,7 @@ In this tutorial, we will run a script on the first boot via a systemd service. == Writing the script -Let's write a simple script that uses https://icanhazip.com/[icanhazip.com] to create an issue file to display as a prelogin message on the console and store it in `public-ipv4.sh`. +Let's write a small script that uses https://icanhazip.com/[icanhazip.com] to create an issue file to display as a prelogin message on the console and store it in `public-ipv4.sh`. [source,bash] ---- From f4d7e19781fd104f626aeeaea80457d056422750 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Ravier?= Date: Thu, 14 Mar 2024 11:21:15 +0100 Subject: [PATCH 2/2] provisioning-vmware: Turn note into a NOTE --- modules/ROOT/pages/provisioning-vmware.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/provisioning-vmware.adoc b/modules/ROOT/pages/provisioning-vmware.adoc index 386613f6..01ec038a 100644 --- a/modules/ROOT/pages/provisioning-vmware.adoc +++ b/modules/ROOT/pages/provisioning-vmware.adoc @@ -239,8 +239,9 @@ The VMware OVA is a tarball that contains the files `disk.vmdk` and `coreos.ovf`. In order to edit the metadata used by FCOS as a guest VM, you should untar the OVA artifact, edit the OVF file, then create a new OVA file. -The example commands below change the OVF hardware version from the preconfigured -value to hardware version `13`. (Note: the defaults in the OVF are subject to change.) +The example commands below change the OVF hardware version from the preconfigured value to hardware version `13`. + +NOTE: The defaults in the OVF are subject to change. [source,bash,subs="attributes"] ----