From 85ed4c4f86de45432631c4e8e4c3863b19ddec44 Mon Sep 17 00:00:00 2001
From: Paddy Carver <paddy@hashicorp.com>
Date: Wed, 22 Aug 2018 01:43:50 -0700
Subject: [PATCH] Add docs about image families and instance templates.

Recommend using our data source instead of hardcoding the family into a
template.
---
 .../r/compute_instance_template.html.markdown | 55 +++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/website/docs/r/compute_instance_template.html.markdown b/website/docs/r/compute_instance_template.html.markdown
index ef50d420..c5865f2f 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