Configure an Agent

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.

• Amazon Web Services (AWS)
• Microsoft Azure
• Google Cloud Platform (GCP)
• Running locally in Docker
• Kubernetes (k8s) Cluster

​

AWS

​

Overview

​

Prerequisites

• Review the Agent reference page.
• Amazon Web Services (AWS) account.

​

Step One - Create an Agent

​

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. 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 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.

​

Next Steps

​

Azure

​

Overview

​

Prerequisites

• Review the Agent reference page.
• Microsoft Azure account.

​

Step One - Create an Agent

​

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.
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.

​

Next Steps

​

GCP

​

Overview

​

Prerequisites

• Review the Agent reference page.
• Google Cloud Platform (GCP) account.

​

Step One - Create an Agent

​

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.

2. Log in to the GCP Console. 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 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.

​

Next Steps

​

Running locally in Docker

​

Overview

​

Prerequisites

• Review the Agent reference page.
• Install the CLI.
• Install Docker.

​

Step One - Create an Agent

​

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.

cpln agent up --bootstrap-file=path/to/bootstrapConfig.json

2. The agent will now be running, connecting to the Control Plane servers, and ready to process requests.

​

Next Steps

​

Kubernetes (k8s) Cluster

​

Overview

​

Prerequisites

• Review the Agent reference page.
• Install the CLI.

​

Step One - Create an Agent

​

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:

# 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