Prerequisites
Before you start, ensure you have an IAM role in your AWS that permits you to create CloudFormation Templates. Latch utilizes CloudFormation Templates to establish an IAM role that provisions AWS Resources to create a forch domainInstructions
Connecting an AWS Account
1
Go to this link
2
Log into the AWS account
3
You will be directed to an AWS CloudFormation 'Quick create stack' template.
When you open the CloudFormation template, you’ll see an acknowledgment stating “The following resource(s) require capabilities: [AWS::IAM::Role]. I acknowledge that AWS CloudFormation might create IAM resources with custom names.” This pertains to you as the customer executing the CloudFormation stack.
The stack creates a role that has permission to provision cloud resources, AWS ensures that you are aware of this action. The permissions of this role which can be verified by inspecting the cloudformation template in the AWS UI.Refer to [Advanced Notes](#Advanced Notes) for an overview of the permission this IAM role.
4
Click on the checkbox to acknowledge that this stack will create an iam role.
5
Click 'Create Stack' and wait for it to be created.
6
Notify someone at Latch with the following details.
- AWS Account Id
- Target AWS Region for this deployment (us-west-2, eu-central-1, etc)
Architecture
Please refer to this blog post for an overview of Forch’s architectureIAM
Each forch domain requires a minimum of 4 IAM role to operate:- forch-agent for provisioning cloud resources to setup the forch-domain
- forch-orchestrator for scheduling and managing tasks in the forch-domain
- forch-node for running the tasks in an compute instances the forch-domain
- forch-nat-* for running NAT instance in the forch-domain (1 per vpc)
forch-agent
forch-agent is created by the Cloudformation Stack from previous section. This role is used when provisioning cloud resources to setup the forch domain. The list of cloud resources created are as follows:
- Network resource including vpcs, subnets, internet gateways, security groups, network acls, route tables and elastic ip addresses
- An S3 Bucket for storing logs
- forch-orchestrator, forch-node and forch-nat-* roles and their policies
- A KMS key for encrypting and decrypting volumes created by forch
- An ec2 instance running the NAT server on the vpc
- Forch specific secrets
- Permisssions
- Policy Document
| Rules | Purpose |
|---|---|
s3:CreateBucket, s3:ListBucket*, s3:GetBucket*, s3:GetAccelerateConfiguration, s3:GetLifecycleConfiguration, s3:GetReplicationConfiguration, s3:GetEncryptionConfiguration, s3:PutBucketCORS, s3:PutBucketVersioning, s3:PutEncryptionConfiguration, s3:PutBucketRequestPayment | Retrieve the bucket metadata and configuration, compare it against the desired state, and apply any necessary updates to the S3 bucket arn:aws:s3:::forch-${AWS::AccountId} |
iam:CreateRole, iam:GetRole, iam:DeleteRole, iam:PutRolePolicy, iam:AttachRolePolicy | Retrieve configurations, compare it against the desired state, and apply any necessary updates to the IAM roles: arn:aws:iam::*:role/forch-orchestrator, arn:aws:iam::*:role/forch-node, arn:aws:iam::*:role/forch-nat-*, arn:aws:iam::*:role/forch-agent |
iam:CreateServiceLinkedRole | Create a service-linked role for the forch-agent linked service to AWS KMS |
iam:PassRole | Allows forch-agent to pass the forch-nat or forch-node role when launching NAT, SSH Forwarder and Pod Router instances |
iam:CreatePolicy, iam:GetPolicy, iam:DeletePolicy, iam:CreatePolicyVersion | Retrieve configuration, compare it against the desired state, and apply any necessary updates to the IAM roles: arn:aws:iam::*:policy/forch-orchestrator-base, arn:aws:iam::*:policy/forch-node-base, arn:aws:iam::*:policy/forch-agent-delete-permissions |
iam:CreateInstanceProfile, iam:DeleteInstanceProfile, iam:AddRoleToInstanceProfile | Create and manage instance profiles: arn:aws:iam::*:instance-profile/forch-nat-*, arn:aws:iam::*:instance-profile/forch-node |
ec2:CreateTags | Tag ec2 resources created by forch-agent |
ec2:CreateKeyPair, ec2:DeleteKeyPair, ec2:ImportKeyPair, ec2:DescribeKeyPairs | Create, import and manage a specific SSH key pair for access to forch-created instances |
ec2:CreateVpc, ec2:DescribeVpcs, ec2:DescribeVpcAttribute, ec2:CreateInternetGateway, ec2:AttachInternetGateway, ec2:DescribeInternetGateways, ec2:CreateSecurityGroup, ec2:AuthorizeSecurityGroupIngress/Egress, ec2:RevokeSecurityGroupIngress/Egress, ec2:DescribeSecurityGroups, ec2:DescribeSecurityGroupRules, ec2:CreateSubnet, ec2:DescribeSubnets, ec2:ModifySubnetAttribute, ec2:CreateRouteTable, ec2:CreateRoute, ec2:DescribeRouteTables, ec2:CreateNetworkAcl, ec2:DeleteNetworkAclEntry, ec2:CreateNetworkAclEntry, ec2:ReplaceNetworkAclAssociation | Retrieve the configuration of the Forch VPC and its associated network resources, compare it to the desired state, and apply any necessary updates |
ec2:AllocateAddress, ec2:AssociateAddress, ec2:DescribeAddresses, ec2:DescribeAddressesAttribute | Provision Elastic IP address for NAT instance, SSH Forwarder and Pod Router instance and associate them to the appropriate instances |
ec2:DescribeImages | Retrieve information about Latch-owned Forch ami image |
ec2:RunInstances, ec2:DescribeInstances, ec2:DescribeVolumes, ec2:DescribeAvailabilityZones | Retrieve information about the NAT, SSH Forwarder and Pod Router instance and launch them if not present. Instance must be launched with the forch-node instance profile, use the Latch-owned forch ami image and launched only with forch created ebs volumes |
ssm:GetParameters | Allows retrieving parameters (configuration data, environment variables, etc.) from AWS Systems Manager Parameter Store. Note: Required by AWS for ec2:RunInstances |
secretsmanager:CreateSecret, secretsmanager:PutSecretValue, secretsmanager:DeleteSecret | Create and manage the forch-nat JWT token, and ssh forwarder private keys |
kms:CreateKey, kms:PutKeyPolicy, kms:EnableKeyRotation, kms:CreateAlias | Create and manage the forch-volume key used to encrypt / decrypt forch created EBS volumes |
kms:Encrypt, kms:Decrypt, kms:GenerateDataKey*, kms:CreateGrant | Allows usage of KMS keys to decrypt EBS volumes and AMIs when launching instances |
forch-orchestrator
forch-orchestrator is assumed at runtime to schedule and manage tasks. It has permissions to:
- Run and Terminate ec2 instances on forch created vpc
- Assign Private IP Addresses to ec2 instances
- Create, Modify, Detach, Attach and Delete volumes
- Describe, Associate and Disassociate forch created elastic ip addresses
- Use KMS Keys to decrypt volumes
- Get and List objects in the S3 bucket storing logs
- Permisssions
- Policy Document
| Rules | Purpose |
|---|---|
ec2:RunInstances | Allows launching EC2 instances in the Forch VPC. Instance must be launched with the forch-node instance profile, use the Latch-owned forch ami image and launched only with forch created ebs volumes |
iam:PassRole | Allows the orchestrator to pass the forch-node IAM role to an EC2 instance upon creation, granting the instance its required permissions |
ssm:GetParameters | Allows retrieving parameters (configuration data, environment variables, etc.) from AWS Systems Manager Parameter Store. Note: Required by AWS for ec2:RunInstances |
ec2:TerminateInstances | Allows terminating EC2 instances that are tagged Created By: Forch |
ec2:AssignPrivateIpAddresses, ec2:AssignIpv6Addresses | Assign private IPv4 and public IPv6 addresses to instances within the Forch VPC |
ec2:DescribeNetworkInterfaces | Retrieve details of network interfaces attached to forch created instance to manage IP addresses |
ec2:DescribeInstances, ec2:DescribeInstanceStatus | To retrieve details and poll status of instances |
ec2:ModifyVolume, ec2:DetachVolume, ec2:CreateVolume, ec2:DeleteVolume, ec2:AttachVolume | To manage EBS volumes created by forch orchestrator |
ec2:DetachVolume, ec2:AttachVolume | Allows attaching/detaching volumes to/from instances using the forch-node Instance Profile AND is tagged Created By: Forch |
ec2:DescribeVolumesModifications, ec2:DescribeVolumes | Retrieve details of EBS volumes and storage device resize operations |
ec2:DisassociateAddress, ec2:AssociateAddress | Attach / Detach Elastic IPs to instances in the Forch VPC |
ec2:DescribeAddresses | Allows retrieving details of all Elastic IP addresses in the account |
ec2:CreateTags | Tag ec2 instances created by forch orchestrator |
s3:GetObject | Retrieve logs from the log storage s3 bucket |
s3:ListBucket | List the contents of the log storage S3 bucket |
sts:AssumeRole | Allows the forch orchestrator to assume another IAM role in the AWS account |
secretsmanager:UpdateSecret, secretsmanager:CreateSecret | Create and update secrets tagged with forch/allow: true |
kms:ReEncrypt*, kms:GenerateDataKey*, kms:Encrypt, kms:DescribeKey, kms:Decrypt, kms:CreateGrant | Allows usage of KMS keys to decrypt EBS volumes and AMIs when launching instances |
forch-node
forch-node role has permission to get the task secrets from secretsmanager, read and write logs to the s3 bucket and also assume the forch-node-shared role to get access to ecr images and secrets from Latch’s aws account. This role’s can only be assumed by roles within the forch domains’ cloud account.
- Permisssions
- Policy Document
| Rules | Purpose |
|---|---|
s3:PutObject, s3:GetObject | Store log files to the S3 bucket. Retrieve files for log verification or log rotation |
s3:ListBucket | List the bucket contents to check for the existence of the logs folder, manage file rotation, or check the state of previously uploaded batches of logs |
ec2:DescribeAddresses | Retrieve information about EC2 Elastic IP addresses attached to the instance to configure networking |
sts:AssumeRole | Used to assume the IAM role forch-node-shared to get access to resources in Latch’s AWS Account (ECR images, secrets) |
secretsmanager:GetSecretValue | Retrieve secrets tagged with forch/allow: true |
secretsmanager:BatchGetSecretValue | Allows retrieving multiple secrets at once |
forch-nat-*
forch-nat-* role is a superset of forch-node. It has additional permissions to get the nat-jwt-* JWT token from secretsmanager to perform database authentication
- Permisssions
- Policy Document
| Rules | Purpose |
|---|---|
secretsmanager:GetSecretValue | Retrieve JWT token to authenticate with Latch’s database |