CloudConnector -- Quick Start v1.0.0

This walkthrough builds CloudConnector's evaluation shape from one Terraform root: a new AWS VPC and a new Google Cloud network, a relay fleet in each, and the controller that joins them. You then send test traffic through the pipe, confirm that the source address survives, and remove everything. Nothing you already run is touched. Most of the time is spent waiting for instances to boot.

What you will build

Before you begin

Step 1 -- Get the configuration

CloudConnector is deployed from the cloudconnector example root, which calls the cloudspectra-relay-deploy composition by relative path (../../terraform/cloudspectra-relay-deploy). Keep the directory layout exactly as delivered, or the module path breaks:

<workdir>/
  examples/cloudconnector/          main.tf  variables.tf  outputs.tf  plan-only/
  terraform/cloudspectra-relay-deploy/
  terraform/cloudspectra-relay-controller/
  terraform/cloudspectra-relay-pipe/
  terraform/cloudspectra-relay/modules/

To obtain the configuration for your release, contact support@cloudspectra.ai.

Step 2 -- Provide credentials

The deployment needs three credentials: AWS, Google Cloud and your licence. Authenticate the two clouds the standard way, so that every module in the configuration picks them up:

# AWS: a named profile, environment variables or SSO -- whatever the AWS CLI uses
export AWS_PROFILE=my-profile
aws sts get-caller-identity

# Google Cloud: application-default credentials, and the project to build in
gcloud auth application-default login
export GOOGLE_PROJECT=my-project-id

The root also reads ~/.secrets/.aws.credentials (an AWS shared-credentials file) and ~/.secrets/.gcp.credentials (a service-account key, whose own project it then uses) when they exist, for its own lookups. The modules it calls authenticate through the standard chains, so configure those in any case.

Place the licence key where the deployment reads it:

mkdir -p ~/.secrets && chmod 700 ~/.secrets
printf '%s\n' '<your licence key>' > ~/.secrets/.cloudspectra.relay.credentials
chmod 600 ~/.secrets/.cloudspectra.relay.credentials

Step 3 -- Choose the inputs

Every input of the example has a default. Create examples/cloudconnector/terraform.tfvars:

name        = "cloudconnector"   # prefixes every resource; also the fleet id
release     = "1.0.0"            # the release whose relay images are deployed
aws_region  = "us-east-1"
gcp_region  = "us-central1"
target_gbps = 3                  # capacity to size each end for

target_gbps decides the number of relays per end: one relay per 3 Gbps, rounded up, never fewer than one. The value 3 used here gives one relay per end -- the cheapest pipe, with no redundancy: the plan says so in a note, and losing either relay stops the pipe until it is replaced. The example's own default of 10 builds four relays per end, which is 24 raw vCPUs and more than the Developer lane allows.

So that you can query the controller in Step 7, add two outputs to examples/cloudconnector/outputs.tf:

output "fleet_id" {
  value = module.cloudconnector.fleet_id
}

output "read_token" {
  value     = module.cloudconnector.credentials.read_token
  sensitive = true
}

Step 4 -- Initialize and plan

cd examples/cloudconnector
terraform init
terraform plan

Read the plan's warnings before you apply. Terraform reports them but still lets the apply go ahead:

Step 5 -- Apply

terraform apply

When the apply finishes it prints:

The relays need a few minutes after the apply to boot, fetch their datapath, register with the controller and bond with each other.

Step 6 -- Route traffic into the pipe

Nothing is steered into the pipe until you say so. The steps below create one test host on each side; for your own workloads, apply the same routes and firewall rules to their subnets and VMs.

On AWS: a workload subnet and a route to the GWLB endpoint

Put workloads in their own subnet with their own route table. Do not add the steering route to the relays' route table: the relays must not route the far side's range back into the load balancer.

REGION=us-east-1
VPC=$(aws ec2 describe-vpcs --region $REGION \
  --filters Name=tag:Name,Values=cloudconnector-pipe --query 'Vpcs[0].VpcId' --output text)
IGW=$(aws ec2 describe-internet-gateways --region $REGION \
  --filters Name=attachment.vpc-id,Values=$VPC --query 'InternetGateways[0].InternetGatewayId' --output text)
GWLBE=$(aws ec2 describe-vpc-endpoints --region $REGION \
  --filters Name=service-name,Values=$(terraform output -raw aws_endpoint_service) \
  --query 'VpcEndpoints[0].VpcEndpointId' --output text)

# A subnet for workloads, in the relays' zone, with its own route table
SUBNET=$(aws ec2 create-subnet --region $REGION --vpc-id $VPC \
  --cidr-block 10.60.128.0/24 --availability-zone ${REGION}a --query Subnet.SubnetId --output text)
RTB=$(aws ec2 create-route-table --region $REGION --vpc-id $VPC --query RouteTable.RouteTableId --output text)
aws ec2 associate-route-table --region $REGION --route-table-id $RTB --subnet-id $SUBNET
aws ec2 create-route --region $REGION --route-table-id $RTB \
  --destination-cidr-block 0.0.0.0/0 --gateway-id $IGW

# The steering route: the Google Cloud range goes to this zone's GWLB endpoint
aws ec2 create-route --region $REGION --route-table-id $RTB \
  --destination-cidr-block 10.70.0.0/16 --vpc-endpoint-id $GWLBE

A route can only target the endpoint, never the load balancer or the endpoint service. With relays in several zones, route each workload subnet to the endpoint in its own zone.

Now a test host. Its security group must admit the Google Cloud range, because packets from there arrive with their original source:

SG=$(aws ec2 create-security-group --region $REGION --vpc-id $VPC \
  --group-name cc-test --description "CloudConnector test host" --query GroupId --output text)
aws ec2 authorize-security-group-ingress --region $REGION --group-id $SG \
  --protocol tcp --port 22 --cidr <your-public-ip>/32
aws ec2 authorize-security-group-ingress --region $REGION --group-id $SG \
  --protocol -1 --cidr 10.70.0.0/16

aws ec2 run-instances --region $REGION --instance-type t3.micro \
  --image-id resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64 \
  --subnet-id $SUBNET --security-group-ids $SG --associate-public-ip-address \
  --key-name <your-key-pair> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=cc-test-aws}]'

On Google Cloud: the client tag and two firewall rules

The deployment already created the route that sends 10.60.0.0/16 to the internal load balancer. It applies only to VMs with the network tag <name>-client -- here cloudconnector-client -- and never to the relays themselves (tag cloudconnector-gcp-relay). Add firewall rules so that the AWS range can reach your VMs, and your VMs can reach the relays:

gcloud compute firewall-rules create cc-test-from-aws --network cloudconnector-pipe \
  --source-ranges 10.60.0.0/16 --allow all --target-tags cloudconnector-client
gcloud compute firewall-rules create cc-test-to-relays --network cloudconnector-pipe \
  --source-ranges 10.70.0.0/16 --allow all --target-tags cloudconnector-gcp-relay
gcloud compute firewall-rules create cc-test-ssh --network cloudconnector-pipe \
  --source-ranges <your-public-ip>/32 --allow tcp:22 --target-tags cloudconnector-client

gcloud compute instances create cc-test-gcp --zone us-central1-a --machine-type e2-small \
  --subnet cloudconnector-pipe --tags cloudconnector-client \
  --image-family debian-12 --image-project debian-cloud

To put an existing VM on the pipe, add the tag: gcloud compute instances add-tags <vm> --tags cloudconnector-client --zone <zone>.

Step 7 -- Verify end to end

ssh ec2-user@<aws-test-public-ip>
ping -c 5 <gcp-test-private-ip>

gcloud compute ssh cc-test-gcp --zone us-central1-a
sudo tcpdump -ni any icmp and src host <aws-test-private-ip>

curl -s -H "Authorization: Bearer $(terraform output -raw read_token)" \
  "$(terraform output -raw controller_url)/fleet/v1/pipe/status?fleet=$(terraform output -raw fleet_id)"

Step 8 -- Tear down

Remove what you created by hand first: Terraform cannot delete a VPC or network that still holds resources it does not manage.

# AWS
aws ec2 terminate-instances --region $REGION --instance-ids <cc-test-aws-instance-id>
aws ec2 wait instance-terminated --region $REGION --instance-ids <cc-test-aws-instance-id>
aws ec2 delete-security-group --region $REGION --group-id $SG
aws ec2 delete-subnet --region $REGION --subnet-id $SUBNET
aws ec2 delete-route-table --region $REGION --route-table-id $RTB

# Google Cloud
gcloud compute instances delete cc-test-gcp --zone us-central1-a --quiet
gcloud compute firewall-rules delete cc-test-from-aws cc-test-to-relays cc-test-ssh --quiet

# Everything Terraform built
terraform destroy

terraform state rm 'module.cloudconnector.module.controller.aws_eip.controller[0]'
aws dynamodb update-table --region $REGION --table-name cloudconnector-controller-fleet \
  --no-deletion-protection-enabled
terraform destroy
aws ec2 release-address --region $REGION --allocation-id <controller-eip-allocation-id>

Destroying the deployment does not cancel your Cloud Spectra subscription. Relays are metered for the clock hours they hold, so a relay's last hour bills in full; a relay that stops checking in without a goodbye stops accruing time within 30 minutes.

Next steps

• Join networks you already own, with credentials you supply: Topology and the configuration reference.
• Size the pipe for your traffic: Sizing and scaling.
• Watch it: Monitoring and alerts.
• When something does not cross: Troubleshooting.