Best practices for using Deployment Manager

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:

  1. In your deployment configuration, delete the definition of that resource.
  2. 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 or gcloud.
❑  
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.
❑  
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.
  • 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.