CloudVpc -- Overview v1.0.0

CloudVpc makes a machine in another cloud an ordinary member of your AWS VPC. A small relay instance in your VPC holds a private IPv4 address. A worker -- a Linux VM in Oracle Cloud Infrastructure (OCI) or DigitalOcean -- wears that address over a WireGuard tunnel. The VPC's instance metadata service answers it, the relay's IAM role works for it, your security groups apply to it, and a load balancer registers it as a target, while the work itself runs on the other cloud's compute.

CloudVpc is one of the four relay modes of Cloud Spectra Gateway; its mode value is cloud_vpc.

What CloudVpc is

Every CloudVpc deployment has two halves, and they are independent of each other:

Relays and workers are paired one to one: each relay serves exactly one worker, and each address is worn by exactly one machine. The number of workers follows from the number of relays; it is never a separate setting.

           Your AWS VPC (10.0.0.0/16)                       Oracle Cloud or DigitalOcean
  +-----------------------------------------+          +------------------------------------+
  |  load balancer, IAM, security groups,   |          |                                    |
  |  private endpoints, other instances     |          |                                    |
  |                                         |          |                                    |
  |  relay A  holds 10.0.1.21  ==============WireGuard=====  worker A  wears 10.0.1.21      |
  |  relay B  holds 10.0.1.22  ==============WireGuard=====  worker B  wears 10.0.1.22      |
  |                                         |          |       |                            |
  +-----------------------------------------+          |  worker A <---- direct ----> worker B
                                                       +------------------------------------+
  The tunnel carries the VPC range and the metadata address. Other traffic stays local.

Illustrative addresses.

The problem it solves

Moving a workload to another cloud is rarely blocked by the workload. It is blocked by everything around it: the VPC, the security groups, the IAM roles, the load balancer, the DNS names, and the services that reach the workload by private address. CloudVpc moves only the compute and leaves the rest where it is.

• Use another cloud's compute without a second network design. Run workers on OCI or DigitalOcean capacity while the network, identity and data stay in AWS.
• No AWS access keys for your workload. The worker reaches the VPC's metadata service through the tunnel, so the AWS SDKs on the worker obtain temporary credentials for the relay's instance role, the same way they do on EC2.
• Kubernetes nodes in another cloud. A worker can join an Amazon EKS cluster as a Ready node that holds a VPC address. See EKS topology.
• One number sizes the fleet. The relays are an EC2 Auto Scaling group. On OCI and in the EKS topology, the workers follow the group's size by themselves.

CloudVpc and the other relay modes

A relay runs in exactly one of four modes. Choose CloudVpc when a machine outside AWS must behave as a member of your VPC.

How it works

flowchart LR
    subgraph FAR["Another cloud -- OCI, DigitalOcean, OpenStack, on-prem"]
        direction TB
        W["Worker
runs your image
wears 10.0.1.11"]
        INET["Internet
package installs, image pulls"]
    end
    subgraph VPC["Your AWS VPC"]
        direction TB
        R["Relay
private IPv4 10.0.1.11
forwards without translating"]
        SVC["Your services
security groups, target groups,
VPC endpoints"]
        IMDS["169.254.169.254
instance metadata + IAM role"]
    end
    W -->|"WireGuard: the VPC range
and 169.254.169.254 only"| R
    W -. "default route stays here --
internet traffic never crosses" .-> INET
    R --> SVC
    R --> IMDS
    SVC -. "sees the relay's private address,
so the worker IS the relay to it" .-> R
    style VPC fill:#eef2ff,stroke:#6366f1,color:#312e81
    style R fill:#d1fae5,stroke:#10b981,color:#065f46
    style W fill:#d1fae5,stroke:#10b981,color:#065f46
    style INET fill:#fef3c7,stroke:#f59e0b,color:#92400e
    style IMDS fill:#fff7ed,stroke:#fb923c,color:#7c2d12

The tunnel carries the VPC, not the internet

Each worker routes the VPC's address range and the instance metadata address, 169.254.169.254, through its WireGuard tunnel. Its default route stays on its own cloud, so package installs, container pulls and other internet traffic do not travel through AWS. The relay never pushes a worker into a full tunnel: tunnelling everything is a per-client choice, and the CloudVpc configurations do not make it.

The relay forwards between the tunnel and the VPC without translating addresses. Inside the VPC, the worker's packets carry the relay's private address as their source, which is why security groups, load balancer target groups and VPC endpoints treat the worker as the relay.

Which address is which

Each relay has several addresses. Only its identity addresses are transferred to the worker; the endpoint is only how the worker reaches the relay.

Worker-to-worker traffic goes direct

When two workers talk to each other they do not hairpin through AWS. Each worker advertises its host address, and workers exchange traffic directly, encapsulated in GENEVE over UDP and spread across four source ports so the cloud network can balance it. Until a direct path is known, traffic falls back through the relays.

How relays and workers find each other

• Rendezvous addresses. Terraform pre-allocates a block of IPv6 addresses in each relay subnet. At boot each relay claims one with an EC2 API call. Because AWS assigns an IPv6 address to exactly one network interface, the claim itself is the lock -- no database or lock service is involved. This is why the autoscaling topologies need a dual-stack VPC.
• Enrolment. Workers poll the block, find a relay that answers, and enrol with the fleet's enrolment token. In the pool topologies each relay accepts the token once, so the first worker to reach a relay pairs with it and the others move on to the next address.
• Keys stay where they are used. Each worker generates its own WireGuard key pair and sends only the public half; in the autoscaling topologies each relay generates its own key at first boot. No WireGuard private key is written to Terraform state.
• Reconciliation (EKS). In the EKS topology a Cloud Spectra controller in your cluster scans relays and workers by tag, launches a worker for every unpaired relay, and retires workers whose relays are gone, within limits on how much one pass may remove.

Security in brief

• Your accounts are the boundary. Relays run in your AWS account and workers in your OCI or DigitalOcean account. Traffic between them is encrypted by WireGuard.
• Containers do not inherit the relay's role. The relays' metadata hop limit defaults to 1 and the relay caps the metadata service's replies to one hop. A process on the worker host reaches the metadata service; a container one forwarding hop further away does not.
• Few open ports. Workers reach a relay on its WireGuard port and its enrolment port. SSH is closed unless you list your own address ranges.

The full model is in the User Guide under Security model.

Supported clouds and topologies

The relay side is AWS. Other clouds on the relay side, and other clouds on the worker side, are not supported in this release.

Requirements

• An AWS account for the relays, and an OCI or DigitalOcean account for the workers.
• A Cloud Spectra licence key. A relay without a valid licence starts but forwards nothing. Buy one from your account page.
• The CloudVpc Terraform configurations and the relay machine image (an arm64 AMI of the Cloud Spectra Gateway image) for your release. See Quick Start prerequisites.
• Terraform 1.5 or later.
• Workers: Linux with kernel 5.10 or newer, run as root (the client needs CAP_BPF and CAP_NET_ADMIN), with IPv6 egress in the pool topologies. The configurations create workers that meet these requirements.

Pricing

Cloud Spectra bills CloudVpc on the relays, per vCPU-hour, at the rate of the lane your licence is on: Developer at $10 per vCPU per month or Enterprise at $30 per vCPU per month (a nominal 730-hour month). The second vCPU of every relay is free, and only the first 64 vCPUs of a relay count, so a relay bills at most 63 vCPUs. The relay mode does not change the rate.

• Workers are free. The Cloud Spectra client is not billed, and there is no per-device charge.
• Developer lane: an account may run at most 16 vCPUs (raw, not billed); relays beyond the limit park and carry no traffic. Enterprise lane: no account limit; each relay needs at least 4 vCPUs.
• Your cloud providers bill the relay instances, the workers, the load balancer and data transfer as usual.

See Pricing for the full terms.

Limits

• One worker per relay, always.
• Stateless, compute-bound workloads. EBS volumes attach to an EC2 instance -- the relay, not the worker.
• The worker must be a machine you control. It needs NET_ADMIN, so managed serverless containers (AWS Fargate, Google Cloud Run, Azure Container Instances) cannot host one.
• Cross-cloud traffic is billed by both clouds.
• The full list is in the FAQ under Known limitations.

Next steps

• Quick Start -- deploy relays in AWS and workers in OCI, verify, and tear down.
• User Guide -- architecture, configuration reference, topologies and operations.
• FAQ -- common questions and known limitations.
• Questions: support@cloudspectra.ai.