From 11cca3a97ffdfa204a000b879bd8c45e4981f2b6 Mon Sep 17 00:00:00 2001 From: Stephan Merker Date: Thu, 8 Aug 2024 15:48:15 +0200 Subject: [PATCH 1/3] [RFC] CF API v2 End of Life This RFC shall define a plan to disable and finally remove CF API v2 from CAPI and cf-deployment. --- toc/rfc/rfc-draft-cfapiv2-eol.md | 51 ++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 toc/rfc/rfc-draft-cfapiv2-eol.md diff --git a/toc/rfc/rfc-draft-cfapiv2-eol.md b/toc/rfc/rfc-draft-cfapiv2-eol.md new file mode 100644 index 00000000..81907fce --- /dev/null +++ b/toc/rfc/rfc-draft-cfapiv2-eol.md @@ -0,0 +1,51 @@ +# Meta +[meta]: #meta +- Name: CF API v2 End of Life +- Start Date: 2024-08-08 +- Author(s): stephanme +- Status: Draft +- RFC Pull Request: (fill in with PR link after you submit it) + + +## Summary + +CF API v2 is deprecated since at least 2021 but there is no End of Life date communicated (see [ccng #2725](https://github.com/cloudfoundry/cloud_controller_ng/discussions/2725)). + +This RFC shall define a plan to disable and finally remove CF API v2 from CAPI and cf-deployment. + +## Problem + +There are several issues and efforts with keeping the deprecated CF API v2 as part of CAPI and cf-deployment: + +- Maintenance effort in CAPI and CF API client libraries +- CF API v2 uses a different Ruby web framework than v3 +- Shipping an API that is not well tested anymore: CATS don’t test CF API v2 +- Performance problems especially in large foundations: metrics show that v2 requests take between 3 to 5 times as long as v3 requests on average +- Larger cloud controller database schema refactorings/improvements are not possible or at least difficult because the same DB schema has to serve v2 and v3. This blocks performance improvements in CF API v3. + - Example: [ccng decision 0007-implementing-v3-roles.md](https://github.com/cloudfoundry/cloud_controller_ng/blob/main/decisions/0007-implementing-v3-roles.md) + - Areas where schema changes could lead to performance improvements: roles, service plan visibilities +- More fine grained org and space roles, a recurring user request, would benefit from a DB schema migration away from the current one table per role design. Blocked as well by CF API v2. + +## Proposal + +September 2024 (after accepting this RFC) +- Add a validation to cf-deployment that runs with disabled CF API v2 +- Define and announce an End of Life date for CF API v2: end of 2025 + +Jan 2025 +- Disable CF API v2 in cf-deployment by changing the default for CAPI property [cc.temporary_enable_v2](https://bosh.io/jobs/cloud_controller_ng?source=github.com/cloudfoundry/capi-release&version=1.185.0#p%3dcc.temporary_enable_v2) to false. Operators may still re-enable v2. + +Jan 2026 +- CF API v2 reached EOL +- Remove the option to re-enable CF API v2 in CAPI and cf-deployment +- Remove CF API v2 implementation from CAPI + +### Impact and Consequences + +- CF API client libraries like [cf-java-client](https://github.com/cloudfoundry/cf-java-client), [cf-goclient](https://github.com/cloudfoundry/go-cfclient) and [cf_exporter](https://github.com/cloudfoundry/cf_exporter) should plan for closing gaps in CF API v3 support and for removing their CF API v2 implementation. +- CF CLI v6 and v7 still use CF API v2 and will stop working against foundations with disabled CF API v2. CF CLI v8 doesn’t use CF API v2 anymore (exception: CLI plugins, see next point). +- Most CF CLI plugins rely on CF API v2. A new CF CLI plugin interface should be defined (out of scope of this RFC). However, it is possible to implement a CLI plugin without using CF API v2. +- Cloud Foundry users and operators may use tooling and CI/CD pipelines which still rely on CF API v2 and therefore have migration efforts. + +CF API v2 specific rate limiting and the feature flag to disable CF API v2 completely is already implemented in CAPI. +The [CF API v3 Upgrade Guide](https://v3-apidocs.cloudfoundry.org/index.html#upgrade-guide) helps authors of CF api clients to migrate from v2 to v3. \ No newline at end of file From 1c43eb82db4867de86b831a63cfedf273d015e88 Mon Sep 17 00:00:00 2001 From: Stephan Merker Date: Fri, 20 Sep 2024 15:12:22 +0200 Subject: [PATCH 2/3] 3 phase removal plan with checkpoints --- toc/rfc/rfc-draft-cfapiv2-eol.md | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/toc/rfc/rfc-draft-cfapiv2-eol.md b/toc/rfc/rfc-draft-cfapiv2-eol.md index 81907fce..5ce59477 100644 --- a/toc/rfc/rfc-draft-cfapiv2-eol.md +++ b/toc/rfc/rfc-draft-cfapiv2-eol.md @@ -4,7 +4,7 @@ - Start Date: 2024-08-08 - Author(s): stephanme - Status: Draft -- RFC Pull Request: (fill in with PR link after you submit it) +- RFC Pull Request: [#941](https://github.com/cloudfoundry/community/pull/941) ## Summary @@ -28,17 +28,26 @@ There are several issues and efforts with keeping the deprecated CF API v2 as pa ## Proposal -September 2024 (after accepting this RFC) -- Add a validation to cf-deployment that runs with disabled CF API v2 -- Define and announce an End of Life date for CF API v2: end of 2025 +Since CF API v2 removal is a fundamental breaking change, the removal is devided into 3 phases of about 1 year each with checkpoints in between that require TOC approval. -Jan 2025 -- Disable CF API v2 in cf-deployment by changing the default for CAPI property [cc.temporary_enable_v2](https://bosh.io/jobs/cloud_controller_ng?source=github.com/cloudfoundry/capi-release&version=1.185.0#p%3dcc.temporary_enable_v2) to false. Operators may still re-enable v2. +**Phase 1** (starts after accepting this RFC) +- Announce an End of Life date for CF API v2 (~ mid/end 2026). +- Engineering work so that all cf-deployment components are built/tested/released with v2 turned off +- Turn off CF API v2 by default in cf-deployment (set CAPI property [cc.temporary_enable_v2](https://bosh.io/jobs/cloud_controller_ng?source=github.com/cloudfoundry/capi-release&version=1.185.0#p%3dcc.temporary_enable_v2) to false). Operators may still re-enable v2. -Jan 2026 -- CF API v2 reached EOL -- Remove the option to re-enable CF API v2 in CAPI and cf-deployment -- Remove CF API v2 implementation from CAPI +**Checkpoint 1** +- TOC approval + +**Phase 2** (after Checkpoint 1, ~mid/end 2025) +- Engineering work so that all CFF-controlled clients use v3 by default +- Window for 3rd-party clients to complete migration to v3 + +**Checkpoint 2** +- TOC approval + +**Phase 3** (after Checkpoint 2, ~mid/end 2026) +- Turn CF API v2 permanently off for CAPI/cf-deployment. +- Engineering work to remove CF API v2 from CAPI. ### Impact and Consequences From cb02feaf84c40b4d5698f2cfb6b05f8b4ba2f6ee Mon Sep 17 00:00:00 2001 From: Stephan Merker Date: Tue, 8 Oct 2024 15:17:06 +0200 Subject: [PATCH 3/3] Deal with TOC rejection at a checkpoint --- toc/rfc/rfc-draft-cfapiv2-eol.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/toc/rfc/rfc-draft-cfapiv2-eol.md b/toc/rfc/rfc-draft-cfapiv2-eol.md index 5ce59477..4a759b8d 100644 --- a/toc/rfc/rfc-draft-cfapiv2-eol.md +++ b/toc/rfc/rfc-draft-cfapiv2-eol.md @@ -28,7 +28,8 @@ There are several issues and efforts with keeping the deprecated CF API v2 as pa ## Proposal -Since CF API v2 removal is a fundamental breaking change, the removal is devided into 3 phases of about 1 year each with checkpoints in between that require TOC approval. +Since CF API v2 removal is a fundamental breaking change, the removal is divided into 3 phases of about 1 year each with checkpoints in between that require TOC approval. +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. **Phase 1** (starts after accepting this RFC) - Announce an End of Life date for CF API v2 (~ mid/end 2026).