Cert-manager: letsencrypt documentation unclear or missing configuration options

[monotek]

Is this a BUG REPORT or FEATURE REQUEST?:

Uncomment only one, leave it on its own line:

/kind bug
/kind feature

What happened:
I've tried to install cert-manager via Helm, following the docs from:
https://github.com/jetstack/cert-manager/blob/master/docs/user-guides/deploying.md

Shim pod logs show a lot of these errors:

I0131 16:05:27.006009       1 controller.go:147] ingress-shim controller: syncing item 'infrastructure/grafana-grafana'
E0131 16:05:27.006127       1 controller.go:156] ingress-shim controller: Re-queuing item "infrastructure/grafana-grafana" due to error processing: clusterissuer.certmanager.k8s.io "letsencrypt-staging" not found

What you expected to happen:
Automatic Letsencrypt configuration and creation of https certificates.

How to reproduce it (as minimally and precisely as possible):

• Install cert-manager via:
  helm install stable/cert-manager --name cert-manager --namespace=infrastructure -f values.yaml
• Add "kubernetes.io/tls-acme: 'true'" to your ingress: controllers.
• Use this values file:

# Optional additional arguments
extraArgs: []

ingressShim:
  enabled: true

  # Optional additional arguments for ingress-shim
  extraArgs: ['--default-issuer-name=letsencrypt-staging', '--default-issuer-kind=ClusterIssuer']

createCustomResource: true

rbac:
  # Specifies whether RBAC resources should be created
  create: true

serviceAccount:
  # Specifies whether a service account should be created
  create: true

Anything else we need to know?:
Coming from kube-lego i know that there should be a place where the letsencrypt registration email and api url are configured, but the docs are not saying a word about this.

Imho the cluster-issuer for letsencrypt should more look like this one: https://github.com/jetstack/cert-manager/blob/master/docs/examples/cluster-issuer.yaml

But the one i get from "helm get cert-manager" is:

# Source: cert-manager/templates/clusterissuer-crd.yaml
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
  name: clusterissuers.certmanager.k8s.io
  labels:
    app: cert-manager
    chart: cert-manager-0.2.1
    release: cert-manager
    heritage: Tiller
spec:
  group: certmanager.k8s.io
  version: v1alpha1
  names:
    kind: ClusterIssuer
    plural: clusterissuers
  scope: Cluster

If i miss some configuration for this the documentation should be extended.
If there is no way to configure this via the values.yaml i consider this a missing feature.

Environment:

• Kubernetes version (use kubectl version): 1.8.5
• Cloud provider or hardware configuration**: Google
• Install tools: Helm 2.7.2
• Others:

[whereisaaron]

Hi @monotek, you are doing everything right, but you've missed one last step. You haven't created the ClusterIssuer you named in --default-issuer-name=letsencrypt-staging. In the ClusterIssuer resource is where you configure the email and API URL. kube-lego only supports one issuer, but cert-manager supports any number.

That's why the error is clusterissuer.certmanager.k8s.io "letsencrypt-staging" not found. You can easily create one e.g.

apiVersion: certmanager.k8s.io/v1alpha1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    server: https://acme-staging.api.letsencrypt.org/directory
    email: [email protected]
    privateKeySecretRef:
      name: letsencrypt-staging
    http01: {}

[monotek]

Hi @whereisaaron ,

yes, thats what i also recognized, when i had used "helm get cert-manager".

But if this part is missing, how to add it via the Helm chart at the moment?
If this is not possible, the Helm chart feels kind of incomplete to me.
I don't think one should have to add this via "kubectl apply -f letsencrypt-staging.yaml".

[monotek]

What about something like this:?

https://github.com/monotek/cert-manager/commit/fd5f24cab1493541a76f6b91dc06d15fab6f991d

[whereisaaron]

Currently you create the Issuer/ClusterIssuer separately, since everyone needs are different. Only using Letsencrypt and http01 is common though, for converting kube-lego users. I agree it would be great to have the option to create a default ClusterIssuer, even if just for Letsencrypt and http01. It should be optional though, but I'd say it could be created by default for LE staging.

Your Helm template example looks pretty good, but I suggest:

1. you call the whole configuration clusterIssuer rather than letsencrypt, Lets Encrypt is only one possible ACME provider, and you can use the chart to configure for other ACME provider URLs, so will cause confusion later if we call it letsencrypt
2. You should make each provider optional. The will eventually be dozens of different providers and not everyone will want them all.
3. You need to support multiple providers accpunts of the same type (AWS, Cloudflare, etc.), since many people will be issuing certificates for domains spread across e.g. multiple AWS accounts.
4. The same certificate can have domain handled by http01 and dns01, so they should not be mutually exclusive, you should be able to have both in the same Issuer/ClusterIssuer (so separate enabled options).

Rather than map every possible value of all providers, it may be easier to just let everyone enter the providers using the Issuer/Cluster syntax in the Helm values.yaml, and just include everything verbatim into the ClusterIssuer template with something like:

spec:
  acme:
    ...
    dns01:
{{ include "toYaml" .Values.clusterIssuer.providers | indent 8 }}

When you get it working, you can PR it for @munnerz to review.

[orian]

@whereisaaron I had a problem with finding: https://github.com/jetstack/cert-manager/blob/22ed25955d424e40c9b84f822ca96a4a563eac42/pkg/apis/certmanager/v1alpha1/types.go

Any idea why godoc.org may have problems indexing it? It's a pretty good documentation.
The doc: https://github.com/jetstack/cert-manager/tree/master/docs/api-types/certificate is missing Ingress field.

Also, what will happen if I specify acme.config.http01.Ingress but leave domains empty?

[whereisaaron]

@orian you only need to specify an ingress in the Certificate if you want a particular Ingress resource to be modified. And you only need to specify domains if you what different domain challenges handled differently.

No idea about the godoc issue sorry.

[zamai]

Hey @whereisaaron I've think I've experienced the same path that @monotek took. I'm coming from kube-lego and my expectation that helm chart should handle the letsencrypt out of the box. If user want to use cert-manager they have to have at least one provider, thus implementing general Issuer chart would be a nice place to start and have the letsencrypt as an example there.
I want to know is that something on the roadmap?

[munnerz]

@zamai please see https://github.com/jetstack/cert-manager/issues/259 for more info.

I am open to accepting a second chart in the repository for this. However, for the reasons described in #259 we cannot simply add it to the main chart.

[monotek]

@munnerz
So i should skip adding a pull request for it?

[whereisaaron]

@zamai I think we are all agreed the an easy option to bootstrap with LE, even as the default, is a good idea. There are technical difficulties for helm though, since you can't have CRDs in the chart until the CRDs are created (chart validation will fail, blocking the install), which is not until after cert-manager deploys (#259).

Options are:
(1) to mess with some real ugly helm lifecycle hooks to create the CRD resources post-install,
(2) to make a separate cert-manager-lets-encrypt chart that you install as a second step. The second helm chart with CRDs in it will validate and work, because cert-manager is already running and has created the CRDs

helm install cert-manager --set ingressShim.extraArgs='{--default-issuer-name=letsencrypt-prod,--default-issuer-kind=ClusterIssuer}'
helm install cert-manager-lets-encrypt --set [email protected]

So the two commands would get you a fully operation cert-manager with LE HTTP-01 support using the usual Ingres annotation.

[monotek]

If a second chart is the only suitable solution at the moment a second chart could be connected via requirements.yaml. So you still have only to enter one "helm install" command...

[munnerz]

I'm not sure that's possible, but I'd be open to depending on it via requirements if it is possible.

As far as I'm aware though, Helm validates all resources at once before installing (so that it can prevent half-installed charts). This will likely prevent it working even with requirements.yaml.

If that's the case, a second chart is likely the best way to go (and also least intrusive to other users who don't want this).

[monotek]

Hmmm... I expected that dependencies are installed before the parent chart. To bad if not.

So maybe charts hooks would be an option too: https://github.com/kubernetes/helm/blob/master/docs/charts_hooks.md

[munnerz]

Chart hooks suffer from the same issue - all the resources are validated at once, so it fails due to the CRDs not existing in the apiserver yet,

Other projects have created a post-start hook Pod resource, that runs kubectl create in order to create the resources. I'm not a fan of this approach as it isn't particularly secure, and requires some hacking around RBAC permissions.

[munnerz]

See: https://github.com/kubernetes/helm/issues/2994

[amasucci]

I had exactly the same problem, I found the docs really unclear, that’s why immediately I managed to make it work I put down a how-to https://amasucci.com/post/2018/03/17/how-to-generate-tls-certificates-with-cert-manager-and-lets-encrypt-in-kubernetes/ feel free to reference or copy it. I think this is a cool project but docs deserve more love. Hope this helps.

[tuananh]

@amasucci That's awesome. Thanks

I think most of users are looking for how to setup this with Lets Encrypt. Let's make the default options more sensible?

[sourcesoft]

@amasucci Just wanted to say that I love you.

[amasucci]

@sourcesoft 🤭 Thanks 😁

[munnerz]

Closing in favour of #259