Creating a Deployment

To deploy workloads onto downstream clusters, first create a Git repo, then create a GitRepo resource and apply it.

This tutorial uses the fleet-examples repository.

Creating a Deployment - 图1note

For more details on how to structure the repository and configure the deployment of each bundle see GitRepo Contents. For more details on the options that are available per Git repository see Adding a GitRepo.

Single-Cluster Examples

All examples will deploy content to clusters with no per-cluster customizations. This is a good starting point to understand the basics of structuring Git repos for Fleet.

  • Helm
  • Helm Multi Chart
  • Helm & Kustomize
  • Kustomize
  • Manifests

An example using Helm. We are deploying the helm example to the local cluster.

The repository contains a helm chart and an optional fleet.yaml to configure the deployment:

fleet.yaml

  1. namespace: fleet-helm-example
  3. # Custom helm options
  4. helm:
  5.   # The release name to use. If empty a generated release name will be used
  6.   releaseName: guestbook
  8.   # The directory of the chart in the repo.  Also any valid go-getter supported
  9.   # URL can be used there is specify where to download the chart from.
  10.   # If repo below is set this value if the chart name in the repo
  11.   chart: ""
  13.   # An https to a valid Helm repository to download the chart from
  14.   repo: ""
  16.   # Used if repo is set to look up the version of the chart
  17.   version: ""
  19.   # Force recreate resource that can not be updated
  20.   force: false
  22.   # How long for helm to wait for the release to be active. If the value
  23.   # is less that or equal to zero, we will not wait in Helm
  24.   timeoutSeconds: 0
  26.   # Custom values that will be passed as values.yaml to the installation
  27.   values:
  28.     replicas: 2

To create the deployment, we apply the custom resource to the upstream cluster. The fleet-local namespace contains the local cluster resource. The local fleet-agent will create the deployment in the fleet-helm-example namespace.

  1. kubectl apply -n fleet-local -f - <<EOF
  2. kind: GitRepo
  3. apiVersion: fleet.cattle.io/v1alpha1
  4. metadata:
  5.   name: helm
  6. spec:
  7.   repo: https://github.com/rancher/fleet-examples
  8.   paths:
  9.   - single-cluster/helm
  10. EOF

An example deploying multiple charts from a single repo. This is similar to the previous example, but will deploy three helm charts from the sub folders, each configured by its own fleet.yaml.

  1. kubectl apply -n fleet-local -f - <<EOF
  2. kind: GitRepo
  3. apiVersion: fleet.cattle.io/v1alpha1
  4. metadata:
  5.   name: helm
  6. spec:
  7.   repo: https://github.com/rancher/fleet-examples
  8.   paths:
  9.   - single-cluster/helm-multi-chart
  10. EOF

An example using Kustomize to modify a third party Helm chart. It will deploy the Kubernetes sample guestbook application as packaged as a Helm chart downloaded from a third party source and will modify the helm chart using Kustomize. The app will be deployed into the fleet-helm-kustomize-example namespace.

  1. kubectl apply -n fleet-local -f - <<EOF
  2. kind: GitRepo
  3. apiVersion: fleet.cattle.io/v1alpha1
  4. metadata:
  5.   name: helm
  6. spec:
  7.   repo: https://github.com/rancher/fleet-examples
  8.   paths:
  9.   - single-cluster/helm-kustomize
  10. EOF

An example using Kustomize.

Note that the fleet.yaml has a kustomize: key to specify the path to the required kustomization.yaml:

fleet.yaml

  1. kustomize:
  2.   # To use a kustomization.yaml different from the one in the root folder
  3.   dir: ""
  1. kubectl apply -n fleet-local -f - <<EOF
  2. kind: GitRepo
  3. apiVersion: fleet.cattle.io/v1alpha1
  4. metadata:
  5.   name: helm
  6. spec:
  7.   repo: https://github.com/rancher/fleet-examples
  8.   paths:
  9.   - single-cluster/kustomize
  10. EOF

An example using raw Kubernetes YAML.

  1. kubectl apply -n fleet-local -f - <<EOF
  2. kind: GitRepo
  3. apiVersion: fleet.cattle.io/v1alpha1
  4. metadata:
  5.   name: helm
  6. spec:
  7.   repo: https://github.com/rancher/fleet-examples
  8.   paths:
  9.   - single-cluster/manifests
  10. EOF

Multi-Cluster Examples

The examples below will deploy a multi git repo to multiple clusters at once and configure the app differently for each target.

  • Helm
  • Helm External
  • Helm & Kustomize
  • Kustomize
  • Manifests

An example using Helm. We are deploying the helm example and customizing it per target cluster

The repository contains a helm chart and an optional fleet.yaml to configure the deployment. The fleet.yaml is used to configure different deployment options, depending on the cluster’s labels:

fleet.yaml

  1. namespace: fleet-mc-helm-example
  2. targetCustomizations:
  3. - name: dev
  4.   helm:
  5.     values:
  6.       replication: false
  7.   clusterSelector:
  8.     matchLabels:
  9.       env: dev
  11. - name: test
  12.   helm:
  13.     values:
  14.       replicas: 3
  15.   clusterSelector:
  16.     matchLabels:
  17.       env: test
  19. - name: prod
  20.   helm:
  21.     values:
  22.       serviceType: LoadBalancer
  23.       replicas: 3
  24.   clusterSelector:
  25.     matchLabels:
  26.       env: prod

To create the deployment, we apply the custom resource to the upstream cluster. The fleet-default namespace, by default, contains the downstream cluster resources. The chart will be deployed to all clusters in the fleet-default namespace, which have a labeled cluster resources that matches any entry under targets:.

gitrepo.yaml

  1. kind: GitRepo
  2. apiVersion: fleet.cattle.io/v1alpha1
  3. metadata:
  4.   name: helm
  5.   namespace: fleet-default
  6. spec:
  7.   repo: https://github.com/rancher/fleet-examples
  8.   paths:
  9.   - multi-cluster/helm
  10.   targets:
  11.   - name: dev
  12.     clusterSelector:
  13.       matchLabels:
  14.         env: dev
  16.   - name: test
  17.     clusterSelector:
  18.       matchLabels:
  19.         env: test
  21.   - name: prod
  22.     clusterSelector:
  23.       matchLabels:
  24.         env: prod

By applying the gitrepo resource to the upstream cluster, fleet will start to monitor the repository and create deployments:

  1. kubectl apply -n fleet-default -f gitrepo.yaml

An example using a Helm chart that is downloaded from a third party source and customizing it per target cluster. The customization is similar to the previous example.

To create the deployment, we apply the custom resource to the upstream cluster. The fleet-default namespace, by default, contains the downstream cluster resources. The chart will be deployed to all clusters in the fleet-default namespace, which have a labeled cluster resources that matches any entry under targets:.

gitrepo.yaml

  1. kind: GitRepo
  2. apiVersion: fleet.cattle.io/v1alpha1
  3. metadata:
  4.   name: helm-external
  5.   namespace: fleet-default
  6. spec:
  7.   repo: https://github.com/rancher/fleet-examples
  8.   paths:
  9.   - multi-cluster/helm-external
  10.   targets:
  11.   - name: dev
  12.     clusterSelector:
  13.       matchLabels:
  14.         env: dev
  16.   - name: test
  17.     clusterSelector:
  18.       matchLabels:
  19.         env: test
  21.   - name: prod
  22.     clusterSelector:
  23.       matchLabels:
  24.         env: prod

By applying the gitrepo resource to the upstream cluster, fleet will start to monitor the repository and create deployments:

  1. kubectl apply -n fleet-default -f gitrepo.yaml

An example using kustomize to modify a third party Helm chart. It will deploy the Kubernetes sample guestbook application as packaged as a Helm chart downloaded from a third party source and will modify the helm chart using Kustomize. The app will be deployed into the fleet-helm-kustomize-example namespace.

The application will be customized as follows per environment:

  • Dev clusters: Only the redis leader is deployed and not the followers.
  • Test clusters: Scale the front deployment to 3
  • Prod clusters: Scale the front deployment to 3 and set the service type to LoadBalancer

The fleet.yaml is used to control which overlays are used, depending on the cluster’s labels:

fleet.yaml

  1. namespace: fleet-mc-kustomize-example
  2. targetCustomizations:
  3. - name: dev
  4.   clusterSelector:
  5.     matchLabels:
  6.       env: dev
  7.   kustomize:
  8.     dir: overlays/dev
  10. - name: test
  11.   clusterSelector:
  12.     matchLabels:
  13.       env: test
  14.   kustomize:
  15.     dir: overlays/test
  17. - name: prod
  18.   clusterSelector:
  19.     matchLabels:
  20.       env: prod
  21.   kustomize:
  22.     dir: overlays/prod

To create the deployment, we apply the custom resource to the upstream cluster. The fleet-default namespace, by default, contains the downstream cluster resources. The chart will be deployed to all clusters in the fleet-default namespace, which have a labeled cluster resources that matches any entry under targets:.

gitrepo.yaml

  1. kind: GitRepo
  2. apiVersion: fleet.cattle.io/v1alpha1
  3. metadata:
  4.   name: helm-kustomize
  5.   namespace: fleet-default
  6. spec:
  7.   repo: https://github.com/rancher/fleet-examples
  8.   paths:
  9.   - multi-cluster/helm-kustomize
  10.   targets:
  11.   - name: dev
  12.     clusterSelector:
  13.       matchLabels:
  14.         env: dev
  16.   - name: test
  17.     clusterSelector:
  18.       matchLabels:
  19.         env: test
  21.   - name: prod
  22.     clusterSelector:
  23.       matchLabels:
  24.         env: prod

By applying the gitrepo resource to the upstream cluster, fleet will start to monitor the repository and create deployments:

  1. kubectl apply -n fleet-default -f gitrepo.yaml

An example using Kustomize and customizing it per target cluster.

The customization in fleet.yaml is identical to the “Helm & Kustomize” example.

To create the deployment, we apply the custom resource to the upstream cluster. The fleet-default namespace, by default, contains the downstream cluster resources. The chart will be deployed to all clusters in the fleet-default namespace, which have a labeled cluster resources that matches any entry under targets:.

  1. kubectl apply -n fleet-default -f - <<EOF
  2. kind: GitRepo
  3. apiVersion: fleet.cattle.io/v1alpha1
  4. metadata:
  5.   name: kustomize
  6.   namespace: fleet-default
  7. spec:
  8.   repo: https://github.com/rancher/fleet-examples
  9.   paths:
  10.   - multi-cluster/kustomize
  11.   targets:
  12.   - name: dev
  13.     clusterSelector:
  14.       matchLabels:
  15.         env: dev
  17.   - name: test
  18.     clusterSelector:
  19.       matchLabels:
  20.         env: test
  22.   - name: prod
  23.     clusterSelector:
  24.       matchLabels:
  25.         env: prod
  26. EOF

By applying the gitrepo resource to the upstream cluster, fleet will start to monitor the repository and create deployments:

An example using raw Kubernetes YAML and customizing it per target cluster. The application will be customized as follows per environment:

  • Dev clusters: Only the redis leader is deployed and not the followers.
  • Test clusters: Scale the front deployment to 3
  • Prod clusters: Scale the front deployment to 3 and set the service type to LoadBalancer

The fleet.yaml is used to control which ‘yaml’ overlays are used, depending on the cluster’s labels:

fleet.yaml

  1. namespace: fleet-mc-manifest-example
  2. targetCustomizations:
  3. - name: dev
  4.   clusterSelector:
  5.     matchLabels:
  6.       env: dev
  7.   yaml:
  8.     overlays:
  9.     # Refers to overlays/noreplication folder
  10.     - noreplication
  12. - name: test
  13.   clusterSelector:
  14.     matchLabels:
  15.       env: test
  16.   yaml:
  17.     overlays:
  18.     # Refers to overlays/scale3 folder
  19.     - scale3
  21. - name: prod
  22.   clusterSelector:
  23.     matchLabels:
  24.       env: prod
  25.   yaml:
  26.     # Refers to overlays/servicelb, scale3 folders
  27.     overlays:
  28.     - servicelb
  29.     - scale3

To create the deployment, we apply the custom resource to the upstream cluster. The fleet-default namespace, by default, contains the downstream cluster resources. The chart will be deployed to all clusters in the fleet-default namespace, which have a labeled cluster resources that matches any entry under targets:.

To create the deployment, we apply the custom resource to the upstream cluster. The fleet-default namespace, by default, contains the downstream cluster resources. The chart will be deployed to all clusters in the fleet-default namespace, which have a labeled cluster resources that matches any entry under targets:.

gitrepo.yaml

  1. kind: GitRepo
  2. apiVersion: fleet.cattle.io/v1alpha1
  3. metadata:
  4.   name: manifests
  5.   namespace: fleet-default
  6. spec:
  7.   repo: https://github.com/rancher/fleet-examples
  8.   paths:
  9.   - multi-cluster/manifests
  10.   targets:
  11.   - name: dev
  12.     clusterSelector:
  13.       matchLabels:
  14.         env: dev
  16.   - name: test
  17.     clusterSelector:
  18.       matchLabels:
  19.         env: test
  21.   - name: prod
  22.     clusterSelector:
  23.       matchLabels:
  24.         env: prod
  1. kubectl apply -n fleet-default -f gitrepo.yaml