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. For Vocareum VM labs, the use case for this type of integration is creating Amazon Machine Images (AMIs) and provisioning Elastic Cloud Computer (EC2) instances.
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.
For more context on VM Labs and where this process fits in, refer to the article What are Vocareum Virtual Machine Labs?
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.
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.
Attach the appropriate policy
This policy covers both the resources Vocareum manages on your behalf and the automated account setup described in the next section below, 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.
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.
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.