About fleet packages

This page explains fleet packages, the FleetPackage API, and how they relate to Config Sync.

A FleetPackage is a declarative API that lets you manage packages across a fleet. A fleet package is a set of Kubernetes YAML manifests that define cluster configuration. By using fleet packages, you can deploy packages through an all-at-once or progressive rollout to clusters that are registered to your fleet.

You define each FleetPackage object once, and then you can update that package with a new revision. When you apply a new revision, the fleet package service picks up those changes and deploys them to your clusters.

Benefits

Use fleet packages to deploy Kubernetes resources across clusters that are registered to a fleet. After you create and apply a fleet package, the fleet package automatically deploys the Kubernetes configuration files in the Git repository to the new cluster. Fleet packages builds upon Config Sync's benefits like automatic drift correction, and offers the following unique advantages:

• Automate resource rollout: After you set up a fleet package, the Kubernetes resources it points to are automatically deployed by the fleet package service on all clusters.

• Configure new clusters automatically: If you configure a fleet package and then later add new clusters to a fleet, any resources defined by the fleet package are automatically deployed to the new cluster.

• Manage Kubernetes configuration at scale: Instead of managing clusters one-by-one, use fleet packages to deploy resources to an entire fleet of clusters.

• Minimize the impact of incorrect changes: Choose a maximum number of clusters to deploy resources to at once. You can closely monitor the changes to each cluster to ensure that incorrect changes don't impact your entire fleet.

• Simplify Config Sync configuration: Fleet packages uses Cloud Build to authenticate to Git, meaning you authenticate once per project instead of once per RootSync or RepoSync object.

You might prefer to use Config Sync with RootSync or RepoSync objects instead of fleet packages if one or more of the following scenarios applies to you:

• You manage a small number of clusters.

• You need more control over how resources are deployed to your clusters, beyond what the fleet package API provides with labels and variants.

Requirements and limitations

• Only Git repositories are supported as the source of truth when configuring a fleet package.

• The Kubernetes resources stored in Git must represent the end state of the resource. Additional overlays to transform the resource stored in Git are not supported. For more information about the differences in these resources, see Best practice: Create WET repositories.

• The FleetPackage API is available only in the us-central1 region. You can still deploy to clusters in different regions, but you must set up Cloud Build and configure the gcloud CLI in us-central1.

Architecture

You can use the FleetPackage API to deploy Kubernetes manifests to a fleet of clusters. The FleetPackage API uses Cloud Build to sync and fetch Kubernetes resources from your Git repository. The fleet package service then deploys those resources to your clusters.

Example use cases

You can use fleet packages to deploy resources from a Git repository to your entire fleet of clusters. You can also configure your fleet package to control how, where, and what type of resources are deployed.

The following section shows examples of different FleetPackage configurations. For more detailed information about applying fleet packages, see Deploy fleet packages.

Deployment to all clusters in a fleet

The following FleetPackage uses a rolling strategy to deploy Kubernetes resources to three clusters at a time and targets all clusters in a fleet:

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    serviceAccount: projects/my-project/serviceAccounts/[e-mail]
target:
  fleet:
    project: projects/my-project
rolloutStrategy:
  rolling:
    maxConcurrent: 3

Deployment to a subset of clusters

The following FleetPackage uses a label selector to deploy Kubernetes resources only to clusters with the membership label country that matches "us" in the fleet:

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    serviceAccount: projects/my-project/serviceAccounts/[e-mail]
target:
  fleet:
    project: projects/my-project
    selector:
      matchLabels:
        country: "us"
rolloutStrategy:
  rolling:
    maxConcurrent: 3

Deployment of variant resources to a cluster

For this example, in your Git repository, you have a folder named "deployments" that contains two different deployment specs:

Replicas: 3

    # small.yaml
    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
    

Replicas: 10

    # large.yaml
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: nginx-deployment
      labels:
        app: nginx
    spec:
      replicas: 10
      selector:
        matchLabels:
          app: nginx
      template:
        metadata:
          labels:
            app: nginx
        spec:
          containers:
          - name: nginx
            image: nginx:1.14.2
            ports:
            - containerPort: 80
    

You can use variants to deploy either the "small" or "large" deployments to different clusters. Each cluster has a label of either nginx-size=small or nginx-size=large.

The FleetPackage in this example would resemble the following:

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    serviceAccount: projects/my-project/serviceAccounts/[e-mail]
    path: deployments
    variantsPattern: "*.yaml"
rolloutStrategy:
  rolling:
    maxConcurrent: 2
target:
  fleet:
    project: projects/my-project
variantSelector:
  variantNameTemplate: ${membership.labels['nginx-size']}

What's next

Deploy fleet packages