# Prerequisites

## Specialized Knowledge <a href="#specialized_knowledge" id="specialized_knowledge"></a>

This deployment requires a moderate level of familiarity with AWS services. If you’re new to AWS, see [Getting Started Resource Center](https://aws.amazon.com/getting-started/) and [AWS Training and Certification](https://aws.amazon.com/training/). 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 <support@codeocean.com> 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-north-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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/usingsharedamis-finding.html). 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](http://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](https://docs.codeocean.com/admin-guide/v3.2/deployment-parameters#domain-configuration).

## SSL Certificate Validation

The deployment provisions an SSL certificate through AWS ACM for the Code Ocean hosting domain and uses either [DNS Validation](https://docs.aws.amazon.com/acm/latest/userguide/dns-validation.html) or [Email Validation](https://docs.aws.amazon.com/acm/latest/userguide/email-validation.html) to validate domain ownership.

DNS validation is used for deployments that are both internet facing and use an [existing Route53 hosted zone](https://docs.codeocean.com/admin-guide/v3.2/deployment-parameters#domain-configuration). 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

{% hint style="warning" %}
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.
{% endhint %}

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](https://docs.codeocean.com/admin-guide/v3.2/deployment-parameters#tls-certificate-configuration) 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](https://console.aws.amazon.com/servicequotas).

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](https://docs.codeocean.com/admin-guide/v3.2/deployment-parameters#worker-configuration)):

{% hint style="warning" %}
If your quota does not allow sufficient resources your Code Ocean installation may not function.
{% endhint %}

#### 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](https://console.aws.amazon.com/servicequotas/home/services/ec2/quotas/L-1216C47A)

#### 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](https://console.aws.amazon.com/servicequotas/home/services/ec2/quotas/L-DB2E81BA)

{% hint style="info" %}
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.
{% endhint %}

#### **Spot Instance (Optional)**

If you wish to use Code Ocean's [dedicated machines feature with spot instance option](https://docs.codeocean.com/user-guide/compute-capsule-basics/structure-of-a-compute-capsule/environment/compute-resources#dedicated-machine), 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](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html#AmazonDNS).

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 has a NAT gateway, and it 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](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html#vpc-endpoints-security-groups) 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](https://docs.aws.amazon.com/whitepapers/latest/kms-best-practices/aws-managed-and-customer-managed-cmks.html) you will need to add permissions for the Code Ocean services IAM role in the [CMK key policy,](https://docs.aws.amazon.com/kms/latest/developerguide/control-access-overview.html#managing-access) or [create grants](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) for that role.

### Support for Multiple Availability Zones

Code Ocean can support up to six availability zones in the selected region to ensure instance type availability for dedicated machines. To allow this ability, please verify the following:

**Availability Zones Reachability**

Not all regions have six availability zones. Before specifying an additional availability zone in the CloudFormation template, verify that the zone is available and active in your region, meaning its *opt-in* status is set to *opt-in-not-required*. You can do this by running the following command from a CloudShell session.

```bash
aws ec2 describe-availability-zones --region [REGION] --query 'AvailabilityZones[*].ZoneName'
```

**Subnets Configuration**

If you are deploying a new AWS VPC and your initial version of Code Ocean was older than v2.21, you have to expand your VPC CIDR blocks by adding a secondary range. This can be done by navigating to the Code Ocean VPC, editing its CIDRs, and adding a new IPv4 CIDR for the additional future subnets (e.g. 10.1.0.0/16). Alternatively, if you are deploying on an existing VPC, ensure your desired additional availability zone has a private and public subnet deployed in.

**Elastic IP Addresses Quota**

If you are deploying a new AWS VPC, please ensure that your AWS account can create more *EC2-VPC Elastic IPs* than the default quota value of 5. Additionally, verify there is room for at least one available IP address per zone. You can check your current quotas and request a quota increase in the [AWS Service Quotas console](https://console.aws.amazon.com/servicequotas).