search

cert-manager / website

Source code for the cert-manager.io website, including project documentation
https://cert-manager.io
Apache License 2.0
54 stars 335 forks source link

HTTP Validation, privateKeySecretRef #554

Open johngrabner opened 3 years ago

johngrabner commented 3 years ago

Thank you for this very useful application. I offer this issue in the context of someone new to cert-manager.

documentation in question

Someone new to cert-manager (like me) may be overwhelmed with details, not knowing what configuration needs to be correlated with other configuration, or what information is about usage vs information about internal implementation.

The comment for privateKeySecretRef is # Name of a secret used to store the ACME account private key. This does not make it clear that this secret does not need to correlate to anything else in userspace or anything else the user needs to configure to use cert-manager, or that it will not appear a a secret in user namespace.

Suggestion #1 Make this configuration parameter optional, since it's data that only the acme manager will use and store in its namespace. Suggestion #2 If you will not make it optional, suggest the comment be changed to 

#  Cert-manager will store your  ACME account private key in namespace cert-manager using this key.
# This key does not need to match any other data the user will configure.  A set and forget value.
privateKeySecretRef:
      name: letsencrypt-staging

Please let me know if there is some other use for this configuration data.

irbekrm commented 3 years ago

Hi @johngrabner ,

Thanks for opening the issue.

There are scenarios where the user would need it:

1) If you want to re-use an existing ACME account https://cert-manager.io/docs/configuration/acme/#reusing-an-acme-account

2) Users may sometimes need to delete the Secret to force a new account key to be generated, see i.e https://community.letsencrypt.org/t/dns-challenge-caching/49703

3) Potentially some more that I cannot think of right now

So generally, I feel like it is useful for the users to be aware that this is where the ACME account key is stored when the time comes to debug something- it's not quite a 'set and forget' value I think.

Agree that it could be documented better though- suggestions are welcome 😄