# Deploy executors

Executors run resource-intensive or untrusted jobs for precise code navigation and Batch Changes. This guide helps self-hosted operators choose a deployment method and prepare the infrastructure that executors require.

For feature concepts, Sourcegraph configuration, connected instance management, and executor secrets, see [Administer executors](/admin/executors).

## Prepare to deploy executors

Complete these prerequisites before deploying executor infrastructure:

- **Confirm version compatibility.** Run the same major and minor version of the executor as your Sourcegraph Enterprise instance.
- **Configure authentication to your Sourcegraph instance.** Complete [Setting up executors](/admin/executors#setting-up-executors) to create the shared authentication secret. The guide for your deployment method explains how to provide that secret to the executor.
- **Confirm network connectivity.** Executor infrastructure must be able to reach the Sourcegraph frontend.
- **Provide a supported runtime.** Current executor deployments require a Linux AMD64 (`x86_64`) environment.
- **Plan executor capacity.** Size CPU, memory, and disk for the number and type of concurrent jobs. See [Plan executor capacity](/self-hosted/executors/resource-sizing).

## Choose a deployment method

The primary decision is whether jobs require a virtual-machine isolation boundary.

- **Use Firecracker for the strongest supported job isolation.** Choose a Terraform deployment on AWS or Google Cloud, or install the Linux binary on compatible infrastructure. Firecracker requires KVM: AWS uses bare-metal instances, while Google Cloud supports nested virtualization.
- **Use Docker when KVM is unavailable and privileged container execution is acceptable.** Install the Linux binary in Docker mode or use Docker Compose.
- **For Kubernetes deployments, prefer Docker-in-Docker.** Docker-in-Docker is the preferred option when running executors in an existing Kubernetes cluster. It remains in beta and does not provide the same MicroVM isolation boundary as Firecracker. Native Kubernetes executors are being deprecated.

![Flowchart for choosing an executor deployment method](https://storage.googleapis.com/sourcegraph-assets/executor_deployment_tree.png)

<Callout type="warning">
	Executors run untrusted repository code and build tooling. Deployment
	methods without Firecracker do not provide a MicroVM boundary. Isolate
	executor hosts or nodes from sensitive workloads, restrict access to private
	networks and cloud metadata services, and use disposable compute where
	possible.
</Callout>

### Recommended deployment methods

<QuickLinks>
	<QuickLink
		title="Terraform on AWS"
		icon="installation"
		href="/self-hosted/executors/deploy-executors-terraform-aws"
		description="Provision autoscaling, Firecracker-capable executors and supporting AWS infrastructure."
	/>
	<QuickLink
		title="Terraform on Google Cloud"
		icon="installation"
		href="/self-hosted/executors/deploy-executors-terraform-gcp"
		description="Provision autoscaling executors with nested virtualization on Google Cloud."
	/>
	<QuickLink
		title="Linux binary"
		icon="theming"
		href="/self-hosted/executors/deploy-executors-binary"
		description="Install an executor directly on a Linux host, with Firecracker or Docker isolation."
	/>
	<QuickLink
		title="Offline Linux binary"
		icon="theming"
		href="/self-hosted/executors/deploy-executors-binary-offline"
		description="Install the executor and its dependencies in an air-gapped environment."
	/>
	<QuickLink
		title="Docker Compose"
		icon="lightbulb"
		href="/self-hosted/executors/deploy-executors-docker"
		description="Run an executor as a privileged container without Firecracker isolation."
	/>
</QuickLinks>

### Kubernetes deployment methods

<QuickLinks>
	<QuickLink
		title="Docker-in-Docker on Kubernetes (Beta)"
		icon="presets"
		href="/self-hosted/executors/deploy-executors-dind"
		description="Run Docker jobs through a privileged sidecar in an isolated Kubernetes node pool."
	/>
	<QuickLink
		title="Native Kubernetes (Beta)"
		icon="presets"
		href="/self-hosted/executors/deploy-executors-kubernetes"
		description="Run each job step as a Kubernetes Job. This deployment method is being deprecated."
	/>
</QuickLinks>

## Validating executor deployments

Follow the validation steps in the guide for your selected deployment method. After the executor starts, confirm that it is active and reporting the expected version under **Site admin > Maintenance > Executor instances**.

![Executor instances listed in the Sourcegraph site administration UI](https://storage.googleapis.com/sourcegraph-assets/docs/images/code-intelligence/sg-3.34/executor-ui-test.png)

## Configure and operate executors

<QuickLinks>
	<QuickLink
		title="Private container registries"
		icon="presets"
		href="/self-hosted/executors/private-registries"
		description="Configure authentication for images stored in private container registries."
	/>
	<QuickLink
		title="Custom certificates"
		icon="theming"
		href="/self-hosted/executors/custom-certificates"
		description="Configure executors to trust private certificate authorities."
	/>
	<QuickLink
		title="Executor configuration reference"
		icon="installation"
		href="/self-hosted/executors/executors-config"
		description="Review executor environment variables and runtime configuration."
	/>
	<QuickLink
		title="Troubleshoot executors"
		icon="lightbulb"
		href="/self-hosted/executors/executors-troubleshooting"
		description="Diagnose connectivity, runtime, scheduling, and isolation problems."
	/>
</QuickLinks>

For details about the strongest supported job-isolation boundary, see [Firecracker isolation and caveats](/self-hosted/executors/firecracker).