Article

Table of Contents
Theme:
Was this article helpful?
Try Vultr Today with

$50 Free on Us!

Want to contribute?

You could earn up to $300 by adding new articles!

How to Create an Ignition Configuration File

Last Updated: Mon, Aug 17, 2020
Containers 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, file systems, 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 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
    

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

Minimal FCC file

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 config, the core user can log in with the private key, but has no password.

Add Password to Core User

If you want a password for the core user, add a password_hash. The password will be accepted for local authentication at the console, but FCOS does 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"

The complete FCC file for context.

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 similar to 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 similar to 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

Complete example with hostname

Here's a full example with the hostname configured, using 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

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:

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

Here's a full FCC file that includes all the previous options:

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 VPS will have 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 with your key. See our 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.

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

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.

More Information

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

Want to contribute?

You could earn up to $300 by adding new articles