Deploying Common Fate

​

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.

​

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"

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"
}

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 load_balancer_domain from the 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:

​

6. Set up integrations