174 lines
8.2 KiB
Markdown
174 lines
8.2 KiB
Markdown
# 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**.
|
|
|
|
## 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](./concepts.md) 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](./concepts.md) 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](./concepts.md) is defined that will then be
|
|
configured differently from the parent bundle.
|
|
|
|
:::caution
|
|
|
|
__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](https://rancher.com/docs/rancher/v2.6/en/deploy-across-clusters/fleet/#helm-chart-dependencies) in Rancher for more information.
|
|
|
|
:::
|
|
|
|
The available fields are documented in the [fleet.yaml reference](./ref-fleet-yaml.md)
|
|
|
|
For a private Helm repo, users can reference a secret from the git repo resource.
|
|
See [Using Private Helm Repositories](./gitrepo-add.md#using-private-helm-repositories) for more information.
|
|
|
|
## Using Helm Values
|
|
|
|
__How changes are applied to `values.yaml`__:
|
|
|
|
- Note that the most recently applied changes to the `values.yaml` will override any previously existing values.
|
|
|
|
- When changes are applied to the `values.yaml` from multiple sources at the same time, the values will update in the following order: `helm.values` -> `helm.valuesFiles` -> `helm.valuesFrom`. That means `valuesFrom` will take precedence over both, `valuesFiles` and `values`.
|
|
|
|
### Using ValuesFrom
|
|
|
|
These examples showcase the style and format for using `valuesFrom`. ConfigMaps and Secrets should be created in *downstream clusters*.
|
|
|
|
Example [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/):
|
|
|
|
```yaml
|
|
apiVersion: v1
|
|
kind: ConfigMap
|
|
metadata:
|
|
name: configmap-values
|
|
namespace: default
|
|
data:
|
|
values.yaml: |-
|
|
replication: true
|
|
replicas: 2
|
|
serviceType: NodePort
|
|
```
|
|
|
|
Example [Secret](https://kubernetes.io/docs/concepts/configuration/secret/):
|
|
|
|
```yaml
|
|
apiVersion: v1
|
|
kind: Secret
|
|
metadata:
|
|
name: secret-values
|
|
namespace: default
|
|
stringData:
|
|
values.yaml: |-
|
|
replication: true
|
|
replicas: 3
|
|
serviceType: NodePort
|
|
```
|
|
|
|
A secret like that, can be created from a YAML file `secretdata.yaml` by running the following kubectl command: `kubectl create secret generic secret-values --from-file=values.yaml=secretdata.yaml`
|
|
|
|
The resources can then be referenced from a `fleet.yaml`:
|
|
|
|
```yaml
|
|
helm:
|
|
chart: simple-chart
|
|
valuesFrom:
|
|
- secretKeyRef:
|
|
name: secret-values
|
|
namespace: default
|
|
key: values.yaml
|
|
- configMapKeyRef:
|
|
name: configmap-values
|
|
namespace: default
|
|
key: values.yaml
|
|
values:
|
|
replicas: "4"
|
|
```
|
|
|
|
## 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."
|
|
|
|
```yaml
|
|
# Match everything
|
|
clusterSelector: {}
|
|
# Selector ignored
|
|
clusterSelector: null
|
|
```
|
|
|
|
See [Mapping to Downstream Clusters](gitrepo-targets#customization-per-cluster) for more information and a list of supported customizations.
|
|
|
|
## 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.
|
|
|
|
```shell
|
|
# 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.
|
|
|
|
## Cluster and Bundle State
|
|
|
|
See [Cluster and Bundle state](./cluster-bundles-state.md).
|