Skip to content

Commit 2ff3063

Browse files
edwardsbedwardsb
committed
📝 (addons/migrations): Update documentation to reflect new features and usage
✨ (addons/migrations): Add support for assuming IAM role for ECS permissions in migration script
1 parent f3d1a07 commit 2ff3063

File tree

5 files changed

+146
-15
lines changed

5 files changed

+146
-15
lines changed

‎addons/migrations/.header.md

Lines changed: 57 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,57 @@
1-
# Migrations addon
2-
This addon enables automatic migrations for Fleet.
3-
Due to limitations in the AWS provider for Terraform, only Linux platforms are supported.
4-
This module uses the local-exec provisioner to call aws-cli to complete migrations.
5-
Due to this, the following commands must be available to the shell:
6-
- aws
1+
# Terraform AWS Fleet Database Migration Module
2+
3+
This Terraform module provides a mechanism to trigger database migrations for a Fleet application running on AWS ECS. It is designed to integrate into an infrastructure deployment pipeline, ensuring that database schema changes are applied gracefully, typically during application upgrades.
4+
5+
The core functionality relies on a `null_resource` which executes a local script (`migrate.sh`) when specific triggers change (primarily the `task_definition_revision`). This script is expected to handle the actual migration process, which usually involves:
6+
7+
1. Scaling down the main Fleet application ECS service.
8+
2. Running a one-off ECS task using the *new* task definition revision (which contains the updated application code capable of performing the migration). This task executes the necessary Fleet migration command (e.g., `fleetctl prepare db`).
9+
3. Scaling the main Fleet application ECS service back up once the migration is complete.
10+
11+
## Usage
12+
13+
```hcl
14+
module "fleet_migration" {
15+
source = "./path/to/this/module" # Or Git source
16+
17+
ecs_cluster = "my-fleet-cluster"
18+
ecs_service = "my-fleet-service"
19+
task_definition = "arn:aws:ecs:us-west-2:123456789012:task-definition/my-fleet-app" # Base ARN without revision
20+
task_definition_revision = 5 # The *new* revision to migrate *to*
21+
min_capacity = 0 # Scale down to this during migration
22+
desired_count = 2 # Scale back up to this after migration
23+
subnets = ["subnet-xxxxxxxxxxxxxxxxx", "subnet-yyyyyyyyyyyyyyyyy"]
24+
security_groups = ["sg-xxxxxxxxxxxxxxxxx"]
25+
26+
# Optional: Specify if a separate vulnerability processing service needs coordination
27+
# vuln_service = "my-fleet-vuln-service"
28+
29+
# Optional: Provide an IAM Role ARN for the local-exec script to assume
30+
# assume_role_arn = "arn:aws:iam::123456789012:role/MyMigrationRole"
31+
# assume_role_session_name = "TerraformFleetMigration"
32+
33+
# Ensure this module depends on the resource that creates/updates the task definition revision
34+
# For example:
35+
# depends_on = [aws_ecs_task_definition.fleet_app]
36+
}
37+
```
38+
39+
## Workflow
40+
41+
1. When `var.task_definition_revision` changes, Terraform triggers the `null_resource`.
42+
2. The `local-exec` provisioner executes the `migrate.sh` script located within the module's directory.
43+
3. It passes essential AWS and ECS details (region, cluster, service, task definition, revision, network configuration, scaling parameters, optional role ARN) as command-line arguments or environment variables to the script.
44+
4. The `migrate.sh` script (which you must provide and maintain) performs the migration steps against the Fleet database, using the provided parameters to interact with AWS ECS.
45+
46+
## Prerequisites
47+
48+
* **`bash` shell:** Must be available in the environment where Terraform is executed.
49+
* **AWS CLI:** Must be installed and configured with credentials in the environment where Terraform is executed. The credentials need permissions to perform ECS actions (DescribeServices, UpdateService, RunTask, DescribeTasks) and potentially STS AssumeRole if `assume_role_arn` is provided.
50+
* **`migrate.sh` script:** A script named `migrate.sh` *must* exist within this module's directory (`path.module`). This script contains the actual logic for scaling services and running the migration task. **This module only triggers the script; it does not contain the migration logic itself.**
51+
* **Existing Resources:** The specified ECS Cluster, Service, Task Definition (base ARN), Subnets, and Security Groups must exist.
52+
53+
## Important Considerations
54+
55+
* **`local-exec`:** This provisioner runs commands on the machine executing Terraform. Ensure this machine has the necessary tools (bash, AWS CLI) and network access/credentials to interact with your AWS environment. This might require specific configuration in CI/CD pipelines.
56+
* **IAM Permissions:** The credentials used by `local-exec` (either default AWS credentials or the assumed role specified by `assume_role_arn`) require sufficient IAM permissions to manage the specified ECS services and tasks.
57+
* **State:** The `null_resource` uses the `task_definition_revision` in its `triggers` map. This ensures that Terraform re-runs the provisioner if (and only if) the revision number changes between applies.

‎addons/migrations/README.md

Lines changed: 62 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,60 @@
1-
# Migrations addon
2-
This addon enables automatic migrations for Fleet.
3-
Due to limitations in the AWS provider for Terraform, only Linux platforms are supported.
4-
This module uses the local-exec provisioner to call aws-cli to complete migrations.
5-
Due to this, the following commands must be available to the shell:
6-
- aws
1+
# Terraform AWS Fleet Database Migration Module
2+
3+
This Terraform module provides a mechanism to trigger database migrations for a Fleet application running on AWS ECS. It is designed to integrate into an infrastructure deployment pipeline, ensuring that database schema changes are applied gracefully, typically during application upgrades.
4+
5+
The core functionality relies on a `null_resource` which executes a local script (`migrate.sh`) when specific triggers change (primarily the `task_definition_revision`). This script is expected to handle the actual migration process, which usually involves:
6+
7+
1. Scaling down the main Fleet application ECS service.
8+
2. Running a one-off ECS task using the *new* task definition revision (which contains the updated application code capable of performing the migration). This task executes the necessary Fleet migration command (e.g., `fleetctl prepare db`).
9+
3. Scaling the main Fleet application ECS service back up once the migration is complete.
10+
11+
## Usage
12+
13+
```hcl
14+
module "fleet_migration" {
15+
source = "./path/to/this/module" # Or Git source
16+
17+
ecs_cluster = "my-fleet-cluster"
18+
ecs_service = "my-fleet-service"
19+
task_definition = "arn:aws:ecs:us-west-2:123456789012:task-definition/my-fleet-app" # Base ARN without revision
20+
task_definition_revision = 5 # The *new* revision to migrate *to*
21+
min_capacity = 0 # Scale down to this during migration
22+
desired_count = 2 # Scale back up to this after migration
23+
subnets = ["subnet-xxxxxxxxxxxxxxxxx", "subnet-yyyyyyyyyyyyyyyyy"]
24+
security_groups = ["sg-xxxxxxxxxxxxxxxxx"]
25+
26+
# Optional: Specify if a separate vulnerability processing service needs coordination
27+
# vuln_service = "my-fleet-vuln-service"
28+
29+
# Optional: Provide an IAM Role ARN for the local-exec script to assume
30+
# assume_role_arn = "arn:aws:iam::123456789012:role/MyMigrationRole"
31+
# assume_role_session_name = "TerraformFleetMigration"
32+
33+
# Ensure this module depends on the resource that creates/updates the task definition revision
34+
# For example:
35+
# depends_on = [aws_ecs_task_definition.fleet_app]
36+
}
37+
```
38+
39+
## Workflow
40+
41+
1. When `var.task_definition_revision` changes, Terraform triggers the `null_resource`.
42+
2. The `local-exec` provisioner executes the `migrate.sh` script located within the module's directory.
43+
3. It passes essential AWS and ECS details (region, cluster, service, task definition, revision, network configuration, scaling parameters, optional role ARN) as command-line arguments or environment variables to the script.
44+
4. The `migrate.sh` script (which you must provide and maintain) performs the migration steps against the Fleet database, using the provided parameters to interact with AWS ECS.
45+
46+
## Prerequisites
47+
48+
* **`bash` shell:** Must be available in the environment where Terraform is executed.
49+
* **AWS CLI:** Must be installed and configured with credentials in the environment where Terraform is executed. The credentials need permissions to perform ECS actions (DescribeServices, UpdateService, RunTask, DescribeTasks) and potentially STS AssumeRole if `assume_role_arn` is provided.
50+
* **`migrate.sh` script:** A script named `migrate.sh` *must* exist within this module's directory (`path.module`). This script contains the actual logic for scaling services and running the migration task. **This module only triggers the script; it does not contain the migration logic itself.**
51+
* **Existing Resources:** The specified ECS Cluster, Service, Task Definition (base ARN), Subnets, and Security Groups must exist.
52+
53+
## Important Considerations
54+
55+
* **`local-exec`:** This provisioner runs commands on the machine executing Terraform. Ensure this machine has the necessary tools (bash, AWS CLI) and network access/credentials to interact with your AWS environment. This might require specific configuration in CI/CD pipelines.
56+
* **IAM Permissions:** The credentials used by `local-exec` (either default AWS credentials or the assumed role specified by `assume_role_arn`) require sufficient IAM permissions to manage the specified ECS services and tasks.
57+
* **State:** The `null_resource` uses the `task_definition_revision` in its `triggers` map. This ensures that Terraform re-runs the provisioner if (and only if) the revision number changes between applies.
758

859
## Requirements
960

@@ -13,8 +64,8 @@ No requirements.
1364

1465
| Name | Version |
1566
|------|---------|
16-
| <a name="provider_aws"></a> [aws](#provider\_aws) | 5.31.0 |
17-
| <a name="provider_null"></a> [null](#provider\_null) | 3.2.2 |
67+
| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
68+
| <a name="provider_null"></a> [null](#provider\_null) | n/a |
1869

1970
## Modules
2071

@@ -31,6 +82,8 @@ No modules.
3182

3283
| Name | Description | Type | Default | Required |
3384
|------|-------------|------|---------|:--------:|
85+
| <a name="input_assume_role_arn"></a> [assume\_role\_arn](#input\_assume\_role\_arn) | ARN of the IAM role to assume for ECS permissions | `string` | `""` | no |
86+
| <a name="input_assume_role_session_name"></a> [assume\_role\_session\_name](#input\_assume\_role\_session\_name) | Session name to use when assuming the IAM role | `string` | `""` | no |
3487
| <a name="input_desired_count"></a> [desired\_count](#input\_desired\_count) | n/a | `number` | n/a | yes |
3588
| <a name="input_ecs_cluster"></a> [ecs\_cluster](#input\_ecs\_cluster) | n/a | `string` | n/a | yes |
3689
| <a name="input_ecs_service"></a> [ecs\_service](#input\_ecs\_service) | n/a | `string` | n/a | yes |
@@ -39,6 +92,7 @@ No modules.
3992
| <a name="input_subnets"></a> [subnets](#input\_subnets) | n/a | `list(string)` | n/a | yes |
4093
| <a name="input_task_definition"></a> [task\_definition](#input\_task\_definition) | n/a | `string` | n/a | yes |
4194
| <a name="input_task_definition_revision"></a> [task\_definition\_revision](#input\_task\_definition\_revision) | n/a | `number` | n/a | yes |
95+
| <a name="input_vuln_service"></a> [vuln\_service](#input\_vuln\_service) | n/a | `string` | `""` | no |
4296

4397
## Outputs
4498

‎addons/migrations/main.tf

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,6 @@ resource "null_resource" "main" {
55
task_definition_revision = var.task_definition_revision
66
}
77
provisioner "local-exec" {
8-
command = "/bin/bash ${path.module}/migrate.sh REGION=${data.aws_region.current.name} VULN_SERVICE=${var.vuln_service} ECS_CLUSTER=${var.ecs_cluster} TASK_DEFINITION=${var.task_definition} TASK_DEFINITION_REVISION=${var.task_definition_revision} SUBNETS=${jsonencode(var.subnets)} SECURITY_GROUPS=${jsonencode(var.security_groups)} ECS_SERVICE=${var.ecs_service} MIN_CAPACITY=${var.min_capacity} DESIRED_COUNT=${var.desired_count}"
8+
command = "/bin/bash ${path.module}/migrate.sh REGION=${data.aws_region.current.name} VULN_SERVICE=${var.vuln_service} ECS_CLUSTER=${var.ecs_cluster} TASK_DEFINITION=${var.task_definition} TASK_DEFINITION_REVISION=${var.task_definition_revision} SUBNETS=${jsonencode(var.subnets)} SECURITY_GROUPS=${jsonencode(var.security_groups)} ECS_SERVICE=${var.ecs_service} MIN_CAPACITY=${var.min_capacity} DESIRED_COUNT=${var.desired_count} ASSUME_ROLE_ARN=${var.assume_role_arn} ASSUME_ROLE_SESSION_NAME=${var.assume_role_session_name}"
99
}
1010
}

‎addons/migrations/migrate.sh

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,21 @@ do
3939
export "$KEY"="$VALUE"
4040
done
4141

42+
# If an IAM role ARN is provided, assume it and export AWS temporary credentials
43+
if [ -n "${ASSUME_ROLE_ARN:-}" ]; then
44+
SESSION_NAME="${ASSUME_ROLE_SESSION_NAME:-migrate-$(date +%s)}"
45+
echo "Assuming role ${ASSUME_ROLE_ARN} with session name ${SESSION_NAME}" >&2
46+
# Retrieve temporary credentials via AWS STS
47+
read AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN <<< "$(
48+
aws sts assume-role \
49+
--role-arn "${ASSUME_ROLE_ARN}" \
50+
--role-session-name "${SESSION_NAME}" \
51+
--query 'Credentials.[AccessKeyId,SecretAccessKey,SessionToken]' \
52+
--output text
53+
)"
54+
export AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN
55+
fi
56+
4257
scale_services down "${ECS_SERVICE:?}" true "${DESIRED_COUNT}"
4358

4459
if [ -n "${VULN_SERVICE}" ]; then

‎addons/migrations/variables.tf

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,4 +41,15 @@ variable "security_groups" {
4141
variable "vuln_service" {
4242
default = ""
4343
}
44+
variable "assume_role_arn" {
45+
description = "ARN of the IAM role to assume for ECS permissions"
46+
type = string
47+
default = ""
48+
}
49+
50+
variable "assume_role_session_name" {
51+
description = "Session name to use when assuming the IAM role"
52+
type = string
53+
default = ""
54+
}
4455

0 commit comments

Comments
 (0)