### Full fleet.yaml configuration example

Source: https://fleet.rancher.io/reference/ref-fleet-yaml

A comprehensive example demonstrating various configuration options for bundles, including namespace settings, Helm chart integration, and deployment flags.

```yaml
# 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

# Name of the bundle. If not specified, the bundle name will be computed based
# on the GitRepo's name, and the path from which the bundle is created.
# Default: ""
name: my-great-bundle

# 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:

  # These options control how "fleet apply" downloads the chart
  # (See `Helm Options` below for more details)
  #
  chart: ./chart

  # A https URL to a Helm repo to download the chart from, or an OCI registry
  # URL (oci://...). For OCI registries, repo is the canonical field and no
  # chart name is needed. For standard Helm repos, the value of `chart` is used
  # as the chart name to look up in the repository.
  repo: https://charts.rancher.io

  # The version of the chart or semver constraint of the chart to find. If a
  # constraint is specified, it is evaluated each time git changes.
  # (See `Helm Options` below for more details)
  version: 0.1.0

  # By default fleet downloads any dependency found in a helm chart.  Use
  # disableDependencyUpdate: true to disable this feature.
  disableDependencyUpdate: false

  ### These options only work for helm-type bundles.
  #
  # Any values that should be placed in the `values.yaml` and passed to helm
  # during install.
  values:

    any-custom: value

    # All labels on Rancher clusters are available using
    # global.fleet.clusterLabels.LABELNAME These can now be accessed directly as
    # variables The variable's value will be an empty string if the referenced
    # cluster label does not exist on the targeted cluster.
    variableName: global.fleet.clusterLabels.LABELNAME

    # See Templating notes below for more information on templating.
    templatedLabel: "${ .ClusterLabels.LABELNAME }-foo"

    valueFromEnv:
      "${ .ClusterLabels.ENV }": ${ .ClusterValues.someValue | upper | quote }

  # Path to any values files that need to be passed to helm during install.
  valuesFiles:
    - values1.yaml
    - values2.yaml

  # Allow to use values files from configmaps or secrets defined in the
  # downstream clusters.
  valuesFrom:
    - configMapKeyRef:
        name: configmap-values
        # default to namespace of bundle
        namespace: default
        key: values.yaml
    - secretKeyRef:
        name: secret-values
        namespace: default
        key: values.yaml

  ### These options control how fleet-agent deploys the bundle, they also apply
  ### for kustomize- and manifest-style bundles.
  #
  # A custom release name to deploy the chart as. If not specified a release name
  # will be generated by combining the invoking GitRepo.name + GitRepo.path.
  releaseName: my-release
  #
  # Makes helm skip the check for its own annotations
  takeOwnership: false
  #
  # Override immutable resources. This could be dangerous.
  force: false
  #
  # Set the Helm --atomic flag when upgrading
  atomic: false
  #
  # Disable go template pre-processing on the fleet values
  disablePreProcess: false
  #
  # Disable DNS resolution in Helm's template functions
  disableDNS: false
  #
  # Skip evaluation of the values.schema.json file
  skipSchemaValidation: false
  #
  # If set and timeoutSeconds provided, will wait until all Jobs have been
  # completed before marking the GitRepo as ready.  It will wait for as long as
  # timeoutSeconds.
  waitForJobs: true

# A paused bundle will not update downstream clusters but instead mark the bundle
# as OutOfSync. One can then manually confirm that a bundle should be deployed to
# the downstream clusters.
#
# Default: false
paused: false
```

--------------------------------

### Install Helm CLI and Fleet Repository

Source: https://fleet.rancher.io/tutorials/quickstart

Install the Helm CLI and add the Fleet repository for your operating system.

```bash
brew install helm
helm repo add fleet https://rancher.github.io/fleet-helm-charts/
```

```bash
choco install kubernetes-helm
helm repo add fleet https://rancher.github.io/fleet-helm-charts/
```

--------------------------------

### Cluster Registration Output Example

Source: https://fleet.rancher.io/how-tos-for-operators/cluster-registration

Example output showing the status of registered clusters.

```text
NAME                   BUNDLES-READY   NODES-READY   SAMPLE-NODE             LAST-SEEN              STATUS
my-cluster             1/1             1/1           k3d-cluster2-server-0   2020-08-31T19:23:10Z
```

--------------------------------

### Clone the Fleet examples repository

Source: https://fleet.rancher.io/how-tos-for-users/install-use-fleet-cli

Downloads the official repository containing sample bundles for testing.

```bash
git clone https://github.com/rancher/fleet-examples
cd fleet-examples/single-cluster
```

--------------------------------

### Example Directory Structure

Source: https://fleet.rancher.io/explanations/gitrepo-content

Visual representation of a repository structure for user-driven bundle definitions.

```text
driven
     |___helm
     |      |__ fleet.yaml
     |
     |___simple
     |      |__ configmap.yaml
     |      |__ service.yaml
     |
     |___kustomize
            |__ base
            |      |__ kustomization.yaml
            |      |__ secret.yaml
            |
            |__ overlays
            |         |__ dev
            |         |     |__ kustomization.yaml
            |         |     |__ secret.yaml
            |         |__ prod
            |         |     |__ kustomization.yaml
            |         |     |__ secret.yaml
            |         |__ test
            |               |__ kustomization.yaml
            |               |__ secret.yaml
            |__ dev.yaml
            |__ prod.yaml
            |__ test.yaml
```

--------------------------------

### Install Fleet Charts

Source: https://fleet.rancher.io/how-tos-for-operators/installation

Commands to add the Fleet Helm repository and install the CRDs and controller components.

```bash
API_SERVER_URL="https://example.com:6443"
API_SERVER_CA="ca.pem"
```

```bash
helm repo add fleet https://rancher.github.io/fleet-helm-charts/
```

```bash
helm -n cattle-fleet-system install --create-namespace --wait \
    fleet-crd fleet/fleet-crd
```

```bash
helm -n cattle-fleet-system install --create-namespace --wait \
    --set apiServerURL="$API_SERVER_URL" \
    --set-file apiServerCA="$API_SERVER_CA" \
    fleet fleet/fleet
```

--------------------------------

### Verify Prerequisites

Source: https://fleet.rancher.io/how-tos-for-users/install-use-fleet-cli

Checks that kubectl, Helm, and the Fleet CLI are correctly installed and configured.

```bash
kubectl get nodes
helm version
fleet --version
```

--------------------------------

### Install Fleet Controllers

Source: https://fleet.rancher.io/how-tos-for-operators/installation

Deploys the Fleet controller components into the cluster.

```bash
helm -n cattle-fleet-system install --create-namespace --wait fleet \
    fleet/fleet
```

--------------------------------

### Ready Condition Status Example

Source: https://fleet.rancher.io/reference/ref-status-fields

Example of the status conditions field showing a non-ready state with aggregated BundleDeployment information.

```yaml
status:
  conditions:
  - lastUpdateTime: "2025-06-25T14:59:35Z"
    message: WaitApplied(1) [Cluster fleet-default/downstream4]
    status: "False"
    type: Ready
```

--------------------------------

### Verify Fleet CLI Installation

Source: https://fleet.rancher.io/how-tos-for-users/install-use-fleet-cli

Checks the installed version of the Fleet CLI.

```bash
fleet --version
```

--------------------------------

### Install Fleet CLI on Windows

Source: https://fleet.rancher.io/how-tos-for-users/install-use-fleet-cli

Downloads the Fleet executable using PowerShell.

```powershell
Invoke-WebRequest -Uri "https://github.com/rancher/fleet/releases/latest/download/fleet-windows-amd64.exe" -OutFile "fleet.exe"
```

--------------------------------

### Template Output Example

Source: https://fleet.rancher.io/reference/ref-fleet-yaml

The resulting string after processing the escaped template delimiter example.

```text
foo-bar-${PWD}
```

--------------------------------

### Configuring concurrency for bundle creation

Source: https://fleet.rancher.io/reference/cli/fleet-cli/fleet_apply

Example of setting the bundle creation concurrency using an environment variable.

```bash
FLEET_BUNDLE_CREATION_MAX_CONCURRENCY=8 fleet apply <args>
```

--------------------------------

### Kustomize Options File Configuration

Source: https://fleet.rancher.io/explanations/gitrepo-content

Example of an options file content used to configure a kustomize bundle.

```yaml
namespace: kustomize-dev
kustomize:
  dir: "overlays/dev"
```

--------------------------------

### Example .fleetignore directory structure

Source: https://fleet.rancher.io/explanations/gitrepo-content

Visual representation of how .fleetignore files function at different levels of a directory tree.

```text
root/
├── .fleetignore            # contains `ignore-always.yaml'
├── something.yaml
├── bar
│   ├── .fleetignore        # contains `something.yaml`
│   ├── ignore-always.yaml
│   ├── something2.yaml
│   └── something.yaml
└── foo
    ├── ignore-always.yaml
    └── something.yaml
bashCopied!
```

--------------------------------

### Install Fleet Agent

Source: https://fleet.rancher.io/how-tos-for-operators/cluster-registration

Deploy the Fleet agent using Helm in the cattle-fleet-system namespace.

```bash
helm -n cattle-fleet-system install --create-namespace --wait \
    --set clientID="$CLUSTER_CLIENT_ID" \
    --values values.yaml \
    fleet-agent fleet/fleet-agent
```

--------------------------------

### Install Fleet Helm Charts

Source: https://fleet.rancher.io/tutorials/quickstart

Deploy the Fleet CRD and Fleet charts into the cattle-fleet-system namespace.

```bash
helm -n cattle-fleet-system install --create-namespace --wait fleet-crd \
    fleet/fleet-crd
helm -n cattle-fleet-system install --create-namespace --wait fleet \
    fleet/fleet
```

--------------------------------

### Verify Fleet Installation

Source: https://fleet.rancher.io/how-tos-for-operators/installation

Check the logs and pod status to ensure the Fleet controller is running correctly.

```bash
kubectl -n cattle-fleet-system logs -l app=fleet-controller
kubectl -n cattle-fleet-system get pods -l app=fleet-controller
```

```text
NAME                                READY   STATUS    RESTARTS   AGE
fleet-controller-64f49d756b-n57wq   1/1     Running   0          3m21s
```

--------------------------------

### Install Fleet CLI on Linux/macOS

Source: https://fleet.rancher.io/how-tos-for-users/install-use-fleet-cli

Downloads the latest Fleet binary, makes it executable, and moves it to the system path.

```bash
curl -L -o fleet https://github.com/rancher/fleet/releases/latest/download/fleet-linux-amd64

# Make it executable and move to PATH
chmod +x fleet
sudo mv fleet /usr/local/bin/
```

--------------------------------

### Create a Nginx Deployment Bundle

Source: https://fleet.rancher.io/how-tos-for-users/bundle-add

Example of a Bundle resource definition deploying an Nginx deployment to the local cluster.

```yaml
kind: Bundle
apiVersion: fleet.cattle.io/v1alpha1
metadata:
  # Any name can be used here
  name: my-bundle
  # For single cluster use fleet-local, otherwise use the namespace of
  # your choosing
  namespace: fleet-local
spec:
  resources:
  # List of all resources that will be deployed
  - content: |
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: nginx-deployment
        labels:
          app: nginx
      spec:
        replicas: 3
        selector:
          matchLabels:
            app: nginx
        template:
          metadata:
            labels:
              app: nginx
          spec:
            containers:
              - name: nginx
                image: nginx:1.14.2
                ports:
                  - containerPort: 80
    name: nginx.yaml
  targets:
  - clusterName: local
```

--------------------------------

### Verify Fleet Installation

Source: https://fleet.rancher.io/how-tos-for-operators/installation

Commands to check the status and logs of the Fleet controller pods.

```bash
kubectl -n cattle-fleet-system logs -l app=fleet-controller
kubectl -n cattle-fleet-system get pods -l app=fleet-controller
```

--------------------------------

### Fleet and Helm Templating Example

Source: https://fleet.rancher.io/how-tos-for-users/templating

Demonstrates the use of Fleet's ${ } syntax alongside Helm's {{ }} syntax within a fleet.yaml file.

```yaml
values:
  cluster: ${ .ClusterName }

config:
  message: "{{ .Values.message }}"
```

--------------------------------

### Install Fleet with additional SSH known hosts

Source: https://fleet.rancher.io/how-tos-for-operators/installation

Use the additionalKnownHosts Helm value to add custom SSH host keys during installation for private git servers.

```bash
helm -n cattle-fleet-system install --create-namespace --wait fleet fleet/fleet \
  --set additionalKnownHosts={'ourgitserver.company ssh-rsa <fingerprint>','our-other-git-server.company ssh-ed25519 <fingerprint2>'}
```

--------------------------------

### Example directory structure for a Helm chart

Source: https://fleet.rancher.io/explanations/gitrepo-content

Standard layout for a Helm chart repository containing a fleet.yaml configuration file.

```text
.
├── Chart.yaml
├── fleet.yaml
├── README.md
├── templates/
│   ├── deployment.yaml
│   └── service.yaml
└── values.yaml   # chart defaults
```

--------------------------------

### Example CA Certificate File

Source: https://fleet.rancher.io/how-tos-for-operators/installation

The expected format of the extracted ca.pem file.

```pem
-----BEGIN CERTIFICATE-----
MIIBVjCB/qADAgECAgEAMAoGCCqGSM49BAMCMCMxITAfBgNVBAMMGGszcy1zZXJ2
ZXItY2FAMTU5ODM5MDQ0NzAeFw0yMDA4MjUyMTIwNDdaFw0zMDA4MjMyMTIwNDda
...
-----END CERTIFICATE-----
```

--------------------------------

### Define a basic Schedule resource

Source: https://fleet.rancher.io/experimental-features/scheduling

Configures a 1-hour deployment window starting daily at 22:00 for a specific cluster.

```yaml
apiVersion: fleet.cattle.io/v1alpha1
kind: Schedule
metadata:
  name: schedule-test
  namespace: fleet-local
spec:
  schedule: "0 0 22 * * *"
  duration: 1h
  targets:
    clusters:
      - name: local
        clusterName: local
```

--------------------------------

### Configure default resource limits via Helm

Source: https://fleet.rancher.io/how-tos-for-operators/resource-limits

Apply global resource constraints during Helm installation or upgrade.

```bash
helm -n cattle-fleet-system upgrade --install fleet fleet/fleet \
  --set resources.limits.cpu=8000m \
  --set resources.limits.memory=8Gi \
  --set resources.requests.cpu=250m \
  --set resources.requests.memory=768Mi
```

--------------------------------

### Define a Bundle Resource

Source: https://fleet.rancher.io/reference/ref-bundle

Example of a Bundle resource configuration including metadata, deployment options, and embedded YAML resources.

```yaml
kind: Bundle
apiVersion: fleet.cattle.io/v1alpha1
metadata:
  # Any name can be used here
  name: my-bundle
  # For single cluster use fleet-local, otherwise use the namespace of
  # your choosing
  namespace: fleet-local
spec:
  # Namespace used for resources that do not specify a namespace.
  # This field is not used to enforce or lock down the deployment to a specific namespace.
  # defaultNamespace: test

  # If present will assign all resource to this
  # namespace and if any cluster scoped resource exists the deployment will fail.
  # targetNamespace: app

  # Kustomize options for the deployment, like the dir containing the kustomization.yaml file.
  # kustomize: ...

  # Helm options for the deployment, like the chart name, repo and values.
  # helm: ...

  # ServiceAccount which will be used to perform this deployment.
  # serviceAccount: sa

  # ForceSyncGeneration is used to force a redeployment.
  # forceSyncGeneration: 0

  # YAML options, if using raw YAML these are names that map to overlays/{name} that will be used to replace or patch a resource.
  # yaml: ...

  # Diff can be used to ignore the modified state of objects which are amended at runtime.
  # A specific commit or tag can also be watched.
  #
  # diff: ...

  # KeepResources can be used to keep the deployed resources when removing the bundle.
  # keepResources: false

  # If set to true, will stop any BundleDeployments from being updated. It will be marked as out of sync.
  # paused: false

  # Controls the rollout of bundles, by defining partitions, canaries and percentages for cluster availability.
  # rolloutStrategy: ...

  # Contain the actual resources from the git repo which will be deployed.
  resources:
  - content: |
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: nginx-deployment
        labels:
          app: nginx
      spec:
        replicas: 3
        selector:
          matchLabels:
            app: nginx
        template:
          metadata:
            labels:
              app: nginx
          spec:
            containers:
              - name: nginx
                image: nginx:1.14.2
                ports:
                  - containerPort: 80
    name: nginx.yaml

  # Target clusters to deploy to if running Fleet in a multi-cluster
  # style. Refer to the "Mapping to Downstream Clusters" docs for
  # more information.
  #
  # targets: ...

  # This field is used by Fleet internally, and it should not be modified manually.
  # Fleet will copy all targets into targetRestrictions when a Bundle is created for a GitRepo.
  # targetRestrictions: ...

  # Refers to the bundles which must be ready before this bundle can be deployed.
  # dependsOn: ...
```

--------------------------------

### Configure Cluster Targets

Source: https://fleet.rancher.io/how-tos-for-users/gitrepo-targets

Examples of using cluster selectors to match clusters or ignoring them, and matching clusters by name.

```yaml
targets:
  # Match everything
  - clusterSelector: {}
  # Selector ignored
  - clusterSelector: null
```

```yaml
targets:
  - clusterName: fleetname
```

--------------------------------

### Secrets Path Configuration File

Source: https://fleet.rancher.io/how-tos-for-users/gitrepo-add

Example content for the secrets-path.yaml file defining credentials for specific paths.

```yaml
single-cluster/test-multipasswd/passwd:
  username: fleet-ci
  password: foo
  insecureSkipVerify: true
```

```yaml
path-one: # path path-one must exist in the repository
  username: user
  password: pass
path-two: # path path-two must exist in the repository
  username: user2
  password: pass2
  caBundle: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCiAgICBNSUlEblRDQ0FvV2dBd0lCQWdJVUNwMHB2...
  sshPrivateKey: ICAgIC0tLS0tQkVHSU4gQ0VSVElGSUNBVEUtLS0tLQogICAgTUlJRFF6Q0NBaXNDRkgxTm5Y...
```

--------------------------------

### Example diff output

Source: https://fleet.rancher.io/how-tos-for-users/bundle-diffs

The default output format showing modified resources and their corresponding JSON Merge Patch.

```yaml
Bundle: my-bundle
BundleDeployments with diffs: 1
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  BundleDeployment: cluster-fleet-local-local-abc123/my-bundle-deployment
  Modified Resources (1):
    Resource: ConfigMap.v1 default/my-config
    Status: Modified
    Patch:
    {
      "metadata": {
        "annotations": {
          "timestamp": "2024-01-15T10:30:00Z"
        }
      }
    }
```

--------------------------------

### Common Monitor Usage Patterns

Source: https://fleet.rancher.io/reference/cli/fleet-cli/fleet_monitor

Examples of piping monitor output to jq or fleet analyze, and saving continuous monitoring data to a file.

```bash
# Single snapshot with formatted output
fleet monitor | jq

# Single snapshot with human-readable analysis
fleet monitor | fleet analyze

# Continuous monitoring with built-in watch mode (every 60 seconds)
fleet monitor --watch --interval 60 >> monitor.json
```

--------------------------------

### Fleet analyze usage examples

Source: https://fleet.rancher.io/reference/cli/fleet-cli/fleet_analyze

Common usage patterns for analyzing snapshots, including stdin piping and flag combinations.

```bash
# Analyze latest snapshot
fleet analyze monitor.json

# Analyze from stdin
fleet monitor | fleet analyze

# Show all snapshots in file
fleet analyze --all monitor.json

# Show changes between consecutive snapshots
fleet analyze --diff monitor.json

fleet analyze --issues monitor.json

# Detailed analysis with controller info and events
fleet analyze --detailed monitor.json

# Compare two specific snapshot files
fleet analyze --compare before.json after.json

# JSON output for programmatic use
fleet analyze --json monitor.json

# Disable colored output
fleet analyze --no-color monitor.json
```

--------------------------------

### Install Fleet with Sharding via Helm

Source: https://fleet.rancher.io/how-tos-for-operators/installation

Use Helm to deploy Fleet with multiple shards, each assigned a unique ID and node selector.

```bash
helm -n cattle-fleet-system install --create-namespace --wait fleet fleet/fleet \
  --set shards[0].id=foo \
  --set shards[0].nodeSelector."kubernetes\.io/hostname"=k3d-upstream-server-0 \
  --set shards[1].id=bar \
  --set shards[1].nodeSelector."kubernetes\.io/hostname"=k3d-upstream-server-1 \
  --set shards[2].id=baz \
  --set shards[2].nodeSelector."kubernetes\.io/hostname"=k3d-upstream-server-2
```

--------------------------------

### Define GitRepo resource structure

Source: https://fleet.rancher.io/explanations/gitrepo-content

Example directory structure showing base files and overlay files for resource customization.

```yaml
# Base files
deployment.yaml
svc.yaml

# Overlay files
overlays/custom/configmap.yaml
overlays/custom/svc.yaml
overlays/custom/deployment_patch.yaml
```

--------------------------------

### Reference a chart by absolute URL

Source: https://fleet.rancher.io/how-tos-for-users/helm-ops

Configures a HelmOp to install a chart directly from a .tgz URL. Repo and version fields must be empty.

```yaml
  helm:
    chart: https://example.com/charts/my-chart-1.2.3.tgz

    # can be omitted
    repo: ''
    version: ''
```

--------------------------------

### View bundle status fields

Source: https://fleet.rancher.io/how-tos-for-users/validate-fleet-cli

Example of the status section within a bundle's YAML output indicating readiness.

```yaml
status:
  display:
    readyClusters: 1/1
  summary:
    desiredReady: 1
    ready: 1
  conditions:
    type: Ready
    status: "True"
```

--------------------------------

### Apply a sample bundle to the current cluster

Source: https://fleet.rancher.io/how-tos-for-users/install-use-fleet-cli

Deploys a local bundle directly to the current cluster, creating a Bundle resource in the namespace.

```bash
fleet apply -o my-cool-bundle manifests
```

--------------------------------

### Install Fleet CRDs

Source: https://fleet.rancher.io/how-tos-for-operators/installation

Installs the required CustomResourceDefinitions for Fleet into the cattle-fleet-system namespace.

```bash
helm -n cattle-fleet-system install --create-namespace --wait fleet-crd \
    fleet/fleet-crd
```

--------------------------------

### Execute the full bundle lifecycle

Source: https://fleet.rancher.io/explanations/ref-bundle-stages

Demonstrates the end-to-end process of applying, targeting, and dry-running a deployment using the Fleet CLI.

```bash
git clone https://github.com/rancher/fleet-test-data
cd fleet-test-data
fleet apply -n fleet-local -o bundle.yaml testbundle simple-chart/
fleet target --bundle-file bundle.yaml --list-inputs  > bd.yaml
fleet deploy --input-file bd.yaml --dry-run
```

--------------------------------

### Fleet apply command syntax

Source: https://fleet.rancher.io/reference/cli/fleet-cli/fleet_apply

The basic command structure for creating bundles from directories.

```bash
fleet apply [flags] BUNDLE_NAME PATH...
```

--------------------------------

### Troubleshooting: Performance Issues

Source: https://fleet.rancher.io/reference/cli/fleet-cli/fleet_monitor

Analyze bundle sizes and content availability.

```bash
# Check bundle sizes
fleet monitor | jq '.diagnostics.largeBundles'

# Find bundles with most resources
fleet monitor | jq '[.bundles[] | {name, size: .sizeBytes, sizeMB: (.sizeBytes / 1048576 | floor)}] |
  sort_by(.size) | reverse'

# Check for missing content resources
fleet monitor | jq '.diagnostics.bundlesWithMissingContent'
```

--------------------------------

### Troubleshooting: Bundle Not Deploying

Source: https://fleet.rancher.io/reference/cli/fleet-cli/fleet_monitor

Analyze bundle status and consistency issues.

```bash
# Capture current state
fleet monitor | jq > bundle-status.json

# Check for bundles with generation mismatch
jq '.diagnostics.bundlesWithGenerationMismatch' bundle-status.json

# Check if bundle matched any targets
jq '.diagnostics.bundlesWithNoDeployments' bundle-status.json

# Check bundle-to-gitrepo consistency
jq '.diagnostics.gitRepoBundleInconsistencies' bundle-status.json
```

--------------------------------

### GitRepo Resource Configuration

Source: https://fleet.rancher.io/how-tos-for-users/gitrepo-add

Example of a GitRepo resource configured to use path-specific secrets.

```yaml
kind: GitRepo
apiVersion: fleet.cattle.io/v1alpha1
metadata:
  name: gitrepo
  namespace: fleet-local
spec:
  helmSecretNameForPaths: test-multipasswd
  repo: https://github.com/0xavi0/fleet-examples
  branch: helm-multi-passwd
  paths:
  - single-cluster/test-multipasswd
```

--------------------------------

### Configure GitRepo for Consul Chart

Source: https://fleet.rancher.io/how-tos-for-users/bundle-diffs

Initial configuration for installing a Helm chart via a GitRepo.

```yaml
defaultNamespace: consul
helm:
  releaseName: test-consul
  chart: "consul"
  repo: "https://helm.releases.hashicorp.com"

  values:
    global:
      name: consul
      acls:
        manageSystemACLs: true
```

--------------------------------

### Identify gzip header error

Source: https://fleet.rancher.io/troubleshooting

Example error message indicating an issue with the Helm chart content.

```sh
Error opening a gzip reader for /tmp/getter154967024/archive: gzip: invalid header
```

--------------------------------

### Incorrect Kustomize Directory Reference

Source: https://fleet.rancher.io/explanations/gitrepo-content

An example of an incorrect kustomize directory path definition relative to the base.

```yaml
namespace: kustomize-dev
kustomize:
  dir: "."
```

--------------------------------

### Render a folder into a Fleet bundle

Source: https://fleet.rancher.io/explanations/ref-bundle-stages

Use the apply command to convert Kubernetes resources into a bundle resource file.

```bash
git clone https://github.com/rancher/fleet-test-data
cd fleet-test-data
fleet apply -n fleet-local -o bundle.yaml testbundle simple-chart/
```

--------------------------------

### Convert Helm Chart to Bundle

Source: https://fleet.rancher.io/how-tos-for-users/install-use-fleet-cli

Creates a targets file and a fleet.yaml configuration, then uses the fleet CLI to generate and apply a bundle.

```bash
cat > targets.yaml <<EOF
targets:
- clusterSelector: {}
EOF

mkdir app
cat > app/fleet.yaml <<EOF
defaultNamespace: external-secrets
helm:
  repo: https://charts.external-secrets.io
  chart: external-secrets
EOF

fleet apply --compress --targets-file=targets.yaml -n fleet-default -o - external-secrets app > eso-bundle.yaml

kubectl apply -f eso-bundle.yaml
```

--------------------------------

### Apply configuration with Helm values file

Source: https://fleet.rancher.io/how-tos-for-operators/resource-limits

Use a values file to apply the defined resource configuration.

```bash
helm -n cattle-fleet-system upgrade --install fleet fleet/fleet \
  -f values.yaml
```

--------------------------------

### Fleet 403 Error Log

Source: https://fleet.rancher.io/troubleshooting

Example of the error message returned when Fleet cannot access a specified Helm repository.

```text
time="2021-11-04T09:21:24Z" level=fatal msg="bad response code: 403"
```

--------------------------------

### Define Path-Specific Credentials

Source: https://fleet.rancher.io/how-tos-for-users/gitrepo-add

Example configuration for matching repository paths to specific credentials using glob patterns.

```yaml
world-domination/*_charts: # will not be used
  username: fleet-ci
  password: foo
  insecureSkipVerify: true
world-domination/*: # will be used, as `/*` will be sorted before `/*_charts`
  username: fleet-ci
  password: foo
  insecureSkipVerify: true
```

--------------------------------

### Apply a bundle with Fleet CLI

Source: https://fleet.rancher.io/how-tos-for-users/install-use-fleet-cli

Creates or previews a bundle from local files without requiring a cluster connection.

```bash
fleet apply my-bundle ./manifests
```

--------------------------------

### Construct Diff Patch Operation

Source: https://fleet.rancher.io/how-tos-for-users/bundle-diffs

Example of a patch operation to ignore specific fields by targeting array indices.

```yaml
  - apiVersion: admissionregistration.k8s.io/v1
    kind: ValidatingWebhookConfiguration
    name: gatekeeper-validating-webhook-configuration
    operations:
    - {"op": "remove", "path":"/webhooks/0/clientConfig/caBundle"}
    - {"op": "remove", "path":"/webhooks/0/rules"}
    - {"op": "remove", "path":"/webhooks/1/clientConfig/caBundle"}
    - {"op": "remove", "path":"/webhooks/1/rules"}
```

--------------------------------

### Deploy Kustomize with Target Customizations

Source: https://fleet.rancher.io/tutorials/tut-deployment

Applies a GitRepo resource configured with Kustomize paths and environment-specific cluster selectors.

```bash
kubectl apply -n fleet-default -f - <<EOF
kind: GitRepo
apiVersion: fleet.cattle.io/v1alpha1
metadata:
  name: kustomize
  namespace: fleet-default
spec:
  repo: https://github.com/rancher/fleet-examples
  paths:
  - multi-cluster/kustomize
  targets:
  - name: dev
    clusterSelector:
      matchLabels:
        env: dev

  - name: test
    clusterSelector:
      matchLabels:
        env: test

  - name: prod
    clusterSelector:
      matchLabels:
        env: prod
EOF
```

--------------------------------

### Apply Kustomize GitRepo

Source: https://fleet.rancher.io/tutorials/tut-deployment

Deploys resources using Kustomize by applying a GitRepo resource.

```bash
kubectl apply -n fleet-local -f - <<EOF
kind: GitRepo
apiVersion: fleet.cattle.io/v1alpha1
metadata:
  name: helm
spec:
  repo: https://github.com/rancher/fleet-examples
  paths:
  - single-cluster/kustomize
EOF
```

--------------------------------

### Fleet Controller Pod Status Output

Source: https://fleet.rancher.io/how-tos-for-operators/installation

Example output showing the expected status of the Fleet controller pod.

```text
NAME                                READY   STATUS    RESTARTS   AGE
fleet-controller-64f49d756b-n57wq   1/1     Running   0          3m21s
```

--------------------------------

### Run fleet-controller

Source: https://fleet.rancher.io/reference/cli/fleet-controller/fleet-controller

Basic command syntax to execute the fleet-controller.

```bash
fleet-controller [flags]
```

--------------------------------

### Enable experimental features for Fleet with Rancher

Source: https://fleet.rancher.io/experimental-features/enableexperimental

Use these flags when installing Fleet through Rancher. The parameters require the fleet. prefix.

```bash
--set-string fleet.extraEnv[0].name=EXPERIMENTAL_SCHEDULES \
--set-string fleet.extraEnv[0].value=true
```

--------------------------------

### Identify modified resource in fleet-agent logs

Source: https://fleet.rancher.io/troubleshooting

Example log entry showing a deployment modification that can be ignored via patches.

```text
level=error msg="bundle monitoring-monitoring: deployment.apps monitoring/monitoring-monitoring-kube-state-metrics modified {\"spec\":{\"template\":{\"spec\":{\"hostNetwork\":false}}}}"
```

--------------------------------

### List all bundle deployments

Source: https://fleet.rancher.io/how-tos-for-users/validate-fleet-cli

Verify the status of individual BundleDeployment objects, which correspond to specific target clusters.

```bash
kubectl get bundledeployments.fleet.cattle.io -A
```

--------------------------------

### Define a Tenant GitRepo Resource

Source: https://fleet.rancher.io/how-tos-for-operators/multi-user

Example of a GitRepo resource created by a tenant, including required labels and target specifications.

```yaml
kind: GitRepo
apiVersion: fleet.cattle.io/v1alpha1
metadata:
  name: simpleapp
  namespace: workspace1
  labels:
    team: one

spec:
  repo: https://github.com/rancher/fleet-examples
  paths:
  - bundle-diffs

  targetNamespace: workspace1simpleapp

  # do not match the upstream/local cluster, won't work
  targets:
  - name: dev
    clusterSelector:
      matchLabels:
        env: dev
```

--------------------------------

### Configure Rollout Strategy for Multiple Partitions

Source: https://fleet.rancher.io/how-tos-for-users/rollout

Use this configuration to define multiple partitions and control rollout concurrency.

```yaml
rolloutStrategy:
  maxUnavailablePartitions: 1
  autoPartitionSize: 10%
```

--------------------------------

### Fleet deploy command syntax

Source: https://fleet.rancher.io/reference/cli/fleet-cli/fleet_deploy

Basic usage syntax for the fleet deploy command.

```bash
fleet deploy [flags]
```

--------------------------------

### Bundle Definition with Nested Options Path

Source: https://fleet.rancher.io/explanations/gitrepo-content

Example of defining a bundle where the options file is located within a subdirectory of the base.

```yaml
bundles:
    - base: driven/kustomize
      options: overlays/dev/dev.yaml
```

--------------------------------

### Basic Monitoring Commands

Source: https://fleet.rancher.io/reference/cli/fleet-cli/fleet_monitor

Use these commands to retrieve current snapshots of the Fleet state, optionally filtered by namespace.

```bash
# Single snapshot with pretty formatting
fleet monitor | jq

# Monitor specific namespace
fleet monitor -n fleet-local | jq

# Check fleet-default namespace (common for local clusters)
fleet monitor -n fleet-default | jq
```

--------------------------------

### Enable error interpretation via GVK mapping

Source: https://fleet.rancher.io/how-tos-for-users/fine-tune-error

Example configuration to explicitly treat a specific condition status as an error.

```json
[
  {
    "gvk": "sample.cattle.io/v1, Kind=Sample",
    "conditionMappings": [
      { "type": "Failed", "status": ["True"] }
    ]
  }
]
```

--------------------------------

### Define GitRepo with Multiple Bundles

Source: https://fleet.rancher.io/explanations/gitrepo-content

Example of a GitRepo resource defining multiple bundles with different base directories and options files.

```yaml
kind: GitRepo
apiVersion: fleet.cattle.io/v1alpha1
metadata:
  name: driven
  namespace: fleet-local
spec:
  repo: https://github.com/0xavi0/fleet-test-data
  branch: driven-scan-example
  bundles:
  - base: driven/helm
  - base: driven/simple
  - base: driven/kustomize
    options: dev.yaml
  - base: driven/kustomize
    options: test.yaml
```