This is unreleased documentation for Fleet Next.

Mapping to Downstream Clusters

Fleet in Rancher allows users to manage clusters easily as if they were one cluster. Users can deploy bundles, which can be comprised of deployment manifests or any other Kubernetes resource, across clusters using grouping configuration.

Multi-cluster Only: This approach only applies if you are running Fleet in a multi-cluster style If no targets are specified, i.e. when using a single-cluster, the bundles target the default cluster group.

When deploying GitRepos to downstream clusters the clusters must be mapped to a target.

Defining Targets

The deployment targets of GitRepo is done using the spec.targets field to match clusters or cluster groups. The YAML specification is as below.

kind: GitRepo
apiVersion: fleet.cattle.io/v1alpha1
metadata:
  name: myrepo
  namespace: clusters
spec:
  repo: https://github.com/rancher/fleet-examples
  paths:
  - simple

  # Targets are evaluated in order and the first one to match is used. If
  # no targets match then the evaluated cluster will not be deployed to.
  targets:
  # The name of target. This value is largely for display and logging.
  # If not specified a default name of the format "target000" will be used
  - name: prod
    # A selector used to match clusters. The structure is the standard
    # metav1.LabelSelector format. If clusterGroupSelector or clusterGroup is specified,
    # clusterSelector will be used only to further refine the selection after
    # clusterGroupSelector and clusterGroup is evaluated.
    clusterSelector:
      matchLabels:
        env: prod
    # A selector used to match cluster groups.
    clusterGroupSelector:
      matchLabels:
        region: us-east
    # A specific clusterGroup by name that will be selected
    clusterGroup: group1
    # A specific cluster by name that will be selected
    clusterName: cluster1

Target Matching

All clusters and cluster groups in the same namespace as the GitRepo will be evaluated against all targets. If any of the targets match the cluster then the GitRepo will be deployed to the downstream cluster. If no match is made, then the GitRepo will not be deployed to that cluster.

There are four approaches to matching clusters. One can use cluster selectors, cluster group selectors, an explicit cluster group name, or a cluster name. All criteria is additive so the final match is evaluated as "clusterName && clusterSelector && clusterGroupSelector && clusterGroup". If any of the four have the default value it is dropped from the criteria. The default value is either null or "". It is important to realize that the value {} for a selector means "match everything."

When multiple target entries are specified, they are evaluated in order and act as alternatives: if a cluster matches the first entry, subsequent entries are not evaluated. This means that entries behave like an OR list, while the fields within each entry are still AND’d together.

targets:
  # Match everything
  - clusterSelector: {}
  # Selector ignored
  - clusterSelector: null

You can also match clusters by name:

targets:
  - clusterName: fleetname

When using Fleet in Rancher, make sure to put the name of the clusters.fleet.cattle.io resource.

Default Target

If no target is set for the GitRepo then the default targets value is applied. The default targets value is as below.

targets:
- name: default
  clusterGroup: default

This means if you wish to setup a default location non-configured GitRepos will go to, then just create a cluster group called default and add clusters to it.

Customization per Cluster

The targets: in the GitRepo resource select clusters to deploy on. The targetCustomizations: in fleet.yaml override Helm values and other settings but do not change which clusters are targeted.

Target customizations allow you to modify bundle deployments for specific clusters without maintaining separate bundles. You can customize Helm values, namespaces, overlays, and deployment options based on cluster labels or names.

Fleet supports two modes for applying customizations:

FirstMatch (default): Applies only the first matching customization
AllMatches: Applies all matching customizations in order, merging them

For a comprehensive guide including merge behavior and advanced patterns, see Target Customization.

Example: FirstMatch Mode (Environment-Specific Configuration)

This example demonstrates the default FirstMatch behavior, where only the first matching customization is applied. We will use multi-cluster/helm/fleet.yaml.

Situation: User has three clusters with three different labels: env=dev, env=test, and env=prod. User wants to deploy a frontend application with a backend database across these clusters.

Expected behavior:

After deploying to the dev cluster, database replication is not enabled.
After deploying to the test cluster, database replication is enabled.
After deploying to the prod cluster, database replication is enabled and Load balancer services are exposed.

Advantage of Fleet:

Instead of deploying the app on each cluster, Fleet allows you to deploy across all clusters following these steps:

Deploy gitRepo https://github.com/rancher/fleet-examples.git and specify the path multi-cluster/helm.
Under multi-cluster/helm, a Helm chart will deploy the frontend app service and backend database service.
The following rule will be defined in fleet.yaml:

targetCustomizations:
- name: dev
  helm:
    values:
      replication: false
  clusterSelector:
    matchLabels:
      env: dev

- name: test
  helm:
    values:
      replicas: 3
  clusterSelector:
    matchLabels:
      env: test

- name: prod
  helm:
    values:
      serviceType: LoadBalancer
      replicas: 3
  clusterSelector:
    matchLabels:
      env: prod

Result:

Fleet will deploy the Helm chart with your customized values.yaml to the different clusters.

Configuration management is not limited to deployments but can be expanded to general configuration management. Fleet is able to apply configuration management through customization among any set of clusters automatically.

Example: AllMatches Mode (Layered Customizations)

When customizations represent independent concerns that should be combined, use AllMatches mode. This example shows how to layer environment-specific configuration with optional user overrides.

Situation: You need to deploy an application where:

Edge clusters require specific values
Some clusters need user-provided ConfigMap overrides
Clusters may have both requirements

Configuration:

targetCustomizationMode: AllMatches

helm:
  chart: ./chart
  values:
    # Base configuration
    app:
      name: myapp
      replicas: 1

targetCustomizations:
  - name: edge-config
    clusterSelector:
      matchLabels:
        edge: "true"
    helm:
      valuesFiles:
        - values/edge.yaml

  - name: configmap-override
    clusterSelector:
      matchLabels:
        custom-values: "true"
    helm:
      valuesFrom:
        - configMapKeyRef:
            name: custom-values
            key: values.yaml
            namespace: default

Result:

Cluster with edge: "true" only: Gets values from values/edge.yaml
Cluster with custom-values: "true" only: Gets values from ConfigMap
Cluster with both labels: Gets both values/edge.yaml AND ConfigMap values merged together

This avoids the need to create separate customizations for every label combination.

For more examples and detailed merge behavior, see Common Patterns.

Limitations

For information about limitations when overriding Helm chart settings, bundle size considerations, and workarounds, see Limitations and Considerations.

Additional Examples

Examples using raw Kubernetes YAML, Helm charts, Kustomize, and combinations of the three are in the Fleet Examples repo.