From d994e04f3390e0c19cc6ca5ab942f8ff6ea94bab Mon Sep 17 00:00:00 2001
From: Warren Gifford <warrenbruceg@gmail.com>
Date: Tue, 7 Jul 2026 20:23:46 -0700
Subject: [PATCH 1/8] minor typo fixups

---
 docs/self-hosted/executors/deploy-executors-terraform.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/self-hosted/executors/deploy-executors-terraform.mdx b/docs/self-hosted/executors/deploy-executors-terraform.mdx
index 3e9df238e..710513990 100644
--- a/docs/self-hosted/executors/deploy-executors-terraform.mdx
+++ b/docs/self-hosted/executors/deploy-executors-terraform.mdx
@@ -29,7 +29,7 @@ module "executors" {
   # Either:
   executor_queue_name                          = "<codeintel | batches>"
   # Or:
-  executor_queue_names                         = "codeintel,batches"
+  executor_queue_names                         = ["codeintel", "batches"]
 
   executor_instance_tag                        = "<tag to filter in stackdriver monitoring>"
   executor_metrics_environment_label           = "<label to filter custom metrics>"
@@ -181,7 +181,7 @@ The following is a step-by-step guide on provisioning a single `codeintel` execu
 4. Set up your Sourcegraph instance's Site configuration for executors
     1. Click on your profile picture in the top right corner
     2. Select **Site admin**
-    3. Example the **Configuration** section
+    3. Expand the **Configuration** section
     4. Select **Site configuration**
     5. Set the following,
         - `"externalURL": "<URL>"`

From c2bed344ca60afa0c062531fa78355ea6948adc1 Mon Sep 17 00:00:00 2001
From: Warren Gifford <warrenbruceg@gmail.com>
Date: Tue, 7 Jul 2026 20:28:13 -0700
Subject: [PATCH 2/8] update versions

---
 .../executors/deploy-executors-terraform.mdx       | 14 +++-----------
 1 file changed, 3 insertions(+), 11 deletions(-)

diff --git a/docs/self-hosted/executors/deploy-executors-terraform.mdx b/docs/self-hosted/executors/deploy-executors-terraform.mdx
index 710513990..197e4d20c 100644
--- a/docs/self-hosted/executors/deploy-executors-terraform.mdx
+++ b/docs/self-hosted/executors/deploy-executors-terraform.mdx
@@ -55,15 +55,7 @@ See the Terraform Modules for additional configurations.
 
 ## Terraform Version
 
-Terraform modules `4.2.x` and above allow Terraform from `1.1.x` to `< 2.x` to be used.
-
-If using a Terraform module `4.1.x` or below, use [tfenv](https://github.com/tfutils/tfenv) to install Terraform
-1.1+.
-
-```shell
-tfenv install 1.1.9
-tfenv use 1.1.9
-```
+The executor Terraform modules require Terraform `>= 1.1.0, < 2.0.0`.
 
 ## Permissions
 
@@ -423,8 +415,8 @@ module "executors" {
   # Find the latest version matching your Sourcegraph version here:
   # - https://github.com/sourcegraph/terraform-google-executors/tags
   # - https://github.com/sourcegraph/terraform-aws-executors/tags
--  version = "4.0.0"
-+  version = "4.1.0"
+-  version = "7.3.0"
++  version = "7.4.0"
 
   # AWS specific
   availability_zone = "<availability zone to provision resource in AWS>"

From baae788616f92ffbadf0270edaf44be3629289d2 Mon Sep 17 00:00:00 2001
From: Warren Gifford <warrenbruceg@gmail.com>
Date: Tue, 7 Jul 2026 21:22:30 -0700
Subject: [PATCH 3/8] better example machine types

---
 .../executors/deploy-executors-terraform.mdx         | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/docs/self-hosted/executors/deploy-executors-terraform.mdx b/docs/self-hosted/executors/deploy-executors-terraform.mdx
index 197e4d20c..394207d79 100644
--- a/docs/self-hosted/executors/deploy-executors-terraform.mdx
+++ b/docs/self-hosted/executors/deploy-executors-terraform.mdx
@@ -210,8 +210,8 @@ or run the following command.
 ```shell
 $ gcloud compute instances list
 NAME                                          ZONE           MACHINE_TYPE   PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP    STATUS
-sourcegraph-executor-h0rv                     us-central1-c  n1-standard-4               10.0.1.16                   RUNNING
-sourcegraph-executors-docker-registry-mirror  us-central1-c  n1-standard-2               10.0.1.2                    RUNNING
+sourcegraph-executor-h0rv                     us-central1-c  c2-standard-8               10.0.1.16                   RUNNING
+sourcegraph-executors-docker-registry-mirror  us-central1-c  n2-standard-2               10.0.1.2                    RUNNING
 ```
 
 You can ssh into to the instance to ensure the service is running. You can open an ssh connection either via the GCP
@@ -318,12 +318,10 @@ module "my-credentials" {
   source  = "sourcegraph/executors/<aws | google>//modules/credentials"
   version = "<version>"
 
-  # AWS
-  availability_zone = "<availability zone to provision resource in AWS>" # Removed in 4.2
-  # Google
-  zone              = "<zone to provision resource in GCP>" # Removed in 4.1
+  resource_prefix = "<optional prefix to add to created resources>"
 
-  resource_prefix = "<optional prefix to added to created resources>"
+  # AWS only (optional)
+  # permissions_boundary_arn = "<ARN of IAM permissions boundary policy>"
 }
 
 # AWS

From 8feb599ab4d70cffd40113faa6e77f3d3b012863 Mon Sep 17 00:00:00 2001
From: Warren Gifford <warrenbruceg@gmail.com>
Date: Tue, 7 Jul 2026 21:37:30 -0700
Subject: [PATCH 4/8] examples

---
 .../self-hosted/executors/deploy-executors-terraform.mdx | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/self-hosted/executors/deploy-executors-terraform.mdx b/docs/self-hosted/executors/deploy-executors-terraform.mdx
index 394207d79..712250363 100644
--- a/docs/self-hosted/executors/deploy-executors-terraform.mdx
+++ b/docs/self-hosted/executors/deploy-executors-terraform.mdx
@@ -33,6 +33,7 @@ module "executors" {
 
   executor_instance_tag                        = "<tag to filter in stackdriver monitoring>"
   executor_metrics_environment_label           = "<label to filter custom metrics>"
+  executor_use_firecracker                     = true
 }
 ```
 
@@ -47,6 +48,7 @@ module "executors" {
 | `executor_queue_names`                         | The multiple queues from which the executor should pull jobs - one or more of [`codeintel`](/code-navigation/auto-indexing) and [`batches`](/batch-changes/server-side). Either this or `executor_queue_name` must be set. |
 | `executor_instance_tag`                        | A label tag to add to all the executors; can be used for filtering out the right instances in stackdriver monitoring                                                                                                       |
 | `executor_metrics_environment_label`           | The value for environment by which to filter the custom metrics.                                                                                                                                                           |
+| `executor_use_firecracker`                     | Whether to use [Firecracker](/self-hosted/executors/firecracker) sandboxing for job execution. Requires bare metal instances (AWS) or nested virtualization (GCP). Defaults to `false`.                                    |
 
 See the Terraform Modules for additional configurations.
 
@@ -161,6 +163,13 @@ queue.
 -   [AWS example](https://github.com/sourcegraph/terraform-aws-executors/tree/main/examples/multiple-executors)
 -   [Google example](https://github.com/sourcegraph/terraform-google-executors/tree/main/examples/multiple-executors)
 
+### Private Single Executor
+
+The following examples provision a single executor in a private network (no public IP). On AWS, a NAT Gateway is used for outbound traffic. On GCP, Cloud NAT provides the same functionality.
+
+-   [AWS example](https://github.com/sourcegraph/terraform-aws-executors/tree/main/examples/private-single-executor)
+-   [Google example](https://github.com/sourcegraph/terraform-google-executors/tree/main/examples/private-single-executor)
+
 ### Step-by-step Guide
 
 The following is a step-by-step guide on provisioning a single `codeintel` executor on GCP.

From 1887826c12ddefaa0b2da9e64546cd396017d6ed Mon Sep 17 00:00:00 2001
From: Warren Gifford <warrenbruceg@gmail.com>
Date: Tue, 7 Jul 2026 21:42:47 -0700
Subject: [PATCH 5/8] update with new field options

---
 .../executors/deploy-executors-terraform.mdx           | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/docs/self-hosted/executors/deploy-executors-terraform.mdx b/docs/self-hosted/executors/deploy-executors-terraform.mdx
index 712250363..622df2dca 100644
--- a/docs/self-hosted/executors/deploy-executors-terraform.mdx
+++ b/docs/self-hosted/executors/deploy-executors-terraform.mdx
@@ -49,6 +49,10 @@ module "executors" {
 | `executor_instance_tag`                        | A label tag to add to all the executors; can be used for filtering out the right instances in stackdriver monitoring                                                                                                       |
 | `executor_metrics_environment_label`           | The value for environment by which to filter the custom metrics.                                                                                                                                                           |
 | `executor_use_firecracker`                     | Whether to use [Firecracker](/self-hosted/executors/firecracker) sandboxing for job execution. Requires bare metal instances (AWS) or nested virtualization (GCP). Defaults to `false`.                                    |
+| `private_networking`                           | If `true`, the executors and Docker registry mirror will live in a private subnet and communicate with the internet through NAT (NAT Gateway on AWS, Cloud NAT on GCP). Defaults to `false`. See the [Private Single Executor](#private-single-executor) example. |
+| `randomize_resource_names`                     | Use randomized names for resources. Defaults to `false`. On GCP, enabling this on existing deployments will **recreate** executor resources. On AWS, existing resources are updated in-place.                              |
+| `permissions_boundary_arn`                     | (**AWS only**) The ARN of an IAM policy to use as the [permissions boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) for IAM roles and users created by the module. Optional.  |
+| `private_ca_cert_path`                         | Path to a private CA certificate file. Use this when executors need to communicate with a Sourcegraph instance that uses a certificate signed by a private/internal CA. Optional.                                          |
 
 See the Terraform Modules for additional configurations.
 
@@ -433,9 +437,15 @@ module "executors" {
 
   executor_sourcegraph_external_url            = "<external url>"
   executor_sourcegraph_executor_proxy_password = "<shared secret>"
+
+  # Either:
   executor_queue_name                          = "<codeintel | batches>"
+  # Or:
+  executor_queue_names                         = ["codeintel", "batches"]
+
   executor_instance_tag                        = "<tag to filter in stackdriver monitoring>"
   executor_metrics_environment_label           = "<label to filter custom metrics>"
+  executor_use_firecracker                     = true
 }
 ```
 

From 7fdd6ff676557c0fbd9bfd06be20fac0e4eb3029 Mon Sep 17 00:00:00 2001
From: Warren Gifford <warrenbruceg@gmail.com>
Date: Tue, 7 Jul 2026 22:41:03 -0700
Subject: [PATCH 6/8] split terraform docs into two seperate docs one for aws
 one for gcp

---
 .../deploy-executors-terraform-aws.mdx        | 350 ++++++++++++++
 .../deploy-executors-terraform-gcp.mdx        | 362 ++++++++++++++
 .../executors/deploy-executors-terraform.mdx  | 455 +-----------------
 .../executors/deploy-executors.mdx            |   2 +-
 docs/self-hosted/index.mdx                    |   2 +-
 5 files changed, 718 insertions(+), 453 deletions(-)
 create mode 100644 docs/self-hosted/executors/deploy-executors-terraform-aws.mdx
 create mode 100644 docs/self-hosted/executors/deploy-executors-terraform-gcp.mdx

diff --git a/docs/self-hosted/executors/deploy-executors-terraform-aws.mdx b/docs/self-hosted/executors/deploy-executors-terraform-aws.mdx
new file mode 100644
index 000000000..cf3b9f21d
--- /dev/null
+++ b/docs/self-hosted/executors/deploy-executors-terraform-aws.mdx
@@ -0,0 +1,350 @@
+# Deploying Sourcegraph executors using Terraform on AWS
+
+A [Terraform module](https://github.com/sourcegraph/terraform-aws-executors) is provided to
+provision machines running executors on AWS.
+
+See also: [Deploying on Google Cloud](/self-hosted/executors/deploy-executors-terraform-gcp)
+
+## Basic Definition
+
+The following is the minimum required definition to deploy an executor on AWS.
+
+```terraform
+module "executors" {
+  source  = "sourcegraph/executors/aws"
+
+  # Find the latest version matching your Sourcegraph version here:
+  # https://github.com/sourcegraph/terraform-aws-executors/tags
+  version = "<version>"
+
+  availability_zone = "<availability zone to provision resources in>"
+
+  executor_sourcegraph_external_url            = "<external url>"
+  executor_sourcegraph_executor_proxy_password = "<shared secret>"
+
+  # Either:
+  executor_queue_name                          = "<codeintel | batches>"
+  # Or:
+  executor_queue_names                         = ["codeintel", "batches"]
+
+  executor_instance_tag                        = "<tag to filter in monitoring>"
+  executor_metrics_environment_label           = "<label to filter custom metrics>"
+  executor_use_firecracker                     = true
+}
+```
+
+| Variable                                       | Description                                                                                                                                                                                                                |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `availability_zone`                            | The AWS availability zone to create the instance in.                                                                                                                                                                       |
+| `executor_sourcegraph_external_url`            | The public URL of your Sourcegraph instance. This corresponds to the `externalURL` value in your Sourcegraph instance's site configuration and must be resolvable from the provisioned executor compute resources.         |
+| `executor_sourcegraph_executor_proxy_password` | The access token corresponding to the `executors.accessToken` in your Sourcegraph instance's site configuration.                                                                                                           |
+| `executor_queue_name`                          | The single queue from which the executor should pull jobs - [`codeintel`](/code-navigation/auto-indexing) or [`batches`](/batch-changes/server-side). Either this or `executor_queue_names` must be set.                   |
+| `executor_queue_names`                         | The multiple queues from which the executor should pull jobs - one or more of [`codeintel`](/code-navigation/auto-indexing) and [`batches`](/batch-changes/server-side). Either this or `executor_queue_name` must be set. |
+| `executor_instance_tag`                        | A label tag to add to all the executors; can be used for filtering out the right instances in monitoring.                                                                                                                  |
+| `executor_metrics_environment_label`           | The value for environment by which to filter the custom metrics.                                                                                                                                                           |
+| `executor_use_firecracker`                     | Whether to use [Firecracker](/self-hosted/executors/firecracker) sandboxing for job execution. Requires bare metal instances (e.g. `c5n.metal`). Defaults to `true`.                                                      |
+| `private_networking`                           | If `true`, the executors and Docker registry mirror will live in a private subnet and communicate with the internet through a NAT Gateway. Defaults to `false`. See the [Private Single Executor](#private-single-executor) example. |
+| `randomize_resource_names`                     | Use randomized names for resources. Defaults to `false`. Existing resources are updated in-place when enabled.                                                                                                             |
+| `permissions_boundary_arn`                     | The ARN of an IAM policy to use as the [permissions boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) for IAM roles and users created by the module. Optional.                 |
+| `private_ca_cert_path`                         | Path to a private CA certificate file. Use this when executors need to communicate with a Sourcegraph instance that uses a certificate signed by a private/internal CA. Optional.                                          |
+
+See the [AWS Terraform module variables](https://github.com/sourcegraph/terraform-aws-executors/blob/main/modules/executors/variables.tf) for additional configurations.
+
+## Terraform Version
+
+The executor Terraform modules require Terraform `>= 1.1.0, < 2.0.0`.
+
+## Permissions
+
+Access to get and create in the following resources.
+
+-   Auto Scaling
+-   CloudWatch Logs
+-   EBS (EC2)
+-   EC2 (Elastic Compute Cloud)
+-   IAM (Identity & Access Management)
+-   VPC (Virtual Private Cloud)
+
+## Supported Regions
+
+-   `us-east-1`
+-   `us-east-2`
+-   `us-west-1`
+-   `us-west-2`
+-   `eu-west-1`
+-   `eu-west-2`
+-   `eu-west-3`
+-   `eu-north-1`
+-   `eu-south-1`
+-   `eu-central-1`
+-   `ap-northeast-1`
+-   `ap-northeast-2`
+-   `ap-southeast-1`
+-   `ap-southeast-2`
+-   `ap-southeast-3`
+-   `ap-east-1`
+-   `ap-south-1`
+-   `sa-east-1`
+-   `me-south-1`
+-   `af-south-1`
+-   `ca-central-1`
+
+## Examples
+
+### Single Executor
+
+Provisions a single executor to pull from the `codeintel` queue.
+
+-   [AWS example](https://github.com/sourcegraph/terraform-aws-executors/tree/main/examples/single-executor)
+
+### Multiple Executors
+
+Provisions two executors, one to pull from the `codeintel` queue and the other for the `batches` queue.
+
+-   [AWS example](https://github.com/sourcegraph/terraform-aws-executors/tree/main/examples/multiple-executors)
+
+### Private Single Executor
+
+Provisions a single executor in a private subnet (no public IP). A NAT Gateway is used for outbound internet traffic.
+
+-   [AWS example](https://github.com/sourcegraph/terraform-aws-executors/tree/main/examples/private-single-executor)
+
+## Step-by-step Guide
+
+The following is a step-by-step guide on provisioning a single `codeintel` executor on AWS.
+
+### Provision
+
+1. [Install Terraform](#terraform-version).
+2. Install the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
+3. Run `aws configure` to set up your credentials and default region.
+4. Set up your Sourcegraph instance's Site configuration for executors
+    1. Click on your profile picture in the top right corner
+    2. Select **Site admin**
+    3. Expand the **Configuration** section
+    4. Select **Site configuration**
+    5. Set the following,
+        - `"externalURL": "<URL>"`
+            - A URL that is accessible from the EC2 instance (e.g. a public URL such as `https://sourcegraph.example.com`)
+        - `"executors.accessToken": "<new long secret>"`
+            - Can be generated by running `cat /dev/random | base64 | head -c 20`
+            - The secret will be displayed as `REDACTED` once it's saved.
+        - `"codeIntelAutoIndexing.enabled": true`
+            - _This is only for `codeintel` executors._
+5. Download the [example files](https://github.com/sourcegraph/terraform-aws-executors/tree/main/examples/single-executor).
+6. Change the following in `providers.tf`
+    - `region` to the AWS region to provision the executor in
+7. Change the following in `main.tf`
+    - `availability_zone` to an availability zone within your chosen region (e.g. `us-west-2a`)
+    - `executor_sourcegraph_external_url` to the URL configured in your instance's **Site configuration**
+    - `executor_sourcegraph_executor_proxy_password` to the access token configured in your instance's **Site configuration**
+8. Run `terraform init` to download the Sourcegraph executor modules.
+9. Run `terraform plan` to preview the changes that will occur to your AWS infrastructure.
+10. Run `terraform apply` and enter "yes" after reviewing the proposed changes to create the executor resources.
+    - Ensure `terraform apply` exited with code 0 and did not print any errors
+11. Go back to the site admin page, expand **Executors**, click **Instances**, and check to see if your executor shows up in the list with a green dot 🟢
+
+### Validation
+
+The following can be done to troubleshoot or double-check that the executor has been properly provisioned.
+
+Ensure the executor instance is running. Either go to **EC2 → Instances** in the AWS Console or run the following command.
+
+```shell
+$ aws ec2 describe-instances \
+    --filters "Name=tag:executor_tag,Values=<your executor_instance_tag>" \
+              "Name=instance-state-name,Values=running" \
+    --query "Reservations[].Instances[].[InstanceId,InstanceType,State.Name,PrivateIpAddress]" \
+    --output table
+-------------------------------------------------------------------
+|                       DescribeInstances                         |
++----------------------+-------------+---------+------------------+
+|  i-0abc123def456789  | c5n.metal   | running |  10.0.1.42       |
++----------------------+-------------+---------+------------------+
+```
+
+You can connect to the instance using [AWS Systems Manager Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager.html) (if the instance has the SSM agent and appropriate IAM role) or via SSH.
+
+```shell
+# Using SSM (no SSH key required)
+aws ssm start-session --target i-0abc123def456789
+
+# Using SSH (requires the key pair configured in the module)
+ssh -i <key-pair>.pem ubuntu@<instance-public-ip>
+```
+
+Then run the following command to check if the service is running.
+
+```shell
+ubuntu@ip-10-0-1-42:~$ systemctl status executor
+🟢 executor.service - User code executor
+     Loaded: loaded (/etc/systemd/system/executor.service; enabled; vendor preset: enabled)
+     Active: active (running) since Thu 2021-11-18 02:28:48 UTC; 19s ago
+```
+
+To check the logs, you can either query **CloudWatch Logs** in the AWS Console or run the following command while connected to the instance.
+
+```shell
+ubuntu@ip-10-0-1-42:~$ journalctl -u executor | less
+```
+
+Ensure the `EXECUTOR_FRONTEND_URL` and `EXECUTOR_FRONTEND_PASSWORD` in `/etc/systemd/system/executor.env` are correct.
+
+```shell
+cat /etc/systemd/system/executor.env
+```
+
+Ensure the instance can reach your `externalURL`:
+
+```shell
+ubuntu@ip-10-0-1-42:~$ curl <your externalURL here>
+<a href="/sign-in?returnTo=%2F">Found</a>
+```
+
+### Configure Auto-indexing
+
+1. Go to the **Site admin** page
+2. Expand **Code graph**,
+3. Select **Configuration**
+4. Click **Create new policy**, and fill in:
+    - Name: `TEST`
+    - Click _add a repository pattern_
+    - Repository pattern #1: set this to an existing repository on your Sourcegraph instance (
+      e.g. `github.com/gorilla/mux`)
+    - Type: `HEAD`
+    - Retention: Disabled
+    - Auto-indexing: Enabled
+5. Expand **Code graph**
+6. Select **Auto-indexing**, and check to see if an indexing job has appeared. If nothing is there:
+    - Try clicking **Enqueue**
+    - Try setting a higher update frequency: `PRECISE_CODE_INTEL_AUTO_INDEXING_TASK_INTERVAL=10s`
+    - Try setting a lower delay: `PRECISE_CODE_INTEL_AUTO_INDEXING_REPOSITORY_PROCESS_DELAY=10s`
+7. Once you have a completed indexing job, click **Uploads** and check to see that an index has been uploaded.
+8. Once the index has been uploaded, you should see the **`PRECISE`** badge in the hover! 🎉
+
+## Auto-scaling
+
+> NOTE: Auto scaling is currently not supported
+> when [downloading and running executor binaries yourself](/self-hosted/executors/deploy-executors-binary),
+> and on managed instances when using self-hosted executors, since it requires deployment adjustments.
+
+Auto-scaling of executor instances can help to increase concurrency of jobs, without paying for unused resources. With auto-scaling, you can scale down to 0 instances when no workload exist and scale up as far as you like and your cloud provider can support. Auto-scaling needs to be configured separately.
+
+Auto-scaling makes use of **AutoScalingGroups** on AWS. Sourcegraph's `worker` service publishes a scaling metric (that is, the number of jobs in queue) to CloudWatch. Then, based on that reported value, the auto-scaler adds and removes compute resources to match the required amount of compute. The autoscaler will attempt to hold 1 instance running per each `executor_jobs_per_instance_scaling` items in queue.
+
+For example, if `executor_jobs_per_instance_scaling` is set to `20` and the queue size is currently `400`, then `20` instances would be determined as required to handle the load. You might want to tweak this number based on the `machine_type`, `maximum_num_jobs` (concurrency per machine), and desired processing speed. See the [AWS variable definitions](https://github.com/sourcegraph/terraform-aws-executors/blob/main/modules/executors/variables.tf) for details.
+
+With the Terraform variables `executor_min_replicas` and `executor_max_replicas`, you can configure the minimum and maximum number of compute machines to be run at a given time.
+
+For auto-scaling to work, two things must be true:
+
+1. `executor_min_replicas` must be `>= 0` and `executor_max_replicas` must be `> executor_min_replicas`.
+2. The Sourcegraph instance (its `worker` service, specifically) needs to publish scaling metrics to CloudWatch.
+
+For the latter to work, the Sourcegraph instance needs to be configured with the correct credentials that allow it to access AWS.
+
+The `credentials` submodule in the [AWS executor module](https://github.com/sourcegraph/terraform-aws-executors/tree/main/modules/credentials) exists for that purpose. When used, the `credentials` module sets up an IAM user with permission to write CloudWatch metrics and returns the access key in the Terraform outputs.
+
+Here's an example of how one would configure auto-scaling.
+
+```terraform
+module "executors" {
+  source  = "sourcegraph/executors/aws"
+  version = "<version>"
+
+  # Basic configuration...
+
+  # Auto-scaling
+  executor_min_replicas              = 0 # Spin down when not in use
+  executor_max_replicas              = 30
+  executor_jobs_per_instance_scaling = 20
+}
+
+module "my-credentials" {
+  source  = "sourcegraph/executors/aws//modules/credentials"
+  version = "<version>"
+
+  resource_prefix          = "<optional prefix to add to created resources>"
+  # permissions_boundary_arn = "<ARN of IAM permissions boundary policy>"
+}
+
+output "metric_writer_access_key_id" {
+  value = module.my-credentials.metric_writer_access_key_id
+}
+
+output "metric_writer_secret_key" {
+  value     = module.my-credentials.metric_writer_secret_key
+  sensitive = true
+}
+```
+
+After running `terraform apply`, retrieve the credentials by running the following commands.
+
+```shell
+$ terraform output metric_writer_access_key_id
+$ terraform output metric_writer_secret_key
+```
+
+### Configuring the Sourcegraph instance
+
+The AWS EC2 auto-scaling groups configured by the Sourcegraph Terraform module respond to changes in metric values written to **CloudWatch**. The target Sourcegraph instance is expected to continuously write these values.
+
+To write the scaling metric to **CloudWatch**, the `worker` service must have defined the following environment variables.
+
+| Environment Variable                    | Description                                              |
+| --------------------------------------- | -------------------------------------------------------- |
+| `EXECUTOR_METRIC_ENVIRONMENT_LABEL`     | Same value as `executor_metrics_environment_label`       |
+| `EXECUTOR_METRIC_AWS_NAMESPACE`         | Must be set to `sourcegraph-executor`                    |
+| `EXECUTOR_METRIC_AWS_REGION`            | The target AWS region                                    |
+| `EXECUTOR_METRIC_AWS_ACCESS_KEY_ID`     | The value of the output of `metric_writer_access_key_id` |
+| `EXECUTOR_METRIC_AWS_SECRET_ACCESS_KEY` | The value of the output of `metric_writer_secret_key`    |
+
+### Testing auto scaling
+
+Once the environment variables have been set and the worker service has been restarted, you should be able to find the scaling metrics in **CloudWatch**.
+
+To test if the metric is correctly reported: go to the **CloudWatch** metrics section. Under **All metrics**, select the namespace `sourcegraph-executor` and then the metric `environment`, `queueName`. Make sure there are entries returned.
+
+Next, you can test whether the number of executors rises and shrinks as load spikes occur. Keep in mind that auto-scaling is not a real-time operation and usually takes a short moment and can have some delays between the metric going down and the desired machine count adjusting.
+
+## Upgrading executors
+
+Upgrading executors is relatively uninvolved. Simply follow the instructions below.
+Also, check the [changelog](https://sourcegraph.com/changelog) for any Executors related breaking changes or new features or flags that you might want to configure. See [Executors maintenance](/self-hosted/executors/deploy-executors#Maintaining-and-upgrading-executors) for version compatibility.
+
+### **Step 1:** Update the source version of the terraform modules
+
+> NOTE: Keep in mind that only one minor version bumps are guaranteed to be disruption-free.
+
+```diff
+module "executors" {
+  source = "sourcegraph/executors/aws"
+
+  # Find the latest version matching your Sourcegraph version here:
+  # https://github.com/sourcegraph/terraform-aws-executors/tags
+-  version = "7.3.0"
++  version = "7.4.0"
+
+  availability_zone = "<availability zone>"
+
+  executor_sourcegraph_external_url            = "<external url>"
+  executor_sourcegraph_executor_proxy_password = "<shared secret>"
+
+  # Either:
+  executor_queue_name                          = "<codeintel | batches>"
+  # Or:
+  executor_queue_names                         = ["codeintel", "batches"]
+
+  executor_instance_tag                        = "<tag to filter in monitoring>"
+  executor_metrics_environment_label           = "<label to filter custom metrics>"
+  executor_use_firecracker                     = true
+}
+```
+
+### **Step 2:** Reapply the terraform configuration
+
+Simply reapply the terraform configuration and executors will be ready to go again.
+
+```bash
+terraform apply
+```
diff --git a/docs/self-hosted/executors/deploy-executors-terraform-gcp.mdx b/docs/self-hosted/executors/deploy-executors-terraform-gcp.mdx
new file mode 100644
index 000000000..919c05b1e
--- /dev/null
+++ b/docs/self-hosted/executors/deploy-executors-terraform-gcp.mdx
@@ -0,0 +1,362 @@
+# Deploying Sourcegraph executors using Terraform on Google Cloud
+
+A [Terraform module](https://github.com/sourcegraph/terraform-google-executors) is provided to
+provision machines running executors on Google Cloud.
+
+See also: [Deploying on AWS](/self-hosted/executors/deploy-executors-terraform-aws)
+
+## Basic Definition
+
+The following is the minimum required definition to deploy an executor on Google Cloud.
+
+```terraform
+module "executors" {
+  source  = "sourcegraph/executors/google"
+
+  # Find the latest version matching your Sourcegraph version here:
+  # https://github.com/sourcegraph/terraform-google-executors/tags
+  version = "<version>"
+
+  region = "<region to provision in>"
+  zone   = "<zone to provision resources in>"
+
+  executor_sourcegraph_external_url            = "<external url>"
+  executor_sourcegraph_executor_proxy_password = "<shared secret>"
+
+  # Either:
+  executor_queue_name                          = "<codeintel | batches>"
+  # Or:
+  executor_queue_names                         = ["codeintel", "batches"]
+
+  executor_instance_tag                        = "<tag to filter in stackdriver monitoring>"
+  executor_metrics_environment_label           = "<label to filter custom metrics>"
+  executor_use_firecracker                     = true
+}
+```
+
+| Variable                                       | Description                                                                                                                                                                                                                |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `region`                                       | The Google Cloud region to provision the executor resources in.                                                                                                                                                            |
+| `zone`                                         | The Google Cloud zone to provision the executor resources in.                                                                                                                                                              |
+| `executor_sourcegraph_external_url`            | The public URL of your Sourcegraph instance. This corresponds to the `externalURL` value in your Sourcegraph instance's site configuration and must be resolvable from the provisioned executor compute resources.         |
+| `executor_sourcegraph_executor_proxy_password` | The access token corresponding to the `executors.accessToken` in your Sourcegraph instance's site configuration.                                                                                                           |
+| `executor_queue_name`                          | The single queue from which the executor should pull jobs - [`codeintel`](/code-navigation/auto-indexing) or [`batches`](/batch-changes/server-side). Either this or `executor_queue_names` must be set.                   |
+| `executor_queue_names`                         | The multiple queues from which the executor should pull jobs - one or more of [`codeintel`](/code-navigation/auto-indexing) and [`batches`](/batch-changes/server-side). Either this or `executor_queue_name` must be set. |
+| `executor_instance_tag`                        | A label tag to add to all the executors; can be used for filtering out the right instances in stackdriver monitoring.                                                                                                      |
+| `executor_metrics_environment_label`           | The value for environment by which to filter the custom metrics.                                                                                                                                                           |
+| `executor_use_firecracker`                     | Whether to use [Firecracker](/self-hosted/executors/firecracker) sandboxing for job execution. Requires nested virtualization support. Defaults to `true`.                                                                |
+| `private_networking`                           | If `true`, the executors and Docker registry mirror will live in a private subnet and communicate with the internet through Cloud NAT. Defaults to `false`. See the [Private Single Executor](#private-single-executor) example. |
+| `randomize_resource_names`                     | Use randomized names for resources. Defaults to `false`. Enabling this on existing deployments will **recreate** executor resources.                                                                                       |
+| `private_ca_cert_path`                         | Path to a private CA certificate file. Use this when executors need to communicate with a Sourcegraph instance that uses a certificate signed by a private/internal CA. Optional.                                          |
+
+See the [Google Cloud Terraform module variables](https://github.com/sourcegraph/terraform-google-executors/blob/main/modules/executors/variables.tf) for additional configurations.
+
+## Terraform Version
+
+The executor Terraform modules require Terraform `>= 1.1.0, < 2.0.0`.
+
+## Permissions
+
+Ensure the [IAM API](https://console.cloud.google.com/apis/api/iam.googleapis.com/overview) is enabled.
+
+-   appengine.applications.get
+-   clientauthconfig.brands.\*
+-   clientauthconfig.clients.\*
+-   cloudasset.assets.searchAllResources
+-   cloudnotifications.activities.list
+-   cloudtrace.insights.get
+-   cloudtrace.insights.list
+-   cloudtrace.stats.get
+-   cloudtrace.tasks.\*
+-   cloudtrace.traces.list
+-   compute.addresses.\*
+-   compute.autoscalers.\*
+-   compute.disks.\*
+-   compute.firewalls.\*
+-   compute.globalOperations.get
+-   compute.instanceGroupManagers.\*
+-   compute.instanceGroups.create
+-   compute.instances.\*
+-   compute.instanceTemplates.\*
+-   compute.networks.\*
+-   compute.regionOperations.get
+-   compute.subnetworks.\*
+-   compute.zoneOperations.get
+-   compute.zones.get
+-   container.clusters.list
+-   iam.roles.\*
+-   iam.serviceAccountKeys.\*
+-   logging.logEntries.list
+-   logging.privateLogEntries.list
+-   monitoring.timeSeries.list
+-   oauthconfig.testusers.update
+-   oauthconfig.verification.update
+-   orgpolicy.policy.get
+-   resourcemanager.projects.\*
+-   secretmanager.locations.list
+-   secretmanager.secrets.\*
+-   secretmanager.versions.\*
+
+## Supported Regions
+
+All regions are supported.
+
+## Examples
+
+### Single Executor
+
+Provisions a single executor to pull from the `codeintel` queue.
+
+-   [Google Cloud example](https://github.com/sourcegraph/terraform-google-executors/tree/main/examples/single-executor)
+
+### Multiple Executors
+
+Provisions two executors, one to pull from the `codeintel` queue and the other for the `batches` queue.
+
+-   [Google Cloud example](https://github.com/sourcegraph/terraform-google-executors/tree/main/examples/multiple-executors)
+
+### Private Single Executor
+
+Provisions a single executor in a private subnet (no public IP). Cloud NAT is used for outbound internet traffic.
+
+-   [Google Cloud example](https://github.com/sourcegraph/terraform-google-executors/tree/main/examples/private-single-executor)
+
+## Step-by-step Guide
+
+The following is a step-by-step guide on provisioning a single `codeintel` executor on Google Cloud.
+
+### Provision
+
+1. [Install Terraform](#terraform-version).
+2. Install the [`gcloud CLI`](https://cloud.google.com/sdk/docs/install)
+3. Run `gcloud auth application-default login`
+4. Set up your Sourcegraph instance's Site configuration for executors
+    1. Click on your profile picture in the top right corner
+    2. Select **Site admin**
+    3. Expand the **Configuration** section
+    4. Select **Site configuration**
+    5. Set the following,
+        - `"externalURL": "<URL>"`
+            - A URL that is accessible from the GCP VM (e.g. a public URL such as `https://sourcegraph.example.com`)
+        - `"executors.accessToken": "<new long secret>"`
+            - Can be generated by running `cat /dev/random | base64 | head -c 20`
+            - The secret will be displayed as `REDACTED` once it's saved.
+        - `"codeIntelAutoIndexing.enabled": true`
+            - _This is only for `codeintel` executors._
+5. Download
+   the [example files](https://github.com/sourcegraph/terraform-google-executors/tree/main/examples/single-executor)
+6. Change the following in `providers.tf`
+    - `project` to the GCP project to provision the executor in
+    - `region` to the GCP region to provision the executor in
+    - `zone` to the GCP zone to provision the executor in
+7. Change the following in `main.tf`
+    - `executor_sourcegraph_external_url` to the URL configured in your instance's **Site configuration**
+    - `executor_sourcegraph_executor_proxy_password` to the access token configured in your instance's **Site
+      configuration**
+8. Run `terraform init` to download the Sourcegraph executor modules.
+9. Run `terraform plan` to preview the changes that will occur to your GCP infrastructure.
+10. Run `terraform apply` and enter "yes" after reviewing the proposed changes to create the executor VM
+    - Ensure `terraform apply` exited with code 0 and did not print any errors
+11. Go back to the site admin page, expand **Executors**, click **Instances**, and check to see if your executor shows
+    up in the list with a green dot 🟢
+
+### Validation
+
+The following can be done to troubleshoot or double-check that the executor has been properly provisioned.
+
+Ensure the executor is listed in the Compute Engine. Either go to **Compute Engine** in the GCP Console for your project
+or run the following command.
+
+```shell
+$ gcloud compute instances list
+NAME                                          ZONE           MACHINE_TYPE   PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP    STATUS
+sourcegraph-executor-h0rv                     us-central1-c  c2-standard-8               10.0.1.16                   RUNNING
+sourcegraph-executors-docker-registry-mirror  us-central1-c  n2-standard-2               10.0.1.2                    RUNNING
+```
+
+You can ssh into to the instance to ensure the service is running. You can open an ssh connection either via the GCP
+Console or by running the following command.
+
+```shell
+gcloud compute ssh sourcegraph-executor-h0rv
+```
+
+Then run the following command to check if the service is running.
+
+```shell
+you@sourcegraph-executor-h0rv:~$ systemctl status executor
+🟢 executor.service - User code executor
+     Loaded: loaded (/etc/systemd/system/executor.service; enabled; vendor preset: enabled)
+     Active: active (running) since Thu 2021-11-18 02:28:48 UTC; 19s ago
+```
+
+To check the logs, you can either query the **Log Explorer** in the GCP Console or by running the following command
+while connected to the instance.
+
+```shell
+you@sourcegraph-executor-h0rv:~$ journalctl -u executor | less
+Nov 18 02:31:01 sourcegraph-executor-h0rv executor[2465]: t=2021-11-18T02:31:01+0000 lvl=dbug msg="TRACE internal" host=... path=/.executors/queue/codeintel/dequeue code=204 duration=92.131237ms
+Nov 18 02:31:01 sourcegraph-executor-h0rv executor[2465]: t=2021-11-18T02:31:01+0000 lvl=dbug msg="TRACE internal" host=... path=/.executors/queue/codeintel/canceled code=200 duration=90.630467ms
+Nov 18 02:31:02 sourcegraph-executor-h0rv executor[2465]: t=2021-11-18T02:31:02+0000 lvl=dbug msg="TRACE internal" host=... path=/.executors/queue/codeintel/dequeue code=204 duration=91.269106ms
+Nov 18 02:31:02 sourcegraph-executor-h0rv executor[2465]: t=2021-11-18T02:31:02+0000 lvl=dbug msg="TRACE internal" host=... path=/.executors/queue/codeintel/canceled code=200 duration=161.469685ms
+```
+
+Ensure the `EXECUTOR_FRONTEND_URL` and `EXECUTOR_FRONTEND_PASSWORD` in `/etc/systemd/system/executor.env` are correct
+
+```
+cat /etc/systemd/system/executor.env
+```
+
+Ensure the VM can hit your `externalURL`:
+
+```shell
+you@sourcegraph-executor-h0rv:~$ curl <your externalURL here>
+<a href="/sign-in?returnTo=%2F">Found</a>
+```
+
+### Configure Auto-indexing
+
+1. Go to the **Site admin** page
+2. Expand **Code graph**,
+3. Select **Configuration**
+4. Click **Create new policy**, and fill in:
+    - Name: `TEST`
+    - Click _add a repository pattern_
+    - Repository pattern #1: set this to an existing repository on your Sourcegraph instance (
+      e.g. `github.com/gorilla/mux`)
+    - Type: `HEAD`
+    - Retention: Disabled
+    - Auto-indexing: Enabled
+5. Expand **Code graph**
+6. Select **Auto-indexing**, and check to see if an indexing job has appeared. If nothing is there:
+    - Try clicking **Enqueue**
+    - Try setting a higher update frequency: `PRECISE_CODE_INTEL_AUTO_INDEXING_TASK_INTERVAL=10s`
+    - Try setting a lower delay: `PRECISE_CODE_INTEL_AUTO_INDEXING_REPOSITORY_PROCESS_DELAY=10s`
+7. Once you have a completed indexing job, click **Uploads** and check to see that an index has been uploaded.
+8. Once the index has been uploaded, you should see the **`PRECISE`** badge in the hover! 🎉
+
+## Auto-scaling
+
+> NOTE: Auto scaling is currently not supported
+> when [downloading and running executor binaries yourself](/self-hosted/executors/deploy-executors-binary),
+> and on managed instances when using self-hosted executors, since it requires deployment adjustments.
+
+Auto-scaling of executor instances can help to increase concurrency of jobs, without paying for unused resources. With auto-scaling, you can scale down to 0 instances when no workload exist and scale up as far as you like and your cloud provider can support. Auto-scaling needs to be configured separately.
+
+Auto-scaling makes use of **Instance Groups** on Google Cloud. Sourcegraph's `worker` service publishes a scaling metric (that is, the number of jobs in queue) to Cloud Monitoring. Then, based on that reported value, the auto-scaler adds and removes compute resources to match the required amount of compute. The autoscaler will attempt to hold 1 instance running per each `executor_jobs_per_instance_scaling` items in queue.
+
+For example, if `executor_jobs_per_instance_scaling` is set to `20` and the queue size is currently `400`, then `20` instances would be determined as required to handle the load. You might want to tweak this number based on the `machine_type`, `maximum_num_jobs` (concurrency per machine), and desired processing speed. See the [Google Cloud variable definitions](https://github.com/sourcegraph/terraform-google-executors/blob/main/modules/executors/variables.tf) for details.
+
+With the Terraform variables `executor_min_replicas` and `executor_max_replicas`, you can configure the minimum and maximum number of compute machines to be run at a given time.
+
+For auto-scaling to work, two things must be true:
+
+1. `executor_min_replicas` must be `>= 0` and `executor_max_replicas` must be `> executor_min_replicas`.
+2. The Sourcegraph instance (its `worker` service, specifically) needs to publish scaling metrics to Cloud Monitoring.
+
+For the latter to work, the Sourcegraph instance needs to be configured with the correct credentials that allow it to access Google Cloud.
+
+The `credentials` submodule in the [Google Cloud executor module](https://github.com/sourcegraph/terraform-google-executors/tree/main/modules/credentials) exists for that purpose. When used, the `credentials` module sets up a service account with permission to write Cloud Monitoring metrics and returns the credentials in the Terraform outputs.
+
+Here's an example of how one would configure auto-scaling.
+
+```terraform
+module "executors" {
+  source  = "sourcegraph/executors/google"
+  version = "<version>"
+
+  # Basic configuration...
+
+  # Auto-scaling
+  executor_min_replicas              = 0 # Spin down when not in use
+  executor_max_replicas              = 30
+  executor_jobs_per_instance_scaling = 20
+}
+
+module "my-credentials" {
+  source  = "sourcegraph/executors/google//modules/credentials"
+  version = "<version>"
+
+  resource_prefix = "<optional prefix to add to created resources>"
+}
+
+output "metric_writer_credentials_file" {
+  value     = module.my-credentials.metric_writer_credentials_file
+  sensitive = true
+}
+```
+
+After running `terraform apply`, retrieve the credentials by running the following command.
+
+```shell
+$ terraform output metric_writer_credentials_file
+```
+
+### Configuring the Sourcegraph instance
+
+The Google Compute Engine auto-scaling groups configured by the Sourcegraph Terraform module respond to changes in metric values written to Cloud Monitoring. The target Sourcegraph instance is expected to continuously write these values.
+
+To write the scaling metric to **Cloud Monitoring**, the `worker` service must have defined the following environment variables.
+
+| Environment Variable                | Description                                        |
+| ----------------------------------- | -------------------------------------------------- |
+| `EXECUTOR_METRIC_ENVIRONMENT_LABEL` | Same value as `executor_metrics_environment_label` |
+| `EXECUTOR_METRIC_GCP_PROJECT_ID`    | The GCP Project ID                                 |
+
+Then either one of the following environment variables must be set.
+
+| Environment Variable                                          | Description                                                                                       |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `EXECUTOR_METRIC_GOOGLE_APPLICATION_CREDENTIALS_FILE_CONTENT` | The **base64-decoded** output of `metric_writer_credentials_file`                                 |
+| `EXECUTOR_METRIC_GOOGLE_APPLICATION_CREDENTIALS_FILE`         | The path to the file containing the **base64-decoded** output of `metric_writer_credentials_file` |
+
+### Testing auto scaling
+
+Once the environment variables have been set and the worker service has been restarted, you should be able to find the scaling metrics in **Cloud Monitoring**.
+
+To test if the metric is correctly reported: go to the **Metrics explorer**. Select **Resource type: Global** and then **Metric: `custom/executors/queue/size`**. You should see values reported here. `0` is also an indicator that it works correctly.
+
+Next, you can test whether the number of executors rises and shrinks as load spikes occur. Keep in mind that auto-scaling is not a real-time operation and usually takes a short moment and can have some delays between the metric going down and the desired machine count adjusting.
+
+## Upgrading executors
+
+Upgrading executors is relatively uninvolved. Simply follow the instructions below.
+Also, check the [changelog](https://sourcegraph.com/changelog) for any Executors related breaking changes or new features or flags that you might want to configure. See [Executors maintenance](/self-hosted/executors/deploy-executors#Maintaining-and-upgrading-executors) for version compatibility.
+
+### **Step 1:** Update the source version of the terraform modules
+
+> NOTE: Keep in mind that only one minor version bumps are guaranteed to be disruption-free.
+
+```diff
+module "executors" {
+  source = "sourcegraph/executors/google"
+
+  # Find the latest version matching your Sourcegraph version here:
+  # https://github.com/sourcegraph/terraform-google-executors/tags
+-  version = "7.3.0"
++  version = "7.4.0"
+
+  region = "<region>"
+  zone   = "<zone>"
+
+  executor_sourcegraph_external_url            = "<external url>"
+  executor_sourcegraph_executor_proxy_password = "<shared secret>"
+
+  # Either:
+  executor_queue_name                          = "<codeintel | batches>"
+  # Or:
+  executor_queue_names                         = ["codeintel", "batches"]
+
+  executor_instance_tag                        = "<tag to filter in stackdriver monitoring>"
+  executor_metrics_environment_label           = "<label to filter custom metrics>"
+  executor_use_firecracker                     = true
+}
+```
+
+### **Step 2:** Reapply the terraform configuration
+
+Simply reapply the terraform configuration and executors will be ready to go again.
+
+```bash
+terraform apply
+```
diff --git a/docs/self-hosted/executors/deploy-executors-terraform.mdx b/docs/self-hosted/executors/deploy-executors-terraform.mdx
index 622df2dca..31f124692 100644
--- a/docs/self-hosted/executors/deploy-executors-terraform.mdx
+++ b/docs/self-hosted/executors/deploy-executors-terraform.mdx
@@ -1,458 +1,11 @@
-# Deploying Sourcegraph executors using Terraform on AWS or GCP
+# Deploying Sourcegraph executors using Terraform
 
 [Terraform modules](https://learn.hashicorp.com/tutorials/terraform/module-use?in=terraform/modules) are provided to
-provision machines running executors on [AWS](https://github.com/sourcegraph/terraform-aws-executors)
-and [Google Cloud](https://github.com/sourcegraph/terraform-google-executors).
+provision machines running executors on AWS and Google Cloud. Choose your cloud provider:
 
-## Basic Definition
-
-The following is the minimum required definition to deploy an executor.
-
-```terraform
-module "executors" {
-  source = "sourcegraph/executors/<aws | google>"
-
-  # Find the latest version matching your Sourcegraph version here:
-  # - https://github.com/sourcegraph/terraform-google-executors/tags
-  # - https://github.com/sourcegraph/terraform-aws-executors/tags
-  version = "<version>"
-
-  # AWS specific
-  availability_zone = "<availability zone to provision resource in AWS>"
-  # Google specific
-  region            = "<region to provision in GCP>"
-  zone              = "<zone to provision resource in GCP>"
-
-  executor_sourcegraph_external_url            = "<external url>"
-  executor_sourcegraph_executor_proxy_password = "<shared secret>"
-
-  # Either:
-  executor_queue_name                          = "<codeintel | batches>"
-  # Or:
-  executor_queue_names                         = ["codeintel", "batches"]
-
-  executor_instance_tag                        = "<tag to filter in stackdriver monitoring>"
-  executor_metrics_environment_label           = "<label to filter custom metrics>"
-  executor_use_firecracker                     = true
-}
-```
-
-| Variable                                       | Description                                                                                                                                                                                                                |
-| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `availability_zone`                            | The **AWS** availability zone to create the instance in                                                                                                                                                                    |
-| `region`                                       | The **Google** region to provision the executor resources in.                                                                                                                                                              |
-| `zone`                                         | The **Google** zone to provision the executor resources in.                                                                                                                                                                |
-| `executor_sourcegraph_external_url`            | The public URL of your Sourcegraph instance. This corresponds to the `externalURL` value in your Sourcegraph instance’s site configuration and must be resolvable from the provisioned executor compute resources.         |
-| `executor_sourcegraph_executor_proxy_password` | The access token corresponding to the `executors.accessToken` in your Sourcegraph instance's site configuration.                                                                                                           |
-| `executor_queue_name`                          | The single queue from which the executor should pull jobs - [`codeintel`](/code-navigation/auto-indexing) or [`batches`](/batch-changes/server-side). Either this or `executor_queue_names` must be set.                   |
-| `executor_queue_names`                         | The multiple queues from which the executor should pull jobs - one or more of [`codeintel`](/code-navigation/auto-indexing) and [`batches`](/batch-changes/server-side). Either this or `executor_queue_name` must be set. |
-| `executor_instance_tag`                        | A label tag to add to all the executors; can be used for filtering out the right instances in stackdriver monitoring                                                                                                       |
-| `executor_metrics_environment_label`           | The value for environment by which to filter the custom metrics.                                                                                                                                                           |
-| `executor_use_firecracker`                     | Whether to use [Firecracker](/self-hosted/executors/firecracker) sandboxing for job execution. Requires bare metal instances (AWS) or nested virtualization (GCP). Defaults to `false`.                                    |
-| `private_networking`                           | If `true`, the executors and Docker registry mirror will live in a private subnet and communicate with the internet through NAT (NAT Gateway on AWS, Cloud NAT on GCP). Defaults to `false`. See the [Private Single Executor](#private-single-executor) example. |
-| `randomize_resource_names`                     | Use randomized names for resources. Defaults to `false`. On GCP, enabling this on existing deployments will **recreate** executor resources. On AWS, existing resources are updated in-place.                              |
-| `permissions_boundary_arn`                     | (**AWS only**) The ARN of an IAM policy to use as the [permissions boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) for IAM roles and users created by the module. Optional.  |
-| `private_ca_cert_path`                         | Path to a private CA certificate file. Use this when executors need to communicate with a Sourcegraph instance that uses a certificate signed by a private/internal CA. Optional.                                          |
-
-See the Terraform Modules for additional configurations.
-
--   [AWS](https://github.com/sourcegraph/terraform-aws-executors/blob/main/modules/executors/variables.tf)
--   [Google](https://github.com/sourcegraph/terraform-google-executors/blob/main/modules/executors/variables.tf)
+-   [AWS](/self-hosted/executors/deploy-executors-terraform-aws) — using the [`sourcegraph/executors/aws`](https://github.com/sourcegraph/terraform-aws-executors) module
+-   [Google Cloud](/self-hosted/executors/deploy-executors-terraform-gcp) — using the [`sourcegraph/executors/google`](https://github.com/sourcegraph/terraform-google-executors) module
 
 ## Terraform Version
 
 The executor Terraform modules require Terraform `>= 1.1.0, < 2.0.0`.
-
-## Permissions
-
-In order to provision executor resources, specific permissions must be granted.
-
-### AWS
-
-Access to get and create in the following resources.
-
--   Auto Scaling
--   CloudWatch Logs
--   EBS (EC2)
--   EC2 (Elastic Compute Cloud)
--   IAM (Identity & Access Management)
--   VPC (Virtual Private Cloud)
-
-### Google
-
-Ensure the [IAM API](https://console.cloud.google.com/apis/api/iam.googleapis.com/overview) is enabled.
-
--   appengine.applications.get
--   clientauthconfig.brands.\*
--   clientauthconfig.clients.\*
--   cloudasset.assets.searchAllResources
--   cloudnotifications.activities.list
--   cloudtrace.insights.get
--   cloudtrace.insights.list
--   cloudtrace.stats.get
--   cloudtrace.tasks.\*
--   cloudtrace.traces.list
--   compute.addresses.\*
--   compute.autoscalers.\*
--   compute.disks.\*
--   compute.firewalls.\*
--   compute.globalOperations.get
--   compute.instanceGroupManagers.\*
--   compute.instanceGroups.create
--   compute.instances.\*
--   compute.instanceTemplates.\*
--   compute.networks.\*
--   compute.regionOperations.get
--   compute.subnetworks.\*
--   compute.zoneOperations.get
--   compute.zones.get
--   container.clusters.list
--   iam.roles.\*
--   iam.serviceAccountKeys.\*
--   logging.logEntries.list
--   logging.privateLogEntries.list
--   monitoring.timeSeries.list
--   oauthconfig.testusers.update
--   oauthconfig.verification.update
--   orgpolicy.policy.get
--   resourcemanager.projects.\*
--   secretmanager.locations.list
--   secretmanager.secrets.\*
--   secretmanager.versions.\*
-
-## Supported Regions
-
-### AWS
-
--   `us-east-1`
--   `us-east-2`
--   `us-west-1`
--   `us-west-2`
--   `eu-west-1`
--   `eu-west-2`
--   `eu-west-3`
--   `eu-north-1`
--   `eu-south-1`
--   `eu-central-1`
--   `ap-northeast-1`
--   `ap-northeast-2`
--   `ap-southeast-1`
--   `ap-southeast-2`
--   `ap-southeast-3`
--   `ap-east-1`
--   `ap-south-1`
--   `sa-east-1`
--   `me-south-1`
--   `af-south-1`
--   `ca-central-1`
-
-### Google
-
-All regions are supported.
-
-## Examples
-
-### Single Executor
-
-The following examples provision a single executor to pull from the `codeintel` queue.
-
--   [AWS example](https://github.com/sourcegraph/terraform-aws-executors/tree/main/examples/single-executor)
--   [Google example](https://github.com/sourcegraph/terraform-google-executors/tree/main/examples/single-executor)
-
-### Multiple Executors
-
-The following examples provision two executors, one to pull from the `codeintel` queue and the other for the `batches`
-queue.
-
--   [AWS example](https://github.com/sourcegraph/terraform-aws-executors/tree/main/examples/multiple-executors)
--   [Google example](https://github.com/sourcegraph/terraform-google-executors/tree/main/examples/multiple-executors)
-
-### Private Single Executor
-
-The following examples provision a single executor in a private network (no public IP). On AWS, a NAT Gateway is used for outbound traffic. On GCP, Cloud NAT provides the same functionality.
-
--   [AWS example](https://github.com/sourcegraph/terraform-aws-executors/tree/main/examples/private-single-executor)
--   [Google example](https://github.com/sourcegraph/terraform-google-executors/tree/main/examples/private-single-executor)
-
-### Step-by-step Guide
-
-The following is a step-by-step guide on provisioning a single `codeintel` executor on GCP.
-
-#### Provision
-
-1. [Install Terraform](#terraform-version).
-2. Install the [`gcloud CLI`](https://cloud.google.com/sdk/docs/install)
-3. Run `gcloud auth application-default login`
-4. Set up your Sourcegraph instance's Site configuration for executors
-    1. Click on your profile picture in the top right corner
-    2. Select **Site admin**
-    3. Expand the **Configuration** section
-    4. Select **Site configuration**
-    5. Set the following,
-        - `"externalURL": "<URL>"`
-            - A URL that is accessible from the GCP VM (e.g. a public URL such as `https://sourcegraph.example.com`)
-        - `"executors.accessToken": "<new long secret>"`
-            - Can be generated by running `cat /dev/random | base64 | head -c 20`
-            - The secret will be as displayed `REDACTED` once it's saved.
-        - `"codeIntelAutoIndexing.enabled": true`
-            - _This is only for `codeintel` executors._
-5. Download
-   the [example files](https://github.com/sourcegraph/terraform-google-executors/tree/main/examples/single-executor)
-6. Change the following in `providers.tf`
-    - `project` to the GCP project to provision the executor in
-    - `region` to the GCP region to provision the executor in
-    - `zone` to the GCP zone to provision the executor in
-7. Change the following in `main.tf`
-    - `executor_sourcegraph_external_url` to the URL configured in your instance's **Site configuration**
-    - `executor_sourcegraph_executor_proxy_password` to the access token configured in your instance's **Site
-      configuration**
-8. Run `terraform init` to download the Sourcegraph executor modules.
-9. Run `terraform plan` to preview the changes that will occur to your GCP infrastructure.
-10. Run `terraform apply` and enter "yes" after reviewing the proposed changes to create the executor VM
-    - Ensure `terraform apply` exited with code 0 and did not print any errors
-11. Go back to the site admin page, expand **Executors**, click **Instances**, and check to see if your executor shows
-    up in the list with a green dot 🟢
-
-#### Validation
-
-The following can be done to troubleshoot or double-check that the executor has been properly provisioned.
-
-Ensure the executor is listed in the Compute Engine. Either go to **Compute Engine** in the GCP Console for your project
-or run the following command.
-
-```shell
-$ gcloud compute instances list
-NAME                                          ZONE           MACHINE_TYPE   PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP    STATUS
-sourcegraph-executor-h0rv                     us-central1-c  c2-standard-8               10.0.1.16                   RUNNING
-sourcegraph-executors-docker-registry-mirror  us-central1-c  n2-standard-2               10.0.1.2                    RUNNING
-```
-
-You can ssh into to the instance to ensure the service is running. You can open an ssh connection either via the GCP
-Console or by running the following command.
-
-```shell
-gcloud compute ssh sourcegraph-executor-h0rv
-```
-
-Then run the following command to check if the service is running.
-
-```shell
-you@sourcegraph-executor-h0rv:~$ systemctl status executor
-🟢 executor.service - User code executor
-     Loaded: loaded (/etc/systemd/system/executor.service; enabled; vendor preset: enabled)
-     Active: active (running) since Thu 2021-11-18 02:28:48 UTC; 19s ago
-```
-
-To check the logs, you can either query the **Log Explorer** in the GCP Console or by running the following command
-while connected to the instance.
-
-```shell
-you@sourcegraph-executor-h0rv:~$ journalctl -u executor | less
-Nov 18 02:31:01 sourcegraph-executor-h0rv executor[2465]: t=2021-11-18T02:31:01+0000 lvl=dbug msg="TRACE internal" host=... path=/.executors/queue/codeintel/dequeue code=204 duration=92.131237ms
-Nov 18 02:31:01 sourcegraph-executor-h0rv executor[2465]: t=2021-11-18T02:31:01+0000 lvl=dbug msg="TRACE internal" host=... path=/.executors/queue/codeintel/canceled code=200 duration=90.630467ms
-Nov 18 02:31:02 sourcegraph-executor-h0rv executor[2465]: t=2021-11-18T02:31:02+0000 lvl=dbug msg="TRACE internal" host=... path=/.executors/queue/codeintel/dequeue code=204 duration=91.269106ms
-Nov 18 02:31:02 sourcegraph-executor-h0rv executor[2465]: t=2021-11-18T02:31:02+0000 lvl=dbug msg="TRACE internal" host=... path=/.executors/queue/codeintel/canceled code=200 duration=161.469685ms
-```
-
-Ensure the `EXECUTOR_FRONTEND_URL` and `EXECUTOR_FRONTEND_PASSWORD` in `/etc/systemd/system/executor.env` are correct
-
-```
-cat /etc/systemd/system/executor.env
-```
-
-Ensure the VM can hit your `externalURL`:
-
-```shell
-you@sourcegraph-executor-h0rv:~$ curl <your externalURL here>
-<a href="/sign-in?returnTo=%2F">Found</a>
-```
-
-#### Configure Auto-indexing
-
-1. Go to the **Site admin** page
-2. Expand **Code graph**,
-3. Select **Configuration**
-4. Click **Create new policy**, and fill in:
-    - Name: `TEST`
-    - Click _add a repository pattern_
-    - Repository pattern #1: set this to an existing repository on your Sourcegraph instance (
-      e.g. `github.com/gorilla/mux`)
-    - Type: `HEAD`
-    - Retention: Disabled
-    - Auto-indexing: Enabled
-5. Expand **Code graph**
-6. Select **Auto-indexing**, and check to see if an indexing job has appeared. If nothing is there:
-    - Try clicking **Enqueue**
-    - Try setting a higher update frequency: `PRECISE_CODE_INTEL_AUTO_INDEXING_TASK_INTERVAL=10s`
-    - Try setting a lower delay: `PRECISE_CODE_INTEL_AUTO_INDEXING_REPOSITORY_PROCESS_DELAY=10s`
-7. Once you have a completed indexing job, click **Uploads** and check to see that an index has been uploaded.
-8. Once the index has been uploaded, you should see the **`PRECISE`** badge in the hover! 🎉
-
-## Auto-scaling
-
-> NOTE: Auto scaling is currently not supported
-> when [downloading and running executor binaries yourself](/self-hosted/executors/deploy-executors-binary),
-> and on managed instances when using self-hosted executors, since it requires deployment adjustments.
-
-Auto-scaling of executor instances can help to increase concurrency of jobs, without paying for unused resources. With auto-scaling, you can scale down to 0 instances when no workload exist and scale up as far as you like and your cloud provider can support. Auto-scaling needs to be configured separately.
-
-Auto-scaling makes use of the auto-scaling capabilities of the respective cloud provider (**AutoScalingGroups** on AWS and **Instance Groups** on GCP). Sourcegraph's `worker` service publishes a scaling metric (that is, the number of jobs in queue) to the cloud providers. Then, based on that reported value, the auto-scalers add and remove compute resources to match the required amount of compute. The autoscaler will attempt to hold 1 instance running per each `executor_jobs_per_instance_scaling` items in queue.
-
-For example, if `executor_jobs_per_instance_scaling` is set to `20` and the queue size is currently `400`, then `20` instances would be determined as required to handle the load. You might want to tweak this number based on the `machine_type`, `maximum_num_jobs` (concurrency per machine), and desired processing speed. See the [AWS](https://github.com/sourcegraph/terraform-aws-executors/blob/main/modules/executors/variables.tf) and [Google](https://github.com/sourcegraph/terraform-google-executors/blob/main/modules/executors/variables.tf) variable definitions for details.
-
-With the Terraform variables `executor_min_replicas` and `executor_max_replicas` in the Terraform modules linked to above, you can configure the minimum and maximum number of compute machines to be run at a given time.
-
-For auto-scaling to work, two things must be true:
-
-1. `executor_min_replicas` must be `>= 0` and `executor_max_replicas` must be `> executor_min_replicas`.
-2. The Sourcegraph instance (its `worker` service, specifically) needs to publish scaling metrics to the used cloud
-   provider.
-
-For the latter to work, the Sourcegraph instance needs to be configured with the correct credentials that allow it to access the cloud provider.
-
-The `credentials` submodule in both the [AWS](https://github.com/sourcegraph/terraform-aws-executors/tree/main/modules/credentials) and [Google](https://github.com/sourcegraph/terraform-google-executors/tree/main/modules/credentials) executor modules exists for that purpose. When used, the `credentials` module sets up the credentials on the cloud provider and returns them in the Terraform outputs.
-
-Here's an example of how one would configure auto-scaling.
-
-```terraform
-module "executors" {
-  source  = "sourcegraph/executors/<aws | google>"
-  version = "<version>"
-
-  # Basic configuration...
-
-  # Auto-scaling
-  executor_min_replicas              = 0 # Spin down when not in use
-  executor_max_replicas              = 30
-  executor_jobs_per_instance_scaling = 20
-}
-
-module "my-credentials" {
-  source  = "sourcegraph/executors/<aws | google>//modules/credentials"
-  version = "<version>"
-
-  resource_prefix = "<optional prefix to add to created resources>"
-
-  # AWS only (optional)
-  # permissions_boundary_arn = "<ARN of IAM permissions boundary policy>"
-}
-
-# AWS
-output "metric_writer_access_key_id" {
-  value = module.my-credentials.metric_writer_access_key_id
-}
-
-output "metric_writer_secret_key" {
-  value     = module.my-credentials.metric_writer_secret_key
-  sensitive = true
-}
-
-# Google
-output "metric_writer_credentials_file" {
-  value     = module.my-credentials.metric_writer_credentials_file
-  sensitive = true
-}
-```
-
-After running `terraform apply`, the outputs are retrieved by running the following commands.
-
-```shell
-# AWS
-$ terraform output metric_writer_access_key_id
-$ terraform output metric_writer_secret_key
-
-# Google
-$ terraform output metric_writer_credentials_file
-```
-
-These outputs are used to configure the Sourcegraph instance (see below).
-
-### AWS
-
-The AWS EC2 auto-scaling groups configured by the Sourcegraph Terraform module respond to changes in metric values written to **CloudWatch**. The target Sourcegraph instance is expected to continuously write these values.
-
-To write the scaling metric to **CloudWatch**, the `worker` service must have defined the following environment variables.
-
-| Environment Variable                    | Description                                              |
-| --------------------------------------- | -------------------------------------------------------- |
-| `EXECUTOR_METRIC_ENVIRONMENT_LABEL`     | Same value as `executor_metrics_environment_label`       |
-| `EXECUTOR_METRIC_AWS_NAMESPACE`         | Must be set to `sourcegraph-executor`                    |
-| `EXECUTOR_METRIC_AWS_REGION`            | The target AWS region                                    |
-| `EXECUTOR_METRIC_AWS_ACCESS_KEY_ID`     | The value of the output of `metric_writer_access_key_id` |
-| `EXECUTOR_METRIC_AWS_SECRET_ACCESS_KEY` | The value of the output of `metric_writer_secret_key`    |
-
-### Google
-
-The Google Compute Engine auto-scaling groups configured by the Sourcegraph Terraform module respond to changes in metric values written to Cloud Monitoring. The target Sourcegraph instance is expected to continuously write these values.
-
-To write the scaling metric to **Cloud Monitoring**, the `worker` service must have defined the following environment variables.
-
-| Environment Variable                | Description                                        |
-| ----------------------------------- | -------------------------------------------------- |
-| `EXECUTOR_METRIC_ENVIRONMENT_LABEL` | Same value as `executor_metrics_environment_label` |
-| `EXECUTOR_METRIC_GCP_PROJECT_ID`    | The GCP Project ID                                 |
-
-Then either one of the following environment variables must be set.
-
-| Environment Variable                                          | Description                                                                                       |
-| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `EXECUTOR_METRIC_GOOGLE_APPLICATION_CREDENTIALS_FILE_CONTENT` | The **base64-decoded** output of `metric_writer_credentials_file`                                 |
-| `EXECUTOR_METRIC_GOOGLE_APPLICATION_CREDENTIALS_FILE`         | The path to the file containing the **base64-decoded** output of `metric_writer_credentials_file` |
-
-### Testing auto scaling
-
-Once the environment variables have been set and the worker service has been restarted, you should be able to find the scaling metrics in your cloud providers dashboards.
-
-To test if the metric is correctly reported into the Cloud provider:
-
--   On AWS, this can be found in the **CloudWatch** metrics section. Under **All metrics**, select the namespace `sourcegraph-executor` and then the metric `environment`, `queueName`. Make sure there are entries returned.
--   On Google Cloud, this can be found in the **Metrics explorer**. Select **Resource type: Global** and then **Metric: `custom/executors/queue/size`**. You should see values reported here. `0` is also an indicator that it works correct.
-
-Next, you can test whether the number of executors rises and shrinks as load spikes occur. Keep in mind that auto-scaling is not a real-time operation on most cloud providers and usually takes a short moment and can have some delays between the metric going down and the desired machine count adjusting.
-
-## Upgrading executors
-
-Upgrading executors is relatively uninvolved. Simply follow the instructions below.
-Also, check the [changelog](https://sourcegraph.com/changelog) for any Executors related breaking changes or new features or flags that you might want to configure. See [Executors maintenance](/self-hosted/executors/deploy-executors#Maintaining-and-upgrading-executors) for version compatability.
-
-### **Step 1:** Update the source version of the terraform modules
-
-> NOTE: Keep in mind that only one minor version bumps are guaranteed to be disruption-free.
-
-```diff
-module "executors" {
-  source = "sourcegraph/executors/<aws | google>"
-
-  # Find the latest version matching your Sourcegraph version here:
-  # - https://github.com/sourcegraph/terraform-google-executors/tags
-  # - https://github.com/sourcegraph/terraform-aws-executors/tags
--  version = "7.3.0"
-+  version = "7.4.0"
-
-  # AWS specific
-  availability_zone = "<availability zone to provision resource in AWS>"
-  # Google specific
-  region            = "<region to provision in GCP>"
-  zone              = "<zone to provision resource in GCP>"
-
-  executor_sourcegraph_external_url            = "<external url>"
-  executor_sourcegraph_executor_proxy_password = "<shared secret>"
-
-  # Either:
-  executor_queue_name                          = "<codeintel | batches>"
-  # Or:
-  executor_queue_names                         = ["codeintel", "batches"]
-
-  executor_instance_tag                        = "<tag to filter in stackdriver monitoring>"
-  executor_metrics_environment_label           = "<label to filter custom metrics>"
-  executor_use_firecracker                     = true
-}
-```
-
-### **Step 2:** Reapply the terraform configuration
-
-Simply reapply the terraform configuration and executors will be ready to go again.
-
-```bash
-terraform apply
-```
diff --git a/docs/self-hosted/executors/deploy-executors.mdx b/docs/self-hosted/executors/deploy-executors.mdx
index 88208a604..2b7a23367 100644
--- a/docs/self-hosted/executors/deploy-executors.mdx
+++ b/docs/self-hosted/executors/deploy-executors.mdx
@@ -3,7 +3,7 @@
 Executors can be deployed in a variety of manners. The supported deployment options are:
 
 -   [Linux Binary Service](/self-hosted/executors/deploy-executors-binary) ([Firecracker](./firecracker) compatible)
--   [Terraform on AWS or GCP](/self-hosted/executors/deploy-executors-terraform) ([Firecracker](./firecracker) compatible)
+-   Terraform ([Firecracker](./firecracker) compatible): [AWS](/self-hosted/executors/deploy-executors-terraform-aws) | [Google Cloud](/self-hosted/executors/deploy-executors-terraform-gcp)
 -   [Native Kubernetes](/self-hosted/executors/deploy-executors-kubernetes) *(Beta — not recommended for production)*
 -   [Docker-in-Docker on Kubernetes](/self-hosted/executors/deploy-executors-dind) *(Beta — not recommended for production)*
 -   [Docker-Compose](/self-hosted/executors/deploy-executors-docker)
diff --git a/docs/self-hosted/index.mdx b/docs/self-hosted/index.mdx
index 7b56dff82..7d95e1784 100644
--- a/docs/self-hosted/index.mdx
+++ b/docs/self-hosted/index.mdx
@@ -60,7 +60,7 @@ Get started running Sourcegraph on-prem.
 -   [Executors overview](/self-hosted/executors/)
 -   [Deploy executors](/self-hosted/executors/deploy-executors)
 -   [Kubernetes deployment](/self-hosted/executors/deploy-executors-kubernetes) *(Beta)*
--   [Terraform deployment](/self-hosted/executors/deploy-executors-terraform)
+-   Terraform deployment: [AWS](/self-hosted/executors/deploy-executors-terraform-aws) | [Google Cloud](/self-hosted/executors/deploy-executors-terraform-gcp)
 -   [Docker deployment](/self-hosted/executors/deploy-executors-docker)
 -   [Binary deployment](/self-hosted/executors/deploy-executors-binary)
 -   [Binary deployment (offline)](/self-hosted/executors/deploy-executors-binary-offline)

From adb9b48b8a8926f8ad1122f0f04d7f83732e309a Mon Sep 17 00:00:00 2001
From: Warren Gifford <warrenbruceg@gmail.com>
Date: Tue, 7 Jul 2026 22:51:50 -0700
Subject: [PATCH 7/8] improve linking so the terraform options are more
 discoverable

---
 .../executors/deploy-executors-terraform-gcp.mdx     |  4 ++++
 .../executors/deploy-executors-terraform.mdx         |  4 ++--
 docs/self-hosted/executors/deploy-executors.mdx      | 12 +++++++++---
 3 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/docs/self-hosted/executors/deploy-executors-terraform-gcp.mdx b/docs/self-hosted/executors/deploy-executors-terraform-gcp.mdx
index 919c05b1e..bd2dc26e2 100644
--- a/docs/self-hosted/executors/deploy-executors-terraform-gcp.mdx
+++ b/docs/self-hosted/executors/deploy-executors-terraform-gcp.mdx
@@ -59,6 +59,8 @@ The executor Terraform modules require Terraform `>= 1.1.0, < 2.0.0`.
 
 Ensure the [IAM API](https://console.cloud.google.com/apis/api/iam.googleapis.com/overview) is enabled.
 
+<Accordion title="Required GCP permissions">
+
 -   appengine.applications.get
 -   clientauthconfig.brands.\*
 -   clientauthconfig.clients.\*
@@ -97,6 +99,8 @@ Ensure the [IAM API](https://console.cloud.google.com/apis/api/iam.googleapis.co
 -   secretmanager.secrets.\*
 -   secretmanager.versions.\*
 
+</Accordion>
+
 ## Supported Regions
 
 All regions are supported.
diff --git a/docs/self-hosted/executors/deploy-executors-terraform.mdx b/docs/self-hosted/executors/deploy-executors-terraform.mdx
index 31f124692..3d9e7a9d6 100644
--- a/docs/self-hosted/executors/deploy-executors-terraform.mdx
+++ b/docs/self-hosted/executors/deploy-executors-terraform.mdx
@@ -3,8 +3,8 @@
 [Terraform modules](https://learn.hashicorp.com/tutorials/terraform/module-use?in=terraform/modules) are provided to
 provision machines running executors on AWS and Google Cloud. Choose your cloud provider:
 
--   [AWS](/self-hosted/executors/deploy-executors-terraform-aws) — using the [`sourcegraph/executors/aws`](https://github.com/sourcegraph/terraform-aws-executors) module
--   [Google Cloud](/self-hosted/executors/deploy-executors-terraform-gcp) — using the [`sourcegraph/executors/google`](https://github.com/sourcegraph/terraform-google-executors) module
+-   **AWS** — [Deployment guide](/self-hosted/executors/deploy-executors-terraform-aws) · [Module source](https://github.com/sourcegraph/terraform-aws-executors)
+-   **Google Cloud** — [Deployment guide](/self-hosted/executors/deploy-executors-terraform-gcp) · [Module source](https://github.com/sourcegraph/terraform-google-executors)
 
 ## Terraform Version
 
diff --git a/docs/self-hosted/executors/deploy-executors.mdx b/docs/self-hosted/executors/deploy-executors.mdx
index 2b7a23367..352e00a6f 100644
--- a/docs/self-hosted/executors/deploy-executors.mdx
+++ b/docs/self-hosted/executors/deploy-executors.mdx
@@ -95,10 +95,16 @@ Once the shared secret is set in Sourcegraph, you can start setting up executors
 
 <QuickLinks>
 	<QuickLink
-		title="Terraform"
+		title="Terraform (AWS)"
 		icon="lightbulb"
-		href="/self-hosted/executors/deploy-executors-terraform"
-		description="Simply launch executors on AWS or GCP using Sourcegraph-maintained modules and machine images."
+		href="/self-hosted/executors/deploy-executors-terraform-aws"
+		description="Launch executors on AWS using the Sourcegraph-maintained Terraform module and machine images."
+	/>
+	<QuickLink
+		title="Terraform (Google Cloud)"
+		icon="lightbulb"
+		href="/self-hosted/executors/deploy-executors-terraform-gcp"
+		description="Launch executors on Google Cloud using the Sourcegraph-maintained Terraform module and machine images."
 	/>
 	<QuickLink
 		title="Install executor on your machine"

From f683ab8dac1087350001882e83da9d2b0a430737 Mon Sep 17 00:00:00 2001
From: Warren Gifford <warrenbruceg@gmail.com>
Date: Tue, 7 Jul 2026 23:15:22 -0700
Subject: [PATCH 8/8] docs validation addition updates

---
 .../executors/deploy-executors-terraform-aws.mdx       | 10 +++-------
 1 file changed, 3 insertions(+), 7 deletions(-)

diff --git a/docs/self-hosted/executors/deploy-executors-terraform-aws.mdx b/docs/self-hosted/executors/deploy-executors-terraform-aws.mdx
index cf3b9f21d..eeb50d724 100644
--- a/docs/self-hosted/executors/deploy-executors-terraform-aws.mdx
+++ b/docs/self-hosted/executors/deploy-executors-terraform-aws.mdx
@@ -163,22 +163,18 @@ $ aws ec2 describe-instances \
 +----------------------+-------------+---------+------------------+
 ```
 
-You can connect to the instance using [AWS Systems Manager Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager.html) (if the instance has the SSM agent and appropriate IAM role) or via SSH.
+You can connect to the instance using [AWS Systems Manager Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager.html). The module attaches the `AmazonSSMManagedInstanceCore` policy to the executor IAM role, so SSM works out of the box.
 
 ```shell
-# Using SSM (no SSH key required)
 aws ssm start-session --target i-0abc123def456789
-
-# Using SSH (requires the key pair configured in the module)
-ssh -i <key-pair>.pem ubuntu@<instance-public-ip>
 ```
 
 Then run the following command to check if the service is running.
 
 ```shell
 ubuntu@ip-10-0-1-42:~$ systemctl status executor
-🟢 executor.service - User code executor
-     Loaded: loaded (/etc/systemd/system/executor.service; enabled; vendor preset: enabled)
+● executor.service - User code executor
+     Loaded: loaded (/etc/systemd/system/executor.service; enabled; preset: enabled)
      Active: active (running) since Thu 2021-11-18 02:28:48 UTC; 19s ago
 ```