diff --git a/docs/reference/ingress-shim.rst b/docs/reference/ingress-shim.rst index dd56f8d34..1934d720a 100644 --- a/docs/reference/ingress-shim.rst +++ b/docs/reference/ingress-shim.rst @@ -69,7 +69,7 @@ Certificate resources to be automatically created: configuration of the ingress-shim (see above). Namely, a default issuer must be specified as arguments to the ingress-shim container. -* ``certmanager.k8s.io/acme-http01-edit-in-place""`` - if the ACME challenge type +* ``certmanager.k8s.io/acme-http01-edit-in-place: "true"`` - if the ACME challenge type has been set to http01, and the ingress has the 'kubernetes.io/tls-acme: true' annotation, this controls whether the ingress is modified 'in-place', or a new one created specifically for the http01 challenge. If present, and set to "true" diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index b6e175798..79be77f5b 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -11,3 +11,4 @@ cert-manager. acme/index ca/index vault/index + upgrading/index diff --git a/docs/tutorials/upgrading/index.rst b/docs/tutorials/upgrading/index.rst new file mode 100644 index 000000000..f450245cd --- /dev/null +++ b/docs/tutorials/upgrading/index.rst @@ -0,0 +1,12 @@ +====================== +Upgrading cert-manager +====================== + +This section contains information on upgrading cert-manager. +It also contains documents detailing breaking changes between cert-manager versions, +and information on things to look out for when upgrading. + +.. toctree:: + :maxdepth: 1 + + upgrading-0.2-0.3 diff --git a/docs/tutorials/upgrading/upgrading-0.2-0.3.rst b/docs/tutorials/upgrading/upgrading-0.2-0.3.rst new file mode 100644 index 000000000..01f5b5bba --- /dev/null +++ b/docs/tutorials/upgrading/upgrading-0.2-0.3.rst @@ -0,0 +1,138 @@ +=========================== +Upgrading from v0.2 to v0.3 +=========================== + +During the v0.3 release, a number of breaking changes were made that require you +to update either deployment configuration and runtime configuration (e.g. Certificate, +Issuer and ClusterIssuer resources). + +After reading these instructions, you should then proceed to upgrade cert-manager +according to your deployment configuration (e.g. using ``helm upgrade`` if installing +via Helm chart, or ``kubectl apply`` if installing with raw manifests). + +A brief summary: + +* Supporting resources for ClusterIssuers (e.g. signing CA certificates, or + ACME account private keys) will now be stored in the same namespace as + cert-manager, instead of kube-system in previous versions (#329, @munnerz) + +* Switch to ConfigMaps instead of Endpoints for leader election (#327, @mikebryant) + +* Removing support for ACMEv1 in favour of ACMEv2 (#309, @munnerz) + +* Removing ingress-shim and compiling it into cert-manager itself (#502, @munnerz) + +* Change to the default behaviour of ingress-shim. It now generates Certificates + with the ``ingressClass`` field set instead of the ``ingress`` field. This will + mean users of ingress controllers that assign a single IP to a single Ingress (e.g. + the GCE ingress controller) will no longer work without adding a new annotation + to your ingress resource. + +Supporting resources for ClusterIssuers moving into the cert-manager namespace +============================================================================== + +In the past, the cert-manager controller was hard coded to look for supplemental +resources, such as Secrets containing DNS provider credentials, in the kube-system +namespace. + +We now store these resources in the same namespace as the cert-manager pod itself +runs within. + +When upgrading, you should make sure to move any of these supplemental resources into +the cert-manager deployment namespace, or otherwise deploy cert-manager into kube-system +itself. + +You can also change the 'cluster resource namespace' when deploying cert-manager: + +With the helm chart: ``--set clusterResourceNamespace=kube-system``. + +Or if using the static deployment manifests, by adding the ``--cluster-resource-namespace`` +flag to the ``args`` field of the cert-manager container. + +Switch to ConfigMaps instead of Endpoints for leader election +============================================================= + +cert-manager-controller performs leader election to allow you to run 'hot standby' +replicas of cert-manager. + +In the past, we used Endpoint resources to perform this election. +The new best practice is to use ConfigMap resources in order to reduce API overhead +in large clusters. + +As such, v0.3 switches us to use ConfigMap resources for leader election. + +During the upgrade, you should first scale your cert-manager-controller deployment +to 0 to ensure no other replicas of cert-manager are running when the new v0.3 +deployment starts: + +.. code-block:: shell + + kubectl scale --namespace --replicas=0 deployment + +Removing support for ACMEv1 in favour of ACMEv2 +=============================================== + +The ACME v2 specification is now in production with Let's Encrypt. +In order to support this new spec, which includes support for wildcard certificates, +we have removed support for the v1 protocol altogether. + +If you have any ACME Issuer or ClusterIssuer resources, you should update the +server fields of these to the new ACMEv2 endpoints. + +For example, if you have a Let's Encrypt production issuer, you should update the +server URL: + +.. code-block:: yaml + + apiVersion: certmanager.k8s.io/v1alpha1 + kind: Issuer + ... + spec: + acme: + # server: https://acme-v01.api.letsencrypt.org/directory + server: https://acme-v02.api.letsencrypt.org/directory # we switch 'v01' to 'v02' + +Removing ingress-shim and compiling it into cert-manager itself +=============================================================== + +In v0.3 we removed the ingress-shim component and instead now compile in its +functionality into the main cert-manager binary. + +This change also introduces a change to the way you configure default Issuers +and ClusterIssuers at deployment time. + +The deployment documentation has been updated accordingly, but instead of setting +``ingressShim.extraArgs={--default-issuer-name=letsencrypt-pod}`` there are +now dedicated Helm chart fields: + +.. code-block:: shell + + --set ingressShim.defaultIssuerName=letsencrypt-prod \ + --set ingressShim.defaultIssuerKind=ClusterIssuer + +Change to the default behaviour of ingress-shim +=============================================== + +In the past, when using ingress-shim, we set the ``ingress`` field on the Certificate +resource to trigger cert-manager to edit the specified Ingress resource to solve +the challenge. + +The alternate option is to set the ``ingressClass`` field, which causes cert-manager +to create temporary Ingress resources to solve the challenge. This behaviour provides +better compatibility with ingress controllers like nginx-ingress_. + +In v0.3 we have changed the default behaviour of ingress-shim to set the ``ingressClass`` +field instead of ``ingress``. + +This will cause validations for ingress controllers like ingress-gce_ to fail without +additional configuration in your Ingress resources annotations. + +Add the follow annotation to your Ingress resources if you are using the GCE ingress +controller, in addition to the usual ingress-shim annotation(s): + +.. code-block:: yaml + + certmanager.k8s.io/acme-http01-edit-in-place: "true" + +.. _nginx-ingress: https://github.com/kubernetes/ingress-nginx +.. _ingress-gce: https://github.com/kubernetes/ingress-gce \ No newline at end of file