diff --git a/website/docs/r/compute_instance_template.html.markdown b/website/docs/r/compute_instance_template.html.markdown index b55211107..e3a55200 100644 --- a/website/docs/r/compute_instance_template.html.markdown +++ b/website/docs/r/compute_instance_template.html.markdown @@ -108,6 +108,61 @@ With this setup Terraform generates a unique name for your Instance Template and can then update the Instance Group manager without conflict before destroying the previous Instance Template. +## Deploying the Latest Image + +A common way to use instance templates and managed instance groups is to deploy the +latest image in a family, usually the latest build of your application. There are two +ways to do this in Terraform, and they have their pros and cons. The difference ends +up being in how "latest" is interpreted. You can either deploy the latest image available +when Terraform runs, or you can have each instance check what the latest image is when +it's being created, either as part of a scaling event or being rebuilt by the instance +group manager. + +If you're not sure, we recommend deploying the latest image available when Terraform runs, +because this means all the instances in your group will be based on the same image, always, +and means that no upgrades or changes to your instances happen outside of a `terraform apply`. +You can achieve this by using the [`google_compute_image`](../d/datasource_compute_image.html) +data source, which will retrieve the latest image on every `terraform apply`, and will update +the template to use that specific image: + +```tf +data "google_compute_image" "my_image" { + family = "debian-9" + project = "debian-cloud" +} + +resource "google_compute_instance_template" "instance_template" { + name_prefix = "instance-template-" + machine_type = "n1-standard-1" + region = "us-central1" + + // boot disk + disk { + initialize_params { + image = "${data.google_compute_image.my_image.self_link}" + } + } +} +``` + +To have instances update to the latest on every scaling event or instance re-creation, +use the family as the image for the disk, and it will use GCP's default behavior, setting +the image for the template to the family: + +```tf +resource "google_compute_instance_template" "instance_template" { + name_prefix = "instance-template-" + machine_type = "n1-standard-1" + region = "us-central1" + + // boot disk + disk { + initialize_params { + image = "debian-cloud/debian-9" + } + } +} +``` ## Argument Reference