Install on Amazon ECS

On Amazon ECS, Remote Operator runs as one Fargate service in a cluster and network you already have. Setup generates a CloudFormation template and a deploy command for one installation. The command stores the registration token in your AWS Secrets Manager and deploys the stack. The operator presents that token to Alien to register, then uses its connection key to authenticate. The locally generated encryption key stays in your AWS account, and the CloudFormation template contains no secret values.

Before you start

You need:

The AWS CLI, jq, and OpenSSL, with credentials for the target AWS account.
An existing ECS cluster that can run Fargate tasks.
One or more subnets for the task. If the stack creates EFS storage, choose at most one subnet per Availability Zone. Private subnets need outbound HTTPS to Alien's public management endpoint through NAT or another approved public egress path. VPC endpoints can provide access to AWS services, but not to that Alien endpoint.
One or more security groups for the task that allow outbound HTTPS and NFS.

By default the stack creates encrypted EFS storage for the operator identity. To use existing storage instead, you need an EFS filesystem and an access point that uses POSIX UID and GID 1000, with a mount target in each selected Availability Zone. The access-point root must exist and be writable by UID/GID 1000, or its creation settings must create it with those permissions. Each existing mount target must have a security group that allows inbound TCP port 2049 from a security group assigned to the task. The stack adds this rule only for EFS storage it creates.

Generate the template

On the project overview, select Set up Remote operator, then Set up manually instead.
Under Installation platform, select Amazon ECS Fargate.
In Choose operations, select the plugins the operator can run and select Continue. The default for ECS is the AWS group: S3, EC2, VPC, CloudWatch, SQS, RDS, and Load balancers. The selected operations determine the operation-specific IAM grants. The operator also needs EFS mount and write access for its identity storage.
In Review the exact ECS target and CloudFormation, fill in the target:

Field	Value
Environment name	A name for this installation, such as `customer-staging`.
AWS account ID	The 12-digit account that owns the cluster.
AWS Region	The cluster's Region, such as `us-east-1`.
ECS cluster ARN	The cluster ARN. Its account and Region must match the two fields above.
Subnet IDs	Comma or newline separated. If the stack creates EFS, use at most one subnet per Availability Zone and keep the same subnets, in the same order, on every later update.
Security group IDs	Comma or newline separated.
Existing EFS filesystem ID and Existing EFS access point ID	Optional. Enter both or neither.
Assign public IP	Disabled for private subnets. Enabled only for reviewed public subnets.
Exact S3 bucket ARN ceilings and Exact SQS queue ARN ceilings	When a selected operation requires them, the bucket and queue ARNs its permissions are limited to.

Select Generate CloudFormation. When the operator image is ready, the page shows the stack name and the immutable image.
Select Download JSON. The file is named after the stack, remote-operator-<environment>-<project-id>.json.
Review the template, then select the checkbox that confirms the account, Region, cluster, subnets, security groups, EFS storage, image, and IAM permissions.

The page URL keeps the non-secret target values, so you can come back to this installation later.

What the stack creates

Resource	Notes
ECS service and Fargate task definition	0.25 vCPU and 512 MiB. The task definition family is `<stack>-remote-operator`.
Execution role	Reads the registration secret and writes to the log group.
Task role	Holds the IAM permissions of the selected operations. An update removes grants for operations you disable. For existing EFS storage, its policy also allows mount and write access through the selected access point; for stack-created EFS, the filesystem policy grants the task role that access.
CloudWatch Logs log group	30-day retention, for startup and recovery diagnostics.
EFS filesystem, access point, and mount targets	Only when you leave the EFS fields empty. The filesystem is encrypted and its policy lets only the task role mount it. The stack also adds an inbound NFS rule to the first security group, from that same group.

The EFS filesystem and access point are kept when the stack is deleted or replaces them, so the operator identity survives. Only a failed first create deletes them. The ECS cluster, subnets, and security groups are never owned by the stack.

The stack outputs include StackId, ServiceArn, TaskDefinitionArn, LogGroupName, TaskRoleArn, AccountId, Region, ClusterArn, EfsFileSystemId, EfsAccessPointId, RegistrationSecretArn, EnvironmentName, OperatorImage, and OperatorImageDigest. The lifecycle commands on the setup page read these outputs to check that they act on the right stack.

Register and deploy

In Register, deploy and verify, select Create one-time registration.
Copy the registration token that the page shows. It is shown once and expires at the time on the page.
Copy Bootstrap and deploy and run it in Bash or Zsh from the directory that contains the downloaded JSON file.
At the prompt Paste the unexpired Alien registration token:, paste the token. The input is not echoed.

The command:

Checks that your AWS credentials belong to the account you entered.
Reads the existing stack, if there is one, so an update keeps the same EFS storage and subnets.
Stores the token and an encryption key as JSON in the Secrets Manager secret <stack>-registration. On the first run it generates the encryption key. On later runs it keeps the existing key, so the operator can still read its identity.
Runs aws cloudformation deploy with --capabilities CAPABILITY_IAM, passes the exact cluster, subnets, security groups, EFS IDs, and secret version as parameters, and tags the stack with AlienRemoteOperator=true, AlienProjectId, and AlienEnvironment.

The secret must use the default aws/secretsmanager KMS key. The command stops if an existing secret uses a customer-managed key.

If the token expires before the first registration, open the same installation in setup and select Generate replacement registration token. Run the deploy command again with the new token.

Verify

When the operator registers, the setup step changes to Manage the ECS installation. Open the installation under Deployments and select Run read-only CloudWatch diagnostic. It lists a bounded page of CloudWatch log-group metadata without reading log contents. You can run the same operation from the CLI:

alien operations invoke --deployment <deployment-id> --operation cloudwatch/log-groups --params '{"region":"<region>","maxResults":20}'

This needs the CloudWatch operations enabled for the project.

Apply an update

To change operations or the operator image, generate the template again on the setup page, review it, and run the command that is now labeled Apply reviewed update. Save the new JSON over the old file first.

Before running it, open the existing <stack>-registration secret in AWS Secrets Manager and copy its current syncToken value. At the command's hidden token prompt, paste that value, even though the prompt calls it a registration token. Do not leave the prompt empty or use a token copied earlier from setup; it may have changed through rotation. The command compares your input with the stored value and, when they match, keeps the same secret version and encryption key.

The operator keeps its identity and current credential through the update.

The account, Region, cluster, and stack must stay the same. Setup refuses update commands for a target that differs from the one recorded for the installation.

After the stack update completes and the latest heartbeat reports the new image, select the checkbox that confirms the template is the deployed revision. Alien then keeps the previous image as the rollback target. See Upgrade and roll back.