How to Create an Ignition Configuration File

<?xml encoding="utf-8" ??>

Introduction

This guide shows how to create an Ignition configuration to deploy a Fedora CoreOS (FCOS) cloud server instance at Vultr. Ignition files are JSON formatted provisioning instructions that configure storage, file systems, systemd units, networks, users, and other items during the first boot of the system. You must supply an Ignition file in the Vultr customer portal when you deploy an FCOS server. The preferred way to create an Ignition file is by transpiling a Fedora CoreOS Configuration (FCC) file with the Fedora CoreOS Config Transpiler, fcct.

1. Install fcct

The fcct utility is available for Linux, macOS, and Windows. Windows users may need to install Gpg4win to verify the file signature.

1. Download the Fedora signing keys.

   $ wget https://getfedora.org/static/fedora.gpg
   

2. Import the keys to gpg.

   $ gpg --import fedora.gpg
   

3. Download the latest version of fcct for your architecture. This example uses fcct-x86_64-unknown-linux-gnu.

4. Download the corresponding detached signature. This example uses fcct-x86_64-unknown-linux-gnu.asc.

5. Verify the download.

   $ gpg --verify fcct-x86_64-unknown-linux-gnu.asc fcct-x86_64-unknown-linux-gnu
   

6. Make the file executable.

   $ chmod +x fcct-x86_64-unknown-linux-gnu
   

2. Create an FCC File

Fedora CoreOS Configuration (FCC) files are in YAML format. See the full FCC YAML language specification for more information, and advanced users may prefer the specification summary.

On your local system, create an example FCC file.

$ nano example.fcc

A Minimal FCC File Example

This is a minimal, working FCC file. The public SSH key is truncated for clarity.

variant: fcos
version: 1.0.0
passwd:
  users:
    - name: core
      ssh_authorized_keys:
        - "ssh-rsa AAAAB3Nza...QP0MTkX0= [email protected]"
      groups: [ sudo, docker ]

This will provision an FCOS instance with an SSH key for the core user, and will make the core user a member of the sudo and docker groups. With this minimal configuration, the core user can log in with the private key, but has no password.

Add Password to Core User

Add a password_hash if you need a password for the core user. The password is accepted for local authentication at the console, but FCOS will not allow password authentication via SSH. Use a YAML stanza as shown. The password hash is truncated for clarity.

  users:
    - name: core
      password_hash: "$5$QQx.D1549w$INeU4...OyuLyUbdi1AyA"

Here is the completed FCC file example.

variant: fcos
version: 1.0.0
passwd:
  users:
    - name: core
      password_hash: "$5$QQx.D1549w$INeU4...OyuLyUbdi1AyA"
      ssh_authorized_keys:
        - "ssh-rsa AAAAB3Nza...QP0MTkX0= [email protected]"
      groups: [ sudo, docker ]

Set Hostname

You can set the hostname via Ignition through one of two methods:

1. Write the /etc/hostname file directly.
2. Create a one-shot systemd service.

Option 1: Write the /etc/hostname file directly

Include a YAML stanza in your .fcc file like this example. Replace example-hostname with your server hostname.

storage:
  files:
    - path: /etc/hostname
      overwrite: true
      contents:
        inline: example-hostname

Option 2: Create a oneshot systemd service

Include a YAML stanza in your .fcc file like this example. Replace example-hostname with your server hostname.

systemd:
  units:
    - name: set-hostname.service
      enabled: true
      contents: |
        [Unit]
        Description=Set the hostname

        [Service]
        Type=oneshot
        ExecStart=/usr/bin/hostnamectl set-hostname example-hostname

        [Install]
        WantedBy=multi-user.target

FCC example with Hostname

Here's an FCC example with the hostname configured, as described before in Option 1.

variant: fcos
version: 1.0.0
passwd:
  users:
    - name: core
      password_hash: "$5$QQx.D1549w$INeU4...OyuLyUbdi1AyA"
      ssh_authorized_keys:
        - "ssh-rsa AAAAB3Nza...QP0MTkX0= [email protected]"
      groups: [ sudo, docker ]
storage:
  files:
    - path: /etc/hostname
      overwrite: true
      contents:
        inline: example-hostname

Private Networking

Ignition can also configure a VPS for private networking. Before proceeding, make sure you understand how to use private networking at Vultr and create a private network at the deployment location. For more information, refer to our private networking documentation:

• Configuring Private Network
• Multiple Private Networks

? Private Networking Notes

• When you enable private networking, you may use any RFC1918 private address for your ignition files: 10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16.
• You may choose any RFC1918 address, as long as there are no conflicts with your other instances at that location.
• Private networks can not communicate between locations, regardless of IP addressing. For example, server instances in Miami can not see private networks in Dallas.
• The private IP addresses shown in the customer portal are suggestions. You are not required to use these suggested private IP addresses.
• Private networks do not have DHCP, you must manually manage your IP address space or install your own DHCP server on your private network.
• For optimal performance, we suggest setting your private network adapters' MTU to 1450 when configuring the NIC at the OS level.

To configure a private network, include a YAML stanza that writes your network information. Replace the example IP address with your address.

storage:
  files:
    - path: /etc/NetworkManager/system-connections/ens7.nmconnection
      mode: 0600
      overwrite: true
      contents:
        inline: |
          [connection]
          type=ethernet
          interface-name=ens7

          [ipv4]
          method=manual
          addresses=10.10.10.10/20

Complete FCC Example

Here's a full FCC example file which includes all the sections described before.

variant: fcos
version: 1.0.0
passwd:
  users:
    - name: core
      password_hash: "$5$QQx.D1549w$INeU4...OyuLyUbdi1AyA"
      ssh_authorized_keys:
        - "ssh-rsa AAAAB3Nza...QP0MTkX0= [email protected]"
      groups: [ sudo, docker ]
storage:
  files:
    - path: /etc/hostname
      mode: 0644
      overwrite: true
      contents:
        inline: example-hostname
    - path: /etc/NetworkManager/system-connections/ens7.nmconnection
      mode: 0600
      overwrite: true
      contents:
        inline: |
          [connection]
          type=ethernet
          interface-name=ens7

          [ipv4]
          method=manual
          addresses=10.10.10.10/20

The deployed cloud server has two adapters:

• ens3 on the public network, configured by DHCP.
• ens7 on the private network, with the static IP address set by Ignition.

Example Reference Files

The full example FCC file is available for download along with the corresponding compiled Ignition file. The example will:

• Install an example public SSH key for the core user. Replace the example key with your key. See Vultr's documentation to create a public/private key pair on your platform.
• Set the core user password to: example-password
• Set the instance hostname to: example-hostname
• Create a private network adapter with IP address 10.10.10.10. You must enable private networking on the instance for the adapter to function.

3. Transpile FCC to Ignition

The FCC file must be transpiled to Ignition format before use.

$ ./fcct-x86_64-unknown-linux-gnu -o example.ign example.fcc

4. Deploy Fedora CoreOS with Ignition

1. Deploy a new server in your Vultr customer portal.
2. Select Fedora CoreOS as the server type.

3. Paste the contents of your example.ign file to the Ignition field.

   

4. Select your deployment options and click Deploy Now.

More Information

Find more information about Ignition and FCC at the Fedora CoreOS site.