Add comprehensive documentation for resource extension points #5004

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

What this PR does

ASO v2 provides 9 extension interfaces for customizing resource behavior, but lacked documentation causing contributor friction. This PR adds comprehensive technical documentation covering all extension points, with links to source code to avoid duplication and ensure documentation stays synchronized with implementation.

New Documentation Structure

docs/hugo/content/contributing/extension-points/ folder with overview and 9 detailed guides
Each extension point documented with: interface link, motivation, usage patterns, implementation examples, testing guidance
Cross-referenced with Hugo-compatible links
Links to actual source code instead of duplicating interface definitions and large code blocks

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.

Documentation Structure (per extension point)

Description: What the extension does and when it's invoked
Interface Definition: Link to source code (not duplicated)
Motivation: Why the extension point exists and problems it solves
When to Use: Clear guidance with ✅/❌ examples
Example: Link to actual implementation with key aspects highlighted
Common Patterns: Short code snippets with links to source implementations
Testing: Concise testing guidance
Important Notes: Key considerations and gotchas
Related Extension Points: Links to related documentation

Code Enhancement

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

Documentation Improvements Based on Review

Removed page weight to allow alphabetical listing
Formatted extension points table for better markdown readability with reference-style links
Added concrete example demonstrating the "Call next" pattern
Replaced all interface definitions with links to source code
Replaced large code examples with links to actual implementations
Added links to source code for all pattern examples
Removed duplicate patterns and test structure examples

Example of Code Comment Enhancement

// 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)
}

Closes #3902

How does this PR make you feel?

Checklist

this PR contains documentation
this PR contains tests
this PR contains YAML Samples

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

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

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

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?

Agreed. No point in replicating large blocks of code; a direct link avoids issues with consistency.

Replaced large code blocks with links to implementations in commits 3af00e3 and 3264d4c. All examples now link to the actual source files.

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.

Yeah, we'll remove that.

Removed "Example test structure" sections from all extension point docs in commit 3264d4c.

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?

Yes. Will remove this pattern.

Removed duplicate Pattern 5 from error-classifier.md in commit 3264d4c.

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

Agreed. Will check for, and remove, Example test structure across all the extension points.

Removed "Example test structure" sections from all extension point docs in commit 3264d4c.

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?

Agreed. Linking to an existing test is smarter.

Removed "Example test implementation" sections in commit 3264d4c. The Testing sections now provide concise guidance without detailed test structure examples.

theunrepentantgeek · 2025-11-17T21:00:42Z

@copilot, please reference the code review comments above and update the PR.

- Removed weight from _index.md to allow alphabetical listing - Formatted table in _index.md for better readability - Added example for "Call next" guideline - Replaced Interface Definition in arm-resource-modifier.md with link to code - Replaced large code example with link to implementation - Added links to code for pattern implementations Co-authored-by: theunrepentantgeek <[email protected]>

- Replaced all "Interface Definition" sections with links to source code - Replaced large code examples with links to implementations - Removed "Example test structure" sections from all extension point docs - Removed duplicate Pattern 5 from error-classifier.md This addresses all remaining PR review comments about reducing duplication and linking to source code instead of copying it. Co-authored-by: theunrepentantgeek <[email protected]>

Copilot · 2025-11-17T21:16:18Z

@copilot, please reference the code review comments above and update the PR.

All PR review comments have been addressed in commits 3af00e3 and 3264d4c:

Removed weight for alphabetical sorting
Formatted table for readability
Added "Call next" example
Replaced interface definitions with links
Replaced large examples with links
Added links to pattern implementations
Removed test structure sections
Removed duplicate pattern

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

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

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

docs/hugo/content/contributing/extension-points/kubernetes-secret-exporter.md

docs/hugo/content/contributing/extension-points/post-reconciliation-checker.md

docs/hugo/content/contributing/extension-points/pre-reconciliation-owner-checker.md

docs/hugo/content/contributing/extension-points/successful-creation-handler.md

docs/hugo/content/design/ADR-2023-05-Installing-Only-Selected-CRDs.md

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

Copilot started work on behalf of theunrepentantgeek November 17, 2025 21:01 View session

Copilot AI and others added 2 commits November 17, 2025 21:11

Copilot finished work on behalf of theunrepentantgeek November 17, 2025 21:19

matthchr reviewed Nov 18, 2025

View reviewed changes

theunrepentantgeek added 4 commits November 24, 2025 10:11

Tidy numbered markdown lists

16e4d3f

Format markdown

b356c1e

Revised based on PR feedback

fb6df54

Further updates

c274ebb


		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!

What this PR does

New Documentation Structure

Extension Points Documented

Documentation Structure (per extension point)

Code Enhancement

Documentation Improvements Based on Review

Example of Code Comment Enhancement

How does this PR make you feel?

Checklist

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

theunrepentantgeek Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 17, 2025

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!

Copilot AI Nov 17, 2025

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!

Copilot AI Nov 17, 2025

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!

Copilot AI Nov 17, 2025

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!

Copilot AI Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

theunrepentantgeek commented Nov 17, 2025

Uh oh!

Copilot AI commented Nov 17, 2025

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Oct 28, 2025 •

edited

Loading

theunrepentantgeek Nov 17, 2025 •

edited

Loading