[RFC] CF API v2 End of Life

[stephanme]

This RFC shall define a plan to disable and finally remove CF API v2 from CAPI and cf-deployment.

Preview

[Gerg]

I'd love to remove v2, but I'm worried that the cost of migrating clients will be too high. There are a bunch of (often non-OSS) legacy v2 clients that are in active use, but are not actively maintained. It is unlikely they will ever move the v3, so this would be a big breaking change.

I'm personally interested if there are any half-steps we can take to maintain the v2 interface, but realize some of y'all's goals around v3 modernization. E.g. could we make Role schema migrations that favor the v3 API over v2?

[stephanme]

From SAP point of view, CF will be used productively at least for the next decade and probably even longer. We have to anticipate more demands on scalability and performance and there will be feature requests like the mentioned more fine granular roles. This gets harder and more expensive with the v2 legacy in the code base. I find that this extra burden and development cost within CAPI is difficult to justify for "a bunch of (often non-OSS), unmaintained legacy v2 clients that are still in use". I think that the efforts should be shared with the users of legacy v2 which translates into v3 migration efforts, replacing legacy clients or even more advanced strategies like shimming by v2 users with help of the CF community e.g. by new v3 clients, add missing v3 support in existing clients etc.

This takes time and I know this only too well from our efforts to reduce v2 usage on SAP foundations. But it also takes a clear signal that v2 has an EOL one day and this is the main point of this RFC. A way forward could be to keep the EOL date and the related removal of v2 in CAPI more vague ('propose'/'plan' instead of 'define') and add checkpoints before the proposed EOL date. This way we get the message out and can start with first steps like disabling v2 by default in cf-deployment (without removing v2).

I can come up with proposal but it will take some time due to vacation.

[Gerg]

How about something like:

1. Three-year EoL window
2. Divided into three phases, with two "checkpoints"
3. Checkpoints require unanimous approval from TOC before progressing to the next phase, else postpone by X months

Proposed phases:

1. Phase A (~ 1 year)
   1. Announce three-year EoL
   2. Engineering work so all CF-D components are built/tested/released with v2 turned off
   3. Turn v2 off by default in CF-D
2. Checkpoint M
3. Phase B (~ 2 years)
   1. Engineering work so all CFF-controlled clients use v3 by default
   2. Window for 3rd-party clients to complete migration to v3
4. Checkpoint N
5. Phase C (ongoing)
   1. Turn v2 permanently off for CAPI/CF-D
   2. Engineering work to remove v2 from CAPI

Parallel with this process, we can explore opportunities to decouple v3 performance from v2, where possible.

[wayneeseguin]

The proposed phases seem reasonable. For Stratos, our team, along with any contributors who wish to assist, plans to fully transition the codebase to v3. Our target for completing this transition is by next July, though we cannot provide any guarantees at this stage. We aim to discuss our plans with the community at CF Day EU on October 10th.

[stephanme]

@Gerg: I adapted the RFC to the proposed 3 phases. I added rough dates to avoid misunderstandings ("Three-year EoL window" is easily interpreted as "v2 is available at least for 3y"). Of course, the dates may shift due the checkpoints.

We discussed the "unanimous approval from TOC" in the last TOC meeting and came to the conclusion that we should stick with the standard TOC Decision-Making process (decision by quorum). It is explicitly mention that TOC should strive to reach consensus on decisions and I don't remember any decision with a dissenting vote.

[beyhan]

We discussed this during the TOC meeting on 01.10.2024 and decided to start the FCP with the goal to accept it during the next TOC meeting.

[Gerg]

Overall, it looks good to me.

I would like some language in the RFC saying what happens if the TOC doesn't approve moving to the next phase. For example something like:

If the TOC does not approve moving to the next phase, the TOC will decide a number of months to extend the current phase. Subsequent phases and the EoL date will be updated accordingly. The TOC will then re-convene after that period to again evaluate if it is appropriate to move to the next phase.