How to Create an Ignition Configuration File

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= core@example.com"
      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= core@example.com"
      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= core@example.com"
      groups: [ sudo, docker ]
storage:
  files:
    - path: /etc/hostname
      overwrite: true
      contents:
        inline: example-hostname

Using a VPC

Ignition can also configure the server for a Virtual Private Cloud (VPC). Before proceeding, make sure you understand how to use a Vultr VPC.

To configure a VPC, 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 that 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= core@example.com"
      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 VPC 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 VPC network adapter with IP address 10.10.10.10. You must enable VPC 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 from the Operating System list.

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.