Skip to content

docs(compute-envs): make IAM policies downloadable and source from JSON files#1434

Merged
justinegeffen merged 10 commits into
masterfrom
docs-cloud-policy-downloadable
May 21, 2026
Merged

docs(compute-envs): make IAM policies downloadable and source from JSON files#1434
justinegeffen merged 10 commits into
masterfrom
docs-cloud-policy-downloadable

Conversation

@gavinelder
Copy link
Copy Markdown
Contributor

@gavinelder gavinelder commented May 18, 2026

Summary

Refactors the inline IAM policy <details> blocks on the AWS compute environment pages (platform-cloud) so they are:

  • Sourced from a single canonical JSON file per policy (no more 200-line JSON snippets pasted into Markdown).
  • Downloadable — each block now has a Download <name>.json link next to the rendered code, served by Docusaurus as a fingerprinted asset.
  • Always in sync — the expanded code block and the download link both come from the same file, so they can't drift.

Pages migrated

Page Policies extracted
compute-envs/aws-batch.mdx (was .md) Full permissive policy
compute-envs/eks.mdx (was .md) Full permissive policy
compute-envs/aws-cloud.mdx (was .md) Full permissive policy + Seqera Intelligent Compute policy

New JSON sources live under platform-cloud/docs/compute-envs/_policies/. The _ prefix keeps Docusaurus from treating them as standalone pages.

Drive-by fix

The Seqera Intelligent Compute policy in aws-cloud.md had a duplicate "Action": [ line (previously L526-527), making the JSON invalid. The downloadable version is now valid — and tabs are normalized to spaces.

How it works

Rspack's built-in ?raw import bypasses the JSON parser and gives us the file contents as a string:

import AwsBatchFullPolicy from './_policies/aws-batch-full-policy.json?raw';

<details>
<summary>Full permissive policy (for reference)</summary>

<CodeBlock language="json">{AwsBatchFullPolicy}</CodeBlock>

[Download aws-batch-full-policy.json](./_policies/aws-batch-full-policy.json)
</details>

Note: The existing repo pattern (!!raw-loader!./file.yaml in seqerakit/templates.mdx) doesn't work for .json because Rspack's built-in JSON parser intercepts first. ?raw is the working pattern for JSON.

Out of scope (intentional)

  • The parallel pages in platform-enterprise_docs/compute-envs/ (aws-batch.md, eks.md, aws-cloud.md) still use the old inline-JSON pattern. They have the same broken SIC JSON. Will follow up in a separate PR.
  • gke.md's <details> block is shell commands + prose, not a JSON policy — left alone.
  • Versioned enterprise docs (platform-enterprise_versioned_docs/version-25.3/...) are frozen, untouched.

Test plan

  • yarn build succeeds, no new warnings introduced.
  • All 4 JSON files parse with python3 -m json.tool.
  • Built HTML for /platform-cloud/compute-envs/aws-batch/, /eks/, and /aws-cloud/ contains the expanded JSON content plus a fingerprinted asset URL (/assets/files/<name>-<hash>.json).
  • Netlify preview: open each of the three pages, expand the <details> block, verify rendered JSON matches and the download link returns a valid .json file.
  • Spot-check that nothing else in the docs deep-links to compute-envs/aws-batch.md/eks.md/aws-cloud.md with the .md extension (resource-labels was the only known offender and is fixed here).

🤖 Generated with Claude Code

…ON files

Extract the inline "Full permissive policy" JSON blocks on the AWS Batch, EKS,
and AWS Cloud compute environment pages (platform-cloud) into co-located
.json files imported via Rspack's `?raw` query. Each <details> block now
renders from the same file that users can download, eliminating drift between
the rendered example and any copy-paste artifact.

Also fixes a pre-existing copy-paste error in the Seqera Intelligent Compute
policy where line 526-527 of aws-cloud.md had a duplicate `"Action": [` line,
making the JSON invalid. Normalized tabs to spaces in the same policy.

Drops the .md extension on internal links to the renamed pages from
resource-labels/overview.md (the .md extension would now mis-resolve).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@netlify
Copy link
Copy Markdown

netlify Bot commented May 18, 2026

Deploy Preview for seqera-docs ready!

Name Link
🔨 Latest commit 0804049
🔍 Latest deploy log https://app.netlify.com/projects/seqera-docs/deploys/6a0f42d179d23400085ae437
😎 Deploy Preview https://deploy-preview-1434--seqera-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

…ocks

Surface the download as a sibling of the collapsible rather than hiding it
inside the expanded section, so users can grab the JSON without expanding.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@gavinelder gavinelder marked this pull request as ready for review May 18, 2026 16:33
@justinegeffen justinegeffen added 1. Editor review Needs a language review 1. Dev/PM/SME Needs a review by a Dev/PM/SME labels May 18, 2026
Copy link
Copy Markdown
Member

@bebosudo bebosudo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I restarted the netlify deployment which ran out of memory on the first try.
The change looks good to me: https://deploy-preview-1434--seqera-docs.netlify.app/platform-cloud/compute-envs/aws-batch#required-platform-iam-permissions

@MichaelTansiniSeqera
Copy link
Copy Markdown
Contributor

Nice.

Could we rename the section to something like 'Example IAM Policies' for clarity?

Also as Intelligent Compute is not yet released, can we exclude it from the release or hide it? @justinegeffen

@gavinelder
Copy link
Copy Markdown
Contributor Author

@MichaelTansiniSeqera there was a discussion around Intelligent compute and the decision was to include it with an Alpha / Early Access preview admonition and to speak to an account manager around interest.

Will see how "Default / Example Iam works"

@christopher-hakkaart
Copy link
Copy Markdown
Member

fix formatting

@justinegeffen
Copy link
Copy Markdown
Contributor

@copilot resolve the merge conflicts in this pull request

…ownloadable

# Conflicts:
#	platform-cloud/docs/compute-envs/aws-cloud.mdx

Co-authored-by: justinegeffen <4223530+justinegeffen@users.noreply.github.com>
Copy link
Copy Markdown
Contributor

Copilot AI commented May 21, 2026

@copilot resolve the merge conflicts in this pull request

Merge conflicts resolved in commit 0804049. The conflict was in aws-cloud.mdxorigin/master had a fix (2eb2dd30) removing a duplicate "Action": [ line from the inline JSON, while our branch had already extracted that policy to _policies/aws-cloud-intelligent-compute-policy.json (without the duplicate) using the <CodeBlock> approach. Kept our version.

Copilot AI requested a review from justinegeffen May 21, 2026 17:37
@justinegeffen justinegeffen merged commit f8f062a into master May 21, 2026
5 of 7 checks passed
@justinegeffen justinegeffen deleted the docs-cloud-policy-downloadable branch May 21, 2026 17:46
@justinegeffen
Copy link
Copy Markdown
Contributor

@gavinelder, I've merged this but wanted to check if we should replicate the changes in the enterprise docs?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

1. Dev/PM/SME Needs a review by a Dev/PM/SME 1. Editor review Needs a language review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants