Add documentation around resource pools on object templates.#8581
Add documentation around resource pools on object templates.#8581FragmentedPacket wants to merge 5 commits intorelease-1.8from
Conversation
WalkthroughDocumentation adds an "Allocating resources from pools via templates" feature: describes extending InfraInterface with 🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 📝 Coding Plan
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 Tip CodeRabbit can scan for known vulnerabilities in your dependencies using OSV Scanner.OSV Scanner will automatically detect and report security vulnerabilities in your project's dependencies. No additional configuration is required. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/docs/guides/object-template.mdx`:
- Around line 545-557: The object-file tab stops at the YAML example and needs
the final load step; after the YAML for the Object (spec.kind:
TemplateInfraInterface, template_name: "Template-SwitchModel123-Ethernet1") add
a sentence and the corresponding infrahubctl CLI invocation (infrahubctl object
load <path-to-file> --namespace <ns> or similar as used in the pool-creation
tab) so readers can execute the object-file workflow end-to-end; mirror the
style and flags used in the pool-creation tab to keep consistency.
- Around line 517-526: The instructions are ambiguous about scope: update the
text around the "IP Address" field steps (which reference
Template-SwitchModel123-Ethernet1 and the "Allocated by pool" badge) to clarify
that allocating from "Interface IP Pool" only applies to the specific template
you edit and therefore must be repeated for each interface template you want to
auto-allocate, or alternatively change the closing claim (Lines 577–579) to say
"each configured template you update will receive an address" instead of
implying all generated interfaces are covered automatically; make the change
either by adding a brief sentence after step 5 instructing the user to repeat
for other interface templates or by narrowing the closing paragraph's wording so
the scope is accurate.
- Line 343: The term "IPAM" is used without definition; update the first
occurrence in the sentence "Add the two IPAM nodes and an `ip_address`
relationship to `InfraInterface`" to spell out the acronym as "IP address
management (IPAM)" so readers see the full term on first use; keep the rest of
the sentence unchanged and ensure subsequent mentions remain as "IPAM".
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: d8dd2d94-fcc2-4fde-97e9-43df541ab86c
📒 Files selected for processing (1)
docs/docs/guides/object-template.mdx
docs/docs/guides/object-template.mdx
Outdated
|
|
||
| ### Update the schema | ||
|
|
||
| Add the two IPAM nodes and an `ip_address` relationship to `InfraInterface`: |
There was a problem hiding this comment.
Define IPAM on first mention.
Spell this out as IP address management (IPAM) the first time it appears so the section is self-contained for readers who are new to the term. As per coding guidelines, define technical terms on first use in documentation.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/docs/guides/object-template.mdx` at line 343, The term "IPAM" is used
without definition; update the first occurrence in the sentence "Add the two
IPAM nodes and an `ip_address` relationship to `InfraInterface`" to spell out
the acronym as "IP address management (IPAM)" so readers see the full term on
first use; keep the rest of the sentence unchanged and ensure subsequent
mentions remain as "IPAM".
| With the pool created, update the interface template from the previous section to allocate an IP address from it whenever a new interface is created. | ||
|
|
||
| <Tabs groupId="method" queryString> | ||
| <TabItem value="web" label="Via the Web Interface" default> | ||
|
|
||
| 1. Navigate to `Object Management` > `Templates` | ||
| 2. Open `Template-SwitchModel123-Ethernet1` (or any interface template) | ||
| 3. On the `IP Address` field, click the pool selector button and choose `Interface IP Pool` | ||
| 4. The field will show an `Allocated by pool` badge | ||
| 5. Save |
There was a problem hiding this comment.
Clarify whether allocation applies to one interface or all configured templates.
These steps tell the reader to update a single interface template, but the closing paragraph says every generated interface gets an address. As written, a reader who only updates Template-SwitchModel123-Ethernet1 will only see allocation on that configured template. Please either instruct them to repeat the step for each interface template or narrow the claim in Lines 577-579.
✍️ Suggested wording
- With the pool created, update the interface template from the previous section to allocate an IP address from it whenever a new interface is created.
+ With the pool created, update each interface template that should allocate an IP address from the pool when a new interface is created.
- 2. Open `Template-SwitchModel123-Ethernet1` (or any interface template)
+ 2. Open each interface template that should receive an allocated address, starting with `Template-SwitchModel123-Ethernet1`
- Creating a device from the template works exactly as described in the [Create object instances](`#create-object-instances-using-the-predefined-template`) section above. No additional steps are required — when the device is saved, Infrahub allocates an available IP address from `Interface IP Pool` and assigns it to each interface's `ip_address` field.
+ Creating a device from the template works exactly as described in the [Create object instances](`#create-object-instances-using-the-predefined-template`) section above. No additional steps are required — when the device is saved, Infrahub allocates an available IP address from `Interface IP Pool` for each interface template configured with `ip_address_from_resource_pool`.Also applies to: 577-579
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/docs/guides/object-template.mdx` around lines 517 - 526, The
instructions are ambiguous about scope: update the text around the "IP Address"
field steps (which reference Template-SwitchModel123-Ethernet1 and the
"Allocated by pool" badge) to clarify that allocating from "Interface IP Pool"
only applies to the specific template you edit and therefore must be repeated
for each interface template you want to auto-allocate, or alternatively change
the closing claim (Lines 577–579) to say "each configured template you update
will receive an address" instead of implying all generated interfaces are
covered automatically; make the change either by adding a brief sentence after
step 5 instructing the user to repeat for other interface templates or by
narrowing the closing paragraph's wording so the scope is accurate.
| <TabItem value="object-file" label="Via an Object File"> | ||
|
|
||
| ```yaml | ||
| --- | ||
| apiVersion: infrahub.app/v1 | ||
| kind: Object | ||
| spec: | ||
| kind: TemplateInfraInterface | ||
| data: | ||
| - template_name: "Template-SwitchModel123-Ethernet1" | ||
| device: "Template-SwitchModel123" | ||
| ip_address_from_resource_pool: "Interface IP Pool" | ||
| ``` |
There was a problem hiding this comment.
Finish the object-file path with the load step.
This tab stops at the YAML example, so the object-file workflow is not fully executable end to end. Please add the infrahubctl object load ... step here, like you did in the pool-creation tab above.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/docs/guides/object-template.mdx` around lines 545 - 557, The object-file
tab stops at the YAML example and needs the final load step; after the YAML for
the Object (spec.kind: TemplateInfraInterface, template_name:
"Template-SwitchModel123-Ethernet1") add a sentence and the corresponding
infrahubctl CLI invocation (infrahubctl object load <path-to-file> --namespace
<ns> or similar as used in the pool-creation tab) so readers can execute the
object-file workflow end-to-end; mirror the style and flags used in the
pool-creation tab to keep consistency.
github-actions
bot
added
the
type/documentation
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/docs/topics/object-template.mdx (1)
40-40: Consider using active voice.The phrase "is all that is needed" uses passive voice. Per documentation guidelines, prefer active voice.
📝 Suggested wording
-When a schema node has a relationship or attribute whose peer type supports resource pool allocation (for example, a relationship to an IP address node, or a number attribute backed by a number pool), Infrahub automatically generates a `<attribute_or_relationship_name>_from_resource_pool` field on the corresponding template node. Assigning a pool to that field is all that is needed — no changes to object creation are required. +When a schema node has a relationship or attribute whose peer type supports resource pool allocation (for example, a relationship to an IP address node, or a number attribute backed by a number pool), Infrahub automatically generates a `<attribute_or_relationship_name>_from_resource_pool` field on the corresponding template node. Assigning a pool to that field is all you need — no changes to object creation are required.As per coding guidelines: "Use active voice in documentation (e.g., 'Create a branch' not 'A branch can be created')".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/docs/topics/object-template.mdx` at line 40, Rewrite the passive sentence "Assigning a pool to that field is all that is needed" into active voice; update the sentence that follows the mention of the generated field "<attribute_or_relationship_name>_from_resource_pool" to something like "Assign the pool to that field; you don't need to change object creation" so it reads actively and keeps the meaning.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/docs/topics/object-template.mdx`:
- Line 40: Rewrite the passive sentence "Assigning a pool to that field is all
that is needed" into active voice; update the sentence that follows the mention
of the generated field "<attribute_or_relationship_name>_from_resource_pool" to
something like "Assign the pool to that field; you don't need to change object
creation" so it reads actively and keeps the meaning.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 8117c0fb-ac98-420a-b2ea-452b03fdd1af
📒 Files selected for processing (1)
docs/docs/topics/object-template.mdx
| name: {value: "Interface IP Pool"} | ||
| default_address_type: {value: "IpamIPAddress"} | ||
| ip_namespace: {hfid: ["default"]} | ||
| resources: [{id: $prefixId}] |
There was a problem hiding this comment.
wonder if we can't use prefix HFID here (haven't tried tho):
| resources: [{id: $prefixId}] | |
| resources: [["192.168.0.0/16", "default"]] |
There was a problem hiding this comment.
This does not work:
mutation CreatePrefix {
IpamIPPrefixCreate(
data: {
prefix: {value: "192.168.0.0/16"}
member_type: {value: "address"}
is_pool: {value: true}
}
) {
ok
object {
id
}
}
}
{
"data": null,
"errors": [
{
"message": "Expected value of type 'RelatedIPPrefixNodeInput', found [\"192.168.0.0/16\", \"default\"].",
"locations": [
{
"line": 52,
"column": 19
}
]
}
]
}
Tried with HFID, but the BuiltinIPPrefix does not have an HFID defined.
mutation CreatePool {
CoreIPAddressPoolCreate(
data: {
name: {value: "Interface IP Pool"}
default_address_type: {value: "IpamIPAddress"}
ip_namespace: {hfid: ["default"]}
resources: {hfid: ["192.168.0.0/16", "default"]}
}
) {
ok
}
}
{
"data": {
"CoreIPAddressPoolCreate": null
},
"errors": [
{
"message": "Unable to lookup node by HFID, schema 'BuiltinIPPrefix' does not have a HFID defined.",
"locations": [
{
"line": 47,
"column": 3
}
],
"path": [
"CoreIPAddressPoolCreate"
]
}
]
}
| - name__value | ||
| uniqueness_constraints: | ||
| - ["device", "name__value"] | ||
| human_friendly_id: ["device__name__value", "name__value"] |
There was a problem hiding this comment.
I think you need generate_template: true on this schema
There was a problem hiding this comment.
It's a component relationship on device so that gets created automatically. We're building on the schema at the start of the guide, but maybe I just add the full schemas into this one as well?
docs/docs/topics/object-template.mdx
Outdated
|
|
||
| ### How it works | ||
|
|
||
| When a schema node has a relationship or attribute whose peer type supports resource pool allocation (for example, a relationship to an IP address node, or a number attribute backed by a number pool), Infrahub automatically generates a `<attribute_or_relationship_name>_from_resource_pool` field on the corresponding template node. Assigning a pool to that field is all that is needed — no changes to object creation are required. |
There was a problem hiding this comment.
number attribute backed by a number pool -> number attribute
the number attribute can't be backed by a pool before the pool is linked to the template
There was a problem hiding this comment.
I'm not sure I understand this. Should I omit the backed by a number pool?
There was a problem hiding this comment.
yes that's what I think
because the number won't be backed by a pool until the pool is linked to the template right? not a big deal either way
There was a problem hiding this comment.
Ahh ok, I think I understand. The pool would be tied to the model/attribute, independent of the template, but that pool must exist before it can be tied to an object template.
Sorry I think this a good convo for understanding lol
There was a problem hiding this comment.
I don't think there's an example in here for using NumberPools on an attribute in a template, which would probably be helpful. I don't know if it needs to be a full example, but it is unexpected that you have to use a relationship to specify a pool for an attribute
There was a problem hiding this comment.
I think from a user perspective, it should be the same and that seems like an implementation detail that we'd be discussing in the guide? We can potentially discuss this in the topic.
| ## Allocating resources from pools via templates | ||
|
|
||
| Object templates support automatic resource allocation. This section extends the device and interface schema from above by adding IP address support to `InfraInterface`, then shows how to wire a `CoreIPAddressPool` to the interface template. | ||
|
|
There was a problem hiding this comment.
I'd add a link to the related topic section here, Like "if you want to know more about xyz"
There was a problem hiding this comment.
This is documented at the bottom of the guide to learn more about resource managers. Do you want me to move that up to here?
|
|
||
| For more details, see the [Creating and assigning Profiles guide](../guides/profiles.mdx). | ||
|
|
||
| ## Integration with Resource Pools |
There was a problem hiding this comment.
Do we have any precise use case in mind for that integration, e.g. management interface IP if all device using this template are sharing the same prefix. On that perhaps it's worth mentioning when not using it, if for instance I need to use different pool based on the site I can't put this in the template.
There was a problem hiding this comment.
Let me think about this.
Co-authored-by: Baptiste <32564248+BaptisteGi@users.noreply.github.com>
There was a problem hiding this comment.
♻️ Duplicate comments (3)
docs/docs/guides/object-template.mdx (3)
545-559:⚠️ Potential issue | 🟡 MinorFinish the object-file path with the load command.
This tab stops at the YAML example, so the object-file workflow is not executable end to end. Add the corresponding
infrahubctl object load ...step after the example, like the pool-creation tab does.✍️ Suggested wording
- Load with:
infrahubctl object load <path-to-file></details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/docs/guides/object-template.mdxaround lines 545 - 559, The
"object-file" TabItem in docs/guides/object-template.mdx ends the YAML example
without the final load step; add the CLI instruction to complete the workflow by
appending a line after the YAML showing how to run infrahubctl object load
(e.g., "Load with: infrahubctl object load ") so
readers can execute the object-file path end-to-end.</details> --- `343-343`: _⚠️ Potential issue_ | _🟡 Minor_ **Define `IPAM` on first mention.** Spell this out as `IP address management (IPAM)` here so the section is self-contained for readers who are new to the term. As per coding guidelines, "Define technical terms on first use in documentation". <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/docs/guides/object-template.mdxat line 343, Update the first
occurrence of the acronym "IPAM" in the sentence that reads "Add the two IPAM
nodes and anip_addressrelationship toInfraInterface..." to spell it out
as "IP address management (IPAM)" so the section is self-contained for new
readers; keep the rest of the sentence intact and retain the references to
InfraInterfaceand theip_addressrelationship.</details> --- `517-526`: _⚠️ Potential issue_ | _🟠 Major_ **Clarify which interface templates actually receive allocated addresses.** These steps update one interface template, but Line 579 reads as if every generated interface is covered automatically. Either tell readers to repeat this for each interface template they want to auto-allocate, or narrow the closing sentence to only templates configured with `ip_address_from_resource_pool`. <details> <summary>✍️ Suggested wording</summary> ```diff - With the pool created, update the interface template from the previous section to allocate an IP address from it whenever a new interface is created. + With the pool created, update each interface template that should allocate an IP address from the pool when a new interface is created. - 2. Open `Template-SwitchModel123-Ethernet1` (or any interface template) + 2. Open each interface template that should receive an allocated address, starting with `Template-SwitchModel123-Ethernet1` - Creating a device from the template works exactly as described in the [Create object instances](`#create-object-instances-using-the-predefined-template`) section above. No additional steps are required — when the device is saved, Infrahub allocates an available IP address from `Interface IP Pool` and assigns it to each interface's `ip_address` field. + Creating a device from the template works exactly as described in the [Create object instances](`#create-object-instances-using-the-predefined-template`) section above. No additional steps are required — when the device is saved, Infrahub allocates an available IP address from `Interface IP Pool` for each interface template configured with `ip_address_from_resource_pool`.Also applies to: 577-579
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/docs/guides/object-template.mdx` around lines 517 - 526, The doc currently implies all generated interfaces will get pool addresses; clarify that only interface templates where the "IP Address" field is set to use the "Interface IP Pool" (i.e., configured with ip_address_from_resource_pool) will receive allocated addresses—either add an explicit instruction to repeat the steps for each interface template you want auto-allocation for (referencing Template-SwitchModel123-Ethernet1 and the "Interface IP Pool" selector) or change the closing sentence to state that only templates configured with ip_address_from_resource_pool will auto-allocate addresses.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@docs/docs/guides/object-template.mdx`:
- Around line 545-559: The "object-file" TabItem in
docs/guides/object-template.mdx ends the YAML example without the final load
step; add the CLI instruction to complete the workflow by appending a line after
the YAML showing how to run infrahubctl object load <path-to-file> (e.g., "Load
with: infrahubctl object load <path-to-file>") so readers can execute the
object-file path end-to-end.
- Line 343: Update the first occurrence of the acronym "IPAM" in the sentence
that reads "Add the two IPAM nodes and an `ip_address` relationship to
`InfraInterface`..." to spell it out as "IP address management (IPAM)" so the
section is self-contained for new readers; keep the rest of the sentence intact
and retain the references to `InfraInterface` and the `ip_address` relationship.
- Around line 517-526: The doc currently implies all generated interfaces will
get pool addresses; clarify that only interface templates where the "IP Address"
field is set to use the "Interface IP Pool" (i.e., configured with
ip_address_from_resource_pool) will receive allocated addresses—either add an
explicit instruction to repeat the steps for each interface template you want
auto-allocation for (referencing Template-SwitchModel123-Ethernet1 and the
"Interface IP Pool" selector) or change the closing sentence to state that only
templates configured with ip_address_from_resource_pool will auto-allocate
addresses.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: df844abd-4f57-43f8-8b42-513d57c169af
📒 Files selected for processing (2)
docs/docs/guides/object-template.mdxdocs/docs/topics/object-template.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/docs/topics/object-template.mdx
3 participants
Why
Documents the ability to add resource pools to object templates.
Checklist
uv run towncrier create ...)Summary by CodeRabbit