Installation guide

This guide is for the platform team installing FunctionPilot in their AWS account. The install is one CloudFormation stack (the hub). Every other account whose functions FunctionPilot should reach gets a small role stack (the spoke). With IAM Identity Center or another SAML IdP, the hub takes two steps: deploy the stack, configure the SAML application, then update the stack. For the short version, see Getting started.

#Before you start

• Region. Any Region with AWS Lambda, Amazon API Gateway (HTTP APIs), Amazon DynamoDB, Amplify Hosting, Amazon Cognito, AWS License Manager and Amazon ECS on Fargate. The templates are always loaded from the vendor's public bucket in us-east-1 (CloudFormation accepts a template URL from any Region), and all product code comes from the container image. The hub's Region doesn't limit which Regions' functions you can see.
• Account. Deploy the hub in the account that subscribed on AWS Marketplace: the licence is delivered to that account through AWS License Manager. To run the hub in another account of your organization, distribute the licence to it with a License Manager grant first.
• Permissions. You need permission to create the resources in the stack: IAM roles (some have fixed names), Lambda, ECS, EC2 security groups, Cognito, API Gateway, Amplify, DynamoDB, S3, SNS, EventBridge, KMS and CloudWatch Logs.
• Network. A VPC with at least one subnet with outbound HTTPS access, for the one-off installer task (see Networking). Nothing else runs in your VPC.
• Identity. Decide how users will sign in: IAM Identity Center, another SAML 2.0 IdP (Entra ID, Okta and others), an OIDC IdP, or Cognito-managed users. SAML IdPs other than IAM Identity Center, and OIDC, need the Team plan or above.

#1. Subscribe

1. Open FunctionPilot in AWS Marketplace and choose Continue to Subscribe. Choose the plan and the contract length (Team is the base plan; Business and Enterprise are add-ons to it) and accept the offer. AWS License Manager now holds your licence.
2. Choose Continue to Configuration, select the fulfilment option and the Region, then open the CloudFormation launch link from the usage instructions.

#2. Launch the hub stack

In the CloudFormation console, fill in the parameters (see the reference). Acknowledge "AWS CloudFormation might create IAM resources with custom names" and create the stack. Creation takes about 10 minutes.

The quick-create link, with the release version filled in:

https://console.aws.amazon.com/cloudformation/home#/stacks/quickcreate?templateURL=https://cloudcertainty-functionpilot-us-east-1.s3.us-east-1.amazonaws.com/pro/<version>/main.yaml&stackName=functionpilot

From the AWS CLI (--region is the Region you deploy to):

aws cloudformation create-stack --region <your-region> --stack-name functionpilot \
  --template-url https://cloudcertainty-functionpilot-us-east-1.s3.us-east-1.amazonaws.com/pro/<version>/main.yaml \
  --parameters file://params.json \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM

params.json lists the parameters as [{"ParameterKey": "VpcId", "ParameterValue": "vpc-..."}, ...].

#What happens during creation

The product's code (the Lambda functions and the web app) ships inside the subscription-protected container image, not as public downloads. Early in stack creation:

1. CloudFormation creates a private S3 bucket in your account (output ArtifactsBucketName; all public access blocked, encrypted, TLS only).
2. The ArtifactInstall custom resource starts one Fargate task from the product image in your InstallerSubnetIds. The task checks your AWS Marketplace licence in AWS License Manager, verifies every file of the code bundle against the SHA-256 checksums in the image, and copies it into the bucket under the release's version. It runs for about a minute at 0.25 vCPU and 512 MB, with a read-only root filesystem and a security group without inbound rules.
3. The Lambda functions and the web app are then created from that bucket.

If the installer task fails, stack creation fails and rolls back. The error message gives the task's exit code and its log stream (log group /<NamePrefix>/installer); see Troubleshooting.

#3. Connect your identity provider

Until SamlMetadataUrl is set, the portal falls back to Cognito sign-in, which has no users. Nobody can sign in at that point, so the stack is safe in that state.

#4. First sign-in

Open the PortalUrl output and sign in as BootstrapAdminEmail. The first account that signs in with that (verified) email becomes the bootstrap administrator and stays bound to it (see the admin guide).

The local connection to the hub's own account exists from the start. It uses the stack's local role, which may do what LocalAccessLevel allows, in the Regions of LocalRegions. Administrators see every function there. Other users see nothing until an administrator grants them access (admin guide).

#5. Deploy the spoke role in other accounts

spoke-role.yaml creates one role, /functionpilot/<RoleName>, that only the hub's API role (stack output SpokeTrustedPrincipal) can assume, only with your external ID, and only with a user's email as the source identity. Its template URL is the stack output SpokeTemplateUrl:

https://cloudcertainty-functionpilot-us-east-1.s3.us-east-1.amazonaws.com/pro/<version>/spoke-role.yaml

The role is the upper limit of what FunctionPilot can do in that account; grants narrow it per user or group but never widen it. The role has no permission to change code, delete functions, or touch IAM, CloudFormation, DynamoDB or S3. IAM is global, so deploy the stack once per account, in any one Region. The stack's outputs are RoleArn (enter it in the connection) and AccessLevel (choose the same level for the connection).

#A single account

cat > spoke-params.json <<'EOF'
[
  {"ParameterKey": "TrustedPrincipal", "ParameterValue": "<SpokeTrustedPrincipal output>"},
  {"ParameterKey": "ExternalId", "ParameterValue": "<a secret of at least 16 characters>"},
  {"ParameterKey": "AccessLevel", "ParameterValue": "ReadOnly"}
]
EOF
aws cloudformation create-stack --region us-east-1 --stack-name functionpilot-spoke \
  --template-url https://cloudcertainty-functionpilot-us-east-1.s3.us-east-1.amazonaws.com/pro/<version>/spoke-role.yaml \
  --parameters file://spoke-params.json --capabilities CAPABILITY_NAMED_IAM

Administration › Connections › How to connect another AWS account in the portal shows the same steps with your template URL.

#Every account of an AWS Organization (StackSets)

With service-managed StackSets, new accounts in the target OUs get the role automatically. Use one external ID for the whole StackSet, and enter that same external ID for every connection you create for those accounts.

# From the management account or a delegated StackSets administrator.
aws cloudformation create-stack-set --region us-east-1 --stack-set-name functionpilot-spoke \
  --template-url https://cloudcertainty-functionpilot-us-east-1.s3.us-east-1.amazonaws.com/pro/<version>/spoke-role.yaml \
  --parameters file://spoke-params.json \
  --capabilities CAPABILITY_NAMED_IAM \
  --permission-model SERVICE_MANAGED \
  --auto-deployment Enabled=true,RetainStacksOnAccountRemoval=false

# One Region only: the role is global.
aws cloudformation create-stack-instances --region us-east-1 --stack-set-name functionpilot-spoke \
  --deployment-targets OrganizationalUnitIds=ou-abcd-11111111 --regions us-east-1

Service-managed StackSets don't deploy to the management account; use a normal stack there if FunctionPilot should reach it. To change AccessLevel later, update the StackSet, then the access level of the connections.

#Add the connection

In Administration › Connections › Add connection, enter an id (used in links, it can't be changed later), a name, the account ID, the access level, the spoke stack's RoleArn, the external ID and the Regions to show. Choose Test: FunctionPilot assumes the role and lists the functions in each Region. See Connections.

#Parameter reference

The IdentityCenterStartUrl, IdentityCenterRegion and PersonalAccessKeys parameters set the first values of the personal access settings; administrators can change them later in Administration › Settings.

#Networking

Only the installer task runs in your VPC, for about a minute at install and at each upgrade. It needs outbound HTTPS (443) to:

• Amazon ECR in us-east-1, to pull the image from the AWS Marketplace registry (cross-Region, so this needs internet egress: a NAT gateway or public subnets);
• AWS License Manager in your Region, for the licence check;
• Amazon S3 in your Region, to write the code into the artifacts bucket (a gateway endpoint works);
• CloudWatch Logs in your Region, for its log stream.

Its security group has no inbound rules and one outbound rule, TCP 443. The Lambda functions don't run in your VPC; they reach Lambda, CloudWatch and STS in your accounts over AWS's public endpoints.

#Encryption and KMS

Without KmsKeyArn, the DynamoDB tables, the log groups, the update SNS topic and the artifacts bucket use AWS owned keys and SSE-S3. The stack still creates one small customer managed KMS key with automatic rotation for personal AWS access: it encrypts the Identity Center tokens and temporary credentials people connect. Only the API role may use it, and only with an encryption context that names the user. The key is deleted with the stack (after a 7-day waiting period).

With KmsKeyArn, your key encrypts the DynamoDB tables, CloudWatch Logs, the SNS topic, the artifacts bucket and the personal access secrets, and the stack creates no key of its own. The key must be a symmetric customer managed key in the stack's Region (give its ARN, not an alias), and its key policy must:

• let the account's IAM policies grant its use (the default key policy statement for the account root does this). The stack's API role gets kms:Encrypt and kms:Decrypt for personal access only with a functionpilot:* encryption context, and the other key actions only through DynamoDB;
• allow logs.<region>.amazonaws.com to use it for the stack's log groups;
• allow sns.amazonaws.com to use it for the update topic.

The identity that creates or updates the stack also needs kms:Decrypt on the key, because Lambda reads the function code from the encrypted artifacts bucket with the deploying identity's permissions.

The key protects FunctionPilot's own data. Your functions, their environment variables and their logs keep their own encryption.

#Stack outputs

#Updating

Each release is a new template; there is no version parameter. To upgrade, update the stack with the new release's template (Update stack › Replace current template) and keep every other parameter value. See the upgrading guide.

To change a setting such as LocalAccessLevel, LocalRegions or SamlMetadataUrl, update the stack with the current template and change only that parameter.

#Deleting

1. Delete the hub stack. The DynamoDB table (<NamePrefix>-table) is retained on purpose, with its settings, grants, saved tests and audit history. Everything else is deleted: the cache table, the Cognito user pool (Cognito-only users are lost), the artifacts bucket, the log groups and the personal access key. A new stack with the same NamePrefix can't be created while the retained table exists.

   To delete the table when you no longer need it, turn off its deletion protection, then delete it.

2. Delete the spoke stacks or the StackSet in the other accounts.

3. Delete the SAML or OIDC application in your identity provider.

#Troubleshooting