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. |