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:
|
|
❑
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: 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.
|
❑
Automate the creation of projects using the
templates available on GitHub
as a starting point.
|
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.
|
|
❑
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:
|