Prerequisites

  • An AWS account with necessary permissions.
  • Terraform installed and configured.
  • Access to DNS settings for domain configuration.

Deployment Process

The following guide should be used in conjunction with our simple deployment example.

If you’re deploying into an existing VPC or want to limit network ingress to your Common Fate deployment, refer to our existing VPC example.

If you would like to customise the components in the deployment, refer to our full example.

1. Domain Configuration

In order for your deployment to be accessible through HTTPS you need to configure DNS and register HTTPS certificates with AWS Certificate Manager.

Steps:

  • ACM Certificate (Target Region): Create an ACM certificate in the target deployment region. Include the following domains:

    • Application domain e.g (commonfate.example.com)

After creating the ACM certificate you will need to configure the DNS verification records in your DNS provider.

Once ACM shows that your domains are verified, you can continue with the deployment.

2. Licence Key

Common Fate requires a licence key to activate and run the Control Plane. The Terraform modules are configured to read secrets values from SSM Parameter Store.

You will need to create a new SecretString in SSM Parameter Store and then use the ARN when deploying the Terraform.

You can use the AWS CLI to create a secret in the region you are deploying to. We recommend naming these "/<namespace>/<stage>/<secret name>".

aws ssm put-parameter \
    --name "/common-fate/prod/licence-key" \
    --value "mySecretValue" \
    --type "SecureString" \
    --region "ap-southeast-2"

Retrieve the ARN:

aws ssm get-parameter \
    --name "/common-fate/prod/licence-key" --query Parameter.ARN

3. Initial Deployment

Create a new folder called common-fate-deployment. In the folder, create a main.tf file as follows:

module "common-fate-deployment" {
  source                = "common-fate/common-fate-deployment/aws"
  version               = "1.22.0"
  aws_region            = "<your target region>"

  licence_key_ps_arn = <for licence key parameter ARN>

  app_certificate_arn   = <your domain certificate ARN>

  // Replace this with your actual domain
  app_url            = "https://commonfate.example.com"
}

output "first_time_setup_config" {
  description = "Common Fate Setup Config"
  value       = module.common-fate-deployment.first_time_setup_config
}

output "control_plane_task_role_arn" {
  value = module.common-fate-deployment.control_plane_task_role_arn
}

output "outputs" {
  description = "outputs"
  value       = module.common-fate-deployment.outputs
}

output "terraform_client_secret" {
  description = "terraform client secret"
  value       = module.common-fate-deployment.terraform_client_secret

  sensitive = true
}

Run the first deployment

terraform apply

You should see an output like the below from Terraform. You will need to reference this in the next steps.

Outputs:

first_time_setup_config = {
  "dns_cname_record_for_app_domain": "your-app-domain.your-aws-region.elb.amazonaws.com",
  "dns_cname_record_for_auth_domain": "your-cloudfront-domain.net",
  "saml_sso_acs_url": "https://your-auth-domain/saml2/idpresponse",
  "saml_sso_entity_id": "urn:amazon:cognito:sp:us-west-2_yourEntityID"
}

By default, the module deploys a VPC with NAT Gateways across three Availability Zones (AZs). If you’d like to reduce the hosting cost of your Common Fate deployment, you can opt to use a single NAT Gateway:

module "common-fate-deployment" {
  source                = "common-fate/common-fate-deployment/aws"

+ single_nat_gateway     = true
+ one_nat_gateway_per_az = false
}

4. Final DNS Configuration

Now that your Application Load Balancer is deployed, you can configure your DNS records.

For your App domain create a CNAME record pointing to the dns_cname_record_for_app_domain from the first_time_setup_config deployment outputs. This will route traffic through to the Common Fate services.

After deploying you can test everything is working by opening your App domain in a browser and you should be directed to the login screen.

5. Set up SSO authentication

Your users will sign in to Common Fate using SAML SSO. Follow a guide below for your identity provider:

Set up SSO with Microsoft Entra

Set up SSO using Microsoft Entra.

Set up SSO with AWS IAM Identity Center

Set up SSO using AWS IAM Identity Center.

Set up SSO with Okta

Set up SSO using Okta.

6. Set up integrations

Set up notifications with Slack

Notify and approve access inside of Slack.

Integrate with PagerDuty

Approve access contextually based on PagerDuty on-call status.