Provisioning and Configuration
This guide introduces the in-depth configuration specification for human-friendly FCOS Configuration (FCC) YAML files.
Rather than read these detailed instructions, advanced users may want to reference the configuration specification for an abbreviated list of options. |
Ignition overview
Ignition is a provisioning utility that reads a configuration file (in JSON format) and provisions an FCOS system based on that configuration. Configurable components include storage and filesystems, systemd units, and users.
Ignition runs only once during the first boot of the system (in initramfs). Because Ignition runs so early in the boot process, it can re-partition disks, format filesystems, create users, and write files before the userspace begins to boot. As a result, systemd services are already written to disk when systemd starts, speeding the time to boot.
Configuration process
Ignition configurations are formatted as JSON, which is quick and easy for a machine to read. However, these files are not easy for humans to read or write. The solution is a two-step configuration process that is friendly for both humans and machines:
-
Produce a YAML-formatted Fedora CoreOS Configuration (FCC) file.
-
Run the Fedora CoreOS Configuration Transpiler (
fcct
) to convert the YAML file into a JSON Ignition file.
During the transpilation process, fcct
verifies the syntax of the YAML file, which can catch errors before you use it to launch the FCOS system.
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.
FCC file structure
The FCC file follows YAML syntax and contains the following top-level nodes:
-
variant
: specifiesfcos
as the operating system -
version
: specifies the version offcct
-
ignition
: specifies a remote configuration (for convenience or for platforms that do not allow for the ingestion of large configuration files) -
storage
: provisions storage and configures the filesystem -
systemd
: controls systemd units -
passwd
: configures users
YAML files must have consistent indentation. See the YAML Specification for further details. |
FCC file metadata (variant
and version
)
The first two lines of an FCC file define fcos
as the operating system and the semantic version of the document specification (e.g. 1.3.0
). Both lines are required.
variant: fcos
version: 1.3.0
Ignition metadata (ignition
)
The optional ignition
block defines the metadata for the Ignition configuration. It allows you to specify a remote configuration file for platforms that do not allow the direct ingestion of large configuration files. It tells Ignition to start the first boot of FCOS, at which time, Ignition will fetch the specified Ignition file from a remote server.
Nodes
The ignition
node contains the following nodes:
-
config
- provides the location of the remote Ignition file and specifies whether tomerge
it with the current file orreplace
it. -
timeouts
- specifies how to handle http responses. -
security
- specifies a tls certificate authority, if necessary.
Remote configuration file (config
)
The first line of the config
node specifies whether you want to merge
or replace
the remote configuration. Regardless of this choice, the following lines are the same:
-
source
defines the remote location as a URL. The supported schemes arehttp
,https
,s3
,tftp
, anddata
. -
verification
is optional but recommended when using thehttp
scheme. It contains a hash of the configuration-
hash
provides the hash string in the form<type>-<value>
wheretype
issha512
.
-
Handling HTTP responses (timeouts
)
This node is optional but recommended when fetching Ignition files via http
or https
.
-
http_response_headers
is an integer for the time to wait (in seconds) for the server’s response headers (but not the body) after making the request. The default is10
. To specify no timeout, set the value to0
. -
http_total
is an integer for the time limit (in seconds) for the entire operation (connection, request, and response), including any retries. The default is0
for no timeout.
Network security (security
)
This optional node provides options related to TLS when fetching an Ignition file via https
. It contains the tls
object, which contains the certificate_authorities
, a list of certificate authorities (in addition to system authorities) to be used for TLS verification. All certificate authorities must have a unique source
:
-
source
is a string that specifies the URL of the certificate in PEM format. The supported schemes arehttp
,https
,s3
,tftp
, anddata
. -
verification
is optional but recommended when using thehttp
scheme. It contains a hash of the certificate.-
hash
provides the hash string in the form<type>-<value>
wheretype
issha512
.
-
Note that certificate authorities listed here are not automatically added to the host filesystem. They are solely used by Ignition itself when fetching over https
. If you’d like to also install them on the host filesystem, include them as usual under the storage.files
array.
Examples
The following examples show how to retrieve an Ignition file from a remote source. They are both set to replace the current configuration with a remote Ignition file.
variant: fcos
version: 1.3.0
ignition:
config:
replace:
source: http://example.com/sample.ign
verification:
hash: sha512-e2bb19fdbc3604f511b13d66f4c675f011a63dd967b97e2fe4f5d50bf6cb224e902182221ba0f9dd87c0bb4abcbd2ab428eb7965aa7f177eb5630e7a1793e2e6
variant: fcos
version: 1.3.0
ignition:
config:
replace:
source: https://example.com/sample.ign
security:
tls:
certificate_authorities:
- source: https://example.com/source1
verification:
hash: sha512-e2bb19fdbc3604f511b13d66f4c675f011a63dd967b97e2fe4f5d50bf6cb224e902182221ba0f9dd87c0bb4abcbd2ab428eb7965aa7f177eb5630e7a1793e2e6
Storage specification
This section describes the FCOS Configuration (FCC) YAML format for defining the desired state of storage associated with a FCOS instance. See also Configuring Storage which contains examples for customizing the default storage layout.
The storage
block contains a list of objects, which can be of the following type:
-
disks
: List of disks -
raid
: List of RAID arrays -
filesystems
: List of filesystems -
files
: List of files to be written -
directories
: List of directories to be created -
links
: List of links to be created
Disks
Every entry under the disks
node must correspond to a unique device. For each device, specify a list of GPT partitions. Unless specified as optional, all nodes are mandatory. The contents of disks
is as follows:
-
device
(string): Absolute path of the disk device. Disks are typically referenced by the/dev/disk/by-*
symlinks. Avoid specifying the disk device/dev/sdx
directly: when new disks are inserted, the system might re-enumerate devices at boot. This could change the order of the/dev/sdx
devices. The/dev/disk/by-*
symlinks always point to the right devices. -
wipe_table
(boolean, optional): Whentrue
, Ignition erases the partition table before proceeding. Otherwise, the table’s existing partition entries are left alone. -
partitions
(object list, optional): List of partitions to be written to the partition table of the device. Each partition occupies a slot in the table. You can either specify the slot directly with thenumber
node, or specifynumber: 0
and supply a uniquelabel
.-
label
(string, optional): GPT PARTLABEL for the partition. -
number
(integer, optional): Slot number occupied by the partition, starting at 1. To use the next available slot, specify0
. In this case, you should also specify a uniquelabel
. -
size_mib
(integer, optional): Size of the partition in mebibytes. If0
, the partition is sized as large as possible. Note: 1 mebibytes = 1024 * 1024 bytes. -
start_mib
(integer, optional): Start position of the partition from the beginning of the disk, in mebibytes. If0
, the partition will be placed at the start of the largest block available. -
type_guid
(string, optional): Partition type GUID. If omitted, it defaults to0FC63DAF-8483-4772-8E79-3D69D8477DE4
, the Linux native file system GUID. The ultimate reference list for the type GUIDs is currently the parttypes.cc file in the GPT fdisk source code. A more readable list can be found in the GUID Partition Table article on Wikipedia. -
guid
(string, optional, must be unique): GUID of the partition. You can omit this when creating new partitions. -
wipe_partition_entry
(boolean, optional)-
true: Ignition erases any existing partition that does not match this entry.
-
false: Ignition leaves the partition unchanged, which will fail.
-
-
should_exist
(boolean, optional). Defaults totrue
.-
true: If
true
and if it does not already exist, the partition with the specifiednumber
is created. If the partition exists, andwipe_partition_entry
isfalse
, thennumber
must be specified as a non-zero integer, andlabel
,start_mib
,size_mib
,guid
andtype_guid
must all be omitted. -
false: If
false
and the partition exists, Ignition looks at thewipe_partition_entry
value and deletes the partition iftrue
, or fails iffalse
.
-
-
variant: fcos
version: 1.3.0
storage:
disks:
-
# Mandatory. We use the World-Wide Number ID of the drive to ensure
# uniqueness.
device: /dev/disk/by-id/wwn-0x50014e2eb507fcdf
# This ensures that the partition table is re-created, along with all
# the partitions.
wipe_table: true
partitions:
# The first partition (slot number 1) is 32 GiB and starts at the
# beginning of the device. Its type_guid identifies it as a Linux
# swap partition.
- label: part1
number: 1
size_mib: 32768
start_mib: 0
type_guid: 0657fd6d-a4ab-43c4-84e5-0933c84b4f4f
# The second partition (implicit slot number 2) will be placed after
# partition 1 and will occupy the rest of the available space.
# Since type_guid is not specified, it will be a Linux native
# partition.
- label: part2
number: 0
Raid
Every entry under the raid
node must correspond to a unique RAID array. The resulting configuration is implemented as an mdadm "software" RAID. The contents of raid
is as follows. Unless specified as optional, all nodes are mandatory.
-
name
(string): Name of the resulting md device. -
level
(string): Redundancy level of the array. See the supported levels in the Fedoramdadm
man page. Examples:linear
,raid0
,raid
. -
devices
(list of strings): List of devices that should be part of the array, referenced by absolute path. -
spares
(optional, integer): Number of spares in the array, if applicable. -
options
(optional, list of strings): Additional options to be passed tomdadm
.
File systems
Entries under the filesystems
node list the file systems to be created and mounted. Each file system must have a unique device. The contents of filesystems
is as follows. Unless specified as optional, all nodes are mandatory.
-
path
(string): Mount point of of the filesystem while Ignition is running, relative to where the root filesystem will be mounted. This is not necessarily the same as where it should be mounted in the real root, but you should set it as such. -
device
(string): Absolute path of the device. -
format
(string): File system "format" (ie - file system type). Accepted values:ext4
,btrfs
,xfs
,vfat
, orswap
. -
wipe_filesystem
(boolean, optional): If true, the device is wiped before the file system is created. -
label
(string, optional): Label of the file system. -
uuid
(string, optional): UUID of the file system. -
options
(list of strings, optional): Additional options to be passed tomkfs
.
variant: fcos
version: 1.3.0
storage:
disks:
# This defines two partitions, each on its own disk. The disks are
# identified by their WWN.
- device: /dev/disk/by-id/wwn-0x50014ee261e524e4
wipe_table: true
partitions:
-
# Each partition gets a human-readable label.
label: "raid.1.1"
# Each partition is placed at the beginning of the disk and is 64 GiB
# long.
number: 1
size_mib: 65536
start_mib: 0
- device: /dev/disk/by-id/wwn-0x50014ee0b8442cd3
wipe_table: true
partitions:
- label: "raid.1.2"
number: 1
size_mib: 65536
start_mib: 0
# We use the previously defined partitions as devices in a RAID1 md array.
raid:
- name: publicdata
level: raid1
devices:
- /dev/disk/by-partlabel/raid.1.1
- /dev/disk/by-partlabel/raid.1.2
# The resulting md array is used to create an EXT4 file system.
filesystems:
- path: /var/publicdata
device: /dev/md/publicdata
format: ext4
label: PUB
Files
The files
node lets you define a list of files, identified by a unique path, that Ignition will create with the required contents and attributes as needed.
An empty file would not be very useful, so the files can be defined with a contents
option to specify either a source from which the file will be copied, or inline data.
The contents of files
is as follows. Unless specified as optional, all nodes are mandatory.
-
path
(string, must be unique): Absolute path of the file to be created. -
overwrite
(boolean, optional): Defaults tofalse
. Iftrue
,source
must be specified, and any preexisting file of the specifiedpath
will be overwritten with the contents ofsource
. -
contents
(object, optional): Specifies the contents of the file.-
compression
(string, optional): Type of compression of the source. Possible values arenull
orgzip
. Defaults tonull
. Compression cannot be specified ifsource
uses ans3
scheme. -
source
(string, optional): Mandatory ifoverwrite
is true. Mutually exclusive with optioninline
. Specifies the URL of the source to be copied to thepath
. Supported schemes arehttp
,https
,tftp
,s3
, anddata
. If you use thehttp
scheme, you should specify a verification option to ensure the remote contents have not changed. Ifsource
is omitted, Ignition checks if the file already exists:-
File exists: Ignition does nothing.
-
File does not exist: Ignition creates an empty file.
-
-
inline
(string, optional): Mutually exclusive with optionsource
. Specifies a string to be written to the file. -
verification
(object, optional): Tells Ignition to verify the contents of the file. Currently, only one verification option has been implemented:hash
.-
hash
(string, mandatory ifverification
is specified): Hash of the file contents, in the form<type>-<value>
. The only supportedtype
issha512
.
-
-
-
append
(object list, optional): This node has the same options assource
. It specifies contents to be appended to the (presumably existing) file.-
compression
: Seecontents
. -
source
: Seecontents
. -
inline
: Seecontents
. -
verification
: Seecontents
.-
hash
: Seecontents
.
-
-
-
mode
(integer, optional): Specifies the file’s permission or mode. Ifmode
is not specified, Ignition checks to see if the file already exists:-
File exists: Keep the existing file mode if
overwrite
is false andsource
is not specified. Otherwise, set mode to octal 0644. -
File does not exist:
mode
defaults to octal 0644.
-
-
user
(object, optional): Specifies the user ID of the file owner. Either an ID or name must be specified.-
id
(integer, optional): User ID of the owner. -
name
(string, optional): User name of the owner.
-
-
group
(object, optional): Specifies the group of the file owner. Either an ID or name must be specified.-
id
(integer, optional): Group ID of the owner. -
name
(string, optional): Group name of the owner.
-
Directories
The directories
node specifies a list of directories, identified by a unique path, that Ignition creates as needed.
The directories
structure is similar to the files
structure. Unless specified as optional, all nodes are mandatory.
-
path
(string): See Files. -
overwrite
(boolean, optional): Defaults tofalse
. Iftrue
, preexisting files or directories at the specifiedpath
are removed. Ifoverwrite
isfalse
and a file system object already exists at the specifiedpath
, Ignition checks the type of the existing file system object:-
Existing path is a directory: Ignition does nothing
-
Existing path is not a directory: Ignition fails.
-
-
mode
(integer, optional): Specifies the directory’s permission or mode. Ifmode
is not specified, Ignition checks to see if the directory already exists:-
Directory exists: if
overwrite
is false, Ignition does nothing, otherwise the mode is set to octal0755
. -
Directory does not exist: The
mode
is set to0755
.
-
-
user
: Specifies the directory owner. See Files.-
id
: See Files -
name
: See Files
-
-
group
: Specifies the directory group. See Files.-
id
: See Files -
name
: See Files
-
Links
The links
node lets you specify links (hard or symbolic) to be created by Ignition as needed.
The contents of links
is as follows. Unless specified as optional, all nodes are mandatory.
-
path
(string, must be unique): Absolute path of the link to be created. -
overwrite
(boolean, optional): Defaults tofalse
. Iffalse
and a link already exists at the specified path, Ignition sets only the owner and group. -
user
: Specifies the link owner. See Files.-
id
: See Files. -
name
: See Files.
-
-
group
: Specifies the link group. See Files.-
id
: See Files. -
name
: See Files.
-
-
target
(string): Target path of the link. -
hard
(boolean, optional): Defaults tofalse
. Iftrue
, Ignition creates a hard link. If false, it creates a symbolic link
variant: fcos
version: 1.3.0
storage:
# This creates a directory. Its mode is set to 0755 by default, that
# is, readable and executable by all, and writable by the owner.
directories:
- path: /opt/tools
overwrite: true
files:
-
# Creates a file /var/helloworld containing a string defined in-line.
path: /var/helloworld
overwrite: true
contents:
inline: Hello, world!
# Sets the file mode to 0644 (readable by all, also writable by the
# owner).
mode: 0644
user:
# The owner uid and group are defined by their numerical IDs.
id: 500
group:
id: 500
-
# We need the nifty (and alas imaginary) transmogrifier tool.
path: /opt/tools/transmogrifier
overwrite: true
# Deploys this tool by copying an executable from an https link. The
# file is compressed with gzip.
contents:
source: https://mytools.example.com/path/to/archive.gzip
compression: gzip
verification:
# The hash is sha512- followed by the 128 hex characters given by
# the sha512sum command.
hash: sha512-00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
# Makes the tool file readable and executable by all.
mode: 0555
links:
-
# Creates a symlink to the tool location from /usr/local/bin. This is
# useful to let local processes invoke this tool without altering
# their PATH environment variable.
path: /usr/local/bin/transmogrifier
overwrite: true
target: /opt/tools/transmogrifier
hard: false
Configuring systemd Units (systemd
)
The systemd
node of an FCC file allows you to add and configure systemd units on the FCOS machine.
Nodes
The systemd
node contains one top-level node: a list of units. For each unit, the following options are available:
-
name
(string, required, must be unique): the full name of the unit in the form ofthing.service
. -
enabled
(boolean): When set totrue
, the unit is enabled. By default, the service is unmodified. For a unit to run, it must have an[Install]
section. -
mask
(boolean): determines whether the unit is masked. When set totrue
, the service is masked by a symlink to/dev/null
. -
contents
(string): the contents of the unit. -
dropins
(list of objects): a list of drop-ins for the unit.-
name
(string, required, must be unique): the name of the drop-in, which must have a suffix of.conf
. -
contents
(string): the contents of the drop-in.
-
Examples
Running Containers shows some examples of adding systemd units to an FCC file.
Configuring Users (passwd
)
The passwd
node allows you to create, modify, and configure FCOS users.
FCOS has a default privileged user named core . You can use this user for system administration tasks. Use the passwd node to modify this user’s attributes, as shown below.
|
Nodes
The top-level nodes for passwd
include users
and groups
. These are both lists of objects.
-
users
(list of objects): the lists of accounts to create on FCOS.-
name
(string, required, must be unique): the username -
password_hash
(string): the hashed password for the account. -
ssh_authorized_keys
(list of strings, each must be unique): a list of SSH keys to be added as an SSH key fragment in the user’s home directory (.ssh/authorized_keys.d/ignition
). -
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): when set to true, no home directory is created for the user. This does not have any effect on any existing home directory. -
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): when true, does not create a user group for the account. This has no effect on any existing groups. -
no_log_init
(boolean): when set totrue
, does not add the user to the lastlog and faillog databases. This has no effect on any existing accounts. -
shell
(string): the login shell of the new account -
system
(boolean): when set totrue
, creates the account as a system account. Has no effect on an existing account.
-
-
groups
(list of objects): a list of groups to be added-
name
(string, required, must be unique): the name of the group -
gid
(integer): the group ID of the group -
password_hash
(string): the hashed password for the group -
system
(boolean): when set totrue
, the group is created as a system group. Has no effect on existing groups.
-
Examples
Producing an Ignition File is a tutorial for how to provide an SSH key for login of the existing core
user.
You can also add a password hash to this user, specify the user’s groups, and add more users as shown below:
variant: fcos
version: 1.3.0
passwd:
users:
- name: core
ssh_authorized_keys:
- "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDGdByTgSVHq......."
- name: elroy
password_hash: "$6$5s2u6/jR$un0AvWnqilcgaNB3Mkxd5yYv6mTlWfOoCYHZmfi3LDKVltj.E8XNKEcwWm..."
ssh_authorized_keys:
- "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDGdByTgSVHq......."
groups: [ sudo, docker ]
As you can see from this snippet, the core
user is modified with a private SSH key, and a new user named elroy
is added. The elroy
user can log in with a private SSH key or with a password and is added to the sudo
and docker
groups.