Skip to content

Update Graviton Power #157

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nadetastic merged 2 commits into from
Jul 8, 2026
Merged

Update Graviton Power #157

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6a65fb9
Add files via upload
tohwsw Jun 29, 2026
c7e69bd
Merge pull request #1 from tohwsw/tohwsw-patch-1
tohwsw Jun 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
324 changes: 262 additions & 62 deletions aws-graviton-migration/POWER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: "graviton-migration-power"
displayName: "Graviton Migration Power"
displayName: "Plan and Migration to Graviton Power"
description: "Analyzes source code to identify compatibilities with Graviton processors(Arm64 architecture). Generates reports with incompatibilities and provides suggestions for minimal required and recommended versions for language runtimes and dependency libraries."
keywords: ["ec2", "graviton", "arm", "migration", "porting", "dependencies", "compatibilities", "arm64", "aarch64"]
author: "AWS"
Expand All @@ -10,110 +10,310 @@ author: "AWS"

## Overview

The Graviton Migration Power helps developers migrate workloads to AWS Graviton processors (Arm64 architecture). It analyzes source code for known code patterns and dependency libraries to identify compatibilities with Graviton processors, generates reports highlighting detected compatibility issues (manual review recommended), and provides actionable suggestions for minimal required and recommended versions for both language runtimes and dependency libraries.
Migrates codebases from x86 to AWS Graviton (Arm64). Scans Dockerfiles, dependency manifests, and source code to identify architecture-specific issues, then provides actionable fixes.

### What This Power Does
---

## Migration Workflow

Copy this checklist and track progress:

```
Migration Progress:
- [ ] Step 1: Verify prerequisites (Docker running)
- [ ] Step 2: Check Dockerfiles for ARM64 base image compatibility
- [ ] Step 3: Verify packages installed in Dockerfiles
- [ ] Step 4: Check dependency manifests (requirements.txt, pom.xml, go.mod, package.json)
- [ ] Step 5: Determine language and run migrate_ease_scan
- [ ] Step 6: Generate migration report
- [ ] Step 7: Get user confirmation before making changes
- [ ] Step 8: Apply changes
```

### Step 1: Verify Prerequisites

**CRITICAL**: Docker must be running. If not, stop and inform the user.

```bash
docker ps
```

If this fails, do NOT proceed. Tell the user to start Docker Desktop.

### Step 2: Check Dockerfiles for Base Image Compatibility

For each Dockerfile found in the project:

1. Extract the base image (e.g., `FROM eclipse-temurin:17-jdk-alpine`)
2. Run `check_image` or `skopeo` to verify ARM64 support
3. If image lacks ARM64 support → find a multi-arch alternative

**Validation**: Confirm the replacement image supports BOTH `amd64` AND `arm64` before recommending it.

### Step 3: Verify Packages Installed in Dockerfiles

For each package installed via `apt-get`, `apk`, `yum`, or `pip` inside Dockerfiles:

1. Send to `knowledge_base_search`: "Is [package] compatible with Arm architecture?"
2. If incompatible → suggest compatible version or alternative

### Step 4: Check Dependency Manifests

**Python projects** (requirements.txt, setup.py, pyproject.toml):
→ Check each package with `knowledge_base_search`
→ Focus on packages with native C extensions

The goal is to migrate a codebase from x86 to Arm. Use the MCP server tools to help you with this. Check for x86-specific dependencies (build flags, intrinsics, libraries, etc) and change them to Arm architecture equivalents, help identify compatibility issues and suggests optimizations for Arm architecture. Look at Dockerfiles, versionfiles, and other dependencies, compatibility, and optimize performance.
**Java projects** (pom.xml, build.gradle):
→ Check native dependencies (Netty classifiers, JNI libraries)
→ Look for architecture-specific classifiers like `linux-x86_64`

Steps to follow:
* Look in all Dockerfiles and use the check_image and/or skopeo tools to verify Arm compatibility, changing the base image if necessary.
* Look at the packages installed by the Dockerfile and send each package to the knowledge_base_search tool to check each package for Arm compatibility. If a package is not compatible, change it to a compatible version. When invoking the tool, explicitly ask "Is [package] compatible with Arm architecture?" where [package] is the name of the package.
* Look at the contents of any requirements.txt files line-by-line and send each line to the knowledge_base_search tool to check each package for Arm compatibility. If a package is not compatible, change it to a compatible version.
* Look at the codebase that you have access to, and determine what the language used is.
* Run the migrate_ease_scan tool on the codebase, using the appropriate language scanner based on what language the codebase uses.
* Provide an analysis report with complete dependency analysis, migration recommendations and optimizations for AWS Graviton processor
* Get a confirmation with user before proceeding with the code changes
**Go projects** (go.mod):
→ Check CGO dependencies
→ Look for platform-specific build tags

**JavaScript/Node.js** (package.json):
→ Check native addons (node-gyp based packages)
→ Look for platform-specific optional dependencies

**C/C++** (Makefile, CMakeLists.txt):
→ Check for x86 intrinsics, inline assembly
→ Look for architecture-specific compiler flags

### Step 5: Run migrate_ease_scan

Determine the primary language, then run the appropriate scanner:

| Language | Scanner |
|----------|---------|
| Python | `python` |
| Java | `java` |
| Go | `go` |
| JavaScript | `js` |
| C/C++ | `cpp` |

**Validation**: Review scan results for false positives before including in report.

### Step 6: Generate Migration Report

Use the report template below. Do NOT proceed to changes without user review.

### Step 7: Get User Confirmation

Present the report and explicitly ask: "Would you like me to apply these changes?"

**Do NOT modify any files until the user confirms.**

### Step 8: Apply Changes

Apply changes one file at a time. After each file, briefly state what was changed.

---

## Onboarding
## Report Template

### Prerequisites
Use this structure for all migration reports:

```markdown
# Graviton Migration Report

## Summary
[One paragraph: project type, total issues found, severity breakdown (critical/warning/info)]

Before using the Graviton Migration Power, ensure the following are installed and running:
## Docker Images

#### Required Tools
| Image | Source File | ARM64 Support | Action Required |
|-------|------------|---------------|-----------------|
| `image:tag` | Dockerfile | ❌ / ✅ | Replace with `image:tag` / None |

1. **Docker Desktop**: Required for running the Arm MCP server and migration assessment tools
- Verify installation: `docker --version`
- Ensure Docker daemon is running: `docker ps`
- **CRITICAL**: If Docker is not installed or not running, DO NOT proceed with migration assessment
## Dependencies

2. **Git** (optional but recommended): For scanning remote repositories
- Verify installation: `git --version`
| Package | Version | File | ARM64 Compatible | Action |
|---------|---------|------|------------------|--------|
| `pkg` | x.y.z | requirements.txt | ❌ / ✅ | Upgrade to x.y.z / None |

### Step 1: Validate MCP Server Connection
## Source Code Scan Results

The power uses the Arm MCP server running in a Docker container. Test the connection:
**Scanner used**: [language] scanner
**Files scanned**: [count]
**Issues found**: [count]

[List each issue with file path, line number if available, and recommended fix]

## Recommendations (Priority Order)

1. [Critical] ...
2. [Critical] ...
3. [Warning] ...
4. [Info] ...

## Build Instructions

### Multi-Architecture Docker Build
```bash
# The MCP server should auto-start when you use the power
# If you encounter issues, verify Docker is running
docker ps
docker buildx create --name multiarch --use --bootstrap
docker buildx build -t your-registry/app:latest \
--platform linux/amd64,linux/arm64 \
--push .
```
```

---

## Examples

### Example: Checking a Docker Image

**Input**: Dockerfile contains `FROM eclipse-temurin:17-jdk-alpine`

**Steps**:
1. Run `check_image` on `eclipse-temurin:17-jdk-alpine`
2. Result: x86_64 only ❌
3. Run `check_image` on `eclipse-temurin:17-jdk`
4. Result: supports amd64, arm64 ✅

**Report entry**:
| `eclipse-temurin:17-jdk-alpine` | Dockerfile | ❌ | Replace with `eclipse-temurin:17-jdk` |

### Example: Checking a Python Dependency

**Input**: requirements.txt contains `grpcio==1.48.0`

**Steps**:
1. Query `knowledge_base_search`: "Is grpcio compatible with Arm architecture?"
2. Result: grpcio 1.48.0+ provides ARM64 wheels ✅

### Step 2: Understand Available Tools
**Report entry**:
| `grpcio` | 1.48.0 | requirements.txt | ✅ | None |

This power provides access to several specialized tools:
### Example: Netty Native Transport (Java)

- **migrate-ease scan**: Scans codebases for Arm compatibility issues (C++, Python, Go, JS, Java)
- **skopeo**: Inspects container images remotely for architecture support
- **knowledge base search**: Searches Arm documentation for migration guidance
- **check image**: Quick Docker image architecture verification
- **mca (Machine Code Analyzer)**: Analyzes assembly code performance predictions
**Input**: pom.xml contains:
```xml
<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-transport-native-epoll</artifactId>
<classifier>linux-x86_64</classifier>
</dependency>
```

**Steps**:
1. Identify x86_64-specific classifier
2. Query `knowledge_base_search`: "Is netty-transport-native-epoll compatible with Arm architecture?"
3. Result: Needs additional `linux-aarch_64` classifier

**Fix**: Add alongside existing:
```xml
<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-transport-native-epoll</artifactId>
<classifier>linux-aarch_64</classifier>
</dependency>
```

---

## Steering Files
## Degrees of Freedom

This power has the following steering files for detailed workflow guidance:
**Low freedom (follow exactly)**:
- The checklist order (Steps 1-8)
- Never modify files without user confirmation (Step 7)
- Always verify Docker is running before proceeding
- Use the report template structure

- **karpenter.md** — Guides detection and migration of Karpenter configurations (NodePool, EC2NodeClass) to use Graviton ARM64 instances. Covers gradual rollout with taints/tolerations, instance family mappings, and post-migration cleanup.
**High freedom (adapt to context)**:
- How to phrase knowledge_base_search queries
- Which alternative images to suggest (pick best multi-arch option)
- How to organize findings within report sections
- Level of detail in recommendations based on project complexity

---

## License & Legal
## Troubleshooting

### Power License
### Docker Not Running

**Symptom**: MCP server fails to start, tools return connection errors
**Fix**: Tell user to start Docker Desktop and retry

### Scan Timeout

**Symptom**: `migrate_ease_scan` hangs or returns timeout error
**Cause**: Large codebase or slow Docker volume mount
**Fix**: Try scanning a subdirectory, or suggest user increase Docker resource limits

### Image Not Found

**Symptom**: `check_image` or `skopeo` returns "not found"
**Cause**: Private registry requiring authentication, or typo in image name
**Fix**: Verify image name is correct. For private images, inform user that manual verification is needed.

This power is provided by AWS and is subject to the AWS Customer Agreement and applicable AWS service terms.
### Knowledge Base Returns No Results

### MCP Server Licenses
**Symptom**: `knowledge_base_search` returns empty or irrelevant results
**Fix**: Rephrase query. Try: "Is [package] [version] compatible with ARM64 aarch64?"
If still no results, note the package as "unknown compatibility - manual verification recommended"

This power uses the following MCP server and tools:
### Scan Reports False Positives

- **arm-mcp** (`armswdev/arm-mcp:latest`): Docker container providing Arm migration tools
- Distributed via Docker Hub by Arm
- Contains multiple open-source tools with their respective licenses
- For complete license information, see: https://github.com/arm/mcp/blob/main/LICENSE
**Symptom**: `migrate_ease_scan` flags code that is actually architecture-neutral
**Fix**: Review each finding. If the flagged code doesn't use architecture-specific features (intrinsics, inline assembly, platform-specific paths), mark as false positive in the report.

---

## Onboarding

### Prerequisites

1. **Docker Desktop**: Required for the Arm MCP server
- Verify: `docker --version`
- Confirm running: `docker ps`

2. **Git** (optional): For scanning remote repositories
- Verify: `git --version`

### Available Tools

| Tool | Purpose |
|------|---------|
| `migrate_ease_scan` | Scan codebase for Arm compatibility issues |
| `skopeo` | Inspect container images for architecture support |
| `knowledge_base_search` | Search Arm documentation for package compatibility |
| `check_image` | Quick Docker image architecture check |
| `mca` | Machine Code Analyzer for assembly performance |

---

### Third-Party Dependencies
## Steering Files

- **karpenter.md** — Karpenter NodePool/EC2NodeClass migration to Graviton instances
- **build-pipelines.md** — CI/CD pipeline adjustments for multi-arch builds

---

This power requires Docker to run the MCP server container. Docker is subject to its own licensing terms. See: https://www.docker.com/legal/docker-subscription-service-agreement/
## License & Legal

### Usage Terms
### Power License

By using this power, you acknowledge that:
- You are responsible for compliance with all applicable licenses
- Code analysis is performed using open-source tools within a Docker container
- You should review and comply with individual tool licenses for production use
Provided by AWS, subject to the AWS Customer Agreement and applicable service terms.

### MCP Server

- **arm-mcp** (`armlimited/arm-mcp:latest`): Docker container with Arm migration tools
- License: https://github.com/arm/mcp/blob/main/LICENSE

### Third-Party

- Docker: https://www.docker.com/legal/docker-subscription-service-agreement/

---

## Additional Resources

- AWS Graviton Technical Guide: https://github.com/aws/aws-graviton-getting-started
- Arm Architecture Reference: Available through knowledge base search
- Migration Tools Documentation: Included in MCP server responses
- Arm Architecture Reference: Available via `knowledge_base_search`

---

## Power Metadata

**Version**: 1.1
**Author**: AWS
**Supported Languages**: C++, Python, Go, JavaScript, Java
**Container Runtime**: Docker required
**MCP Server**: arm-mcp (Docker-based). License information, see: https://github.com/arm/mcp/blob/main/LICENSE
**Supported Languages**: C++, Python, Go, JavaScript, Java
**Container Runtime**: Docker required
**MCP Server**: arm-mcp (Docker-based)
Loading
Loading