VAULT-19278 Static secret caching docs

[VioletHynes]

The docs for the static secret caching feature!

As part of this PR, I corrected some capitalization of Agent and Proxy that seems to have been adjusted from the following PR: #21426. Proxy and Agent should be capitalized, just like Vault.

The feature isn't fully implemented yet (at time of raising this docs PR), but I had an opportune time to write these, and I can include an update to the docs if anything small needs to be updated, but I doubt anything major will change at this point.

[github-actions]

Build Results:
All builds succeeded! ✅

[github-actions]

CI Results:
All Go tests succeeded! ✅

[kubawi]

Hey, I've found two unfinished sentences that made it to the PR, so leaving a request changes, but other than these the docs look good. Thanks for taking the time to fix capitalisation in so many places, our docs will look slicker now.

[kubawi]

LGTM!

[finnstech]

Doesn't Vault Agent support static secret caching? This statement is misleading.

[VioletHynes]

It doesn't support static secret caching through it's API proxy -- while templating it does output templates to files, which acts like a cache in case of downtime but, the cache subsystem of Agent doesn't support it, nor does the API proxy.

I'll try and reword this so it's clearer! Thanks!

[finnstech]

(KVv1 and KVv2) through its API proxy, requiring less requests to be forwarded to Vault itself. We recommend

should be

(KVv1 and KVv2) through its API proxy, requiring fewer requests to be forwarded to Vault itself. We recommend

[VioletHynes]

Good spot! I always get less/fewer mixed up :P

[schavis]

I still need to review the new static secret doc, will try to get that done later this afternoon

[schavis]

If we think this note will be useful in other places in the future, I would recommend making it into a partial so it's easier to maintain the language going forward.

[VioletHynes]

We're planning on deprecating the API proxy aspect of Agent in the future, so (and perhaps this is optimistic), we'll hopefully be able to remove this when we do. To put it another way, though, we won't be adding any new functionality or pages to Agent's API proxy functionality

[schavis]

Suggested change

	Vault Proxy can be configured to cache KVv1 and KVv2 secrets as well as dynamic secrets described
	above. This means that, when enabled, subsequent requests to the same KV secret made via Proxy will
	only result in a single request made to Vault. Proxy will keep a single cache entry of the secret in its
	cache, and will only provide the cached response to requests made with tokens that can access the secret.
	You can configure Vault Proxy to cache dynamic secrets and static, KVv1 and KVv2
	secrets. When you enable caching for static secrets. Proxy keeps a cached entry
	of the secret but only provides the cached response to requests made with tokens
	that can access the secret. As a result, multiple requests to Vault Proxy for
	the same KV secret only require a single, initial request made to Vault.

Style correction: write in active voice, speak directly to the reader, avoid "this" as a pronoun

[VioletHynes]

Thanks! I slightly reworded the last sentence to hopefully be clearer:
initial request made to Vault
->
initial request to be forwarded to Vault

To hopefully make it clear that Proxy does the forwarding for you, and the client doesn't need to send the request to Vault itself

[VioletHynes]

I'll leave this un-resolved to give you a chance to review the updated wording -- let me know if you disagree and I can change it back :)

[schavis]

Suggested change

	If a token requests a KV secret, we store in the cache that this token has the capability to access a secret.
	Therefore, subsequent requests by the same token will be able to access this secret from the cache. For a second
	token to access the same secret, it must first complete a successful `GET` to the secret before its permission
	to access the secret is cached, and its subsequent requests can be served from the cache instead of Vault itself.
	Similarly, when a token requests access to a KV secret, it must complete a
	success `GET` request. If the request is successful, Proxy caches the fact that
	the token was successful in addition to the result. Subsequent requests by the
	same token can then access this secret from the cache instead of Vault.

Style correction: write in active voice, avoid repetitive statements

[VioletHynes]

This reads a little confusingly to me, since the token is cached as part of the client making the request, i.e. two requests are not required and it might sound like tokens are not part of client requests somehow? I think your version is still better, and I've updated it, but I wonder if we can still make it clearer

[schavis]

Suggested change

	Vault Proxy will also intermittently check the permissions of tokens that can access cache entries. This interval
	defaults to once every five minutes, but is configurable by the `static_secret_token_capability_refresh_interval` configuration.
	Every interval, Proxy will perform a call to [`sys/capabilies-self`](/vault/api-docs/system/capabilities-self) on
	each token's behalf to validate that it still has previously-demonstrated capabilities to read secrets from the cache.
	If there is a difference, and a permission (or the token itself) has been revoked, then the cache will be updated,
	and it will no longer be to able access those paths from the cache. Note that the `static_secret_token_capability_refresh_interval`
	configuration can be seen as the maximum period after which permission to read a KV secret can be revoked that a
	token will retain access.
	Vault Proxy also checks and refreshes the access permissions of known tokens
	according to the window set with `static_secret_token_capability_refresh_interval`.
	By default, the refresh interval is five minutes.
	Every interval, Proxy calls [`sys/capabilies-self`](/vault/api-docs/system/capabilities-self) on
	behalf of every token in the cache to confirm the token still has permission to
	access the cached secret. If the result from Vault indicates that permission (or
	the token itself) was revoked, Proxy updates the cache entry so that the affected
	token can no longer access the relevant paths from the cache. The refresh interval
	is essentially the maximum period after which permission to read a KV secret is
	fully revoked for the relevant token.
	For token refresh to work, any token that will access the cache also needs
	`update` permission for [`sys/capabilies-self`](/vault/api-docs/system/capabilities-self).
	Having `update` permission for the token lets Proxy test capabilities for the
	token against multiple paths with a single request instead of testing for a `403`
	response for each path explicitly.
	<Warning title="Refresh with API proxy may affect multiple clients">
	If API proxy is configured to use auto-authentication for tokens, **all**
	requests that pass through Vault Proxy use the same token. As result, Proxy
	makes a single request to Vault every refresh interval, no matter how many
	secrets are currently cached.
	</Warning>

Style correction: write in active voice, 1 idea per sentence. Also folds in content from earlier in the doc

[VioletHynes]

This was mostly great, but I updated the end for clarity as it was slightly inaccurate (or, at least, could be read in an inaccurate way). I'll leave this unresolved just in case you wanted to re-review.

[schavis]

Apologies for the delay, I pulled into a few things that distracted me for a bit. Let me know if you have any questions about the suggestions.

[finnstech]

Server

[finnstech]

"may be required in"

[VioletHynes]

Good catch! Updated