weiguoqiang/cert-manager
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

Add installing on OpenShift guide

Browse Source 
Signed-off-by: James Munnelly <james@munnelly.eu>
This commit is contained in:
James Munnelly 2019-05-08 14:47:05 +01:00
parent 98f67a88aa
commit c0085f47b2
5 changed files with 124 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/getting-started/index.rst
View File

@ -11,6 +11,6 @@ check the :doc:`troubleshooting <./troubleshooting>` document.
:maxdepth: 2
:caption: Contents:
install
install/index
webhook
troubleshooting

16
docs/getting-started/install/index.rst Normal file
View File

@ -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

15
docs/getting-started/install.rst → docs/getting-started/install/kubernetes.rst
View File

@ -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

99
docs/getting-started/install/openshift.rst Normal file
View File

@ -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 </tasks/issuers/index>`.
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 </tasks/issuers/index>` 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/

1
docs/redirects
View File

@ -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