diff --git a/README.md b/README.md index a3b4828..a63169a 100644 --- a/README.md +++ b/README.md @@ -38,15 +38,34 @@ aws s3api get-bucket-tagging --bucket test-map-XXXXX ## Day-2: Add or Remove Accounts -1. Open `configurator.html` → **Editor** tab -2. Enter MPE ID, choose add/remove, enter account IDs -3. Click **Generate update.sh** → download and run: +Run in AWS CloudShell from the management account: ```bash -bash update.sh +# 1. View current scope +aws cloudformation describe-stack-set \ + --stack-set-name map-auto-tagger-mig \ + --region \ + --query "StackSet.Parameters[?ParameterKey=='ScopedAccountIds'].ParameterValue" \ + --output text + +# 2. Update scope (replace with full list) +aws cloudformation update-stack-set \ + --stack-set-name map-auto-tagger-mig \ + --use-previous-template \ + --parameters \ + 'ParameterKey=ScopedAccountIds,ParameterValue=["111111111111","222222222222"]' \ + ParameterKey=MpeId,UsePreviousValue=true \ + ParameterKey=AgreementStartDate,UsePreviousValue=true \ + ParameterKey=AgreementEndDate,UsePreviousValue=true \ + ParameterKey=ScopeMode,UsePreviousValue=true \ + ParameterKey=ScopedVpcIds,UsePreviousValue=true \ + ParameterKey=TagNonVpcServices,UsePreviousValue=true \ + ParameterKey=AlertEmail,UsePreviousValue=true \ + --capabilities CAPABILITY_NAMED_IAM \ + --region ``` -No redeployment needed — updates the account scope across all existing stack instances. +See [INSTRUCTIONS.md](docs/INSTRUCTIONS.md) for single-account deployments and detailed guidance. --- @@ -66,7 +85,16 @@ The S3 staging bucket is deleted only when no other MAP Auto-Tagger deployments ## Upgrading from a Previous Version -Prior versions used fixed resource names (`map-auto-tagger`). The current version uses MPE-ID-namespaced names (`map-auto-tagger-mig111`). Running `deploy.sh` without removing the old stack will deploy **both side by side**. Delete the old stack first: +The recommended upgrade path is **delete and redeploy**. Existing `map-migrated` tags on resources are preserved — MAP credits stay intact. + +```bash +# Single-account: +aws cloudformation delete-stack --stack-name map-auto-tagger-mig --region +aws cloudformation wait stack-delete-complete --stack-name map-auto-tagger-mig --region +bash deploy.sh +``` + +For pre-v19 un-namespaced stacks (`map-auto-tagger` without MPE suffix): ```bash aws cloudformation delete-stack --stack-name map-auto-tagger @@ -74,13 +102,15 @@ aws cloudformation wait stack-delete-complete --stack-name map-auto-tagger bash deploy.sh ``` +Enable backfill to catch resources created during the brief gap (~2-5 minutes). + --- ## Components | File | Description | |------|-------------| -| `configurator.html` | Self-service UI (built output). Generates `deploy.sh` for new deployments, `update.sh` for day-2 account changes (Editor tab), `upgrade.sh` for template-version upgrades (Upgrade tab), and `delete.sh` for clean removal (Delete tab). | +| `configurator.html` | Self-service UI (built output). Generates `deploy.sh` for new deployments and `delete.sh` for clean removal. Day-2 account scope changes are done via CloudShell (see INSTRUCTIONS.md). | | `src/` | Modular source files — CSS, HTML skeleton, JS modules, i18n, per-service definitions, Lambda Python | | `scripts/build.js` | Build script — assembles `configurator.html` from `src/` | | `CHANGELOG.md` | Version history | diff --git a/configurator.html b/configurator.html index ea7afc4..50fe707 100644 --- a/configurator.html +++ b/configurator.html @@ -233,6 +233,8 @@

Deploy new MAP Auto-Tagger

+ +
🗑️
diff --git a/docs/INSTRUCTIONS.md b/docs/INSTRUCTIONS.md index f639577..74499d7 100644 --- a/docs/INSTRUCTIONS.md +++ b/docs/INSTRUCTIONS.md @@ -284,11 +284,77 @@ Yes — all resources are namespaced by MPE ID. Deploy separate stacks for each --- +## Day-2: Add or Remove Accounts from Scope + +To modify which accounts are tagged, update the `ScopedAccountIds` CloudFormation parameter directly via CloudShell. No configurator UI or script download needed. + +### Step 1 — View current scope + +```bash +aws cloudformation describe-stack-set \ + --stack-set-name map-auto-tagger-mig \ + --region \ + --query "StackSet.Parameters[?ParameterKey=='ScopedAccountIds'].ParameterValue" \ + --output text +``` + +### Step 2 — Update scope (full replacement) + +Copy the current list from Step 1, add or remove account IDs, then run: + +```bash +aws cloudformation update-stack-set \ + --stack-set-name map-auto-tagger-mig \ + --use-previous-template \ + --parameters \ + 'ParameterKey=ScopedAccountIds,ParameterValue=["111111111111","222222222222","333333333333"]' \ + ParameterKey=MpeId,UsePreviousValue=true \ + ParameterKey=AgreementStartDate,UsePreviousValue=true \ + ParameterKey=AgreementEndDate,UsePreviousValue=true \ + ParameterKey=ScopeMode,UsePreviousValue=true \ + ParameterKey=ScopedVpcIds,UsePreviousValue=true \ + ParameterKey=TagNonVpcServices,UsePreviousValue=true \ + ParameterKey=AlertEmail,UsePreviousValue=true \ + --capabilities CAPABILITY_NAMED_IAM \ + --region +``` + +This propagates the SSM config change to all member accounts via the StackSet. Takes effect immediately on the next Lambda invocation in each account. + +> **Note:** The `ParameterValue` must be the **complete** list of scoped accounts — it replaces the existing value, not appends to it. Use `["ALL"]` to tag all accounts in the org. + +### Single-account deployments + +For single-account stacks, update the SSM parameter directly: + +```bash +aws ssm get-parameter --name "/auto-map-tagger/mig/config" --region --query Parameter.Value --output text +# Edit the scoped_account_ids array, then: +aws ssm put-parameter \ + --name "/auto-map-tagger/mig/config" \ + --type String --overwrite \ + --value '' +``` + +--- + ## Upgrading from a Previous Version -### Recommended: in-place upgrade via `upgrade.sh` +> **⚠️ Limitation:** The upgrade flow in the configurator UI has been disabled. Upgrading an existing deployment requires a delete-and-redeploy. See below for the recommended path. + +### Recommended: delete and redeploy + +The safest upgrade path is to delete the existing deployment and redeploy with the latest `deploy.sh`. Existing `map-migrated` tags on resources are preserved (MAP credits stay intact). + +```bash +# For StackSets — see "Removing a Deployment" section below +# For single-account stacks: +aws cloudformation delete-stack --stack-name map-auto-tagger-mig --region +aws cloudformation wait stack-delete-complete --stack-name map-auto-tagger-mig --region +bash deploy.sh +``` -For v19.x+ deployments (MPE-ID-namespaced stacks like `map-auto-tagger-mig1234567890`), open `configurator.html` → **🔄 Upgrade to the latest template version** → download and run `upgrade.sh`. The script reads the deployed SSM version, compares to target via SemVer, and applies the template update in place (scope and agreement dates preserved via `UsePreviousValue=true` on every existing parameter). No dual-Lambda window. +Enable backfill to catch resources created during the brief gap (~2-5 minutes). ### Migrating from the pre-v19 un-namespaced layout diff --git a/docs/LIMITATIONS.md b/docs/LIMITATIONS.md index f88e7eb..b9b89ec 100644 --- a/docs/LIMITATIONS.md +++ b/docs/LIMITATIONS.md @@ -138,3 +138,24 @@ Customer-visible impact: - **Downgrade is manual:** subsequently reducing `ScopedAccountIds` below the threshold does **not** automatically revert the parameter to Standard tier. If a customer wants to drop back to Standard pricing after shrinking scope, they must delete and recreate the parameter (or the stack) manually. See the AWS documentation for [SSM Parameter Store Advanced tier](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-advanced-parameters.html) for authoritative pricing and limit details. + +--- + +## In-Place Upgrade Not Supported + +In-place template upgrades (via `upgrade.sh` or `update-stack-set --template-body`) are not supported. The upgrade flow has been disabled because: + +1. **Scope blow-out risk:** New CFN parameters introduced in later template versions (e.g., `ScopedAccountIds`) default to `["ALL"]` when upgrading from an older template that didn't have those parameters. CloudFormation cannot "use previous value" for parameters that didn't previously exist, causing the scope to silently expand to all accounts. +2. **SSM config overwrite:** The `MapConfig` SSM parameter is rewritten on every stack update because its value is computed via `!Sub` from CFN parameters. Placeholder defaults in the upgrade template overwrite the customer's real configuration. + +**Recommended upgrade path:** Delete the existing deployment and redeploy with the latest `deploy.sh`. Existing `map-migrated` tags on resources are preserved — MAP credits stay intact. Enable backfill to catch resources created during the brief gap (~2-5 minutes). + +See [INSTRUCTIONS.md](INSTRUCTIONS.md) for step-by-step upgrade guidance. + +--- + +## Reconciliation Lambda Removed + +The daily reconciliation Lambda (introduced in v20.5.0) has been removed. The real-time tagger with SQS buffering (14-day retention, 5 retries) provides sufficient coverage. Reconciliation added risk of mass-tagging damage when SSM config was incorrect (e.g., after a scope blow-out) and provided minimal incremental value given the SQS retry guarantees. + +Resources that exhaust all SQS retries land in the Dead Letter Queue and trigger the SNS alert — these should be tagged manually or investigated. diff --git a/src/html/configurator.html b/src/html/configurator.html index 547c186..6ee750e 100644 --- a/src/html/configurator.html +++ b/src/html/configurator.html @@ -51,6 +51,8 @@

Deploy new MAP Auto-Tagger

+ +
🗑️