From 1c57feb523ec5c2d43ddd4496da2b590e5ad657d Mon Sep 17 00:00:00 2001 From: Euan Kemp Date: Fri, 23 Mar 2018 16:15:00 -0700 Subject: [PATCH] docs: add ambient credentials documentation --- docs/user-guides/ambient-credentials.md | 46 +++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/user-guides/ambient-credentials.md diff --git a/docs/user-guides/ambient-credentials.md b/docs/user-guides/ambient-credentials.md new file mode 100644 index 000000000..cad6f490c --- /dev/null +++ b/docs/user-guides/ambient-credentials.md @@ -0,0 +1,46 @@ +# Ambient Credentials + +Some API clients are able to infer credentials to use from the environment they +run within. Notably, this includes cloud instance-metadata stores and +environment variables. +In cert manager, the term 'ambient credentials' refers +to such credentials. They are always drawn from the environment of the 'cert-manager-controller' deployment. + +## Example Usage + +If cert-manager is deployed in an environment with ambient AWS credentials, such as with a [kube2iam](https://github.com/jtblin/kube2iam) role, the following ClusterIssuer would make use of those credentials to perform the ACME dns challenge with route53. + +```yaml +apiVersion: certmanager.k8s.io/v1alpha1 +kind: ClusterIssuer +metadata: + name: letsencrypt-prod +spec: + acme: + server: https://acme-v01.api.letsencrypt.org/directory + email: user@example.com + privateKeySecretRef: + name: letsencrypt-prod + dns01: + providers: + - name: route53 + route53: + region: us-east-1 +``` + +It is important to note that the `route53` section does not specify any `accessKeyID` or `secretAccessKeySecretRef`. If either of these are specified, ambient credentials will not be used. + +## When are Ambient Credentials used + +Ambient credentials are supported for the 'route53' ACME dns01 provider. + +They will only be used if no credentials are supplied, even if the supplied credentials are incorrect. + +By default, they may be used by ClusterIssuers, but not regular issuers. The +`--issuer-ambient-credentials` and +`--cluster-issuer-ambient-credentials=false` flags on the cert-manager may be +used to override this behavior. + +Note that ambient credentials are disabled for regular Issuers by default to +ensure unprivileged users who may create issuers cannot issue certificates +using any credentials cert-manager incidentally has access to.