diff --git a/aws/container-linux/kubernetes/variables.tf b/aws/container-linux/kubernetes/variables.tf
index 9dcf980e..b2b423e2 100644
--- a/aws/container-linux/kubernetes/variables.tf
+++ b/aws/container-linux/kubernetes/variables.tf
@@ -1,21 +1,44 @@
 variable "cluster_name" {
   type        = "string"
-  description = "Cluster name"
+  description = "Unique cluster name (prepended to dns_zone)"
 }
 
+# AWS
+
 variable "dns_zone" {
   type        = "string"
-  description = "AWS DNS Zone (e.g. aws.dghubble.io)"
+  description = "AWS Route53 DNS Zone (e.g. aws.example.com)"
 }
 
 variable "dns_zone_id" {
   type        = "string"
-  description = "AWS DNS Zone ID (e.g. Z3PAABBCFAKEC0)"
+  description = "AWS Route53 DNS Zone ID (e.g. Z3PAABBCFAKEC0)"
 }
 
-variable "ssh_authorized_key" {
+# instances
+
+variable "controller_count" {
   type        = "string"
-  description = "SSH public key for user 'core'"
+  default     = "1"
+  description = "Number of controllers (i.e. masters)"
+}
+
+variable "worker_count" {
+  type        = "string"
+  default     = "1"
+  description = "Number of workers"
+}
+
+variable "controller_type" {
+  type        = "string"
+  default     = "t2.small"
+  description = "EC2 instance type for controllers"
+}
+
+variable "worker_type" {
+  type        = "string"
+  default     = "t2.small"
+  description = "EC2 instance type for workers"
 }
 
 variable "os_channel" {
@@ -27,37 +50,7 @@ variable "os_channel" {
 variable "disk_size" {
   type        = "string"
   default     = "40"
-  description = "The size of the disk in Gigabytes"
-}
-
-variable "host_cidr" {
-  description = "CIDR IPv4 range to assign to EC2 nodes"
-  type        = "string"
-  default     = "10.0.0.0/16"
-}
-
-variable "controller_count" {
-  type        = "string"
-  default     = "1"
-  description = "Number of controllers"
-}
-
-variable "controller_type" {
-  type        = "string"
-  default     = "t2.small"
-  description = "Controller EC2 instance type"
-}
-
-variable "worker_count" {
-  type        = "string"
-  default     = "1"
-  description = "Number of workers"
-}
-
-variable "worker_type" {
-  type        = "string"
-  default     = "t2.small"
-  description = "Worker EC2 instance type"
+  description = "Size of the EBS volume in GB"
 }
 
 variable "controller_clc_snippets" {
@@ -72,7 +65,12 @@ variable "worker_clc_snippets" {
   default     = []
 }
 
-# bootkube assets
+# configuration
+
+variable "ssh_authorized_key" {
+  type        = "string"
+  description = "SSH public key for user 'core'"
+}
 
 variable "asset_dir" {
   description = "Path to a directory where generated assets should be placed (contains secrets)"
@@ -91,6 +89,12 @@ variable "network_mtu" {
   default     = "1480"
 }
 
+variable "host_cidr" {
+  description = "CIDR IPv4 range to assign to EC2 nodes"
+  type        = "string"
+  default     = "10.0.0.0/16"
+}
+
 variable "pod_cidr" {
   description = "CIDR IPv4 range to assign Kubernetes pods"
   type        = "string"
diff --git a/aws/container-linux/kubernetes/workers/variables.tf b/aws/container-linux/kubernetes/workers/variables.tf
index ac49bc65..415be285 100644
--- a/aws/container-linux/kubernetes/workers/variables.tf
+++ b/aws/container-linux/kubernetes/workers/variables.tf
@@ -1,21 +1,23 @@
 variable "name" {
   type        = "string"
-  description = "Unique name instance group"
+  description = "Unique name for the worker pool"
 }
 
+# AWS
+
 variable "vpc_id" {
   type        = "string"
-  description = "ID of the VPC for creating instances"
+  description = "Must be set to `vpc_id` output by cluster"
 }
 
 variable "subnet_ids" {
   type        = "list"
-  description = "List of subnet IDs for creating instances"
+  description = "Must be set to `subnet_ids` output by cluster"
 }
 
 variable "security_groups" {
   type        = "list"
-  description = "List of security group IDs"
+  description = "Must be set to `worker_security_groups` output by cluster"
 }
 
 # instances
@@ -41,14 +43,20 @@ variable "os_channel" {
 variable "disk_size" {
   type        = "string"
   default     = "40"
-  description = "Size of the disk in GB"
+  description = "Size of the EBS volume in GB"
+}
+
+variable "clc_snippets" {
+  type        = "list"
+  description = "Container Linux Config snippets"
+  default     = []
 }
 
 # configuration
 
 variable "kubeconfig" {
   type        = "string"
-  description = "Generated Kubelet kubeconfig"
+  description = "Must be set to `kubeconfig` output by cluster"
 }
 
 variable "ssh_authorized_key" {
@@ -71,9 +79,3 @@ variable "cluster_domain_suffix" {
   type        = "string"
   default     = "cluster.local"
 }
-
-variable "clc_snippets" {
-  type        = "list"
-  description = "Container Linux Config snippets"
-  default     = []
-}
diff --git a/bare-metal/container-linux/kubernetes/variables.tf b/bare-metal/container-linux/kubernetes/variables.tf
index ace976df..7f74e8ae 100644
--- a/bare-metal/container-linux/kubernetes/variables.tf
+++ b/bare-metal/container-linux/kubernetes/variables.tf
@@ -1,3 +1,10 @@
+variable "cluster_name" {
+  type        = "string"
+  description = "Unique cluster name"
+}
+
+# bare-metal
+
 variable "matchbox_http_endpoint" {
   type        = "string"
   description = "Matchbox HTTP read-only endpoint (e.g. http://matchbox.example.com:8080)"
@@ -13,17 +20,7 @@ variable "container_linux_version" {
   description = "Container Linux version of the kernel/initrd to PXE or the image to install"
 }
 
-variable "cluster_name" {
-  type        = "string"
-  description = "Cluster name"
-}
-
-variable "ssh_authorized_key" {
-  type        = "string"
-  description = "SSH public key to set as an authorized_key on machines"
-}
-
-# Machines
+# machines
 # Terraform's crude "type system" does not properly support lists of maps so we do this.
 
 variable "controller_names" {
@@ -50,13 +47,18 @@ variable "worker_domains" {
   type = "list"
 }
 
-# bootkube assets
+# configuration
 
 variable "k8s_domain_name" {
   description = "Controller DNS name which resolves to a controller instance. Workers and kubeconfig's will communicate with this endpoint (e.g. cluster.example.com)"
   type        = "string"
 }
 
+variable "ssh_authorized_key" {
+  type        = "string"
+  description = "SSH public key for user 'core'"
+}
+
 variable "asset_dir" {
   description = "Path to a directory where generated assets should be placed (contains secrets)"
   type        = "string"
@@ -75,14 +77,14 @@ variable "network_mtu" {
 }
 
 variable "pod_cidr" {
-  description = "CIDR IP range to assign Kubernetes pods"
+  description = "CIDR IPv4 range to assign Kubernetes pods"
   type        = "string"
   default     = "10.2.0.0/16"
 }
 
 variable "service_cidr" {
   description = <<EOD
-CIDR IP range to assign Kubernetes services.
+CIDR IPv4 range to assign Kubernetes services.
 The 1st IP will be reserved for kube_apiserver, the 10th IP will be reserved for kube-dns.
 EOD
 
diff --git a/digital-ocean/container-linux/kubernetes/variables.tf b/digital-ocean/container-linux/kubernetes/variables.tf
index d136d247..581adcb7 100644
--- a/digital-ocean/container-linux/kubernetes/variables.tf
+++ b/digital-ocean/container-linux/kubernetes/variables.tf
@@ -1,8 +1,10 @@
 variable "cluster_name" {
   type        = "string"
-  description = "Unique cluster name"
+  description = "Unique cluster name (prepended to dns_zone)"
 }
 
+# Digital Ocean
+
 variable "region" {
   type        = "string"
   description = "Digital Ocean region (e.g. nyc1, sfo2, fra1, tor1)"
@@ -13,22 +15,12 @@ variable "dns_zone" {
   description = "Digital Ocean domain (i.e. DNS zone) (e.g. do.example.com)"
 }
 
-variable "image" {
-  type        = "string"
-  default     = "coreos-stable"
-  description = "OS image from which to initialize the disk (e.g. coreos-stable)"
-}
+# instances
 
 variable "controller_count" {
   type        = "string"
   default     = "1"
-  description = "Number of controllers"
-}
-
-variable "controller_type" {
-  type        = "string"
-  default     = "s-2vcpu-2gb"
-  description = "Digital Ocean droplet size (e.g. s-2vcpu-2gb, s-2vcpu-4gb, s-4vcpu-8gb)."
+  description = "Number of controllers (i.e. masters)"
 }
 
 variable "worker_count" {
@@ -37,15 +29,22 @@ variable "worker_count" {
   description = "Number of workers"
 }
 
+variable "controller_type" {
+  type        = "string"
+  default     = "s-2vcpu-2gb"
+  description = "Droplet type for controllers (e.g. s-2vcpu-2gb, s-2vcpu-4gb, s-4vcpu-8gb)."
+}
+
 variable "worker_type" {
   type        = "string"
   default     = "s-1vcpu-1gb"
-  description = "Digital Ocean droplet size (e.g. s-1vcpu-1gb, s-1vcpu-2gb, s-2vcpu-2gb)"
+  description = "Droplet type for workers (e.g. s-1vcpu-1gb, s-1vcpu-2gb, s-2vcpu-2gb)"
 }
 
-variable "ssh_fingerprints" {
-  type        = "list"
-  description = "SSH public key fingerprints. (e.g. see `ssh-add -l -E md5`)"
+variable "image" {
+  type        = "string"
+  default     = "coreos-stable"
+  description = "Container Linux image for instances (e.g. coreos-stable)"
 }
 
 variable "controller_clc_snippets" {
@@ -60,7 +59,12 @@ variable "worker_clc_snippets" {
   default     = []
 }
 
-# bootkube assets
+# configuration
+
+variable "ssh_fingerprints" {
+  type        = "list"
+  description = "SSH public key fingerprints. (e.g. see `ssh-add -l -E md5`)"
+}
 
 variable "asset_dir" {
   description = "Path to a directory where generated assets should be placed (contains secrets)"
@@ -74,14 +78,14 @@ variable "networking" {
 }
 
 variable "pod_cidr" {
-  description = "CIDR IP range to assign Kubernetes pods"
+  description = "CIDR IPv4 range to assign Kubernetes pods"
   type        = "string"
   default     = "10.2.0.0/16"
 }
 
 variable "service_cidr" {
   description = <<EOD
-CIDR IP range to assign Kubernetes services.
+CIDR IPv4 range to assign Kubernetes services.
 The 1st IP will be reserved for kube_apiserver, the 10th IP will be reserved for kube-dns.
 EOD
 
diff --git a/docs/advanced/worker-pools.md b/docs/advanced/worker-pools.md
index c039448f..4168d640 100644
--- a/docs/advanced/worker-pools.md
+++ b/docs/advanced/worker-pools.md
@@ -56,7 +56,7 @@ The AWS internal `workers` module supports a number of [variables](https://githu
 | security_groups | Must be set to `worker_security_groups` output by cluster | "${module.cluster.worker_security_groups}" |
 | name | Unique name (distinct from cluster name) | "tempest-m5s" |
 | kubeconfig | Must be set to `kubeconfig` output by cluster | "${module.cluster.kubeconfig}" |
-| ssh_authorized_key | SSH public key for ~/.ssh_authorized_keys | "ssh-rsa AAAAB3NZ..." |
+| ssh_authorized_key | SSH public key for user 'core' | "ssh-rsa AAAAB3NZ..." |
 
 #### Optional
 
@@ -131,7 +131,7 @@ The Google Cloud internal `workers` module supports a number of [variables](http
 | name | Unique name (distinct from cluster name) | "yavin-16x" |
 | cluster_name | Must be set to `cluster_name` of cluster | "yavin" |
 | kubeconfig | Must be set to `kubeconfig` output by cluster | "${module.cluster.kubeconfig}" |
-| ssh_authorized_key | SSH public key for ~/.ssh_authorized_keys | "ssh-rsa AAAAB3NZ..." |
+| ssh_authorized_key | SSH public key for user 'core' | "ssh-rsa AAAAB3NZ..." |
 
 #### Optional
 
@@ -139,7 +139,7 @@ The Google Cloud internal `workers` module supports a number of [variables](http
 |:-----|:------------|:--------|:--------|
 | count | Number of instances | 1 | 3 |
 | machine_type | Compute instance machine type | "n1-standard-1" | See below |
-| os_image | OS image for compute instances | "coreos-stable" | "coreos-alpha", "coreos-beta" |
+| os_image | Container Linux image for compute instances | "coreos-stable" | "coreos-alpha", "coreos-beta" |
 | disk_size | Size of the disk in GB | 40 | 100 |
 | preemptible | If true, Compute Engine will terminate instances randomly within 24 hours | false | true |
 | service_cidr | Must match `service_cidr` of cluster | "10.3.0.0/16" | "10.3.0.0/24" |
diff --git a/docs/aws.md b/docs/aws.md
index 37d31f29..58db3bc8 100644
--- a/docs/aws.md
+++ b/docs/aws.md
@@ -248,19 +248,19 @@ Reference the DNS zone id with `"${aws_route53_zone.zone-for-clusters.zone_id}"`
 | Name | Description | Default | Example |
 |:-----|:------------|:--------|:--------|
 | controller_count | Number of controllers (i.e. masters) | 1 | 1 |
-| controller_type | Controller EC2 instance type | "t2.small" | "t2.medium" |
 | worker_count | Number of workers | 1 | 3 |
-| worker_type | Worker EC2 instance type | "t2.small" | "t2.medium" |
+| controller_type | EC2 instance type for controllers | "t2.small" | "t2.medium" |
+| worker_type | EC2 instance type for workers | "t2.small" | "t2.medium" |
 | os_channel | Container Linux AMI channel | stable | stable, beta, alpha |
 | disk_size | Size of the EBS volume in GB | "40" | "100" |
-| networking | Choice of networking provider | "calico" | "calico" or "flannel" |
-| network_mtu | CNI interface MTU (calico only) | 1480 | 8981 |
-| host_cidr | CIDR range to assign to EC2 instances | "10.0.0.0/16" | "10.1.0.0/16" |
-| pod_cidr | CIDR range to assign to Kubernetes pods | "10.2.0.0/16" | "10.22.0.0/16" |
-| service_cidr | CIDR range to assign to Kubernetes services | "10.3.0.0/16" | "10.3.0.0/24" |
-| cluster_domain_suffix | FQDN suffix for Kubernetes services answered by kube-dns. | "cluster.local" | "k8s.example.com" |
 | controller_clc_snippets | Controller Container Linux Config snippets | [] | |
 | worker_clc_snippets | Worker Container Linux Config snippets | [] | |
+| networking | Choice of networking provider | "calico" | "calico" or "flannel" |
+| network_mtu | CNI interface MTU (calico only) | 1480 | 8981 |
+| host_cidr | CIDR IPv4 range to assign to EC2 instances | "10.0.0.0/16" | "10.1.0.0/16" |
+| pod_cidr | CIDR IPv4 range to assign to Kubernetes pods | "10.2.0.0/16" | "10.22.0.0/16" |
+| service_cidr | CIDR IPv4 range to assign to Kubernetes services | "10.3.0.0/16" | "10.3.0.0/24" |
+| cluster_domain_suffix | FQDN suffix for Kubernetes services answered by kube-dns. | "cluster.local" | "k8s.example.com" |
 
 Check the list of valid [instance types](https://aws.amazon.com/ec2/instance-types/).
 
diff --git a/docs/bare-metal.md b/docs/bare-metal.md
index 6c733557..0db00aa5 100644
--- a/docs/bare-metal.md
+++ b/docs/bare-metal.md
@@ -186,13 +186,13 @@ module "bare-metal-mercury" {
     tls = "tls.default"
   }
   
-  # install
+  # bare-metal
+  cluster_name            = "mercury"
   matchbox_http_endpoint  = "http://matchbox.example.com"
   container_linux_channel = "stable"
   container_linux_version = "1632.3.0"
 
   # configuration
-  cluster_name       = "mercury"
   k8s_domain_name    = "node1.example.com"
   ssh_authorized_key = "ssh-rsa AAAAB3Nz..."
   asset_dir          = "/home/user/.secrets/clusters/mercury"
@@ -355,19 +355,19 @@ Learn about [maintenance](topics/maintenance.md) and [addons](addons/overview.md
 
 | Name | Description | Example |
 |:-----|:------------|:--------|
+| cluster_name | Unique cluster name | mercury |
 | matchbox_http_endpoint | Matchbox HTTP read-only endpoint | http://matchbox.example.com:8080 |
 | container_linux_channel | Container Linux channel | stable, beta, alpha |
 | container_linux_version | Container Linux version of the kernel/initrd to PXE and the image to install | 1632.3.0 |
-| cluster_name | Cluster name | mercury |
 | k8s_domain_name | FQDN resolving to the controller(s) nodes. Workers and kubectl will communicate with this endpoint | "myk8s.example.com" |
-| ssh_authorized_key | SSH public key for ~/.ssh/authorized_keys | "ssh-rsa AAAAB3Nz..." |
+| ssh_authorized_key | SSH public key for user 'core' | "ssh-rsa AAAAB3Nz..." |
+| asset_dir | Path to a directory where generated assets should be placed (contains secrets) | "/home/user/.secrets/clusters/mercury" |
 | controller_names | Ordered list of controller short names | ["node1"] |
 | controller_macs | Ordered list of controller identifying MAC addresses | ["52:54:00:a1:9c:ae"] |
 | controller_domains | Ordered list of controller FQDNs | ["node1.example.com"] |
 | worker_names | Ordered list of worker short names | ["node2", "node3"] |
 | worker_macs | Ordered list of worker identifying MAC addresses | ["52:54:00:b2:2f:86", "52:54:00:c3:61:77"] |
 | worker_domains | Ordered list of worker FQDNs | ["node2.example.com", "node3.example.com"] |
-| asset_dir | Path to a directory where generated assets should be placed (contains secrets) | "/home/user/.secrets/clusters/mercury" |
 
 ### Optional
 
@@ -378,8 +378,8 @@ Learn about [maintenance](topics/maintenance.md) and [addons](addons/overview.md
 | container_linux_oem | Specify alternative OEM image ids for the disk install | "" | "vmware_raw", "xen" |
 | networking | Choice of networking provider | "calico" | "calico" or "flannel" |
 | network_mtu | CNI interface MTU (calico-only) | 1480 | - | 
-| pod_cidr | CIDR range to assign to Kubernetes pods | "10.2.0.0/16" | "10.22.0.0/16" |
-| service_cidr | CIDR range to assign to Kubernetes services | "10.3.0.0/16" | "10.3.0.0/24" |
+| pod_cidr | CIDR IPv4 range to assign to Kubernetes pods | "10.2.0.0/16" | "10.22.0.0/16" |
+| service_cidr | CIDR IPv4 range to assign to Kubernetes services | "10.3.0.0/16" | "10.3.0.0/24" |
 | cluster_domain_suffix | FQDN suffix for Kubernetes services answered by kube-dns. | "cluster.local" | "k8s.example.com" |
 | kernel_args | Additional kernel args to provide at PXE boot | [] | "kvm-intel.nested=1" |
 
diff --git a/docs/digital-ocean.md b/docs/digital-ocean.md
index d47d2599..7fb0b30e 100644
--- a/docs/digital-ocean.md
+++ b/docs/digital-ocean.md
@@ -260,16 +260,16 @@ Digital Ocean requires the SSH public key be uploaded to your account, so you ma
 | Name | Description | Default | Example |
 |:-----|:------------|:--------|:--------|
 | controller_count | Number of controllers (i.e. masters) | 1 | 1 |
-| controller_type | Digital Ocean droplet size | s-2vcpu-2gb | s-2vcpu-2gb, s-2vcpu-4gb, s-4vcpu-8gb, ... |
 | worker_count | Number of workers | 1 | 3 |
-| worker_type | Digital Ocean droplet size | s-1vcpu-1gb | s-1vcpu-1gb, s-1vcpu-2gb, s-2vcpu-2gb, ... |
-| image | OS image for droplets | "coreos-stable" | coreos-stable, coreos-beta, coreos-alpha |
-| networking | Choice of networking provider | "flannel" | "flannel" |
-| pod_cidr | CIDR range to assign to Kubernetes pods | "10.2.0.0/16" | "10.22.0.0/16" |
-| service_cidr | CIDR range to assign to Kubernetes services | "10.3.0.0/16" | "10.3.0.0/24" |
-| cluster_domain_suffix | FQDN suffix for Kubernetes services answered by kube-dns. | "cluster.local" | "k8s.example.com" |
+| controller_type | Droplet type for controllers | s-2vcpu-2gb | s-2vcpu-2gb, s-2vcpu-4gb, s-4vcpu-8gb, ... |
+| worker_type | Droplet type for workers | s-1vcpu-1gb | s-1vcpu-1gb, s-1vcpu-2gb, s-2vcpu-2gb, ... |
+| image | Container Linux image for instances | "coreos-stable" | coreos-stable, coreos-beta, coreos-alpha |
 | controller_clc_snippets | Controller Container Linux Config snippets | [] | |
 | worker_clc_snippets | Worker Container Linux Config snippets | [] | |
+| networking | Choice of networking provider | "flannel" | "flannel" |
+| pod_cidr | CIDR IPv4 range to assign to Kubernetes pods | "10.2.0.0/16" | "10.22.0.0/16" |
+| service_cidr | CIDR IPv4 range to assign to Kubernetes services | "10.3.0.0/16" | "10.3.0.0/24" |
+| cluster_domain_suffix | FQDN suffix for Kubernetes services answered by kube-dns. | "cluster.local" | "k8s.example.com" |
 
 Check the list of valid [droplet types](https://developers.digitalocean.com/documentation/changelog/api-v2/new-size-slugs-for-droplet-plan-changes/) or use `doctl compute size list`.
 
diff --git a/docs/google-cloud.md b/docs/google-cloud.md
index 866fbdb5..d4a0c421 100644
--- a/docs/google-cloud.md
+++ b/docs/google-cloud.md
@@ -226,7 +226,7 @@ Learn about [maintenance](topics/maintenance.md) and [addons](addons/overview.md
 | region | Google Cloud region | "us-central1" |
 | dns_zone | Google Cloud DNS zone | "google-cloud.example.com" |
 | dns_zone_name | Google Cloud DNS zone name | "example-zone" |
-| ssh_authorized_key | SSH public key for ~/.ssh_authorized_keys | "ssh-rsa AAAAB3NZ..." |
+| ssh_authorized_key | SSH public key for user 'core' | "ssh-rsa AAAAB3NZ..." |
 | asset_dir | Path to a directory where generated assets should be placed (contains secrets) | "/home/user/.secrets/clusters/yavin" |
 
 Check the list of valid [regions](https://cloud.google.com/compute/docs/regions-zones/regions-zones) and list Container Linux [images](https://cloud.google.com/compute/docs/images) with `gcloud compute images list | grep coreos`.
@@ -255,14 +255,14 @@ resource "google_dns_managed_zone" "zone-for-clusters" {
 | controller_count | Number of controllers (i.e. masters) | 1 | 1 |
 | worker_count | Number of workers | 1 | 3 |
 | machine_type | Machine type for compute instances | "n1-standard-1" | See below |
-| os_image | OS image for compute instances | "coreos-stable" | "coreos-stable-1632-3-0-v20180215" |
+| os_image | Container Linux image for compute instances | "coreos-stable" | "coreos-stable-1632-3-0-v20180215" |
 | worker_preemptible | If enabled, Compute Engine will terminate workers randomly within 24 hours | false | true |
-| networking | Choice of networking provider | "calico" | "calico" or "flannel" |
-| pod_cidr | CIDR range to assign to Kubernetes pods | "10.2.0.0/16" | "10.22.0.0/16" |
-| service_cidr | CIDR range to assign to Kubernetes services | "10.3.0.0/16" | "10.3.0.0/24" |
-| cluster_domain_suffix | FQDN suffix for Kubernetes services answered by kube-dns. | "cluster.local" | "k8s.example.com" |
 | controller_clc_snippets | Controller Container Linux Config snippets | [] | |
 | worker_clc_snippets | Worker Container Linux Config snippets | [] | |
+| networking | Choice of networking provider | "calico" | "calico" or "flannel" |
+| pod_cidr | CIDR IPv4 range to assign to Kubernetes pods | "10.2.0.0/16" | "10.22.0.0/16" |
+| service_cidr | CIDR IPv4 range to assign to Kubernetes services | "10.3.0.0/16" | "10.3.0.0/24" |
+| cluster_domain_suffix | FQDN suffix for Kubernetes services answered by kube-dns. | "cluster.local" | "k8s.example.com" |
 
 Check the list of valid [machine types](https://cloud.google.com/compute/docs/machine-types).
 
diff --git a/google-cloud/container-linux/kubernetes/controllers/variables.tf b/google-cloud/container-linux/kubernetes/controllers/variables.tf
index 4e7e0da1..c261eb2c 100644
--- a/google-cloud/container-linux/kubernetes/controllers/variables.tf
+++ b/google-cloud/container-linux/kubernetes/controllers/variables.tf
@@ -66,7 +66,7 @@ variable "ssh_authorized_key" {
 
 variable "service_cidr" {
   description = <<EOD
-CIDR IP range to assign Kubernetes services.
+CIDR IPv4 range to assign Kubernetes services.
 The 1st IP will be reserved for kube_apiserver, the 10th IP will be reserved for kube-dns.
 EOD
 
diff --git a/google-cloud/container-linux/kubernetes/variables.tf b/google-cloud/container-linux/kubernetes/variables.tf
index d536a5ca..78f3b8ee 100644
--- a/google-cloud/container-linux/kubernetes/variables.tf
+++ b/google-cloud/container-linux/kubernetes/variables.tf
@@ -1,8 +1,10 @@
 variable "cluster_name" {
   type        = "string"
-  description = "Cluster name"
+  description = "Unique cluster name (prepended to dns_zone)"
 }
 
+# Google Cloud
+
 variable "region" {
   type        = "string"
   description = "Google Cloud Region (e.g. us-central1, see `gcloud compute regions list`)"
@@ -10,17 +12,26 @@ variable "region" {
 
 variable "dns_zone" {
   type        = "string"
-  description = "Google Cloud DNS Zone (e.g. google-cloud.dghubble.io)"
+  description = "Google Cloud DNS Zone (e.g. google-cloud.example.com)"
 }
 
 variable "dns_zone_name" {
   type        = "string"
-  description = "Google Cloud DNS Zone name (e.g. google-cloud-prod-zone)"
+  description = "Google Cloud DNS Zone name (e.g. example-zone)"
 }
 
-variable "ssh_authorized_key" {
+# instances
+
+variable "controller_count" {
   type        = "string"
-  description = "SSH public key for user 'core'"
+  default     = "1"
+  description = "Number of controllers (i.e. masters)"
+}
+
+variable "worker_count" {
+  type        = "string"
+  default     = "1"
+  description = "Number of workers"
 }
 
 variable "machine_type" {
@@ -32,19 +43,7 @@ variable "machine_type" {
 variable "os_image" {
   type        = "string"
   default     = "coreos-stable"
-  description = "OS image from which to initialize the disk (see `gcloud compute images list`)"
-}
-
-variable "controller_count" {
-  type        = "string"
-  default     = "1"
-  description = "Number of controllers"
-}
-
-variable "worker_count" {
-  type        = "string"
-  default     = "1"
-  description = "Number of workers"
+  description = "Container Linux image for compute instances (e.g. coreos-stable)"
 }
 
 variable "worker_preemptible" {
@@ -65,7 +64,12 @@ variable "worker_clc_snippets" {
   default     = []
 }
 
-# bootkube assets
+# configuration
+
+variable "ssh_authorized_key" {
+  type        = "string"
+  description = "SSH public key for user 'core'"
+}
 
 variable "asset_dir" {
   description = "Path to a directory where generated assets should be placed (contains secrets)"
@@ -79,14 +83,14 @@ variable "networking" {
 }
 
 variable "pod_cidr" {
-  description = "CIDR IP range to assign Kubernetes pods"
+  description = "CIDR IPv4 range to assign Kubernetes pods"
   type        = "string"
   default     = "10.2.0.0/16"
 }
 
 variable "service_cidr" {
   description = <<EOD
-CIDR IP range to assign Kubernetes services.
+CIDR IPv4 range to assign Kubernetes services.
 The 1st IP will be reserved for kube_apiserver, the 10th IP will be reserved for kube-dns.
 EOD
 
diff --git a/google-cloud/container-linux/kubernetes/workers/variables.tf b/google-cloud/container-linux/kubernetes/workers/variables.tf
index fa0f85a7..70bf80cb 100644
--- a/google-cloud/container-linux/kubernetes/workers/variables.tf
+++ b/google-cloud/container-linux/kubernetes/workers/variables.tf
@@ -1,21 +1,23 @@
 variable "name" {
   type        = "string"
-  description = "Unique name for instance group"
+  description = "Unique name for the worker pool"
 }
 
 variable "cluster_name" {
   type        = "string"
-  description = "Cluster name"
+  description = "Must be set to `cluster_name of cluster`"
 }
 
+# Google Cloud
+
 variable "region" {
   type        = "string"
-  description = "Google Cloud region (e.g. us-central1, see `gcloud compute regions list`)."
+  description = "Must be set to `region` of cluster"
 }
 
 variable "network" {
   type        = "string"
-  description = "Name of the network to attach to the compute instance interfaces"
+  description = "Must be set to `network_name` output by cluster"
 }
 
 # instances
@@ -35,7 +37,7 @@ variable "machine_type" {
 variable "os_image" {
   type        = "string"
   default     = "coreos-stable"
-  description = "OS image from which to initialize the disk (e.g. gcloud compute images list)"
+  description = "Container Linux image for compute instanges (e.g. gcloud compute images list)"
 }
 
 variable "disk_size" {
@@ -54,7 +56,7 @@ variable "preemptible" {
 
 variable "kubeconfig" {
   type        = "string"
-  description = "Generated Kubelet kubeconfig"
+  description = "Must be set to `kubeconfig` output by cluster"
 }
 
 variable "ssh_authorized_key" {
@@ -64,7 +66,7 @@ variable "ssh_authorized_key" {
 
 variable "service_cidr" {
   description = <<EOD
-CIDR IP range to assign Kubernetes services.
+CIDR IPv4 range to assign Kubernetes services.
 The 1st IP will be reserved for kube_apiserver, the 10th IP will be reserved for kube-dns.
 EOD