docs: nVersionCount support for KMP design doc

[duffney]

Description

Design document for nVersionCount support for the KMP.

Type of change

• documentation

Post Merge Requirements

• MAINTAINERS: manually trigger the "Publish Package" workflow after merging any PR that indicates Helm Chart Change

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

see 131 files with indirect coverage changes

[susanshi]

thanks for the proposal @duffney. Added some suggestion.

[susanshi]

Suggestion to include a CR example with maxVersionCount parameter

[susanshi]

Suggestion to add example of the output of "describe" command. Customer should be able to see the versions fetched. If a version is disabled, I m thinking we could:

• log a warning that cert was skipped due to cert disabled state
• agreed we should not cache disabled version

[duffney]

Are there scenarios where a customer might not want Ratify to fully match the upstream secret store? If limiting the number of versions in Ratify isn’t necessary, would it make sense to introduce a syncVersions option at the provider level to automatically keep Ratify in sync with all versions from the upstream store? This would relieve customers from managing version limits manually.

[susanshi]

Are there scenarios where a customer might not want Ratify to fully match the upstream secret store? If limiting the number of versions in Ratify isn’t necessary, would it make sense to introduce a syncVersions option at the provider level to automatically keep Ratify in sync with all versions from the upstream store? This would relieve customers from managing version limits manually.

Discussed in PR review meeting , we want to use existing patterns from secret store csi driver with a version count configured for now.

[duffney]

@yizha1 & @FeynmanZhou would you mind reviewing the proposal to see if it's in alignment with your expectations. Thanks!

[yizha1]

Thanks @duffney I just left several comments.

[yizha1]

The parameter name maxVersionCount seems not intuitive. For example, the default value 0 means max version count is 0 , however, we will cache one version, the latest one, right? If the value is 1, we cached two versions. Maybe using maxPreviousVersionCount or previousVersionCount is better? Additonally, using max is also a bit confusing for me, for example, if the value is 2, does that mean at maximum, two versions are cached, but caching one version is still OK?

Since it means the cached versions, how about using the parameter name cachedVersionCount or cachedPreviousVersionCount?

[susanshi]

discussed during community meeting. we want to avoid 'cache' as this is implementation detail. We are proposing , "syncVersionCount", and given @duffney 's research that 3 is a common default. We propose to stay with 3 as the default.

[binbin-li]

not a strong opinion, just posting a var name recommended by Chatgpt, versionsFetchLimit

[duffney]

secret store uses objectVersionHistory, so perhaps a good name for us would be certificateVersionHistory? or simply versionHistory?

[susanshi]

discussed during community meeting, we would go with "versionHistory"

[junczhu]

Vote for versionHistory

[yizha1]

+1 for versionHistory

[yizha1]

Maybe we can start with 2, which means we will cache the latest version and one previous version.

[duffney]

That does break away from the pattern secret store driver has, but I'm not opposed.

It does bring up an interesting point, what exactly is the int counting for the value of the history? Is it the total number of the versions stored in the KMP or latest +n? for example the secret store, always stores latest and then if you specify to store one more than latest you would pass 1 to the objectVersionHistory option.

[susanshi]

discussed during community meeting, versionHistory defaults to 2 （ keeping 3 version)

[yizha1]

discussed during community meeting, versionHistory defaults to 2 （ keeping 3 version)

LGTM. One current version, 2 history versions

[duffney]

The design doc has been updated to reflect all the decisions that came from the last two weeks of community meeting discussions and comments.