Skip to content

docs: keep the RGW placement contract in HACKING.md for now - #892

Open
johnramsden wants to merge 2 commits into
rgw-stack/11-robot-multivmfrom
rgw-stack/12-hacking
Open

johnramsden wants to merge 2 commits into
rgw-stack/11-robot-multivmfrom
rgw-stack/12-hacking

Conversation

@johnramsden

@johnramsden johnramsden commented Sep 23, 2026 •

Copy link
Copy Markdown
Member

Description

RGW placement is still being built, so a published reference page would describe an API that can still change underneath it. The standing rules go where developers look instead: a new "RGW placement (in development)" section at the end of HACKING.md, which is not part of the Sphinx build under docs/ and so carries no promise of stability to an external reader.

The section documents the rgw object's fields with an example policy, the rules that hold today and what a PUT returns for RGW, the three on-member files (radosgw.conf, radosgw.conf.pending, rgw-tls/<hash>/), the upgrade limitation for a policy stored while rgw was still a boolean, and where the code lives.

Stack: PR 12 of 13. Merge in order. Each PR is one logical change on top of the one before it.

  1. feat(db): add a table for each member's last applied RGW frontend #881 feat(db): add a table for each member's last applied RGW frontend
  2. fix(services): keep error classes through the service enable path #882 fix(services): keep error classes through the service enable path
  3. feat(api): describe an RGW placement as an object with explicit TLS intent #883 feat(api): describe an RGW placement as an object with explicit TLS intent
  4. feat(rgw): make the member-side RGW apply safe to repeat #884 feat(rgw): make the member-side RGW apply safe to repeat
  5. feat(rgw): wait until the gateway really serves the requested frontend #885 feat(rgw): wait until the gateway really serves the requested frontend
  6. feat(rgw): reuse the member's own pair when TLS is asked for without one #886 feat(rgw): reuse the member's own pair when TLS is asked for without one
  7. fix(rgw): make RGW disable converge when repeated or interrupted #887 fix(rgw): make RGW disable converge when repeated or interrupted
  8. feat(placement): accept the RGW object in the policy and keep its secrets out #888 feat(placement): accept the RGW object in the policy and keep its secrets out
  9. feat(placement): reconcile RGW across the cluster #889 feat(placement): reconcile RGW across the cluster
  10. test(robot): add the single-VM RGW placement suite #890 test(robot): add the single-VM RGW placement suite
  11. test(robot): add the three-VM RGW placement suite #891 test(robot): add the three-VM RGW placement suite
  12. docs: keep the RGW placement contract in HACKING.md for now #892 docs: keep the RGW placement contract in HACKING.md for now (this PR)
  13. fix(rgw): do not trust a pending-apply marker the operator completed by hand #893 fix(rgw): do not trust a pending-apply marker the operator completed by hand

Type of change

  • Documentation update (change to documentation only)

How has this been tested?

Documentation only. Every statement was checked against the code in this stack.

Contributor checklist

Please check that you have:

  • self-reviewed the code in this PR
  • added code comments, particularly in less straightforward areas (not applicable, documentation only)
  • checked and added or updated relevant documentation (this PR is the documentation)
  • checked and added or updated relevant release notes
  • added tests to verify effectiveness of this change (not applicable, documentation only)

@johnramsden
johnramsden added this pull request to stack #894 September 23, 2026 04:20
@johnramsden johnramsden changed the title rgw stack/12 hacking docs: keep the RGW placement contract in HACKING.md for now Sep 23, 2026
@johnramsden
johnramsden marked this pull request as ready for review September 23, 2026 04:31
@johnramsden
johnramsden marked this pull request as draft September 23, 2026 06:12
@johnramsden
johnramsden marked this pull request as ready for review September 25, 2026 23:06
@johnramsden
johnramsden force-pushed the rgw-stack/12-hacking branch 2 times, most recently from 686beaa to d36c52c Compare October 2, 2026 04:08
@johnramsden
johnramsden force-pushed the rgw-stack/12-hacking branch from d36c52c to b227b7b Compare October 6, 2026 00:47
RGW placement is still being built, so a published reference page would describe an API that can still change underneath it. The standing rules go where developers look instead: a new "RGW placement (in development)" section at the end of HACKING.md, which is not part of the Sphinx build under docs/ and so carries no promise of stability to an external reader.

The section documents the rgw object's fields with an example policy, the rules that hold today and what a PUT returns for RGW, the three on-member files (radosgw.conf, radosgw.conf.pending, rgw-tls/<hash>/), the upgrade limitation for a policy stored while rgw was still a boolean, and where the code lives.

Assisted-by: claude-code:claude-fable-5-1
Assisted-by: pi:gpt-6-astra
Signed-off-by: John Ramsden <john.ramsden@canonical.com>
Assisted-by: omp:openrouter/openai/gpt-6-astra
Signed-off-by: John Ramsden <john.ramsden@canonical.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants