Getting Started with Flatcar Linux on Brightbox

This guide will help you get started with Flatcar Container Linux on Brightbox. It assumes you have already signed up and configured the command line interface. If you haven’t, follow the Getting Started guide.

Everything here can also be achieved using the Brightbox Control Panel graphical user interface.

Introduction

Flatcar is a minimal, container-optimised Linux distribution, which is a direct descendent and spiritual successor of CoreOS Container Linux, which was discontinued in 2020.

Here, we’ll cover building your first Flatcar server and configuring a simple NGINX container deployment using Butane/Ignition to provide suitable User Data.

Butane Configuration

Flatcar allows you to configure machine parameters, launch systemd units on startup and more using their Butane configuration syntax. Butane configs are intended to be human-readable and are written in YAML. The syntax is quite forgiving and things like references and multi-line strings are supported.

Butane configs are then transpiled into Ignition JSON before use, which can be provided directly as User Data during server creation.

Rather than using Ignition directly, Butane was chosen because it offers better human-readability and provides a number of additional features. Check out Flatcar’s documentation for more details and to learn about all of the supported features.

NGINX Example

For this guide, we’ll use a simple Butane config which creates a directory for our NGINX web root and enables a systemd unit to start an NGINX container, serving a simple index page containing the server’s hostname.

Create a file called nginx-butane.yaml with the following contents:

variant: flatcar
version: 1.0.0
storage:
  directories:
    - path: /var/www
systemd:
  units:
    - name: nginx.service
      enabled: true
      contents: |
        [Unit]
        Description=NGINX example
        After=docker.service coreos-metadata.service
        Requires=docker.service coreos-metadata.service
        [Service]
        EnvironmentFile=/run/metadata/flatcar
        TimeoutStartSec=0
        ExecStartPre=-/usr/bin/docker rm --force nginx1
        ExecStartPre=-/usr/bin/bash -c "echo 'Hello from ${COREOS_OPENSTACK_HOSTNAME}' > /var/www/index.html"
        ExecStart=/usr/bin/docker run --name nginx1 --volume "/var/www:/usr/share/nginx/html:ro" --pull always --log-driver=journald --net host docker.io/nginx:1
        ExecStop=/usr/bin/docker stop nginx1
        Restart=always
        RestartSec=5s
        [Install]
        WantedBy=multi-user.target

Transpiling to Ignition

To transpile the Butane config we just created to Ignition JSON, we’ll use the butane Docker image. You’ll need Docker installed locally, which we won’t cover here.

Pipe the contents of nginx-butane.yaml to a new transpiler container and save the output as nginx-ignition.json:

$ cat nginx-butane.yaml | docker run --rm -i quay.io/coreos/butane:release > nginx-ignition.json

Choosing a Flatcar Server Image

We provide official images of the latest Stable and LTS Flatcar releases in our public image library. You can find them by listing all images and grepping for flatcar:

$ brightbox images list | grep flatcar

 id         owner      type      created_on  status   size   name
 ---------------------------------------------------------------------------------------------------------
 img-s1dtb  brightbox  official  2024-04-04  public   8694    flatcar-lts-amd64-server (x86_64)
 img-c0roj  brightbox  official  2024-04-04  public   8694    flatcar-stable-amd64-server (x86_64)

For this example, we’ll use the latest Stable release (img-c0roj).

Build a New Server

Build a new server with a Cloud IP using the image selected above and provide the previously-created Ignition config as User Data using the --user-data-file flag:

$ brightbox servers create --type 512mb.ssd --cloud-ip=true --user-data-file=./nginx-ignition.json img-c0roj
Creating a 512mb.ssd (typ-1j3zh) server with image flatcar-stable-amd64-server (img-c0roj) with 1.04k of user data mapping a new cloud IP when built

 id         status    type       zone   created_on  image_id   cloud_ip_ids  name
-------------------------------------------------------------------------------------------
 srv-gyfhb  creating  512mb.ssd  gb1-b  2024-04-10  img-c0roj  cip-l5trc     flatcar-nginx
-------------------------------------------------------------------------------------------

Testing Everything Works

After waiting a few seconds for the new server to finish creating and booting, we can test that NGINX has started successfully by using curl to access the Cloud IP hostname provided in the CLI output above:

$ curl http://cip-l5trc.gb1.brightbox.com
Hello from srv-gyfhb.gb1.brightbox.com

We can also access the new server with SSH and confirm that our nginx.service systemd unit is running. The default user is core and any SSH keys associated with your account will be installed automatically during first-boot:

$ ssh core@cip-l5trc.gb1.brightbox.com
Last login: Wed Apr 10 10:26:01 UTC 2024 from 2001:8b0:1d0a:6:fd61:94d:dddc:3c18 on pts/0
Flatcar Container Linux by Kinvolk stable 3815.2.1 for Openstack
core@srv-gyfhb ~ $ systemctl status nginx
● nginx.service - NGINX example
     Loaded: loaded (/etc/systemd/system/nginx.service; enabled; preset: enabled)
     Active: active (running) since Wed 2024-04-10 10:18:56 UTC; 7min ago

Further Reading

Check out Flatcar’s Container Linux Quickstart Guide and their documentation for details on other features and more advanced topics.