Skip to content

First pass at Operations docs#956

Merged
negz merged 15 commits intocrossplane:masterfrom
negz:whats-op-doc
Aug 8, 2025
Merged

First pass at Operations docs#956
negz merged 15 commits intocrossplane:masterfrom
negz:whats-op-doc

Conversation

@negz
Copy link
Member

@negz negz commented Aug 6, 2025 •
edited
Loading

First pass at Operations documentation including getting started guide and concept documentation.

I've tested the getting started guide end-to-end in a live cluster and it works perfectly. Here's what I validated:

Test Environment:

  • Kind cluster with Crossplane v0.0.0-hack (development build)
  • Operations feature flag enabled (--enable-operations)
  • function-python v0.2.0

Test Results:
All steps in the getting started guide work as documented:

  1. Created sample Ingress resource
  2. Applied RBAC permissions (ClusterRole properly aggregated to Crossplane)
  3. Installed function-python v0.2.0 (became healthy)
  4. Created and ran the Operation successfully
  5. Operation retrieved google.com SSL certificate and calculated 53 days until expiry
  6. Operation correctly annotated the Ingress with certificate monitoring metadata:
    • cert-monitor.crossplane.io/expires: Sep 29 08:34:02 2025 GMT
    • cert-monitor.crossplane.io/days-until-expiry: "53"
    • cert-monitor.crossplane.io/status: ok
  7. Operation status shows SYNCED=True and SUCCEEDED=True with detailed output
  8. Clean up worked - all resources deleted successfully

The key functionality works correctly: required resource fetching, SSL certificate inspection via Python, resource modification (adding annotations), and operation output for monitoring.

Dependencies

@netlify
Copy link

netlify bot commented Aug 6, 2025 •
edited
Loading

✅ Deploy Preview for crossplane ready!

Name Link
🔨 Latest commit 1c911d8
🔍 Latest deploy log https://app.netlify.com/projects/crossplane/deploys/68957cd6e380700008e539a9
😎 Deploy Preview https://deploy-preview-956--crossplane.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse		 1 paths audited
Performance: 67 (🔴 down 6 from production)
Accessibility: 90 (🔴 down 2 from production)
Best Practices: 83 (no change from production)
SEO: 100 (no change from production)
PWA: 70 (no change from production)
View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

@negz negz force-pushed the whats-op-doc branch 8 times, most recently from dabe420 to 78092bc Compare August 7, 2025 01:11
@negz negz mentioned this pull request Aug 7, 2025
Merged
2 tasks
negz
negz commented Aug 7, 2025
View reviewed changes
@negz negz marked this pull request as ready for review August 7, 2025 08:07
tr0njavolta
tr0njavolta approved these changes Aug 7, 2025
View reviewed changes
Copy link
Collaborator

@tr0njavolta tr0njavolta left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Small rendering change requested, otherwise looks good! Approving to not block

@negz negz force-pushed the whats-op-doc branch 2 times, most recently from 8118d1c to 21bed19 Compare August 7, 2025 20:34
@negz
Copy link
Member Author

negz commented Aug 7, 2025

Gonna hold on merging until crossplane/crossplane#6695 is merged, since this PR documents stuff in that one (namely crossplane alpha render).

jbw976
jbw976 reviewed Aug 7, 2025
View reviewed changes
Copy link
Member

@jbw976 jbw976 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

awesome @negz! this is really useful content that will be very helpful for users learning about operations and developing them for their control planes 💪

negz added a commit to negz/docs that referenced this pull request Aug 8, 2025
@negz
Add consistent backticks for Kubernetes resource types
9fe95b8 
Apply backticks to Kubernetes resource types (Operation, Ingress,
ClusterRole, Job) to follow documentation style conventions
for API objects per Jared's feedback in PR crossplane#956.
negz added a commit to negz/docs that referenced this pull request Aug 8, 2025
@negz
Fix consistent code blocks in status field list
aeeefae 
Add backticks to all status field names (Conditions, Succeeded,
ValidPipeline, Failures, Pipeline) to match AppliedResourceRefs
per Jared's feedback in PR crossplane#956.
@negz negz force-pushed the whats-op-doc branch 2 times, most recently from b6a7d66 to 00b3296 Compare August 8, 2025 04:12
negz added 8 commits August 7, 2025 21:27
@negz
Add ops to "What's Crossplane?"
bfff85f 
Feels like it belongs here as a top-level tool, despite being alpha.

Signed-off-by: Nic Cope <nicc@rk0n.org>
@negz
Add Operations to "What's new" page.
bb454e8 
Signed-off-by: Nic Cope <nicc@rk0n.org>
@negz
First pass at Operations docs
4c36f90 
Signed-off-by: Nic Cope <nicc@rk0n.org>
@negz
Document crossplane alpha render op command
91edda5 
Add Test an operation section to Operations concept documentation showing how to
preview Operations locally using the CLI. Follows same pattern as composition
render documentation with usage examples and output format.

Signed-off-by: Nic Cope <nicc@rk0n.org>
@negz
Document requirement stabilization pattern for dynamic resource disco…
ea1ab25 
…very

Add critical guidance for WatchOperation functions that request resources
dynamically. Functions must return consistent requirements across iterations
for proper stabilization. Include working example with error handling.

Signed-off-by: Nic Cope <nicc@rk0n.org>
@negz
Fix code block rendering for cron syntax diagram
7240b42 
Change from plain code block to console with disabled line numbers and copy
functionality per docs engineer feedback. Improves visual presentation of the
cron schedule diagram.

Signed-off-by: Nic Cope <nicc@rk0n.org>
@negz
Fix alphaVersion rendering issue in operations/_index.md
02df3da 
Change alphaVersion from 'v2.0-preview' to '2.0' to avoid
double 'v' rendering in the documentation.

Signed-off-by: Nic Cope <nicc@rk0n.org>
@negz
Add consistent backticks for Kubernetes resource types
40f768e 
Apply backticks to Kubernetes resource types (Operation, Ingress,
ClusterRole, Job) to follow documentation style conventions
for API objects per Jared's feedback in PR crossplane#956.

Signed-off-by: Nic Cope <nicc@rk0n.org>
negz added 7 commits August 7, 2025 21:27
@negz
Fix consistent code blocks in status field list
5f729d9 
Add backticks to all status field names (Conditions, Succeeded,
ValidPipeline, Failures, Pipeline) to match AppliedResourceRefs
per Jared's feedback in PR crossplane#956.

Signed-off-by: Nic Cope <nicc@rk0n.org>
@negz
Fix truncated mermaid diagram text
178a42c 
Changed 'SSL Monitor Operation API' to 'SSL Monitor Operation' in the
mermaid diagram to prevent text truncation that was showing as
'SSL Monitor Operation AP' in the rendered output.

Signed-off-by: Nic Cope <nicc@rk0n.org>
@negz
Alphabetize all Vale dictionary files
4efb03c 
Sorted all dictionary files in utils/vale/styles/Crossplane/ alphabetically:
- allowed-jargon.txt
- brands.txt
- crossplane-words.txt
- provider-words.txt
- spelling-exceptions.txt

This removes duplicate entries and ensures consistent ordering for
easier maintenance and Vale linting compliance.

Signed-off-by: Nic Cope <nicc@rk0n.org>
@negz
Add troubleshooting item about --enable-operations flag
fcba825 
Added a new troubleshooting item to operation.md documenting the common
error when Operations feature is not enabled and how to resolve it by
adding the --enable-operations flag to Crossplane's startup arguments.

Updated numbering for subsequent troubleshooting items accordingly.

Signed-off-by: Nic Cope <nicc@rk0n.org>
@negz
Fix status field capitalization to match YAML
1460b62 
Updated status field names in operation.md to match actual YAML
capitalization: conditions, failures, pipeline, appliedResourceRefs
instead of the capitalized versions.

Signed-off-by: Nic Cope <nicc@rk0n.org>
@negz
Fix HTML comment causing ordered list numbering reset
e604ae5 
Fixed Vale linter disable comment that was interrupting the ordered list
in the "Event handling" section of watchoperation.md. Moved the Vale
disable comments to wrap around the entire list instead of interrupting
it, which resolves the ordering numbering reset issue.

Signed-off-by: Nic Cope <nicc@rk0n.org>
@negz
Add context before Operations mermaid diagram
1c911d8 
Added introductory sentence before Operations diagram to match the pattern
used for other diagrams. Explains the SSL certificate monitoring scenario
that the diagram illustrates, connecting the use case to the visual representation.

Signed-off-by: Nic Cope <nicc@rk0n.org>
@negz negz merged commit 704d5df into crossplane:master Aug 8, 2025
7 checks passed
@jbw976 jbw976 mentioned this pull request Aug 8, 2025
Closed
@negz negz mentioned this pull request Aug 13, 2025
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jbw976 jbw976 jbw976 left review comments

@tr0njavolta tr0njavolta tr0njavolta approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@negz @jbw976 @tr0njavolta