​
Prerequisites

  • An AWS account with necessary permissions. We recommend creating a dedicated AWS account within your organization for Common Fate.
  • Terraform installed and configured.
  • Access to DNS settings for domain configuration.

​
Deployment Process

The following guide should be used in conjunction with our BYOC starter config.

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

​
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.

​
Initial Deployment

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

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

  licence_key = <your Common Fate licence key>

  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
}

​
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.

​
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.

​
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.

IntroductionGlossary