docs: refine AWS byoc guide with JSON policies instead of just terraform#231
docs: refine AWS byoc guide with JSON policies instead of just terraform#231Alex Bartolomey (zoomoid) wants to merge 2 commits intomainfrom
Conversation
Signed-off-by: Alexander Bartolomey <alexander.bartolomey@nitrado.net>
There was a problem hiding this comment.
Pull request overview
This PR refines the AWS Bring Your Own Cloud (BYOC) guide by adding JSON-formatted IAM policies alongside the existing Terraform examples. This enables customers who are not using Terraform to configure AWS access for GameFabric operators using the AWS Console or other tools.
Changes:
- Added JSON policy examples in code-group blocks for trust policies and permission policies (EKS, EC2, Autoscaling, and Auxiliary permissions)
- Restructured documentation to present both JSON and Terraform options side-by-side
- Updated section headings from "Creating the role and assumption policy" and "Creating policies for resource management" to "Set up account federation" and streamlined instructions
- Modified the conclusion section from "Confirming the AWS setup" to "Validating the AWS setup" with clearer language
src/multiplayer-servers/getting-started/cloud-provider-setup.md
Outdated
Show resolved
Hide resolved
src/multiplayer-servers/getting-started/cloud-provider-setup.md
Outdated
Show resolved
Hide resolved
src/multiplayer-servers/getting-started/cloud-provider-setup.md
Outdated
Show resolved
Hide resolved
src/multiplayer-servers/getting-started/cloud-provider-setup.md
Outdated
Show resolved
Hide resolved
src/multiplayer-servers/getting-started/cloud-provider-setup.md
Outdated
Show resolved
Hide resolved
src/multiplayer-servers/getting-started/cloud-provider-setup.md
Outdated
Show resolved
Hide resolved
src/multiplayer-servers/getting-started/cloud-provider-setup.md
Outdated
Show resolved
Hide resolved
src/multiplayer-servers/getting-started/cloud-provider-setup.md
Outdated
Show resolved
Hide resolved
Signed-off-by: Alexander Bartolomey <alexander.bartolomey@nitrado.net>
|
|
||
| After creating the policies, attach them to the created role. Go to the Role you created, choose the `Permissions` tab and click on `Add permissions > Attach policies`. Select the Policies you just created, and confirm with `Add permissions`. | ||
|
|
||
| ### Validating the AWS setup |
There was a problem hiding this comment.
Inconsistent heading style. Line 654 uses "Validating" while line 59 (for the GCP section) uses "Confirming". For consistency, consider using the same verb in both sections. "Confirming" might be more appropriate given that both sections involve contacting Nitrado for verification.
| ### Validating the AWS setup | ||
|
|
||
| After you have completed the steps above, please contact Nitrado to confirm that the setup is complete, and provide us with the ARN of the role you created previously, as we need it on our end to access your account. | ||
| After you have completed the steps above, please contact Nitrado and provide us with the ARN of the Role you created. We need it to access your account and validate that the setup is complete. |
There was a problem hiding this comment.
The sentence structure could be clearer. Consider: "After completing the steps above, contact Nitrado and provide the ARN of the Role you created. We need it to validate the setup and access your account." This separates the two actions (contact and provide) more clearly and uses "validate" instead of "validate that the setup is complete" for conciseness.
| For AWS, to access another organization, you have to setup a chain of _roles_. Roles are AWS objects that allow scoping permissions. Roles are assumable by _principals_. Principals are arbitrary entities operating AWS, and specifically, users or groups of users. This setup allows you to delegate game server cluster management to Gamefabric operators by creating a role that is fine-grained to provision resources _without having to grant broad access to their organization_. | ||
|
|
||
| By chaining those roles together (i.e., allowing a role to assume another role), Gamefabric operators can access your organization/account, | ||
| as long as the chain of _Trust Relationship_ is not broken. | ||
| By chaining those roles together (i.e., allowing a role to assume another role), Gamefabric operators can access your organization/account. |
There was a problem hiding this comment.
Inconsistent capitalization of "Gamefabric" in lines 72 and 74. When referring to the organization or operators in prose, use "GameFabric" (with capital F) to match the consistent capitalization used throughout the documentation.
| value = aws_iam_role.gamefabric_operators.arn | ||
| The account ID `339712714940` belongs to the Gamefabric organization. | ||
|
|
||
| In the role creation wizard, skip the permissions step during role creation. You attach custom policies in a later step. Name the role `gamefabric-operators`, and optionally add a description and tags for adding metadata, for example noting the purpose of the role and being linked to GameFabric. |
There was a problem hiding this comment.
Minor documentation flow issue. The text on line 169 states "Name the role gamefabric-operators" but this instruction should come after explaining what to do during the role creation wizard. Consider reordering to say "In the role creation wizard, skip the permissions step. Name the role gamefabric-operators, and optionally add a description and tags..." for better logical flow.
|
|
||
| In the role creation wizard, skip the permissions step during role creation. You attach custom policies in a later step. Name the role `gamefabric-operators`, and optionally add a description and tags for adding metadata, for example noting the purpose of the role and being linked to GameFabric. | ||
|
|
||
| Next, create one or more policies for the required permissions. The below policies state the required permissions explicitly for all the AWS services. AWS restricts the size of these documents to 4KB per document. Adding all the permissions into one policy exceeds the limit for a single policy. We split them up logically such that they are grouped broadly by the resource types they grant access to. |
There was a problem hiding this comment.
The sentence structure could be clearer. The phrase "The below policies state the required permissions explicitly for all the AWS services" could be more concise and direct. Consider: "The following policies explicitly list required permissions for all AWS services."
| You may take steps to add constraints and permission boundaries, but note that this can impact our ability to provision, maintain, or deprovision your cloud clusters. | ||
| ::: | ||
|
|
||
| After creating the policies, attach them to the created role. Go to the Role you created, choose the `Permissions` tab and click on `Add permissions > Attach policies`. Select the Policies you just created, and confirm with `Add permissions`. |
There was a problem hiding this comment.
The instructions could be more concise and clearer. Consider rephrasing to: "After creating the policies, attach them to the role. Navigate to the Role, select the Permissions tab, click Add permissions > Attach policies, select your newly created policies, and confirm." This follows the guideline to use clear, direct language and present tense.
1 participant
refines the AWS BYOC guide to include policies in JSON format for customers onboarding without terraform.