A Cloud Deploy execution environment is the environment in which
Cloud Deploy executes its render, predeploy, deploy, verify, and
postdeploy operations. The execution environment consists of the following
components:

- The [Cloud Build worker pool](https://docs.cloud.google.com/build/docs/private-pools/private-pools-overview)
  (default or private) in which Cloud Deploy executes render,
  predeploy, deploy, verify, and postdeploy operations

- The service account (default or alternate) that calls Cloud Deploy
  to perform these actions

- The storage location (default or alternate) for rendered manifests in
  Cloud Storage

- The Cloud Build timeout for operations (default or custom)

This document describes the default execution environment, service accounts, and
storage for Cloud Deploy, as well as why and how you can change these
defaults.

## Defaults

The following are the defaults that Cloud Deploy uses to run, to
execute rendering and deployment, and to store assets such as rendered manifests:

- Default worker pool

  By default, Cloud Deploy runs in the default Cloud Build
  worker pool. However, you can [configure Cloud Deploy to use a Cloud Build
  private worker pool](https://docs.cloud.google.com/deploy/docs/config-files#executionconfigs).

  For more details about worker pools, see the Cloud Build
  [Overview of default pools and private pools](https://docs.cloud.google.com/build/docs/private-pools/private-pools-overview#overview_of_default_pools_and_private_pools).
- Default execution service account

  By default, Cloud Deploy uses the [default Compute Engine
  service account](https://docs.cloud.google.com/deploy/docs/cloud-deploy-service-account#default_service_account).
- Default Cloud Deploy storage location

  This value is the Cloud Storage bucket where Cloud Deploy
  stores your rendered manifests. By default, Cloud Deploy creates
  a Cloud Storage bucket, in the same [region](https://docs.cloud.google.com/deploy/docs/regions)
  as the Cloud Deploy resources, taking the following form:

  `<location>.deploy-artifacts.<project ID>.appspot.com`
- Default Cloud Build timeout

  By default, Cloud Build has a timeout of 1 hour on operations it
  performs for Cloud Deploy. You can change that timeout in the
  execution environment specification in
  [target configuration](https://docs.cloud.google.com/deploy/docs/config-files#executionconfigs).
- Default verbosity for Skaffold, gcloud CLI, and kubectl

  By default, log levels for these tools are set to their respective defaults,
  typically `warn` or the equivalent. You can [change this](https://docs.cloud.google.com/deploy/docs/execution-environment#changing_log_level)
  to `debug` or the equivalent.

The sections that follow describe the circumstances under which you would change
any of these values, and links to instructions for doing so.

## About Cloud Build worker pools

The Cloud Deploy execution environment can use one of the following:

- The [Cloud Build default pool](https://docs.cloud.google.com/build/docs/private-pools/private-pools-overview)

  The default worker pool is a secure, hosted environment with access to the
  public internet. Render, deploy, predeploy, postdeploy, and verify operations
  are executed in that pool, isolated from other workloads.
- A private pool

  [Private worker pools](https://docs.cloud.google.com/build/docs/private-pools/private-pools-overview) are
  private, dedicated pools that can be customized more than the default worker
  pool. That customization can include the ability to access resources in a
  private network. Like the default worker pool, private worker pools are hosted
  and fully managed by Cloud Build. These pools can scale up or
  scale down to zero, with no infrastructure to set up, upgrade, or scale.

  The Cloud Build [Private pools overview](https://docs.cloud.google.com/build/docs/private-pools/private-pools-overview)
  describes default worker pools and private worker pools more thoroughly,
  including a table comparing their features.

> [!NOTE]
> **Note:** Cloud Build private worker pools are regional resources. Cloud Deploy lets you configure [targets](https://docs.cloud.google.com/deploy/docs/terminology#target) with private pools in other regions. This configuration makes it possible to share private worker pools among targets, and allows cross-regional dependencies.

## Changing the Cloud Deploy execution environment

You might change the Cloud Deploy execution environment under the
following circumstances:

- You want to [deploy to a private Google Kubernetes Engine cluster](https://docs.cloud.google.com/build/docs/private-pools/use-in-private-network#deploying-to-clusters)

- You want render, deploy, predeploy, postdeploy, or verify operations, or a
  combination of the five, to be performed in an environment that's isolated from
  other organizations.

- You want these operations to be performed in an environment that isn't
  connected to the public internet.

- You want separate environments for render and deploy.

- You want to use a dedicated service account with permissions that are more
  specific to your use than the permissions available in the default service
  account.

- You want to store rendered manifests in a location different from the default
  Cloud Storage bucket.

Configuration of all three parts of the execution environment (worker pool, service
account, and storage) is done per target, in
[each target's YAML configuration](https://docs.cloud.google.com/deploy/docs/config-files#target_definitions).

### Changing from the default pool to a private pool

You configure worker pools [per target](https://docs.cloud.google.com/deploy/docs/config-files#target_definitions),
so that the pool is used for `RENDER`, `DEPLOY`, `PREDEPLOY`, `POSTDEPLOY`, or
`VERIFY` (or a combination of the five) *for that target only*.

To use the default worker pool for both render and deploy operations, you don't
need to do anything.

> [!NOTE]
> **Note:** if you want to configure a target to use a private worker pool for either operation (`RENDER` or `DEPLOY`), but the default worker pool for the other, you must configure both. That is, you can't specify a private worker pool for `DEPLOY` but assume Cloud Deploy will perform rendering in the default pool.

The following is a sample target configuration that specifies a private worker
pool for `DEPLOY`, and the default worker pool for `RENDER`, `PREDEPLOY`,
`POSTDEPLOY` and `VERIFY`:

    executionConfigs:
    - usages:
      - DEPLOY
      privatePool:
        workerPool: "projects/p123/locations/us-central1/workerPools/wp123"
    - usages:
      - RENDER
      - PREDEPLOY
      - VERIFY
      - POSTDEPLOY

> [!NOTE]
> **Note:** if Cloud Deploy is running in a different project from the worker pool's project, make sure the [service agent](https://docs.cloud.google.com/deploy/docs/cloud-deploy-service-account#service_agent) has permission on the worker pool in that project. You can use either the `roles/cloudbuild.workerPoolUser` role or the `cloudbuild.workerpools.use` direct permission.

For more information about how to configure private pools for targets, see
[Delivery pipeline configuration documentation](https://docs.cloud.google.com/deploy/docs/config-files#executionconfigs).

### Changing from the default to custom execution service account

As with the worker pool, you can specify an alternate service account to use for
rendering or deploying (or both) per target. To do so, add the following line to
the target configuration, after the `workerPool` element:

`serviceAccount: "[name]@[project_name].iam.gserviceaccount.com"`

The specified service account must include the `clouddeploy.jobRunner` role, as
described in the [Cloud Deploy service accounts](https://docs.cloud.google.com/deploy/docs/cloud-deploy-service-account)
document.

See [Target definitions](https://docs.cloud.google.com/deploy/docs/config-files#target_definitions) for more
details on this configuration.

### Changing the storage location

To change the storage bucket from the Cloud Deploy default, add the
following line to the [target definition](https://docs.cloud.google.com/deploy/docs/config-files#target_definitions)
in the `workerPool` stanza:

`artifactStorage: "gs://[bucket_name]/[dir]"`

This configuration changes where the rendered manifests are stored, but does not
affect [where the rendering source is stored](https://docs.cloud.google.com/sdk/gcloud/reference/deploy/releases/create#--source).

### Changing the log level for Skaffold, gcloud CLI, and kubectl

To change the log level for Skaffold, gcloud CLI, and kubectl, from
their respective defaults to `debug` (or the equivalent), set `verbose` to
`true` in the execution configs. Here's an example:

    executionConfigs:
    - usages:
      - [RENDER | PREDEPLOY|  DEPLOY | VERIFY | POSTDEPLOY]
      workerPool:
      serviceAccount:
      artifactStorage:
      executionTimeout:
      verbose: true

## Using Cloud Deploy in a VPC Service Controls perimeter

Cloud Deploy supports [VPC Service Controls](https://docs.cloud.google.com/vpc-service-controls).

You can follow the [VPC Service Controls quickstart](https://docs.cloud.google.com/vpc-service-controls/docs/set-up-service-perimeter)
to set up a service perimeter.

### Limitations

- You must use a Cloud Build private worker pool for the target's
  execution environment---not the default worker pool.

- The project that contains the worker pool and the project that contains your
  Cloud Deploy resources must remain in the same VPC Service Controls
  security perimeter.

- Any GKE cluster you deploy to in the
  VPC Service Controls perimeter must be a private cluster.

  To set up a private pool for a private cluster, see
  [this tutorial](https://docs.cloud.google.com/build/docs/private-pools/accessing-private-gke-clusters-with-cloud-build-private-pools).

## What's next

- Find out more about [Cloud Deploy target configuration](https://docs.cloud.google.com/deploy/docs/config-files#target_definitions).

- Read about [Cloud Build private pools](https://docs.cloud.google.com/build/docs/private-pools/private-pools-overview).

- Read about [how Cloud Build uses VPC Service Controls](https://docs.cloud.google.com/build/docs/private-pools/using-vpc-service-controls).

- Learn about how Cloud Deploy uses [service accounts](https://docs.cloud.google.com/deploy/docs/cloud-deploy-service-account).

- [Access private GKE clusters with Cloud Build private pools](https://docs.cloud.google.com/architecture/accessing-private-gke-clusters-with-cloud-build-private-pools).