RFC: CLI Plugin Transitional Migration to CAPI V3#1452
RFC: CLI Plugin Transitional Migration to CAPI V3#1452norman-abramovitz wants to merge 3 commits intocloudfoundry:mainfrom
Conversation
Proposes a guest-side migration path for CF CLI plugins to eliminate their CAPI V2 dependency before RFC-0032 removal. Plugin developers can adopt this today with no CLI host changes required. Tracking issue: cloudfoundry/cli#3621
|
|
||
| ### Relationship to a New Plugin Interface | ||
|
|
||
| This RFC addresses the immediate V2 end-of-life risk using the existing plugin interface and works with any current CLI version (v7, v8). A separate future RFC will propose a modernized plugin interface targeting v9 and later with a minimal stable contract, polyglot language support, backward compatibility, and improved help and versioning metadata. |
There was a problem hiding this comment.
CLI v7 is already deprecated and it uses CF API v2 for service related commands -> CLI v7 won't work on CF foundations with disabled CF API v2 independent of plugins.
I would leave v2 out of this RFC and only consider v8 and future version.
There was a problem hiding this comment.
Agreed. CLI v7 is deprecated and will not function on v2-disabled foundations regardless of plugin migration. The RFC has been updated to scope to v8 and later, with a note explaining the v7 exclusion.
|
|
||
| Beyond the intended plugin API, 11 of 20 surveyed plugins import internal CLI packages (`cf/terminal`, `cf/trace`, `cf/flags`, `cf/configuration/confighelpers`, `util/ui`). These imports create tight coupling to CLI internals that are not part of the public plugin contract and will break if the CLI team refactors those packages. The most common import is `cf/terminal` (used by 7 plugins across up to 22 files each for UI, tables, and color output). Replacement packages with matching signatures can eliminate this coupling for most cases. | ||
|
|
||
| ## Proposal |
There was a problem hiding this comment.
IMHO, the main point of this RFC is to deprecate and eventually remove most of the CLI plugin interface because it depends on CF API v2 (which is already disabled by default in cf-deployment). Only a minimal plugin interface as proposed in cli #3621 shall remain (basically: access token and context).
The "Guest-Side v2 compatibility Wrapper" is a nice tool for dealing with this RFC once it is accepted and implemented. It is not the only solution: plugins could decide to migrate directly to CF API v3 instead of using a compatibility wrapper (as done by some plugins in the past). Therefore, I would place the wrapper approach into a separate section as an offer how to deal with this RFC.
There was a problem hiding this comment.
Agree that deprecation of the v2-dependent plugin interface methods is the broader goal, and that this RFC is one part of enabling it. However, the decision to formally deprecate and remove those methods belongs to the CLI Working Group, not to this RFC. The guest-side wrapper is presented as the recommended migration path, with direct v3 access as an equally valid alternative — that framing is intentional. A new section has been added to the RFC covering plugin repository metadata tagging, which addresses the plugin compatibility tracking aspect of this concern. The broader deprecation scope remains deferred to CLI WG consensus.
There was a problem hiding this comment.
would like to leave my agreement with @norman-abramovitz too. A change of the interface (probably not only with deprecation but with removal of some methods) would be the future. As mentioned in the issue comment cloudfoundry/cli#3621 (comment) the rpc_server can be updated to stop using the v2 api, while keeping the same interface without deprecation.
perhaps it would be an idea to add a section regarding this update on the cli codebase, and this rfc becomes a very clear path to migrate plugins which also directly depend on cc v2 endpoints. something we could discuss if it doesn't sound like a good idea in a first instance.
| @@ -0,0 +1,129 @@ | |||
| # Meta | |||
| [meta]: #meta | |||
| - Name: CLI Plugin Transitional Migration to CAPI V3 | |||
There was a problem hiding this comment.
I would even go further and rename the RFC: Deprecation of CLI Plugin interface methods that depend on CF API v2
Rational: see below
There was a problem hiding this comment.
Thank you for the suggestion. Renaming the RFC to frame it as a deprecation RFC would change its scope beyond what this proposal intends to address. The decision on what to deprecate, when, and under what timeline is appropriately one for the CLI Working Group and TOC to make. This RFC proposes the migration technique that makes such a deprecation decision viable — the naming reflects that scope.
There was a problem hiding this comment.
I'm with @stephanme on this one, I would like to see an RFC with a wider scope, the migration tool just being one piece of the puzzel.
As discussed during the TOC meeting it would be great to add some context about support cli version support lines. And how they align with the capi v2 api removal RFC.
There was a problem hiding this comment.
I am inclined towards multiple RFCs, but that decision belongs to the CLI WG. I am planning to attend the WG meeting next week, so the decision would be forth coming.
RFC 1 - Overall Arching
RFC 2 (this one)
RFC 3 (V9 plugin interface)
RFC 4 (plugin repo)
There was a problem hiding this comment.
I personally like more the approach of splitting RFCs, where breaking things down into smaller, self-contained RFCs makes tracking and governance perspective esier. Each RFC can then:
- Have a clear and focused scope that is easier to review and reason about
- Be progressed independently, avoiding bottlenecks where one unresolved discussion blocks everything else
- Allow incremental delivery and validation of each piece before moving to the next
Of course they need to be steps into the right strategic direction we want to go. This is of course a trade-off and people driving the topic can decide what makes more sense from their perspective.
There was a problem hiding this comment.
One more thing worth mentioning. I don't think we need a dedicated RFC for the overall architecture. Instead, the first RFC could include a Future Improvements section that broadly outlines the big picture, which subsequent RFCs can then reference to provide context for the overall idea. This is the pattern we used in many past RFCs.
| Beyond the intended plugin API, 11 of 20 surveyed plugins import internal CLI packages (`cf/terminal`, `cf/trace`, `cf/flags`, `cf/configuration/confighelpers`, `util/ui`). These imports create tight coupling to CLI internals that are not part of the public plugin contract and will break if the CLI team refactors those packages. The most common import is `cf/terminal` (used by 7 plugins across up to 22 files each for UI, tables, and color output). Replacement packages with matching signatures can eliminate this coupling for most cases. | ||
|
|
||
| ## Proposal | ||
|
|
There was a problem hiding this comment.
I think the rfc should also propose a reviewed cli repo metadata format, where plugins can be tagged for which plugin interface are they compatible with.
Would also suggest that the rfc would include a cli plugin repo cleanup. Plugins which are not maintained and kept up to date should be removed. The cf top, for example, which hasn't been updated since 2017, is simply not compatible with v3 unless the plugin itself is updated. Even though we can update the rpc_server to use v3 endpoints, the plugin itself calls /v2 endpoints directly and will simply not work in the future.
There was a problem hiding this comment.
Agreed on both points. A new section — "Plugin Repository Metadata and Maintenance" — has been added to the RFC proposing a compatibility metadata format for the CLI plugin repository. The cf-plugin-migrate scan tool can provide an objective basis for tagging plugins without requiring self-reporting by authors. The decision to remove unmaintained plugins is noted as deferred to the CLI Working Group and TOC. If the plugin repository changes prove to be a larger body of work than anticipated, a separate RFC will be proposed to cover that scope.
There was a problem hiding this comment.
In general I'm not a fan of splitting related context out into separate RFCs. There is no need to split things out into a new RFC even if the change proves to be a larger body of work. From the TOCs point of view we want to track progress still top level. During implementation it can be split into multiple issues and PRs which all link back to the same RFC tracking issue.
There was a problem hiding this comment.
Noted. I will ruminate some more since we know the pieces but have not decided how to implement.
| **Scan** — AST-based analysis identifies V2 domain method calls, `CliCommand`/`cf curl` usage, internal CLI package imports, and traces which fields of returned models are actually accessed. | ||
|
|
||
| **Generate** — Reads the scan output (YAML) and produces a single `v2compat_generated.go` file with minimal V3 replacements. If a plugin uses `GetApp` only for `.Guid` and `.Name`, the generated code makes 1 V3 API call and populates 2 fields — compared to the 10+ calls a full reimplementation requires. | ||
|
|
There was a problem hiding this comment.
The proposed tool can be used the identify the pain points that need to be updated, but ultimately the repository owner needs to do that, and failing to do so, should result in it either being removed from the cli repo, or have its metadata updated with up to which version is it compatible with (although... as mentioned, while it may be compatible with the latest cli version, the plugin itself is not compatible with v3 capi, so, it will still be deprecated without a proper update)
There was a problem hiding this comment.
Agreed that repository owners bear responsibility for updating their plugins. The new metadata section addresses the compatibility tagging aspect — the scan tool provides an objective basis for identifying which plugins have v2 dependencies. The decision on whether unmaintained plugins should be removed from the CLI plugin repository is appropriately deferred to the CLI Working Group and TOC. If the plugin repository work becomes a larger body of work, a separate RFC will be proposed to cover that scope.
…tion, add repo reference
5 participants
Summary
The CF CLI plugin interface exposes 10 methods that return CAPI V2-shaped data. With CAPI V2 reaching end of life (RFC-0032), these methods will stop working — affecting at least 20 actively maintained plugins.
This RFC proposes a guest-side transitional migration that plugin developers can adopt today, without waiting for CLI team changes or a new plugin interface. A companion tool (
cf-plugin-migrate) scans a plugin's source code, identifies V2 usage, and generates drop-in replacement code backed by CAPI V3 via go-cfclient. The approach requires no host (CLI) changes and works with any existing CF CLI version.Key Points
cf/terminal,cf/trace,cf/configuration) — companion replacement packages are proposedRelated
cc @cloudfoundry/toc