How to Create an Ignition Configuration File

Last Updated: Wed, Jul 15, 2020
Containers CoreOS FAQ Fedora CoreOS

Introduction

Ignition files are JSON formatted provisioning instructions for container-centric operating systems such as Fedora CoreOS (FCOS) and Flatcar Linux. Ignition can configure system components like storage, filesystems, systemd units, and users. Ignition runs one time, during the first boot of the system. When you provision an FCOS server at Vultr, you must supply an Ignition file in the customer portal. Ignition files are created by transpiling Fedora CoreOS Configuration (FCC) files with the Fedora CoreOS Config Transpiler, fcct.

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 cooresponding 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
    

Create an FCC File

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

On your local system, create an example FCC file.

$ nano example.fcc

This FCC file instructs Ignition to make the core user a member of the sudo and docker groups. The user is allowed to log in via SSH with an RSA key pair. The example SSH key is truncated for clarity. We also have the fully-tested example.fcc available for download. See our documentation to create a public/private key pair on your platform.

variant: fcos
version: 1.0.0
passwd:
  users:
    - name: core
      ssh_authorized_keys:
        - "ssh-rsa AAAA..."
      groups: [ sudo, docker ]

Transpile FCC to Ignition

This file must be transpiled to Ignition format with fcct as shown before use. This example is for x86_64 Linux.

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

The example.ign output file looks similar to this:

{"ignition":{"version":"3.0.0"},"passwd":{"users":[{"groups":["sudo","docker"],"name":"core","sshAuthorizedKeys":["ssh-rsa AAAA..."]}]}}

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.

    Ignition

  4. Select your deployment options and click Deploy Now.

Private Networking

Ignition can also configure a VPS for private networking. Before proceeding, make sure you understand how to use private networking at Vultr. Before deploying your VPS, create a private network at the deployment location.

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.

For more information, refer to our private networking documentation:

Create the private-net.fcc file as shown below. Replace 192.0.2.123/20 with your chosen private IP address and subnet. The example SSH key is truncated for clarity. We also have the fully-tested private-net.fcc available for download.

variant: fcos
version: 1.0.0
passwd:
  users:
    - name: core
      ssh_authorized_keys:
        - "ssh-rsa AAAA..."
      groups: [ sudo, docker ]
storage:
  files:
    - path: /etc/NetworkManager/system-connections/eth1.nmconnection
      mode: 0600
      overwrite: true
      contents:
        inline: |
          [connection]
          type=ethernet
          interface-name=eth1

          [ipv4]
          method=manual
          addresses=192.0.2.123/20

Transpile the file in the same manner as before, and use the private-net.ign file to deploy your server.

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

The deployed VPS will have two adapters:

  • eth0 on the public network, configured by DHCP.
  • eth1 on the private network, with the static IP address set in the ignition file.

The transpiled private-net.ign file will look similar to this:

{"ignition":{"version":"3.0.0"},"passwd":{"users":[{"groups":["sudo","docker"],"name":"core","sshAuthorizedKeys":["ssh-rsa AAAA..."]}]},"storage":{"files":[{"overwrite":true,"path":"/etc/NetworkManager/system-connections/eth1.nmconnection","contents":{"source":"data:,%5Bconnection%5D%0Atype%3Dethernet%0Ainterface-name%3Deth1%0A%0A%5Bipv4%5D%0Amethod%3Dmanual%0Aaddresses%3D192.0.2.123%2F20%0A"},"mode":384}]}}

More Information

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

Example Reference Files

The examples above have truncated SSH keys for readability. Below are download links for the files used in this this documentation. These files are tested and working as of the publication date. You will need to swap your public SSH key for the example key.

Want to contribute?

You could earn up to $300 by adding new articles