Prerequisites

Learn what is required to prepare for deployment.

Specialized Knowledge

This deployment requires a moderate level of familiarity with AWS services. If you’re new to AWS, see Getting Started Resource Center and AWS Training and Certification. These sites provide materials for learning how to design, deploy, and operate your infrastructure and applications on the AWS Cloud.

Request Code Ocean AMIs

To share the Code Ocean AMI with your company's AWS account, contact our support or email [email protected] with your company's AWS account ID.

We currently support us-east-1, us-east-2, us-west-1, us-west-2, eu-central-1, eu-west-2, ap-southeast-2 and ca-central-1 AWS regions so please include your preferred region in the request. After you get the confirmation from Code Ocean, you can check for shared AMIs in your AWS account by following the instructions in Find Shared AMIs. You should see the following AMI:

codeocean-vpc-amzn2-[timestamp]

Create AWS IAM Service Linked Roles

The next step is to create AWS IAM service-linked roles for the various AWS services in use by the Code Ocean deployment, such as AWS Batch, RDS, and OpenSearch. Execute the following AWS CLI commands, make sure to use your selected region:

aws iam create-service-linked-role --aws-service-name autoscaling.amazonaws.com
aws iam create-service-linked-role --aws-service-name batch.amazonaws.com
aws iam create-service-linked-role --aws-service-name elasticache.amazonaws.com
aws iam create-service-linked-role --aws-service-name elasticfilesystem.amazonaws.com
aws iam create-service-linked-role --aws-service-name elasticloadbalancing.amazonaws.com
aws iam create-service-linked-role --aws-service-name es.amazonaws.com
aws iam create-service-linked-role --aws-service-name rds.amazonaws.com
aws iam create-service-linked-role --aws-service-name spot.amazonaws.com

The commands might return an error if the roles already exist in the AWS account, in which case the error can be ignored.

Choose a Hosting Domain

The deployment will create a new AWS Route53 hosted zone to host the Code Ocean deployment. The domain name for this hosted zone is made up of the Code Ocean application subdomain (codeocean by default) and a root (parent) domain. For example, company XYZ has root domain XYZ.com, therefore the hosting domain for Code Ocean will be codeocean.XYZ.com

If you choose an internet-facing deployment type you will need to configure the parent domain (in our example, XYZ.com) to delegate the Code Ocean subdomain to Route53 by adding an NS record to the parent domain, so access to configure DNS on the parent domain is required.

Alternatively, you can use your own Route53 hosted zone and have the Code Ocean deployment add DNS records under it. This Route53 hosted zone must reside in the same deployed AWS account. You can specify your Route53 hosted zone under "Existing Route 53 Hosted Zone ID" in the deployment parameters.

SSL Certificate Validation

The deployment provisions an SSL certificate through AWS ACM for the Code Ocean hosting domain and uses either DNS Validation or Email Validation to validate domain ownership.

DNS validation is used for deployments that are both internet facing and use an existing Route53 hosted zone. In that case, the certificate validation will happen automatically and the certificate will be eligible for automatic renewal.

For other types of deployments, email validation is used. To approve the certificate, you must have access to one of the following email addresses:

• administrator@your_root_domain_name

• hostmaster@your_root_domain_name

• postmaster@your_root_domain_name

• webmaster@your_root_domain_name

• admin@your_root_domain_name

You or your IT administrator must have access to one of these email addresses when certificate email validation is used. The Code Ocean deployment will eventually fail if you are unable to approve the certificate request.

Alternatively, it is possible to provide the deployment with a pre-validated ACM certificate ARN as a CloudFormation template parameter. In this case, no further certificate validation is required. See the CloudFormation deployment parameter section for details.

AWS Account Requirements

Region and Availability Zones

Make sure the following resources are available for provisioning in your region and availability zones:

• OpenSearch instance type t3.small.search

• ElasticCache instance type cache.t3.micro

Service Quotas

If you are deploying a new AWS VPC please make sure that your AWS account allows an additional VPC to be created. This includes other VPC resources such as NAT Gateways, Internet Gateway, EIPs, etc. You can check your current quotas and request a quota increase in the AWS Service Quotas console.

In addition, make sure that the following service quotas have sufficient capacity. (If you require a quota increase and your request is declined, a smaller instance type should be configured during deployment):

If your quota does not allow sufficient resources your Code Ocean installation may not function.

Running On-Demand Standard (A, C, D, H, I, M, R, T, Z) instances

Code Ocean services machine is m5.large and it utilezes 2 vCPUs. The default general purpose worker instance type is r5d.4xlarge and it utilizes 16 vCPUs. In order to deploy with the default configuration you must have at least 34 vCPUs in Running On-Demand Standard (A, C, D, H, I, M, R, T, Z) instances quota.

Link to Quota

Running On-Demand G and VT instances

Code Ocean default GPU worker instance type is g4dn.4xlarge and it utilizes 16 vCPUs. In order to deploy with the default configuration you must have at least 32 vCPUs in Running On-Demand G and VT instances quota.

Link to Quota

When a worker enters the "running" state a new worker is provisioned to enter the warm pool and then stopped. During the window when one worker enters the running state and one enters the initialization state, both workers will run simultaneously so your quota must allow sufficient vCPUs for two workers.

Spot Instance (Optional)

If you wish to use Code Ocean's dedicated machines feature with spot instance option, you should also check for sufficient quota for:

• All P Spot Instance Requests

• All Standard (A, C, D, H, I, M, R, T, Z) Spot Instance Requests

• All G and VT Spot Instance Requests

• All X Spot Instance Requests

Networking

The default DHCP option set in your AWS account needs to be configured with DNS servers that can resolve internal AWS hostnames, such as EFS-file-system-id.efs.aws-region.amazonaws.com, for example, by using AmazonProvidedDNS.

If you are deploying into an existing AWS VPC please make sure that the VPC is configured with 2 private subnets as a minimum, both should be defined on the VPC's main CIDR block, each with a minimum of 256 addresses (/24 mask bit, the smaller the mask bit the bigger the address range, we recommend to use /16 mask bit). Also, please make sure that the VPC is configured with both DNS Resolution and DNS Hostnames enabled.

If you are deploying into an existing AWS VPC and the VPC is configured with VPC endpoints for SSM or EC2 (PrivateLink) using a security group that restricts access to these endpoints you'll need to add an ingress rule in the security group for the Code Ocean services security group and the Code Ocean workers security group. This will allow the Code Ocean instances to make the required SSM and EC2 API calls.

KMS

If your AWS account is configured with AWS KMS Customer-managed CMKs you will need to add permissions for the Code Ocean services IAM role in the CMK key policy, or create grants for that role.