​
Overview

In situations where your workload needs to consume services from endpoints within a VPC or another private network, you would use a wormhole agent. Control Plane’s wormhole technology securely connects your workloads to any TCP or UDP endpoints in VPCs and other private networks, including on-prem data centers and even on a developer’s laptop. You establish a wormhole by running an agent VM (agent for short) inside the private network to which you are connecting your workloads. Control Plane offers agents for both private networks and cloud providers. The agent is installed and configured within the location where it can access the applications or services that your workload requires. It does this by establishing a secure and persistent connection to publicly hosted Control Plane servers. Requests from your workload are tunneled to the agent which performs the request and then tunnels the response back. This flow occurs in a performant manner and is transparent to the workload. Agents are scoped to an org and are used in conjunction with identities to set up network resources.

​
Create and Set up an Agent

Visit one of the links below for a step-by-step guide on how to create an agent with a specific provider:

​
High Availability (HA)

Agents run in active-passive mode. If an active agent misses a set amount of heartbeats, it is considered offline and replaced by a redundant agent. The recommended method to configure a highly available agent deployment is by using an instance group (also called an autoscaling group on AWS or a VMSS/virtual machine scale set on Azure). The autoscaling group template must be configured in the same way as a single VM in terms of cloud configuration, network settings, etc. As the agent’s functionality is not CPU intensive, that metric cannot be used to scale instances up and down. Instead, use a fixed sized group set to a minimum of 2 and a maximum of the number of zones used within your infrastructure.

​
BYOK Locations Configuration to Allow Agent Connection

For BYOK locations, ensure that the Middlebox is enabled.

​
Agent Sizing Guidance

When utilizing an agent, the machine type running the agent affects the bandwidth and latency exhibited by the agent. The tables below are provided to help guide your agent machine type selection. Tests were performed using qperf. The qperf client was configured as a container workload running on the Control Plane platform and deployed in the same region as the qperf server running on a virtual machine. Based on the results below, select an agent type suitable for your performance requirements.
  • AWS
    • Region tested: aws-us-west-2
    • qperf server running on: c5.2xlarge instance type
    • Test runtime: 30 seconds
    Agent Instance TypeAverage Bandwidth (MB/sec)Average Latency (us)Basline Bandwidth (Gbps)
    No Agent307.6585.6n/a
    t2.micro21.2313010.064
    t3.small143.911070.128
    c5.large341.1629.60.75
    c4.xlarge70.25680.85.0
    When capacity planning the Basline Bandwidth should be used instead of the Burst Bandwidth.
    Available Basline Bandwidth for each instance can be discovered using the AWS CLI. This query shows the BaselineBandwidthInGbps for t3 instances. Adjust as needed for the instance types required. 
      aws ec2 describe-instance-types \
  --filters "Name=instance-type,Values=t3.*" \
  --query "InstanceTypes[].[InstanceType, NetworkInfo.NetworkCards[0].BaselineBandwidthInGbps] | sort_by(@,&[1])" \
  --output table

  -------------------------
  | DescribeInstanceTypes |
  +-------------+---------+
  |  t3.nano    |  0.032  |
  |  t3.micro   |  0.064  |
  |  t3.small   |  0.128  |
  |  t3.medium  |  0.256  |
  |  t3.large   |  0.512  |
  |  t3.xlarge  |  1.024  |
  |  t3.2xlarge |  2.048  |
  +-------------+---------+
  • GCP
    • Region tested: gcp-us-east1
    • qperf server running on: e2-standard-8 machine type
    • Test runtime: 30 seconds
    Agent Machine TypeAverage Bandwidth (MB/sec)Average Latency (us)
    No Agent313.4251.2
    n2-standard-2250.3407.7
    n2-standard-8223.3350.7
    n2-standard-4217.5354.1
    n1-standard-1199.9409.3

​
Permissions

The permissions below are used to define policies together with one or more of the four principal types:
PermissionDescriptionImplies
createCreate new agents
deleteDelete service agents
editModify existing agentsview
manageFull accesscreate, delete, edit, manage, use, view
useUse an agent in an identityview
viewRead-only access

​
Access Report

Displays the permissions granted to principals for the agent.

​
CLI

To view the CLI documentation for an agent, click here.