fleet.yaml

The fleet.yaml file adds options to a bundle. Any directory with a fleet.yaml is automatically turned into bundle.

For more information on how to use the fleet.yaml to customize bundles see Git Repository Contents.

The content of the fleet.yaml corresponds to https://github.com/rancher/fleet/blob/main/pkg/bundlereader/read.go#L129-L135, which contains the BundleSpec.

Reference

fleet.yaml

# 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

# 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:
  # Use a custom location for the Helm chart. This can refer to any go-getter URL or
  # OCI registry based helm chart URL e.g. "oci://ghcr.io/fleetrepoci/guestbook".
  # This allows one to download charts from most any location.  Also know that
  # go-getter URL supports adding a digest to validate the download. If repo
  # is set below this field is the name of the chart to lookup
  chart: ./chart
  # A https URL to a Helm repo to download the chart from. It's typically easier
  # to just use `chart` field and refer to a tgz file.  If repo is used the
  # value of `chart` will be used as the chart name to lookup in the Helm repository.
  repo: https://charts.rancher.io
  # A custom release name to deploy the chart as. If not specified a release name
  # will be generated by combining the invoking GitRepo.name + GitRepo.path.
  releaseName: my-release
  # Makes helm skip the check for its own annotations
  takeOwnership: false
  # The version of the chart or semver constraint of the chart to find. If a constraint
  # is specified it is evaluated each time git changes.
  # The version also determines which chart to download from OCI registries.
  version: 0.1.0
  # Any values that should be placed in the `values.yaml` and passed to helm during
  # install.
  values:
    any-custom: value
  # All labels on Rancher clusters are available using global.fleet.clusterLabels.LABELNAME
  # These can now be accessed directly as variables
  # The variable's value will be an empty string if the referenced cluster label does not
  # exist on the targeted cluster
    variableName: global.fleet.clusterLabels.LABELNAME
  # It is possible to specify the keys and values as go template strings for
  # advanced templating needs. Most of the functions from the sprig templating
  # library are available. However, the `uuidv4` function is not supported.
  # The template context has following keys.
  # `.ClusterValues` are retrieved from target cluster's `spec.templateValues`
  # `.ClusterLabels` and `.ClusterAnnotations` are the labels and annoations in the cluster resource.
  # `.ClusterName` as the fleet's cluster resource name.
  # `.ClusterNamespace` as the namespace in which the cluster resource exists.
  # Note: The fleet.yaml must be valid yaml. Templating uses ${ } as delims,
  #       unlike helm which uses {{ }}.
    templatedLabel: "${ .ClusterLabels.LABELNAME }-foo"
    valueFromEnv:
      "${ .ClusterLabels.ENV }": ${ .ClusterValues.someValue | upper | quote }
  # Path to any values files that need to be passed to helm during install
  valuesFiles:
    - values1.yaml
    - values2.yaml
  # Allow to use values files from configmaps or secrets defined in the downstream clusters
  valuesFrom:
  - configMapKeyRef:
      name: configmap-values
      # default to namespace of bundle
      namespace: default 
      key: values.yaml
  - secretKeyRef:
      name: secret-values
      namespace: default
      key: values.yaml
  # Override immutable resources. This could be dangerous.
  force: false
  # Set the Helm --atomic flag when upgrading
  atomic: false
  # Disable go template pre-processing on the fleet values
  disablePreProcess: false
  # if set and timeoutSeconds provided, will wait until all Jobs have been completed before marking the GitRepo as ready.
  # It will wait for as long as timeoutSeconds
  waitForJobs: true
  
# A paused bundle will not update downstream clusters but instead mark the bundle
# as OutOfSync. One can then manually confirm that a bundle should be deployed to
# the downstream clusters.
# Default: false
paused: false

rolloutStrategy:
    # A number or percentage of clusters that can be unavailable during an update
    # of a bundle. This follows the same basic approach as a deployment rollout
    # strategy. Once the number of clusters meets unavailable state update will be
    # paused. Default value is 100% which doesn't take effect on update.
    # default: 100%
    maxUnavailable: 15%
    # A number or percentage of cluster partitions that can be unavailable during
    # an update of a bundle.
    # default: 0
    maxUnavailablePartitions: 20%
    # A number of percentage of how to automatically partition clusters if not
    # specific partitioning strategy is configured.
    # default: 25%
    autoPartitionSize: 10%
    # A list of definitions of partitions.  If any target clusters do not match
    # the configuration they are added to partitions at the end following the
    # autoPartitionSize.
    partitions:
      # A user friend name given to the partition used for Display (optional).
      # default: ""
    - name: canary
      # A number or percentage of clusters that can be unavailable in this
      # partition before this partition is treated as done.
      # default: 10%
      maxUnavailable: 10%
      # Selector matching cluster labels to include in this partition
      clusterSelector:
        matchLabels:
          env: prod
      # A cluster group name to include in this partition
      clusterGroup: agroup
      # Selector matching cluster group labels to include in this partition
      clusterGroupSelector: 
        clusterSelector:
          matchLabels:
            env: prod

# Target customization are used to determine how resources should be modified per target
# Targets are evaluated in order and the first one to match a cluster is used for that cluster.
targetCustomizations:
# The name of target. If not specified a default name of the format "target000"
# will be used. This value is mostly for display
- name: prod
  # Custom namespace value overriding the value at the root
  namespace: newvalue
  # Custom defaultNamespace value overriding the value at the root
  defaultNamespace: newdefaultvalue
  # Custom kustomize options overriding the options at the root
  kustomize: {}
  # Custom Helm options override the options at the root
  helm: {}
  # If using raw YAML these are names that map to overlays/{name} that will be used
  # to replace or patch a resource. If you wish to customize the file ./subdir/resource.yaml
  # then a file ./overlays/myoverlay/subdir/resource.yaml will replace the base file.
  # A file named ./overlays/myoverlay/subdir/resource_patch.yaml will patch the base file.
  # A patch can in JSON Patch or JSON Merge format or a strategic merge patch for builtin
  # Kubernetes types. Refer to "Raw YAML Resource Customization" below for more information.
  yaml:
    overlays:
    - custom2
    - custom3
  # 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 a specific cluster by name.    
  clusterName: dev-cluster    
  # A selector used to match cluster groups.
  clusterGroupSelector:
    matchLabels:
      region: us-east
  # A specific clusterGroup by name that will be selected
  clusterGroup: group1

# dependsOn allows you to configure dependencies to other bundles. The current bundle
# will only be deployed, after all dependencies are deployed and in a Ready state.
dependsOn:
  # Format: <GITREPO-NAME>-<BUNDLE_PATH> with all path separators replaced by "-"
  # Example: GitRepo name "one", Bundle path "/multi-cluster/hello-world" => "one-multi-cluster-hello-world"
  - name: one-multi-cluster-hello-world
  # Select bundles to depend on based on their label.
  - selector:
      matchLabels:
        app: weak-monkey