docs(aws): clarify generated External ID behavior for key and role credentials

[llewellyn-sl]

Summary

• document AWS credential modes in Cloud and Enterprise compute-environment docs
• clarify External ID behavior from credential creation flow
• specify that External ID is optional for key-based credentials and mandatory for role-based credentials
• add/align trust policy examples using sts:ExternalId
• keep existing-credentials compatibility notes
• keep TOWER_ALLOW_CREDENTIALS note scoped to Enterprise docs only

Jira

• EDU-1025

Notes

• This PR updates docs only (no product code changes).

[netlify]

❌ Deploy Preview for seqera-docs failed. Why did it fail? →

Name	Link
🔨 Latest commit	7cd53a9
🔍 Latest deploy log	https://app.netlify.com/projects/seqera-docs/deploys/69a997969e89d3f6335c33e4

[llewellyn-sl]

@claude please review

[claude]

Claude finished @llewellyn-sl's task —— View job

---

AWS External ID Documentation Review ✅

I've completed a thorough review of your AWS External ID documentation changes across all 6 files. Here's my comprehensive analysis:

Files Reviewed:

• platform-cloud/docs/compute-envs/aws-batch.md
• platform-cloud/docs/compute-envs/aws-cloud.md
• platform-cloud/docs/compute-envs/eks.md
• platform-enterprise_docs/compute-envs/aws-batch.md
• platform-enterprise_docs/compute-envs/aws-cloud.md
• platform-enterprise_docs/compute-envs/eks.md

Overall Assessment: Excellent ⭐

Your documentation changes successfully address AWS credential modes and External ID behavior with high consistency and technical accuracy.

✅ Strengths

1. Perfect Content Consistency

• Identical External ID sections across all 6 files ensures uniform user experience
• Clear distinction between key-based vs role-based credentials
• Proper explanation of when External ID is optional vs mandatory

2. Technical Accuracy

• Correctly explains that Platform generates External ID for key-based credentials
• Properly states External ID is mandatory for role-based credentials
• Accurate description of cross-account security use case

3. Excellent Structure

• Clean tabbed interface for credential types
• Logical flow from credential selection to External ID explanation
• Consistent formatting and organization across files

4. Voice & Tone Compliance

• Maintains second person perspective throughout
• Uses clear, confident language
• Follows established documentation patterns

🟡 Minor Issues Found (3 total)

Issue 1: Subject-Verb Agreement

File: aws-cloud.md (both Cloud & Enterprise versions)
Line: ~9
Current: "AWS cloud compute environments allows you to..."
Fix: "AWS cloud compute environments allow you to..."
Priority: Medium - grammatical error

Issue 2: Passive Voice Clarity

File: aws-batch.md (both versions)
Line: ~88
Current: "Compute environment instances launched with this key pair allow for direct SSH access."
Suggested: "This key pair allows direct SSH access to compute environment instances."
Priority: Low - stylistic improvement

Issue 3: Minor Terminology Inconsistency

All files: Mixed capitalization of "External ID" vs "external ID" within same paragraphs
Suggested: Use consistent capitalization throughout
Priority: Low - minor inconsistency

✅ Documentation Standards Compliance

• ✅ Formatting: Excellent Markdown structure and consistent styling
• ✅ Links: Proper cross-references to credential setup docs
• ✅ Organization: Logical information hierarchy
• ✅ User Experience: Clear instructions and helpful context
• ✅ Consistency: Perfect alignment between Cloud and Enterprise versions

🎯 Recommendation

Approve with minor fixes. The documentation effectively addresses the EDU-1025 requirements and provides clear guidance on AWS credential configuration. The identified issues are minor and don't impact the technical accuracy or user comprehension.

The new External ID sections are well-integrated and will help users understand the security implications and proper configuration of their AWS credentials.

---

[munishchouhan]

@llewellyn-sl Please update the trust policy to this

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::161471496260:role/SeqeraPlatformCloudAccessRole"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "<ExternalId>"
                }
            }
        },
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::161471496260:role/SeqeraPlatformCloudAccessRole"
            },
            "Action": "sts:TagSession"
        }
    ]
}

[llewellyn-sl]

@claude review

[claude]

Claude finished @llewellyn-sl's task —— View job

---

AWS External ID Documentation Review ✅

I've completed a comprehensive review of your AWS External ID documentation updates across Cloud and Enterprise compute environment docs.

Files Reviewed:

• platform-cloud/docs/compute-envs/aws-batch.md
• platform-cloud/docs/compute-envs/aws-cloud.md
• platform-cloud/docs/compute-envs/eks.md
• platform-enterprise_docs/compute-envs/aws-batch.md
• platform-enterprise_docs/compute-envs/aws-cloud.md
• platform-enterprise_docs/compute-envs/eks.md

Overall Assessment: Excellent ⭐

Your documentation changes successfully address AWS credential modes and External ID behavior with high consistency and technical accuracy. The implementation effectively addresses the EDU-1025 requirements.

✅ Key Strengths

1. Technical Accuracy & Completeness

• Correctly explains External ID generation by Platform during credential creation
• Properly distinguishes between key-based (optional External ID) vs role-based (mandatory External ID) credentials
• Accurate trust policy examples with proper sts:ExternalId and sts:TagSession statements
• Correctly handles Cloud vs Enterprise differences (Cloud uses fixed SeqeraPlatformCloudAccessRole, Enterprise uses custom role)

2. Excellent Content Consistency

• Identical External ID sections across all 6 files ensures uniform user experience
• Proper implementation of tabbed interface for credential types
• Consistent messaging about backwards compatibility ("Existing credentials created before March 2026 continue to work")

3. Enterprise-Specific Features

• Correctly includes TOWER_ALLOW_INSTANCE_CREDENTIALS=true legacy mode documentation only in Enterprise files
• Proper explanation of legacy credential behavior (IAM role ARN only, no External ID)
• Clear guidance on trust policy modifications for legacy mode

4. User Experience

• Clear step-by-step credential creation flow
• Helpful notes about when External ID is required vs optional
• Good backwards compatibility messaging to reassure existing users

🟡 Minor Issues Found (3 total)

Issue 1: Trust Policy Consistency

Location: Multiple files
Current: Mixed usage of specific Cloud role ARN vs generic placeholder
Recommendation: Consider standardizing placeholder usage for better maintainability
Priority: Low - consistency improvement

Issue 2: Cross-Reference Alignment

Location: Various credential sections
Observation: Some sections reference steps that may have changed due to added External ID steps
Recommendation: Verify all step references are accurate after External ID additions
Priority: Low - navigation improvement

Issue 3: Configuration Variable Context

Location: Enterprise files
Current: Good inclusion of TOWER_ALLOW_INSTANCE_CREDENTIALS but could benefit from more context about when to use legacy mode
Suggestion: Consider adding brief guidance on migration strategy from legacy to External ID mode
Priority: Low - enhancement opportunity

✅ Implementation Highlights

Proper Cloud/Enterprise Differentiation:

• Cloud: Fixed role ARN arn:aws:iam::161471496260:role/SeqeraPlatformCloudAccessRole
• Enterprise: Configurable role ARN <YOUR_SEQERA_ROLE_ARN> placeholder

Backwards Compatibility:

• Clear messaging about March 2026 cutoff date
• Proper legacy credential support documentation
• No breaking changes for existing users

Security Best Practices:

• Mandatory External ID for role-based credentials enhances security
• Proper cross-account trust policy examples
• Clear separation of concerns between credential types

🎯 Recommendation

Approve for merge. The documentation effectively addresses the AWS External ID requirements and provides clear, consistent guidance across all compute environment types. The minor issues identified are suggestions for future improvements and don't impact the technical accuracy or user comprehension of the current implementation.

This update successfully enhances AWS credential security while maintaining full backwards compatibility for existing users.

✅ Documentation Standards Compliance

• Formatting: Excellent Markdown structure and consistent styling
• Voice & Tone: Maintains second person perspective and confident language
• Organization: Logical information hierarchy and clear section flow
• Consistency: Perfect alignment between Cloud and Enterprise versions
• Technical Accuracy: Correct AWS IAM and trust policy specifications

---

[munishchouhan]

@llewellyn-sl FYI, external Id and role crdentials are live in plaform prod now