dfmicro - Run MicroShift clusters in rootful Podman containers
dfmicro
dfmicro creates and manages single-node MicroShift clusters inside rootful Podman containers. Each cluster gets its own Podman network and a loop-device backed LVM thin pool for TopoLVM storage.
Verified on: Linux (Fedora / RHEL) Best-effort support: macOS (requires rootful Podman machine via 'podman machine init --rootful')
Quick start: dfmicro ops sudoers create # one-time: passwordless sudo for cluster tools dfmicro cluster create # create cluster with default name dfmicro cluster kubeconfig > ~/.kube/config # overwrites kubeconfig! kubectl get nodes dfmicro cluster delete # tear everything down
Usage:
dfmicro [GLOBAL OPTIONS] [command [COMMAND OPTIONS]] [ARGUMENTS...]
Manage cluster addons
--list: List available addons
Manage OpenShift Data Foundation on a MicroShift cluster
Manage ODF lifecycle on MicroShift. Verified on Linux, not tested on macOS.
Note: --name and --kubeconfig apply to all subcommands and must come before the subcommand name.
--kubeconfig="": Path to an existing kubeconfig file
--kubectl: Use kubectl instead of oc for cluster operations
--name="": Cluster name to resolve kubeconfig from (default: "micro")
Configure ODF to run on MicroShift
Run after 'install' once the operator CSV reaches Succeeded. Applies without retries and fails fast on any error.
--client: Client-only mode
--include-cephfs: Run CephFS and CSI Driver
--multi-node: Configure ODF for a multi-node cluster
Install ODF and required shim resources
Requires rbd, ceph, nbd kernel modules loaded on the host. Run 'dfmicro addon odf modules load' first.
Example:
dfmicro addon odf install --catalog-image quay.io/example/catalog:v4.16 --channel stable-4.16 --version 4.16.0
--catalog-image="": Catalog source image
--channel="": Subscription channel (e.g. stable-4.16)
--shims: Apply only the shim CRDs
--sub-name="": Subscription name (repeatable) (default: "odf-operator")
--version="": OCP version in X.Y.Z format (e.g. 4.16.0)
Manage ODF kernel module auto-load configuration
Load rbd, ceph, nbd kernel modules and configure auto-load at boot
Unload rbd, ceph, nbd kernel modules and remove auto-load config
Uninstall ODF and all associated resources
Prints the cleanup commands by default. Pass --attempt to execute them (best-effort).
Examples:
dfmicro addon odf uninstall # dry-run: print commands
dfmicro addon odf uninstall --attempt # execute cleanup
--attempt: Execute the delete commands instead of printing them (best-effort)
Manage cluster lifecycle
Manage MicroShift cluster lifecycle in rootful Podman containers.
Print saved cluster config as JSON
Config is recorded at creation time and reflects the flags used.
--name="": Cluster name (default: "micro")
Create a cluster, wait until ready, and print connection info
Mounts flags are immutable after creation. Delete and recreate to change them.
Examples:
dfmicro cluster create
dfmicro cluster create --name dev
dfmicro cluster create --name odf --lvm-volsize 50G --pull-secret ~/pull-secret.json
dfmicro cluster create --idms ~/idms-1.yaml --idms ~/idms-2.yaml
--api-server-port="": Host port to expose the Kubernetes API server on (1024-65535) (default: 6443)
--bridge-subnet="": Network subnet in CIDR notation (default: "172.20.0.0/24")
--cluster-cidr="": Pod CIDR for the cluster (default: "10.42.0.0/16")
--etcd: Use etcd storage backend (default: SQLite)
--idms="": Path to an ImageDigestMirrorSet YAML file for mirror registries (repeatable, merged in order)
--image="": MicroShift container image to run (OKD / SCOS build) (default: "ghcr.io/leelavg/microshift:5.0.0_202609201132_g4582bf673_5.0.0_okd_scos.ec.8")
--lvm-volsize="": Size of the sparse loop-device image backing the LVM thin pool for TopoLVM (e.g. 10G, 50G) (default: "10G")
--mount="": Extra bind mount in Podman format: /host/path:/container/path[:opts] (repeatable)
--name="": Cluster name, used to identify containers and stored config (default: "micro")
--no-expose-kubeapi: Do not bind the API server port on the host (cluster-internal access only)
--no-power-tuning: Do not apply MicroShift power tuning on create
--no-share-host-containers: Do not bind-mount /var/lib/containers from the host (use if the shared containers store gets corrupted)
--no-thinpool: Skip thin pool creation and configuration for TopoLVM storage
--no-topolvm: Disable TopoLVM storage provisioner (all other topolvm flags are disregarded)
--overprovision-ratio="": TopoLVM thin pool overprovision ratio (default: 20)
--pull-secret="": Path to a pull secret JSON file for accessing private image registries
--service-cidr="": Service CIDR for the cluster (default: "10.43.0.0/16")
Delete cluster containers, network, and storage
Stops and removes all cluster containers, networking, and storage stack.
--name="": Cluster name (default: "micro")
Open an interactive shell inside the cluster container
Useful for running crictl, oc, or kubectl directly against the node.
--container="": Container name (defaults to first running container for the cluster)
--name="": Cluster name (default: "micro")
Print kubeconfig for a cluster
Pipe to a file or merge into an existing kubeconfig:
dfmicro cluster kubeconfig > ~/.kube/config
dfmicro cluster kubeconfig | KUBECONFIG=~/.kube/config:- kubectl config view --merge --flatten > merged.yaml
--name="": Cluster name (default: "micro")
List all clusters
Start a stopped cluster
Use after 'cluster stop' or after a host reboot.
--name="": Cluster name (default: "micro")
Stop cluster containers without removing them
Preserves all state. Resume with 'cluster start'.
--name="": Cluster name (default: "micro")
Print the embedded default configuration as JSON
Shows the compiled-in defaults for cluster name, image, network subnet, LVM size, and more.
These are the values used when flags are omitted on any command.
Print full command reference as markdown
dfmicro docs > cli.md
--examples: Print command examples
Manage multi-cluster networks
Attach clusters to a network
Attach one or more clusters to a bridge network.
Example:
dfmicro network attach --cluster first:gp1 --cluster second:gp2 --cluster third:gp1/gp2 --to backbone
--cluster="": Cluster name with optional groups (name[:group1[/group2,...]]). Without group, cluster joins 'default'
--namespace="": Namespace for NAD creation (default: "default")
--to="": Network name to attach to
Show bridge and IPAM configuration
Show bridge and IPAM state for a network.
Example:
dfmicro network config --name backbone
--name="": Network name
Connect clusters to a bridge network
Connect one or more clusters to a bridge network.
Example:
dfmicro network connect --cluster first --cluster second --to backbone
--cluster="": Cluster name (repeatable)
--to="": Network name to connect to
Create a bridge network for multi-cluster interconnect
Create a bridge network that clusters can attach to.
Example:
dfmicro network create --name backbone --group-count 5 --subnet 172.30.0.0/16
--cluster-count="": Number of clusters per IPAM group (default: 5)
--group-count="": Number of IPAM groups for the subnet (1-253) (default: 5)
--name="": Network name
--reserve-count="": Number of IPs to reserve per group (max 253) (default: 5)
--subnet="": Network subnet in CIDR notation (minimum /16)
Delete a bridge network
Delete a bridge network.
Example:
dfmicro network delete --name backbone
--name="": Network name
Detach clusters from a network
Detach one or more clusters from a bridge network.
Example:
dfmicro network detach --cluster first:gp1 --cluster second:gp2 --from backbone
--cluster="": Cluster name with optional groups (name[:group1[,group2,...]]). Without group, detaches from 'default'
--from="": Network name to detach from
--namespace="": Namespace of the NAD to delete (default: "default")
Disconnect clusters from a bridge network
Disconnect one or more clusters from a bridge network.
Example:
dfmicro network disconnect --cluster first --cluster second --from backbone
--cluster="": Cluster name (repeatable)
--from="": Network name to disconnect from
Establish direct peering between clusters
Establish direct peering between clusters.
Example:
dfmicro network peer --cluster first --cluster second
--cluster="": Cluster name (repeatable, at least 2 required)
Remove direct peering between clusters
Remove direct peering between clusters.
Example:
dfmicro network unpeer --cluster first --cluster second
--cluster="": Cluster name (repeatable, at least 2 required)
Manage cluster nodes
Add worker nodes to existing cluster.
add worker node to existing cluster
--cluster="": cluster name (default: "micro")
--force: skip control plane readiness checks
--mount="": Extra bind mount in Podman format: /host/path:/container/path[:opts] (repeatable)
Print cluster node configuration
--cluster="": cluster name (default: "micro")
remove worker node from cluster
--cluster="": cluster name (default: "micro")
--name="": worker node name
Operational utilities for running clusters
Show CPU and memory requests, limits, and live usage per container (experimental)
Experimental: output format and flags may change. Use --namespace to scope and improve performance.
Examples:
dfmicro ops resources
dfmicro ops resources --namespace openshift-operator-lifecycle-manager
dfmicro ops resources --name dev --node microshift-node-1
--name="": Cluster name (default: "micro")
--namespace="": Restrict output to a single namespace (omit for all namespaces)
--node="": Restrict output to a single node by name (omit for all nodes)
Show storage paths for all dfmicro clusters
Manage passwordless sudo configuration for dfmicro (Linux only)
Writes /etc/sudoers.d/dfmicro with the commands used by dfmicro requiring elevated access.
No-op on macOS: rootful Podman machine runs as root so no sudoers entry is needed.
Warning: these rules allow any process running as your user to invoke the listed binaries without a password prompt. Intended for developer workstations, not shared hosts.
Write /etc/sudoers.d/dfmicro for the current user
Remove /etc/sudoers.d/dfmicro
Removes the sudoers file created by 'sudoers create'. On macOS this is a no-op.