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/master/pkg/bundlereader/read.go#L129-L135, which contains the BundleSpec.

Reference

fleet.yaml

  1. # The default namespace to be applied to resources. This field is not used to
  2. # enforce or lock down the deployment to a specific namespace, but instead
  3. # provide the default value of the namespace field if one is not specified
  4. # in the manifests.
  5. # Default: default
  6. defaultNamespace: default
  8. # All resources will be assigned to this namespace and if any cluster scoped
  9. # resource exists the deployment will fail.
  10. # Default: ""
  11. namespace: default
  13. # Optional map of labels, that are set at the bundle and can be used in a 
  14. # dependsOn.selector
  15. labels:
  16.   key: value
  18. kustomize:
  19.   # Use a custom folder for kustomize resources. This folder must contain
  20.   # a kustomization.yaml file.
  21.   dir: ./kustomize
  23. helm:
  24.   # Use a custom location for the Helm chart. This can refer to any go-getter URL or
  25.   # OCI registry based helm chart URL e.g. "oci://ghcr.io/fleetrepoci/guestbook".
  26.   # This allows one to download charts from most any location.  Also know that
  27.   # go-getter URL supports adding a digest to validate the download. If repo
  28.   # is set below this field is the name of the chart to lookup
  29.   chart: ./chart
  30.   # A https URL to a Helm repo to download the chart from. It's typically easier
  31.   # to just use `chart` field and refer to a tgz file.  If repo is used the
  32.   # value of `chart` will be used as the chart name to lookup in the Helm repository.
  33.   repo: https://charts.rancher.io
  34.   # A custom release name to deploy the chart as. If not specified a release name
  35.   # will be generated by combining the invoking GitRepo.name + GitRepo.path.
  36.   releaseName: my-release
  37.   # Makes helm skip the check for its own annotations
  38.   takeOwnership: false
  39.   # The version of the chart or semver constraint of the chart to find. If a constraint
  40.   # is specified it is evaluated each time git changes.
  41.   # The version also determines which chart to download from OCI registries.
  42.   version: 0.1.0
  43.   # Any values that should be placed in the `values.yaml` and passed to helm during
  44.   # install.
  45.   values:
  46.     any-custom: value
  47.   # All labels on Rancher clusters are available using global.fleet.clusterLabels.LABELNAME
  48.   # These can now be accessed directly as variables
  49.   # The variable's value will be an empty string if the referenced cluster label does not
  50.   # exist on the targeted cluster
  51.     variableName: global.fleet.clusterLabels.LABELNAME
  52.   # It is possible to specify the keys and values as go template strings for
  53.   # advanced templating needs. Most of the functions from the sprig templating
  54.   # library are available. However, the `uuidv4` function is not supported.
  55.   # The template context has following keys.
  56.   # `.ClusterValues` are retrieved from target cluster's `spec.templateValues`
  57.   # `.ClusterLabels` and `.ClusterAnnotations` are the labels and annoations in the cluster resource.
  58.   # `.ClusterName` as the fleet's cluster resource name.
  59.   # `.ClusterNamespace` as the namespace in which the cluster resource exists.
  60.   # Note: The fleet.yaml must be valid yaml. Templating uses ${ } as delims,
  61.   #       unlike helm which uses {{ }}.
  62.     templatedLabel: "${ .ClusterLabels.LABELNAME }-foo"
  63.     valueFromEnv:
  64.       "${ .ClusterLabels.ENV }": ${ .ClusterValues.someValue | upper | quote }
  65.   # Path to any values files that need to be passed to helm during install
  66.   valuesFiles:
  67.     - values1.yaml
  68.     - values2.yaml
  69.   # Allow to use values files from configmaps or secrets defined in the downstream clusters
  70.   valuesFrom:
  71.   - configMapKeyRef:
  72.       name: configmap-values
  73.       # default to namespace of bundle
  74.       namespace: default 
  75.       key: values.yaml
  76.   - secretKeyRef:
  77.       name: secret-values
  78.       namespace: default
  79.       key: values.yaml
  80.   # Override immutable resources. This could be dangerous.
  81.   force: false
  82.   # Set the Helm --atomic flag when upgrading
  83.   atomic: false
  84.   # Disable go template pre-processing on the fleet values
  85.   disablePreProcess: false
  86.   # if set and timeoutSeconds provided, will wait until all Jobs have been completed before marking the GitRepo as ready.
  87.   # It will wait for as long as timeoutSeconds
  88.   waitForJobs: true
  90. # A paused bundle will not update downstream clusters but instead mark the bundle
  91. # as OutOfSync. One can then manually confirm that a bundle should be deployed to
  92. # the downstream clusters.
  93. # Default: false
  94. paused: false
  96. rolloutStrategy:
  97.     # A number or percentage of clusters that can be unavailable during an update
  98.     # of a bundle. This follows the same basic approach as a deployment rollout
  99.     # strategy. Once the number of clusters meets unavailable state update will be
  100.     # paused. Default value is 100% which doesn't take effect on update.
  101.     # default: 100%
  102.     maxUnavailable: 15%
  103.     # A number or percentage of cluster partitions that can be unavailable during
  104.     # an update of a bundle.
  105.     # default: 0
  106.     maxUnavailablePartitions: 20%
  107.     # A number of percentage of how to automatically partition clusters if not
  108.     # specific partitioning strategy is configured.
  109.     # default: 25%
  110.     autoPartitionSize: 10%
  111.     # A list of definitions of partitions.  If any target clusters do not match
  112.     # the configuration they are added to partitions at the end following the
  113.     # autoPartitionSize.
  114.     partitions:
  115.       # A user friend name given to the partition used for Display (optional).
  116.       # default: ""
  117.     - name: canary
  118.       # A number or percentage of clusters that can be unavailable in this
  119.       # partition before this partition is treated as done.
  120.       # default: 10%
  121.       maxUnavailable: 10%
  122.       # Selector matching cluster labels to include in this partition
  123.       clusterSelector:
  124.         matchLabels:
  125.           env: prod
  126.       # A cluster group name to include in this partition
  127.       clusterGroup: agroup
  128.       # Selector matching cluster group labels to include in this partition
  129.       clusterGroupSelector: 
  130.         clusterSelector:
  131.           matchLabels:
  132.             env: prod
  134. # Target customization are used to determine how resources should be modified per target
  135. # Targets are evaluated in order and the first one to match a cluster is used for that cluster.
  136. targetCustomizations:
  137. # The name of target. If not specified a default name of the format "target000"
  138. # will be used. This value is mostly for display
  139. - name: prod
  140.   # Custom namespace value overriding the value at the root
  141.   namespace: newvalue
  142.   # Custom defaultNamespace value overriding the value at the root
  143.   defaultNamespace: newdefaultvalue
  144.   # Custom kustomize options overriding the options at the root
  145.   kustomize: {}
  146.   # Custom Helm options override the options at the root
  147.   helm: {}
  148.   # If using raw YAML these are names that map to overlays/{name} that will be used
  149.   # to replace or patch a resource. If you wish to customize the file ./subdir/resource.yaml
  150.   # then a file ./overlays/myoverlay/subdir/resource.yaml will replace the base file.
  151.   # A file named ./overlays/myoverlay/subdir/resource_patch.yaml will patch the base file.
  152.   # A patch can in JSON Patch or JSON Merge format or a strategic merge patch for builtin
  153.   # Kubernetes types. Refer to "Raw YAML Resource Customization" below for more information.
  154.   yaml:
  155.     overlays:
  156.     - custom2
  157.     - custom3
  158.   # A selector used to match clusters.  The structure is the standard
  159.   # metav1.LabelSelector format. If clusterGroupSelector or clusterGroup is specified,
  160.   # clusterSelector will be used only to further refine the selection after
  161.   # clusterGroupSelector and clusterGroup is evaluated.
  162.   clusterSelector:
  163.     matchLabels:
  164.       env: prod
  165.   # A selector used to match a specific cluster by name.    
  166.   clusterName: dev-cluster    
  167.   # A selector used to match cluster groups.
  168.   clusterGroupSelector:
  169.     matchLabels:
  170.       region: us-east
  171.   # A specific clusterGroup by name that will be selected
  172.   clusterGroup: group1
  174. # dependsOn allows you to configure dependencies to other bundles. The current bundle
  175. # will only be deployed, after all dependencies are deployed and in a Ready state.
  176. dependsOn:
  177.   # Format: <GITREPO-NAME>-<BUNDLE_PATH> with all path separators replaced by "-"
  178.   # Example: GitRepo name "one", Bundle path "/multi-cluster/hello-world" => "one-multi-cluster-hello-world"
  179.   - name: one-multi-cluster-hello-world
  180.   # Select bundles to depend on based on their label.
  181.   - selector:
  182.       matchLabels:
  183.         app: weak-monkey