diff --git a/docs/getting-started/index.rst b/docs/getting-started/index.rst index b505cf3e3..975db5ed4 100644 --- a/docs/getting-started/index.rst +++ b/docs/getting-started/index.rst @@ -11,6 +11,6 @@ check the :doc:`troubleshooting <./troubleshooting>` document. :maxdepth: 2 :caption: Contents: - install + install/index webhook troubleshooting diff --git a/docs/getting-started/install/index.rst b/docs/getting-started/install/index.rst new file mode 100644 index 000000000..741118c05 --- /dev/null +++ b/docs/getting-started/install/index.rst @@ -0,0 +1,16 @@ +======================= +Installing cert-manager +======================= + +cert-manager supports running on Kubernetes_ and OpenShift_. The installation +mechanism between the two platforms is similar, although there are a number +of extra notes to be aware of per-platform. + +.. toctree:: + :maxdepth: 1 + + kubernetes + openshift + +.. _Kubernetes: https://kubernetes.io +.. _OpenShift: https://www.openshift.com diff --git a/docs/getting-started/install.rst b/docs/getting-started/install/kubernetes.rst similarity index 97% rename from docs/getting-started/install.rst rename to docs/getting-started/install/kubernetes.rst index b761e5012..88bcde461 100644 --- a/docs/getting-started/install.rst +++ b/docs/getting-started/install/kubernetes.rst @@ -1,6 +1,6 @@ -======================= -Installing cert-manager -======================= +======================== +Installing on Kubernetes +======================== cert-manager runs within your Kubernetes cluster as a series of deployment resources. It utilises `CustomResourceDefinitions`_ to configure Certificate @@ -48,7 +48,7 @@ cert-manager runs in: # Disable resource validation on the cert-manager namespace kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true -You can read more about the webhook on the :doc:`webhook document <./webhook>`. +You can read more about the webhook on the :doc:`webhook document <../webhook>`. We can now go ahead and install cert-manager. All resources (the CustomResourceDefinitions, cert-manager, and the webhook component) @@ -159,7 +159,7 @@ state, and the ``ca-sync`` pod is Completed. If the webhook has not Completed but the ``cert-manager`` pod has recently started, wait a few minutes for the ``ca-sync`` pod to be retried. If you experience problems, please check the -:doc:`troubleshooting guide <./troubleshooting>`. +:doc:`troubleshooting guide <../troubleshooting>`. The following steps will confirm that cert-manager is set up correctly and able to issue basic certificate types: @@ -225,7 +225,7 @@ to issue basic certificate types: If all the above steps have completed without error, you are good to go! If you experience problems, please check the -:doc:`troubleshooting guide <./troubleshooting>`. +:doc:`troubleshooting guide <../troubleshooting>`. Configuring your first Issuer ============================= @@ -263,7 +263,7 @@ Debugging installation issues ============================= If you have any issues with your installation, please refer to the -:doc:`troubleshooting guide <./troubleshooting>`. +:doc:`troubleshooting guide <../troubleshooting>`. .. _`CustomResourceDefinitions`: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/ .. _`Helm chart README`: https://github.com/jetstack/cert-manager/blob/release-0.8/deploy/charts/cert-manager/README.md @@ -275,7 +275,6 @@ If you have any issues with your installation, please refer to the .. _`installing helm docs`: https://github.com/kubernetes/helm/blob/master/docs/install.md .. _Tiller: https://github.com/helm/helm .. _`Tillerless Helm v2`: https://rimusz.net/tillerless-helm/ -.. _`Let's Encrypt`: https://letsencrypt.org .. _`Bitnami Kubernetes Production Runtime`: https://github.com/bitnami/kube-prod-runtime/ .. _`regularly tested`: https://github.com/bitnami/kube-prod-runtime/blob/master/Jenkinsfile .. _`BKPR installation guide`: https://github.com/bitnami/kube-prod-runtime/blob/master/docs/install.md diff --git a/docs/getting-started/install/openshift.rst b/docs/getting-started/install/openshift.rst new file mode 100644 index 000000000..7047e73cc --- /dev/null +++ b/docs/getting-started/install/openshift.rst @@ -0,0 +1,99 @@ +======================= +Installing on OpenShift +======================= + +cert-manager supports running on OpenShift in a similar manner to :doc:`Running on Kubernetes <./kubernetes>`. +It runs within your OpenShift cluster as a series of deployment +resources. +It utilises `CustomResourceDefinitions`_ to configure Certificate +Authorities and request certificates. + +It is deployed using regular YAML manifests, like any other application on +OpenShift. + +Once cert-manager has been deployed, you must configure Issuer or ClusterIssuer +resources which represent certificate authorities. +More information on configuring different Issuer types can be found in the +:doc:`respective setup guides `. + +Login to your OpenShift cluster +=============================== + +Before you can install cert-manager, you must first ensure your local machine +is configured to talk to your OpenShift cluster using the ``oc`` tool. + +.. code-block:: shell + + # Login to the OpenShift cluster + oc login + +Installing with regular manifests +================================= + +In order to install cert-manager, we must first create a namespace to run it +within. This guide will install cert-manager into the ``cert-manager`` +namespace. It is possible to run cert-manager in a different namespace, +although you will need to make modifications to the deployment manifests. + +.. code-block:: shell + + # Create a namespace to run cert-manager in + oc create namespace cert-manager + +As part of the installation, cert-manager also deploys a +`ValidatingWebhookConfiguration`_ resource in order to validate that the +Issuer, ClusterIssuer and Certificate resources we will create after +installation are valid. + +In order to deploy the ValidatingWebhookConfiguration, cert-manager creates +a number of 'internal' Issuer and Certificate resources in its own namespace. + +This creates a chicken-and-egg problem, where cert-manager requires the +webhook in order to create the resources, and the webhook requires cert-manager +in order to run. + +We avoid this problem by disabling resource validation on the namespace that +cert-manager runs in: + +.. code-block:: shell + + # Disable resource validation on the cert-manager namespace + oc label namespace cert-manager certmanager.k8s.io/disable-validation=true + +You can read more about the webhook on the :doc:`webhook document <../webhook>`. + +We can now go ahead and install cert-manager. All resources +(the CustomResourceDefinitions, cert-manager, and the webhook component) +are included in a single YAML manifest file: + +.. code-block:: shell + + # Install the CustomResourceDefinitions and cert-manager itself + oc apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.8.0-beta.0/cert-manager-openshift.yaml + +.. note:: + The ``--validate=false`` flag is added to the ``oc apply`` command above + else you will receive a validation error relating to the ``caBundle`` field + of the ``ValidatingWebhookConfiguration`` resource. + + +Configuring your first Issuer +============================= + +Before you can begin issuing certificates, you must configure at least one +Issuer or ClusterIssuer resource in your cluster. + +You should read the :doc:`Setting up Issuers ` guide to +learn how to configure cert-manager to issue certificates from one of the +supported backends. + +Debugging installation issues +============================= + +If you have any issues with your installation, please refer to the +:doc:`troubleshooting guide <../troubleshooting>`. + +.. _`CustomResourceDefinitions`: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/ +.. _`Helm chart README`: https://github.com/jetstack/cert-manager/blob/release-0.8/deploy/charts/cert-manager/README.md +.. _`kubernetes/kubernetes#69590`: https://github.com/kubernetes/kubernetes/issues/69590 +.. _`ValidatingWebhookConfiguration`: https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/ diff --git a/docs/redirects b/docs/redirects index 752096278..44e186e3a 100644 --- a/docs/redirects +++ b/docs/redirects @@ -1,6 +1,7 @@ admin/resource-validation-webhook.rst getting-started/webhook.rst getting-started/1-configuring-helm.rst getting-started/install.rst getting-started/2-install.rst getting-started/install.rst +getting-started/install.rst getting-started/install/index.rst getting-started/3-configuring-first-issuer.rst tasks/issuers/index.rst tasks/acme/issuing-certificates.rst tasks/issuers/setup-acme/index.rst tasks/issuers/setup-acme.rst tasks/issuers/setup-acme/index.rst