Flatcar Container Linux is a minimal, container-optimized Linux distribution designed for running containerized workloads at scale.
Flatcar Container Linux is:
Flatcar is supported on the following cloud providers:
Flatcar is not supported on: DigitalOcean, Hetzner Cloud, Nutanix
To use Flatcar as the operating system:
spec:
template:
spec:
providerSpec:
value:
operatingSystem: "flatcar"
operatingSystemSpec:
# Flatcar-specific configuration
disableAutoUpdate: false
operatingSystemSpec:
# Disable automatic updates (not recommended for Flatcar)
disableAutoUpdate: false
# Provision using Ignition instead of cloud-init
provisioningUtility: "ignition"
Flatcar uses Ignition as its primary provisioning mechanism. Machine-controller generates Ignition configuration that:
Some providers may also support cloud-init for Flatcar, but Ignition is the recommended method.
Flatcar provides three release channels:
Specify the channel in your cloud provider configuration.
AWS provides Flatcar AMIs in the marketplace:
cloudProviderSpec:
# Let machine-controller select the appropriate Flatcar AMI
# Or specify a custom AMI
ami: "ami-xxxxx" # Flatcar Stable AMI for your region
region: "us-east-1"
instanceType: "t3.medium"
To find Flatcar AMIs:
aws ec2 describe-images \
--owners 075585003325 \
--filters "Name=name,Values=Flatcar-stable-*" \
--query 'Images[*].[ImageId,Name,CreationDate]' \
--output table
Azure provides Flatcar images:
cloudProviderSpec:
imageReference:
publisher: "kinvolk"
offer: "flatcar-container-linux"
sku: "stable"
version: "latest"
Google Cloud Platform provides Flatcar images:
cloudProviderSpec:
# Use Flatcar stable image
customImage: "projects/kinvolk-public/global/images/family/flatcar-stable"
For OpenStack, you need to upload a Flatcar image:
openstack image create \
--disk-format qcow2 \
--container-format bare \
--file flatcar_production_openstack_image.img \
flatcar-stable
cloudProviderSpec:
image: "flatcar-stable"
For vSphere, import the Flatcar OVA:
cloudProviderSpec:
templateVMName: "flatcar-stable-template"
Flatcar has built-in automatic updates via the update_engine:
# Check update status
update_engine_client -status
# Trigger update check
update_engine_client -check_for_update
# View update history
journalctl -u update-engine
Flatcar updates are:
To control updates, configure the update strategy:
operatingSystemSpec:
# Disable automatic updates
disableAutoUpdate: true
If auto-reboot is disabled, manually reboot nodes after updates:
# Check if reboot is needed
update_engine_client -status | grep NEED_REBOOT
# Cordon and drain node
kubectl cordon <node-name>
kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data
# Reboot the node
sudo reboot
# Uncordon after reboot
kubectl uncordon <node-name>
Flatcar comes with Docker pre-installed, but containerd is recommended for Kubernetes:
Machine-controller automatically configures containerd on Flatcar nodes.
# Check containerd status
systemctl status containerd
# List running containers
crictl ps
# Check containerd configuration
cat /etc/containerd/config.toml
If provisioning fails, check Ignition logs:
# View Ignition journal
journalctl -u ignition
# Check Ignition files applied
ls -la /etc/
# View kubelet status
systemctl status kubelet
journalctl -u kubelet -f
Access the Flatcar instance via cloud provider console:
# Check if Ignition ran successfully
journalctl -u ignition-firstboot
# View system logs
journalctl -xe
# Check network configuration
networkctl status
Enable SSH for debugging:
cloudProviderSpec:
# Add SSH key for access
sshPublicKeys:
- "ssh-rsa AAAAB3NzaC1yc2E..."
Then SSH as the core user:
ssh core@<instance-ip>
For advanced use cases, you can provide custom Ignition configuration:
spec:
template:
spec:
providerSpec:
value:
operatingSystem: "flatcar"
operatingSystemSpec:
provisioningUtility: "ignition"
# Custom Ignition config (in addition to machine-controller defaults)
cloudInit: |
{
"ignition": {
"version": "3.0.0"
},
"storage": {
"files": [{
"path": "/etc/custom-config",
"contents": {
"source": "data:,custom%20content"
}
}]
}
}
core, not ubuntu or adminTo migrate from Ubuntu to Flatcar:
Example:
# Create new Flatcar MachineDeployment
kubectl apply -f flatcar-workers.yaml
# Scale up
kubectl scale machinedeployment flatcar-workers --replicas=3 -n kube-system
# Wait for nodes
kubectl get nodes -w
# Drain Ubuntu nodes
kubectl drain -l os=ubuntu --ignore-daemonsets --delete-emptydir-data
# Scale down Ubuntu deployment
kubectl scale machinedeployment ubuntu-workers --replicas=0 -n kube-system
apiVersion: cluster.k8s.io/v1alpha1
kind: MachineDeployment
metadata:
name: flatcar-workers
namespace: kube-system
spec:
replicas: 3
selector:
matchLabels:
name: flatcar-workers
template:
metadata:
labels:
name: flatcar-workers
spec:
providerSpec:
value:
cloudProvider: "aws"
cloudProviderSpec:
region: "us-east-1"
availabilityZone: "us-east-1a"
instanceType: "t3.medium"
vpcId: "vpc-xxxxx"
subnetId: "subnet-xxxxx"
# Flatcar Stable AMI
ami: "ami-xxxxx"
diskSize: 50
tags:
KubernetesCluster: "my-cluster"
operatingSystem: "flatcar"
operatingSystemSpec:
disableAutoUpdate: false
provisioningUtility: "ignition"
versions:
kubelet: "<YOUR-KUBERNETES-VERSION>"