playbooks

home / skills / bitsoex / bitso-java / upgrade-aws-sdk-v2

upgrade-aws-sdk-v2 skill

/.claude/skills/upgrade-aws-sdk-v2

This skill guides migrating from AWS SDK v1 to v2 in Java projects, enabling faster adoption and modern features.

npx playbooks add skill bitsoex/bitso-java --skill upgrade-aws-sdk-v2

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
3.7 KB
---
name: upgrade-aws-sdk-v2
description: >
  Migrate from AWS SDK for Java v1 (com.amazonaws) to v2 (software.amazon.awssdk).
  Use when projects need to move away from deprecated AWS SDK v1 to the modern v2 API.
compatibility: Java projects using Gradle with AWS SDK dependencies
metadata:
  version: "2.0.0"
  technology: java
  category: modernization
  tags:
    - aws
    - sdk
    - migration
    - dependencies
    - upgrade
---

# Upgrade AWS SDK v2

Migrate Java projects from AWS SDK v1 (`com.amazonaws`) to v2 (`software.amazon.awssdk`).

## When to Use

- Project uses deprecated AWS SDK v1 (`com.amazonaws.*` imports)
- Dependabot/security scans flag v1 vulnerabilities
- Need features only available in v2 (async clients, HTTP/2, etc.)
- When asked to "upgrade to aws sdk v2"

## Skill Contents

### Sections

- [When to Use](#when-to-use) (L23-L29)
- [Critical: MSK IAM Authentication](#critical-msk-iam-authentication) (L49-L61)
- [Migration Strategy (Priority Order)](#migration-strategy-priority-order) (L62-L70)
- [Quick Start](#quick-start) (L71-L110)
- [References](#references) (L111-L116)
- [Related Command](#related-command) (L117-L120)
- [Related Resources](#related-resources) (L121-L124)

### Available Resources

**📚 references/** - Detailed documentation
- [migration patterns](references/migration-patterns.md)

---

## Critical: MSK IAM Authentication

When migrating to AWS SDK v2, also update `aws-msk-iam-auth` if using Kafka with MSK IAM.

**Error after migration:**
```
NoClassDefFoundError: com/amazonaws/auth/AWSCredentialsProvider
```

**Fix:** Update `aws-msk-iam-auth` to `2.3.5` (AWS SDK v2 compatible).

See [references/migration-patterns.md](references/migration-patterns.md) for details.

## Migration Strategy (Priority Order)

| Priority | Strategy | When to Use |
|----------|----------|-------------|
| 1 | **Update library** | A newer version of the library uses v2 |
| 2 | **Update BOM** | v1 comes from Spring Boot or other BOM |
| 3 | **Dependency substitution** | Replace v1 artifact with v2 equivalent |
| 4 | **Direct code migration** | Only if no library update available |

## Quick Start

### 1. Identify v1 Usages

```bash
# Find all files with v1 imports
grep -r "import com.amazonaws" --include="*.java" . | grep -v "/build/"

# Check dependency tree
./gradlew dependencies --configuration runtimeClasspath | grep -B5 "com.amazonaws"
```

### 2. Apply Migration

See `references/migration-patterns.md` for detailed code migration patterns.

**Dependency Substitution (in root build.gradle):**

```groovy
allprojects {
    configurations.configureEach {
        resolutionStrategy.dependencySubstitution {
            substitute module("com.amazonaws:aws-java-sdk-s3")
                using module("software.amazon.awssdk:s3:${libs.versions.aws.sdk.v2.get()}")
                because "Migrate to AWS SDK v2"
        }
    }
}
```

### 3. Validate

```bash
# Verify no v1 imports remain
grep -r "import com.amazonaws" --include="*.java" . | grep -v "/build/"

# Build and test
./gradlew clean build test
```

## References

| Reference | Content |
|-----------|---------|
| [references/migration-patterns.md](references/migration-patterns.md) | Code migration patterns for S3, SQS, SNS, Lambda |

## Related Command

This skill is referenced by: `/upgrade-to-aws-sdk-v2` (see `java/commands/`)

## Related Resources

- [AWS SDK v2 Developer Guide](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/)
- [AWS SDK v2 Migration Guide](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration.html)
<!-- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY -->
<!-- Source: bitsoex/ai-code-instructions → java/skills/upgrade-aws-sdk-v2/SKILL.md -->
<!-- To modify, edit the source file and run the distribution workflow -->

Overview

This skill helps migrate Java projects from AWS SDK v1 (com.amazonaws) to AWS SDK v2 (software.amazon.awssdk). It provides a practical migration strategy, quick commands to find and replace v1 usage, and recommended dependency changes to minimize code churn. Use it to remove deprecated v1 imports, resolve dependency conflicts, and adopt v2 features like async clients and HTTP/2.

How this skill works

The skill inspects source files and Gradle/Maven dependencies to locate com.amazonaws imports and transitive v1 artifacts. It recommends a priority-ordered migration strategy: prefer library updates, then BOM overrides, then dependency substitution, and finally direct code changes. It includes concrete Gradle snippets for dependency substitution and validation commands to confirm removal of v1 usage.

When to use it

  • Project contains imports starting with com.amazonaws.*
  • Dependabot or security scans flag AWS SDK v1 vulnerabilities
  • You need v2-only features such as async clients or HTTP/2
  • Upgrading libraries or platform BOMs to eliminate v1 transitive dependencies
  • Deliverable requests explicitly require migrating to AWS SDK v2

Best practices

  • Prefer upgrading dependent libraries to versions that already use SDK v2 before changing code.
  • Check BOMs (Spring Boot, corporate BOMs) for v1 overrides and update BOM or use dependency management to force v2.
  • Use dependency substitution at the build root to replace v1 artifacts with v2 equivalents when library updates are not available.
  • Run grep and dependency tree checks early and after changes to validate no com.amazonaws imports remain.
  • Update related plugins or connectors (example: aws-msk-iam-auth) to v2-compatible versions to avoid NoClassDefFoundError.

Example use cases

  • A legacy service uses S3 and SQS via com.amazonaws; replace transitive v1 dependencies and migrate usage to software.amazon.awssdk clients.
  • A monorepo where a Spring Boot BOM pulls in aws-java-sdk modules; override the BOM to point to v2 or update the BOM version.
  • A security audit flags v1; use dependency substitution and quick validation commands to remediate and rebuild.
  • Migrating Kafka MSK IAM authentication: update aws-msk-iam-auth to a v2-compatible release to prevent AWSCredentialsProvider errors.

FAQ

What if a library I use has no v2 release?

Use dependency substitution to swap the v1 artifact for the v2 equivalent if APIs match, or perform direct code migration for only the modules that reference v1.

How do I validate the migration?

Search the codebase for import com.amazonaws, inspect the build dependency tree for com.amazonaws artifacts, then run clean build and tests to confirm runtime behavior.