docs: add a CLI user guide and fix the stale API reference#68
Open
scotwells wants to merge 5 commits into
Open
docs: add a CLI user guide and fix the stale API reference#68scotwells wants to merge 5 commits into
scotwells wants to merge 5 commits into
Conversation
Adds a task-oriented guide for people using the IPAM service from the command line, and corrects reference docs that described an old resource model the service never shipped. - docs/guides/ — new home for user-facing guides, with an index that lists the CLI guide and the topics we plan to add next. - docs/guides/managing-ip-address-space.md — install the datumctl ipam plugin, understand pools/claims/allocations, and run the common workflows (create pools, claim/inspect/release prefixes, scripting and exit codes, troubleshooting). - docs/api.md — rewritten to the shipped API: IPPool, IPClaim, and IPAllocation. The previous version documented IPPrefix/IPPrefixClaim/ IPAddress/ASN* kinds that the service does not serve. - CLAUDE.md — corrected the registry layout line to the actual ippool/ipclaim/ipallocation directories.
The install step jumped straight to installing the plugin, but the IPAM plugin lives in the milo-os catalog, not datumctl's built-in datum catalog. Add the 'datumctl plugin index add milo-os milo-os/cli-plugins' step (with the trust prompt) and install by name, and note the direct install-from-release alternative and its trade-offs.
The guides index and CLI guide linked to sibling docs by their file path (e.g. `../api.md`). Use human-readable link text that says where the link goes.
Convert the two plain blockquote callouts in the CLI guide to GitHub alert syntax ([!NOTE], [!TIP]) so they render as styled callouts.
slindseysr
previously approved these changes
Jul 2, 2026
The registry-layout line was already corrected; this finishes the pass. Remove references to resources and fields the service doesn't implement (ASN allocation, IPAddress/IPPrefix kinds, childPrefixTemplate) and align the naming with what ships: IPPool, IPClaim, IPAllocation. - Service summary, sync-status bullet, and repo layout no longer claim ASN. - Allocation transaction sequence and AllocatingREST point at IPClaim (internal/registry/ipam/ipclaim) and drop the childPrefixTemplate branch. - ExtraConfig matches the code: PrefixAllocator + AllocatorPool + optional PoolChecker (no ASNAllocator). - Drop the 'atomic child prefix creation' design decision (renumbered). - Acceptance criteria reference IPClaim; drop the childPrefixTemplate item.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Gives users a task-oriented guide for managing IP space from the command line, and corrects a reference that described resources the service never shipped.
What this delivers
docs/guides/): install the plugin, understand pools/claims/allocations, and run the common workflows — create pools, claim/inspect/release prefixes, scripting, and troubleshooting.docs/api.md(and the CLAUDE.md layout) now describe the shippedIPPool/IPClaim/IPAllocationmodel instead of the oldIPPrefix/ASNkinds.Docs only.