Skip to content

Commit

Permalink
Remove 'simple', 'good practice' and related terms
Browse files Browse the repository at this point in the history
Things are generally not 'simple' thus the need for documentation. Let's
remove those terms from our docs as much as possible.
  • Loading branch information
travier committed Mar 14, 2024
1 parent 1b8d260 commit 6645195
Show file tree
Hide file tree
Showing 9 changed files with 14 additions and 14 deletions.
2 changes: 1 addition & 1 deletion modules/ROOT/pages/bare-metal.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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].

Expand Down
2 changes: 1 addition & 1 deletion modules/ROOT/pages/getting-started.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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].
Expand Down
2 changes: 1 addition & 1 deletion modules/ROOT/pages/live-booting.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.
4 changes: 2 additions & 2 deletions modules/ROOT/pages/producing-ign.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
== Full 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.

Expand Down
6 changes: 3 additions & 3 deletions modules/ROOT/pages/provisioning-vmware.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]
----
Expand Down Expand Up @@ -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]:

Expand All @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion modules/ROOT/pages/proxy.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
----
Expand Down
4 changes: 2 additions & 2 deletions modules/ROOT/pages/storage.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions modules/ROOT/pages/tutorial-autologin.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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 `[email protected]`.
* The override will make the service automatically log the `core` user in to the serial console of the booted machine.
Expand Down
2 changes: 1 addition & 1 deletion modules/ROOT/pages/tutorial-services.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]
----
Expand Down

0 comments on commit 6645195

Please sign in to comment.