This page describes how to preview a configuration file before creating a deployment. To learn more about configurations, read Configurations Overview.
After you have written a configuration file, you can preview the configuration before you create a deployment. Previewing a configuration lets you see the resources that Deployment Manager would create but does not actually instantiate any actual resources. The Deployment Manager service previews the configuration by:
- Expanding the full configuration, including any templates.
- Creating a deployment and "shell" resources.
You can preview your configuration by using the preview
query parameter when
making an insert()
request.
Before you begin
- If you want to use the command-line examples in this guide, install the `gcloud` command-line tool.
- If you want to use the API examples in this guide, set up API access.
- Understand how to create a basic configuration.
Previewing a new configuration
Preview a configuration by using the Google Cloud CLI or by making a direct request to the API.
gcloud
If you're using the Google Cloud CLI, use the create
sub-command
with the --preview
flag:
gcloud deployment-manager deployments create example-config --config configuration-file.yaml \
--preview
The server returns a list of resources whose state is IN_PREVIEW
for you
to review:
The fingerprint of the deployment is ulPDrJON8E5ySHKC5fcukw==
Waiting for create [operation-1492785372594-54dae2ddbff50-58d45d53-12d483cf]...done.
Create operation operation-1492785372594-54dae2ddbff50-58d45d53-12d483cf completed successfully.
NAME TYPE STATE ERRORS INTENT
datadisk-example compute.v1.disk IN_PREVIEW [] CREATE_OR_ACQUIRE
vm-example compute.v1.instance IN_PREVIEW [] CREATE_OR_ACQUIRE
API
In the API, use the insert()
method with a request body that contains the target
and name
fields and
the preview=true
query parameter. Provide your configuration in the
target
field.
For example, the following API request previews a simple template:
POST https://www.googleapis.com/deploymentmanager/v2/projects/myproject/global/deployments?preview=true
{
"name": "example-config",
"target": {
"config": {
"content": "resources:\n- name: vm-created-by-cloud-config\n type: compute.v1.instance\n properties:\n zone: us-central1-a\n machineType: https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/machineTypes/n1-standard-1\n disks:\n - deviceName: boot\n type: PERSISTENT\n boot: true\n autoDelete: true\n initializeParams:\n diskName: disk-created-by-cloud-config\n sourceImage: https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-7-wheezy-v20140619\n networkInterfaces:\n networkInterfaces:\n - network: https://www.googleapis.com/compute/v1/projects/myproject/global/networks/default"
}
}
}
When a deployment is in preview mode, you can move forward with the deployment in one of three ways:
- Deploy the configuration by performing an update.
- Cancel the preview and then delete the deployment.
- Update the preview.
Performing multiple previews
If you want to change your configuration and perform another preview,
use the update
command with the --preview
flag:
gcloud deployment-manager deployments update example-config \
--config new-config.yaml --preview
In the API, make a
PUT()
request with an existing deployment and provide the preview=true
query
parameter. The request body must contain the intent
, target
, and name
fields. For example, the following API request previews a simple update:
PUT https://www.googleapis.com/deploymentmanager/v2/projects/myproject/global/deployments/example-config?preview=true
{
"target": {
"config": {
"content": "resources:\n- name: vm-created-by-cloud-config\n type: compute.v1.instance\n properties:\n zone: us-central1-a\n machineType: https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/machineTypes/n1-standard-1\n disks:\n - deviceName: boot\n type: PERSISTENT\n boot: true\n autoDelete: true\n initializeParams:\n diskName: disk-created-by-cloud-config\n sourceImage: https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-7-wheezy-v20140619\n networkInterfaces:\n - network: https://www.googleapis.com/compute/v1/projects/myproject/global/networks/default"
}
},
"name": "example-config"
}
Deploying or canceling a preview
After previewing a deployment, you can move forward with the deployment by performing an update and committing the configuration. For example, assume you have a deployment named example-config currently in preview mode. You can move forward with the deployment by running the following command:
gcloud deployment-manager deployments update example-config
Deployment Manager uses the last previewed configuration to create a deployment.
Alternatively, if you don't want to move forward with the configuration, you can cancel the preview, and then delete the deployment:
gcloud deployment-manager deployments cancel-preview example-config
While a deployment is in preview mode, you cannot move forward with another
configuration. For example, assume you have a deployment called
example-config
that is in preview mode using a configuration named
vm.yaml
. You decide that you want to deploy a new configuration named
two_vms.yaml
to the same deployment, skipping the preview process. While
example-config
is still in preview mode, you cannot deploy a new
configuration. Cancel the preview, and then
update the deployment
with the new configuration.
What's next
- Learn more about configuration files.
- Make an update to your deployment after you deploy it.