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 the struct at pkg/bundlereader/read.go, 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 in
  4. # the manifests.
  5. #
  6. # Default: default
  7. defaultNamespace: default
  9. # All resources will be assigned to this namespace and if any cluster scoped
  10. # resource exists the deployment will fail.
  11. #
  12. # Default: ""
  13. namespace: default
  15. # namespaceLabels are labels that will be appended to the namespace created by
  16. # Fleet.
  17. namespaceLabels:
  18.   key: value
  20. # namespaceAnnotations are annotations that will be appended to the namespace
  21. # created by Fleet.
  22. namespaceAnnotations:
  23.   key: value
  25. # Optional map of labels, that are set at the bundle and can be used in a
  26. # dependsOn.selector
  27. labels:
  28.   key: value
  30. kustomize:
  31.   # Use a custom folder for kustomize resources. This folder must contain a
  32.   # kustomization.yaml file.
  33.   dir: ./kustomize
  35. helm:
  37.   # These options control how "fleet apply" downloads the chart
  38.   #
  39.   # Use a custom location for the Helm chart. This can refer to any go-getter
  40.   # URL or OCI registry based helm chart URL e.g.
  41.   # "oci://ghcr.io/fleetrepoci/guestbook".  This allows one to download charts
  42.   # from most any location.  Also know that go-getter URL supports adding a
  43.   # digest to validate the download. If repo is set below this field is the name
  44.   # of the chart to lookup.
  45.   #
  46.   # It is possible to download the chart from a Git repository, e.g.  by using
  47.   # `[email protected]:rancher/fleet-examples//single-cluster/helm`. If a secret
  48.   # for the SSH key was defined in the GitRepo via `helmSecretName`, it will be
  49.   # injected into the chart URL.
  50.   #
  51.   # Git repositories can be downloaded via unauthenticated http, by using for
  52.   # example:
  53.   #
  54.   # `git::http://github.com/rancher/fleet-examples/single-cluster/helm`.
  55.   chart: ./chart
  57.   # A https URL to a Helm repo to download the chart from. It's typically easier
  58.   # to just use `chart` field and refer to a tgz file.  If repo is used the
  59.   # value of `chart` will be used as the chart name to lookup in the Helm
  60.   # repository.
  61.   repo: https://charts.rancher.io
  63.   # The version of the chart or semver constraint of the chart to find. If a
  64.   # constraint is specified it is evaluated each time git changes.
  65.   #
  66.   # The version also determines which chart to download from OCI registries.
  67.   # Note: OCI registries don't support the '+' character, which is supported by
  68.   # semver.  When pushing a helm chart with a tag containing the '+' character
  69.   # helm automatically replaces '+' to '_' before uploading it.
  70.   #
  71.   # You should use the version with the '+' in this file, as the '_' character
  72.   # is not supported by semver and Fleet also replaces '+' to '_' when accessing
  73.   # the OCI registry.
  74.   version: 0.1.0
  76.   # By default fleet downloads any dependency found in a helm chart.  Use
  77.   # disableDependencyUpdate: true to disable this feature.
  78.   disableDependencyUpdate: false
  80.   ### These options only work for helm-type bundles.
  81.   #
  82.   # Any values that should be placed in the `values.yaml` and passed to helm
  83.   # during install.
  84.   values:
  86.     any-custom: value
  88.     # All labels on Rancher clusters are available using
  89.     # global.fleet.clusterLabels.LABELNAME These can now be accessed directly as
  90.     # variables The variable's value will be an empty string if the referenced
  91.     # cluster label does not exist on the targeted cluster.
  92.     variableName: global.fleet.clusterLabels.LABELNAME
  94.     # See Templating notes below for more information on templating.
  95.     templatedLabel: "${ .ClusterLabels.LABELNAME }-foo"
  97.     valueFromEnv:
  98.       "${ .ClusterLabels.ENV }": ${ .ClusterValues.someValue | upper | quote }
  100.   # Path to any values files that need to be passed to helm during install.
  101.   valuesFiles:
  102.     - values1.yaml
  103.     - values2.yaml
  105.   # Allow to use values files from configmaps or secrets defined in the
  106.   # downstream clusters.
  107.   valuesFrom:
  108.     - configMapKeyRef:
  109.         name: configmap-values
  110.         # default to namespace of bundle
  111.         namespace: default
  112.         key: values.yaml
  113.     - secretKeyRef:
  114.         name: secret-values
  115.         namespace: default
  116.         key: values.yaml
  118.   ### These options control how fleet-agent deploys the bundle, they also apply
  119.   ### for kustomize- and manifest-style bundles.
  120.   #
  121.   # A custom release name to deploy the chart as. If not specified a release name
  122.   # will be generated by combining the invoking GitRepo.name + GitRepo.path.
  123.   releaseName: my-release
  124.   #
  125.   # Makes helm skip the check for its own annotations
  126.   takeOwnership: false
  127.   #
  128.   # Override immutable resources. This could be dangerous.
  129.   force: false
  130.   #
  131.   # Set the Helm --atomic flag when upgrading
  132.   atomic: false
  133.   #
  134.   # Disable go template pre-processing on the fleet values
  135.   disablePreProcess: false
  136.   #
  137.   # Disable DNS resolution in Helm's template functions
  138.   disableDNS: false
  139.   #
  140.   # Skip evaluation of the values.schema.json file
  141.   skipSchemaValidation: false
  142.   #
  143.   # If set and timeoutSeconds provided, will wait until all Jobs have been
  144.   # completed before marking the GitRepo as ready.  It will wait for as long as
  145.   # timeoutSeconds.
  146.   waitForJobs: true
  148. # A paused bundle will not update downstream clusters but instead mark the bundle
  149. # as OutOfSync. One can then manually confirm that a bundle should be deployed to
  150. # the downstream clusters.
  151. #
  152. # Default: false
  153. paused: false
  155. rolloutStrategy:
  157.   # A number or percentage of clusters that can be unavailable during an update
  158.   # of a bundle. This follows the same basic approach as a deployment rollout
  159.   # strategy. Once the number of clusters meets unavailable state update will be
  160.   # paused. Default value is 100% which doesn't take effect on update.
  161.   #
  162.   # default: 100%
  163.   maxUnavailable: 15%
  165.   # A number or percentage of cluster partitions that can be unavailable during
  166.   # an update of a bundle.
  167.   #
  168.   # default: 0
  169.   maxUnavailablePartitions: 20%
  171.   # A number of percentage of how to automatically partition clusters if not
  172.   # specific partitioning strategy is configured.
  173.   #
  174.   # default: 25%
  175.   autoPartitionSize: 10%
  177.   # A list of definitions of partitions.  If any target clusters do not match
  178.   # the configuration they are added to partitions at the end following the
  179.   # autoPartitionSize.
  180.   partitions:
  182.     # A user friend name given to the partition used for Display (optional).
  183.     # default: ""
  184.     - name: canary
  186.       # A number or percentage of clusters that can be unavailable in this
  187.       # partition before this partition is treated as done.
  188.       # default: 10%
  189.       maxUnavailable: 10%
  191.       # Selector matching cluster labels to include in this partition
  192.       clusterSelector:
  193.         matchLabels:
  194.           env: prod
  196.       # A cluster group name to include in this partition
  197.       clusterGroup: agroup
  199.       # Selector matching cluster group labels to include in this partition
  200.       clusterGroupSelector:
  201.         clusterSelector:
  202.           matchLabels:
  203.             env: prod
  205. # Target customization are used to determine how resources should be modified
  206. # per target Targets are evaluated in order and the first one to match a cluster
  207. # is used for that cluster.
  208. targetCustomizations:
  210.   # The name of target. If not specified a default name of the format
  211.   # "target000" will be used. This value is mostly for display
  212.   - name: prod
  214.     # Custom namespace value overriding the value at the root.
  215.     namespace: newvalue
  217.     # Custom defaultNamespace value overriding the value at the root.
  218.     defaultNamespace: newdefaultvalue
  220.     # Custom kustomize options overriding the options at the root.
  221.     kustomize: {}
  223.     # Custom Helm options override the options at the root.
  224.     helm: {}
  226.     # If using raw YAML these are names that map to overlays/{name} that will be
  227.     # used to replace or patch a resource. If you wish to customize the file
  228.     # ./subdir/resource.yaml then a file
  229.     # ./overlays/myoverlay/subdir/resource.yaml will replace the base file.  A
  230.     # file named ./overlays/myoverlay/subdir/resource_patch.yaml will patch the
  231.     # base file.  A patch can in JSON Patch or JSON Merge format or a strategic
  232.     # merge patch for builtin Kubernetes types. Refer to "Raw YAML Resource
  233.     # Customization" below for more information.
  234.     yaml:
  235.       overlays:
  236.         - custom2
  237.         - custom3
  239.     # A selector used to match clusters.  The structure is the standard
  240.     # metav1.LabelSelector format. If clusterGroupSelector or clusterGroup is
  241.     # specified, clusterSelector will be used only to further refine the
  242.     # selection after clusterGroupSelector and clusterGroup is evaluated.
  243.     clusterSelector:
  244.       matchLabels:
  245.         env: prod
  247.     # A selector used to match a specific cluster by name. When using Fleet in
  248.     # Rancher, make sure to put the name of the clusters.fleet.cattle.io
  249.     # resource.
  250.     clusterName: dev-cluster
  252.     # A selector used to match cluster groups.
  253.     clusterGroupSelector:
  254.       matchLabels:
  255.         region: us-east
  257.     # A specific clusterGroup by name that will be selected.
  258.     clusterGroup: group1
  260.     # Resources will not be deployed in the matched clusters if doNotDeploy is
  261.     # true.
  262.     doNotDeploy: false
  264.     # Drift correction removes any external change made to resources managed by
  265.     # Fleet.  It performs a helm rollback, which uses a three-way merge strategy
  266.     # by default.  It will try to update all resources by doing a PUT request if
  267.     # force is enabled.  Three-way strategic merge might fail when updating an
  268.     # item inside of an array as it will try to add a new item instead of
  269.     # replacing the existing one.  This can be fixed by using force.  Keep in
  270.     # mind that resources might be recreated if force is enabled.  Failed
  271.     # rollback will be removed from the helm history unless keepFailHistory is
  272.     # set to true.
  273.     correctDrift:
  274.       enabled: false
  275.       force: false # Warning: it might recreate resources if set to true
  276.       keepFailHistory: false
  278. # dependsOn allows you to configure dependencies to other bundles. The current
  279. # bundle will only be deployed, after all dependencies are deployed and in a
  280. # Ready state.
  281. dependsOn:
  283.   # Format:
  284.   #     <GITREPO-NAME>-<BUNDLE_PATH> with all path separators replaced by "-"
  285.   #
  286.   # Example:
  287.   #
  288.   #      GitRepo name "one", Bundle path "/multi-cluster/hello-world"
  289.   #      results in "one-multi-cluster-hello-world".
  290.   #
  291.   # Note:
  292.   #
  293.   #   Bundle names are limited to 53 characters long. If longer they will be
  294.   #   shortened:
  295.   #
  296.   #     opni-fleet-examples-fleets-opni-ui-plugin-operator-crd becomes
  297.   #     opni-fleet-examples-fleets-opni-ui-plugin-opera-021f7
  298.   - name: one-multi-cluster-hello-world
  300.   # Select bundles to depend on based on their label.
  301.   - selector:
  302.       matchLabels:
  303.         app: weak-monkey
  305. # Ignore fields when monitoring a Bundle. This can be used when Fleet thinks
  306. # some conditions in Custom Resources makes the Bundle to be in an error state
  307. # when it shouldn't.
  308. ignore:
  310.   # Conditions to be ignored
  311.   conditions:
  313.     # In this example a condition will be ignored if it contains
  314.     # {"type": "Active", "status", "False"}
  315.     - type: Active
  316.       status: "False"
  318. # Override targets defined in the GitRepo. The Bundle will not have any targets
  319. # from the GitRepo if overrideTargets is provided.
  320. overrideTargets:
  321.   - clusterSelector:
  322.       matchLabels:
  323.         env: dev

Helm Options

How fleet-agent deploys the bundle

These options also apply to kustomize- and manifest-style bundles. They control how the fleet-agent deploys the bundle. All bundles are converted into Helm charts and deployed with the Helm SDK. These options are often similar to the Helm CLI options for install and update.

  • releaseName
  • takeOwnership
  • force
  • atomic
  • disablePreProcess
  • disableDNS
  • skipSchemaValidation
  • waitForJobs

Helm Chart Download Options

These options are for Helm-style bundles, they specify how to download the chart.

  • chart
  • repo
  • version

The reference to the chart can be either:

  • a local path in the cloned Git repository, specified by chart.
  • a go-getter URL, specified by chart. This can be used to download a tarball of the chart. go-getter also allows to download a chart from a Git repo.
  • a Helm repository, specified by repo and optionally version.
  • an OCI Helm repository, specified by repo and optionally version.

Helm Chart Value Options

Options for the downloaded Helm chart.

  • values
  • valuesFiles
  • valueFrom

Templating

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.

Note that if the functions output changes with every call, e.g. uuidv4, the bundle will get redeployed.

The template context has the following keys:

  • .ClusterValues are retrieved from target cluster’s spec.templateValues
  • .ClusterLabels and .ClusterAnnotations are the labels and annotations in the cluster resource.
  • .ClusterName as the fleet’s cluster resource name.
  • .ClusterNamespace as the namespace in which the cluster resource exists.

To access Labels or Annotations by their key name:

  1. ${ get .ClusterLabels "management.cattle.io/cluster-display-name" }

Note: The fleet.yaml must be valid yaml. Templating uses ${ } as delims, unlike Helm which uses {{ }}. These fleet.yaml template delimiters can be escaped using backticks, eg.:

  1. foo-bar-${`${PWD}`}

will result in the following text:

  1. foo-bar-${PWD}