Cloud VPCs

A cloud VPC adds an offline AWS region to your canvas. Learners can work with AWS services safely, and nothing leaves the range.

What a cloud VPC is

Open the Cloud rail panel and drag the AWS card onto the canvas. Azure and Google Cloud are marked “Coming soon”.

The VPC is created right away with sensible defaults. The platform adds the region box when the canvas builds. A machine you drop inside it shows up as an EC2 instance when you give it the register-as-instance plugin (see Give a VM an instance role).

Configure it

Double-click the VPC, or choose Edit, to open the Cloud VPC panel. The panel has these settings:

• Name. The name must end in .local.
• VPC CIDR. The VPC’s address range, for example 192.168.10.0/24. The router and the DHCP pool follow this range. Keep it clear of the VPCs your seed files create (see Keys and permissions).
• Provider. The cloud vendor. Only AWS is available today. Azure and Google Cloud are coming.
• Region. An AWS region name, such as us-east-1. The region box uses it.
• Web console. The region’s browser console, on port 4500. New cloud VPCs start with it off. It has no login and acts with the range’s admin key, so everyone on the cloud network is admin while it is on. Turn it on only for labs where students should be admin (see Keys and permissions). Existing VPCs keep their setting. A change takes effect on the next redeploy, which rebuilds the region box.
• DHCP, DNS and more network settings. This link opens the rest of the network options.

Seed files

Seed files create resources in the region when the canvas builds. Each file has a name and content.

Allowed file names:

• <name>.tf for Terraform. Terraform is a tool that creates cloud resources from files that describe them.
• terraform.tfvars or <name>.auto.tfvars for Terraform variables. These files hold the values your Terraform files use.
• <name>.sh for bash. A bash script is a list of shell commands that run one after another.

A name can use letters, digits, dots, dashes, and underscores. It can’t start with zz_roguecloudos_, and it must be unique within the VPC.

Limits:

• At most 50 files.
• At most 200,000 characters in total.

Run order:

1. All Terraform files apply together in one run.
2. Bash files run after that, one at a time, in list order.

Use the buttons above the list:

• New file adds an empty file.
• Upload accepts several files at once. An uploaded file with the same name as an existing one replaces it.
• Browse samples opens the sample library.

Keys and permissions

Each range gets its own AWS admin key. An admin key can do anything in the account. The platform sets it up for you:

• The region box runs your seed files with it.
• Every box with the cloud-client plugin already has it. On Linux it is in each user’s ~/.aws/credentials. On Windows it is in C:\ProgramData\roguecloudos\aws-credentials, which administrators and anyone signed in at the console or over RDP can read. Services and network logons can’t read it.
• The cloud-tools plugin installs the same tools with no key (see Give learners the AWS tools without the key).

Nobody types or copies a key. The AWS CLI, SDKs and Terraform find it on their own. The test key that local AWS tutorials use is refused. On Windows the key file is read-only, so aws configure can’t save into it. To use another key there, point AWS_SHARED_CREDENTIALS_FILE at your own file.

The region checks requests the way AWS does. It checks the request’s signature, then IAM policies, service control policies (SCPs), S3 bucket policies and SNS topic policies. A call the key isn’t allowed to make gets AccessDenied. A few checks aren’t there yet. See what the region doesn’t check yet.

When you write seed files:

• Leave access_key and secret_key out of your Terraform provider "aws" block. A provider block that names its own key stops the build with “remove access_key and secret_key from your provider block; the range’s key is set up for you”.
• Don’t print the environment or a key in a bash seed. Seed output goes to the build log.
• For a learner with fewer rights, create an IAM user or role in the seed with only what the lab needs.
• Tag keys that start with roguecloudos: are reserved for the platform. The region refuses to create them, as it does for aws: tags.
• Give every VPC your seeds create a CIDR outside the cloud VPC’s own range. If one overlaps it, the build fails and names the VPC. The build checks the admin account’s VPCs only, but the rule applies to member accounts too.
• Every AWS region’s default VPC uses 172.31.0.0/16, so a cloud VPC inside that range always fails. The samples put their VPCs in 10.x.0.0/16 ranges, so a cloud VPC inside 10.0.0.0/8 can collide with one of them.

Anyone signed in to a cloud-client box is the account admin. While the Web console switch is on, the console has no login and acts with the admin key, so everyone on the cloud network is admin too. The region box itself takes no SSH or password logins. The platform reaches it on its own channel.

If learners must not have admin, for example in a credential or role-hop lab:

• Don’t give learners a cloud-client box. Give them a VM with an instance role (see below), and add the cloud-tools plugin if they need the AWS tools.
• Leave the Web console switch off in the cloud VPC’s panel.

Give a VM an instance role

An instance role lets a VM act as an IAM role, the way an EC2 instance does on AWS. Tools on the VM get the role’s short-lived keys from the instance metadata service, and nothing more.

1. In a seed file, create the IAM role and the policies the lab needs. If the role doesn’t exist at build, the plugin creates it with no permissions.
2. Put the VM inside the cloud VPC; the plugin works only there. Linux and Windows VMs both work.
3. Add the register-as-instance plugin to the VM and set InstanceRole to the role’s name.
4. On every Debian VM, also set InstanceName. Debian VMs all start with the same hostname, and each instance needs its own name.

After the build, the VM shows up as an EC2 instance at its own address. The AWS CLI, SDKs and Terraform on it use the role’s temporary keys from 169.254.169.254. Both IMDSv1 and IMDSv2 work, so a learner who gets onto the VM can take the role’s keys, as on a real EC2 instance. A call outside the role gets AccessDenied. The plugin leaves no key on the VM.

Only VMs registered with register-as-instance get role keys from the instance metadata service. Other VMs in the cloud VPC get none.

Don’t add the cloud-client plugin to a VM whose users must stay inside the role. That plugin sets up the admin key, and the AWS tools pick it before the role. Add cloud-tools instead.

Give learners the AWS tools without the key

The cloud-tools plugin installs the AWS CLI, Terraform, kubectl and Helm, pointed at the range’s cloud region. It puts no admin key on the VM.

• On a VM registered with register-as-instance, the tools act as that VM’s role, with nothing to type.
• On any other VM they have no credentials until a learner supplies some.

Settings:

• RegionName. The region name, us-east-1 by default.
• EndpointHost. The region’s host, aws.local by default.
• InstallDocker. Off by default, and Linux only. Turn it on only if learners need Docker, since Docker access is root access on that VM.

Use cloud-client instead when a box should hold the range’s admin key. Don’t add both to one VM: cloud-client’s key wins, and every user on the box is admin.

Sample library

The library has 134 ready-made samples in 12 categories. See the full list of samples.

Open it with Browse samples in the Cloud VPC panel. Pick a sample, choose Add to VPC, and then click Save. The Cloud panel also has a “Browse sample scripts” link that opens the same library for browsing and copying.

Samples are built to be combined, so you can add many of them to one VPC.

To see which topics a learner can practice end to end, read What you can configure and practice.

Kubernetes service mesh (EKS)

The Kubernetes category in the library holds eight samples. They build an EKS cluster, then a service mesh with mutual TLS on it. Mutual TLS means both sides of every connection prove who they are with a certificate.

Sample	What it shows
eks-cluster	The cluster named mesh that the other samples install into. Add it first.
envoy-sidecar-static	An Envoy proxy beside each app, with certificates made at install.
envoy-cert-manager-sds	Short-lived certificates from cert-manager that Envoy picks up without a restart.
istio-strict	Istio refusing any connection without mutual TLS, with access rules per service.
envoy-node-proxy	One shared Envoy per node, and a revoked certificate refused.
envoy-xds-consul	Services found through Consul, and a control plane that checks each config before Envoy gets it.
envoy-authz	Access decided by the caller’s certificate, in Envoy or in a small policy service.
smokescreen-egress	Outbound traffic allowed only to listed hosts, per service.

1. Add eks-cluster first, then the others, from Browse samples → Kubernetes. Bash files run in list order, so the cluster is ready before the others install.
2. All eight together need region size Large. Each sample’s description gives its measured size.
3. Each sample has a check script, <sample>-check.sh. The build never runs it. The checks are preloaded on Linux cloud-client and cloud-tools boxes at /opt/roguecloudos/eks-checks/. Run bash /opt/roguecloudos/eks-checks/<sample>-check.sh. Windows boxes have none, and Add to VPC adds only the Terraform and the installer. A check prints PASS or FAIL for each test, then one MESH-CHECK line.
4. To run a sample by hand instead, copy its files to a cloud-client box. Run terraform init && terraform apply (only eks-cluster and envoy-xds-consul have Terraform), then bash <sample>.sh, then bash /opt/roguecloudos/eks-checks/<sample>-check.sh.

Your own images and files:

• Upload docker save image archives under Images and files in the Cloud VPC panel. The region loads them at build. Images from Docker Hub, Quay, GitHub, Kubernetes, Google and public ECR registries are pulled by their usual name, such as docker.io/library/busybox:1.37. An image from any other registry is pushed to the range’s ECR and pulled as 000000000000.dkr.ecr.<region>.aws.local:4566/<registry host>/<path>:<tag> (the host lowercased, a port’s colon written as a dash), for example 000000000000.dkr.ecr.us-east-1.aws.local:4566/registry.example.com-5000/team/app:1.
• Your bash seed files can read every other uploaded file from the folder in $CLOUD_FILES_DIR. For example: kubectl apply -f "$CLOUD_FILES_DIR/app.yaml".
• To apply your own Terraform from an upload, add the terraform-from-files sample (DevOps) and upload the Terraform as an archive named <name>.tf.tgz or <name>.tf.tar.gz. Each archive gets its own terraform init and terraform apply, and its state is kept between builds.
• From a Linux box with the cloud-client plugin you can also docker push images and helm push charts to the region’s ECR, then deploy them to the cluster.

With Oracle

You can ask Oracle to add a sample, write a seed file, or clear the seed files. Oracle finds the tools it needs on demand.

What the region supports

The samples use these services:

APIGateway, Athena, CloudTrail, CloudWatch, Cognito, DynamoDB, EBS, EC2, ECS, EKS, ElastiCache, EventBridge, Firehose, Glue, IAM, KMS, Kinesis, Lambda, RDS, Route53, S3, SNS, SQS, SSM, STS, SecretsManager, StepFunctions, and VPC.

The region is a copy of AWS that runs inside the range. It copies the main AWS services, though not all of them. Managed detection services such as GuardDuty and Security Hub are missing, and so are some APIs.

The notes below are for people who write their own Terraform. If you only use the samples, you can skip them.

• EBS snapshots (saved copies of a disk) can’t be created.
• ECR repositories (stores for container images) can be created, but deleting them fails. Because cleanup hangs, avoid them.
• SSM documents (saved Systems Manager scripts) don’t work. Use SSM parameters, which store plain values, instead.
• Transit gateway VPC attachments (links from a VPC to a central network hub) fail.
• API Gateway API keys crash the Terraform provider. Usage plans work without them.
• CloudWatch Logs metric filters and composite alarms are not supported.
• For Redis, use an ElastiCache replication group (a Redis cache setup). The region refuses a plain Redis cluster.
• For Glue (data catalog) databases and tables, set catalog_id yourself.
• Network load balancer target groups need an HTTP health check, even for TCP targets.
• S3 object lock keeps objects from being deleted. Destroy fails on locked objects, so set force_destroy on them.
• Percentile alarms need extended_statistic, for example p95, instead of statistic.
• An account has only one IAM password policy, so only one seed can set it.