For Admins
For certain applications, Vocareum launches resources in your own AWS account. This depends on the business agreement between you and Vocareum and the type of labs used.
The three use cases for this type of integration are:
Virtual Machine Labs - creating Amazon Machine Images (AMIs) and provisioning Elastic Cloud Computer (EC2) instances for Vocareum VM Labs.
Custom Clusters - running Vocareum container-based labs (such as Vocareum Notebook) on managed EC2 server clusters inside your own AWS account.
Databricks - backing compute for students using Vocareum Databricks labs. See this article for the steps for setting up Databricks: Setting Up Databricks Resources.
If you plan to use your own AWS payer to provision individual accounts to students via Vocareum's AWS Cloud Labs, refer instead to Cloud Labs: Bring Your Own AWS Account.
Before you start
Vocareum does not ask for credentials to your account. Instead, you create a role named vocareumvm in your account and trust Vocareum's account to assume it.
Registering your account number is a Vocareum-side action - contact Vocareum Support to start the process. The overall process follows this order:
You send Vocareum the AWS account number you want used, and the regions you need.
You create the
vocareumvmrole and attach the policy for your use case.Vocareum registers the account and runs the automated setup, which creates the remaining resources in your account.
You complete any Databricks or Compute configuration that applies.
Once registered, you can review the configuration under Control Center → Custom Infra → VM Settings. Regions are configured as a set, so every step below — setup, the access proxies — is performed per region. Confirm the full region list with Vocareum up front.
Step 1 : Create the vocareumvm role
Create a role named exactly vocareumvm with this trust policy. Replace <Vocareum AWS account> with the account number Vocareum gives you.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::<Vocareum AWS account>:role/vocareum"
},
"Action": "sts:AssumeRole"
},
{
"Effect": "Allow",
"Principal": {
"Service": "ec2.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}Then attach the policy for your use case from the sections below.
The Budget field on the VM Settings page does not apply to customer-managed accounts so please ignore it.
Step 2 : Attach the appropriate policy
VM Labs
This policy covers both the resources Vocareum manages on your behalf and the automated account setup described in Step 3, which runs inside your account.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "CfnAndElb",
"Effect": "Allow",
"Action": [
"cloudformation:*",
"elasticloadbalancing:*"
],
"Resource": "*"
},
{
"Sid": "AccountSetupIam",
"Effect": "Allow",
"Action": [
"iam:GetRole",
"iam:GetPolicy",
"iam:GetUser",
"iam:GetInstanceProfile",
"iam:CreateRole",
"iam:CreatePolicy",
"iam:AttachRolePolicy",
"iam:CreateUser",
"iam:CreateAccessKey",
"iam:AttachUserPolicy",
"iam:CreateInstanceProfile",
"iam:AddRoleToInstanceProfile",
"iam:RemoveRoleFromInstanceProfile",
"iam:DeleteInstanceProfile",
"iam:PassRole"
],
"Resource": "*"
},
{
"Sid": "AccountSetupQueues",
"Effect": "Allow",
"Action": [
"sqs:CreateQueue",
"sqs:GetQueueAttributes",
"sqs:SetQueueAttributes"
],
"Resource": "*"
},
{
"Sid": "AccountSetupFileSyncLambda",
"Effect": "Allow",
"Action": [
"lambda:GetFunction",
"lambda:CreateFunction",
"lambda:ListEventSourceMappings",
"lambda:CreateEventSourceMapping"
],
"Resource": "*"
},
{
"Sid": "Ec2RestrictedByInstanceType",
"Effect": "Allow",
"Action": [
"ec2:*"
],
"Resource": "*",
"Condition": {
"StringEqualsIfExists": {
"ec2:InstanceType": [
"t2.micro",
"t2.small",
"t2.medium",
"t2.large",
"t2.xlarge",
"t2.2xlarge",
"t3.small",
"t3.medium",
"t3.large",
"r4.large",
"r4.xlarge",
"r4.2xlarge",
"r5.large",
"r5.xlarge",
"r5.2xlarge",
"r5.4xlarge",
"r6i.large",
"r6i.2xlarge",
"p3.2xlarge",
"p3.8xlarge",
"p3dn.24xlarge",
"dl1.24xlarge",
"g2.2xlarge",
"g3s.xlarge",
"g3.8xlarge",
"g4dn.xlarge",
"g4dn.2xlarge",
"g4dn.4xlarge",
"g4dn.12xlarge",
"g5.xlarge",
"g5.2xlarge",
"g5.4xlarge",
"g5.12xlarge",
"c5a.2xlarge",
"c5a.4xlarge",
"m5.large",
"m5.2xlarge",
"c5.metal",
"c5n.metal",
"m5zn.metal",
"m6a.large",
"m6a.2xlarge",
"m6a.4xlarge",
"m8i.large",
"m8i.xlarge",
"g6e.4xlarge"
]
}
}
},
{
"Sid": "ServiceLinkedRoles",
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "*",
"Condition": {
"StringEquals": {
"iam:AWSServiceName": [
"elasticloadbalancing.amazonaws.com",
"spot.amazonaws.com",
"spotfleet.amazonaws.com"
]
}
}
}
]
}Keep this instance-type list in sync. It must match the instance types offered in your courses.
The .metal types (c5.metal, c5n.metal, m5zn.metal) are required for nested-virtualization and VMware labs. t2.micro and t2.small are the access-proxy sizes and are required even if you never offer them as lab sizes.
Compute (custom clusters)
Use the VM Labs policy above, plus the following statements:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AssumeVocareumS3Role",
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": [
"arn:aws:iam::<Vocareum AWS account>:role/voc-s3-readwrite-role",
"arn:aws:iam::<Vocareum AWS account>:role/voc-s3-read-role"
]
},
{
"Sid": "ECRAccess",
"Effect": "Allow",
"Action": "ecr:GetAuthorizationToken",
"Resource": "*"
},
{
"Sid": "AllowPassRunServerRole",
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::<customer-aws-account>:role/runserver"
},
{
"Sid": "ALBPermissions",
"Effect": "Allow",
"Action": [
"elasticloadbalancing:RegisterTargets",
"elasticloadbalancing:DeregisterTargets"
],
"Resource": "*"
},
{
"Sid": "MountFilesystems",
"Effect": "Allow",
"Action": [
"elasticfilesystem:*"
],
"Resource": "*"
},
{
"Sid": "KmsAliases",
"Effect": "Allow",
"Action": [
"kms:ListAliases"
],
"Resource": "*"
}
]
}The S3 role lives in the Vocareum account, not yours. voc-s3-readwrite-role and voc-s3-read-role are Vocareum-side roles that your run servers assume to reach course and student work content.
Step 3 : Vocareum runs account setup
Once the vocareumvm role and its policy exist, let Vocareum know. Vocareum then runs an automated setup against your account, once per region.
vocareum-vm and vocareumvm are two different roles. vocareumvm is the control-plane role Vocareum assumes. vocareum-vm (hyphenated) is the instance-profile role attached to lab VMs, and setup creates it for you with the SSM, CloudWatch, DCV-licensing and S3 permissions the VMs need. Do not attach the VM Labs policy above to vocareum-vm, and do not merge the two roles.
Networking
The access proxies need inbound 80 and 443 from 0.0.0.0/0. Lab instance security groups additionally need inbound access from Vocareum's management addresses — Vocareum will provide these and configures the rules during setup. If you apply SCPs or use a restricted VPC, allow both.
DNS records for the access proxies are managed by Vocareum, so no Route 53 permissions are required in your account for VM labs.
Compute: the runserver role
To run backend interactive and grading clusters, create one additional role and policy.
1. Create the policy
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "SSM",
"Effect": "Allow",
"Action": [
"ssm:GetParameter",
"ssm:GetParameters",
"ssm:GetParametersByPath"
],
"Resource": "*"
},
{
"Sid": "KMSDecryptionForParameterStore",
"Effect": "Allow",
"Action": "kms:Decrypt",
"Resource": [
"arn:aws:kms:<region>:<customer-aws-account>:key/*"
],
"Condition": {
"StringLike": {
"kms:ViaService": "ssm.*.amazonaws.com"
}
}
},
{
"Sid": "CW",
"Effect": "Allow",
"Action": [
"cloudwatch:GetMetricData",
"cloudwatch:ListMetrics"
],
"Resource": "*"
},
{
"Sid": "CwAgentServer",
"Effect": "Allow",
"Action": [
"cloudwatch:PutMetricData",
"ec2:DescribeVolumes",
"ec2:DescribeTags",
"logs:PutLogEvents",
"logs:DescribeLogStreams",
"logs:DescribeLogGroups",
"logs:CreateLogStream",
"logs:CreateLogGroup"
],
"Resource": "*"
},
{
"Sid": "ECRPermissions",
"Effect": "Allow",
"Action": [
"ecr:GetAuthorizationToken",
"ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage"
],
"Resource": "*"
},
{
"Sid": "DynamoDBAccess",
"Effect": "Allow",
"Action": [
"dynamodb:UpdateItem"
],
"Resource": [
"arn:aws:dynamodb:<region>:<customer-aws-account>:table/ExecutionProcesses"
]
}
]
}
2. Create the runserver role
Create a role named exactly runserver with this trust policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::<Vocareum AWS account>:role/vocareum"
},
"Action": "sts:AssumeRole"
},
{
"Effect": "Allow",
"Principal": {
"Service": "ec2.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}Attach the policy from Step 1 and the AWS managed policy AmazonSSMManagedInstanceCore.
3. Container image access
Run servers pull container images from a Vocareum-hosted ECR registry in us-west-2. Vocareum will give you the registry URL and must add your AWS account number to the repository policy on its side — the ecr:* permissions above are necessary but not sufficient on their own.
4. DynamoDB table
Create a DynamoDB table named ExecutionProcesses in each region where you run clusters. The run servers write execution state to it.
Troubleshooting
A VM launches but never becomes ready. Lab VMs must register with Systems Manager. If the instance cannot reach the SSM endpoints — because of a missing VPC endpoint, an egress rule, or an SCP — the VM never reports as connected and the lab eventually fails to start. The SSM, ssmmessages and ec2messages permissions on the vocareum-vm role are load-bearing.
"Service role has insufficient EC2 permissions." Almost always an instance type missing from the allowlist in the VM Labs policy. Compare the list against the instance types your courses offer.
"Cannot set up access routes for the VM." Vocareum could not reach the access proxies in your account over SSH. Check that the proxy security group still allows Vocareum's management addresses on port 22, and that the proxy instances are running.
Note
It is good practice to create your account as a member account in a separate AWS Organization, to keep Vocareum-related resources and billing isolated from other activity. You can also apply organization-level SCPs to further reduce risk. If you do, make sure the SCPs allow the instance types, regions and services listed above.