Add comprehensive documentation for resource extension points #5004

Copilot · 2025-10-28T01:51:48Z

ASO v2 provides 9 extension interfaces for customizing resource behavior, but lacked documentation causing contributor friction. This adds ~3,700 lines of technical documentation covering all extension points.

Changes

New Documentation Structure

docs/hugo/content/contributing/extension-points/ folder with overview and 9 detailed guides
Each extension point documented with: interface definition, motivation, usage patterns, real examples, testing guidance
Cross-referenced with Hugo-compatible links

Extension Points Documented

ARMResourceModifier - Modify ARM payloads pre-submission (soft-delete, child resources)
Deleter - Multi-step deletion, pre-deletion operations
ErrorClassifier - Classify ARM errors as retryable/fatal
Importer - Filter resources during asoctl import
KubernetesSecretExporter - Export Azure secrets to Kubernetes
PostReconciliationChecker - Defer Ready condition until async operations complete
PreReconciliationChecker - Block reconciliation until prerequisites met
PreReconciliationOwnerChecker - Block reconciliation based on owner state without accessing resource
SuccessfulCreationHandler - One-time initialization post-creation

Note: Claimer was initially included but removed as it is an internal interface, not a contributor-facing extension point.

Code Enhancement

Enhanced interface comments in v2/pkg/genruntime/extensions/*.go to include usage guidance and problem statements inline.

Example

// Before: minimal comment
type ErrorClassifier interface {
    ClassifyError(...) (core.CloudErrorDetails, error)
}

// After: actionable guidance
// ErrorClassifier customizes how the reconciler reacts to Azure errors.
// Implement when:
// - Resource-specific error codes need special handling
// - Transient errors are misclassified as fatal
// - Error messages need resource-specific clarification
type ErrorClassifier interface {
    // ClassifyError evaluates errors, determining retry behavior.
    // cloudError: error from ARM
    // apiVersion: ARM API version used
    // next: default classification to chain
    ClassifyError(...) (core.CloudErrorDetails, error)
}

Each documentation page includes 5-6 implementation patterns with real codebase examples (KeyVault soft-delete, PrivateEndpoint approval, MySQL config filtering, Kusto cluster/database state blocking).

Fixes Add documentation of resource extension points #3902

Original prompt

This section details on the original issue you should resolve

<issue_title>Add documentation of resource extension points</issue_title>
<issue_description>Describe the current behavior

Currently we have little documentation of the various extension points available when adding a completely new resource. This lack of information has proven to be a hinderance for multiple contributors.

Describe the improvement

Add documentation describing the available extension points and when they should be used.

Overview of extensions and extension implementation patterns

Docs for ARMResourceModifier

Docs for Claimer

Docs for Deleter

Docs for ErrorClassifier

Docs for Importer

Docs for KubernetesExporter

Docs for PostReconciliationChecker

Docs for PostReconciliationChecker

Docs for SuccessfulCreationHandler

Copilot Instructions

Create a new documentation folder under docs/hugo/content/contributing/ called extension-points and create an _index.md file to act as a table of contents.

For each extension point identified above, write a separate documentation page to detail the purpose and use of the extension point.

Each documentation page should have the following sections:

Description - a description of what the extension point does, and when it's invoked

Motivation - details about why the extension point is needed. Most everything you need here is already documented in the code, either at the point of declaration for the interface, or when it's implemented.

When to use - guidance on when the extension point should be implemented. You'll need to harvest comments from PRs that implemented the extension points to find all the existing commentary on this.

Example - pick a representative example of use of the extension point, and provide the code with annotations.

If you find the code for an extension interface is lacking, but find the information elsewhere, update the comments on the code, but take extra care not to change the declaration itself.
Some of these interfaces are also lacking documentation in the code; this should be extended at the same time.
</issue_description>

Comments on the Issue (you are @copilot in this section)
@matthchr Would be nice to do this, but low pri

Fixes Add documentation of resource extension points #3902

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

- Created extension-points folder with overview - Documented ARMResourceModifier - Documented Claimer - Documented Deleter - Documented ErrorClassifier - Documented Importer Co-authored-by: theunrepentantgeek <[email protected]>

- Documented KubernetesSecretExporter - Documented PostReconciliationChecker - Documented PreReconciliationChecker - Documented SuccessfulCreationHandler Co-authored-by: theunrepentantgeek <[email protected]>

Updated interface documentation to provide more context about: - When each extension should be used - What problems each extension solves - Key parameters and return values Enhanced comments for: - ARMResourceModifier - Claimer - Deleter - ErrorClassifier - Importer - KubernetesSecretExporter - PostReconciliationChecker - PreReconciliationChecker - SuccessfulCreationHandler Co-authored-by: theunrepentantgeek <[email protected]>

Updated the contributing index page to link to the new extension points documentation. Co-authored-by: theunrepentantgeek <[email protected]>

theunrepentantgeek · 2025-10-28T02:21:16Z

@copilot Please add documentation for PreReconciliationOwnerChecker - this is a variant of PreReconciliationChecker that was omitted from the original request.

Added comprehensive documentation for PreReconciliationOwnerChecker, a specialized variant of PreReconciliationChecker that validates only the owner's state before reconciliation without accessing the resource itself. Key aspects: - Detailed explanation of when to use vs PreReconciliationChecker - Real-world example from Kusto Database (cluster state blocking) - Comparison table showing differences from PreReconciliationChecker - Common patterns for blocking based on owner state - Enhanced code comments in the interface definition This extension is critical for resources where the owner's state can completely block access to child resources (e.g., Kusto databases inaccessible when cluster is powered off). Co-authored-by: theunrepentantgeek <[email protected]>

Copilot · 2025-10-28T02:30:31Z

@copilot Please add documentation for PreReconciliationOwnerChecker - this is a variant of PreReconciliationChecker that was omitted from the original request.

Added documentation for PreReconciliationOwnerChecker in commit c04a5c3.

This extension is a specialized variant of PreReconciliationChecker that validates only the owner's state before reconciliation, without performing GET operations on the resource itself. It's used when the owner's state can completely block access to child resources (e.g., Kusto databases cannot be accessed when the cluster is powered off or updating).

The documentation includes:

Detailed comparison with PreReconciliationChecker
Real-world example from Kusto Database
Clear guidance on when to use each checker
Enhanced code comments in the interface definition

theunrepentantgeek

This is good, but there are a few things to tweak, @copilot. Please make the requested changes.

v2/pkg/genruntime/extensions/importer.go

docs/hugo/content/contributing/extension-points/_index.md

docs/hugo/content/contributing/extension-points/claimer.md

- Fixed comment grammar in importer.go (added "an") - Updated _index.md description to focus on compensating for resource variation - Changed "type assertion" to "type-check at the appropriate time" - Removed Claimer from extension points documentation and deleted claimer.md Claimer is not a contributor-facing extension point but an internal interface. Co-authored-by: theunrepentantgeek <[email protected]>

Copilot · 2025-10-29T00:32:28Z

This is good, but there are a few things to tweak, @copilot. Please make the requested changes.

All requested changes completed in commit df58f62:

Fixed comment grammar in importer.go
Updated _index.md description
Changed "type assertion" to "type-check at the appropriate time"
Removed Claimer documentation and deleted claimer.md file

matthchr · 2025-11-14T21:41:59Z

docs/hugo/content/contributing/extension-points/_index.md

+
+The following extension points are available for customizing resource behavior:
+
+| Extension Point | Purpose | When Invoked |


minor, style: maybe format this table to be more human readable in the raw markdown?

matthchr · 2025-11-14T21:42:58Z

docs/hugo/content/contributing/extension-points/_index.md

+
+1. **Keep extensions minimal**: Only add logic that cannot be handled by the generator
+2. **Document thoroughly**: Explain why the extension is needed
+3. **Type assert hub versions**: Include hub type assertions to catch breaking changes


May want an example?

matthchr · 2025-11-14T21:56:45Z

docs/hugo/content/contributing/extension-points/_index.md

+---
+title: Extension Points
+linktitle: Extension Points
+weight: 100


I thought lower weight is "higher" on the page. I guess this is the index so this weight is about where this lands compared to othher contributing docs?

So this is at the end?

Just confirming this is correct as it seemed a little surprising to me

matthchr · 2025-11-14T21:57:24Z

docs/hugo/content/contributing/extension-points/arm-resource-modifier.md

+
+The interface is invoked during PUT and PATCH operations to ARM, giving the resource an opportunity to make last-minute adjustments to the ARM payload based on runtime conditions, Azure state, or complex business logic that cannot be expressed in the generated code.
+
+## Interface Definition


Wondering if we should just link to the code here? Or directly embed the code via link (does Hugo support that? probably not).

Calling the exact structure + what the parameters mean out here just seems like writing an interface/function comment and I'd sorta rather have a single place where we document it well (ideally in the code) and then reference that place from the docs?

We'd still keep the "when to use", motivation, examples, etc here.

matthchr · 2025-11-14T21:59:22Z

docs/hugo/content/contributing/extension-points/arm-resource-modifier.md

+
+The Key Vault resource uses `ARMResourceModifier` to handle different creation modes based on whether a soft-deleted vault exists:
+
+```go


Another place where we should maybe link to the example code rather than duplicate it here?

matthchr · 2025-11-14T22:01:28Z

docs/hugo/content/contributing/extension-points/deleter.md

+5. **Test conditional paths**: Cover all branching logic
+6. **Test requeue behavior**: Verify multi-step deletions requeue correctly
+
+Example test structure:


Not sure we need to see an example test structure here? Seems a bit overkill for the docs.

matthchr · 2025-11-14T22:02:14Z

docs/hugo/content/contributing/extension-points/error-classifier.md

+}
+```
+
+### Pattern 5: Multiple Error Conditions


This isn't really a separate pattern this is just pattern 1 again, isn't it?

matthchr · 2025-11-14T22:02:31Z

docs/hugo/content/contributing/extension-points/error-classifier.md

+4. **Test error message enhancement**: Verify improved user messages
+5. **Test classification changes**: Assert correct classification results
+
+Example test structure:


Same comment, IMO overkill

matthchr · 2025-11-14T22:03:41Z

docs/hugo/content/contributing/extension-points/importer.md

+Example test structure:
+
+```go
+func TestFlexibleServersConfigurationExtension_Import(t *testing.T) {


matthchr · 2025-11-14T22:11:38Z

docs/hugo/content/contributing/extension-points/importer.md

+}
+```
+
+Example test implementation:


again seems overkill -- link to an existing test at most?

Initial plan

27da1cb

Copilot AI assigned Copilot and theunrepentantgeek Oct 28, 2025

github-project-automation bot added this to Azure Service Operator Roadmap Oct 28, 2025

github-project-automation bot moved this to In Progress in Azure Service Operator Roadmap Oct 28, 2025

Copilot started work on behalf of theunrepentantgeek October 28, 2025 01:52 View session

Copilot AI and others added 4 commits October 28, 2025 02:06

Add documentation for 5 extension points

eee496c

- Created extension-points folder with overview - Documented ARMResourceModifier - Documented Claimer - Documented Deleter - Documented ErrorClassifier - Documented Importer Co-authored-by: theunrepentantgeek <[email protected]>

Add documentation for remaining extension points

5a324d2

- Documented KubernetesSecretExporter - Documented PostReconciliationChecker - Documented PreReconciliationChecker - Documented SuccessfulCreationHandler Co-authored-by: theunrepentantgeek <[email protected]>

Add extension points to contributing index

4a619aa

Updated the contributing index page to link to the new extension points documentation. Co-authored-by: theunrepentantgeek <[email protected]>

Copilot AI changed the title ~~[WIP] Add documentation of resource extension points~~ Add comprehensive documentation for resource extension points Oct 28, 2025

Copilot AI requested a review from theunrepentantgeek October 28, 2025 02:20

Copilot finished work on behalf of theunrepentantgeek October 28, 2025 02:20

Copilot started work on behalf of theunrepentantgeek October 28, 2025 02:21 View session

Copilot finished work on behalf of theunrepentantgeek October 28, 2025 02:31

theunrepentantgeek reviewed Oct 29, 2025

View reviewed changes

Copilot started work on behalf of theunrepentantgeek October 29, 2025 00:24 View session

Copilot AI requested a review from theunrepentantgeek October 29, 2025 00:33

Copilot finished work on behalf of theunrepentantgeek October 29, 2025 00:33

theunrepentantgeek marked this pull request as ready for review October 29, 2025 00:41

theunrepentantgeek requested review from davefellows, jakjang, juan-lee and matthchr as code owners October 29, 2025 00:41

Fix links

3583cf2

theunrepentantgeek added 3 commits November 13, 2025 03:11

Merge branch 'main' into copilot/add-docs-for-extension-points

e06e9e9

Merge branch 'main' into copilot/add-docs-for-extension-points

c8af1ad

Remove broken link

acb7acd

matthchr reviewed Nov 14, 2025

View reviewed changes


		The following extension points are available for customizing resource behavior:

		\| Extension Point \| Purpose \| When Invoked \|


		The interface is invoked during PUT and PATCH operations to ARM, giving the resource an opportunity to make last-minute adjustments to the ARM payload based on runtime conditions, Azure state, or complex business logic that cannot be expressed in the generated code.

		## Interface Definition


		The Key Vault resource uses `ARMResourceModifier` to handle different creation modes based on whether a soft-deleted vault exists:

		```go

Add comprehensive documentation for resource extension points #5004

Are you sure you want to change the base?

Add comprehensive documentation for resource extension points #5004

Uh oh!

Conversation

Copilot AI commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

New Documentation Structure

Extension Points Documented

Code Enhancement

Example

Comments on the Issue (you are @copilot in this section)

Uh oh!

theunrepentantgeek commented Oct 28, 2025

Uh oh!

Copilot AI commented Oct 28, 2025

Uh oh!

theunrepentantgeek left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Oct 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Oct 28, 2025 •

edited

Loading