# Deploy an app to GKE using Cloud Deploy
This page shows you how to use Cloud Deploy to deliver a sample application
image named `nginx` to a sequence of two Google Kubernetes Engine clusters.
In this quickstart, you'll do the following:
1. Create the two clusters.
2. Create a [Skaffold](https://cloud.google.com/skaffold) configuration and a Kubernetes
manifest to specify the (pre-built) container image to deploy.
3. Define your Cloud Deploy delivery pipeline and deployment
[targets](https://docs.cloud.google.com/deploy/docs/terminology#target), which point to the two clusters.
4. Instantiate your delivery pipeline by creating a release, which automatically
deploys to the first target.
5. Promote the release to the second target.
6. View both rollouts in Google Cloud console.
## Before you begin
### Required roles
To ensure that the Cloud Deploy service account has the necessary
permissions to run Cloud Deploy operations and deploy to Cloud Run,
ask your administrator to grant the
following IAM roles to the Cloud Deploy service account on your project:
**Important:** You must grant these roles to the Cloud Deploy service account, *not* to your user account. Failure to grant the roles to the correct principal might result in permission errors.
- [Google Kubernetes Engine Developer](https://docs.cloud.google.com/iam/docs/roles-permissions/container#container.developer) (`roles/container.developer`)
- [IAM Service Account User](https://docs.cloud.google.com/iam/docs/roles-permissions/iam#iam.serviceAccountUser) (`roles/iam.serviceAccountUser`)
- [Cloud Deploy Job Runner](https://docs.cloud.google.com/iam/docs/roles-permissions/clouddeploy#clouddeploy.jobRunner) (`roles/clouddeploy.jobRunner`)
For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access).
Your administrator might also be able to give the Cloud Deploy service account
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).
## Create your Google Kubernetes Engine clusters
Create two clusters: `qsdev` and `qsprod`, with default settings. The clusters'
Kubernetes API endpoints must be network-reachable from the public internet.
GKE clusters are externally accessible by default.
gcloud container clusters create-auto quickstart-cluster-qsdev --project=PROJECT_ID --region=us-central1 && gcloud container clusters create-auto quickstart-cluster-qsprod --project=PROJECT_ID --region=us-central1
## Prepare your Skaffold configuration and Kubernetes manifest
Cloud Deploy uses [Skaffold](https://docs.cloud.google.com/deploy/docs/using-skaffold) to provide the details for
what to deploy and how to deploy it properly for your separate
[targets](https://docs.cloud.google.com/deploy/docs/terminology#target).
In this quickstart, you create a `skaffold.yaml` file, which identifies the
Kubernetes manifest to be used to deploy the sample app.
1. Open a terminal window.
2. Create a new directory, named `deploy-gke-quickstart` and navigate into it.
mkdir deploy-gke-quickstart
cd deploy-gke-quickstart
3. Create a file named `skaffold.yaml` with the following contents:
apiVersion: skaffold/v4beta7
kind: Config
manifests:
rawYaml:
- k8s-*
deploy:
kubectl: {}
This file is a minimal Skaffold config, identifying your manifest. For this
quickstart, you create the file. But you can also
[have Cloud Deploy create one for you](https://docs.cloud.google.com/deploy/docs/using-skaffold/getting-started-skaffold#have_generate_your_skaffoldyaml),
for simple, non-production applications.
See the [`skaffold.yaml` reference](https://skaffold.dev/docs/references/yaml/)
for more information about this file.
4. Create a file named `k8s-pod.yaml`, with the following contents:
apiVersion: v1
kind: Pod
metadata:
name: getting-started
spec:
containers:
- name: nginx
image: my-app-image
This file is a basic Kubernetes [manifest](https://kubernetes.io/docs/reference/glossary/?fundamental=true#term-manifest),
which is applied to the cluster to deploy the application. The container
image to deploy is set here as a placeholder, `my-app-image`, which is
replaced with the specific image when you
[create the release](https://docs.cloud.google.com/deploy/docs/deploy-app-gke#create_a_release).
> [!NOTE]
> **Note:** If you want to use different manifests per target, read [this article
> about managing manifests](https://docs.cloud.google.com/deploy/docs/using-skaffold/managing-manifests) to find out more about using Skaffold profiles.
## Create your delivery pipeline and targets
You can define your pipeline and targets in one file or in separate files. In
this quickstart, you create a single file.
1. In the `deploy-gke-quickstart` directory, create a new file: `clouddeploy.yaml`,
with the following contents:
apiVersion: deploy.cloud.google.com/v1
kind: DeliveryPipeline
metadata:
name: my-gke-demo-app-1
description: main application pipeline
serialPipeline:
stages:
- targetId: qsdev
profiles: []
- targetId: qsprod
profiles: []
---
apiVersion: deploy.cloud.google.com/v1
kind: Target
metadata:
name: qsdev
description: development cluster
gke:
cluster: projects/PROJECT_ID/locations/us-central1/clusters/quickstart-cluster-qsdev
---
apiVersion: deploy.cloud.google.com/v1
kind: Target
metadata:
name: qsprod
description: production cluster
gke:
cluster: projects/PROJECT_ID/locations/us-central1/clusters/quickstart-cluster-qsprod
2. Register your pipeline and targets with the Cloud Deploy service:
gcloud deploy apply --file=clouddeploy.yaml --region=us-central1 --project=PROJECT_ID
You now have a pipeline, with targets, ready to deploy your application to
your first target.
3. Confirm your pipeline and targets:
In the Google Cloud console, navigate to the Cloud Deploy
**Delivery pipelines** page to view of list of your available delivery
pipelines.
[Open the Delivery pipelines page](https://console.cloud.google.com/deploy/delivery-pipelines)
The delivery pipeline you just created is shown, and the two targets are
listed in the **Targets** column.
## Create a release
A release is the central Cloud Deploy resource representing the
changes being deployed. The delivery pipeline defines the lifecycle of that
release. See
[Cloud Deploy service architecture](https://docs.cloud.google.com/deploy/docs/architecture#how_they_fit_together_to_deliver_your_release)
for details about that lifecycle.
Run the following command from the `deploy-gke-quickstart` directory to create a
`release` resource that represents the container image to deploy:
gcloud deploy releases create test-release-001 \
--project=PROJECT_ID \
--region=us-central1 \
--delivery-pipeline=my-gke-demo-app-1 \
--images=my-app-image=gcr.io/google-containers/nginx@sha256:f49a843c290594dcf4d193535d1f4ba8af7d56cea2cf79d1e9554f077f1e7aaa
Notice the
[`--images=` flag](https://docs.cloud.google.com/sdk/gcloud/reference/deploy/releases/create#--images), which
you use to replace the placeholder (`my-app-image`) in the
[manifest](https://docs.cloud.google.com/deploy/docs/deploy-app-gke#prepare_your_skaffold_configuration_and_kubernetes_manifest) with
the specific, SHA-qualified image. Google recommends that you templatize your
manifests this way, and that you use SHA-qualified image names at release
creation.
As with all releases (unless they include `--disable-initial-rollout`),
Cloud Deploy automatically creates a
[rollout](https://docs.cloud.google.com/deploy/docs/terminology#rollout) resource too. The application is
automatically deployed into the first target in the progression.
## Promote the release
> [!NOTE]
> **Note:** after you create the release, you might need wait a few minutes before you continue with this step.
1. From the **Delivery pipelines** page, click the `my-gke-demo-app-1` pipeline.
[Open the Delivery pipelines page](https://console.cloud.google.com/deploy/delivery-pipelines)
The Delivery pipeline details page shows a graphical representation of your
delivery pipeline's progress. In this case, it shows that the release was
deployed to the `qsdev` target.
2. On the first target in the delivery pipeline visualization, click **Promote**.
The **Promote release** dialog is shown. It shows the details of the target
you're promoting to.
3. Click **Promote**.
The release is now queued for deployment into `qsprod`. When deployment is
complete, the delivery pipeline visualization shows it as deployed:
## View the results in Google Cloud console
1. In the Google Cloud console, navigate to the Cloud Deploy
**Delivery pipelines** page to view your **my-gke-demo-app-1** delivery pipeline.
[Open the Delivery pipelines page](https://console.cloud.google.com/deploy/delivery-pipelines)
2. Click the name of your delivery pipeline "my-gke-demo-app-1".
The pipeline visualization shows the app's progress through the pipeline.
And your release is listed on the **Releases** tab under **Delivery pipeline
details**.
3. Click the release name, `test-release-001`.
Your rollouts appear under **Rollouts**. You can click a rollout to view its
details, including the deployment log.
## Clean up
To avoid incurring charges to your Google Cloud account for
the resources used on this page, follow these steps.
1. Delete the `qsdev` cluster:
gcloud container clusters delete quickstart-cluster-qsdev --region=us-central1 --project=PROJECT_ID
2. Delete the `qsprod` cluster:
gcloud container clusters delete quickstart-cluster-qsprod --region=us-central1 --project=PROJECT_ID
3. Delete the delivery pipeline, targets, release and rollouts:
gcloud deploy delete --file=clouddeploy.yaml --force --region=us-central1 --project=PROJECT_ID
4. Delete the Cloud Storage buckets that Cloud Deploy created.
One ends with `_clouddeploy`, and the other is `[region].deploy-artifacts.[project].appspot.com`.
[Open the Cloud Storage browser page](https://console.cloud.google.com/storage/browser)
That's it, you completed this quickstart!
## What's next
- [Learn more about Cloud Deploy](https://docs.cloud.google.com/deploy/docs/overview).
- [Learn the basics of deploying applications](https://docs.cloud.google.com/deploy/docs/deploying-application).
- Learn how to [manage your manifests](https://docs.cloud.google.com/deploy/docs/skaffold).
- [Learn how to combine Google Cloud CI/CD tools to develop and deliver
software effectively to GKE](https://cloud.google.com/architecture/app-development-and-delivery-with-cloud-code-gcb-cd-and-gke).