fleet.yaml
The fleet.yaml file adds options to a bundle. Any directory with a fleet.yaml file is automatically turned into a bundle.
For more information about customizing bundles using fleet.yaml, see Git Repository Contents.
The contents of fleet.yaml correspond to the FleetYAML struct in
fleetyaml.go, which contains the BundleSpec.
== Full Example
Details
# The default namespace to be applied to resources. This field is not used to
# enforce or lock down the deployment to a specific namespace, but instead
# provide the default value of the namespace field if one is not specified in
# the manifests.
#
# Default: default
defaultNamespace: default
# All resources will be assigned to this namespace and if any cluster scoped
# resource exists the deployment will fail.
#
# Default: ""
namespace: default
# namespaceLabels are labels that will be appended to the namespace created by
# Fleet.
namespaceLabels:
  key: value
# namespaceAnnotations are annotations that will be appended to the namespace
# created by Fleet.
namespaceAnnotations:
  key: value
# Optional map of labels, that are set at the bundle and can be used in a
# dependsOn.selector
labels:
  key: value
kustomize:
  # Use a custom folder for kustomize resources. This folder must contain a
  # kustomization.yaml file.
  dir: ./kustomize
helm:
  chart: ./chart
  repo: https://charts.rancher.io
  version: 0.1.0
  disableDependencyUpdate: false
  values:
    any-custom: value
    variableName: global.fleet.clusterLabels.LABELNAME
    templatedLabel: "${ .ClusterLabels.LABELNAME }-foo"
    valueFromEnv:
      "${ .ClusterLabels.ENV }": ${ .ClusterValues.someValue | upper | quote }
  valuesFiles:
    - values1.yaml
    - values2.yaml
  valuesFrom:
    - configMapKeyRef:
        name: configmap-values
        namespace: default
        key: values.yaml
    - secretKeyRef:
        name: secret-values
        namespace: default
        key: values.yaml
  releaseName: my-release
  takeOwnership: false
  force: false
  atomic: false
  disablePreProcess: false
  disableDNS: false
  skipSchemaValidation: false
  waitForJobs: true
paused: false
rolloutStrategy:
  maxUnavailable: 15%
  maxUnavailablePartitions: 20%
  autoPartitionSize: 10%
  partitions:
    - name: canary
      maxUnavailable: 10%
      clusterSelector:
        matchLabels:
          env: prod
      clusterGroup: agroup
      clusterGroupSelector:
        clusterSelector:
          matchLabels:
            env: prod
targetCustomizations:
  - name: prod
    namespace: newvalue
    defaultNamespace: newdefaultvalue
    kustomize: {}
    helm: {}
    yaml:
      overlays:
        - custom2
        - custom3
    clusterSelector:
      matchLabels:
        env: prod
    clusterName: dev-cluster
    clusterGroupSelector:
      matchLabels:
        region: us-east
    clusterGroup: group1
    doNotDeploy: false
    correctDrift:
      enabled: false
      force: false
      keepFailHistory: false
dependsOn:
  - name: one-multi-cluster-hello-world
  - selector:
      matchLabels:
        app: weak-monkey
ignore:
  conditions:
    - type: Active
      status: "False"
overrideTargets:
  - clusterSelector:
      matchLabels:
        env: dev
General Bundle Configuration
These options define the fundamental properties and behavior of the bundle itself and apply to all bundle types.
| Option | Description | Applies to | 
|---|---|---|
  | 
If true, the bundle will not be updated on downstream clusters. Instead, it will be marked as OutOfSync. You can then manually approve the deployment.  | 
All  | 
  | 
A map of key-value pairs set at the bundle level. These can be used in a   | 
All  | 
  | 
A list of bundles that this bundle depends on. The current bundle is deployed only after all dependencies are in a Ready state.  | 
All  | 
  | 
Specifies fields to ignore when monitoring bundle status. Useful for preventing false error states from Custom Resources.  | 
All  | 
  | 
A list of target customizations that override any targets defined in the GitRepo.  | 
All  | 
Namespace Configuration
These options control the Kubernetes namespace where resources will be deployed.
| Option | Description | Applies to | 
|---|---|---|
  | 
Default namespace for resources that don’t specify one.  | 
All  | 
  | 
Assigns all resources in the bundle to this namespace. Fails if any cluster-scoped resources exist.  | 
All  | 
  | 
Labels to be added to the namespace created by Fleet.  | 
All  | 
  | 
Annotations to be added to the namespace created by Fleet.  | 
All  | 
Helm Bundle Configuration
All bundles are deployed using Helm, but these options are specific to Helm-style bundles (those with a Chart.yaml file).
Chart Source
These options specify how to download the chart. The reference can be a local path, go-getter URL, Helm repo, or OCI Helm repo.
| Option | Description | Applies to | 
|---|---|---|
  | 
The Helm chart location (local path, go-getter URL, or OCI registry).  | 
Helm  | 
  | 
URL of a Helm repository.  | 
Helm  | 
  | 
Chart version or semver constraint. Re-evaluated on every git change.  | 
Helm  | 
  | 
If true, disables automatic dependency downloads.  | 
Helm  | 
The chart reference can be one of the following:
- 
Local path (
chart) - 
OCI chart URL (
oci://…) - 
Helm repository (
repo+version) - 
OCI Helm repository (
repo+version) 
helm.chart
Specifies a custom location for the Helm chart. For example:
oci://ghcr.io/fleetrepoci/guestbook.
If a secret for the SSH key was defined via helmSecretName, it is injected automatically.
| 
 If the   | 
| 
 Limitation: Downloading Helm charts from Git with custom CA bundles does not work.
If a CA bundle is configured in a secret referenced in   | 
Values
Options for customizing Helm chart values.
| Option | Description | Applies to | 
|---|---|---|
  | 
Key-value pairs passed to Helm as custom values. Supports templating.  | 
Helm  | 
  | 
Paths to values files passed to Helm.  | 
Helm  | 
  | 
Load values from ConfigMaps or Secrets in downstream clusters.  | 
Helm  | 
It is not necessary to specify a chart’s own values.yaml. It is always used by default.
See Using Helm Values for more information.
For value processing stages, refer to https://fleet.rancher.io/ref-bundle-stages.
Values Templating
Fleet supports Go template expressions for advanced templating needs. See the Sprig template functions for available functions.
| 
 Avoid functions that produce random output (for example,   | 
You can test values templating with the CLI. For more information, refer to fleet-target.
Template context keys:
- 
.ClusterValues - 
.ClusterLabels - 
.ClusterAnnotations - 
.ClusterName - 
.ClusterNamespace 
Example:
${ get .ClusterLabels "management.cattle.io/cluster-display-name" }
Fleet templating uses ${ } delimiters (not Helm’s {{ }}). Escape them using backticks:
foo-bar-${`${PWD}`}
Outputs:
foo-bar-${PWD}
| 
 When using templating, guard against null values. Example: 
 | 
Helm Deployment
These options control how Fleet’s agent deploys resources. They also apply to kustomize- and manifest-style bundles.
| Option | Description | Applies to | 
|---|---|---|
  | 
Custom release name. Defaults to a generated name.  | 
All  | 
  | 
Skip annotation checks.  | 
All  | 
  | 
Override immutable resources.  | 
All  | 
  | 
Use Helm   | 
All  | 
  | 
Wait for all Jobs before marking GitRepo as ready.  | 
All  | 
  | 
Disable Go template preprocessing.  | 
All  | 
  | 
Disable DNS resolution in templates.  | 
All  | 
  | 
Skip   | 
All  | 
Kustomize Configuration
Used when deploying from a directory containing a kustomization.yaml file.
Option  | 
Description  | 
Applies to  | 
  | 
Custom folder for Kustomize resources. Must contain a   | 
Kustomize  | 
Deployment Strategy (Rollout)
These options control how updates roll out across clusters.
| Option | Description | Applies to | 
|---|---|---|
  | 
Maximum unavailable clusters during update.  | 
All  | 
  | 
Maximum unavailable partitions during update.  | 
All  | 
  | 
Auto partition size for clusters.  | 
All  | 
  | 
Defines cluster partitions for phased rollouts.  | 
All  | 
For more information, see Rollout Strategies.
Targeting and Customization
These options let you customize deployments for specific clusters or cluster groups.
| Option | Description | Applies to | 
|---|---|---|
  | 
List of rules for modifying resources per target.  | 
All  | 
  | 
Display name for customization.  | 
All  | 
  | 
Kubernetes label selector for clusters.  | 
All  | 
  | 
Cluster group name to target.  | 
All  | 
  | 
Label selector for cluster groups.  | 
All  | 
  | 
Specific cluster name to target.  | 
All  | 
  | 
Prevents deployment to matched clusters.  | 
All  | 
  | 
Overrides root-level namespace.  | 
All  | 
  | 
Overrides root-level default namespace.  | 
All  | 
  | 
Overrides root-level Helm configuration.  | 
All  | 
  | 
Overrides root-level Kustomize configuration.  | 
Kustomize  | 
  | 
Overlay names to replace or patch YAML resources.  | 
Raw YAML  | 
  | 
Enables drift correction for managed resources.  | 
All  | 
Supported Customizations
| 
 Overriding Helm chart versions in target customizations can increase bundle sizes. Because Fleet stores bundles in etcd, this may exceed etcd’s blob size limit. Refer to fleet#1650 for details.  |