AWS ECS Installation Guide

The purpose of this document is to provide a clear and concise guidance to customers using AWS ECS, who would like to deploy the self-hosted version of Authlete through the Ansible solution.

Prerequisites

AWS

• ECS Cluster (Fargate)
• ECR
• Load Balancer
  • Target Group
• RDS (Engine: MySQL Community)
• Cloud Map
• EFS
• CloudWatch Logs groups

Ansible Execution Environment

• Python (3.12 or later)
• Python modules: boto3, botocore, requests
• Ansible (11.5.0 or later)
• AWS CLI
• Docker
• Crane (https://github.com/google/go-containerregistry/tree/main/cmd/crane)

Installation Steps

Setup Phase: Authlete

1. Create an Organization

• Log in to the Authlete Console.
• Create an organization for your company.
• Note down the Organization ID.

2. Request Access

• Share the Organization ID and Organization Name with Authlete Support.
• Authlete will authorize registry access for your organization.

3. Generate Organization Token

• In the Authlete Console, generate a Token for your organization.
• Keep the Organization ID and Token handy for authentication.

Setup Phase: Ansible Execution Environment

Setup Ansible execution environment.

1. Install Python Requirements:

Install boto3 and botocore for AWS interactions. Use the following command:

pip3 install boto3 botocore

You will also need the Python requests module which you can install with the following command:

pip3 install requests

2. Install Ansible

To install ansible, run the following: Ansible version (>=11.5.0) is recommended.

pip3 install "ansible>=11.5.0"

3. Install Ansible Collections

Option 1: Install the latest Ansible collection: community.aws and amazon.aws dependency:

ansible-galaxy collection install --force community.aws:==9.2.0
ansible-galaxy collection install --force amazon.aws:==9.4.0

Option 2: Create and add the community.aws collection and amazon.aws dependency to a requirements.yml file:

  collections:
    - name: community.aws
      version: 9.2.0
    - name: amazon.aws
      version: 9.4.0

Then, install the requirements:

ansible-galaxy collection install -r requirements.yml

4. Setup AWS CLI Environment

Before anything, you will need to set up your AWS account. Contact your AWS administrator and have them create credentials for you.

Install AWS CLI

Use the following guide to install or update to the latest version of AWS CLI. Skip this step if your AWS CLI environment is already up to date.

AWS Configuration

If you do not have a pre-existing folder, create ~/.aws. Once done, create a ~/.aws/credentials file containing the following information :

[default]
aws_access_key_id = <ACCESS_KEY>
aws_secret_access_key = <SECRET_ACCESS_KEY>

You can find these keys in your AWS IAM account settings.

Then, create another ~/.aws/config file containing the following information :

[default]
region = <REGION>
output = json

This corresponds to the region under which you have created your ECS cluster.

Preparation and Configuration Phase

1. Pull the ansible-playbook

First, log into the artifact registry using your organization identifiers :

docker login artifacts.authlete.com -u <org_id> -p <org_token>

Then, pull the Ansible playbook from the artifact registry :

crane pull artifacts.authlete.com/authlete-platform-playbook:1.0.0 ansible-playbook.tar.gz

Finally, extract the files on your system :

tar -xzf ansible-playbook.tar.gz

Create configuration files from sample files for further editing.

cd ansible-playbook
cp -a group_vars/all.yml.sample group_vars/all.yml
cp -a group_vars/aws_ecs.yml.sample group_vars/aws_ecs.yml

You can check the group_vars/aws_ecs.yml file provided by Ansible for configuration details. This file contains all the required keys with dummy placeholder values that need to be replaced with your AWS resource identifiers.

• ecs_cluster_name
• execution_role_arn
• efs_filesystem_id
• efs_access_point_id
• efs_access_point_arn
• aws_logs_groups
• cloudmap_registry_arns

The following steps will show you how to configure the values in group_vars/aws_ecs.yml file.

2. Create AWS ECS

Once your AWS account is set up, create a Fargate ECS cluster with a name of your choosing.

Use the following aws cli command to display your ECS cluster information:

aws ecs describe-clusters --clusters <CLUSTER_NAME>

In the group_vars/aws_ecs.yml file, you can now replace the following AWS resource identifiers with your AWS ECS values:

# AWS account identifier
aws_account_id: "123455673100"

# Region in which ECS resources will be provisioned
region: us-east-2

# ECS cluster name where services will be deployed
ecs_cluster_name: <CLUSTER_NAME>

3. Create AWS ECR Repositories

Create ECR repositories. Navigate to the ECR dashboard and create the following repositories:

1. <CLUSTER_NAME>/server-db-schema
2. <CLUSTER_NAME>/server
3. <CLUSTER_NAME>/idp-db-schema
4. <CLUSTER_NAME>/idp
5. <CLUSTER_NAME>/authlete-bootstrapper
6. <CLUSTER_NAME>/console
7. <CLUSTER_NAME>/nginx
8. <CLUSTER_NAME>/alpine
9. <CLUSTER_NAME>/valkey (Optional, you can disable the valkey option in the all.yml file)

NOTE: Keep in mind that the namespace in the repository name must be the same as your <CLUSTER_NAME>.

To correctly setup the ecr_repo_url, copy/paste the URI of one of your ECR repositories, and remove the repository name at the end (the final result should end with amazonaws.com)

Use the following command to list your repositories.

aws ecr describe-repositories | grep repositoryArn

In the group_vars/aws_ecs.yml file, replace the value of repo. Make sure not to configure the container images and tags.

#### #### #### #### ####
# ECR Container Images
# Dont change the Container images or tags, unless specified by support@authlete.com or
# unless mentioned in our deployment guide
repo: 123456789.dkr.ecr.us-east-2.amazonaws.com

4. Create AWS ECS Task

From your AWS ECS cluster, go to Tasks and follow instructions to create your task role and execution.

When your task is launched, find and replace the following AWS resource identifiers with your AWS ECS values.

• The execution_role_arn and task_role_arn values can be found under the task definitions.

• The subnet_id values can be found under the tasks.

In the group_vars/aws_ecs.yml file, configure the following:

# IAM role for ECS tasks to pull images and write logs
execution_role_arn: arn:aws:iam::123455673100:role/ecsTaskExecutionRole

# IAM role for ECS tasks to access AWS services at runtime
task_role_arn: arn:aws:iam::123455673100:role/ecsTaskRole

# Security group ID attached to the ECS service for network rules
security_group_id: sg-0f8bef00

# Subnet ID (within a VPC) where ECS tasks will be launched
subnet_id: subnet-4af11000

5. Create AWS Target Groups

In the AWS EC2 dashboard, under Load Balancing, create the following target groups:

1. authlete-console-tg
2. authlete-idp-tg
3. authlete-api-tg
4. authlete-proxy-tg, Health check path=/health
5. authlete-valkey-tg

Make sure these target groups should be of type IP address and use the corresponding container port number.

Finally, in the group_vars/aws_ecs.yml file, replace the following target group ARNs with your AWS EC2 resource identifiers.

# Application Load Balancer (ALB) target groups per microservice
api_target_group_arn: arn:aws:elasticloadbalancing:us-west-1:123456789012:targetgroup/my-api-tg/00be0deb21695fcde5
idp_target_group_arn: arn:aws:elasticloadbalancing:us-west-1:123456789012:targetgroup/my-idp-tg/abcd1234ijkl5678
console_target_group_arn: arn:aws:elasticloadbalancing:us-west-1:123456789012:targetgroup/my-console-tg/abcd1234mnop5678
proxy_target_group_arn: arn:aws:elasticloadbalancing:us-west-1:123456789012:targetgroup/my-proxy-tg/abcd1234qrst5678
valkey_target_group_arn: arn:aws:elasticloadbalancing:us-west-1:123456789012:targetgroup/my-valkey-tg/abcd1234qrst5876

6. Create AWS ALB

Create the following load balancers:

1. authlete-lb
2. idp-lb
3. console-lb
4. proxy-lb

Set the following fields for each of the load balancers:

• Availability zones
• Security group
• Listener port and forwarding
• Certificate (required for HTTPS protocol only)

7. Create AWS Cloud Map

• Navigate to AWS Cloud Map and create a new namespace. This namespace must have the same name as your previously created ECS cluster.

Navigate to the newly created CloudMap namespace and create the following services:

1. console
2. idp
3. authlete-api

Replace the following AWS resource identifiers with your AWS Cloud Map values.

To list any AWS services, use the following:

aws servicediscovery list-services

In the group_vars/aws_ecs.yml file, configure the following:

# Service discovery (Cloud Map) registry ARNs for internal DNS-based discovery
api_cloudmap_registry_arn: arn:aws:servicediscovery:us-west-1:123456789012:service/srv-xxxxxxxxxxxxxxxx
idp_cloudmap_registry_arn: arn:aws:servicediscovery:us-west-1:123456789012:service/srv-yyyyyyyyyyyyyyyy
console_cloudmap_registry_arn: arn:aws:servicediscovery:us-west-1:123456789012:service/srv-zzzzzzzzzzzzzzzz

To correctly set this up, copy/paste your CloudMap namespace ARN, then replace namespace/... with service/{SERVICE_ID} for each registry

8. Create AWS CloudWatch Log Group

In the AWS CloudWatch dashboard, under Logs, create a new log group with a name of your choosing.

In the group_vars/aws_ecs.yml file:

# CloudWatch Logs group name for ECS container logs
aws_logs_groups: /ecs/authlete

9. Create AWS RDS Database

Create an AWS RDS Database with the following configurations:

• Engine type: MySQL
• Engine version: 8.0.X

Before starting the installation, ensure that both of the following databases are created.

create database authlete;
create database idp;

10. Create AWS EFS

• Create an Amazon EFS and replace the following AWS resource identifiers with your Amazon EFS Filesystem values.

In the group_vars/aws_ecs.yml file, configure the following EFS values:

# Amazon EFS (Elastic File System) configuration for persistent shared storage
efs_filesystem_id: fs-02e6123720a9550b5
efs_access_point_id: fsap-02e6123720a9550b5
efs_access_point_arn: arn:aws:elasticfilesystem:us-west-1:123456789012:file-system/fs-02e6123720a9550b5
efs_filesystem_id_valkey: fs-0ba6a21018f65eaas
efs_access_point_id_valkey: fsap-007fd448ce3basass
efs_access_point_arn_valkey: arn:aws:elasticfilesystem:us-west-1:123456789012:file-system/fs-0ba6a21018f65eaas
#### #### #### #### ####

11. Container Images

The Ansible playbook automates the transfer of Authlete-provided container images to a customer’s own container registry. This avoids direct runtime dependency on Authlete’s registry, and ensures reproducible deployments.

• Make sure not to modify the following container images and tags in the group_vars/aws_ecs.yml file.

images:
  api:
    name: server
    tag: "3.0.11"
  server_db_schema:
    name: server-db-schema
    tag: "v3.0.11"
  idp:
    name: idp
    tag: "1.0.5"
  idp_db_schema:
    name: idp-db-schema
    tag: "v1.0.5"
  console:
    name: console
    tag: "1.0.5"
  bootstrapper:
    name: authlete-bootstrapper
    tag: "1.0.0"
  proxy:
    name: nginx
    tag: "1.26.3"
  valkey:
    name: valkey
    tag: "8.0.1"
  proxy_sidecar:
    name: alpine
    tag: "3.18"
#### #### #### #### ####

12. Authlete URLs

Configure Authlete URLs:

Make sure you follow the required format to avoid errors:

In the group_vars/aws_ecs.yml file, configure the following:

1. authlete_api_url
2. authlete_idp_base_url
3. authlete_idp_console_url

#### #### #### #### ####
#### URLs to be used (without http:// or https://)
authlete_api_url: "<api_url>"               # eg: authlete-api.example.com
authlete_idp_base_url: "<idp_url>"          # eg: authlete-idp.example.com
authlete_idp_console_url: "<console_url>"   # eg: authlete-console.example.com
url_scheme: "https"                         # either http or https
#### #### #### #### ####

13. Authlete Email and Password

Configure your admin_user_email and admin_user_password

• Your first Authlete user will be instantiated with these values.

In the group_vars/aws_ecs.yml file, configure the following:

# It create's necessary configuartions for Authlete to start

admin_user_email: "<admin_email>"      # eg: admin@example.com, Admin email used by the bootstrapper to create or log into the Authlete system
admin_user_password: <admin_password>  # Corresponding password for the admin user (used during initial setup only)
boot_task_def: bootstrapper-task       # ECS task definition name for the bootstrapper container/task

14. Configure Authlete Organization ID and Token

Log into the Authlete console and find the Authlete Organization Id and Organization Token for the following step.

Configure your Authlete Organization Id and Organization Token in the group_vars/all.yml file:

authlete_org_id: "<org_id>"
authlete_org_token: "<org_token>"

Validation Phase

Now that you have created and configured all the required AWS resources, you will need to update values in the Ansible group_vars so that your installation correctly points towards them.

Run the environment validation playbook to verify that all required AWS infrastructure is in place. However, you may choose to skip this step as it will be automatically executed during the installation process.

Run the following ansible playbook command:

ansible-playbook playbooks/site.yml --tags prereq --skip-tags=install,uninstall,upgrade,rollingupgrade

If the output displays failed=0, it means this step is completed.

Deployment Phase

1. Install the Authlete Stack

• To install the Full Authlete Stack, run the following ansible commands:

ansible-playbook playbooks/site.yml --tags aws,install --skip-tags upgrade,uninstall,rollingupgrade
ansible-playbook playbooks/site.yml --tags aws,upgrade --skip-tags install,uninstall,rollingupgrade

Uninstall Phase

1. Uninstall the Stack

• To uninstall the full Authlete Stack:

ansible-playbook playbooks/site.yml --tags aws,uninstall --skip-tags install,upgrade,rollingupgrade

Manage Individual Components

1. Authlete API

• To install:

ansible-playbook playbooks/site.yml --tags api,install_api --skip-tags uninstall,upgrade,rollingupgrade

• To uninstall:

ansible-playbook playbooks/site.yml --tags api,uninstall_api --skip-tags install,upgrade,rollingupgrade

• Rolling upgrade:

ansible-playbook playbooks/site.yml --tags api,rollingupgrade --skip-tags install,upgrade,uninstall

2. Authlete IDP

• To install:

ansible-playbook playbooks/site.yml --tags idp,install_idp --skip-tags uninstall,rollingupgrade

• To uninstall:

ansible-playbook playbooks/site.yml --tags idp,uninstall_idp --skip-tags upgrade,rollingupgrade

Rollling upgrade:

ansible-playbook playbooks/site.yml --tags idp,rollingupgrade --skip-tags upgrade,uninstall

3. Authlete Console

• To install:

ansible-playbook playbooks/site.yml --tags console,install_console --skip-tags uninstall,rollingupgrade

• To uninstall:

ansible-playbook playbooks/site.yml --tags console,uninstall_console --skip-tags upgrade,rollingupgrade

• Rolling upgrade:

ansible-playbook playbooks/site.yml --tags console,rollingupgrade --skip-tags upgrade,uninstall