This page describes the best practices for creating deployments using Google Cloud Deployment Manager. This page is designed for users who are familiar with Deployment Manager; this page will not teach you how to use Deployment Manager.
If you are new to Deployment Manager, try the Quickstart instead.
Managing resources
❑
After you have created a resource as part of a
deployment, use Deployment Manager if you need to modify the resource.
If you modify a resource without using Deployment Manager, such as
with the Google Cloud console or
gcloud
you might see
errors if you try to modify the resource in your original deployment. If you want to remove a resource from a deployment without deleting the resource, use the following steps:
- In your deployment configuration, delete the definition of that resource.
- Update the deployment
, and in your `gcloud` command, add
--delete-policy ABANDON. The resource is no longer associated with the deployment, and you can then modify the resource using the Google Cloud console orgcloud.
❑
If you have Compute Engine instances in your deployment and want to
attach persistent disks to the instances, define the disk
separately from the instance, so that you can manage it easily. For
example, in the deployment below, the disk
example-disk
is
defined separately from the instance example-instance
. To
attach the disk, the configuration has a reference
to the disk: resources : # instance - name : example-instance type : compute.v1.instance properties : disks : - type : PERSISTENT source:$(ref.example-disk.selfLink) # disk - name : example-disk type : compute.v1.disk properties : zone : us-central1-a sizeGb : 10 type : ...
❑
If you want to create and manage private Google Kubernetes Engine (GKE)
clusters with Deployment Manager, set the following privateClusterConfig
and ipAllocationPolicy
options in your deployment.
privateClusterConfig : enablePrivateNodes : true enablePrivateEndpoint : true # Configure the IP range for the hosted master network masterIpv4CidrBlock : IP_RANGE ipAllocationPolicy : useIpAliases : true createSubnetwork : true
For requirements and additional considerations when you are creating a private cluster with GKE, read Setting up a private cluster .
Including credentials in your deployment
| ❑
Deployment Manager redacts some fields related to credentials from
properties in your YAML configurations. This redaction occurs based on the key
of the property. The following example demonstrates one such redaction:
# Config provided to Deployment Manager resources : - name : example-resource type : gcp-types/service-v1:sample-type-with-password properties : zone : us-central1-a username : test-user password : hunter2 # Config as surfaced by Deployment Manager resources : - name : example-resource type : gcp-types/service-v1:sample-type-with-password properties : zone : us-central1-a username : test-user password : (redacted) |
|---|
| ❑
If you include the credential in a Jinja or Python template for your
deployment, the credential is redacted from the resulting Expanded Config and
Layout files, but is still visible in the original import file. For this
reason, we strongly recommend that you place all credentials which you
intend to keep secret in your top-level YAML config
. You can reference
them from there by using template properties
.
|
| ❑
Any credentials included in a key-value pair within a YAML file or list of
items will not be redacted
, such as in the following example. We
strongly recommend that you do not provide credentials to
Deployment Manager as key-value pairs within YAML files or lists of items
for this reason.
# Not a valid instance configuration, used solely for demonstration resources : - name : example-resource type : gcp-types/compute-v1:instances properties : zone : us-central1-a disks : - autoDelete : true boot : true # Will not be redacted password : hunter2 |
Building templates
| ❑
To speed up defining your templates, consider starting with the
production-ready sample templates from the Cloud Foundation Toolkit Project
.
|
|---|
| ❑
If you have complex infrastructure requirements, such as the need to create
multiple environments, read the tutorial and samples for using Deployment Manager at scale
.
|
| ❑
Use Python to build your templates
.
You can use Python or Jinja2 to create templates. Jinja is easier to get
started with, but Python is more flexible for complex deployments where you
might have many resources split across multiple environments.
|
| ❑
Structure your configuration file
(the YAML file) so it only uses one type, and use a top-level template as that type
to call all of the other templates. Adopting this practice makes it easier to
change a set of templates into a composite type
.
|
| ❑
Use a schema file
.
Schemas define a set of rules that a configuration file must follow to use a
particular template. By defining a schema and encouraging others to review the
requirements defined in a schema, your users have an easy way to understand
what properties are settable or required for the respective template. This
helps users consume the configuration without having to investigate the detail
of the templates. At a minimum, define a schema file for the top-level template.
|
| ❑
Use template properties
and outputs
.
Using properties and outputs allows you to pass in variables like the zone,
machine size, number of machines, or the app state (test, prod, staging) into
your templates and get back output values such as the IP address and the
selfLink
to a VM instance. Properties and outputs allow your
templates to be flexible so they can be reused with no modifications to the
underlying templates. |
| ❑
Use individual template files that you import into your
main configuration file. This provides you with a more manageable way of
working with configurations.
|
| ❑
Break your configurations up into logical units. For
example, create separate configurations for stateful services such as databases
and buckets and configurations for more transient services such as frontend
instances.
|
| ❑
Use references
.
References should be used for values that are not defined until a resource is
created, such as a resource's
selfLink
, IP address, or
system-generated ID. Without references, Deployment Manager creates all
resources in parallel, so there is no guarantee that dependent resources are
created in the correct order. Using references would enforce the order in which
resources are created. |
| ❑
Preview
your deployments to assess how making an update will affect your deployment.
Deployment Manager does not instantiate any actual resources when you
preview a configuration, but expands the full configuration and creates "shell"
resources instead. This gives you the opportunity to see the changes to your
deployment before committing to it.
|
| ❑
Check the API methods for a specific resource to understand the implications of
carrying out an update. Set update policies
when updating a deployment to help you control how Deployment Manager
applies each update.
|
| ❑
Use labels for your resources. If the resources you are defining supports labels,
use them to label your resources. Labels can help categorize resources that
belong to different deployments and are also a way to distinguish what stage the
resources might be in, such as whether a resource is supporting a production or
test environment.
|
Managing the size of your deployments
Deployment Manager can operate on a large number of resources, subject to quota limits . If you want to reduce the amount of time it takes to create, update, or delete your deployments, you can reduce the number of resources within each individual deployment.
| ❑
If a group of resources does not depend on any resources outside of that group,
you can move that group of resources into a separate deployment. For example,
if your deployment contains several templates
,
you can potentially package each template as a separate deployment.
|
|---|
| ❑
Remove unnecessary resources from your configuration. If you need more resources
later, you can add more resources to your deployment at that time.
|
| ❑
Optionally, limit your deployments to 1000 or fewer resources.
|
Permissions
By default, Deployment Manager uses the credentials of the Google APIs service account to authenticate to other APIs. The Google APIs service account is designed specifically to run internal Google processes on your behalf.
When you want to grant other users access to your Deployment Manager project, you need to grant the user an IAM role that has the appropriate permissions to use Deployment Manager. There are a number of predefined IAM roles you can use to determine how much access a user has to call Deployment Manager.
| ❑
Use IAM roles to restrict what permissions are granted to users
to use Deployment Manager.
|
|---|
| ❑
If you want users to be able to access resources created by
Deployment Manager, grant users the roles
they require to use resources,
but do not grant them permissions to deploy resources directly.
|
| ❑
Granting the owner
role to a
principal will allow them to modify the IAM policy. Therefore,
grant the owner role only if the principal has a legitimate purpose to manage
the IAM policy, as your policy contains sensitive access control
data. Having a minimal set of users manage it will simplify any auditing that
you may have to do.
|
| ❑
Deployment Manager uses the Google APIs service account to create and
manage your resources. If you are using Deployment Manager to manage
critical resources, such as custom IAM roles
,
you must assign additional IAM roles to the default Google APIs
service account. For example, if you want to use Deployment Manager to
create and manage custom IAM roles, you must add the Role
Administrator role to the Google APIs service account.
For an overview of the Google APIs service account, see Google- managed service accounts . For steps to assign roles to a service account, see Granting roles to service accounts . |
Automation
Consider automating the creation of projects as well as automating the creation of resources contained within the projects. This enables you to adopt an infrastructure-as-code approach for project provisioning. This approach provides many benefits, such as the ability to:
- Allow enforcement of corporate requirements when providing projects to the teams who need access to Google Cloud resources.
- Provide a series of predefined project environments that can be quickly and easily provisioned.
- Use version control to manage your base project configuration.
- Have confidence that you are deploying reproducible and consistent project configurations.
- Incorporate project creation as part of an automated provisioning process.
❑
Continuous Integration (CI) / Continuous Deployment (CD)
Use Deployment Manager as part of your CI/CD pipeline.
❑
Do not use a CI/CD pipeline to create and delete entire test and QA projects.
- You might choose to destroy VM instances or resources that might incur extra cost, but consider leaving reusable assets that could take a while to recreate, as deleting these resources could adversely impact how long it takes to complete your build pipelines. There are no costs for setting up networks, subnets, or firewall rules.
- Be aware that if you do delete a project, it will remain part of your project quota for a few days until the project is completely removed. This also means you cannot reuse the project name.
- Using Deployment Manager allows you to easily delete resources from a project so that you do not hit your resource quotas.
❑
Use Deployment Manager to create the stateful parts of the project and
network configuration and deploy these outside of the CI/CD process as part of
the initial setup. After testing is completed, you can delete deployments that
contain only stateless resources that were deployed as part of the pipeline.
❑
As part of the CI/CD process, use a separate configuration to deploy resources
to your test and QA projects. After you have finished testing, you can then use
Deployment Manager to delete the resources from your test and QA projects.
Test deployments. With the ability to incorporate resource provisioning as
part of a CI/CD pipeline, Deployment Manager allows you to treat your
project configuration as code that you can easily test, and reproduce consistent
copies of the current production environment or the current environment with
changes applied to test in confidence.
❑
Use version control. Using a version control system as part of the development
process for your deployments allows you to:
- Fall back to a previous known good configuration.
- Provide an audit trail for changes.
- Use the configuration as part of a continuous deployment system.
