docs: reorganize executor administration and deployment guidance

docs/admin/executors/index.mdx

@@ -5,26 +5,105 @@
 	<user>Available via the Web app.</user>
 </TierCallout>
 
-Executors are Sourcegraph's solution for isolating and running workloads in a secure and controllable way. Executors provide a sandbox that can run resource-intensive or untrusted tasks on behalf of the Sourcegraph instance, such as:
+Executors run resource-intensive or untrusted work on behalf of Sourcegraph. They are used to:
 
--   [Automatically indexing a repository for precise code navigation](/code-navigation/auto-indexing)
--   [Running batch changes](/batch-changes/server-side)
+- [Automatically index repositories for precise code navigation](/code-navigation/auto-indexing)
+- [Run batch changes server-side](/batch-changes/server-side)
+
+This page covers the Sourcegraph configuration and administrative tools that apply to every executor. If you operate a self-hosted Sourcegraph instance and need to deploy executor infrastructure, see [Deploy executors](/self-hosted/executors).
 
 ## Why use executors?
 
-Running untrusted code is a core requirement of features such as precise code navigation [auto-indexing](/code-navigation/auto-indexing), and [running batch changes server-side](/batch-changes/server-side).
+Running untrusted code is a core requirement of features such as precise code navigation [auto-indexing](/code-navigation/auto-indexing) and [running batch changes server-side](/batch-changes/server-side).
+
+Auto-indexing jobs, in particular, invoke project build tools to resolve dependencies. Post-install hooks, insecure [package management tools](https://github.com/golang/go/issues/29230), and package manager proxy attacks can allow malicious code to consume compute resources or exfiltrate data. This is especially dangerous when the work runs inside a Sourcegraph instance that has repository data on disk and unprotected services on its internal network.
+
+Executors move this work outside the Sourcegraph instance. A job receives an isolated workspace containing a clone of only the repository it needs, limiting its access to other repository data and Sourcegraph services.
+
+## How executors work
+
+Executors run jobs outside the Sourcegraph instance. Each executor connects to Sourcegraph, requests work from a queue, prepares an isolated workspace containing one repository, runs the job, and sends its progress and result back to Sourcegraph.
+
+Keeping this work outside the Sourcegraph instance limits the access that untrusted build tools, package managers, and user-defined commands have to Sourcegraph services and repository data. The exact isolation boundary depends on how the executor is deployed. Self-hosted administrators should review the [deployment and isolation options](/self-hosted/executors#choose-a-deployment-method) before deploying executors.
+
+## Sandboxing model
+
+Executors can run each job inside a [Firecracker](https://sourcegraph.com/github.com/firecracker-microvm/firecracker) MicroVM to isolate the job from other jobs and the executor host. Firecracker provides the strongest supported isolation boundary and requires Linux KVM extensions. On cloud infrastructure, this generally requires a bare-metal instance on AWS or nested virtualization on Google Cloud.
+
+Executors can also run jobs in Docker containers or as Kubernetes Jobs without KVM-based isolation. These methods are easier to deploy on common infrastructure, but they provide a weaker isolation boundary and require additional host, node, and network controls.
+
+See [Firecracker isolation](/self-hosted/executors/firecracker) for architecture and caveats, or [choose a deployment method](/self-hosted/executors#choose-a-deployment-method) based on your infrastructure and security requirements.
+
+## Setting up executors
+
+The following steps configure a self-hosted Sourcegraph instance to accept connections from executors. They are separate from deploying the executor service onto infrastructure such as a Linux host, cloud virtual machine, or Kubernetes cluster.
+
+<Callout type="note">
+	Sourcegraph Cloud includes Sourcegraph-managed executor infrastructure by
+	default. Cloud customers using these managed executors do not need to
+	configure executor authentication or deploy their own executor
+	infrastructure.
+</Callout>
+
+If you operate a self-hosted Sourcegraph instance, complete the steps below and then follow the [self-hosted deployment guide](/self-hosted/executors) to choose a deployment method and install executors on your infrastructure.
+
+Self-hosted executors authenticate to Sourcegraph with a shared secret:
+
+1. Generate a random secret containing at least 20 characters. For example, use OpenSSL to generate a 64-character hexadecimal secret:
+
+    ```bash
+    openssl rand -hex 32
+    ```
+
+1. Open **Site admin > Configuration > Advanced configuration**.
+1. Set `executors.accessToken` to the generated secret and save the site configuration.
+
+    ```
+    { "executors.accessToken": "<generated-secret>" }
+    ```
+
+1. Configure the same secret on each executor as `EXECUTOR_FRONTEND_PASSWORD`, or through the equivalent setting for its deployment method.
+
+The executor authentication secret is not a Sourcegraph user access token and is not managed on the **Access tokens** page. See [Site configuration](/admin/config/site-config#view-and-edit-site-configuration) for more information about editing site configuration.
+
+## Monitor executor instances
+
+<Callout type="note">
+	The **Executor instances** page becomes available only after
+	`executors.accessToken` is configured in site configuration.
+</Callout>
+
+Open **Site admin > Maintenance > Executor instances** to see executors that have connected to Sourcegraph. The page shows whether each executor is active, its Sourcegraph compatibility, and details including its hostname and installed runtime versions.
 
-Auto-indexing jobs, in particular, require the invocation of arbitrary and untrusted code to support the resolution of project dependencies. Invocation of post-install hooks, use of insecure [package management tools](https://github.com/golang/go/issues/29230), and package manager proxy attacks can create opportunities in which an adversary can gain unlimited use of compute or exfiltrate data. The latter outcome is particularly dangerous for on-premise installations of Sourcegraph, which is the chosen option for companies wanting to maintain strict privacy of their code property.
+![Executor instances page showing active and inactive executors](https://storage.googleapis.com/sourcegraph-assets/docs/images/executors/executor-instances.png)
 
-Instead of performing this work within the Sourcegraph instance, where code is available on disk and unprotected internal services are available over the local network, we move untrusted compute into a sandboxed environment, the _executor_, that has access only to the clone of a single repository on disk (its _workspace_) and to the public internet.
+Use this page to confirm that a new or upgraded executor is connected and reporting the expected version. For host, service, or runtime failures, see [Troubleshoot executors](/self-hosted/executors/executors-troubleshooting).
 
-## Sandboxing Model
+## Manage executor secrets
 
-Executors can be deployed with [Firecracker](https://sourcegraph.com/github.com/firecracker-microvm/firecracker) isolation in accordance with our [sandboxing model](/admin/executors/#how-it-works) to isolate jobs from each other and the host.
-This requires executors to be run on machines capable of running Linux KVM extensions. On the most popular cloud providers, this either means running executors on bare-metal machines (AWS) or machines capable of nested virtualization (GCP).
+Executor secrets provide environment variables to jobs without placing secret values in a batch spec. Global secrets are available to every eligible job, while user and organization secrets apply only to jobs in their respective namespaces. Namespaced secrets override global secrets with the same name.
 
-Optionally, executors can be run without using KVM-based isolation, which is less secure but might be easier to run on common machines.
+Site administrators manage global secrets under **Site admin > Batch Changes > Secrets**. Users and organization administrators manage their scoped secrets from the corresponding user or organization settings.
 
-## How it works
+Learn how to create, rotate, and remove [executor secrets](/admin/executors/executor-secrets).
 
-Executor instances are capable of being deployed in a variety of ways. Each runtime varies in how jobs are executed.
+<QuickLinks>
+	<QuickLink
+		title="Deploy executors"
+		icon="installation"
+		href="/self-hosted/executors"
+		description="Compare deployment methods and review infrastructure requirements for self-hosted executors."
+	/>
+	<QuickLink
+		title="Executor configuration reference"
+		icon="presets"
+		href="/self-hosted/executors/executors-config"
+		description="Review the environment variables supported by the executor service."
+	/>
+	<QuickLink
+		title="Troubleshoot executors"
+		icon="theming"
+		href="/self-hosted/executors/executors-troubleshooting"
+		description="Diagnose connectivity, runtime, scheduling, and isolation issues."
+	/>
+</QuickLinks>

docs/agentic-batch-changes/index.mdx

@@ -34,7 +34,7 @@ Before creating an Agentic Batch Change, make sure your Sourcegraph instance can
 
 - [Configure code host connections](/admin/code-hosts) for the repositories you want the agent to search and modify.
 - [Configure Batch Changes credentials](/batch-changes/configuring-credentials) for each code host where the agent should publish pull requests or merge requests.
-- [Deploy Sourcegraph executors](/self-hosted/executors/deploy-executors) so Agentic Batch Changes can run code-modification jobs in isolated workspaces. Executors are available with no additional setup on [Sourcegraph Cloud](/cloud).
+- If you use self-hosted Sourcegraph, [deploy Sourcegraph executors](/self-hosted/executors) so Agentic Batch Changes can run code-modification jobs in isolated workspaces. [Sourcegraph Cloud](/cloud) includes Sourcegraph-managed executors by default, so Cloud customers using them do not need to deploy executor infrastructure.
 
 ### Prompting
 

docs/batch-changes/faq.mdx

@@ -226,7 +226,7 @@ They can! Each changeset that is computed can be assigned to a separate executor
 
 ### What additional resources do I need to provision to run batch changes server-side?
 
-See [deploying executors](/self-hosted/executors/deploy-executors) page. You'll require little as a single compute instance and a docker registry mirror if you just want to process batch changes at a small scale; an autoscaling group of instances if you want to process large batch changes very fast.
+For self-hosted Sourcegraph, see [deploying executors](/self-hosted/executors). You may require as little as a single compute instance and a Docker registry mirror to process Batch Changes at a small scale, or an autoscaling group of instances to process large Batch Changes quickly. Sourcegraph Cloud includes Sourcegraph-managed executors by default, so Cloud customers using them do not need to deploy executor infrastructure.
 
 ### Can someone accidentally take down the Sourcegraph instance if they run too big a batch change?
 

docs/batch-changes/how-src-executes-a-batch-spec.mdx

@@ -7,6 +7,10 @@
 
 Here, you will learn what happens when a user applies or previews a Batch Spec by running `src batch apply` or `src batch preview` commands.
 
+![Local Batch Changes execution with src-cli](https://storage.googleapis.com/sourcegraph-assets/executor_src_local_arch.png)
+
+When Batch Changes runs locally, `src` resolves and downloads the target repositories, then runs each batch-spec step sequentially in a Docker container with the repository mounted as its workspace. `src` collects the container logs and resulting diffs, then sends the changeset specifications and batch-spec result to Sourcegraph.
+
 ## Overview
 
 `src batch apply` and `src batch preview` execute a batch spec the same way by following these steps:

docs/batch-changes/server-side.mdx

@@ -11,7 +11,7 @@
 
 By default, Batch Changes uses a command line interface in your local environment to [compute diffs](/batch-changes/how-src-executes-a-batch-spec) and create changesets. This can be impractical for creating batch changes affecting hundreds or thousands of repositories, with large numbers of workspaces, or if the batch change steps require CPU, memory, or disk resources that are unavailable locally.
 
-Instead of computing Batch Changes locally using `src-cli`, you can offload this task to one or many remote server called an [executor](/self-hosted/executors/deploy-executors). Executors are also required to enable code navigation [auto-indexing](/code-navigation/auto-indexing).
+Instead of computing Batch Changes locally using `src-cli`, you can offload this task to one or many remote servers called [executors](/admin/executors). Executors are also required to enable code navigation [auto-indexing](/code-navigation/auto-indexing).
 
 This allows to:
 
@@ -21,16 +21,15 @@ This allows to:
 
 ## Setup
 
-This is a one-time process. Once a site-admin of the Sourcegraph instance sets up executors and enables running batch changes server-side, all users of the Sourcegraph instance can get started with no additional setup required.
+Sourcegraph Cloud includes Sourcegraph-managed executors by default, so Cloud customers using them do not need to deploy executor infrastructure.
 
-Make sure that [executors are deployed and are online](/self-hosted/executors/deploy-executors).
+If you operate a self-hosted Sourcegraph instance, [deploy executors](/self-hosted/executors) and confirm that they are online. This is a one-time process. Once a site administrator sets up executors and enables running Batch Changes server-side, users can get started without additional executor setup.
 
 ## Limitations
 
--   Running batch changes server-side requires setting up executors. Executors are configured ready-to-use on Sourcegraph Cloud
+-   Self-hosted Sourcegraph instances require executor setup. Executors are ready to use on Sourcegraph Cloud.
 -   Running batch changes server-side is limited to user namespaces
 -   The newly introduced APIs for server-side are still experimental and will likely change
--   Executors can only be deployed using Terraform (AWS or GCP) or using pre-built binaries (see [deploying executors](/self-hosted/executors/deploy-executors)).
 
 Running batch changes server-side has been tested to run a simple **45K changeset batch change**. Actual performance and setup requirements depend on the complexity of the batch change.
 

docs/code-navigation/auto-indexing.mdx

@@ -21,7 +21,7 @@ The following docs explains how to turn on [auto-indexing](/code-navigation/auto
 	This step is only required if you are on self-hosted Sourcegraph.
 </Callout>
 
-First, [deploy the executor service](/self-hosted/executors/deploy-executors) targeting your Sourcegraph instance. This will provide the necessary compute resources that clone the target Git repository, securely analyze the code to produce a code graph data index, then upload that index to your Sourcegraph instance for processing.
+First, [deploy the executor service](/self-hosted/executors) targeting your Sourcegraph instance. This will provide the necessary compute resources that clone the target Git repository, securely analyze the code to produce a code graph data index, then upload that index to your Sourcegraph instance for processing.
 
 ### Enable index job scheduling
 

docs/self-hosted/executors/custom-certificates.mdx

@@ -0,0 +1,108 @@
+# Use custom certificates with executors
+
+By default, executors will search for certificates in the following files and directories:
+
+| Directory or file                                   | Distribution              |
+| --------------------------------------------------- | ------------------------- |
+| `/etc/ssl/certs/ca-certificates.crt`                | Debian/Ubuntu/Gentoo etc. |
+| `/etc/pki/tls/certs/ca-bundle.crt`                  | Fedora/RHEL 6             |
+| `/etc/ssl/ca-bundle.pem`                            | OpenSUSE                  |
+| `/etc/pki/tls/cacert.pem`                           | OpenELEC                  |
+| `/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem` | CentOS/RHEL 7             |
+| `/etc/ssl/cert.pem`                                 | Alpine Linux              |
+| `/etc/ssl/certs`                                    | SLES10/SLES11             |
+| `/etc/pki/tls/certs`                                | Fedora/RHEL               |
+| `/system/etc/security/cacerts`                      | Android                   |
+
+If your environment makes use of custom certificates, you can add them to one of these locations in order for executors to pick them up.
+
+## Add certificates to a binary deployment
+
+> NOTE: see the [troubleshooting guide](/self-hosted/executors/executors-troubleshooting#connecting-to-cloud-provider-executor-instances) for instructions on how to connect to cloud provider VMs.
+
+After successfully [deploying binaries](/self-hosted/executors/deploy-executors-binary), follow these steps:
+
+1. Copy your certificates to `/etc/ssl/certs`.
+1. If you are using systemd, run `systemctl restart executor`. If not, proceed to the next step.
+1. Run `executor run` on the VM in order to restart the executor service.
+
+### Add certificates with Firecracker
+
+When running executors with the [firecracker runtime](/self-hosted/executors/firecracker), custom certificates need to be added in
+the container that is running within the Firecracker VM. To add custom certificates, you must create a new Docker image
+that contains the certificates. For example,
+
+```dockerfile
+FROM upstream:tag
+
+# Copy the certificates into the container
+COPY customcert.crt /usr/local/share/ca-certificates/customcert.crt
+# Update the certificate store
+RUN chmod 644 /usr/local/share/ca-certificates/customcert.crt && update-ca-certificates
+# ...
+```
+
+#### Code navigation
+
+Once the custom image is built, you can configure the executor to use it by setting
+the `codeIntelAutoIndexing.indexerMap` to use the custom image. For example,
+
+```json
+"codeIntelAutoIndexing.indexerMap": {
+  "go": "myregistry.company.com/scip-go:custom"
+}
+```
+
+## Add certificates to a Kubernetes deployment using manifests
+
+First, add the certificate data as a secret in your preferred namespace:
+
+```shell
+SECRET_NAME=custom-certs
+CERT_PATH=/path/to/cert.pem
+kubectl create secret generic $SECRET_NAME --from-file=customcert.crt=$CERT_PATH
+```
+
+Or as a declarative manifest:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+    name: custom-certs
+data:
+    customcert.crt: $(base64 -i /path/to/cert.pem)
+type: Opaque
+```
+
+Next, mount the secret in the executor deployment. Add the following snippet to `spec.template.spec.volumes` of each executor deployment:
+
+```yaml
+- name: custom-certs
+  secret:
+      secretName: custom-certs
+```
+
+Also add this snippet to `spec.template.spec.containers.volumeMounts` of each executor deployment (specifically, the executor container, in case you inject any sidecars):
+
+```yaml
+- mountPath: /etc/ssl/certs
+  name: custom-certs
+  readOnly: true
+```
+
+Next, apply the updated YAML manifests. Once the executors have rolled out, they should be picking up your custom certificates.
+
+## Add certificates to a Kubernetes deployment using Helm
+
+You may follow the same instructions for the manifest deployment to set custom certificates.
+
+## Add certificates to a Docker Compose deployment
+
+First, ensure that the certificate file is present on the host machine. Next, add the volume to the [executor compose file](https://sourcegraph.com/github.com/sourcegraph/deploy-sourcegraph-docker/-/blob/docker-compose/executors/executor.docker-compose.yaml?L26-30):
+
+```yaml
+- '/path/to/certs:/etc/ssl/certs'
+```
+
+Next, restart the deployment with `docker-compose down` and `docker-compose up -d`.