AWS setup
The customer's admin runs setup once, with their own AWS credentials, using CloudFormation, Terraform or the project-branded deploy CLI. All three create the same resources. After setup, your manager makes changes through a management role that setup created, and the admin doesn't need to run anything for releases.
Permissions to run setup
Setup creates IAM roles and policies as well as the application's resources, so the admin needs permission to create IAM roles and every resource type the stack uses. In practice that means an administrator role in the target account, or a role that can create the resources below.
| Kind | What setup creates |
|---|---|
| IAM | A role for each permission profile in the stack, and the management role <stack name>-management. Only your manager's identity (the ManagingRoleArn parameter) can assume the management role. An instance profile for compute machines. |
| Network | With NetworkMode set to create-new: a VPC, subnets, an internet gateway, NAT gateways, Elastic IPs, route tables and security groups. With use-existing, setup uses your VPC and subnets. |
| Application resources | What the stack declares, for example S3 buckets, Lambda functions, ECR repositories, KMS keys, DynamoDB tables, SQS queues, CloudWatch log groups and RDS clusters. |
Machines, Auto Scaling groups, load balancers and certificates are not created by setup. Your manager creates them afterwards through the management role, so the admin's credentials don't need those permissions.
The IAM roles have fixed names, so the stack requires the CAPABILITY_NAMED_IAM capability. In the AWS console, tick the acknowledgement that CloudFormation might create IAM resources with custom names. From the command line:
aws cloudformation create-stack \
--stack-name <stack-name-from-the-portal> \
--template-url <template-url-from-the-portal> \
--capabilities CAPABILITY_NAMED_IAMThe template lists every resource it creates. Open the template URL from the portal to review it before launching.
CloudFormation parameters
The portal fills in every parameter. Which parameters appear depends on the stack. These are the ones an admin is most likely to change:
| Parameter | Values | Description |
|---|---|---|
NetworkMode | create-new, use-existing, use-default | create-new creates a VPC with private subnets and a NAT gateway. use-existing uses a VPC you already have. use-default uses the account's default VPC, and isn't offered when the stack needs named subnets. |
VpcCidr, AvailabilityZones | CIDR, 1 to 3 | Only used with create-new. Leave VpcCidr empty for the generated default. |
VpcId, PrivateSubnetIds, PublicSubnetIds, SecurityGroupIds | IDs | Only used with use-existing. SecurityGroupIds is optional. PublicSubnetIds can stay empty in a VPC with only private subnets, as long as no endpoint is internet-facing: the stack has no public endpoints, or EndpointAccess is private. Internet-facing endpoints need public subnets for their load balancer. |
EndpointAccess | internet, private | Who can reach the deployment's endpoints. Can't change after setup. See Networking. |
Container<Name>VolumeSizeGib | 1 to 65536 | Persistent volume size per replica, in GiB, for each container with persistent storage. Volumes can only grow: if a stack update sets a smaller value, the deployment keeps the current size. |
Container<Name>Cpu, Container<Name>Memory | Within the stack's range | CPU and memory per replica. |
Compute<Pool>Machine | EC2 instance type, or empty | Machine type for a compute pool. Empty chooses a size automatically. |
Compute<Pool>Machines, or Compute<Pool>Min and Compute<Pool>Max | Within the stack's range | A fixed number of machines, or the autoscaling range. |
DomainName, CertificateArn, DomainResource | Hostname, ACM ARN, resource ID | Optional custom domain. See Custom domains. |
<Name> and <Pool> are the resource and compute pool IDs in PascalCase, for example ContainerApiVolumeSizeGib.
To change a parameter later, update the stack with new parameter values. EndpointAccess is the exception: changing it requires a new deployment.
Terraform variables
The Terraform module has the network settings as variables: network_mode, vpc_cidr, availability_zones, vpc_id, public_subnet_ids, private_subnet_ids, security_group_ids and endpoint_access. Container sizes and compute pools are not separate variables.
CLI
The deploy CLI takes the network settings as flags (see Networking) and the compute settings from deployment.toml, which the portal generates.
Find the stack name
The portal names a new CloudFormation stack a<8 random hex characters>-<deployment name>, for example a3f9c21b0-acme-corp, shortened to 35 characters. The random part keeps the name unique: setup names resources and scopes IAM permissions with the stack name as a prefix. The portal shows the stack name and region, with a link to the stack in the AWS console. To list the stacks in that region from the command line:
aws cloudformation describe-stacks \
--region <region-from-the-portal> \
--query 'Stacks[].[StackName,StackStatus]' \
--output tableMatch the full stack name shown in the portal. Long deployment names are truncated in the stack name, so searching for the full deployment name can miss the stack.