clarify SetCAOnCertificateRequest deprecation status

[terinjokes]

The argument for deprecating SetCAOnCertificateRequest seems to be that using the secret's ca.crt key for peer validation is a bad idea¹. I agree that peer validation is better solved through other means.

While most servers are happy with just serving a leaf certificate, and expecting the client to be able to make a chain back to a trusted root, some servers insist on having a valid CA certificate available for the leaf certificate before (re-)starting their services. When developing external issuers to be used outside the WebPKI use case, those CA roots may be vary dynamic: such as changing at renewal or being specific to individual issuer instances. Setting ca.crt on the secret allows for these servers to pickup the new CA root at the same time they reload the leaf certificate.

Removing this functionality makes these use cases much more difficult. It would require the controller to coordinate changes simultaneously across multiple resources. These use cases would also be dependent on kubelet synchronizing caches of the multiple resources close enough together in time, and it would still break the atomic filesystem updates currently observed by servers of mounted secrets.

1. Is the deprecation of this a signal that it will be removed in N+X versions, or is it in the spirit of Go 1's deprecation notice, where it's just to discourage new use (unless you know you need it)?
2. Should the GoDoc be updated to clarify that the use of ca.crt for peer validation is discouraged (potentially linking to the FAQ), not necessarily the use by servers?

Footnotes

1. FAQ: Why isn't my certificate's chain in my issued Secret's ca.crt? ↩