Update konnector developer docs

[cnvergence]

Summary

What Type of PR Is This?

/kind documentation

Related Issue(s)

Fixes #

Release Notes

NONE

Summary by CodeRabbit

• Documentation

  • Updated controller docs to reflect a BoundSchema-based reconciliation flow replacing CRD-centric paths. Clarified sequences, conditions and transitions, improved diagrams, and adjusted wording for readability.

• Refactor

  • Internal helpers and references renamed to align with BoundSchema terminology; comments updated for consistency. No behavior changes.

[coderabbitai]

Walkthrough

Documentation and controller code were updated to replace CRD-centric reconcile flows with BoundSchema-centered sequences for APIServiceBinding and APIServiceExport. A helper was renamed from referenceBoundAPIResourceSchema to referenceBoundSchema, call sites and comments updated; no public APIs changed.

Changes

Cohort / File(s)	Summary
Docs — APIServiceBinding flow docs/content/developers/konnector/controllers/cluster/apiservicebinding.md	Reworked reconcile diagram to use BoundSchema: separate fetches for APIServiceExportRequest, fetch/reference BoundSchemas, convert BoundSchema → CRD, update/get CRD, and updated ownership/condition transitions; removed prior APIServiceExport→CRD path and related checks.
Docs — APIServiceExport flow docs/content/developers/konnector/controllers/cluster/apiserviceexport.md	Shifted flow to BoundSchema-first: added get_bound_schemas, is_bound_schema_present, update_bound_schema, integrated get_crd before copying CRD conditions, and adjusted final transition chain to update BoundSchema then stop.
Controller — ServiceBinding reconcile pkg/konnector/controllers/cluster/servicebinding/servicebinding_reconcile.go	Renamed helper from referenceBoundAPIResourceSchema → referenceBoundSchema and updated usages/comments; logic, error aggregation, and behavior unchanged.
Controller — ServiceExport reconcile pkg/konnector/controllers/cluster/serviceexport/serviceexport_reconcile.go	Comment updated to reference "Fetch the BoundSchema" instead of "APIResourceSchema"; functional behavior unchanged.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor Reconciler as APIServiceBinding Reconciler
  participant Export as APIServiceExport
  participant Req as APIServiceExportRequest
  participant BS as BoundSchema
  participant CRD as CustomResourceDefinition
  participant Status as APIServiceBinding Status

  Reconciler->>Export: get APIServiceExport
  alt export present
    Reconciler->>Req: get APIServiceExportRequest
    alt request failed
      Reconciler->>Status: set connected=false (terminal)
    else request ok
      Reconciler->>Export: get_bound_schemas
      alt bound schemas fetched
        Reconciler->>BS: reference_bound_schema
        Reconciler->>BS: convert_boundschema_to_crd
        Reconciler->>CRD: get_crd
        alt crd present
          Reconciler->>CRD: update_crd / create_crd
          Reconciler->>Status: set connected=true
          Reconciler->>Status: set schemaInSync=true
        else crd missing
          Reconciler->>Status: set connected=false
        end
      else fetch failed
        Reconciler->>Status: set connected=false
      end
    end
  else export absent
    Reconciler->>Status: set connected=false
  end

Loading

sequenceDiagram
  autonumber
  actor Reconciler as APIServiceExport Reconciler
  participant Export as APIServiceExport
  participant BS as BoundSchema
  participant CRD as CustomResourceDefinition
  participant Summary as Summary/Conditions

  Reconciler->>Export: fetch export
  alt export present
    Reconciler->>Export: get_bound_schemas
    alt is_bound_schema_present
      Reconciler->>BS: start/ensure syncer
      Reconciler->>Export: get_bound_schemas (for conditions)
      Reconciler->>CRD: get_crd
      Reconciler->>Summary: copy_crd_conditions
      Reconciler->>BS: update_bound_schema
      Reconciler-->>Export: stop (complete)
    else absent
      Reconciler-->>Export: stop sync
    end
  else not present
    Reconciler-->>Export: stop
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested reviewers

• xrstf
• moadqassem
• s-urbaniak

Poem

I thump my paws on fertile ground,
BoundSchemas hop where CRDs were found.
We fetch, we bind, convert, and see,
Conditions settle, tidy and free.
Hops of joy — the bindings grow! 🐇✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description Check	⚠️ Warning	The PR description includes the template headings but leaves the Summary section blank and the Related Issue(s) field incomplete, providing no actual overview of the changes or linked issue context.	Please add a concise overview of the documentation and code updates under the Summary section and update the Related Issue(s) field with the appropriate issue number or explicitly state 'None'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title succinctly and accurately describes the primary focus of the changeset—updating the Konnector developer documentation—without extraneous details or ambiguity.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2278f65 and 4256fd2.

📒 Files selected for processing (1)

• docs/content/developers/konnector/controllers/cluster/apiservicebinding.md (2 hunks)

🧰 Additional context used

🧠 Learnings (1)

📓 Common learnings

Learnt from: mjudeikis
PR: kube-bind/kube-bind#295
File: backend/controllers/serviceexportrequest/serviceexportrequest_reconcile.go:140-143
Timestamp: 2025-09-12T08:40:15.290Z
Learning: APIServiceExportRequest resources in kube-bind are short-lived and automatically deleted after 10 minutes, so they should not be used as owner references for longer-lived resources like BoundSchema. The proper lifecycle management for BoundSchema resources created by APIServiceExportRequest is tracked in issue #297.

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: verify
• GitHub Check: go-test-e2e
• GitHub Check: lint
• GitHub Check: go-test

🔇 Additional comments (1)

docs/content/developers/konnector/controllers/cluster/apiservicebinding.md (1)

77-85: Flow update aligns with BoundSchema reconcile

Nice job reflecting the new referenceBoundSchema ➜ convertBoundSchemaToCRD path; the diagram now mirrors the controller’s fetch/reference/convert sequence precisely.

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[mjudeikis]

Double check please where does boundschema is created now. On request path or on request implementation. And source now has to play where it comes from

[cnvergence]

This includes only changes from servicebinding and serviceexport reconcilers.
We can also describe, if it is consumer or provider side

[mjudeikis]

I think we need more details about Request implementation now too

[mjudeikis]

I really like @CodeRabbit generated flow charts (see PR description).
maybe we can reuse them.

[cnvergence]

We can convert them to sequence diagrams