Uploaded image for project: 'Red Hat Advanced Cluster Security'
  1. Red Hat Advanced Cluster Security
  2. ROX-27788

Agreed-on guidelines on how to evolve operator API

    • Agreed-on guidelines on how to evolve operator API
    • Future Sustainability
    • False
    • Hide

      None

      Show
      None
    • True
    • Not Selected
    • Done
    • 0% To Do, 0% In Progress, 100% Done
    • Hide

      2025-09-23:

      • most changes done
      • working on a followup cleanup PR

      2025-09-09:

      • PR to move defaults from CRD schema to runtime code: rebased, significantly improved and sent for review.
      • PR to improve developer docs: reviewed, rebased to fix one unrelated CI flake just to hit an OpenShift CI outage :facepalm:

      2025-09-02:

      • Investigation revealed problem with underlying library. Fixed by Moritz while I was on sick leave last week+. Resuming work today.

      2025-08-19:

      • Last minute testing revealed unforeseen problems; on PTO since then, resuming investigation this week

      2025-08-05:

      • Good progress: 50% of code already merged, 90% to be sent for review today

      2025-07-29:

      • Work resumed, first PR (move of first field default for central) in review.
      • Work on the same for secured cluster in progress.

      2025-07-22:

      • No updates, preempted by interrupts and ROX-25612
      • Hopefully will really resume work on this this week

      2025-07-15:

      • Again no updates (PTO)
      • Will resume work on this this week

      2025-07-08:

      • No updates (PTO)

      2025-06-17:

      • (Moritz) dev docs merged
      • (Moritz) user docs (ROX-29590) in review

      2025-06-10:

      • (Moritz) Work on ROX-29465 (dev docs) has started.

      2025-06-03:

      • Still preempted by konflux work: ROX-25612

      2025-05-27:

      • CRD change check in place and marked required
      • Design feedback incorporated or turned into Jira tickets
      • Runtime defaulting code merged; refactoring for use with other flows - almost done
      • Now working on documenting agreed changes
      • Remaining changes (removing static defaults, adding user warnings) to be postponed to after konflux work (ROX-25612)

      2025-05-06:

      • Changes to design are still being incorporated, Moritz's prototype in (after changes) in final stages of review, hopefully really this time, after finding a late potential issue.
      • Investigation of CRD change validation still in progress (prerequisite to broad CRD changes).

      2025-04-29:

      • Design review meeting was a success, no vetoes, a few changes are being incorporated, Moritz's prototype in (after changes) in final stages of review.
      • Starting to investigate CRD change validation, as prerequisite to broad CRD changes.

      2025-04-22:

      • Design in review, meeting scheduled for later this week. Moritz's prototype in review.

      2025-04-15:

      • Design shared for review. Moritz is prototyping a solution that will validate it.

      2025-04-08:

      • Design completed, draft in review.

      2025-04-01:

      • Investigation continues... approx 70% there.

      2025-03-18:

      • Investigation continues... approx 40% there.

      2025-03-18:

      • Investigation continues...

      2025-03-11:

      • Started surveying the landscape of sub-issues to solve and possible solutions
      Show
      2025-09-23: most changes done working on a followup cleanup PR 2025-09-09: PR to move defaults from CRD schema to runtime code: rebased, significantly improved and sent for review. PR to improve developer docs: reviewed, rebased to fix one unrelated CI flake just to hit an OpenShift CI outage :facepalm: 2025-09-02: Investigation revealed problem with underlying library. Fixed by Moritz while I was on sick leave last week+. Resuming work today. 2025-08-19: Last minute testing revealed unforeseen problems; on PTO since then, resuming investigation this week 2025-08-05: Good progress: 50% of code already merged, 90% to be sent for review today 2025-07-29: Work resumed, first PR (move of first field default for central) in review. Work on the same for secured cluster in progress. 2025-07-22: No updates, preempted by interrupts and ROX-25612 Hopefully will really resume work on this this week 2025-07-15: Again no updates (PTO) Will resume work on this this week 2025-07-08: No updates (PTO) 2025-06-17: (Moritz) dev docs merged (Moritz) user docs (ROX-29590) in review 2025-06-10: (Moritz) Work on ROX-29465 (dev docs) has started. 2025-06-03: Still preempted by konflux work: ROX-25612 2025-05-27: CRD change check in place and marked required Design feedback incorporated or turned into Jira tickets Runtime defaulting code merged; refactoring for use with other flows - almost done Now working on documenting agreed changes Remaining changes (removing static defaults, adding user warnings) to be postponed to after konflux work (ROX-25612) 2025-05-06: Changes to design are still being incorporated, Moritz's prototype in (after changes) in final stages of review, hopefully really this time, after finding a late potential issue. Investigation of CRD change validation still in progress (prerequisite to broad CRD changes). 2025-04-29: Design review meeting was a success, no vetoes, a few changes are being incorporated, Moritz's prototype in (after changes) in final stages of review. Starting to investigate CRD change validation, as prerequisite to broad CRD changes. 2025-04-22: Design in review, meeting scheduled for later this week. Moritz's prototype in review. 2025-04-15: Design shared for review. Moritz is prototyping a solution that will validate it. 2025-04-08: Design completed, draft in review. 2025-04-01: Investigation continues... approx 70% there. 2025-03-18: Investigation continues... approx 40% there. 2025-03-18: Investigation continues... 2025-03-11: Started surveying the landscape of sub-issues to solve and possible solutions
    • 0

      CUSTOMER PROBLEM

      • Closely related to that, we are in equally bad shape w.r.t. evolving the schema as the operands (e.g. collector) changes - according to k8s API conventions, we make incompatible schema changes and we’re still on v1alpha1. So we are effectively not versioning our API. (Note that many OpenShift APIs are in the same (alpha) boat.)
      • We do not have good guide-rails for evolving the API. For the more dynamically changing parts of configuration this results in getting ourselves painted into a corner, and consequently abominations such as forceCollection field.

      Related (unfinished) discussion on slack.

      ACCEPTANCE CRITERIA

      1. A set of agreed-on guidelines on:
        1. how to introduce new fields into the operator API and subsequently evolve them. These guidelines must describe how we should have handled the above-mentioned issues if we were wiser from the start.
        2. how and in what situations to bump the operator API version.
      2. Solutions to the child tickets.

       

              mowsiany@redhat.com Marcin Owsiany
              mowsiany@redhat.com Marcin Owsiany
              ACS Install
              Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

                Created:
                Updated:
                Resolved: