Git Repository Contents
Fleet will create bundles from a git repository. This happens either explicitly by specifying paths, or when a fleet.yaml is found.
Each bundle is created from paths in a GitRepo and modified further by reading the discovered fleet.yaml file.
Bundle lifecycles are tracked between releases by the helm releaseName field added to each bundle. If the releaseName is not
specified within fleet.yaml it is generated from GitRepo.name + path. Long names are truncated and a -<hash> prefix is added.
The git repository has no explicitly required structure. It is important to realize the scanned resources will be saved as a resource in Kubernetes so you want to make sure the directories you are scanning in git do not contain arbitrarily large resources. Right now there is a limitation that the resources deployed must gzip to less than 1MB.
Proper Namespace​
Git repos are added to the Fleet manager using the GitRepo custom resource type. The GitRepo type is namespaced. By default, Rancher will create two Fleet workspaces: fleet-default and fleet-local.
Fleet-defaultwill contain all the downstream clusters that are already registered through Rancher.Fleet-localwill contain the local cluster by default.
Users can create new workspaces and move clusters across workspaces. An example of a special case might be including the local cluster in the GitRepo payload for config maps and secrets (no active deployments or payloads).
While it's possible to move clusters out of either workspace, we recommend that you keep the local cluster in fleet-local.
If you are using Fleet in a single cluster style, the namespace will always be fleet-local. Check here for more on the fleet-local namespace.
For a multi-cluster style, please ensure you use the correct repo that will map to the right target clusters.
How repos are scanned​
Multiple paths can be defined for a GitRepo and each path is scanned independently.
Internally each scanned path will become a bundle that Fleet will manage,
deploy, and monitor independently.
The following files are looked for to determine the how the resources will be deployed.
| File | Location | Meaning |
|---|---|---|
| Chart.yaml: | / relative to path or custom path from fleet.yaml | The resources will be deployed as a Helm chart. Refer to the fleet.yaml for more options. |
| kustomization.yaml: | / relative to path or custom path from fleet.yaml | The resources will be deployed using Kustomize. Refer to the fleet.yaml for more options. |
| fleet.yaml | Any subpath | If any fleet.yaml is found a new bundle will be defined. This allows mixing charts, kustomize, and raw YAML in the same repo |
| *.yaml | Any subpath | If a Chart.yaml or kustomization.yaml is not found then any .yaml or .yml file will be assumed to be a Kubernetes resource and will be deployed. |
| overlays/{name} | / relative to path | When deploying using raw YAML (not Kustomize or Helm) overlays is a special directory for customizations. |
fleet.yaml​
The fleet.yaml is an optional file that can be included in the git repository to change the behavior of how
the resources are deployed and customized. The fleet.yaml is always at the root relative to the path of the GitRepo
and if a subdirectory is found with a fleet.yaml a new bundle is defined that will then be
configured differently from the parent bundle.
Helm chart dependencies:
It is up to the user to fulfill the dependency list for the Helm charts. As such, you must manually run helm dependencies update $chart OR run helm dependencies build $chart prior to install. See the Fleet docs in Rancher for more information.
The available fields are documented in the fleet.yaml reference
For a private Helm repo, users can reference a secret from the git repo resource. See Using Private Helm Repositories for more information.
Per Cluster Customization​
The GitRepo defines which clusters a git repository should be deployed to and the fleet.yaml in the repository
determines how the resources are customized per target.
All clusters and cluster groups in the same namespace as the GitRepo will be evaluated against all targets of that
GitRepo. The targets list is evaluated one by one and if there is a match the resource will be deployed to the cluster.
If no match is made against the target list on the GitRepo then the resources will not be deployed to that cluster.
Once a target cluster is matched the fleet.yaml from the git repository is then consulted for customizations. The
targetCustomizations in the fleet.yaml will be evaluated one by one and the first match will define how the
resource is to be configured. If no match is made the resources will be deployed with no additional customizations.
There are three approaches to matching clusters for both GitRepo targets and fleet.yaml targetCustomizations.
One can use cluster selectors, cluster group selectors, or an explicit cluster group name. All criteria is additive so
the final match is evaluated as "clusterSelector && clusterGroupSelector && clusterGroup". If any of the three have the
default value it is dropped from the criteria. The default value is either null or "". It is important to realize
that the value {} for a selector means "match everything."
# Match everything
clusterSelector: {}
# Selector ignored
clusterSelector: null
Raw YAML Resource Customization​
When using Kustomize or Helm the kustomization.yaml or the helm.values will control how the resource are
customized per target cluster. If you are using raw YAML then the following simple mechanism is built-in and can
be used. The overlays/ folder in the git repo is treated specially as folder containing folders that
can be selected to overlay on top per target cluster. The resource overlay content
uses a file name based approach. This is different from kustomize which uses a resource based approach. In kustomize
the resource Group, Kind, Version, Name, and Namespace identify resources and are then merged or patched. For Fleet
the overlay resources will override or patch content with a matching file name.
# Base files
deployment.yaml
svc.yaml
# Overlay files
# The following file will be added
overlays/custom/configmap.yaml
# The following file will replace svc.yaml
overlays/custom/svc.yaml
# The following file will patch deployment.yaml
overlays/custom/deployment_patch.yaml
A file named foo will replace a file called foo from the base resources or a previous overlay. In order to patch
the contents of a file the convention of adding _patch. (notice the trailing period) to the filename is used. The string _patch.
will be replaced with . from the file name and that will be used as the target. For example deployment_patch.yaml
will target deployment.yaml. The patch will be applied using JSON Merge, Strategic Merge Patch, or JSON Patch.
Which strategy is used is based on the file content. Even though JSON strategies are used, the files can be written
using YAML syntax.