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 custom clusters, Vocareum container-based labs (such as Vocareum Notebook) run on managed EC2 clusters inside your own AWS account.
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 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 — Vocareum does not manage the budget in your account. You can ignore it.
Attach the appropriate policy
Use the VM Labs policy below, plus the following statements for custom clusters.
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.
VM Labs
{
"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"
]
}
}
}
]
}
Compute
{
"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. Earlier revisions of this article pointed these ARNs at the customer account, which does not work.
Vocareum runs account setup
Once the vocareumvm role and its policy exist, tell Vocareum. Vocareum then runs an automated setup against your account, once per region. Setup is resumable, so if it stops on a missing permission it can be re-run safely after you correct the policy.
Setup creates the following in your account, so you do not need to create them by hand:
IAM policy, role and instance profile for lab VMs —
vocareum-vmIAM user + access key used by file sync —
vocareum-vmFile-sync SQS queue and its dead-letter queue
File-sync Lambda function and event-source mapping
Access-proxy security group, key pair and instance profile —
vocareum-proxyAccess-proxy EC2 instances (
t2.small) and Elastic IPs — per regionMachine image used by the access proxies — copied in per region
vocareum-vm and vocareumvm are two different roles. vocareumvm (no hyphen) 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.
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.
The role also needs an instance profile named exactly runserver that contains the role. Vocareum looks up the instance profile by this name when a cluster is added, and adding the cluster fails if it does not exist. The IAM console may create it for you along with the role; the AWS CLI, Terraform and CloudFormation do not. Check whether it exists:
aws iam get-instance-profile --instance-profile-name runserver
If this returns NoSuchEntity, create it and add the role:
aws iam create-instance-profile --instance-profile-name runserver
aws iam add-role-to-instance-profile --instance-profile-name runserver --role-name runserver
With Terraform, add an aws_iam_instance_profile resource; with CloudFormation, add an AWS::IAM::InstanceProfile resource. In both cases, name it runserver and include the runserver role.
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.
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.