Decision summary

Copy link

The following table summarizes how each factor influences the choice between a single fleet and multiple fleets.

When a single fleet works well

Copy link

A single fleet definition with layered configuration is the simplest approach when devices share more configuration than they differ. The following factors favor consolidating devices into one fleet:

• Configuration differences are limited to a small number of dimensions, such as region, site, device type, or deployment stage, that you can express as device labels.
• You want a unified rollout so that one template update reaches all devices through a single rollout policy.
• Template placeholders, getOrDefault, and conditional expressions (if, else, with) cover all per-device variation.

When these conditions hold, a single fleet keeps configuration in one place and reduces the risk of drift between groups of devices.

When multiple fleets are appropriate

Copy link

Separate fleet definitions provide stronger boundaries between groups of devices. The following factors favor splitting devices across multiple fleets:

• Groups of devices run fundamentally different operating system images, such as different Red Hat Enterprise Linux major versions or different base images for different hardware platforms.
• Different teams own different sets of devices and need independent control over template changes and rollout timing.
• Groups of devices require different rollout cadences. For example, factory controllers might update weekly while retail terminals update monthly.
• Regulatory or compliance requirements mandate separation between device populations. Separate fleets provide an auditable boundary that a label-based distinction within a single fleet does not.

Each additional fleet definition adds maintenance overhead because shared configuration must be kept in sync across fleet resources. Weigh the benefit of isolation against the cost of duplication before creating separate fleets.

Namespace separation versus fleet separation

Copy link

Fleets and namespaces address different levels of separation. A fleet controls which devices share the same desired configuration and rollout policy. A namespace (or OpenShift project) controls access boundaries — which teams or service accounts can view and manage resources.

Use separate namespaces when different teams need independent access control over their fleets, secrets, and repositories. Use separate fleets within the same namespace when devices need different configuration or rollout cadences but the same team manages them. Combine both when teams manage distinct device populations that also require independent configuration — for example, one namespace per region with multiple fleets per device role within each namespace.

Canary rollout strategies

Copy link

You can implement canary rollouts within a single fleet or across separate fleets. Each approach has different trade-offs for isolation and configuration management.

Within a single fleet

Use rolloutPolicy with deviceSelection and a BatchSequence strategy to target canary devices first. Label a subset of devices with a canary label, for example stage: canary, and define the first batch with a selector that matches that label. Set a successThreshold, such as "80%", so the rollout pauses if too many canary devices fail. This approach keeps all configuration in one fleet definition and avoids duplication.

With separate fleets

Create a canary fleet with a narrow label selector, such as stage: canary, and a production fleet with the broader selector. Apply configuration changes to the canary fleet first. After you validate the changes on canary devices, apply the same changes to the production fleet. This approach provides stronger isolation because a failed canary rollout cannot affect production devices. It also lets you test changes independently without rolling them out to production, and separates canary device status from production device status. However, it duplicates configuration across two fleet definitions.

Rollout policy scope

Copy link

The rollout policy applies to the entire fleet template spec. When any configuration entry changes, or when the system detects an upstream change in a Git repository or HTTP endpoint referenced by the fleet, the rollout covers all devices in the fleet.

You cannot roll out changes to one configuration concern independently of another concern within the same fleet. For example, if both network settings and application configuration are defined in the same fleet’s template spec, a change to network settings triggers a rollout that updates the desired state for all devices, including the unchanged application configuration.

If independent rollout cadences per concern are required, separate those concerns into different fleets. Each fleet then has its own rollout policy and its own rollout lifecycle.