Fleet Examples

This repository provides categorized examples of how to use Fleet for different deployment scenarios:

Single Cluster Examples

Deploy content to clusters with no per-cluster customizations. Useful for learning basic Git repo structuring.

• manifests: Raw Kubernetes YAML.
• helm: Using Helm charts.
• helm-multi-chart: Deploying multiple charts from a single repo.
• kustomize: Using Kustomize.
• helm-kustomize: Using Kustomize to modify a third-party Helm chart.

Multi-Cluster Examples

Deploy a single Git repo to multiple clusters simultaneously, configuring the application differently for each target cluster.

• manifests: Raw Kubernetes YAML with per-target customization.
• helm: Helm with per-target customization.
• helm-external: Using a Helm chart from a third-party source with per-target customization.
• kustomize: Kustomize with per-target customization.
• helm-kustomize: Using Kustomize to modify a third-party Helm chart for multi-cluster targets.
• windows-helm: Using Helm for Windows cluster(s).

You can use Fleet's GitRepo resource to deploy applications across multiple clusters while applying different configurations based on the target environment. By defining multiple targets within a single GitRepo object, you can use clusterSelector to map specific paths or configurations to clusters matching certain labels (e.g., env: dev, env: test, or env: prod).

In this pattern, Kustomize is used to handle the environment-specific overrides, such as scaling deployments or changing service types, while Fleet manages the distribution to the correct clusters.

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

This example demonstrates how to use Fleet to deploy a third-party Helm chart while applying environment-specific customizations via Kustomize.

In this pattern, you define a GitRepo resource that points to a repository containing your Fleet manifests. Within that repository, you use Kustomize to override Helm chart values or configurations based on the target environment.

This specific example deploys a guestbook application into the fleet-mc-helm-kustomize-example namespace with the following environment-specific logic:

• Dev clusters: Deploys only the redis leader (omits followers).
• Test clusters: Scales the front deployment to 3 replicas.
• Prod clusters: Scales the front deployment to 3 replicas and sets the service type to LoadBalancer.

kind: GitRepo
apiVersion: fleet.cattle.io/v1alpha1
metadata:
  name: helm-kustomize
  namespace: fleet-default
spec:
  repo: https://github.com/rancher/fleet-examples
  paths:
  - multi-cluster/helm-kustomize
  targets:
  - name: dev
    clusterSelector:
      matchLabels:
        env: dev

  - name: test
    clusterSelector:
      matchLabels:
        env: test

  - name: prod
    clusterSelector:
      matchLabels:
        env: prod

This example demonstrates how to use a GitRepo resource to deploy a third-party Helm chart across multiple clusters with environment-specific customizations.

In this pattern, a single GitRepo resource defines multiple targets. Each target uses a clusterSelector to identify which clusters should receive the deployment. This allows you to apply different configurations (via Helm values or other overrides) to different environments like dev, test, and prod based on cluster labels.

Deployment Logic for this Example:

• Dev clusters (labeled env: dev): Deploys only the redis leader (no followers).
• Test clusters (labeled env: test): Scales the front deployment to 3 replicas.
• Prod clusters (labeled env: prod): Scales the front deployment to 3 replicas and sets the service type to LoadBalancer.

kind: GitRepo
apiVersion: fleet.cattle.io/v1alpha1
metadata:
  name: helm-external
  namespace: fleet-default
spec:
  repo: https://github.com/rancher/fleet-examples
  paths:
  - multi-cluster/helm-external
  targets:
  - name: dev
    clusterSelector:
      matchLabels:
        env: dev

  - name: test
    clusterSelector:
      matchLabels:
        env: test

  - name: prod
    clusterSelector:
      matchLabels:
        env: prod

Before running tests, you need to set up a local environment using k3d, kubectl, and the Fleet CRDs. Ensure the version of the CRDs matches your installed Fleet CLI version.

Steps:

1. Create a minimal k3d cluster.
2. Merge the kubeconfig.
3. Install Fleet CRDs via a downloaded tarball.
4. Create necessary namespaces (fleet-local, fleet-default) and apply setup objects.

FLEET_VERSION=v0.14.3

# Create cluster
k3d cluster create fleet-test --no-lb --wait --timeout 120s
k3d kubeconfig merge fleet-test --kubeconfig-merge-default

# Install Fleet CRDs (use the same version as your fleet CLI)
curl -sL "https://github.com/rancher/fleet/releases/download/${FLEET_VERSION}/fleet-crd-${FLEET_VERSION#v}.tgz" \
  | tar -xz -O fleet-crd/templates/crds.yaml \
  | kubectl apply -f -

# Create namespaces and cluster objects
kubectl create namespace fleet-local
kubectl create namespace fleet-default
kubectl apply -f tests/setup-cluster.yaml