azure-service-operator Add comprehensive documentation for resource extension points

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?

gif

Checklist

[x] 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 Azure/azure-service-operator#3902

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

Oct 28 '25 01:10 Copilot

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

Oct 28 '25 02:10 theunrepentantgeek

@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

Oct 28 '25 02:10 Copilot

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

Oct 29 '25 00:10 Copilot

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

Nov 17 '25 21:11 theunrepentantgeek

@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

Nov 17 '25 21:11 Copilot