> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure an Agent
> Install and configure a Control Plane agent on AWS, Azure, GCP, Docker, or Kubernetes for secure connectivity to private network resources.
Click the desired cloud provider and follow the installation and configuration instructions:
* [Amazon Web Services (AWS)](#aws)
* [Microsoft Azure](#azure)
* [Google Cloud Platform (GCP)](#gcp)
* [Running locally in Docker](#running-locally-in-docker)
* [Kubernetes (k8s) Cluster](#kubernetes-k8s-cluster)
## AWS
### Overview
Follow the steps below to install and configure an [agent](/reference/agent) within your Amazon Web Services (AWS) environment.
### Prerequisites
* Review the [Agent](/reference/agent) reference page.
* [Amazon Web Services](https://aws.amazon.com/) (AWS) account.
### Step One - Create an Agent
Follow the [Create an Agent](/guides/agent) guide to define an agent and generate the bootstrap config file that will be used in
[step two](#step-two-create-a-launch-template-in-aws).
### Step Two - Create a Launch Template in AWS
1. If you already have the `Userdata Script`, you can skip this step. In the Control Plane UI, click `Agents` in the left menu, select your agent, then choose `Download Scripts` from the `Actions` menu. Paste your bootstrap token and copy the YAML from the `Userdata Script` tab.
2. Log in to the [AWS Console](https://console.aws.amazon.com). Once logged in, select the AWS Region at the navigation bar in the top-right corner. Choose the same region where the services it will access are located.
3. In the AWS Console, navigate to `EC2`. In the left sidebar, under Instances, select `Launch Templates` and then click `Create launch template`.
4. Enter a unique name for the launch template. (e.g., `cpln-agent-launch-template`).
5. Under the `Auto Scaling guidance` section, check the box to use this template with EC2 Auto Scaling.
6. Under the `Application and OS Images` section, select `Quick Start` and choose `Ubuntu` (Ubuntu Server 24.04 LTS recommended).
7. For `Instance type`, select `t3.small` or `t3.medium` for testing purposes. In production environments, refer to the [Agent Sizing Guidance](/reference/agent#agent-sizing-guidance) to select the appropriate instance type for running an agent. An instance with at least 2 vCPUs and 4 GiB of memory is recommended for optimal performance.
8. `Optional:` Under the `Key pair (login)` section, select or create a new key pair to
enable SSH access to the agent. A key pair is necessary only for accessing the
agent during troubleshooting.
9. Under the `Networking` section, select `Don't include subnet in the launch template`, subnets are configured by EC2 Auto Scaling. Attach a security group and make sure it belongs to the VPC you plan on using when creating the Auto Scaling Group in Step 3 below.
* `Note:` The VPC must have an `Internet Gateway` attached. To verify, navigate to `VPC`, click `Internet Gateways`, find the gateway associated with your VPC, and confirm the state is `Attached`.
10. Expand the `Advanced details` section. Scroll to the bottom and paste the `Userdata Script` copied in Step 1 into the `User data` textbox.
11. Click `Create launch template`.
### Step Three - Create an Auto Scaling Group in AWS
1. In the AWS Console, navigate to `EC2`. In the left sidebar, scroll down to Auto Scaling, select `Auto Scaling Groups`, then click `Create Auto Scaling group` in the right corner.
2. Enter a name for the Auto Scaling Group. (e.g., `cpln-agent`).
3. For the Launch template, select the name you created in Step Two (e.g., `cpln-agent-launch-template`), and click `Next`.
4. Under the `Network` section, select the VPC used in your launch template from Step Two. For Availability Zones and subnets, select at least `one` subnet and set Availability Zone distribution to `Balanced best effort`.
* `Note:` Confirm your subnet has Auto-assign public IPv4 address by navigating back to `VPC` and clicking `Subnets` in the AWS console. If it is not enabled, you can also expand `Advanced network configuration` and click `Add network interface`, then set `Auto-assign public IP` to `Enable`.
5. `Optional:` Leave all settings as default and click `Next`.
6. For testing, set Desired, Min, and Max capacity all to 1. For production, set Desired capacity to 2, Min capacity to 2, and Max capacity to at least 4. This way you can scale up to multiple agents as needed. Leave all other settings as default, then click `Skip to review`.
* `Note:` You can also scale down to 0 or scale up to multiple agents for redundancy and reliability.
7. Review your settings, then scroll down and click `Create Auto Scaling group` in the bottom-right corner.
The agent virtual machine will begin the deployment process. After a few moments, the agent will be running, connecting to the Control Plane servers, and ready to process requests.
To verify, go to the Control Plane UI, click `Agents` in the left menu, select your agent, and you will see a green heartbeat pinged recently. It may take up to 2-3 minutes to appear after the agent starts.
### Next Steps
Now that you have an agent configured and running, it can be used within an [identity](/reference/identity) to allow your
[workload](/reference/workload) to connect to your internal AWS resources.
## Azure
### Overview
Follow the steps below to install and configure an [agent](/reference/agent) within your Microsoft Azure environment.
### Prerequisites
* Review the [Agent](/reference/agent) reference page.
* [Microsoft Azure](https://azure.com) account.
### Step One - Create an Agent
Follow the [Create an Agent](/guides/agent) guide to define an agent and generate the bootstrap config file that will be used in
[step two](#step-two-create-a-virtual-machine-scale-set-in-azure).
### Step Two - Create a Virtual Machine Scale Set in Azure
1. If you already have the `Userdata Script`, you can skip this step. In the Control Plane UI, click `Agents` in the left menu, select your agent, then choose `Download Scripts` from the `Actions` menu. Paste or import the bootstrap config, click `Next`, and copy or download the YAML from the `Userdata Script` tab. Click `Done`.
2. Log in to the [Azure Console](https://portal.azure.com).
3. In the Azure console, navigate to `Virtual machine scale sets` and click `Create`.
4. Select your `Subscription` and `Resource Group`. If needed, create a new resource group before proceeding.
5. Under the `Scale set details` section, enter a unique name for the Virtual Machine Scale Set. (e.g., `cpln-agent`).
6. Select the Region where your Azure resources are located and set `Availability Zones` to Zones 1, 2, and 3.
7. Under the `Scaling mode` section, select `Autoscaling`, then set the Image to a `Ubuntu Server 24.04 LTS` (recommended).
8. For `Size`, select `Standard D2s v3` for testing purposes. An instance with at least 2 vCPUs and 4 GiB of memory is recommended for optimal performance.
9. Leave the Username as `azureuser`. For SSH Key Type, select an existing key or generate a new one.
10. Click `Next`, skip the Spot section, and click `Next: Disks`.
11. For `OS Disk Type`, select Premium SSD then click `Next: Networking`.
12. Select your `Virtual Network`, `Subnet`, and `Network interface`, or create new ones if they do not exist.
13. Under `Load balancing`, select `None`, then click `Next: Management`.
14. Leave the defaults and click `Next: Health`.
15. Leave the defaults and click `Next: Advanced`.
16. Under the `Custom data and cloud init` section, paste the `Userdata Script` from Step 1 into the `Custom Data` field, then click `Create`. If you created a new key pair, click `Download private key and create resource`.
The agent virtual machine will begin the deployment process. After a few moments, the agent will be running, connecting to the Control Plane servers, and ready to process requests.
To verify, go to the Control Plane UI, click `Agents` in the left menu, select your agent, and you will see a green heartbeat pinged recently. It may take up to 2-3 minutes to appear after the agent starts.
### Next Steps
Now that you have an agent configured and running, it can be used within an [identity](/reference/identity) to allow your
[workload](/reference/workload) to connect to your internal Azure resources.
## GCP
### Overview
Follow the steps below to install and configure an [agent](/reference/agent) within your Google Cloud Platform (GCP) environment.
### Prerequisites
* Review the [Agent](/reference/agent) reference page.
* [Google Cloud Platform (GCP)](https://cloud.google.com/) account.
### Step One - Create an Agent
Follow the [Create an Agent](/guides/agent) guide to define an agent and generate the bootstrap config JSON file that will be used in
[step two](#step-two-create-an-instance-template-in-gcp).
### Step Two - Create an Instance Template in GCP
1. If you already have the `Startup script`, you can skip this step. In the Control Plane Console UI, click `Agents` in the left menu, select your agent, then choose `Download Scripts` from the `Actions` menu. Paste your bootstrap token and copy the script shown in the `Startup script` tab. The `Startup script` is used to automatically install and configure the Control Plane agent on your VM upon startup.
Some images in GCP also support cloud-init so you can use that instead. Consult the docs for image details. For example, Ubuntu supports cloud-init at the time of this writing while Debian does not.
2. Log in to the [GCP Console](https://console.cloud.google.com). To the left of the search bar, select your target project.
3. In the GCP Console, navigate to `Compute Engine`. In the left sidebar, under Virtual Machines, select `Instance templates`, then click `Create instance template`.
4. Enter a name for the Instance template. (e.g., `cpln-agent-instance-template`).
5. Under the `Location` section, select `Regional`, and choose your preferred region.
* `Note:` The region needs to match where your internal resources are located, as the agent must be in the same VPC and region to connect to them.
6. For the `Machine configuration`, select `C4` for testing purposes. In production environments, refer to the [Agent Sizing Guidance](/reference/agent#agent-sizing-guidance) to select the appropriate instance type for running an agent.
7. Under the `Machine Type` section, select `c4-standard-2` (2 vCPUs, 7 GB memory) or `c4-standard-4` (4 vCPUs, 15 GB memory). An instance with at least 2 vCPUs and 4 GiB of memory is recommended for optimal performance.
8. Under the `Boot disk` section, set the operating system to `Ubuntu` and select `Ubuntu 26.04 LTS Minimal`, then click `Select`.
9. Scroll to the bottom of the page and expand `Advanced Options`, then expand `Management`. Paste the `Startup script` from Step 1 into the `Automation` field and click `Create`.
### Step Three - Create an Instance Group in GCP
1. In the GCP Console, navigate to `Compute Engine`. In the left sidebar, scroll down to Instance groups, select `Instance groups`, then click `Create instance group`.
2. Choose `New Managed Instance Group (Stateless)` and enter a name for the instance group. (e.g., `cpln-agent`).
3. For the Instance template, select the name you created in Step Two (e.g., `cpln-agent-instance-template`).
4. Under the `Location` section, select `Multiple zones` and choose your preferred regions.
5. For the Target distribution shape, select `Balanced` to support active-active configuration and evenly distribute instances across all selected zones.
6. Under the `Autoscaling` section, click `Configure Autoscaling`. Set the `Autoscaling Mode` to `On`. Update the Minimum and Maximum number of instances as needed, and add any additional autoscaling signals if required.
* For testing, set Minimum and Maximum capacity to 1.
* For production, set Minimum to 2 and Maximum to at least 4.
* `Note:` You can also scale down to 0 or scale up to multiple agents for redundancy and reliability.
7. Click `Create` in the bottom-left corner.
The agent virtual machine will begin the deployment process. After a few moments, the agent will be running, connecting to the Control Plane servers, and ready to process requests.
To verify, go to the Control Plane UI, click `Agents` in the left menu, select your agent, and you will see a green heartbeat pinged recently. It may take up to 2-3 minutes to appear after the agent starts.
### Next Steps
Now that you have an agent configured and running, it can be used within an [identity](/reference/identity) to allow your [workload](/reference/workload) to connect to your internal GCP resources.
## Running locally in Docker
### Overview
Follow the steps below to install and configure an [agent](/reference/agent) within your private network.
### Prerequisites
* Review the [Agent](/reference/agent) reference page.
* Install the [CLI](/cli-reference/installation).
* Install [Docker](https://docs.docker.com/engine/install/).
### Step One - Create an Agent
Follow the [Create an Agent](/guides/agent) guide to define an agent and generate the bootstrap config file that will be used in
[step two](#step-two-launch-agent-locally).
### Step Two - Launch agent locally
1. Open a new shell and execute the following command. Use the bootstrap file that was created in [step one](#step-one-create-an-agent-4).
```bash theme={null}
cpln agent up --bootstrap-file=path/to/bootstrapConfig.json
```
If you are using Windows, follow these instructions:
* Configure Docker to **not** use the WSL 2 based engine.
* Run the `cpln` command above using a Windows command prompt and not WSL.
2. The agent will now be running, connecting to the Control Plane servers, and ready to process requests.
To verify, go to the Control Plane UI, click `Agents` in the left menu, select your agent, and you will see a green heartbeat pinged recently. It may take up to a minute to appear after the agent starts.
### Next Steps
Now that you have an agent configured and running, it can be used within an [identity](/reference/identity) to allow your [workload](/reference/workload) to connect to your local resources.
When running an agent locally, it is running within a local Docker container. When configuring an [identity network
resource](/reference/identity#network-resources-cloud-wormhole), you must use the IP of the network adapter that Docker installed on the
local machine.
## Kubernetes (k8s) Cluster
### Overview
Follow the steps below to install and configure an [agent](/reference/agent) within your Kubernetes cluster.
### Prerequisites
* Review the [Agent](/reference/agent) reference page.
* Install the [CLI](/cli-reference/installation).
### Step One - Create an Agent
Follow the [Create an Agent](/guides/agent) guide to define an agent and generate the bootstrap config file that will be used in
[step two](#step-two-launch-agent-within-a-k8s-cluster).
### Step Two - Launch agent within a K8s cluster
1. Prepare your k8s manifests by going to your agent's page in Control Plane. Select `Download Scripts` from the `Actions` menu. Paste the bootstrap token you saved earlier and copy the YAML that shows in the `K8S Manifests` tab. There you can optionally configure a namespace and number of replicas. The recommended number of replicas is 2.
2. Assuming you have saved the manifest to a file locally just apply it with `kubectl`:
```bash theme={null}
# may need to create the namespace using kubectl create ns agent-namespace
kubectl apply -f agent-manifests.yaml
```
3. Within a few minutes, the agent pods will be ready to handle requests.
### Next Steps
Now that you have an agent configured and running, it can be used within an [identity](/reference/identity) to allow your [workload](/reference/workload) to connect to your local resources.