Practical answers about CloudVpc, grouped by topic, followed by the known limitations of this release. For the concepts, start with the Overview; for configuration detail, see the User Guide.
General
How is CloudVpc different from a VPN?
A VPN client gets an address from the VPN's own pool, and the network sees a VPN client. A CloudVpc worker wears a real private address of your VPC -- its relay's -- so the VPC sees an ordinary member: security groups apply to it, load balancers register it as a target, private endpoints answer it, and the instance metadata service gives it the relay's IAM role. The relay does not translate addresses between the worker and the VPC.
Which clouds can I use?
The relays run in AWS. The workers run in Oracle Cloud Infrastructure (OCI) or DigitalOcean. See Supported clouds and topologies.
How many workers can one relay serve?
One. Pairing is always one to one. To add workers, add relays.
Can a worker be a container instead of a VM?
Only on compute you control. The worker needs NET_ADMIN to bring up its tunnel and wear an address, so managed serverless container services (AWS Fargate, Google Cloud Run, Azure Container Instances) cannot host one. A VM you run can, and in the EKS topology each worker VM is a Kubernetes node whose pods run as usual.
Which operating systems can a worker run?
Linux. The client needs kernel 5.10 or newer and runs as root, because it uses eBPF and manages network interfaces. The CloudVpc configurations launch Canonical Ubuntu 24.04 on OCI and Debian 13 on DigitalOcean.
How do I deploy it -- CloudFormation, AWS Marketplace or Terraform?
Terraform. CloudVpc is deployed with the CloudVpc Terraform configurations described in the User Guide; the Gateway's CloudFormation templates do not create relays or workers. The public cloudspectra/gateway Terraform provider has a cloudspectra_ecmp_pipe resource that accepts mode = "cloud_vpc", but it only reports at plan time what the mode needs; it creates nothing.
Identity, metadata and IAM
How does a worker get AWS credentials?
The same way an EC2 instance does. The worker routes 169.254.169.254 through its tunnel, so the VPC's instance metadata service answers it as the relay, and the AWS SDKs on the worker obtain temporary credentials for the relay's instance profile. The relays require IMDSv2 (session tokens), which current AWS SDKs use by default.
How do I give my workload AWS permissions?
Attach them to the relays' IAM role -- in the pool configurations it is named <name>-relay. Every process on a worker host that can reach the metadata service holds that role, including the permissions CloudVpc itself grants the relay, so grant only what the workload needs.
Can containers on a worker use the relay's IAM role?
No, by design. The relays' metadata hop limit is 1, and the relay caps the metadata service's replies to one hop. The relay itself consumes no hop, so a process on the worker host reaches the metadata service, but a container one forwarding hop further away does not -- otherwise every workload on the node would silently hold the relay's role.
Does a worker keep the same private address for ever?
For as long as its relay lives. AWS assigns each relay's private IPv4 address at launch, as for any Auto Scaling group member, so when a relay is replaced, the worker that pairs with the replacement wears a different address. Applications that already run on Auto Scaling groups are built for this. The load balancer endpoint stays the same.
What does the instance metadata say about a worker?
It describes the relay: its instance ID, its private address, its instance profile. That is the point -- the worker presents itself to the VPC as the relay. The Quick Start's verification step shows an OCI machine reporting an AWS instance ID.
Networking
Does all of the worker's traffic go through AWS?
No. The tunnel carries the VPC's address range and the metadata address. The worker's default route stays on its own cloud, so package installs, container pulls and other internet traffic leave directly. Tunnelling everything is a per-client choice, and the CloudVpc configurations do not make it.
Does traffic between two workers go through AWS?
Not normally. Workers advertise their own host addresses through a peer map, and two workers that know each other's address exchange traffic directly, encapsulated in GENEVE over UDP (port 6081) across four source ports. Until a direct path is known, traffic falls back through the relays -- it still arrives, but it is slower and is billed leaving and re-entering AWS.
Do I need IPv6?
Yes, in the VPC: each relay claims an IPv6 rendezvous address, so the VPC must be dual-stack. In the pool configurations the workers find relays at those addresses, so they also need IPv6 egress. The CloudVpc configurations create dual-stack networks for you. The WireGuard tunnel itself accepts workers over IPv4 or IPv6.
What is exposed to the internet?
On each relay: the WireGuard port (UDP 28302 by default) and the enrolment and health port (TCP 28300 by default), which workers in another cloud must be able to reach. Recovery SSH (ports 22 and 28301) is open only to the ranges in admin_cidrs, which is empty by default. There is no IPv6 NAT, so a relay is reachable at its rendezvous address as soon as it claims it; its security group limits that to the ports above.
Can I use my existing VPC?
Not with the configurations covered by these docs: each creates its own VPC. See Known limitations.
Kubernetes
Can workers be Kubernetes nodes?
Yes. In the EKS topology each worker joins your Amazon EKS cluster as a node, appears in kubectl get nodes as Ready next to the EC2 nodes, holds a VPC address and is named after the relay whose identity it wears. Nodes carry the label cloudspectra.ai/compute-location (oci or digitalocean), so you can schedule onto them or away from them. See EKS topology.
Which CNI does the EKS topology use?
Calico, in VXLAN mode, which the configuration installs. The AWS VPC CNI is not used in that topology.
Billing
What does Cloud Spectra charge for?
The relays, per vCPU-hour, at your licence's lane rate: Developer $10 or Enterprise $30 per vCPU per month (nominal 730-hour month). Every relay's second vCPU is free, and any clock hour a relay runs is billed as a whole hour. The workers and the client are free. See Pricing.
What will my cloud providers charge for?
Everything they normally would: the relay instances, the load balancer and other AWS resources the configuration creates, the OCI or DigitalOcean workers, and data transfer. Traffic between a relay and its worker crosses clouds, so each cloud bills the traffic that leaves it -- in both directions.
Is there a limit on how many relays I can run?
On the Developer lane an account may run at most 16 vCPUs; relays beyond that park and carry no traffic until room frees. The Enterprise lane has no account limit but requires at least 4 vCPUs per relay.
Operations
How do I scale?
Change the relay Auto Scaling group's desired capacity. On OCI and in the EKS topology the workers follow by themselves; with the DigitalOcean pool, set worker_count to match. The pool configurations can also scale the group on the load of each relay-worker pair. See Scaling.
How do I upgrade?
Change package_version, apply, and replace the relays and workers. Running instances keep the version they booted with. See Upgrades.
How do I get a shell on a relay or a worker?
Set admin_cidrs to your address range and give the configuration your SSH public key. Relays: log in as admin on port 22 while the relay boots, and on port 28301 once it runs. Workers: ubuntu on OCI, root on DigitalOcean. See Access for debugging.
How do I remove CloudVpc?
terraform destroy in the configuration you applied. See Teardown for the cases that need a second pass.
Where do I get help?
Email support@cloudspectra.ai with the configuration you applied, its terraform output (without secrets), and the relay and worker logs described in Troubleshooting.
Known limitations
- Clouds. The relay (identity) side is AWS only. The worker (compute) side is OCI or DigitalOcean.
- One worker per relay. Every worker costs a relay instance in AWS.
- Stateless, compute-bound workloads only. EBS and other block storage attach to an EC2 instance -- the relay, not the worker.
- No serverless containers as workers. The worker needs
NET_ADMIN. - Linux workers only, kernel 5.10 or newer.
- Cross-cloud data transfer is billed by both clouds.
- A worker's private address follows its relay. When a relay is replaced, the worker that pairs with the replacement wears a different address.
- New networks only. The configurations covered by these docs create their own AWS VPC and their own OCI or DigitalOcean network; attaching relays to an existing VPC is not covered.
- IPv6 is required. The VPC must be dual-stack, and in the pool configurations the workers need IPv6 egress, because relays are found at IPv6 rendezvous addresses.
- The OCI pool has no fleet-wide safety rail. Each worker decides alone whether to grow the pool or remove itself, and each holds an AWS access key that can only call
DescribeAutoScalingGroups. The EKS topology's controller adds per-pass limits this topology lacks. - The DigitalOcean pool does not resize itself (set
worker_count) and creates no DigitalOcean Cloud Firewall for its Droplets; add one. - Pair-load scaling is available only in the pool configurations, is off by default, and must not be combined with anything else that sets the relay group's size.
- EKS topology: relays are placed in one subnet with 8 rendezvous addresses, so it runs at most 8 relays (and 8 worker nodes).
- No in-place upgrade of running instances. A new
package_versionreaches relays and workers only when they are replaced. - The licence key is placed on each worker (
/etc/cloudspectra/licence, mode 0600) so the worker can download the client, which also puts it in the worker's launch metadata and in Terraform state.