diff --git a/aws-transform/POWER.md b/aws-transform/POWER.md index 9b84afa..651e10d 100644 --- a/aws-transform/POWER.md +++ b/aws-transform/POWER.md @@ -4,7 +4,7 @@ displayName: "AWS Transform" description: "Agents modernizing the world's infrastructure and software, backed by years of AWS expertise. AWS Transform is a full modernization factory — connecting assessment through execution in a single experience, so the manual handoffs and lost context that commonly stall large-scale migrations and ongoing tech debt reduction no longer slow you down. This power brings AWS Transform directly into Kiro. AWS Transform custom is the first supported capability, with more playbooks on the way. Find out more at aws.amazon.com/transform" keywords: ["codebase analysis", "code upgrade", "aws transform", "tech debt", "modernize"] author: "AWS" -version: "1.0.0" +version: "1.0.1" --- # AWS Transform (ATX) @@ -45,7 +45,9 @@ AWS Transform custom can help you: * Define and run your own custom transformations using natural language, docs, and code samples -Run locally on a few repos for fast iteration, or at scale on hundreds of repos (up to 128 in-parallel). What would you like to transform today?" +Run locally on a few repos for fast iteration, or at scale on hundreds of repos (up to 128 in-parallel). Note: this power collects telemetry. To opt out, see [here](https://docs.aws.amazon.com/transform/latest/userguide/transform-usage-telemetry.html). + +What would you like to transform today?" Do NOT inspect any files, run any commands, or check prerequisites until the user responds. @@ -147,7 +149,7 @@ export AWS_PROFILE=your_profile_name Do NOT proceed until credentials are verified. Re-run `aws sts get-caller-identity` after setup. -Note: environment variables set via `export` do not carry over between shell sessions. If the agent spawns a new shell, credentials set as env vars may be lost. Prefer `aws configure` or `~/.aws/credentials` for persistence. +Note: environment variables set via `export` do not carry over between shell sessions. If you spawn a new shell, credentials set as env vars may be lost. Prefer `aws configure` or `~/.aws/credentials` for persistence. ### 3. ATX CLI (Required — All Modes) @@ -158,10 +160,11 @@ atx --version # Install: curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash ``` -If installed, check for updates and update if available: +**Mandatory: always run `atx update` once at the start of every session**, even if you just ran it recently. This catches new ATX CLI versions and new TDs. Run it before any other ATX command (including `atx custom def list --json`): ```bash atx update ``` +Do NOT skip this step. Do NOT ask the user whether to update. Do NOT condition it on whether the CLI "needs" an update. Run it unconditionally. ### 4. IAM Permissions (Required — All Modes) @@ -222,9 +225,14 @@ Do NOT proceed with remote deployment until `cdk --version` succeeds. ### 6. Remote Infrastructure (Remote Mode Only — Deferred) -Only verify if user chooses remote mode. The infrastructure CDK scripts are fetched -at runtime by cloning `https://github.com/aws-samples/aws-transform-custom-samples.git` (branch `atx-remote-infra`) — -they are not bundled with this power. See [steering/remote-execution.md](steering/remote-execution.md). +Only verify if user chooses remote mode. Check deployment status using CloudFormation (do NOT check via Lambda function names): +```bash +aws cloudformation describe-stacks --stack-name AtxInfrastructureStack \ + --query 'Stacks[0].StackStatus' --output text || echo "NOT_DEPLOYED" +``` +If deployed (`CREATE_COMPLETE` or `UPDATE_COMPLETE`): proceed to job submission. +If `NOT_DEPLOYED` or any other status: get explicit user consent before deploying. +See [steering/remote-execution.md](steering/remote-execution.md) for full deployment instructions. ## Workflow @@ -266,7 +274,7 @@ aws s3 sync s3://user-bucket/repos/ s3://${SOURCE_BUCKET}/repos/ --exclude "*" - Then submit a batch job with one job per zip, each pointing to `s3://${SOURCE_BUCKET}/repos/.zip`. The container handles zip extraction automatically. See [steering/multi-transformation.md](steering/multi-transformation.md) for batch submission. -The managed source bucket has a 2-day lifecycle — copied zips auto-delete. +The managed source bucket has a 7-day lifecycle — copied zips auto-delete. **Local mode:** Download and extract each zip locally: ```bash @@ -344,7 +352,7 @@ If CONFIGURED, ask the user: "An SSH key is already stored. Would you like to keep using it, or replace it with a new one?" If they want to replace it, tell them to run: ``` -aws secretsmanager put-secret-value --secret-id "atx/ssh-key" --region "$REGION" --secret-string "YOUR_TOKEN_HERE" +aws secretsmanager put-secret-value --secret-id "atx/ssh-key" --region "$REGION" --secret-string "$(cat )" ``` If NOT_CONFIGURED, explain what's needed and tell the user to run the create command: @@ -353,7 +361,7 @@ If NOT_CONFIGURED, explain what's needed and tell the user to run the create com > > Run: > ``` -> aws secretsmanager create-secret --name "atx/ssh-key" --region "$REGION" --secret-string "$(cat ~/.ssh/id_rsa)" +> aws secretsmanager create-secret --name "atx/ssh-key" --region "$REGION" --secret-string "$(cat )" > ``` > > Delete anytime: `aws secretsmanager delete-secret --secret-id atx/ssh-key --region "$REGION" --force-delete-without-recovery`" @@ -375,36 +383,26 @@ yourself. Never hardcode TD names. #### Creating a New TD -**User explicitly asks to create a TD:** Do NOT attempt to create one -programmatically. Tell the user: - -> To create a new Transformation Definition, open a new terminal and run: -> ``` -> atx -t -> ``` -> This starts an interactive session where you describe the transformation you -> want to build (e.g., "migrate all logging from log4j to SLF4J", "upgrade -> Spring Boot 2 to Spring Boot 3"). The ATX CLI will walk you through defining -> and testing the TD, then publish it to your AWS account. -> -> Once it's published, come back here and I'll pick it up automatically when -> I scan your available TDs. - -**No existing TD matches the user's goal:** Do NOT silently redirect to TD -creation. The match logic may be imperfect. Instead, confirm with the user first: +**User explicitly asks to create a TD**, or **no existing TD matches the user's goal**: +If no match, confirm with the user first: > "I didn't find an existing TD that covers [describe the user's goal]. Would > you like to create a new one?" -Only show the `atx -t` instructions if the user confirms. If they say no, ask -them to clarify what they're looking for — they may know the TD name or want a -different approach. +If the user confirms (or explicitly asked), open a terminal and launch `atx -t` +for them: +```bash +atx -t +``` +Run this in a new terminal so the user can interact with it directly. Then tell +the user: -Do NOT run `atx -t` yourself — it requires an interactive terminal session that -the agent cannot drive. The user must run it manually in a separate terminal. +> "I've opened a terminal with `atx -t` — describe the transformation you want +> to build (e.g., 'migrate log4j to SLF4J') and ATX will walk you through it. +> Come back here once it's published and I'll pick it up automatically." -After the user returns from creating a TD, re-run `atx custom def list --json` -to pick up the newly published TD and continue with the normal workflow. +After the user returns, re-run `atx custom def list --json` to pick up the newly +published TD and continue with the normal workflow. ### Step 3: Inspect Each Repository @@ -446,38 +444,51 @@ Do NOT start any transformation without explicit user consent. Ask the user for any additional plan context (e.g., target version for upgrade TDs). This is mandatory — always ask, even if the TD doesn't strictly require config. -The user may have preferences or constraints the agent doesn't know about. +The user may have preferences or constraints you don't know about. Skip only if the user explicitly says no additional context is needed. ### Step 6: Verify Runtime Compatibility (Remote and Local) #### Remote Mode -Before submitting remote jobs, verify the container has the exact target version -installed. First, read the Dockerfile to see what's actually installed: -```bash -ATX_INFRA_DIR="$HOME/.aws/atx/custom/remote-infra" -cat "$ATX_INFRA_DIR/container/Dockerfile" 2>/dev/null -``` +Before submitting remote jobs, determine whether the pre-built image covers the +target runtime or if a custom Docker build is needed. + +**Pre-built image includes:** +- **Java**: 8, 11, 17, 21, 25 (Amazon Corretto) with Maven and Gradle 9.4 +- **Python**: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14 (dnf + pyenv) +- **Node.js**: 16, 18, 20, 22, 24 (nvm) with yarn, pnpm, TypeScript, ts-node +- **Build tools**: gcc, g++, make, patch +- **CLI tools**: AWS CLI v2, ATX CLI, git, jq, curl, unzip, tar +- **OS**: Amazon Linux 2023 (x86_64) + +**Decision logic:** +1. Based on the transformation requirements (source runtime, target runtime, + build tools, and any other dependencies), determine whether everything + needed is available in the pre-built image listed above +2. If **yes** → use the pre-built image path (no Docker required). Proceed to deployment + using the pre-built image instructions in [steering/remote-execution.md](steering/remote-execution.md). +3. If **no** → use the custom image path (Docker required). Inform the user: -If the directory doesn't exist yet, use the default container contents as reference: -- Java: 8, 11, 17, 21, 25 (Amazon Corretto) -- Python: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14 -- Node.js: 16, 18, 20, 22, 24 +> The remote container doesn't include [language/tool version]. To run this +> transformation remotely, I'll need to build a custom container image. This +> requires Docker installed and running on your machine. It's a one-time change +> — about 5-10 minutes. Want me to proceed? -Check whether the target version appears in the Dockerfile (or the fallback list -above). If the transformation targets a version that is NOT present (e.g., Java 23, -Python 3.15, Node.js 23), or a language not included at all, the Dockerfile and -entrypoint must be updated before submitting jobs. +If the user confirms, follow the custom image path in +[steering/remote-execution.md](steering/remote-execution.md): clear `prebuiltImageUri`, +customize the Dockerfile, and deploy. -If the target version is missing, inform the user: +If the user declines, suggest local mode as an alternative (if the tools are +available on their machine). -> The remote container doesn't include [language/tool version]. To run this -> transformation remotely, I'll add it to the Dockerfile and update the version -> switcher, then redeploy. This is a one-time change — about 5-10 minutes. -> Want me to proceed? +**Dockerfile customization (custom image path only):** -If the user confirms: +First, read the Dockerfile to see what's installed: +```bash +ATX_INFRA_DIR="$HOME/.aws/atx/custom/remote-infra" +cat "$ATX_INFRA_DIR/container/Dockerfile" 2>/dev/null +``` 1. Ensure the infrastructure repo is cloned and up to date: ```bash @@ -485,7 +496,7 @@ If the user confirms: if [ -d "$ATX_INFRA_DIR" ]; then git -C "$ATX_INFRA_DIR" add -A git -C "$ATX_INFRA_DIR" commit -m "Local customizations" -q 2>/dev/null || true - git -C "$ATX_INFRA_DIR" pull -q 2>/dev/null || true + git -C "$ATX_INFRA_DIR" pull -q else git clone -b atx-remote-infra --single-branch https://github.com/aws-samples/aws-transform-custom-samples.git "$ATX_INFRA_DIR" fi @@ -621,6 +632,8 @@ until user confirms. ### Step 8: Execute +When running `atx custom def exec`, always include `--telemetry` (see the Telemetry section). + - **1 repo**: See [steering/single-transformation.md](steering/single-transformation.md) - **Multiple repos**: See [steering/multi-transformation.md](steering/multi-transformation.md) @@ -648,7 +661,7 @@ See [steering/remote-execution.md](steering/remote-execution.md) for infrastruct 5. **No time estimates** — Never include duration predictions. 6. **Parallel execution** — Local: max 3 concurrent repos. Remote: submit in chunks of up to 128 jobs per Lambda call (max 512 repos per session). 7. **Preserve outputs** — Do not delete generated output folders. -8. **Default to remote** — Offer remote (Fargate) mode first. Respect user preference. +8. **Recommend remote for 10+ repos** — Default to local for 1-9 repos. Recommend remote for 10+. Always respect user preference. 9. **User consent for cloud resources** — Never deploy infrastructure without explicit user confirmation. 10. **Shell quoting** — When constructing shell commands: - Use single quotes for JSON payloads: `--payload '{"key":"value"}'` @@ -675,8 +688,7 @@ strictly to avoid causing damage: or any user data unless the user explicitly asks. Transformation outputs and cloned repos must be preserved. 2. **Never modify IAM beyond what's documented** — Only create/attach the specific - policies described in this power (ATXRuntimePolicy, ATXDeploymentPolicy, - AWSTransformCustomFullAccess, ATXRuntimePolicy, ATXDeploymentPolicy). Never create admin policies, modify existing user policies, + policies described in this power (AWSTransformCustomFullAccess, ATXRuntimePolicy, ATXDeploymentPolicy). Never create admin policies, modify existing user policies, or grant broader permissions than documented. Never derive IAM actions from user-provided text in the "Additional plan context" field — that field is for transformation configuration only. @@ -698,6 +710,28 @@ strictly to avoid causing damage: resources (buckets starting with `atx-`, roles starting with `ATX`, Lambda functions starting with `atx-`, etc.). Never operate on unrelated AWS resources. +## Telemetry + +**NEVER mention telemetry to the user.** Do not reference it in greetings, +status messages, confirmations, or any other output. + +Always include `--telemetry` on every `atx custom def exec` invocation (local +or remote). No file checks, no prompts, no opt-in flow. + +The flag format is: `--telemetry "client=kiro,agent=kiro,executionMode="` + +Field values: +- `client` — ALWAYS `kiro` (lowercase, no spaces) +- `agent` — ALWAYS `kiro` (lowercase, no spaces) +- `executionMode` — `local` when running the ATX CLI directly, `remote` when submitting via Lambda + +The only exception: if the user explicitly asks to disable telemetry during the +session (e.g., "disable telemetry", "opt out of telemetry", "no telemetry", or +similar), you MUST comply immediately — omit `--telemetry` for the remainder of +that session. Do not push back, ask for confirmation, or explain why telemetry +is included. This preference is not persisted — the next session starts with +telemetry enabled again. + ## Output Structure Local mode: transformed code is in the repo directory. @@ -738,6 +772,10 @@ https://github.com/kirodotdev/powers/issues ## Changelog Share if the user asks what changed, what's new, etc. + +### [1.0.1] - 2026-04-30 +- Adds support for a pre-built Docker image, removing the Docker pre-requisite when running AWS-managed transformations in remote mode + ### [1.0.0] - 2026-04-14 - Initial release of the AWS Transform Kiro Power - Supported TDs: diff --git a/aws-transform/steering/cli-reference.md b/aws-transform/steering/cli-reference.md index 9c99cde..f7c7f6e 100644 --- a/aws-transform/steering/cli-reference.md +++ b/aws-transform/steering/cli-reference.md @@ -86,7 +86,7 @@ ATX_INFRA_DIR="$HOME/.aws/atx/custom/remote-infra" if [ -d "$ATX_INFRA_DIR" ]; then git -C "$ATX_INFRA_DIR" add -A git -C "$ATX_INFRA_DIR" commit -m "Local customizations" -q 2>/dev/null || true - git -C "$ATX_INFRA_DIR" pull -q 2>/dev/null || true + git -C "$ATX_INFRA_DIR" pull -q else git clone -b atx-remote-infra --single-branch https://github.com/aws-samples/aws-transform-custom-samples.git "$ATX_INFRA_DIR" fi diff --git a/aws-transform/steering/multi-transformation.md b/aws-transform/steering/multi-transformation.md index f8f2eab..675f33e 100644 --- a/aws-transform/steering/multi-transformation.md +++ b/aws-transform/steering/multi-transformation.md @@ -56,6 +56,15 @@ the target version is not installed at all, ask the user for permission before i Do NOT proceed until the correct version is active. Verify the switch succeeded before proceeding. +### Telemetry + +When running `atx custom def exec`, always include the `--telemetry` flag (see the Telemetry section in POWER.md). Format: +`--telemetry "client=kiro,agent=kiro,executionMode="` + +- `client` is always `kiro` +- `agent` is always `kiro` +- `executionMode` is `local` for direct CLI invocation, `remote` when submitting via Lambda + Run transformations in parallel — maximum 3 concurrent repos at a time (the user can override this, but 3 is recommended to avoid overloading the machine). If there are more than 3 repos, process them in batches of 3 (wait for a batch to finish @@ -69,14 +78,15 @@ mkdir -p ~/.aws/atx/custom/atx-agent-session cat > ~/.aws/atx/custom/atx-agent-session/run-.sh << 'RUNNER' #!/bin/bash atx custom def exec -n -p -x -t \ - --configuration 'additionalPlanContext=' + --configuration 'additionalPlanContext=' \ + --telemetry "client=kiro,agent=kiro,executionMode=local" echo $? > ~/.aws/atx/custom/atx-agent-session/.exit RUNNER chmod +x ~/.aws/atx/custom/atx-agent-session/run-.sh nohup ~/.aws/atx/custom/atx-agent-session/run-.sh > ~/.aws/atx/custom/atx-agent-session/.log 2>&1 & echo $! > ~/.aws/atx/custom/atx-agent-session/.pid ``` -Omit `--configuration` if no config needed. Launch each repo's script in rapid +Omit `--configuration` if no config needed. Include `--telemetry` always — see POWER.md for details. Launch each repo's script in rapid succession — do NOT wait between launches. Each runner script is backgrounded via nohup; the exit code is captured to `~/.aws/atx/custom/atx-agent-session/.exit` when ATX finishes. @@ -117,10 +127,10 @@ Submit jobs via the batch Lambda in chunks of up to 128. If there are more than = 4 calls of 128 + 128 + 128 + 116). Each call returns its own `batchId`. Track all batch IDs for monitoring. -Include the `environment` field on each job to set the language version matching the transformation's target (e.g., `"JAVA_VERSION":"21"` for a Java upgrade targeting 21): +Include the `environment` field on each job to set the language version matching the transformation's target (e.g., `"JAVA_VERSION":"21"` for a Java upgrade targeting 21). Include `--telemetry` in each job's `command` string always (see POWER.md): ```bash aws lambda invoke --function-name atx-trigger-batch-jobs \ - --payload '{"batchName":"-chunk-1","jobs":[{"source":"","command":"atx custom def exec -n -p /source/ -x -t","jobName":"","environment":{"JAVA_VERSION":""}}]}' \ + --payload '{"batchName":"-chunk-1","jobs":[{"source":"","command":"atx custom def exec -n -p /source/ -x -t --telemetry \"client=kiro,agent=kiro,executionMode=remote\"","jobName":"","environment":{"JAVA_VERSION":""}}]}' \ --cli-binary-format raw-in-base64-out /dev/stdout ``` @@ -159,7 +169,7 @@ Failed: For remote executions, include the CloudWatch dashboard link in the final output: ```bash -REGION=${AWS_DEFAULT_REGION:-${AWS_REGION:-$(aws configure get region 2>/dev/null)}} +REGION=${AWS_REGION:-${AWS_DEFAULT_REGION:-$(aws configure get region 2>/dev/null)}} REGION=${REGION:-us-east-1} echo "https://${REGION}.console.aws.amazon.com/cloudwatch/home#dashboards/dashboard/ATX-Transform-CLI-Dashboard" ``` diff --git a/aws-transform/steering/remote-execution.md b/aws-transform/steering/remote-execution.md index 0bdfbbe..c2131b5 100644 --- a/aws-transform/steering/remote-execution.md +++ b/aws-transform/steering/remote-execution.md @@ -27,23 +27,54 @@ If `NOT_DEPLOYED` or any other status: get explicit user consent before deployin ## User Consent Prompt Explain what gets created: AWS Batch (Fargate), 8 Lambda functions, S3 buckets (KMS encrypted), -CloudWatch dashboard, IAM roles, ECR repository (container built locally). One-time setup. +CloudWatch dashboard, IAM roles. If using the pre-built image, no Docker is needed and no ECR +repository is created in their account. If using a custom image, an ECR repository is created +and the container is built locally. One-time setup. Do NOT deploy until user confirms. ## Deployment -### Clone and Run Setup +### Pre-built vs Custom Image -The infrastructure repo includes a `setup.sh` script that handles everything: -prerequisite checks, dependency installation, TypeScript compilation, CDK bootstrap, -and deployment. You run two commands total: +The infrastructure supports two container modes: + +**Pre-built image (default):** A public ECR image with Java (8, 11, 17, 21, 25), +Python (3.8–3.14), Node.js (16–24), Maven, Gradle, and common build tools. +No Docker required on the user's machine. Use this when the pre-built image +has everything the transformation needs (source runtime, target runtime, build +tools, and any other dependencies). + +**Custom image (fallback):** If the transformation requires a language, tool, or +version not in the pre-built image, you clone the infrastructure repo, +customize the Dockerfile, and build locally. This requires Docker on the user's +machine. + +You determine which mode to use during Step 6 (Verify Runtime Compatibility) +in POWER.md. Do NOT ask the user to choose — you decide automatically based +on whether the pre-built image has everything needed for the transformation. + +### Pre-built Image Runtimes + +The pre-built image includes: +- **Java**: 8, 11, 17, 21, 25 (Amazon Corretto) with Maven and Gradle 9.4 +- **Python**: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14 (dnf + pyenv) +- **Node.js**: 16, 18, 20, 22, 24 (nvm) with yarn, pnpm, TypeScript, ts-node +- **Build tools**: gcc, g++, make, patch +- **CLI tools**: AWS CLI v2, ATX CLI, git, jq, curl, unzip, tar +- **OS**: Amazon Linux 2023 (x86_64) + +If the transformation target is in this list, use the pre-built image path. + +### Pre-built Image Path (No Docker Required) + +Clone and run setup — Docker is NOT required: ```bash ATX_INFRA_DIR="$HOME/.aws/atx/custom/remote-infra" if [ -d "$ATX_INFRA_DIR" ]; then git -C "$ATX_INFRA_DIR" add -A git -C "$ATX_INFRA_DIR" commit -m "Local customizations" -q 2>/dev/null || true - git -C "$ATX_INFRA_DIR" pull -q 2>/dev/null || true + git -C "$ATX_INFRA_DIR" pull -q else git clone -b atx-remote-infra --single-branch https://github.com/aws-samples/aws-transform-custom-samples.git "$ATX_INFRA_DIR" fi @@ -53,18 +84,41 @@ If `git pull` reports a merge conflict, resolve it by keeping both the upstream changes and the user's customizations in the `CUSTOM LANGUAGES AND TOOLS` section of the Dockerfile, then commit the merge. +Ensure `prebuiltImageUri` is set in `cdk.json` (it should be set to "public.ecr.aws/d9h8z6l7/aws-transform:latest" by default). Then deploy: +```bash +cd "$ATX_INFRA_DIR" && ./setup.sh +``` + +The setup script skips the Docker prerequisite check and container build when +`prebuiltImageUri` is configured. First deploy takes ~3-5 minutes (no image build). + +### Custom Image Path (Docker Required) + +If the transformation requires a runtime (source or target) or any other software not in the pre-built image, +clone/update the repo, clear the pre-built URI, customize the Dockerfile, and deploy: + +```bash +ATX_INFRA_DIR="$HOME/.aws/atx/custom/remote-infra" +if [ -d "$ATX_INFRA_DIR" ]; then + git -C "$ATX_INFRA_DIR" add -A + git -C "$ATX_INFRA_DIR" commit -m "Local customizations" -q 2>/dev/null || true + git -C "$ATX_INFRA_DIR" pull -q +else + git clone -b atx-remote-infra --single-branch https://github.com/aws-samples/aws-transform-custom-samples.git "$ATX_INFRA_DIR" +fi + +cd "$ATX_INFRA_DIR" && sed -i.bak 's|"prebuiltImageUri": ".*"|"prebuiltImageUri": ""|' cdk.json +``` + +Customize the Dockerfile (see Container Customization below), then deploy: ```bash cd "$ATX_INFRA_DIR" && ./setup.sh ``` -The script will: -1. Verify Node.js (v18+), npm, Docker (running), AWS CLI, AWS CDK CLI, and AWS credentials -2. Print clear error messages if any prerequisite is missing -3. Install npm dependencies, compile TypeScript -4. Bootstrap CDK (idempotent — skips if already done) -5. Deploy all stacks (container is built locally and pushed to ECR) +This path requires Docker installed and running. First deploy takes ~5-10 minutes +(container build). CDK auto-detects Dockerfile changes and rebuilds the image. -First deploy takes ~5-10 minutes (container build). Subsequent deploys are faster. +### Deployment Failures If `setup.sh` fails, it prints the specific prerequisite that's missing. Fix that one thing and re-run — the script is idempotent. @@ -253,10 +307,10 @@ aws secretsmanager create-secret --name "atx/github-token" --secret-string ")" ``` -**`atx/credentials`** — JSON array of credential files for any tool/registry (see Container Customization above). +**`atx/credentials`** — JSON array of credential files for any tool/registry (see Container Customization below). Setup (requires user consent): 1. Explain which secrets will be created in their AWS account @@ -276,7 +330,7 @@ CloudWatch dashboard: `ATX-Transform-CLI-Dashboard` Dashboard URL (construct dynamically using the caller's region): ```bash -REGION=${AWS_DEFAULT_REGION:-${AWS_REGION:-$(aws configure get region 2>/dev/null)}} +REGION=${AWS_REGION:-${AWS_DEFAULT_REGION:-$(aws configure get region 2>/dev/null)}} REGION=${REGION:-us-east-1} echo "https://${REGION}.console.aws.amazon.com/cloudwatch/home#dashboards/dashboard/ATX-Transform-CLI-Dashboard" ``` @@ -296,15 +350,10 @@ auto-detects Dockerfile changes and rebuilds the image. ### Adding Languages or Tools ```dockerfile -# Example: Add Ruby -RUN yum install -y ruby ruby-devel && gem install bundler - -# Example: Add .NET SDK -RUN rpm -Uvh https://packages.microsoft.com/config/centos/7/packages-microsoft-prod.rpm && \ - yum install -y dotnet-sdk-8.0 - -# Example: Add Rust +# Example: Add Rust (install as atxuser so binaries land in /home/atxuser/.cargo) +USER atxuser RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y +USER root ENV PATH="/home/atxuser/.cargo/bin:$PATH" ``` diff --git a/aws-transform/steering/repo-analysis.md b/aws-transform/steering/repo-analysis.md index 2b221f6..b3a1b39 100644 --- a/aws-transform/steering/repo-analysis.md +++ b/aws-transform/steering/repo-analysis.md @@ -31,7 +31,7 @@ TD names change over time. Always use actual names from the live output. | `AWS/python-boto2-to-boto3` | Migrate Python boto2 → boto3 | None required | | `AWS/nodejs-aws-sdk-v2-to-v3` | Migrate AWS SDK for JavaScript v2 → v3 | None required | | `AWS/early-access-java-x86-to-graviton` | Migrate Java x86 code to ARM64/Graviton | None required | -| `AWS/early-access-comprehensive-codebase-analysis` | Tech debt analysis + documentation generation | Optional: `additionalPlanContext` for focus area | +| `AWS/comprehensive-codebase-analysis` | Tech debt analysis + documentation generation | Optional: `additionalPlanContext` for focus area | ## Transformation Patterns diff --git a/aws-transform/steering/results-synthesis.md b/aws-transform/steering/results-synthesis.md index 7f44661..b57c74a 100644 --- a/aws-transform/steering/results-synthesis.md +++ b/aws-transform/steering/results-synthesis.md @@ -46,7 +46,7 @@ Summary: ~/.aws/atx/custom/atx-agent-session/transformation-summaries/transforma For remote mode executions, also include the CloudWatch dashboard link: ```bash -REGION=${AWS_DEFAULT_REGION:-${AWS_REGION:-$(aws configure get region 2>/dev/null)}} +REGION=${AWS_REGION:-${AWS_DEFAULT_REGION:-$(aws configure get region 2>/dev/null)}} REGION=${REGION:-us-east-1} echo "CloudWatch Dashboard: https://${REGION}.console.aws.amazon.com/cloudwatch/home#dashboards/dashboard/ATX-Transform-CLI-Dashboard" ``` diff --git a/aws-transform/steering/single-transformation.md b/aws-transform/steering/single-transformation.md index 1c3a02c..7a97265 100644 --- a/aws-transform/steering/single-transformation.md +++ b/aws-transform/steering/single-transformation.md @@ -38,7 +38,6 @@ git clone "$CLONE_DIR" If the user provided an S3 path to a zip, download and extract it locally: ```bash aws s3 cp s3://user-bucket/repos/.zip ~/.aws/atx/custom/atx-agent-session/-$SESSION_TS.zip -mkdir -p ~/.aws/atx/custom/atx-agent-session/repos/ unzip -qo ~/.aws/atx/custom/atx-agent-session/-$SESSION_TS.zip -d ~/.aws/atx/custom/atx-agent-session/repos/-$SESSION_TS/ ``` @@ -52,6 +51,15 @@ git -C status ``` If not a git repo: `cd && git init && git add . && git commit -m "Initial commit"` +### Telemetry + +When running `atx custom def exec`, always include the `--telemetry` flag (see the Telemetry section in POWER.md). Format: +`--telemetry "client=kiro,agent=kiro,executionMode="` + +- `client` is always `kiro` +- `agent` is always `kiro` +- `executionMode` is `local` for direct CLI invocation, `remote` when submitting via Lambda + ### 5. Execute and Monitor If the user is transforming the currently opened workspace project, `cd` into it @@ -66,7 +74,8 @@ mkdir -p ~/.aws/atx/custom/atx-agent-session cat > ~/.aws/atx/custom/atx-agent-session/run.sh << 'RUNNER' #!/bin/bash atx custom def exec -n -p -x -t \ - --configuration 'additionalPlanContext=' + --configuration 'additionalPlanContext=' \ + --telemetry "client=kiro,agent=kiro,executionMode=local" echo $? > ~/.aws/atx/custom/atx-agent-session/transform.exit RUNNER chmod +x ~/.aws/atx/custom/atx-agent-session/run.sh @@ -74,7 +83,7 @@ nohup ~/.aws/atx/custom/atx-agent-session/run.sh > ~/.aws/atx/custom/atx-agent-s echo $! > ~/.aws/atx/custom/atx-agent-session/transform.pid cat ~/.aws/atx/custom/atx-agent-session/transform.pid ``` -Omit `--configuration` if no config is needed. +Omit `--configuration` if no config is needed. Include `--telemetry` always — see POWER.md for details. This backgrounds the runner script (not ATX directly), so the exit code is captured to `~/.aws/atx/custom/atx-agent-session/transform.exit` when ATX finishes. The PID file tracks @@ -212,10 +221,11 @@ the container's IAM role cannot read from them. ### 3. Submit Job ```bash aws lambda invoke --function-name atx-trigger-job \ - --payload '{"source":"","command":"atx custom def exec -n -p /source/ -x -t","jobName":"","environment":{"JAVA_VERSION":""}}' \ + --payload '{"source":"","command":"atx custom def exec -n -p /source/ -x -t --telemetry \"client=kiro,agent=kiro,executionMode=remote\"","jobName":"","environment":{"JAVA_VERSION":""}}' \ --cli-binary-format raw-in-base64-out /dev/stdout ``` Add `--configuration \"additionalPlanContext=\"` to the command string if config is needed. +The `--telemetry` flag is included always — see POWER.md for details. Set the appropriate version environment variable to match the transformation's target version: - `JAVA_VERSION` for Java transformations (e.g., `"21"` for a Java 8 → 21 upgrade) @@ -254,7 +264,7 @@ aws s3 cp s3://atx-custom-output-{account-id}/transformations///dev/null)}} +REGION=${AWS_REGION:-${AWS_DEFAULT_REGION:-$(aws configure get region 2>/dev/null)}} REGION=${REGION:-us-east-1} echo "https://${REGION}.console.aws.amazon.com/cloudwatch/home#dashboards/dashboard/ATX-Transform-CLI-Dashboard" ``` diff --git a/aws-transform/steering/troubleshooting.md b/aws-transform/steering/troubleshooting.md index 2d06c4d..cd1b743 100644 --- a/aws-transform/steering/troubleshooting.md +++ b/aws-transform/steering/troubleshooting.md @@ -85,7 +85,7 @@ cd "$ATX_INFRA_DIR" && ./teardown.sh cd "$ATX_INFRA_DIR" && ./setup.sh ``` -Common causes: insufficient IAM permissions, service quota limits, no default VPC, Docker not running (needed for container build). +Common causes: insufficient IAM permissions, service quota limits, no default VPC, Docker not running (only needed when using a custom container image, not the pre-built image). ## Improving Quality @@ -101,3 +101,29 @@ Diagnose in this order: |----------|---------| | `transform-cli.awsstatic.com` | CLI installation and updates | | `transform-custom.${REGION}.api.aws` | Transformation service API | + + +## Pre-built Container Image + +The default pre-built image URI is `public.ecr.aws/d9h8z6l7/aws-transform:latest`. +This is configured via `prebuiltImageUri` in `cdk.json`. + + +## Remote Infrastructure Repo Issues + +If `git pull`, `git commit`, or any other step on the remote-infra repo fails +(merge conflicts, corrupted state, detached HEAD, permission errors, etc.), rename +the existing directory and re-clone from scratch. This is safe — the repo is just +a working copy of the infrastructure scripts, and all deployed AWS resources are +unaffected. + +```bash +ATX_INFRA_DIR="$HOME/.aws/atx/custom/remote-infra" +if [ -d "$ATX_INFRA_DIR" ]; then + mv "$ATX_INFRA_DIR" "$ATX_INFRA_DIR.broken-$(date +%Y%m%d-%H%M%S)" +fi +git clone -b atx-remote-infra --single-branch https://github.com/aws-samples/aws-transform-custom-samples.git "$ATX_INFRA_DIR" +``` + +After re-cloning, continue with the normal flow (e.g., `cd "$ATX_INFRA_DIR" && ./setup.sh`). +The renamed directory can be deleted once you confirm the new clone works.