Flatcar Linux

The Middleware Infrastructure Agent collects telemetry from Flatcar Linux nodes. Defining the agent container in Butane and provisioning it through Ignition makes monitoring setup repeatable when nodes are created or replaced.

The Agent runs as a container managed by a systemd service defined through your Butane and Ignition configuration.

Prerequisites#

Before installing the Middleware Agent on Flatcar Linux, make sure you have:

Butane — Used to convert human-readable Butane configuration files into machine-readable Ignition configurations.
Ignition — The provisioning format used by Flatcar Linux to configure and initialize the system.
A running Flatcar Linux node — Docker must be installed and available on the node.

Installation#

1 Create the Butane configuration#

Add the mw-agent.service systemd unit to your existing Butane configuration.

The service starts and manages the Middleware Infrastructure Agent container on the Flatcar node.

1variant: flatcar
2version: 1.0.0
3systemd:
4  units:
5    - name: mw-agent.service
6      enabled: true
7      contents: |
8        [Unit]
9        Description=Middleware Agent
10        After=docker.service
11
12        [Service]
13        Environment="MW_API_KEY=<MW_API_KEY>"
14        Environment="MW_TARGET=https://<MW_UID>.middleware.io:443"
15        ExecStart=/usr/bin/docker run \
16          --name mw-agent \
17          --privileged \
18          -e MW_API_KEY \
19          -e MW_TARGET \
20          ghcr.io/middleware-labs/mw-host-agent:master
21        Restart=always
22
23        [Install]
24        WantedBy=multi-user.target

Replace <MW_API_KEY> and <MW_UID> with your actual values.

2 Generate the Ignition configuration#

Convert the Butane configuration into an Ignition configuration.

1butane your-configuration.bn > ignition.ign

This generates the ignition.ign file.

Use the contents of ignition.ign when provisioning your Flatcar node. The configuration creates the required systemd service and starts the Middleware Infrastructure Agent during node initialization.

3 Add host tags (optional)#

To associate custom tags with the host, set the MW_HOST_TAGS environment variable in the Agent configuration along with your Middleware API key.

Specify multiple tags as comma-separated key=value pairs.

1MW_HOST_TAGS=env:production,role:web MW_API_KEY="<MW_API_KEY>"

After the host starts reporting data, verify the configured tags in the Middleware UI: Infrastructure → [Your Host] → System Information

4 Verify the installation#

After provisioning the Flatcar node, verify that the Middleware Agent container was created and check its status.

Run:

1docker ps -a --filter ancestor=ghcr.io/middleware-labs/mw-host-agent:master

Check the command output:

Up — The Agent container is running and the installation was successful.
Exited — The Agent container was created but is no longer running. Check the container logs and exit code to identify the failure.
No container or an error — The Agent container was not created successfully. Review the Butane/Ignition configuration and provisioning process.

After confirming that the container is running, go to Infrastructure Monitoring → Hosts and verify that the Flatcar node is reporting data.

Manage the agent (Commands)#

The Middleware Agent is managed by a systemd service on the Flatcar node.

Use the following commands to start, stop, restart, and check the status of the Agent service.

Action	Command
Start Agent	`sudo systemctl start mw-agent.service`
Stop Agent	`sudo systemctl stop mw-agent.service`
Restart Agent	`sudo systemctl restart mw-agent.service`
Check service status	`sudo systemctl status mw-agent.service`
View service logs	`sudo journalctl -u mw-agent.service --no-pager`
Verify Docker container	`docker ps -a --filter ancestor=ghcr.io/middleware-labs/mw-host-agent:master`

Verify data collection#

After the Agent is running, go to Infrastructure Monitoring → Hosts and verify that the Flatcar node is reporting data.

After data collection starts, you can:

View host metrics in Infrastructure Monitoring.
View collected host logs in Log Monitoring.
Create alerts for collected metrics.
Create custom dashboards to visualize and monitor metrics from your Flatcar nodes.

Uninstall#

If you need to remove the Middleware.io Infra Agent from your Fedora CoreOS host, follow these steps:

1 Stop & disable the service:#

1sudo systemctl stop mw-agent.service
2sudo systemctl disable mw-agent.service

2 Remove the systemd unit:#

1sudo rm /etc/systemd/system/mw-agent.service
2sudo systemctl daemon-reload

3 Remove the Docker container:#

1docker rm -f mw-agent

4 (Optional) Remove the agent image:#

1docker rmi ghcr.io/middleware-labs/mw-host-agent:master

5 Clean up Ignition/Butane configs:#

Remove the mw-agent.service snippet from your .bn/.ign files before reprovisioning.

Troubleshooting#

If metrics don’t appear after a few minutes, check for the following:

Service health:

1sudo systemctl status mw-agent.service

Agent logs:

1sudo journalctl -u mw-agent.service --no-pager
2docker logs mw-agent

Config verification: Ensure your MW_API_KEY and MW_TARGET are correctly set in the Ignition config.
Network: Confirm your node can reach https://<MW_UID>.middleware.io:443.
Further help: Get in touch with us via our Contact Us.

Need assistance or want to learn more about Middleware? Get in touch with us via our Contact Us or join our Slack channel.