This tutorial teaches you how to use a fleet package to deploy Kubernetesresource manifests across a fleet of clusters. Using GitOps tools likeConfig Sync's fleet packages can help you scale up configuration managementacross large numbers of clusters.

In this tutorial, you complete the following tasks:

• Connect a Git repository to Cloud Build
• Create and register clusters to a fleet
• Install Config Sync as a fleet default
• Deploy resources from your repository to your fleet of clusters

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

Toinitialize the gcloud CLI, run the following command:

gcloudinit

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects createPROJECT_ID

  ReplacePROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set projectPROJECT_ID

  ReplacePROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the GKE, Config Delivery (fleet packages), Cloud Build, Developer Connect APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

gcloudservicesenablecontainer.googleapis.com  configdelivery.googleapis.com  cloudbuild.googleapis.com  developerconnect.googleapis.com

Install the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

Toinitialize the gcloud CLI, run the following command:

gcloudinit

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects createPROJECT_ID

  ReplacePROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set projectPROJECT_ID

  ReplacePROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the GKE, Config Delivery (fleet packages), Cloud Build, Developer Connect APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

gcloudservicesenablecontainer.googleapis.com  configdelivery.googleapis.com  cloudbuild.googleapis.com  developerconnect.googleapis.com

1. Create, or have access to, a GitHub account.

Costs

In this document, you use the following billable components of Google Cloud:

• GKE
• Cloud Build

To generate a cost estimate based on your projected usage, use thepricing calculator.

Connect to Git

Your Git repository contains the resources that you want to deploy across afleet. To deploy those resources with a fleet package, you must connect your Gitrepository to Cloud Build.

Create your Git repository

This tutorial uses GitHub as the Git provider. To create a new GitHub repository,complete the following steps:

1. In your web browser, openGitHub.

2. If needed, sign in to your GitHub account. If you have access to otherorganizations or teams on GitHub, make sure that you're creating therepository with your personal account.

3. From the toolbar, selectAddadd and thenclickNew repository.

4. Typefleet-package-tutorial as the name of the repository.

5. KeepPublic selected as the repository visibility.

6. SelectCreate repository.

Connect the repository to Cloud Build

Config Sync's fleet package service uses Cloud Build to sync andfetch the Kubernetes resources from your Git repository.

To connect your GitHub repository to Cloud Build, complete the followingsteps:

1. Open the Cloud Build page in the Google Cloud console, and then selectRepositories.

   Open the Repositories page

2. Ensure that you are on the 2nd genRepositories page. If needed, selectView repositories (2nd gen).

3. ClickCreate host connection.

4. In theRegion menu, selectus-central1 (Iowa) as your region.

   Caution: You can select onlyus-central1 (Iowa) as the region. TheCloud Build connection and fleet package must be in the same region.Fleet packages (Preview) supports onlyus-central1.

5. In theName field, typefleet-package-quickstart-connection as thename for your connection.

6. ClickConnect.

7. If this is your first time connecting Cloud Build to your GitHubaccount, complete the following steps:

   1. Accept the request for your GitHub OAuth token. The token is stored inSecret Manager for use with Cloud Build GitHub Connection.ClickContinue.
   2. Install Cloud Build into your GitHub repository. SelectInstallin a new account.
   3. In the new GitHub window that opens, select the GitHub account in whichyou created the fork of Cymbal Bank earlier. In a production environment,you might select other accounts or repositories that you have delegatedaccess to.
   4. Follow any authentication prompts to confirm your identity in GitHub.
   5. In the GitHub window for Cloud Build repository access, chooseOnly select repositories.
   6. From the drop-down menu that lists repositories, select yourfleet-package-tutorial repository.
   7. ClickSave.

8. In the Cloud Build page in the Google Cloud console, clickLinkrepository to connect a new Git repository to Cloud Build.

9. In theConnection menu, selectfleet-package-quickstart-connection.

10. In theRepositories menu, select yourfleet-package-tutorialrepository.

11. SelectLink.

Set up your fleet

In this section, you set up your fleet by creating clusters, registering them toa fleet, and installing Config Sync as a fleet package.

Create clusters

To demonstrate how you can use fleet packages to deploy resources acrossmultiple clusters, this tutorial shows you how to create two clusters.

1. In the Google Cloud console, go to theFeature Manager page.

   Go to Feature Manager

2. In theConfig Sync pane, clickConfigure.

3. ClickCustomize fleet settings. In the dialog that appears, selectthe version of Config Sync to install.

4. ClickConfigure.

5. In theConfiguring fleet settings confirmation dialog, clickConfirm. If you haven't previously enabled Config Sync, clickingConfirm also enables theanthosconfigmanagement.googleapis.com API.

6. In theClusters in the fleet table, select both clusters and then ClickSync to fleet settings. This installs Config Sync on both yourClusters with the settings that you configured.

   It can take a few minutes for the clusters to sync. You can proceed withthe next steps when Config Sync shows asInstalled.

Set up a service account for Cloud Build

To create the service account and grant the required permissions toCloud Build, complete the following steps:

1. Create the service account:

   gcloudiamservice-accountscreate"quickstart-service-account"

2. Grant the service account permission to fetch resources from your Gitrepository by adding an IAM policy binding for the ResourceBundle Publisher role:

   gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--member="serviceAccount:quickstart-service-account@PROJECT_ID.iam.gserviceaccount.com"\--role='roles/configdelivery.resourceBundlePublisher'

   If prompted, selectNone as the condition for the policy.

3. Grant the service account permission to write logs by adding anIAM policy binding for theLogs Writer role:

   gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--member="serviceAccount:quickstart-service-account@PROJECT_ID.iam.gserviceaccount.com"\--role='roles/logging.logWriter'

   If prompted, selectNone as the condition for the policy.

Deploy resources across your fleet

In this tutorial, you add a Kubernetes manifest with an nginx deployment to yourGit repository, publish a release, and then create a fleet package to deploy thenginx application.

Commit a Kubernetes manifest to your repository

To add your resources to GitHub and publish a release, complete the following steps:

1. In a web browser window of your GitHub repository, clickAdd file and thenCreate new file.

2. Name your filedeployment.yaml and paste the following contents into it:

   apiVersion:apps/v1kind:Deploymentmetadata:name:nginx-deploymentspec:replicas:3selector:matchLabels:app:nginxtemplate:metadata:labels:app:nginxspec:containers:-image:nginx:1.14.2name:nginxports:-containerPort:80

3. ClickCommit changes...

4. In the confirmation dialog, keepCommit directly to themain branchselected and then clickCommit changes.

5. On the main page of your repository, selectReleases from the sidebar.

6. At the top of the page, chooseDraft a new release.

7. Select theChoose a tag menu and typev1.0.0 as the tag. ClickCreate new tag.

8. ClickPublish release.

Deploy a resource to clusters with a fleet package

To deploy the new resource, create a new fleet package:

1. This fleet package targets all of the clusters in your fleet since itdoesn't contain a selector field. This also means any future clusters addedto the fleet will have the nginx deployment automatically added.

   In your Cloud Shell, create a file namedfleet-package.yaml with thefollowing content:

   resourceBundleSelector:cloudBuildRepository:name:projects/PROJECT_ID/locations/us-central1/connections/fleet-package-quickstart-connection/repositories/REPOSITORY_NAMEtag:v1.0.0serviceAccount:projects/PROJECT_ID/serviceAccounts/quickstart-service-account@PROJECT_ID.iam.gserviceaccount.compath:target:fleet:project:projects/PROJECT_IDrolloutStrategy:rolling:maxConcurrent:1

   ReplaceREPOSITORY_NAME with the repository namefrom Cloud Build. This is usually in the formatUSERNAME-REPOSITORY_NAME.

2. Create the fleet package to start the rollout:

   gcloudcontainerfleetpackagescreatefp-nginx\--source=fleet-package.yaml\--project=PROJECT_ID

3. Verify that the fleet package was created:

   gcloudcontainerfleetpackageslist

   You can click the link provided to view the streaming logs for theCloud Build job.

   The fleet package starts rolling out the Kubernetes resources across yourfleet.

4. In the Google Kubernetes Engine page of the Google Cloud console, go to theWorkloadspage to see an aggregated view of the workloads that are being deployed onall your GKE clusters:

   Open the Workloads page

   It can take a few minutes for the workloads to become available. You mightalso notice availability errors while Autopilotadjusts your resource requests for the new deployment.

   Notice how, becausemaxConcurrent: is set to1 in your fleet packagedefinition, the fleet package API waits until thenginx-deployment is fullydeployed on one cluster before starting the deployment to the second cluster.If you changed the roll-out strategy tomaxConcurrent: 2 or higher, theresources would deploy to both clusters simultaneously.

   After a few minutes, you will see two new workloads for thenginx-deployment onboth your clusters. You might need to refresh the page.

You can continue to explore different deployment strategies with fleet packages.For example, you could add a new cluster to your fleet to observe that yourworkload gets automatically deployed to that new cluster. For more informationabout deployment strategies and variations, seeDeploy fleet packages.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, delete the Google Cloud project with the resources.

Caution: Deleting a project has the following effects:
• Everything in the project is deleted. If you used an existing project for the tasks in this document, when you delete it, you also delete any other work you've done in the project.
• Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as anappspot.com URL, delete selected resources inside the project instead of deleting the whole project.

If you plan to explore multiple architectures, tutorials, or quickstarts, reusing projects can help you avoid exceeding project quota limits.

Delete a Google Cloud project:

gcloud projects deletePROJECT_ID

You can delete your repository by completing the following steps:

1. In a web browser window of your GitHub repository, under yourrepository name, clickSettings.

2. On the General settings page (which is selected by default), go to theDanger Zone section and clickDelete this repository.

3. ClickI want to delete this repository.

4. Read the warnings and clickI have read and understand these effects.

5. To verify that you're deleting the correct repository, in the text field,type the name of your repository.

6. ClickDelete this repository.

What's next

• Learn more aboutfleet packages.
• Learn how todeploy fleet packages.
• Try theScalable apps tutorial app tutorial, a series of tutorials thatteaches you how to deploy, run, and manage modern application environments onGKE. It includes theCentralize change management tutorial which explores scaling upconfiguration changes with fleet packages.