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
RootSyncorRepoSyncobject.
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
FleetPackageAPI is available only in theus-central1region. You can still deploy to clusters in different regions, but you must set up Cloud Build and configure the gcloud CLI inus-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/my-service-account@my-project.iam.gserviceaccount.com
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/my-service-account@my-project.iam.gserviceaccount.com
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/my-service-account@my-project.iam.gserviceaccount.com
path: deployments
variantsPattern: "*.yaml"
rolloutStrategy:
rolling:
maxConcurrent: 2
target:
fleet:
project: projects/my-project
variantSelector:
variantNameTemplate: ${membership.labels['nginx-size']}