Configure an Agent

Click on the desired cloud provider and follow the installation and configuration instructions:

• Amazon Web Services (AWS)
• Microsoft Azure
• Google Cloud Platform (GCP)
• Private Network
• Kubernetes (k8s) Cluster

AWS

Overview

Follow the steps below to install and configure an agent within your Amazon Web Services (AWS) environment.

Prerequisites

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

Step One - Create an Agent

Follow the Create an Agent guide to define an agent and generate the bootstrap config file that will be used in step two.

Step Two - Launch an agent in AWS

1. Log in to the AWS Console.
2. Click this link to be directed to the Control Plane Secure Communications Agent within the AWS Marketplace.
   • For the ARMs version of the agent, click here.
3. Click the Continue to Subscribe button in the upper right corner.
4. After reading the terms and conditions, click the Accept Terms.
5. After the subscription has loaded, click the Continue to Configuration button in the upper right corner.
6. Click the region pull-down and select the region where your AWS resources reside.
7. Click the Continue to Launch button in the upper right corner.
8. Click the Choose Action pull-down and select Launch through EC2. Click the Launch button.
9. The Launch an instance wizard will be displayed.
10. Under the Name and tag section, enter the agent's name. (e.g., cpln-agent).
11. Under the Instance type section, select an applicable instance type.

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

13. Under the Network setting section, review the details and verify that the selected VPC is the same as the AWS resource you are trying to access.

14. Under the Configure storage section, click the Advanced link and expand the volume property. Modify the Delete on termination dropdown to Yes. This will ensure the associated volume is removed if the agent is terminated, thereby preventing any orphaned volumes.

15. Expand the Advanced details section. Scroll to the bottom and paste the contents of the JSON payload generated in step one within the User data textbox. Please review the other properties in this section to check if any default values need to be modified.

16. Click Launch instance in the lower right corner.

17. After a brief moment, the instance will launch and be ready to process requests.

Next Steps

Now that you have an agent configured and running, it can be used within an identity to allow your workload to connect to your internal AWS resources.

Azure

Overview

Follow the steps below to install and configure an agent within your Microsoft Azure environment.

Prerequisites

• Review the Agent reference page
• Microsoft Azure account

Step One - Create an Agent

Follow the Create an Agent guide to define an agent and generate the bootstrap config file that will be used in step two.

Step Two - Launch an agent in Azure

1. Log in to the Azure Console.
2. From the Azure homepage, click the Marketplace icon.
3. In the Marketplace search bar, enter:

copy
Control Plane Secure Communications Agent

4. Press Enter.
5. When clicking the Create dropdown, select gen-1.
6. Use these recommended settings for the Create a virtual machine wizard:

• Basic
  • Subscription: Choose the appropriate subscription.
  • Resource Group: Choose the appropriate resource group. If necessary, create a new one.
  • Virtual machine name: Enter Control-Plane-Agent-01. If installing multiple agents, increment the number.
  • Region: Select a region closest to your other Azure resources.
  • Availability options: Select No infrastructure redundancy required. Use a different option for your environment if you are running in production.
  • Image: Leave as gen-1.
  • Size: An instance with at least 2 vCPUs and 4 GiB of memory is recommended for optimal performance.
  • Authentication type: Select SSH public key.
  • Username: Leave as azureuser.
  • SSH public key source: Choose the appropriate key. If necessary, create a new one.
  • Key pair name: Select appropriate key, or if creating a new one, use the default or update the key name.
  • Public inbound ports: Select None. The agent does not need any inbound ports open.
  • Click Next: Disks.
• Disks
  • OS disk type: Select Premium SSD.
  • Encryption type: Select (Default) Encryption at-rest with a platform-managed key.
  • Click Next: Networking.
• Networking
  • Virtual network: Choose an appropriate network or use the new network that will be created.
  • Subnet: Choose appropriate network or use the default.
  • Public IP: Select None.
  • NIC network security group: Select Basic.
  • Public inbound ports: Select None.
  • Click Next: Management.
• Management
  • Enable basic plan for free: Enabled.
  • Boot diagnostics: Select Enable with managed storage account.
  • Enable OS guest diagnostics: Disabled.
  • System assigned managed identity: Disabled.
  • Enable auto-shutdown: Disabled.
  • Patch orchestration options: Select Image default.
  • Click Next: Advanced.
• Advanced
  • Custom data: Paste the JSON text generated from Step One into the textbox.
  • Click Next: Tags.
• Tags
  • Optional: Enter any necessary tags.
  • Click Next: Review + create.
• Review + create
  • Review all the settings and enter any missing values.
  • Click Create.
  • If you requested to create a new key pair, a modal will pop-up requesting to download the private key. 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.

Next Steps

Now that you have an agent configured and running, it can be used within an identity to allow your workload to connect to your internal Azure resources.

GCP

Overview

Follow the steps below to install and configure an agent within your Google Cloud Platform (GCP) environment.

Prerequisites

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

Step One - Create an Agent

Follow the Create an Agent guide to define an agent and generate the bootstrap config file that will be used in step two.

Step Two - Launch agent in GCP

• Using the Google Cloud SDK

1. Install the latest SDK.
2. If necessary, log in using gcloud init.
3. Execute the command in the note below. Ensure that the instance will be deployed in the same VPC and region as your GCP resources. Use a unique INSTANCE_NAME and the bootstrap file (AGENT_NAME-bootstrapConfig.json) that was created in step one.

4. After a few moments, the command will return and show the status of the deployed instance.
5. The agent will now be running, connecting to the Control Plane servers, and ready to process requests.

Step Three - Configure Firewall

By default, the GCP firewall rules open the common SSH, RDP, and ICMP ports to the world and allows all internal ports within the VPC. The agent does not need any of these ports open.

At a minimum, the agent needs to be able to connect to your GCP resources and the Internet.

Next Steps

Now that you have an agent configured and running, it can be used within an identity to allow your workload to connect to your internal GCP resources.

Private Network

Overview

Follow the steps below to install and configure an agent within your private network.

Prerequisites

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

Step One - Create an Agent

Follow the Create an Agent guide to define an agent and generate the bootstrap config file that will be used in step two.

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.

copy
cpln agent up --bootstrap-file=PATH/AGENT_NAME-bootstrapConfig.json

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

Next Steps

Now that you have an agent configured and running, it can be used within an identity to allow your workload to connect to your local resources.

Kubernetes (k8s) Cluster

Overview

Follow the steps below to install and configure an agent within your k8s cluster.

Prerequisites

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

Step One - Create an Agent

Follow the Create an 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

1. Open a new shell and execute the following command. Update tokens as necessary. Use the bootstrap file that was created in step one.

copy
cpln agent manifest --bootstrap-file bootstrap.json  --namespace NAMESPACE  --replicas 2 --cluster CLUSTER_ID > manifest.yaml
# inspect/modify the manifest file manually, if needed.
kubectl apply -f manifest.yaml

cpln will generate the manifest.yaml file that will deploy two replicas of the agent to the namespace of your choice (NAMESPACE in the example). The parameter --cluster CLUSTER_ID will be added to the agent's status which is used as a hint to know which cluster an agent has been deploy to.

It is recommended to use --replicas=2 for high availability (HA).

On startup, the agent will generate a public/private key-pair which is persisted as a k8s secret. In this scenario, the agents run under a k8s service account, which can create/modify secrets in its own namespace. If this is a concern, the agent can be configured to run in a dedicated namespace.

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

Next Steps

Now that you have an agent configured and running, it can be used within an identity to allow your workload to connect to your local resources.