Fix: Add IAM role configuration for AWS clustering for all affected versions (Product IS issue #21525) #5770
Conversation
…ersions (product-is#21525)
|
wso2-engineering-bot seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account. You have signed the CLA already but the status is still pending? Let us recheck it. |
WalkthroughThis PR updates AWS clustering authentication documentation across 8 Identity Server version branches (5.10.0–7.2.0 and next), introducing two authentication options (IAM role-based and access key-based), clarifying mandatory versus optional parameters, and providing unified IAM policy attachment guidance applicable to both methods. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
en/identity-server/6.1.0/docs/deploy/deployment-guide.md (1)
255-312: Update AWS documentation link to use HTTPS protocol; clarify accessKey/secretKey requirement for Option 2.The two-option approach (IAM role vs access key) is clearly presented with well-structured guidance and a unified IAM permissions section. The note at line 269 clearly documents the default IAM role behavior, and line 271 appropriately flags AWS-only constraints.
Two minor improvements are needed:
AWS documentation link (line 293): Change
http://docs.aws.amazon.com/...tohttps://docs.aws.amazon.com/.... The current http:// URL redirects successfully but uses an outdated protocol.Parameter requirement clarity: Line 287 explicitly states that
securityGroupandregionare mandatory whiletagKeyandtagValueare optional. For consistency and clarity, explicitly confirm thataccessKeyandsecretKeyare mandatory for Option 2 (just as the note clarifiesiamRoleis optional for Option 1).en/identity-server/7.0.0/docs/deploy/deployment-guide.md (1)
275-298: IAM policy is missing a potentially required permission for tag-based filtering.The current policy includes
ec2:DescribeInstances(required for EC2 member discovery) andec2:DescribeAvailabilityZones(not documented as necessary for Hazelcast). However, Hazelcast AWS discovery may also requireec2:DescribeTagsif tag-based filtering is used to identify cluster members. Consider adding this permission or clarifying in the documentation whether tag-based discovery is supported and if so, whether theec2:DescribeTagsaction should be included in the policy.en/identity-server/next/docs/deploy/deployment-guide.md (1)
275-298: Update the AWS documentation link to the current URL.The AWS documentation link on line 279 returns a 301 redirect. Update it to the current AWS managed policies documentation at:
https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.htmlThe IAM policy structure and EC2 permissions (DescribeAvailabilityZones, DescribeInstances) are correct for AWS clustering. The guidance effectively distinguishes policy attachment for IAM roles versus IAM users, reducing confusion.
🧹 Nitpick comments (5)
en/identity-server/7.2.0/docs/deploy/deployment-guide.md (2)
273-273: Add clarity to which parameters are mandatory for Option 2.While line 273 clearly states "The
securityGroupandregionparameters are mandatory, whiletagKeyandtagValueare optional," this guidance immediately follows the Option 2 block. For consistency and clarity, consider adding a similar note directly below the Option 1 TOML block (after line 252) to make it explicit that these same parameter requirements apply to both authentication methods. This prevents readers from assuming different requirements per option.Optionally add a note after the Option 1 configuration block:
tagValue = "a_tag_value" ``` + + !!! note + The `securityGroup` and `region` parameters are mandatory, while `tagKey` and `tagValue` are optional.Then adjust the existing note at line 273 to clarify it applies to both options or remove the duplication.
275-299: Use HTTPS in security documentation; add parameter names for Option 2 consistency.Two minor observations:
URL Protocol: Line 279 references the AWS documentation with
http://instead ofhttps://. For security-sensitive documentation about IAM policies, prefer the secure HTTPS protocol.Parameter Mandatory Status for Option 2: The consolidated IAM permissions section applies to both authentication methods, which is good. However, unlike Option 1 which has a dedicated notes block, the Option 2 block lacks an explicit note restating the mandatory/optional parameter requirements. Consider adding a note block after the Option 2 TOML configuration (similar to the one after Option 1 at lines 254–257) to reinforce this.
Apply this diff to update the URL protocol:
- See the [AWS documentation](http://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_managed-policies.html) for details on how to add the custom IAM policy. + See the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_managed-policies.html) for details on how to add the custom IAM policy.Optionally, to improve consistency, add a note block under the Option 2 configuration (after line 271) that mirrors the mandatory/optional parameter statement.
en/identity-server/5.10.0/docs/setup/deployment-guide.md (1)
287-290: Minor wording refinement suggestion for the note section.The final bullet point combines two related statements. While grammatically acceptable, it could be slightly more scannable by separating the EC2 limitation from the fallback guidance:
- IAM role-based authentication is only supported when running WSO2 Identity Server on EC2 instances. If running outside AWS (such as Lambda functions or external clients), you must use access keys. + IAM role-based authentication is only supported on EC2 instances. + For deployments outside AWS (such as Lambda functions or external clients), use access keys instead.en/identity-server/next/docs/deploy/deployment-guide.md (2)
273-273: Clarification on mandatory parameters is valuable; consider earlier placement for visibility.The statement clearly distinguishes mandatory (
securityGroup,region) from optional parameters (tagKey,tagValue). However, since this critical requirement appears after both Option 1 and Option 2, readers following only Option 1 might miss it. Consider adding a brief note within each option or restructuring to emphasize this earlier.Example placement improvement:
**Option 1: Using IAM role (Recommended)** If your EC2 instances are configured with an IAM role/instance profile, you can use IAM role-based authentication instead of access keys. This is the recommended approach as it provides more secure, temporary credentials that are automatically rotated by AWS. +!!! note + - **Mandatory parameters:** `securityGroup` and `region` + - **Optional parameters:** `tagKey` and `tagValue` + ```toml [clustering.properties]Alternatively, add a single bulleted note before both options stating: "For both options below,
securityGroupandregionare mandatory;tagKeyandtagValueare optional."
240-273: Consider explicitly noting that the two authentication options are mutually exclusive.While the "Recommended" label on Option 1 and structure of Step 2 with "Option 1" and "Option 2" headings make it clear that these are alternatives, readers unfamiliar with AWS IAM configuration might benefit from explicit guidance. A brief introductory sentence before the two options (e.g., "Choose one of the following authentication methods:") would reinforce that only one option should be used.
Example enhancement:
2. Apply the following parameters to update the values to configure clustering properties. + + Choose one of the following authentication methods: **Option 1: Using IAM role (Recommended)**
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
en/identity-server/5.10.0/docs/setup/deployment-guide.md(2 hunks)en/identity-server/5.11.0/docs/setup/deployment-guide.md(2 hunks)en/identity-server/6.0.0/docs/deploy/deployment-guide.md(2 hunks)en/identity-server/6.1.0/docs/deploy/deployment-guide.md(2 hunks)en/identity-server/7.0.0/docs/deploy/deployment-guide.md(2 hunks)en/identity-server/7.1.0/docs/deploy/deployment-guide.md(2 hunks)en/identity-server/7.2.0/docs/deploy/deployment-guide.md(2 hunks)en/identity-server/next/docs/deploy/deployment-guide.md(2 hunks)
🧰 Additional context used
🪛 LanguageTool
en/identity-server/5.11.0/docs/setup/deployment-guide.md
[uncategorized] ~288-~288: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...ep 3 below. - IAM role-based authentication is only supported wh...
(COMMA_COMPOUND_SENTENCE)
[uncategorized] ~290-~290: Possible missing comma found.
Context: ...s. Option 2: Using access key and secret key Altern...
(AI_HYDRA_LEO_MISSING_COMMA)
en/identity-server/5.10.0/docs/setup/deployment-guide.md
[uncategorized] ~290-~290: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ... instances. If running outside AWS (such as Lambda functions or external clients), y...
(COMMA_COMPOUND_SENTENCE)
🔇 Additional comments (19)
en/identity-server/7.2.0/docs/deploy/deployment-guide.md (3)
240-252: Option 1 IAM role configuration is well-structured and clear.The new Option 1 documentation properly introduces IAM role-based authentication as the recommended approach with a clear TOML configuration block. The parameter structure (iamRole, securityGroup, region, tagKey, tagValue) is consistent with the next option and follows documentation conventions.
254-257: IAM role notes provide helpful context and important limitations.The notes correctly clarify the default behavior (default EC2 instance role if iamRole not specified) and the AWS-only limitation for IAM role-based authentication. This guidance helps users understand when to choose which authentication method.
259-272: Option 2 access key configuration mirrors Option 1 structure appropriately.The TOML format and parameter naming (accessKey, secretKey, securityGroup, region, tagKey, tagValue) are consistent with Option 1, making it easy for users to compare the two authentication methods.
en/identity-server/5.10.0/docs/setup/deployment-guide.md (2)
273-306: Well-structured introduction of two authentication options for AWS EC2 clustering.The documentation clearly separates IAM role–based (recommended) and access key authentication paths with appropriate parameter listings. The note block correctly emphasizes key constraints (automatic role detection, EC2-only support).
308-331: IAM permissions guidance is clear and applicable to both authentication methods.The policy definition is accurate for Hazelcast AWS instance discovery, and the guidance to attach the policy conditionally (to IAM role or IAM user depending on method) is correct and helpful.
en/identity-server/5.11.0/docs/setup/deployment-guide.md (3)
272-289: Clear and accurate Option 1 documentation.The IAM role-based authentication section is well-structured with helpful context on security benefits, proper TOML formatting, and important limitations (EC2-only applicability). The note about automatic use of default EC2 IAM role is a valuable detail for users. Minor style note: line 288 could read more fluidly with: "...when running WSO2 Identity Server on EC2 instances, and if running outside AWS..." but the current period-separated structure is acceptable.
290-304: Well-preserved backward compatibility with clear parameter guidance.Option 2 retains the access key method with proper TOML formatting and a helpful summary of parameter requirements (mandatory vs. optional). The recommendation to use the same security group is practical. Note: Line 290's static analysis flag about a missing comma appears to be a false positive, as Markdown header styling does not require commas.
306-329: Excellent unification of IAM permissions guidance.The new section consolidates permission requirements for both authentication methods, eliminating redundancy while clearly distinguishing between IAM role attachment (for EC2-based usage) and IAM user attachment (for access key-based usage). The IAM policy is correctly scoped to the necessary EC2 discovery operations. This unified approach will reduce user confusion and improve security clarity.
en/identity-server/6.0.0/docs/deploy/deployment-guide.md (3)
261-278: ✓ IAM role-based authentication documentation is well-structured and complete.The introduction of Option 1 with IAM role-based authentication is clear, properly marked as "Recommended," and includes valuable context:
- TOML configuration example is correct and well-formatted
- Line 275 documents default EC2 instance role behavior, improving usability
- Line 277 correctly notes EC2-only limitation and directs users to alternative approach
- Aligns with AWS security best practices (temporary credentials over static keys)
279-294: ✓ Option 2 and parameter guidance appropriately presented.The access key-based authentication is clearly documented as an alternative, and line 293–294 effectively clarifies that
securityGroupandregionare mandatory across both authentication methods, whiletagKeyandtagValueremain optional. This removes ambiguity for users implementing either option.
295-318: ✓ IAM permissions section consolidates requirements and provides actionable guidance.The new Step 3 (lines 295–318) successfully:
- Clarifies that the same IAM policy applies to both authentication methods (line 297)
- Provides explicit guidance at lines 301–302 on where to attach the policy (IAM role vs. IAM user), reducing configuration errors
- Includes the standard EC2 discovery policy with correct minimum permissions
- References external AWS documentation for policy management (line 299)
en/identity-server/7.0.0/docs/deploy/deployment-guide.md (2)
241-273: Two-option authentication structure is clear and well-organized.The parallel presentation of IAM role-based and access key authentication options is intuitive. Parameter documentation properly distinguishes between mandatory (
securityGroup,region) and optional (tagKey,tagValue) settings, which is helpful for users. The note on line 255 about default IAM role behavior is valuable.However, one minor clarity point: the statement "It's recommended to add all the nodes to the same security group" (line 273) applies to both options, but it appears only after Option 2. Consider moving this guidance to a note that applies to both authentication methods, or repeating it for Option 1.
254-258: Document the IAM role default behavior and EC2-only limitation.The note properly clarifies:
- Default IAM role is used if
iamRoleis not specified (line 255)- EC2-only limitation for IAM role auth (line 257)
These are important constraints that prevent misuse. The guidance is accurate and helpful.
en/identity-server/next/docs/deploy/deployment-guide.md (2)
241-257: Well-structured IAM role documentation with appropriate caveats.The section clearly motivates the recommended approach, provides a proper configuration example, and includes three well-placed notes that cover default behavior, permission requirements, and AWS-only scope. The documentation is accurate and actionable.
259-271: Clear alternative authentication method.The section appropriately documents access key-based authentication as an alternative. The configuration structure mirrors Option 1, which aids reader comprehension, and the use of masked placeholders for secrets follows security best practices.
en/identity-server/7.1.0/docs/deploy/deployment-guide.md (4)
275-298: Effective consolidation of IAM permissions guidance.The unified IAM permissions section (applicable to both authentication methods) is well-structured, and the explicit guidance on attaching to IAM roles versus IAM users eliminates ambiguity. The policy actions (DescribeAvailabilityZones, DescribeInstances) are appropriate for EC2 discovery.
1-1:⚠️ Administrative: CLA signature required before merge.Per the PR comments, the contributor (wso2-engineering-bot) has not signed the repository Contributor License Agreement. This must be resolved before the PR can be merged.
1-519: Cross-version consistency is maintained across all existing version directories.Verification confirms that all 6 version directories with deployment-guide.md files (6.0.0, 6.1.0, 7.0.0, 7.1.0, 7.2.0, and next) contain identical AWS EC2 configuration structures, parameter names (iamRole, accessKey, secretKey, securityGroup, region, tagKey, tagValue), and explanatory guidance. Note: The PR summary states changes apply to 8 versions, but only 6 version directories contain deployment-guide.md; versions 5.10.0 and 5.11.0 do not have this file in the repository.
240-273: Clear and well-structured authentication options with accurate AWS guidance.The two-option layout (IAM role vs access keys) with explicit mandatory/optional parameter guidance is clear and user-friendly. The note (lines 254–257) appropriately highlights the EC2-only constraint and default IAM role behavior. Line 243's statement that AWS credentials are "automatically rotated by AWS" is accurate per AWS documentation and requires no adjustment.
This PR was automatically generated by Claude AI.
Changes Made
Documentation Enhancement
The AWS EC2 membership scheme section has been enhanced to document two authentication methods:
Option 1: Using IAM role (Recommended) - New addition
iamRoleparameter is not specified, the default IAM role attached to the EC2 instance is automatically usedOption 2: Using access key and secret key - Existing method, now clearly labeled as an alternative
Updated IAM Permissions Section
Affected Versions
This fix has been applied to ALL affected version directories:
Note: Version 5.9.0 was not updated as it only documents AWS ECS membership scheme, not AWS EC2 membership scheme.
Style Compliance
Verification
References
Research and implementation based on:
Summary by CodeRabbit
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.