home/cert-manager
2
0
Fork 0
mirror of https://github.com/wahyd4/cert-manager.git synced 2026-08-09 05:06:38 +10:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2367 from munnerz/docs-redirects

Browse Source 
Add redirects to new documentation website
This commit is contained in:
jetstack-bot
2019-11-15 11:52:32 +00:00
committed by GitHub
parent c3cbaf7c76 1de8920bd7
commit 42a85a4866
108 changed files with 471 additions and 16169 deletions
Download Patch File Download Diff File Expand all files Collapse all files
BUILD.bazel
-1
View File
@@ -50,7 +50,6 @@ filegroup(
"//cmd/controller:all-srcs",
"//cmd/webhook:all-srcs",
"//deploy:all-srcs",
"//docs/generated/reference:all-srcs",
"//hack:all-srcs",
"//pkg/acme:all-srcs",
"//pkg/api:all-srcs",
WORKSPACE
-24
View File
@@ -103,30 +103,6 @@ load(
install_e2e_images()
# Load and define targets used for reference doc generation
load(
"//docs/generated/reference:deps.bzl",
install_docs_dependencies = "install",
)
install_docs_dependencies()
# The npm_install rule runs yarn anytime the package.json or package-lock.json file changes.
# It also extracts any Bazel rules distributed in an npm package.
load("@build_bazel_rules_nodejs//:defs.bzl", "npm_install")
npm_install(
# Name this npm so that Bazel Label references look like @brodocs_modules//package
name = "brodocs_modules",
package_json = "@brodocs//:package.json",
package_lock_json = "//docs/generated/reference/generate/bin:package-lock.json",
)
# Install any Bazel rules which were extracted earlier by the npm_install rule.
load("@brodocs_modules//:install_bazel_dependencies.bzl", "install_bazel_dependencies")
install_bazel_dependencies()
load("//hack/build:repos.bzl", "go_repositories")
go_repositories()
docs/_ext/externalredirect.py
+84
View File
@@ -0,0 +1,84 @@
"""
externalredirect
~~~~~~~~~~~~~~~~~~~~~~~
Generate redirects to external files based on a single 'external_redirects' file
"""
import os
from sphinx.builders import html as builders
from sphinx.builders import linkcheck as linkcheckbuilders
from sphinx.util import logging
TEMPLATE = """<html>
<head><meta http-equiv="refresh" content="0; url=%s"/></head>
</html>
"""
SRC_TEMPLATE = """==========
File moved
==========
This document has moved to %s.
This placeholder file will be removed in a later release.
"""
def generate_external_redirects(app, exception):
logger = logging.getLogger(__name__)
path = os.path.join(app.srcdir, app.config.external_redirects_file)
if not os.path.exists(path):
logger.info("Could not find redirects file at '%s'" % path)
return
in_suffix = app.config.source_suffix
if isinstance(in_suffix, list):
in_suffix = in_suffix[0]
if isinstance(in_suffix, dict):
logger.info("app.config.source_suffix is a dictionary type. "
"Defaulting source_suffix to '.rst'")
in_suffix = ".rst"
if type(app.builder) == linkcheckbuilders.CheckExternalLinksBuilder:
logger.info("Detected 'linkcheck' builder in use so skipping generating redirects")
return
if not (type(app.builder) == builders.StandaloneHTMLBuilder or type(app.builder) == builders.DirectoryHTMLBuilder):
logger.warn("The 'sphinxcontib-redirects' plugin is only supported "
"by the 'html' and 'dirhtml' builder, but you are using '%s'. Skipping..." % type(app.builder))
dirhtml = False
if type(app.builder) == builders.DirectoryHTMLBuilder:
dirhtml = True
with open(path) as redirects:
for line in redirects.readlines():
from_path, to_url = line.rstrip().split(' ')
orig_from_path = from_path
logger.info("Redirecting '%s' to '%s'" % (from_path, to_url))
if dirhtml:
from_path = from_path.replace(in_suffix, '/index.html')
else:
from_path = from_path.replace(in_suffix, '.html')
logger.info("Resolved redirect '%s' to '%s'" % (from_path, to_url))
redirected_filename = os.path.join(app.builder.outdir, from_path)
redirected_directory = os.path.dirname(redirected_filename)
if not os.path.exists(redirected_directory):
os.makedirs(redirected_directory)
logger.info("Writing to '%s'" % redirected_filename)
with open(redirected_filename, 'w') as f:
f.write(TEMPLATE % to_url)
input_rst_filename = os.path.join(app.srcdir, orig_from_path)
with open(input_rst_filename, 'w') as f:
f.write(SRC_TEMPLATE % to_url)
def setup(app):
app.add_config_value('external_redirects_file', 'external_redirects', 'env')
app.connect('build-finished', generate_external_redirects)
docs/conf.py
+5 -2
View File
@@ -26,8 +26,8 @@
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
import os
import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
@@ -48,12 +48,15 @@ release = u''
#
# needs_sphinx = '1.0'
sys.path.append(os.path.abspath("./_ext"))
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.todo',
'sphinxcontrib.redirects',
"externalredirect",
]
# Add any paths that contain templates here, relative to this directory.
docs/design/index.rst
+5 -6
View File
@@ -1,7 +1,6 @@
====================
Design and Proposals
====================
==========
File moved
==========
To view design documents please visit the link here_.
.. _here: https://github.com/jetstack/cert-manager/tree/master/design
This document has moved to https://cert-manager.netlify.com/docs.
This placeholder file will be removed in a later release.
docs/devel/dco-sign-off.rst
+5 -62
View File
@@ -1,63 +1,6 @@
============
DCO Sign off
============
==========
File moved
==========
All authors to the project retain copyright to their work. However, to ensure
that they are only submitting work that they have rights to, we are requiring
everyone to acknowledge this by signing their work.
Any copyright notices in this repo should specify the authors as "the Jetstack
cert-manager contributors".
To sign your work, just add a line like this at the end of your commit message:
.. code::
Signed-off-by: Joe Bloggs <joe@example.com>
This can easily be done with the ``--signoff`` option to ``git commit``.
You can also mass sign-off a whole PR with ``git rebase --signoff master``,
replacing ``master`` with the branch you are creating a pull request again if
not master.
By doing this you state that you certify the following (from https://developercertificate.org/):
.. code::
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
This document has moved to https://cert-manager.netlify.com/docs/contributing/sign-off/.
This placeholder file will be removed in a later release.
docs/devel/develop-with-minikube.rst
+5 -108
View File
@@ -1,109 +1,6 @@
=====================
Develop with minikube
=====================
==========
File moved
==========
Minikube is a tool to quickly provision a local Kubernetes cluster on many
platforms. It can be used to test and develop cert-manager. This guide will
walk you through getting started using Minikube for development.
Start minikube
==============
First, run minikube, and configure your local kubectl command to work with minikube; minikube typically does this automatically.
.. code-block:: shell
# Check your locally installed minikube version
$ minikube version
minikube version: v0.25.0
# Start a local cluster
# If using Minikube v0.25.0 or older:
$ minikube start --extra-config=apiserver.Authorization.Mode=RBAC
# Otherwise:
$ minikube start
# Verify it works. This should output a local apiserver IP
$ kubectl cluster-info
# Create a cluster role binding so Tiller has cluster-admin access rights
$ kubectl create clusterrolebinding default-admin --clusterrole=cluster-admin --serviceaccount=kube-system:default
# Install helm
$ helm init
Install local development tools
===============================
You will need the following tools to build cert-manager:
* Bazel_
* Docker_ (and enable for non-root user)
These instructions have only been tested on Linux and MacOS; Windows may
require further changes.
If you need to add dependencies, you will additionally need:
* Git_
* Mercurial_
You can then run ``./hack/update-vendor.sh`` to regenerate any
dependencies, and ``make build`` to build the docker images.
Build a dev version of cert-manager
===================================
.. code-block:: shell
# Configure your local docker client to use the minikube docker daemon
$ eval "$(minikube docker-env)"
# Build cert-manager binaries and docker images. Full output omitted for brevity
$ make build
Successfully tagged quay.io/jetstack/cert-manager-controller:canary
Deploy that version with helm
=============================
.. code-block:: shell
# Install custom resources before running helm
$ kubectl apply -f deploy/manifests/00-crds.yaml
# Install our freshly built cert-manager image
$ helm install \
--set image.tag=canary \
--set image.pullPolicy=Never \
--set cainjector.image.tag=canary \
--set cainjector.pullPolicy=Never \
--set webhook.image.tag=canary \
--set webhook.pullPolicy=Never \
--name cert-manager \
./deploy/charts/cert-manager
From here, you should be able to do whatever manual testing or development you wish to.
Deploy a new version
====================
In general, upgrading can be done simply by running `make build`, and then deleting the deployed pod using `kubectl delete pod`.
However, if you make changes to the helm chart or wish to change the controller's arguments, such as to change the logging level, you may also update it with the following:
.. code-block:: shell
helm upgrade \
cert-manager \
--reuse-values \
--set extraArgs="{-v=5}"
--set image.tag=build
./contrib/charts/cert-manager
.. _Bazel: https://docs.bazel.build/versions/master/install.html
.. _Docker: https://store.docker.com/search?type=edition&offering=community
.. _Git: https://git-scm.com/downloads
.. _Mercurial: https://www.mercurial-scm.org/
This document has moved to https://cert-manager.netlify.com/docs/contributing/kind/.
This placeholder file will be removed in a later release.
docs/devel/dns01-providers.rst
+5 -47
View File
@@ -1,48 +1,6 @@
============================
Contributing DNS01 providers
============================
==========
File moved
==========
----------
WARNING
----------
Because of the overwhelming number of PRs for new DNS providers, We're changing how we handle the DNS01 contributions. See `this post <https://groups.google.com/d/msg/cert-manager-dev/CgoMxSP6DSI/IyHp0BGfCQAJ>`_ on the mailing list for more information.
Steps to add a ``FooDNS`` DNS-01 provider:
1. Create a new package under ``pkg/issuer/acme/dns/foodns``.
This is where all the code to interact with the DNS providers API will live.
2. Implement functions to match the solver interface (``Present``, ``CleanUp`` and ``Timeout``).
Use an existing provider for reference.
Most of the cert-manager providers are based off
https://github.com/xenolf/lego, so if lego supports the DNS provider you
want to add, it's fairly easy to copy it over and make modifications to fit
with the cert-manager codebase. Examples of the changes required:
- replace uses of ``github.com/xenolf/lego/acme`` with ``github.com/jetstack/cert-manager/pkg/issuer/acme/dns/util``.
- replace uses of ``github.com/xenolf/lego/log`` with ``github.com/golang/glog``.
- remove references to ``github.com/xenolf/lego/platform/config/env``.
cert-manager does not use environment variables for internal configuration, so calls to this package should not be required.
3. Add unit test coverage for this package.
4. Add your provider configuration types to the API (located in ``pkg/apis/certmanager/v1alpha2/types.go``) and regenerate code (run ``./hack/update-codegen.sh``).
New API types should have an associated short documentation string,
which is added to the reference API documentation (run ``./hack/update-reference-docs-dockerized.sh`` to update the API documentation).
5. Register the provider in ``pkg/issuer/acme/dns``:
- The constructor for the provider needs adding to ``dnsProviderConstructors``,
- ``solverForIssuerProvider`` must be updated to handle retrieving any information for the new provider (for example, fetching credentials from a secret)
and constructing a new instance of the provider.
6. Add coverage for the provider to ``pkg/issuer/acme/dns/dns_test.go``.
7. Add example configuration for the new provider to ``docs/tasks/acme/configuring-dns01/``.
The more information here the better,
this example and corresponding documentation should inform users how to use and configure this backend,
as well as mentioning any nuances with using this particular provider.
8. Test your provider out against a real account, and make sure you can issue a Certificate.
9. Submit your new provider to cert-manager!
Things to watch out for:
- Assume that at any point the cert-manager process may restart.
Make sure values required for operations like ``CleanUp`` are not solely stored in memory.
This document has moved to https://cert-manager.netlify.com/docs/contributing/dns-providers/.
This placeholder file will be removed in a later release.
docs/devel/end-to-end-tests.rst
+5 -45
View File
@@ -1,46 +1,6 @@
========================
Running end-to-end tests
========================
==========
File moved
==========
cert-manager has an end-to-end test suite that verifies functionality against a
real Kubernetes cluster.
This document explains how you can run the end-to-end tests yourself.
This is useful when you have added or changed functionality in cert-manager and
want to verify the software still works as expected.
Requirements
============
Currently, a number of tools **must** be installed on your machine in order to
run the tests:
* ``bazel`` - As with all other development, Bazel is required to actually
build the project as well as end-to-end test framework. Bazel will also
retrieve appropriate versions of any other dependencies depending on what
'target' you choose to run.
* ``docker`` - We provision a whole Kubernetes cluster within Docker, and so
an up to date version of Docker must be installed. The oldest Docker version
we have tested is 17.09.
* ``kubectl`` - If you are running the tests on Linux, this step is
technically not required. For non-Linux hosts (i.e. OSX), you will need to
ensure you have a relatively new version of kubectl available on your PATH.
* An internet connection - tests require access to DNS, and optionally
Cloudflare APIs (if a Cloudflare API token is provided).
Bazel, Docker and Kubectl should be installed through your preferred means.
Run end-to-end tests
====================
You can run the end-to-end tests by executing the following:
.. code-block:: shell
./hack/ci/run-e2e-kind.sh
The full suite may take up to 10 minutes to run.
You can monitor output of this command to track progress.
This document has moved to https://cert-manager.netlify.com/docs/contributing/kind/.
This placeholder file will be removed in a later release.
docs/devel/generate-docs.rst
+5 -40
View File
@@ -1,41 +1,6 @@
========================
Generating Documentation
========================
==========
File moved
==========
The documentation is generated from `reStructured Text`_ by `Sphinx`_
(via `Read The Docs`_). If you're unfamiliar with `reStructured Text`_,
the files typically have the extension `.rst`. You can find more details
in the `reStructured Text Basics`_.
Installation instructions
=========================
To install the sphinx tools, you'll need ``python`` (and ``pip``) installed:
.. code-block:: shell
pip install --user -r requirements.txt
Generating documentation locally
================================
You can generate the documentation locally with the following command:
.. code-block:: shell
make html
This will create documentation in the ``_build`` directory which you can
open with your browser.
.. code-block:: shell
open _build/html/index.html
Note that you do not need to add these files to your git client, as
*Read The Docs* will generate the HTML on the fly.
.. _`Sphinx`: https://www.sphinx-doc.org/
.. _`Read The Docs`: https://readthedocs.org/
.. _`reStructured Text`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
.. _`reStructured Text Basics`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
This document has moved to https://cert-manager.netlify.com/docs/contributing/.
This placeholder file will be removed in a later release.
docs/devel/index.rst
+5 -11
View File
@@ -1,12 +1,6 @@
Development documentation
=========================
==========
File moved
==========
.. toctree::
:maxdepth: 1
develop-with-minikube
end-to-end-tests
dns01-providers
dco-sign-off
release-process
generate-docs
This document has moved to https://cert-manager.netlify.com/docs/contributing/.
This placeholder file will be removed in a later release.
docs/devel/release-process.rst
+5 -106
View File
@@ -1,107 +1,6 @@
===============
Release process
===============
==========
File moved
==========
This document aims to outline the process that should be followed for cutting a
new release of cert-manager.
Minor releases
==============
A minor release is a backwards-compatible 'feature' release.
It can contain new features and bugfixes.
Release schedule
----------------
We aim to cut a new minor release once per month.
The rough goals for each release are outlined as part of a GitHub milestone.
We cut a release even if some of these goals are missed, in order to keep up
release velocity.
Process
-------
.. note::
This process document is WIP and may be incomplete
The process for cutting a minor release is as follows:
#. Ensure upgrading document exists in docs/tasks/upgrading
#. Ensure all strings of versions have been updated:
* deploy/charts/cert-manager/README.md
* docs/getting-started/install/kubernetes.rst
* docs/getting-started/install/openshift.rst
* docs/getting-started/webhook.rst
* docs/tutorials/acme/quick-start/index.rst
#. Create a new release branch (e.g. ```release-0.5```)
#. Push it to the ```jetstack/cert-manager`` repository
#. Gather release notes since the previous release:
* Download, install and run the latest version of release-notes:
.. code::
* $ go get k8s.io/release; go install $GOPATH/src/k8s.io/release/cmd/release-notes/.
* $ mkdir -p design/release-notes/release-*X.Y*
* $ export GITHUB_TOKEN=*your-token*
* $ $GOPATH/bin/release-notes -release-version v*X.Y* -github-repo cert-manager -github-org jetstack -requiredAuthor "" -start-sha=$(git rev-parse *X.Y-1.0*) -end-sha=$(git rev-parse HEAD) -output design/release-notes/release-*X.Y*/draft-release-notes.md
* # Add additional blurb, notable items and characterise Changelog.
Finally, create a new tag taken from the release branch, e.g. ```v0.5.0```.
Patch releases
==============
A patch release contains critical bugfixes for the project.
They are managed on an ad-hoc basis, and should only be required when critical
bugs/regressions are found in the release.
We will only perform patch release for the **current** version of cert-manager.
Once a new minor release has been cut, we will stop providing patches for the
version before it.
Release schedule
----------------
Patch releases are cut on an ad-hoc basis, depending on recent activity on the
release branch.
Process
-------
.. note::
This process document is WIP and may be incomplete
Bugs that need to be fixed in a patch release should be cherry picked into the
appropriate release branch using the ```./hack/cherry-pick-pr.sh``` script in
this repository.
The process for cutting a patch release is as follows:
#. Ensure all strings of versions have been updated:
* deploy/charts/cert-manager/README.md
* docs/getting-started/install/kubernetes.rst
* docs/getting-started/install/openshift.rst
* docs/getting-started/webhook.rst
* docs/tutorials/acme/quick-start/index.rst
#. Iterate on review feedback (hopefully this will be minimal) and submit
changes to ```master``` of cert-manager, performing a rebase of release-x.y.
#. Gather release notes since the previous release:
.. code::
* $ go get k8s.io/release; go install $GOPATH/src/k8s.io/release/cmd/release-notes/.
* $ mkdir -p design/release-notes/release-*X.Y*
* $ export GITHUB_TOKEN=*your-token*
* $ $GOPATH/bin/release-notes -release-version v*X.Y* -github-repo cert-manager -github-org jetstack -requiredAuthor "" -start-sha=$(git rev-parse *X.Y.Z-1*) -end-sha=$(git rev-parse release-*X.Y*) -output design/release-notes/release-*X.Y*/draft-release-notes-*Z*.md
* # Add additional blurb, notable items and characterise Changelog.
Finally, create a new tag taken from the release branch, e.g. ```v0.5.1```.
This document has moved to https://cert-manager.netlify.com/docs/contributing/release-process/.
This placeholder file will be removed in a later release.
docs/external_redirects
+64
View File
@@ -0,0 +1,64 @@
devel/index.rst https://cert-manager.netlify.com/docs/contributing/
devel/release-process.rst https://cert-manager.netlify.com/docs/contributing/release-process/
devel/generate-docs.rst https://cert-manager.netlify.com/docs/contributing/
devel/end-to-end-tests.rst https://cert-manager.netlify.com/docs/contributing/kind/
devel/dco-sign-off.rst https://cert-manager.netlify.com/docs/contributing/sign-off/
devel/dns01-providers.rst https://cert-manager.netlify.com/docs/contributing/dns-providers/
devel/develop-with-minikube.rst https://cert-manager.netlify.com/docs/contributing/kind/
index.rst https://cert-manager.netlify.com/docs/
design/index.rst https://cert-manager.netlify.com/docs
tasks/index.rst https://cert-manager.netlify.com/docs/configuration/
tasks/uninstall/kubernetes.rst https://cert-manager.netlify.com/docs/tutorials/uninstall/kubernetes/
tasks/uninstall/index.rst https://cert-manager.netlify.com/docs/tutorials/uninstall/
tasks/uninstall/openshift.rst https://cert-manager.netlify.com/docs/tutorials/uninstall/openshift/
tasks/issuers/index.rst https://cert-manager.netlify.com/docs/configuration/
tasks/issuers/setup-ca.rst https://cert-manager.netlify.com/docs/configuration/ca/
tasks/issuers/setup-selfsigned.rst https://cert-manager.netlify.com/docs/configuration/selfsigned/
tasks/issuers/setup-acme/index.rst https://cert-manager.netlify.com/docs/configuration/acme/
tasks/issuers/setup-acme/dns01/azuredns.rst https://cert-manager.netlify.com/docs/configuration/acme/dns01/azuredns/
tasks/issuers/setup-acme/dns01/index.rst https://cert-manager.netlify.com/docs/configuration/acme/dns01/
tasks/issuers/setup-acme/dns01/cloudflare.rst https://cert-manager.netlify.com/docs/configuration/acme/dns01/cloudflare/
tasks/issuers/setup-acme/dns01/rfc2136.rst https://cert-manager.netlify.com/docs/configuration/acme/dns01/rfc2136/
tasks/issuers/setup-acme/dns01/acme-dns.rst https://cert-manager.netlify.com/docs/configuration/acme/dns01/acme-dns/
tasks/issuers/setup-acme/dns01/route53.rst https://cert-manager.netlify.com/docs/configuration/acme/dns01/route53/
tasks/issuers/setup-acme/dns01/akamai.rst https://cert-manager.netlify.com/docs/configuration/acme/dns01/akamai/
tasks/issuers/setup-acme/dns01/digitalocean.rst https://cert-manager.netlify.com/docs/configuration/acme/dns01/digitalocean/
tasks/issuers/setup-acme/dns01/webhook.rst https://cert-manager.netlify.com/docs/configuration/acme/dns01/webhook/
tasks/issuers/setup-acme/dns01/google.rst https://cert-manager.netlify.com/docs/configuration/acme/dns01/google/
tasks/issuers/setup-acme/http01/index.rst https://cert-manager.netlify.com/docs/configuration/acme/http01/
tasks/issuers/setup-vault.rst https://cert-manager.netlify.com/docs/configuration/vault/
tasks/issuers/setup-venafi.rst https://cert-manager.netlify.com/docs/configuration/venafi/
tasks/upgrading/index.rst https://cert-manager.netlify.com/docs/TODO
tasks/upgrading/upgrading-0.4-0.5.rst https://cert-manager.netlify.com/docs/TODO
tasks/upgrading/upgrading-0.8-0.9.rst https://cert-manager.netlify.com/docs/TODO
tasks/upgrading/upgrading-0.5-0.6.rst https://cert-manager.netlify.com/docs/TODO
tasks/upgrading/upgrading-0.6-0.7.rst https://cert-manager.netlify.com/docs/TODO
tasks/upgrading/upgrading-0.2-0.3.rst https://cert-manager.netlify.com/docs/TODO
tasks/upgrading/upgrading-0.3-0.4.rst https://cert-manager.netlify.com/docs/TODO
tasks/upgrading/upgrading-0.9-0.10.rst https://cert-manager.netlify.com/docs/TODO
tasks/upgrading/upgrading-0.7-0.8.rst https://cert-manager.netlify.com/docs/TODO
tasks/upgrading/upgrading-0.10-0.11.rst https://cert-manager.netlify.com/docs/TODO
tasks/backup-restore-crds.rst https://cert-manager.netlify.com/docs/tutorials/backup/
tasks/issuing-certificates/index.rst https://cert-manager.netlify.com/docs/usage/certificate/
tasks/issuing-certificates/ingress-shim.rst https://cert-manager.netlify.com/docs/usage/ingress/
getting-started/index.rst https://cert-manager.netlify.com/docs/installation/
getting-started/install/kubernetes.rst https://cert-manager.netlify.com/docs/installation/kubernetes/
getting-started/install/index.rst https://cert-manager.netlify.com/docs/installation/
getting-started/install/openshift.rst https://cert-manager.netlify.com/docs/installation/openshift/
getting-started/webhook.rst https://cert-manager.netlify.com/docs/faq/webhook/
tutorials/index.rst https://cert-manager.netlify.com/docs/tutorials/
tutorials/venafi/securing-ingress.rst https://cert-manager.netlify.com/docs/tutorials/venafi/venafi/
tutorials/acme/index.rst https://cert-manager.netlify.com/docs/tutorials/acme/ingress/
tutorials/acme/dns-validation.rst https://cert-manager.netlify.com/docs/tutorials/acme/dns-validation/
tutorials/acme/migrating-from-kube-lego.rst https://cert-manager.netlify.com/docs/tutorials/acme/migrating-from-kube-lego/
tutorials/acme/http-validation.rst https://cert-manager.netlify.com/docs/tutorials/acme/http-validation/
tutorials/acme/quick-start/index.rst https://cert-manager.netlify.com/docs/tutorials/acme/ingress/
reference/index.rst https://cert-manager.netlify.com/docs/concepts/
reference/challenges.rst https://cert-manager.netlify.com/docs/concepts/acme-orders-challenges/
reference/clusterissuers.rst https://cert-manager.netlify.com/docs/concepts/issuer/
reference/cainjector.rst https://cert-manager.netlify.com/docs/concepts/ca-injector/
reference/issuers.rst https://cert-manager.netlify.com/docs/concepts/issuer/
reference/certificaterequests.rst https://cert-manager.netlify.com/docs/concepts/certificaterequest/
reference/certificates.rst https://cert-manager.netlify.com/docs/concepts/certificate/
reference/orders.rst https://cert-manager.netlify.com/docs/concepts/acme-orders-challenges/
reference/api-docs/index.rst https://cert-manager.netlify.com/docs/reference/api-docs/
docs/generated/reference/BUILD.bazel
-22
View File
@@ -1,22 +0,0 @@
filegroup(
name = "package-srcs",
srcs = glob(["**"]),
tags = ["automanaged"],
visibility = ["//visibility:private"],
)
filegroup(
name = "all-srcs",
srcs = [
":package-srcs",
"//docs/generated/reference/generate:all-srcs",
],
tags = ["automanaged"],
visibility = ["//visibility:public"],
)
filegroup(
name = "output",
srcs = glob(["output/**/*"]),
visibility = ["//visibility:public"],
)
docs/generated/reference/deps.bzl
-168
View File
@@ -1,168 +0,0 @@
# Copyright 2019 The Jetstack cert-manager contributors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
load("@bazel_tools//tools/build_defs/repo:git.bzl", "new_git_repository")
load("@bazel_gazelle//:deps.bzl", "go_repository")
# Install brodocs and related dependencies
def install():
install_brodocs()
install_reference_docs_deps()
def install_brodocs():
## Brodocs and associated dependencies
new_git_repository(
name = "brodocs",
remote = "https://github.com/munnerz/brodocs.git",
# We use this specific revision as it contains changes that allow us to
# specify custom paths when building documentation.
commit = "28714834053271ebb5a6a5fe22af29f98fc0b6d0",
shallow_since = "1556994488 +0100",
build_file_content = """
exports_files(["brodoc.js"])
filegroup(
name = "all-srcs",
srcs = glob(["**/*"]),
visibility = ["//visibility:public"],
)
filegroup(
name = "static",
srcs = [
"stylesheet.css",
"scroll.js",
"actions.js",
"tabvisibility.js",
],
visibility = ["//visibility:public"],
)
""",
)
# Install the nodejs "bootstrap" package
# This provides the basic tools for running and packaging nodejs programs in Bazel
http_archive(
name = "build_bazel_rules_nodejs",
sha256 = "395b7568f20822c13fc5abc65b1eced637446389181fda3a108fdd6ff2cac1e9",
urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/0.29.2/rules_nodejs-0.29.2.tar.gz"],
)
def install_reference_docs_deps():
# Load kubernetes-incubator/reference-docs, to be used as part of the docs
# generation pipeline.
# This involves quite a few dependencies, hence the long list of go_repository
# rules.
# We include them here instead of in Gopkg.{toml,lock} to save extra sources in
# the repository.
# These were all taken from the HEAD of each repositories 'master' branch.
go_repository(
name = "io_kubernetes_incubator_reference_docs",
# Points to HEAD of the 'kubebuilder' branch
commit = "1959039a016c77efe6786b19f3f55f7b3042604f",
importpath = "github.com/kubernetes-incubator/reference-docs",
)
go_repository(
name = "in_gopkg_yaml_v2",
commit = "5420a8b6744d3b0345ab293f6fcba19c978f1183",
remote = "https://github.com/go-yaml/yaml",
vcs = "git",
importpath = "gopkg.in/yaml.v2",
)
go_repository(
name = "com_github_go_openapi_spec",
commit = "f1468acb3b29cdd5c5f6fa29435d2d2d6e6c9ff1",
importpath = "github.com/go-openapi/spec",
)
go_repository(
name = "com_github_go_openapi_loads",
commit = "fd899182a268dcf25de088722375311d9dee2662",
importpath = "github.com/go-openapi/loads",
)
go_repository(
name = "com_github_go_openapi_swag",
commit = "dd0dad036e67ae93c27dc64337b3f76296f3a5f0",
importpath = "github.com/go-openapi/swag",
)
go_repository(
name = "com_github_go_openapi_analysis",
commit = "b006789cd277d4fa4d16767046d694a256c6a218",
importpath = "github.com/go-openapi/analysis",
)
go_repository(
name = "com_github_go_openapi_jsonreference",
commit = "1c6a3fa339f2743b7b0fd2b842fc455eca2fa9eb",
importpath = "github.com/go-openapi/jsonreference",
)
go_repository(
name = "com_github_go_openapi_jsonpointer",
commit = "52eb3d4b47c6a51ce2693c8e614a15a07c1af435",
importpath = "github.com/go-openapi/jsonpointer",
)
go_repository(
name = "com_github_go_openapi_strfmt",
commit = "776114108ccc228238641096ea5be3d24842d4ea",
importpath = "github.com/go-openapi/strfmt",
)
go_repository(
name = "com_github_go_openapi_errors",
commit = "87bb653288778f8b0d922c5c3fb8b3f00a47ff28",
importpath = "github.com/go-openapi/errors",
)
go_repository(
name = "com_github_mailru_easyjson",
commit = "60711f1a8329503b04e1c88535f419d0bb440bff",
importpath = "github.com/mailru/easyjson",
)
go_repository(
name = "com_github_puerkitobio_purell",
commit = "975f53781597ed779763b7b65566e74c4004d8de",
importpath = "github.com/PuerkitoBio/purell",
)
go_repository(
name = "com_github_puerkitobio_urlesc",
commit = "de5bf2ad457846296e2031421a34e2568e304e35",
importpath = "github.com/PuerkitoBio/urlesc",
)
go_repository(
name = "com_github_globalsign_mgo",
commit = "1ca0a4f7cbcbe61c005d1bd43fdd8bb8b71df6bc",
importpath = "github.com/globalsign/mgo",
)
go_repository(
name = "com_github_mitchellh_mapstructure",
commit = "fa473d140ef3c6adf42d6b391fe76707f1f243c8",
importpath = "github.com/mitchellh/mapstructure",
)
go_repository(
name = "com_github_asaskevich_govalidator",
commit = "f9ffefc3facfbe0caee3fea233cbb6e8208f4541",
importpath = "github.com/asaskevich/govalidator",
)
docs/generated/reference/generate/BUILD.bazel
-104
View File
@@ -1,104 +0,0 @@
genrule(
name = "__internal_markdown_tar",
srcs = [
"//docs/generated/reference/generate:config.yaml",
"//docs/generated/reference/generate/static_includes:all-srcs",
"//docs/generated/reference/generate/json_swagger:swagger.json",
],
outs = ["defs.tar.gz"],
cmd = "; ".join([
"tmpdir=$$(mktemp -d)",
"mkdir -p \"$$tmpdir/static_includes/\"",
"mkdir -p \"$$tmpdir/includes/\"",
"mkdir -p \"$$tmpdir/openapi-spec/\"",
"cp -L \"$(location //docs/generated/reference/generate/json_swagger:swagger.json)\" \"$$tmpdir/openapi-spec/\"",
"cp -L \"$(location //docs/generated/reference/generate:config.yaml)\" \"$$tmpdir/\"",
"cp -LR $(locations //docs/generated/reference/generate/static_includes:all-srcs) \"$$tmpdir/static_includes/\"",
"rm \"$$tmpdir/static_includes/BUILD.bazel\"",
"$(location @io_kubernetes_incubator_reference_docs//gen-apidocs) --copyright \"<a href=\\\"https://jetstack.io\\\">Copyright 2018 Jetstack Ltd.</a>\" --title \"Cert-manager API Reference\" -config-dir $$tmpdir",
"orig=$$(pwd)",
"cd $$tmpdir",
"tar -cf \"$$orig/$@\" ./manifest.json ./includes/",
]),
tools = [
"@io_kubernetes_incubator_reference_docs//gen-apidocs",
],
visibility = ["//visibility:private"],
)
genrule(
name = "__internal_brodocs_out",
srcs = [
"//docs/generated/reference/generate:__internal_markdown_tar",
],
outs = [
"index.html",
"navData.js",
],
cmd = "; ".join([
"input=$$(mktemp -d)",
"output=$$(mktemp -d)",
"tar -C \"$$input\" -xf $(location //docs/generated/reference/generate:__internal_markdown_tar)",
"$(location //docs/generated/reference/generate/bin:brodocs) \"$$input/manifest.json\" \"$$input/includes\" \"$$output\"",
"cp $$output/index.html $(@D)",
"cp $$output/navData.js $(@D)",
]),
tools = [
"//docs/generated/reference/generate/bin:brodocs",
],
visibility = ["//visibility:private"],
)
# This file constructs an archive containing the full generated reference docs
# website, including all required node_modules.
# The output this script is then consumed by the hack/update-reference-docs.sh
# to place the data into the correct directory to be displayed by readthedocs.
genrule(
name = "generate",
srcs = [
":__internal_brodocs_out",
"@brodocs//:static",
"@brodocs_modules//jquery:jquery__contents",
"@brodocs_modules//bootstrap:bootstrap__contents",
"@brodocs_modules//font-awesome:font-awesome__contents",
"@brodocs_modules//highlight.js:highlight.js__contents",
"@brodocs_modules//jquery.scrollto:jquery.scrollto__contents",
],
outs = ["generated.tar.gz"],
cmd = "; ".join([
"bm=external/brodocs_modules",
"out=$$(mktemp -d)",
"cp -L $(locations :__internal_brodocs_out) $$out",
"cp -L $(locations @brodocs//:static) $$out",
"p=node_modules/jquery/dist; mkdir -p $$out/$$p && cp -L $$bm/$$p/jquery.min.js $$out/$$p",
"p=node_modules/bootstrap/dist/css; mkdir -p $$out/$$p && cp -L $$bm/$$p/bootstrap.min.css $$out/$$p",
"p=node_modules/font-awesome/css; mkdir -p $$out/$$p && cp -L $$bm/$$p/* $$out/$$p",
"p=node_modules/font-awesome/fonts; mkdir -p $$out/$$p && cp -L $$bm/$$p/* $$out/$$p",
"p=node_modules/highlight.js/styles; mkdir -p $$out/$$p && cp -L $$bm/$$p/default.css $$out/$$p",
"p=node_modules/jquery.scrollto; mkdir -p $$out/$$p && cp -L $$bm/$$p/jquery.scrollTo.min.js $$out/$$p",
"orig=$$(pwd)",
"cd $$out",
"tar -cf $$orig/$@ ./",
]),
visibility = ["//visibility:public"],
)
filegroup(
name = "package-srcs",
srcs = glob(["**"]),
tags = ["automanaged"],
visibility = ["//visibility:private"],
)
filegroup(
name = "all-srcs",
srcs = [
":package-srcs",
"//docs/generated/reference/generate/bin:all-srcs",
"//docs/generated/reference/generate/go_openapi:all-srcs",
"//docs/generated/reference/generate/json_swagger:all-srcs",
"//docs/generated/reference/generate/static_includes:all-srcs",
],
tags = ["automanaged"],
visibility = ["//visibility:public"],
)
docs/generated/reference/generate/bin/BUILD.bazel
-26
View File
@@ -1,26 +0,0 @@
load("@build_bazel_rules_nodejs//:defs.bzl", "nodejs_binary")
nodejs_binary(
name = "brodocs",
data = [
"@brodocs//:all-srcs",
],
entry_point = "brodocs/brodoc",
# Ordinarily this defaults to //:node_modules
node_modules = "@brodocs_modules//:node_modules",
visibility = ["//visibility:public"],
)
filegroup(
name = "package-srcs",
srcs = glob(["**"]),
tags = ["automanaged"],
visibility = ["//visibility:private"],
)
filegroup(
name = "all-srcs",
srcs = [":package-srcs"],
tags = ["automanaged"],
visibility = ["//visibility:public"],
)
docs/generated/reference/generate/bin/package-lock.json
Generated
-88
View File
@@ -1,88 +0,0 @@
{
"name": "brodocs",
"version": "1.0.0",
"lockfileVersion": 1,
"requires": true,
"dependencies": {
"bootstrap": {
"version": "3.4.1",
"resolved": "https://registry.npmjs.org/bootstrap/-/bootstrap-3.4.1.tgz",
"integrity": "sha512-yN5oZVmRCwe5aKwzRj6736nSmKDX7pLYwsXiCj/EYmo16hODaBiT4En5btW/jhBF/seV+XMx3aYwukYC3A49DA=="
},
"colors": {
"version": "1.3.3",
"resolved": "https://registry.npmjs.org/colors/-/colors-1.3.3.tgz",
"integrity": "sha512-mmGt/1pZqYRjMxB1axhTo16/snVZ5krrKkcmMeVKxzECMMXoCgnvTPp10QgHfcbQZw8Dq2jMNG6je4JlWU0gWg=="
},
"ejs": {
"version": "2.6.1",
"resolved": "https://registry.npmjs.org/ejs/-/ejs-2.6.1.tgz",
"integrity": "sha512-0xy4A/twfrRCnkhfk8ErDi5DqdAsAqeGxht4xkCUrsvhhbQNs7E+4jV0CN7+NKIY0aHE72+XvqtBIXzD31ZbXQ==",
"dev": true
},
"font-awesome": {
"version": "4.7.0",
"resolved": "https://registry.npmjs.org/font-awesome/-/font-awesome-4.7.0.tgz",
"integrity": "sha1-j6jPBBGhoxr9B7BtKQK7n8gVoTM="
},
"highlight.js": {
"version": "9.15.6",
"resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-9.15.6.tgz",
"integrity": "sha512-zozTAWM1D6sozHo8kqhfYgsac+B+q0PmsjXeyDrYIHHcBN0zTVT66+s2GW1GZv7DbyaROdLXKdabwS/WqPyIdQ==",
"dev": true
},
"jquery": {
"version": "3.4.1",
"resolved": "https://registry.npmjs.org/jquery/-/jquery-3.4.1.tgz",
"integrity": "sha512-36+AdBzCL+y6qjw5Tx7HgzeGCzC81MDDgaUP8ld2zhx58HdqXGoBd+tHdrBMiyjGQs0Hxs/MLZTu/eHNJJuWPw=="
},
"jquery.scrollto": {
"version": "2.1.2",
"resolved": "https://registry.npmjs.org/jquery.scrollto/-/jquery.scrollto-2.1.2.tgz",
"integrity": "sha1-51gNnHrEbvW7JTGUg/b0VxP9fGw=",
"requires": {
"jquery": ">=1.8"
}
},
"marked": {
"version": "0.6.2",
"resolved": "https://registry.npmjs.org/marked/-/marked-0.6.2.tgz",
"integrity": "sha512-LqxwVH3P/rqKX4EKGz7+c2G9r98WeM/SW34ybhgNGhUQNKtf1GmmSkJ6cDGJ/t6tiyae49qRkpyTw2B9HOrgUA==",
"dev": true
},
"mime": {
"version": "1.6.0",
"resolved": "https://registry.npmjs.org/mime/-/mime-1.6.0.tgz",
"integrity": "sha512-x0Vn8spI+wuJ1O6S7gnbaQg8Pxh4NNHb7KSINmEWKiPE4RKOplvijn+NkmYmmRgP68mc70j2EbeTFRsrswaQeg=="
},
"minimist": {
"version": "0.0.10",
"resolved": "https://registry.npmjs.org/minimist/-/minimist-0.0.10.tgz",
"integrity": "sha1-3j+YVD2/lggr5IrRoMfNqDYwHc8="
},
"node-static": {
"version": "0.7.11",
"resolved": "https://registry.npmjs.org/node-static/-/node-static-0.7.11.tgz",
"integrity": "sha512-zfWC/gICcqb74D9ndyvxZWaI1jzcoHmf4UTHWQchBNuNMxdBLJMDiUgZ1tjGLEIe/BMhj2DxKD8HOuc2062pDQ==",
"requires": {
"colors": ">=0.6.0",
"mime": "^1.2.9",
"optimist": ">=0.3.4"
}
},
"optimist": {
"version": "0.6.1",
"resolved": "https://registry.npmjs.org/optimist/-/optimist-0.6.1.tgz",
"integrity": "sha1-2j6nRob6IaGaERwybpDrFaAZZoY=",
"requires": {
"minimist": "~0.0.1",
"wordwrap": "~0.0.2"
}
},
"wordwrap": {
"version": "0.0.3",
"resolved": "https://registry.npmjs.org/wordwrap/-/wordwrap-0.0.3.tgz",
"integrity": "sha1-o9XabNXAvAAI03I0u68b7WMFkQc="
}
}
}
docs/generated/reference/generate/config.yaml
-26
View File
@@ -1,26 +0,0 @@
example_location: "examples"
api_groups:
- "Certmanager"
- "ACME"
resource_categories:
- name: "Certmanager"
include: "certmanager"
resources:
- name: "Certificate"
version: "v1alpha2"
group: "certmanager"
- name: "ClusterIssuer"
version: "v1alpha2"
group: "certmanager"
- name: "Issuer"
version: "v1alpha2"
group: "certmanager"
- name: "ACME"
include: "acme"
resources:
- name: "Order"
version: "v1alpha2"
group: "acme"
- name: "Challenge"
version: "v1alpha2"
group: "acme"
docs/generated/reference/generate/go_openapi/BUILD.bazel
-42
View File
@@ -1,42 +0,0 @@
# gazelle:exclude doc.go
package(default_visibility = ["//visibility:public"])
load("//docs/generated/reference/generate/go_openapi:def.bzl", "openapi_library")
openapi_library(
name = "go_default_library",
srcs = ["doc.go"],
dependency_targets = [
"@io_k8s_api//core/v1:go_default_library",
"@io_k8s_apimachinery//pkg/apis/meta/v1:go_default_library",
"@io_k8s_apimachinery//pkg/runtime:go_default_library",
"@io_k8s_apimachinery//pkg/version:go_default_library",
],
go_prefix = "github.com/jetstack/cert-manager",
openapi_extra_targets = [
"k8s.io/api/core/v1",
"k8s.io/apimachinery/pkg/apis/meta/v1",
"k8s.io/apimachinery/pkg/runtime",
"k8s.io/apimachinery/pkg/version",
],
openapi_targets = [
"pkg/apis/certmanager/v1alpha2",
"pkg/apis/acme/v1alpha2",
"pkg/apis/meta/v1",
],
tags = ["docs"],
)
filegroup(
name = "package-srcs",
srcs = glob(["**"]),
tags = ["automanaged"],
visibility = ["//visibility:private"],
)
filegroup(
name = "all-srcs",
srcs = [":package-srcs"],
tags = ["automanaged"],
)
docs/generated/reference/generate/go_openapi/def.bzl
-50
View File
@@ -1,50 +0,0 @@
# Copyright 2019 The Jetstack cert-manager contributors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
load("@io_bazel_rules_go//go:def.bzl", "go_library")
load("@io_k8s_repo_infra//defs:go.bzl", "go_genrule")
def openapi_library(name, tags, srcs, go_prefix, openapi_targets = [], openapi_extra_targets = [], dependency_targets = []):
deps = [
"@com_github_go_openapi_spec//:go_default_library",
"@io_k8s_kube_openapi//pkg/common:go_default_library",
] + ["//%s:go_default_library" % target for target in openapi_targets] + dependency_targets
go_library(
name = name,
srcs = srcs + [":zz_generated.openapi"],
importpath = go_prefix + "/docs/generated/reference/generate/go_openapi",
tags = tags,
deps = deps,
)
go_genrule(
name = "zz_generated.openapi",
srcs = ["//hack/boilerplate:boilerplate.go.txt"],
outs = ["zz_generated.openapi.go"],
# In order for vendored dependencies to be imported correctly,
# the generator must run from the repo root inside the generated GOPATH.
# All of bazel's $(location)s are relative to the original working directory, however,
# so we must save it first.
cmd = " ".join([
"$(location @io_k8s_kube_openapi//cmd/openapi-gen)",
"--v 1",
"--logtostderr",
"--go-header-file $(location //hack/boilerplate:boilerplate.go.txt)",
"--output-file-base zz_generated.openapi",
"--output-package " + go_prefix + "/docs/generated/reference/generate/go_openapi",
"--input-dirs " + ",".join([go_prefix + "/" + target for target in openapi_targets] + openapi_extra_targets),
"&& cp $$GOPATH/src/" + go_prefix + "/docs/generated/reference/generate/go_openapi/zz_generated.openapi.go $(location :zz_generated.openapi.go)",
]),
go_deps = deps,
tools = ["@io_k8s_kube_openapi//cmd/openapi-gen"],
)
docs/generated/reference/generate/go_openapi/doc.go
-18
View File
@@ -1,18 +0,0 @@
/*
Copyright 2019 The Jetstack cert-manager contributors.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
// Package go_openapi describes OpenAPI type defintions for cert-manager APIs
package go_openapi
docs/generated/reference/generate/json_swagger/BUILD.bazel
-45
View File
@@ -1,45 +0,0 @@
load("@io_bazel_rules_go//go:def.bzl", "go_binary", "go_library")
filegroup(
name = "package-srcs",
srcs = glob(["**"]),
tags = ["automanaged"],
visibility = ["//visibility:private"],
)
filegroup(
name = "all-srcs",
srcs = [":package-srcs"],
tags = ["automanaged"],
visibility = ["//visibility:public"],
)
go_library(
name = "go_default_library",
srcs = ["main.go"],
importpath = "github.com/jetstack/cert-manager/docs/generated/reference/generate/json_swagger",
tags = ["manual"],
visibility = ["//visibility:private"],
deps = [
"//docs/generated/reference/generate/go_openapi:go_default_library",
"@com_github_go_openapi_spec//:go_default_library",
"@io_k8s_kube_openapi//pkg/common:go_default_library",
],
)
go_binary(
name = "generator",
embed = [":go_default_library"],
tags = ["manual"],
visibility = ["//visibility:private"],
)
genrule(
name = "swagger",
outs = ["swagger.json"],
cmd = "; ".join([
"$(locations //docs/generated/reference/generate/json_swagger:generator) > $@",
]),
tools = [":generator"],
visibility = ["//visibility:public"],
)
docs/generated/reference/generate/json_swagger/main.go
-54
View File
@@ -1,54 +0,0 @@
/*
Copyright 2019 The Jetstack cert-manager contributors.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package main
import (
"encoding/json"
"fmt"
"log"
"os"
"strings"
"github.com/go-openapi/spec"
"k8s.io/kube-openapi/pkg/common"
openapi "github.com/jetstack/cert-manager/docs/generated/reference/generate/go_openapi"
)
func main() {
WriteOpenAPI(openapi.GetOpenAPIDefinitions)
}
// WriteOpenAPI writes the openapi json to docs/reference/openapi-spec/swagger.json
func WriteOpenAPI(openapi func(ref common.ReferenceCallback) map[string]common.OpenAPIDefinition) {
defs := openapi(func(name string) spec.Ref {
parts := strings.Split(name, "/")
return spec.MustCreateRef(fmt.Sprintf("#/definitions/%s.%s",
common.EscapeJsonPointer(parts[len(parts)-2]),
common.EscapeJsonPointer(parts[len(parts)-1])))
})
o, err := json.MarshalIndent(defs, "", " ")
if err != nil {
log.Fatalf("Could not Marshal JSON %v\n%v", err, defs)
}
_, err = os.Stdout.Write(o)
if err != nil {
log.Fatalf("%v", err)
}
}
docs/generated/reference/generate/static_includes/BUILD.bazel
-13
View File
@@ -1,13 +0,0 @@
filegroup(
name = "package-srcs",
srcs = glob(["**"]),
tags = ["automanaged"],
visibility = ["//visibility:private"],
)
filegroup(
name = "all-srcs",
srcs = [":package-srcs"],
tags = ["automanaged"],
visibility = ["//visibility:public"],
)
docs/generated/reference/generate/static_includes/_certmanager.md
-9
View File
@@ -1,9 +0,0 @@
# <strong>cert-manager</strong>
------------
This page contains reference documentation for cert-manager API types.
For full documentation on how to use cert-manager, please view our
[official documentation](https://docs.cert-manager.io/).
docs/generated/reference/generate/static_includes/_definitions.md
-5
View File
@@ -1,5 +0,0 @@
# <strong>Field Definitions</strong>
------------
docs/generated/reference/generate/static_includes/_oldversions.md
-5
View File
@@ -1,5 +0,0 @@
# <strong>Old API Versions</strong>
------------
docs/generated/reference/generate/static_includes/_overview.md
-6
View File
@@ -1,6 +0,0 @@
# <strong>Overview</strong>
------------
Some kind of overview here
docs/generated/reference/output/reference/api-docs/actions.js
-58
View File
@@ -1,58 +0,0 @@
// https://jsfiddle.net/upqwhou2/
$(document).ready(function() {
var navigationLinks = $('#sidebar-wrapper > ul li a');
var navigationSections = $('#sidebar-wrapper > ul > ul');
var sectionIdTonavigationLink = {};
var sections = $('#page-content-wrapper').find('h1, h2').map(function(index, node) {
if (node.id) {
sectionIdTonavigationLink[node.id] = $('#sidebar-wrapper > ul li a[href="#' + node.id + '"]');
return node;
}
});
var sectionIdToNavContainerLink = {};
var topLevelSections = $('#page-content-wrapper').find('h1').map(function(index, node) {
if (node.id) {
sectionIdToNavContainerLink[node.id] = $('#sidebar-wrapper > ul > ul[id="' + node.id + '-nav' +'"]');
return node;
}
});
var firstLevelNavs = $('#sidebar-wrapper > li');
var secondLevelNavs = $('#sidebar-wrapper > ul > ul');
var secondLevelNavContents = $('#sidebar-wrapper > ul > ul > li');
var thirdLevelNavs = null; // TODO: When compile provides 3 level nav, implement
var sectionsReversed = $(sections.get().reverse());
function checkScroll(event) {
var scrollPosition = $(window).scrollTop();
var offset = 50;
scrollPosition += offset;
sections.each(function() {
var currentSection = $(this);
var sectionTop = $(this).offset().top;
var id = $(this).attr('id');
if (scrollPosition >= sectionTop) {
navigationLinks.removeClass('selected');
sectionIdTonavigationLink[id].addClass('selected');
var sectionNavContainer = sectionIdToNavContainerLink[id];
var sectionNavContainerDisplay;
if (sectionNavContainer) {
sectionNavContainerDisplay = sectionNavContainer.css('display');
}
if (sectionNavContainer && sectionNavContainerDisplay === 'none') {
navigationSections.toggle(false);
sectionNavContainer.toggle(true);
}
}
if (($(this).offset().top < window.pageYOffset + 50) && $(this).offset().top + $(this).height() > window.pageYOffset) {
window.location.hash = id;
}
});
}
checkScroll();
$(window).on('scroll', function(event) {
checkScroll(event);
});
});
docs/generated/reference/output/reference/api-docs/index.html
-2879
View File
File diff suppressed because one or more lines are too long
docs/generated/reference/output/reference/api-docs/navData.js
-1
View File
@@ -1 +0,0 @@
(function(){navData = {"toc":[{"section":"-strong-field-definitions-strong-","subsections":[{"section":"weightedpodaffinityterm-v1"},{"section":"venafitpp-v1alpha2"},{"section":"venafiissuer-v1alpha2"},{"section":"venaficloud-v1alpha2"},{"section":"vaultkubernetesauth-v1alpha2"},{"section":"vaultissuer-v1alpha2"},{"section":"vaultauth-v1alpha2"},{"section":"vaultapprole-v1alpha2"},{"section":"toleration-v1"},{"section":"time-v1"},{"section":"selfsignedissuer-v1alpha2"},{"section":"secretkeyselector-v1"},{"section":"preferredschedulingterm-v1"},{"section":"podantiaffinity-v1"},{"section":"podaffinityterm-v1"},{"section":"podaffinity-v1"},{"section":"ownerreference-v1"},{"section":"objectreference-v1"},{"section":"objectmeta-v1"},{"section":"nodeselectorterm-v1"},{"section":"nodeselectorrequirement-v1"},{"section":"nodeselector-v1"},{"section":"nodeaffinity-v1"},{"section":"managedfieldsentry-v1"},{"section":"localobjectreference-v1"},{"section":"labelselectorrequirement-v1"},{"section":"labelselector-v1"},{"section":"issuercondition-v1alpha2"},{"section":"fieldsv1-v1"},{"section":"duration-v1"},{"section":"certificatednsnameselector-v1alpha2"},{"section":"certificatecondition-v1alpha2"},{"section":"caissuer-v1alpha2"},{"section":"affinity-v1"},{"section":"acmeissuerdns01providerwebhook-v1alpha2"},{"section":"acmeissuerdns01providerroute53-v1alpha2"},{"section":"acmeissuerdns01providerrfc2136-v1alpha2"},{"section":"acmeissuerdns01providerdigitalocean-v1alpha2"},{"section":"acmeissuerdns01providercloudflare-v1alpha2"},{"section":"acmeissuerdns01providerclouddns-v1alpha2"},{"section":"acmeissuerdns01providerazuredns-v1alpha2"},{"section":"acmeissuerdns01providerakamai-v1alpha2"},{"section":"acmeissuerdns01provideracmedns-v1alpha2"},{"section":"acmeissuer-v1alpha2"},{"section":"acmechallengesolverhttp01ingresspodtemplate-v1alpha2"},{"section":"acmechallengesolverhttp01ingresspodspec-v1alpha2"},{"section":"acmechallengesolverhttp01ingress-v1alpha2"},{"section":"acmechallengesolverhttp01-v1alpha2"},{"section":"acmechallengesolverdns01-v1alpha2"},{"section":"acmechallengesolver-v1alpha2"},{"section":"acmechallenge-v1alpha2"},{"section":"acmeauthorization-v1alpha2"}]},{"section":"-strong-old-api-versions-strong-","subsections":[]},{"section":"challenge-v1alpha2","subsections":[]},{"section":"order-v1alpha2","subsections":[]},{"section":"-strong-acme-strong-","subsections":[]},{"section":"issuer-v1alpha2","subsections":[]},{"section":"clusterissuer-v1alpha2","subsections":[]},{"section":"certificate-v1alpha2","subsections":[]},{"section":"-strong-cert-manager-strong-","subsections":[]}],"flatToc":["weightedpodaffinityterm-v1","venafitpp-v1alpha2","venafiissuer-v1alpha2","venaficloud-v1alpha2","vaultkubernetesauth-v1alpha2","vaultissuer-v1alpha2","vaultauth-v1alpha2","vaultapprole-v1alpha2","toleration-v1","time-v1","selfsignedissuer-v1alpha2","secretkeyselector-v1","preferredschedulingterm-v1","podantiaffinity-v1","podaffinityterm-v1","podaffinity-v1","ownerreference-v1","objectreference-v1","objectmeta-v1","nodeselectorterm-v1","nodeselectorrequirement-v1","nodeselector-v1","nodeaffinity-v1","managedfieldsentry-v1","localobjectreference-v1","labelselectorrequirement-v1","labelselector-v1","issuercondition-v1alpha2","fieldsv1-v1","duration-v1","certificatednsnameselector-v1alpha2","certificatecondition-v1alpha2","caissuer-v1alpha2","affinity-v1","acmeissuerdns01providerwebhook-v1alpha2","acmeissuerdns01providerroute53-v1alpha2","acmeissuerdns01providerrfc2136-v1alpha2","acmeissuerdns01providerdigitalocean-v1alpha2","acmeissuerdns01providercloudflare-v1alpha2","acmeissuerdns01providerclouddns-v1alpha2","acmeissuerdns01providerazuredns-v1alpha2","acmeissuerdns01providerakamai-v1alpha2","acmeissuerdns01provideracmedns-v1alpha2","acmeissuer-v1alpha2","acmechallengesolverhttp01ingresspodtemplate-v1alpha2","acmechallengesolverhttp01ingresspodspec-v1alpha2","acmechallengesolverhttp01ingress-v1alpha2","acmechallengesolverhttp01-v1alpha2","acmechallengesolverdns01-v1alpha2","acmechallengesolver-v1alpha2","acmechallenge-v1alpha2","acmeauthorization-v1alpha2","-strong-field-definitions-strong-","-strong-old-api-versions-strong-","challenge-v1alpha2","order-v1alpha2","-strong-acme-strong-","issuer-v1alpha2","clusterissuer-v1alpha2","certificate-v1alpha2","-strong-cert-manager-strong-"]};})();
docs/generated/reference/output/reference/api-docs/node_modules/bootstrap/dist/css/bootstrap.min.css
Generated Vendored
-6
View File
File diff suppressed because one or more lines are too long
docs/generated/reference/output/reference/api-docs/node_modules/font-awesome/css/font-awesome.css
Generated Vendored
-2337
View File
File diff suppressed because it is too large Load Diff
docs/generated/reference/output/reference/api-docs/node_modules/font-awesome/css/font-awesome.css.map
Generated Vendored
-7
View File
File diff suppressed because one or more lines are too long
docs/generated/reference/output/reference/api-docs/node_modules/font-awesome/css/font-awesome.min.css
Generated Vendored
-4
View File
File diff suppressed because one or more lines are too long
docs/generated/reference/output/reference/api-docs/node_modules/font-awesome/fonts/FontAwesome.otf
Generated Vendored
BIN
View File
Binary file not shown.
docs/generated/reference/output/reference/api-docs/node_modules/font-awesome/fonts/fontawesome-webfont.eot
Generated Vendored
BIN
View File
Binary file not shown.
docs/generated/reference/output/reference/api-docs/node_modules/font-awesome/fonts/fontawesome-webfont.svg
Generated Vendored
-2671
View File
File diff suppressed because it is too large Load Diff
Side by Side

Before

Width:  |  Height:  |  Size: 434 KiB

docs/generated/reference/output/reference/api-docs/node_modules/font-awesome/fonts/fontawesome-webfont.ttf
Generated Vendored
BIN
View File
Binary file not shown.
docs/generated/reference/output/reference/api-docs/node_modules/font-awesome/fonts/fontawesome-webfont.woff
Generated Vendored
BIN
View File
Binary file not shown.
docs/generated/reference/output/reference/api-docs/node_modules/font-awesome/fonts/fontawesome-webfont.woff2
Generated Vendored
BIN
View File
Binary file not shown.
docs/generated/reference/output/reference/api-docs/node_modules/highlight.js/styles/default.css
Generated Vendored
-99
View File
@@ -1,99 +0,0 @@
/*
Original highlight.js style (c) Ivan Sagalaev <maniac@softwaremaniacs.org>
*/
.hljs {
display: block;
overflow-x: auto;
padding: 0.5em;
background: #F0F0F0;
}
/* Base color: saturation 0; */
.hljs,
.hljs-subst {
color: #444;
}
.hljs-comment {
color: #888888;
}
.hljs-keyword,
.hljs-attribute,
.hljs-selector-tag,
.hljs-meta-keyword,
.hljs-doctag,
.hljs-name {
font-weight: bold;
}
/* User color: hue: 0 */
.hljs-type,
.hljs-string,
.hljs-number,
.hljs-selector-id,
.hljs-selector-class,
.hljs-quote,
.hljs-template-tag,
.hljs-deletion {
color: #880000;
}
.hljs-title,
.hljs-section {
color: #880000;
font-weight: bold;
}
.hljs-regexp,
.hljs-symbol,
.hljs-variable,
.hljs-template-variable,
.hljs-link,
.hljs-selector-attr,
.hljs-selector-pseudo {
color: #BC6060;
}
/* Language color: hue: 90; */
.hljs-literal {
color: #78A960;
}
.hljs-built_in,
.hljs-bullet,
.hljs-code,
.hljs-addition {
color: #397300;
}
/* Meta color: hue: 200 */
.hljs-meta {
color: #1f7199;
}
.hljs-meta-string {
color: #4d99bf;
}
/* Misc effects */
.hljs-emphasis {
font-style: italic;
}
.hljs-strong {
font-weight: bold;
}
docs/generated/reference/output/reference/api-docs/node_modules/jquery.scrollto/jquery.scrollTo.min.js
Generated Vendored
-7
View File
@@ -1,7 +0,0 @@
/**
* Copyright (c) 2007-2015 Ariel Flesler - aflesler<a>gmail<d>com | http://flesler.blogspot.com
* Licensed under MIT
* @author Ariel Flesler
* @version 2.1.2
*/
;(function(f){"use strict";"function"===typeof define&&define.amd?define(["jquery"],f):"undefined"!==typeof module&&module.exports?module.exports=f(require("jquery")):f(jQuery)})(function($){"use strict";function n(a){return!a.nodeName||-1!==$.inArray(a.nodeName.toLowerCase(),["iframe","#document","html","body"])}function h(a){return $.isFunction(a)||$.isPlainObject(a)?a:{top:a,left:a}}var p=$.scrollTo=function(a,d,b){return $(window).scrollTo(a,d,b)};p.defaults={axis:"xy",duration:0,limit:!0};$.fn.scrollTo=function(a,d,b){"object"=== typeof d&&(b=d,d=0);"function"===typeof b&&(b={onAfter:b});"max"===a&&(a=9E9);b=$.extend({},p.defaults,b);d=d||b.duration;var u=b.queue&&1<b.axis.length;u&&(d/=2);b.offset=h(b.offset);b.over=h(b.over);return this.each(function(){function k(a){var k=$.extend({},b,{queue:!0,duration:d,complete:a&&function(){a.call(q,e,b)}});r.animate(f,k)}if(null!==a){var l=n(this),q=l?this.contentWindow||window:this,r=$(q),e=a,f={},t;switch(typeof e){case "number":case "string":if(/^([+-]=?)?\d+(\.\d+)?(px|%)?$/.test(e)){e= h(e);break}e=l?$(e):$(e,q);case "object":if(e.length===0)return;if(e.is||e.style)t=(e=$(e)).offset()}var v=$.isFunction(b.offset)&&b.offset(q,e)||b.offset;$.each(b.axis.split(""),function(a,c){var d="x"===c?"Left":"Top",m=d.toLowerCase(),g="scroll"+d,h=r[g](),n=p.max(q,c);t?(f[g]=t[m]+(l?0:h-r.offset()[m]),b.margin&&(f[g]-=parseInt(e.css("margin"+d),10)||0,f[g]-=parseInt(e.css("border"+d+"Width"),10)||0),f[g]+=v[m]||0,b.over[m]&&(f[g]+=e["x"===c?"width":"height"]()*b.over[m])):(d=e[m],f[g]=d.slice&& "%"===d.slice(-1)?parseFloat(d)/100*n:d);b.limit&&/^\d+$/.test(f[g])&&(f[g]=0>=f[g]?0:Math.min(f[g],n));!a&&1<b.axis.length&&(h===f[g]?f={}:u&&(k(b.onAfterFirst),f={}))});k(b.onAfter)}})};p.max=function(a,d){var b="x"===d?"Width":"Height",h="scroll"+b;if(!n(a))return a[h]-$(a)[b.toLowerCase()]();var b="client"+b,k=a.ownerDocument||a.document,l=k.documentElement,k=k.body;return Math.max(l[h],k[h])-Math.min(l[b],k[b])};$.Tween.propHooks.scrollLeft=$.Tween.propHooks.scrollTop={get:function(a){return $(a.elem)[a.prop]()}, set:function(a){var d=this.get(a);if(a.options.interrupt&&a._last&&a._last!==d)return $(a.elem).stop();var b=Math.round(a.now);d!==b&&($(a.elem)[a.prop](b),a._last=this.get(a))}};return p});
docs/generated/reference/output/reference/api-docs/node_modules/jquery/dist/jquery.min.js
Generated Vendored
-2
View File
File diff suppressed because one or more lines are too long
docs/generated/reference/output/reference/api-docs/scroll.js
-196
View File
@@ -1,196 +0,0 @@
$(document).ready(function() {
/**
* TODO: Refactor with intent toward pure functions. Mutation of state can lead to bugs and difficult debugging.
*/
var toc = navData.toc;
var flatToc = navData.flatToc.reverse();
function collectNodes(tocMap) {
var tocNodes = {};
tocMap.map(function(node, index) {
var sectionNode = $('#' + node.section);
var tocSubsections = {};
tocItem = {section: sectionNode};
var subsectionNodes;
if (node.subsections) {
subsectionNodes = (collectNodes(node.subsections));
tocItem.subsections = subsectionNodes;
}
tocNodes[node.section] = tocItem;
});
return tocNodes;
}
var tocItems = collectNodes(toc);
function collectNodesFlat(tocMap, obj) {
var collect = obj || {};
tocMap.map(function(node, index) {
var sectionNode = $('#' + node.section);
tocItem = {section: sectionNode};
if (node.subsections) {
subsectionNodes = (collectNodesFlat(node.subsections, collect));
}
collect[node.section] = sectionNode;
});
return collect;
}
var tocFlat = collectNodesFlat(toc);
var prevSectionToken;
var prevSubsectionToken;
var activeTokensObj = {};
function scrollActions(scrollPosition) {
var activeSection = checkNodePositions(toc, tocFlat, scrollPosition);
var activeSubSection,
prevL1Nav,
currL1Nav,
prevL2Nav,
currL2Nav;
// No active section - return existing activeTokensObj (may be empty)
if (!activeSection) {
return activeTokensObj;
}
/**
* This block deals with L1Nav sections
*/
// If no previous token, set previous to current active and show L1Nav
if (!prevSectionToken) {
prevSectionToken = activeSection.token;
currL1Nav = getNavNode(activeSection.token);
currL1Nav.show('fast');
}
// If active active is not the same as previous, hide previous L1Nav and show current L1Nav; set previous to current
else if (activeSection.token !== prevSectionToken) {
prevL1Nav = getNavNode(prevSectionToken);
currL1Nav = getNavNode(activeSection.token);
prevL1Nav.hide('fast');
currL1Nav.show('fast');
prevSectionToken = activeSection.token;
}
/**
* This block deals with L2Nav subsections
*/
// If there is a subsections array and it has a non-zero length, set active subsection
if (activeSection.subsections && activeSection.subsections.length !== 0) {
activeSubSection = checkNodePositions(activeSection.subsections, tocFlat, scrollPosition);
if (activeSubSection) {
if (!prevSubsectionToken) {
prevSubsectionToken = activeSubSection.token;
currL2Nav = getNavNode(activeSubSection.token);
currL2Nav.show('fast');
} else if (activeSubSection.token !== prevSubsectionToken) {
prevL2Nav = getNavNode(prevSubsectionToken);
currL2Nav = getNavNode(activeSubSection.token);
prevL2Nav.hide('fast');
currL2Nav.show('fast');
prevSubsectionToken = activeSubSection.token;
}
} else {
prevL2Nav = getNavNode(prevSubsectionToken);
prevL2Nav.hide('fast');
prevSubsectionToken = null;
}
}
activeTokensObj.L1 = prevSectionToken;
activeTokensObj.L2 = prevSubsectionToken;
return activeTokensObj;
}
/**
* Checks for active elements by scroll position
*/
var prevElemToken;
var activeElemToken;
function checkActiveElement(items, scrollPosition) {
var offset = 50;
var offsetScroll = scrollPosition + offset;
var visibleNode;
for (var i = 0; i < items.length; i++) {
var token = items[i];
var node = getHeadingNode(token);
if (offsetScroll >= node.offset().top) {
activeElemToken = token;
}
}
if (!prevElemToken) {
getNavElemNode(activeElemToken).addClass('selected');
prevElemToken = activeElemToken;
return;
}
if (activeElemToken !== prevElemToken) {
getNavElemNode(prevElemToken).removeClass('selected');
getNavElemNode(activeElemToken).addClass('selected');
prevElemToken = activeElemToken;
}
return activeElemToken;
}
function getHeadingNode(token) {
return $('#' + token);
}
function getNavNode(token) {
return $('#' + token + '-nav');
}
function getNavElemNode(token) {
return $('#sidebar-wrapper > ul a[href="#' + token + '"]');
}
function checkNodePositions(nodes, flatNodeMap, scrollPosition) {
var activeNode;
for (var i = 0; i < nodes.length; i++) {
var item = nodes[i];
var node = flatNodeMap[item.section];
var nodeTop = node.offset().top - 50;
if (scrollPosition >= nodeTop) {
activeNode = {token: item.section, node: node};
if (item.subsections) {
activeNode.subsections = item.subsections;
}
break;
}
}
return activeNode;
}
function scrollToNav(token) {
setTimeout(function() {
var scrollPosition = $(window).scrollTop();
var activeSectionTokens = scrollActions(scrollPosition);
var activeElemToken = checkActiveElement(flatToc, scrollPosition);
var navNode = $('#sidebar-wrapper > ul a[href="#' + token + '"]');
$('#sidebar-wrapper').scrollTo(navNode, {duration: 'fast', axis: 'y'});
}, 200);
}
$(window).on('hashchange', function(event) {
var scrollPosition = $(window).scrollTop();
var activeSectionTokens = scrollActions(scrollPosition);
var activeElemToken = checkActiveElement(flatToc, scrollPosition);
var scrollToken = activeSectionTokens.L2 ? activeSectionTokens.L2 : activeSectionTokens.L1;
scrollToNav(scrollToken);
var token = location.hash.slice(1);
});
var scrollPosition = $(window).scrollTop();
scrollActions(scrollPosition);
checkActiveElement(flatToc, scrollPosition);
// TODO: prevent scroll on sidebar from propogating to window
$(window).on('scroll', function(event) {
var scrollPosition = $(window).scrollTop();
var activeSectionTokens = scrollActions(scrollPosition);
var activeElemToken = checkActiveElement(flatToc, scrollPosition);
});
});
docs/generated/reference/output/reference/api-docs/stylesheet.css
-269
View File
@@ -1,269 +0,0 @@
/*
Kubernetes colors
kubernetes blue - rgb(50, 109, 230)
dark blue - rgb(51, 113, 227)
dark grey - rgb(48, 48, 48)
light grey - rgb(161, 160, 158)
*/
/* User agent CSS overrides */
#sidebar-wrapper ul, #sidebar-wrapper li {
margin-left: 10px;
padding-left: 0;
}
/* Inspired by Slate CSS */
.body-content aside {
padding: 1.6em;
margin: 1.8em 0;
background: lightsteelblue;
line-height: 1.6;
border-radius: 15px;
}
.body-content aside.warning {
background-color: peachpuff;
}
.body-content aside.success {
background-color: olivedrab;
}
.body-content aside:before {
vertical-align: middle;
padding-right: 1em;
font-size: 16px;
}
.body-content aside.warning:before, .body-content aside.notice:before, .body-content aside.success:before {
font-family: 'FontAwesome';
font-style: normal;
font-weight: normal;
font-variant: normal;
text-transform: none;
line-height: 1;
}
.body-content aside.warning:before {
content: "\f071";
}
.body-content aside.notice:before {
content: "\f05a";
}
.body-content hr {
margin: 2em 0;
border-top: 2px solid dimgrey;
border-bottom: 2px solid antiquewhite;
}
.body-content table {
margin-bottom: 1em;
overflow: auto;
}
.body-content table th, .body-content table td {
text-align: left;
vertical-align: top;
line-height: 1.6;
}
.body-content table th {
padding: 15px 20px;
border-bottom: 1px solid lightsteelblue;
vertical-align: bottom;
}
.body-content table td {
padding: 10px;
}
.body-content table tr:last-child {
border-bottom: 1px solid lightsteelblue;
}
.body-content table tr:nth-child(odd) > td {
background-color: whitesmoke;
}
.body-content table tr:nth-child(even) > td {
background-color: lightsteelblue;
}
.body-content dt {
font-weight: bold;
}
.body-content dd {
margin-left: 15px;
}
.body-content p, .body-content li, .body-content dt, .body-content dd {
line-height: 1.6;
margin-top: 0;
}
/* Brodoc CSS */
body > #wrapper {
display: block;
padding-bottom: 500px;
background-image: linear-gradient(90deg, #FFFFFF 63%, rgb(48, 48, 48) 63%);
}
#sidebar-wrapper {
display: block;
height: 100%;
width: 20%;
position: fixed;
z-index: 1;
top: 0;
left: 0;
background-color: whitesmoke;
border-right: 2px solid slategrey;
overflow-x: hidden;
padding-top: 60px;
}
#sidebar-wrapper a {
text-decoration: none;
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
padding: 0 5px;
}
#sidebar-wrapper ul {
list-style: none;
}
#sidebar-wrapper a.selected {
font-style: bold;
color: whitesmoke;
border: 1px solid rgb(161, 160, 158);
background-color: rgb(51, 113, 227);
border-radius: 5px;
}
#sidebar-wrapper .strong-nav {
font-family: monospace;
font-weight: bold;
}
#sidebar-wrapper .nav-level-1.strong-nav {
margin-top: 25px;
}
#sidebar-wrapper .copyright {
padding-left: 10px;
padding-top: 50px;
padding-bottom: 50px;
text-decoration: underline;
}
#page-content-wrapper {
margin-left: 20%;
padding-top: 60px;
}
.body-content h1, .body-content h2 {
width: 52%;
clear: both;
border-bottom: 3px solid lightslategrey;
}
.body-content > h3, .body-content > h4, .body-content > h5, .body-content > h6, .body-content > p, .body-content > aside, .body-content > ul > li, .body-content > ul > li {
width: 52%;
padding-top: 20px;
}
.body-content table {
width: 52%;
}
.body-content table tr td:not(:first-child) {
overflow-wrap: break-word;
word-wrap: break-word;
}
.body-content table tr td a {
word-break: break-word;
}
.body-content p code {
text-overflow: ellipsis;
display: inline-block;
font-size: smaller;
word-break: break-word;
}
.body-content blockquote {
border-left: 0;
border-radius: 5px;
}
.body-content pre.code-block {
margin-bottom: 80px;
}
.body-content blockquote p, .body-content pre {
color: black;
font-size: 13px;
}
.body-content blockquote.code-block {
background: lightsteelblue;
}
.body-content pre.code-block code {
overflow: auto;
overflow-wrap: normal;
word-wrap: normal;
white-space: pre;
}
.code-block {
display: none;
width: 45%;
float: right;
clear: right;
}
.code-block.active {
display: initial;
}
#code-tabs-wrapper {
width: 35%;
height: 60px;
position: fixed;
top: 0;
right: 0;
}
#code-tabs-wrapper .code-tab-list {
float: right;
margin-top: 0;
padding: 0 10px;
}
#code-tabs-wrapper .code-tab {
color: white;
display: inline-block;
padding: 0 30px;
background: rgb(48, 48, 48);
border: 1px solid rgb(161, 160, 158);
border-radius: 5px;
}
#code-tabs-wrapper .tab-selected {
background: rgb(51, 113, 227);
font-style: bold;
border-radius: 5px;
}
.side-nav a {
color: black;
}
docs/generated/reference/output/reference/api-docs/tabvisibility.js
-27
View File
@@ -1,27 +0,0 @@
$(document).ready(function() {
var codeTabs = $('#code-tabs-wrapper').find('li');
for (var i = 0; i < codeTabs.length; i++) {
createCodeTabListeners(codeTabs, i);
}
function createCodeTabListeners(codeTabs, index) {
var tab = $(codeTabs[index]),
id = tab.attr('id'),
codeClass = '.' + id;
tab.on('click', function() {
codeTabs.removeClass('tab-selected');
tab.addClass('tab-selected');
$('.code-block').removeClass('active');
$(codeClass).addClass('active');
});
}
function setDefautTab() {
$(codeTabs[0]).addClass('tab-selected');
$('.' + codeTabs[0].id).addClass('active');
}
setDefautTab();
});
docs/getting-started/index.rst
+5 -12
View File
@@ -1,13 +1,6 @@
===========
Get started
===========
==========
File moved
==========
The guides in this section will explain how to install, set up, and
uninstall cert-manager.
.. toctree::
:maxdepth: 2
:caption: Contents:
install/index
webhook
This document has moved to https://cert-manager.netlify.com/docs/installation/.
This placeholder file will be removed in a later release.
docs/getting-started/install/index.rst
+5 -15
View File
@@ -1,16 +1,6 @@
=======================
Installing cert-manager
=======================
==========
File moved
==========
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
This document has moved to https://cert-manager.netlify.com/docs/installation/.
This placeholder file will be removed in a later release.
docs/getting-started/install/kubernetes.rst
+5 -297
View File
@@ -1,298 +1,6 @@
========================
Installing on Kubernetes
========================
==========
File moved
==========
cert-manager runs within your Kubernetes 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 applications on
Kubernetes.
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>`.
.. note::
From cert-manager v0.11.0 onwards, the minimum supported version of
Kubernetes is v1.11.0. Users still running Kubernetes v1.10 or below should
upgrade to a supported version before installing cert-manager.
.. warning::
You should not install multiple instances of cert-manager on a single
cluster. This will lead to undefined behaviour and you may be banned from
providers such as Let's Encrypt.
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
kubectl create namespace cert-manager
As part of the installation, cert-manager also deploys a webhook deployment as
an `APIService`_. This can cause issues when uninstalling cert-manager if the
API service still exists but the webhook is no longer running as the API server
is unable to reach the validating webhook. Ensure to follow the documentation
when :doc:`uninstalling cert-manager <../../../tasks/uninstall/index>`.
The webhook enables cert-manager to implement validation and mutating webhooks
on cert-manager resources. A `ValidatingWebhookConfiguration`_ resource is
deployed to validate cert-manager resources we will create after installation.
No mutating webhooks are currently implemented.
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
kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v0.11.0/cert-manager.yaml
.. note::
If you are running Kubernetes v1.15 or below, you will need to add the
``--validate=false`` flag to your ``kubectl apply`` command above else you
will receive a validation error relating to the
``x-kubernetes-preserve-unknown-fields`` field in our
``CustomResourceDefinition`` resources.
This is a benign error and occurs due to the way ``kubectl`` performs
resource validation.
.. note::
When running on GKE (Google Kubernetes Engine), you may encounter a
'permission denied' error when creating some of these resources. This is a
nuance of the way GKE handles RBAC and IAM permissions, and as such you
should 'elevate' your own privileges to that of a 'cluster-admin' **before**
running the above command. If you have already run the above command, you
should run them again after elevating your permissions::
kubectl create clusterrolebinding cluster-admin-binding \
--clusterrole=cluster-admin \
--user=$(gcloud config get-value core/account)
Installing with Helm
====================
As an alternative to the YAML manifests referenced above, we also provide an
official Helm chart for installing cert-manager.
Pre-requisites
--------------
* Helm_ and Tiller installed (or alternatively, use `Tillerless Helm v2`_)
* `cluster-admin privileges bound to the Tiller pod`_
Foreword
--------
Before deploying cert-manager with Helm, you must ensure Tiller_ is up and
running in your cluster. Tiller is the server side component to Helm.
Your cluster administrator may have already setup and configured Helm for you,
in which case you can skip this step.
Full documentation on installing Helm can be found in the `Installing helm docs`_.
If your cluster has RBAC (Role Based Access Control) enabled (default in GKE
v1.7+), you will need to take special care when deploying Tiller, to ensure
Tiller has permission to create resources as a cluster administrator. More
information on deploying Helm with RBAC can be found in the `Helm RBAC docs`_.
Steps
-----
In order to install the Helm chart, you must run:
.. code-block:: shell
# Install the CustomResourceDefinition resources separately
kubectl apply --validate=false -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/deploy/manifests/00-crds.yaml
# Create the namespace for cert-manager
kubectl create namespace cert-manager
# Add the Jetstack Helm repository
helm repo add jetstack https://charts.jetstack.io
# Update your local Helm chart repository cache
helm repo update
# Install the cert-manager Helm chart
helm install \
--name cert-manager \
--namespace cert-manager \
--version v0.11.0 \
jetstack/cert-manager
The default cert-manager configuration is good for the majority of users, but a
full list of the available options can be found in the `Helm chart README`_.
Verifying the installation
==========================
Once you've installed cert-manager, you can verify it is deployed correctly by
checking the ``cert-manager`` namespace for running pods:
.. code-block:: shell
kubectl get pods --namespace cert-manager
NAME READY STATUS RESTARTS AGE
cert-manager-5c6866597-zw7kh 1/1 Running 0 2m
cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m
cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m
You should see the ``cert-manager``, ``cert-manager-cainjector`` and
``cert-manager-webhook`` pod in a Running state.
It may take a minute or so for the TLS assets required for the webhook to
function to be provisioned. This may cause the webhook to take a while longer
to start for the first time than other pods. If you experience problems, please
check the :doc:`troubleshooting guide <../troubleshooting>`.
The following steps will confirm that cert-manager is set up correctly and able
to issue basic certificate types:
.. code-block:: shell
# Create a ClusterIssuer to test the webhook works okay
cat <<EOF > test-resources.yaml
apiVersion: v1
kind: Namespace
metadata:
name: cert-manager-test
---
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: test-selfsigned
namespace: cert-manager-test
spec:
selfSigned: {}
---
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
name: selfsigned-cert
namespace: cert-manager-test
spec:
commonName: example.com
secretName: selfsigned-cert-tls
issuerRef:
name: test-selfsigned
EOF
# Create the test resources
kubectl apply -f test-resources.yaml
# Check the status of the newly created certificate
# You may need to wait a few seconds before cert-manager processes the
# certificate request
kubectl describe certificate -n cert-manager-test
...
Spec:
Common Name: example.com
Issuer Ref:
Name: test-selfsigned
Secret Name: selfsigned-cert-tls
Status:
Conditions:
Last Transition Time: 2019-01-29T17:34:30Z
Message: Certificate is up to date and has not expired
Reason: Ready
Status: True
Type: Ready
Not After: 2019-04-29T17:34:29Z
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal CertIssued 4s cert-manager Certificate issued successfully
# Clean up the test resources
kubectl delete -f test-resources.yaml
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>`.
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.
Alternative installation methods
================================
Helmfile
--------
Helmfile is a declarative spec for deploying helm charts.
'cert-manager-installer': https://github.com/zakkg3/cert-manager-installer
It's an easy and automated way to install cert-manager.
Note: This is an external link and it's not officially maintained by cert-manager
but by the community.
.. code-block:: shell
git clone git@github.com:zakkg3/cert-manager-installer.git
cd cert-manager-installer
helmfile sync
kubeprod
--------
`Bitnami Kubernetes Production Runtime`_ (BKPR, ``kubeprod``) is a curated
collection of the services you would need to deploy on top of your Kubernetes
cluster to enable logging, monitoring, certificate management, automatic
discovery of Kubernetes resources via public DNS servers and other common
infrastructure needs.
It depends on ``cert-manager`` for certificate management, and it is `regularly
tested`_ so the components are known to work together for GKE and AKS clusters
(EKS to be added soon). For its ingress stack it creates a DNS entry in the
configured DNS zone and requests a TLS certificate from the Let's Encrypt
staging server.
BKPR can be deployed using the ``kubeprod install`` command, which will deploy
``cert-manager`` as part of it. Details available in the `BKPR installation guide`_.
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.11/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/
.. _`APIService`: https://kubernetes.io/docs/tasks/access-kubernetes-api/setup-extension-api-server
.. _`Helm`: https://helm.sh/
.. _`cluster-admin privileges bound to the Tiller pod`: https://github.com/helm/helm/blob/240e539cec44e2b746b3541529d41f4ba01e77df/docs/rbac.md#Example-Service-account-with-cluster-admin-role
.. _`helm RBAC docs`: https://github.com/helm/helm/blob/master/docs/rbac.md
.. _`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/
.. _`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
This document has moved to https://cert-manager.netlify.com/docs/installation/kubernetes/.
This placeholder file will be removed in a later release.
docs/getting-started/install/openshift.rst
+5 -95
View File
@@ -1,96 +1,6 @@
=======================
Installing on OpenShift
=======================
==========
File moved
==========
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>`.
.. warning::
You should not install multiple instances of cert-manager on a single
cluster. This will lead to undefined behaviour and you may be banned from
providers such as Let's Encrypt.
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 as the system:admin user
oc login -u system:admin
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 webhook deployment as
an `APIService`_. This can cause issues when uninstalling cert-manager if the
API service still exists but the webhook is no longer running as the API server
is unable to reach the validating webhook. Ensure to follow the documentation
when :doc:`uninstalling cert-manager <../../../tasks/uninstall/index>`.
The webhook enables cert-manager to implement validation and mutating webhooks
on cert-manager resources. A `ValidatingWebhookConfiguration`_ resource is
deployed to validate cert-manager resources we will create after installation.
No mutating webhooks are currently implemented.
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.11.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/
.. _`APIService`: https://kubernetes.io/docs/tasks/access-kubernetes-api/setup-extension-api-server
.. _`kubernetes/kubernetes#69590`: https://github.com/kubernetes/kubernetes/issues/69590
.. _`ValidatingWebhookConfiguration`: https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/
This document has moved to https://cert-manager.netlify.com/docs/installation/openshift/.
This placeholder file will be removed in a later release.
docs/getting-started/webhook.rst
+5 -165
View File
@@ -1,166 +1,6 @@
=================
Webhook component
=================
==========
File moved
==========
In order to provide advanced resource validation, cert-manager includes a
ValidatingWebhookConfiguration_ resource which is deployed into the cluster.
This allows cert-manager to validate that cert-manager API resources that are
submitted to the apiserver are syntactically valid, and catch issues with your
resources early on.
If you disable the webhook component, cert-manager will still perform the
same resource validation however it will not reject 'create' events when the
resources are submitted to the apiserver if they are invalid.
This means it may be possible for a user to submit a resource that renders
the controller inoperable.
For this reason, it is strongly advised to keep the webhook **enabled**.
.. note::
This feature requires Kubernetes v1.9 or greater.
How it works
============
This sections walks through how the resource validation webhook is configured
and explains the process required for it to provision.
The webhook is a ValidatingWebhookConfiguration_ resource combined with an
extra pod that is deployed alongside the cert-manager-controller.
The ValidatingWebhookConfiguration instructs the Kubernetes apiserver to
POST the contents of any Create or Update operations performed on cert-manager
resource types in order to validate that they are setting valid configurations.
This allows us to ensure mis-configurations are caught early on and
communicated to you.
In order for this to work, the webhook requires a TLS certificate that the
apiserver is configured to trust. This is created by the webhook itself and is
implemented by the following two Secrets:
* secret/cert-manager-webhook-ca - A self-signed root CA certificate
which is used to sign certificates for the webhook pod.
* secret/cert-manager-webhook-tls - A TLS certificate issued by the
root CA above, served by the webhook.
The webhook's 'webhookbootstrap' controller is responsible for creating these
secrets with no manual intervention needed.
If errors occur around the webhook but the webhook is running then the webhook
is most likely not reachable from the API server. In this case, ensure that the
API server can communicate with the webhook by following the GKE private cluster
explanation below.
cainjector
----------
The :doc:`cert-manager CA injector </reference/cainjector>` is responsible for
injecting the two CA bundles above into the webhook's
ValidatingWebhookConfiguration and APIService resource in order to allow the
Kubernetes apiserver to 'trust' the webhook apiserver.
This component is configured using the ``cert-manager.io/inject-apiserver-ca: "true"``
and ``cert-manager.io/inject-apiserver-ca: "true"`` annotations on the
APIService and ValidatingWebhookConfiguration resources.
It copies across the CA defined in the 'cert-manager-webhook-ca' Secret
generated above to the ``caBundle`` field on the APIService resource.
It also sets the webhook's ``clientConfig.caBundle`` field on the
``cert-manager-webhook`` ValidatingWebhookConfiguration resource to that of
your Kubernetes API server in order to support Kubernetes versions earlier than
v1.11.
Known issues
------------
This section contains known issues with the webhook component.
If you're having problems, or receiving errors when creating cert-manager
resources, please read through this section for help.
Running on private GKE clusters
-------------------------------
When Google configure the control plane for private clusters, they
automatically configure VPC peering between your Kubernetes cluster's network
and a separate Google managed project.
In order to restrict what Google are able to access within your cluster, the
firewall rules configured restrict access to your Kubernetes pods. This will
mean that you will experience the webhook to not work and expierence errors such
as `Internal error occurred: failed calling admission webhook ... the server is
currently unable to handle the request`.
In order to use the webhook component with a GKE private
cluster, you must configure an additional firewall rule to allow the GKE
control plane access to your webhook pod.
You can read more information on how to add firewall rules for the GKE control
plane nodes in the `GKE docs`_.
Alternatively, you can read how to `disable the webhook component`_ below.
.. todo:: add an example command for how to do this here & explain any security
implications
Disable the webhook component
==============================
If you are having issues with the webhook and cannot use it at this time,
you can optionally disable the webhook altogether.
Doing this may expose your cluster to mis-configuration problems that in some
cases could cause cert-manager to stop working altogether (i.e. if invalid types
are set for fields on cert-manager resources).
How you disable the webhook depends on your deployment method.
With Helm
---------
The Helm chart exposes an option that can be used to disable the webhook.
To do so with an existing installation, you can run:
.. code-block:: shell
helm upgrade cert-manager \
--reuse-values \
--set webhook.enabled=false
If you have not installed cert-manager yet, you can add the
``--set webhook.enabled=false`` to the ``helm install`` command used to install
cert-manager.
With static manifests
---------------------
Because we cannot specify options when installing the static manifests to
conditionally disable different components, we also ship a copy of the
deployment files that do not include the webhook.
Instead of installing with `cert-manager.yaml`_ file, you should instead use
the `cert-manager-no-webhook.yaml`_ file located in the deploy directory.
This is a destructive operation, as it will remove the CustomResourceDefinition
resources, causing your configured Issuers, Certificates etc to be deleted.
You should first :doc:`backup your configuration </tasks/backup-restore-crds>`
before running the following commands.
To re-install cert-manager without the webhook, run:
.. code-block:: shell
kubectl delete -f https://github.com/jetstack/cert-manager/releases/download/v0.11.0/cert-manager.yaml
kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v0.11.0/cert-manager-no-webhook.yaml
Once you have re-installed cert-manager, you should then
:doc:`restore your configuration </tasks/backup-restore-crds>`.
.. _`cert-manager.yaml`: https://github.com/jetstack/cert-manager/releases/download/v0.11.0/cert-manager.yaml
.. _`cert-manager-no-webhook.yaml`: https://github.com/jetstack/cert-manager/releases/download/v0.11.0/cert-manager-no-webhook.yaml
.. _`GKE docs`: https://cloud.google.com/kubernetes-engine/docs/how-to/private-clusters#add_firewall_rules
.. _`ValidatingWebhookConfiguration`: https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/
This document has moved to https://cert-manager.netlify.com/docs/faq/webhook/.
This placeholder file will be removed in a later release.
docs/index.rst
+5 -42
View File
@@ -1,43 +1,6 @@
.. cert-manager documentation master file, created by
sphinx-quickstart on Sat Mar 24 10:03:16 2018.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
==========
File moved
==========
========================================
Welcome to cert-manager's documentation!
========================================
cert-manager is a native Kubernetes_ certificate management controller.
It can help with issuing certificates from a variety of sources, such as
`Let's Encrypt`_, `HashiCorp Vault`_, `Venafi`_, a simple signing keypair, or self signed.
It will ensure certificates are valid and up to date, and attempt to renew
certificates at a configured time before expiry.
It is loosely based upon the work of kube-lego_ and has borrowed some wisdom
from other similar projects e.g. kube-cert-manager_.
.. image:: images/high-level-overview.svg
:align: center
This is the full technical documentation for the project, and should be used as
a source of references when seeking help with the project.
.. toctree::
:maxdepth: 2
:titlesonly:
:caption: Contents:
getting-started/index
tutorials/index
tasks/index
reference/index
design/index
devel/index
.. _Kubernetes: https://kubernetes.io
.. _kube-lego: https://github.com/jetstack/kube-lego
.. _kube-cert-manager: https://github.com/PalmStoneGames/kube-cert-manager
.. _`Let's Encrypt`: https://letsencrypt.org
.. _`HashiCorp Vault`: https://www.vaultproject.io
.. _`Venafi`: https://www.venafi.com/
This document has moved to https://cert-manager.netlify.com/docs/.
This placeholder file will be removed in a later release.
docs/reference/api-docs/index.rst
+6 -3
View File
@@ -1,3 +1,6 @@
=================
API documentation
=================
==========
File moved
==========
This document has moved to https://cert-manager.netlify.com/docs/reference/api-docs/.
This placeholder file will be removed in a later release.
docs/reference/cainjector.rst
+5 -11
View File
@@ -1,12 +1,6 @@
=====================
cainjector controller
=====================
==========
File moved
==========
The cainjector controller injects a Certificate into the ``caBundle`` field
of ValidatingWebhookConfiguration, MutatingWebhookConfiguration or
APIService resources annotated with:
* ``cert-manager.io/inject-apiserver-ca: "true"``
Injects the cluster CA.
* ``cert-manager.io/inject-ca-from: <NAMESPACE>/<CERTIFICATE>``
Injects the CA from the specified :doc:`certificate </reference/certificates>`.
This document has moved to https://cert-manager.netlify.com/docs/concepts/ca-injector/.
This placeholder file will be removed in a later release.
docs/reference/certificaterequests.rst
+5 -67
View File
@@ -1,68 +1,6 @@
===================
CertificateRequests
===================
==========
File moved
==========
A 'CertificateRequest' is a resource in cert-manager that is used to request
x509 certificates from an issuer. The resource contains a base64 encoded string
of a PEM encoded certificate request which is sent to the referenced issuer. A
successful issuance will return a signed certificate, based on the certificate
signing request. 'CertificateRequests' are typically consumed and managed by
controllers or other systems and should not be used by humans - unless
specifically needed.
A simple CertificateRequest looks like the following:
.. code-block:: yaml
:linenos:
apiVersion: cert-manager.io/v1alpha2
kind: CertificateRequest
metadata:
name: my-ca-cr
spec:
csr: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQzNqQ0NBY1lDQVFBd2daZ3hDekFKQmdOVkJBWVRBbHBhTVE4d0RRWURWUVFJREFaQmNHOXNiRzh4RFRBTApCZ05WQkFjTUJFMXZiMjR4RVRBUEJnTlZCQW9NQ0VwbGRITjBZV05yTVJVd0V3WURWUVFMREF4alpYSjBMVzFoCmJtRm5aWEl4RVRBUEJnTlZCQU1NQ0dwdmMyaDJZVzVzTVN3d0tnWUpLb1pJaHZjTkFRa0JGaDFxYjNOb2RXRXUKZG1GdWJHVmxkWGRsYmtCcVpYUnpkR0ZqYXk1cGJ6Q0NBU0l3RFFZSktvWklodmNOQVFFQkJRQURnZ0VQQURDQwpBUW9DZ2dFQkFLd01tTFhuQkNiRStZdTIvMlFtRGsxalRWQ3BvbHU3TlZmQlVFUWl1bDhFMHI2NFBLcDRZQ0c5Cmx2N2kwOHdFMEdJQUgydnJRQmxVd3p6ZW1SUWZ4YmQvYVNybzRHNUFBYTJsY2NMaFpqUlh2NEVMaER0aVg4N3IKaTQ0MWJ2Y01OM0ZPTlRuczJhRkJYcllLWGxpNG4rc0RzTEVuZmpWdXRiV01Zeis3M3ptaGZzclRJUjRzTXo3cQpmSzM2WFM4UkRjNW5oVVcyYU9BZ3lnbFZSOVVXRkxXNjNXYXVhcHg2QUpBR1RoZnJYdVVHZXlZUUVBSENxZmZmCjhyOEt3YTFYK1NwYm9YK1ppSVE0Nk5jQ043OFZnL2dQVHNLZmphZURoNWcyNlk1dEVidHd3MWdRbWlhK0MyRHIKWHpYNU13RzJGNHN0cG5kUnRQckZrU1VnMW1zd0xuc0NBd0VBQWFBQU1BMEdDU3FHU0liM0RRRUJDd1VBQTRJQgpBUUFXR0JuRnhaZ0gzd0N3TG5IQ0xjb0l5RHJrMUVvYkRjN3BJK1VVWEJIS2JBWk9IWEFhaGJ5RFFLL2RuTHN3CjJkZ0J3bmlJR3kxNElwQlNxaDBJUE03eHk5WjI4VW9oR3piN0FVakRJWHlNdmkvYTJyTVhjWjI1d1NVQmxGc28Kd005dE1QU2JwcEVvRERsa3NsOUIwT1BPdkFyQ0NKNnZGaU1UbS9wMUJIUWJSOExNQW53U0lUYVVNSFByRzJVMgpjTjEvRGNMWjZ2enEyeENjYVoxemh2bzBpY1VIUm9UWmV1ZEp6MkxmR0VHM1VOb2ppbXpBNUZHd0RhS3BySWp3ClVkd1JmZWZ1T29MT1dNVnFNbGRBcTlyT24wNHJaT3Jnak1HSE9tTWxleVdPS1AySllhaDNrVDdKU01zTHhYcFYKV0ExQjRsLzFFQkhWeGlKQi9Zby9JQWVsCi0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo=
isCA: false
duraton: 90d
issuerRef:
name: ca-issuer
# We can reference ClusterIssuers by changing the kind here.
# The default value is Issuer (i.e. a locally namespaced Issuer)
kind: Issuer
group: cert-manager.io
This CertificateRequest will make cert-manager attempt to make the Issuer
``letsencrypt-prod`` in the default issuer pool ``cert-manager.io``, return a
certificate based upon the certificate signing request. Other groups can be
specified inside the ``issuerRef`` which will change the targeted issuers to other
external, third party issuers you may have installed.
The resource also exposes the option for stating the certificate as CA and
requested validity duration.
A successful issuance of the certificate signing request will cause an update to
the resource, setting the status with the signed certificate, the CA of the
certificate (if available), and setting the `Ready` condition to `True`.
Whether issuance of the controller was successful or not, a retry of the
issuance will _not_ happen. It is the responsibility of some other controller to
manage the logic and life cycle of CertificateRequets.
----------
Conditions
----------
CertificateRequests have a set of strongly defined conditions that should be
used and relied upon by controllers or services to make decisions on what
actions to take next on the resource. Each condition consists of the pair
`Ready` - a boolean value, and `Reason` - a string. The set of values and
meanings are as follows:
+---------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| *Ready* | *Reason* | Condition Meaning |
+=========+=================+===============================================================================================================================================================================================================================================+
| False | Pending | The CertificateRequest is currently pending, waiting for some other operation to take place. This could be that the Issuer does not exist yet or the Issuer is in the process of issuing a certificate. |
+---------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| False | Failed | The certificate has failed to be issued - either the returned certificate failed to be decoded or an instance of the referenced issuer used for signing failed. No further action will be taken on the CertificateRequest by it's controller. |
+---------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| True | Issued | A signed certificate has been successfully issued by the referenced Issuer. |
+---------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
This document has moved to https://cert-manager.netlify.com/docs/concepts/certificaterequest/.
This placeholder file will be removed in a later release.
docs/reference/certificates.rst
+5 -148
View File
@@ -1,149 +1,6 @@
============
Certificates
============
==========
File moved
==========
cert-manager has the concept of 'Certificates' that define a desired X.509
certificate. A Certificate is a namespaced resource that references an
Issuer or ClusterIssuer for information on how to obtain the certificate.
A simple Certificate could be defined as:
.. code-block:: yaml
:linenos:
:emphasize-lines: 17-20
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
name: acme-crt
spec:
secretName: acme-crt-secret
dnsNames:
- foo.example.com
- bar.example.com
acme:
config:
- http01:
ingressClass: nginx
domains:
- foo.example.com
- bar.example.com
issuerRef:
name: letsencrypt-prod
# We can reference ClusterIssuers by changing the kind here.
# The default value is Issuer (i.e. a locally namespaced Issuer)
kind: Issuer
This Certificate will tell cert-manager to attempt to use the Issuer
named ``letsencrypt-prod`` to obtain a certificate key pair for the
``foo.example.com`` and ``bar.example.com`` domains. If successful, the
resulting key and certificate will be stored in a secret named
``acme-crt-secret`` with keys of ``tls.key`` and ``tls.crt`` respectively.
This secret will live in the same namespace as the ``Certificate`` resource.
The ``dnsNames`` field specifies a list of `Subject Alternative Names`_ to be
associated with the certificate. If the ``commonName`` field is omitted, the
first element in the list will be the common name.
The referenced Issuer must exist in the same namespace as the Certificate.
A Certificate can alternatively reference a ClusterIssuer which is
non-namespaced.
.. _`Subject Alternative Names`: https://en.wikipedia.org/wiki/Subject_Alternative_Name
***************************************
Certificate Duration and Renewal Window
***************************************
cert-manager Certificate resources also support custom validity durations and
renewal windows.
**Important**: The backend service implementation can choose to generate a
certificate with a different validity period than what is requested in the
issuer.
Although the duration and renewal periods are specified on the Certificate
resources, the corresponding Issuer or ClusterIssuer must support this.
The table below shows the support state of the different backend services used
by issuer types:
=========== ============================================================
Issuer Description
=========== ============================================================
ACME Only 'renewBefore' supported
CA Fully supported
Vault Fully supported (although the requested duration must be lower
than the configured Vault role's TTL)
Self Signed Fully supported
Venafi Fully supported
=========== ============================================================
The default duration for all certificates is 90 days and the default renewal
windows is 30 days. This means that certificates are considered valid for 3
months and renewal will be attempted within 1 month of expiration.
The *duration* and *renewBefore* parameters must be given in the golang `parseDuration string format <https://golang.org/pkg/time/#ParseDuration>`__.
Example Usage
=============
Here an example of an issuer specifying the duration and renewal window.
The certificate from the previous section is extended with a validity period of
24 hours and to begin trying to renew 12 hours before the certificate
expiration.
.. code-block:: yaml
:linenos:
:emphasize-lines: 7,8
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
name: example
spec:
secretName: example-tls
duration: 24h
renewBefore: 12h
dnsNames:
- foo.example.com
- bar.example.com
issuerRef:
name: my-internal-ca
kind: Issuer
************************
Certificate Key Encoding
************************
cert-manager Certificate resources support two types of key encodings
for its private key known as the private key cryptography standards (PKCS).
The two key encodings are PKCS#1 and PKCS#8.
The default encoding is PKCS#1, if the `keyEncoding` field of the Certificate spec is left empty.
A limitation exists where once a Certificate resource is generated with a
specific key encoding, it cannot be generated with a different key encoding.
Example Usage
=============
Here is an example of a Certificate specifying the use of PKCS#8 encoding on
its private key.
.. code-block:: yaml
:linenos:
:emphasize-lines: 7
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
name: example-pkcs8-cert
spec:
secretName: example-pkcs8-secret
keyEncoding: pkcs8
dnsNames:
- foo.example.com
- bar.example.com
issuerRef:
name: my-internal-ca
kind: Issuer
This document has moved to https://cert-manager.netlify.com/docs/concepts/certificate/.
This placeholder file will be removed in a later release.
docs/reference/challenges.rst
+3 -116
View File
@@ -1,119 +1,6 @@
==========
Challenges
File moved
==========
Challenge resources are used by the ACME issuer to manage the lifecycle of an
ACME 'challenge' that must be completed in order to complete an 'authorization'
for a single DNS name/identifier.
When an **Order** resource is created, the order controller will create
Challenge resources for each DNS name that is being authorized with the ACME
server.
As an end-user, you will never need to manually create a Challenge resource.
Once created, a Challenge cannot be changed. Instead, a new Challenge resource
must be created.
Challenge lifecycle
===================
After a Challenge resource has been created, it will be initially queued for
processing.
Processing will not begin until the challenge has been 'scheduled' to start.
This scheduling process prevents too many challenges being attempted at once,
or multiple challenges for the same DNS name being attempted at once.
For more information on how challenges are scheduled, read the
`challenge scheduling`_ section.
Once a challenge has been scheduled, it will first be 'synced' with the ACME
server in order to determine its current state. If the challenge is already
valid, its 'state' will be updated to 'valid', and also set
``status.processing = false`` to 'unschedule' itself.
If the challenge is still 'pending', the challenge controller will 'present'
the challenge using the configured solver, one of HTTP01 or DNS01.
Once the challenge has been 'presented', it will set ``status.presented=true``.
Once 'presented', the challenge controller will perform a 'self check' to
ensure that the challenge has 'propagated' (i.e. the authoritve DNS servers
have been updated to respond correctly, or the changes to the ingress resources
have been observed and in-use by the ingress controller).
If the self check fails, cert-manager will retry the self check with a fixed
10 second retry interval. Challenges that do not ever complete the self check
will continue retrying until the user intervenes.
Once the self check is passing, the ACME 'authorization' associated with this
challenge will be 'accepted' (TODO: add link to accepting challenges section of
ACME spec).
The final state of the authorization after accepting it will be copied across
to the Challenge's ``status.state`` field, as well as the 'error reason' if
an error occurred whilst the ACME server attempted to validate the challenge.
Once a Challenge has entered the ``valid``, ``invalid``, ``expired`` or
``revoked`` state, it will set ``status.processing=false`` to prevent any
further processing of the ACME challenge, and to allow another challenge to be
scheduled if there is a backlog of challenges to complete.
Challenge scheduling
====================
Instead of attempting to process all challenges at once, challenges are
'scheduled' by cert-manager.
This scheduler applies a cap on the maximum number of simultaneous challenges
as well as disallows two challenges for the same DNS name and solver type
(http-01 or dns-01) to be completed at once.
The maximum number of challenges that can be processed at a time is 60 as of
ddff78_.
Debugging Challenge resources
=============================
In order to determine why an ACME Certificate is not being issued, we can debug
using the 'Challenge' resources that cert-manager has created.
In order to determine which Challenge is failing, you can run
``kubectl get challenges``:
.. code-block:: shell
$ kubectl get challenges
NAME STATE DOMAIN REASON AGE
example-com-1217431265-0 pending example.com Waiting for dns-01 challenge propagation 22s
This shows that the challenge has been presented using the DNS01 solver
successfully and now cert-manager is waiting for the 'self check' to pass.
You can get more information about the challenge by using ``kubectl describe``:
.. code-block:: shell
$ kubectl describe challenge example-com-1217431265-0
...
Status:
Presented: true
Processing: true
Reason: Waiting for dns-01 challenge propagation
State: pending
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Started 19s cert-manager Challenge scheduled for processing
Normal Presented 16s cert-manager Presented challenge using dns-01 challenge mechanism
Progress about the state of each challenge will be recorded either as Events
or on the Challenge's ``status`` block (as shown above).
Troubleshooting failing challenges
==================================
.. todo::
add section describing common issues and resolutions when challenges are
failing
.. _ddff78: https://github.com/jetstack/cert-manager/blob/ddff78f011558e64186d61f7c693edced1496afa/pkg/controller/acmechallenges/scheduler/scheduler.go#L31-L33
This document has moved to https://cert-manager.netlify.com/docs/concepts/acme-orders-challenges/.
This placeholder file will be removed in a later release.
docs/reference/clusterissuers.rst
+5 -49
View File
@@ -1,50 +1,6 @@
==============
ClusterIssuers
==============
==========
File moved
==========
ClusterIssuers are a resource type similar to :doc:`Issuers </reference/issuers>`.
They are specified in exactly the same way, but they do not belong to a single
namespace and can be referenced by Certificate resources from multiple different
namespaces.
They are particularly useful when you want to provide the ability to obtain
certificates from a central authority (e.g. Letsencrypt, or your internal CA)
and you run single-tenant clusters.
The docs for Issuer resources apply equally to ClusterIssuers.
You can specify a ClusterIssuer resource by changing the ``kind`` attribute of
an Issuer to ``ClusterIssuer``, and removing the ``metadata.namespace`` attribute:
.. code-block:: yaml
:emphasize-lines: 2
apiVersion: cert-manager.io/v1alpha2
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
...
We can then reference a ClusterIssuer from a Certificate resource by setting
the ``spec.issuerRef.kind`` field to ClusterIssuer:
.. code-block:: yaml
:emphasize-lines: 10
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
name: my-certificate
namespace: my-namespace
spec:
secretName: my-certificate-secret
issuerRef:
name: letsencrypt-prod
kind: ClusterIssuer
...
When referencing a ``Secret`` resource in ``ClusterIssuer`` resources (eg ``apiKeySecretRef``) the ``Secret`` needs to be in the same namespace as the ``cert-manager`` controller pod. You can optionally override this by using the ``--cluster-resource-namespace`` argument to the controller.
For more information on configuring Issuer resources, see the :doc:`Issuers </reference/issuers>`
reference documentation.
This document has moved to https://cert-manager.netlify.com/docs/concepts/issuer/.
This placeholder file will be removed in a later release.
docs/reference/index.rst
+5 -21
View File
@@ -1,22 +1,6 @@
Reference documentation
=======================
==========
File moved
==========
This section contains detailed reference documentation about cert-manager's
types and how it operates. It also includes some simple example configurations
in order to help users activate advanced functionality of cert-manager.
Step by step user guides and tutorials can be found in the
:doc:`tutorials </tutorials/index>` section.
.. toctree::
:maxdepth: 2
:caption: Contents:
certificates
certificaterequests
orders
challenges
issuers
clusterissuers
cainjector
api-docs/index
This document has moved to https://cert-manager.netlify.com/docs/concepts/.
This placeholder file will be removed in a later release.
docs/reference/issuers.rst
+5 -147
View File
@@ -1,148 +1,6 @@
=======
Issuers
=======
==========
File moved
==========
Issuers (and :doc:`ClusterIssuers </reference/clusterissuers>`) represent a
certificate authority from which signed x509 certificates can be obtained, such
as `Let's Encrypt`_. You will need at least one Issuer or ClusterIssuer in
order to begin issuing certificates within your cluster.
An example of an Issuer type is ACME. A simple ACME issuer could be defined as:
.. code-block:: yaml
:linenos:
:emphasize-lines: 11, 20
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: letsencrypt-prod
namespace: edge-services
spec:
acme:
# The ACME server URL
server: https://acme-v02.api.letsencrypt.org/directory
# Email address used for ACME registration
email: user@example.com
# Name of a secret used to store the ACME account private key
privateKeySecretRef:
name: letsencrypt-prod
solvers:
# An empty 'selector' means that this solver matches all domains
- selector: {}
http01:
ingress:
class: nginx
This is the simplest of ACME issuers - it specifies no DNS-01 challenge
providers. HTTP-01 validation can be performed through using Ingress
resources by enabling the HTTP-01 challenge mechanism (with the ``http01: {}``
field).
More information on configuring ACME Issuers can be found :doc:`here </tasks/issuers/setup-acme/index>`.
***********
Namespacing
***********
An Issuer is a namespaced resource, and it is not possible to issue
certificates from an Issuer in a different namespace. This means you will need
to create an Issuer in each namespace you wish to obtain Certificates in.
If you want to create a single issuer than can be consumed in multiple
namespaces, you should consider creating a :doc:`ClusterIssuer <clusterissuers>`
resource. This is almost identical to the Issuer resource, however is
non-namespaced and so it can be used to issue Certificates across all namespaces.
*******************
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_ role, the following ClusterIssuer would make use of
those credentials to perform the ACME DNS01 challenge with route53.
.. code-block:: yaml
:linenos:
:emphasize-lines: 17-18
apiVersion: cert-manager.io/v1alpha2
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: user@example.com
privateKeySecretRef:
name: letsencrypt-prod
solvers:
# An empty 'selector' means that this solver matches all domains
- selector: {}
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 challenge
provider.
They will only be used if no credentials are supplied, even if the supplied
credentials are invalid.
By default, ambient credentials may be used by ClusterIssuers, but not regular
issuers. The ``--issuer-ambient-credentials`` and
``--cluster-issuer-ambient-credentials=false`` flags on 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.
**********************
Supported Issuer types
**********************
cert-manager has been designed to support pluggable Issuer backends. The
currently supported Issuer types are:
+------------------------------------------------------+----------------------------------------------------------------------+
| Name | Description |
+======================================================+======================================================================+
| :doc:`ACME </tasks/issuers/setup-acme/index>` | Supports obtaining certificates from an ACME server, validating with |
| | HTTP01 or DNS01 |
+------------------------------------------------------+----------------------------------------------------------------------+
| :doc:`CA </tasks/issuers/setup-ca>` | Supports issuing certificates using a simple signing keypair, stored |
| | in a Secret in the Kubernetes API server |
+------------------------------------------------------+----------------------------------------------------------------------+
| :doc:`Vault </tasks/issuers/setup-vault>` | Supports issuing certificates using HashiCorp Vault. |
+------------------------------------------------------+----------------------------------------------------------------------+
| :doc:`Self signed </tasks/issuers/setup-selfsigned>` | Supports issuing self signed certificates |
+------------------------------------------------------+----------------------------------------------------------------------+
| :doc:`Venafi </tasks/issuers/setup-venafi>` | Supports issuing certificates from Venafi Cloud & TPP |
+------------------------------------------------------+----------------------------------------------------------------------+
Each Issuer resource is of one, and only one type. The type of an Issuer is
inferred by which field it specifies in its spec, such as ``spec.acme``
for the ACME issuer, or ``spec.ca`` for the CA based issuer.
.. _`Let's Encrypt`: https://letsencrypt.org
.. _kube2iam: https://github.com/jtblin/kube2iam
This document has moved to https://cert-manager.netlify.com/docs/concepts/issuer/.
This placeholder file will be removed in a later release.
docs/reference/orders.rst
+5 -81
View File
@@ -1,82 +1,6 @@
======
Orders
======
==========
File moved
==========
Order resources are used by the ACME issuer to manage the lifecycle of an ACME
'order' for a signed TLS certificate.
When a Certificate resource is created that references an ACME issuer,
cert-manager will create an Order resource in order to obtain a signed
certificate.
As an end-user, you will never need to manually create an Order resource.
Once created, an Order cannot be changed. Instead, a new Order resource must be
created.
Debugging Order resources
=========================
In order to debug why a Certificate isn't being issued, we can first run
``kubectl describe`` on the Certificate resource we're having issues with:
.. code-block:: shell
$ kubectl describe certificate example-com
...
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Generated 1m cert-manager Generated new private key
Normal OrderCreated 1m cert-manager Created Order resource "example-com-1217431265"
We can see here that Certificate controller has created an Order resource to
request a new certificate from the ACME server.
Orders are a useful source of information when debugging failures issuing ACME
certificates. By running ``kubectl describe order`` on a particular order,
information can be gleaned about failures in the process:
.. code-block:: shell
$ kubectl describe order example-com-1248919344
...
Reason:
State: pending
URL: https://acme-v02.api.letsencrypt.org/acme/order/41123272/265506123
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Created 1m cert-manager Created Challenge resource "example-com-1217431265-0" for domain "test1.example.com"
Normal Created 1m cert-manager Created Challenge resource "example-com-1217431265-1" for domain "test2.example.com"
Here we can see that cert-manager has created two Challenge resources in order
to fulfil the requirements of the ACME order to obtain a signed certificate.
You can then go on to run
``kubectl describe challenge example-com-1217431265-0`` to further debug the
progress of the Order.
Once an Order is successful, you should see an event like the following:
.. code-block:: shell
$ kubectl describe order example-com-1248919344
...
Reason:
State: valid
URL: https://acme-v02.api.letsencrypt.org/acme/order/41123272/265506123
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Created 72s cert-manager Created Challenge resource "example-com-1217431265-0" for domain "test1.example.com"
Normal Created 72s cert-manager Created Challenge resource "example-com-1217431265-1" for domain "test2.example.com"
Normal OrderValid 4s cert-manager Order completed successfully
If the Order is not completing successfully, you can debug the challenges
for the Order by running ``kubectl describe`` on the Challenge resource.
For more information on debugging Challenge resources, read the
:doc:`challenge reference docs </reference/challenges>`.
This document has moved to https://cert-manager.netlify.com/docs/concepts/acme-orders-challenges/.
This placeholder file will be removed in a later release.
docs/tasks/backup-restore-crds.rst
+4 -53
View File
@@ -1,55 +1,6 @@
========================
Backing up and restoring
========================
If you need to uninstall cert-manager, or transfer your installation to a new
cluster, you can backup all of cert-manager's configuration in order to
later re-install.
Backing up
==========
File moved
==========
To backup all of your cert-manager configuration resources, run:
.. code-block:: shell
kubectl get -o yaml \
--all-namespaces \
issuer,clusterissuer,certificates,orders,challenges,certificaterequests > cert-manager-backup.yaml
If you are transferring data to a new cluster, you may also need to copy across
additional Secret resources that are referenced by your configured Issuers,
such as:
CA Issuers
----------
* The root CA Secret referenced by ``issuer.spec.ca.secretName``
Vault Issuers
-------------
* The token authentication Secret referenced by
``issuer.spec.vault.auth.tokenSecretRef``
* The approle configuration Secret referenced by
``issuer.spec.vault.auth.appRole.secretRef``
ACME Issuers
------------
* The ACME account private key Secret referenced by ``issuer.acme.privateKeySecretRef``
* Any Secrets referenced by DNS providers configured under the
``issuer.acme.dns01.providers`` and ``issuer.acme.solvers.dns01`` fields.
Restoring
=========
In order to restore your configuration, you can simply ``kubectl apply`` the
files created above after installing cert-manager.
.. code-block:: shell
kubectl apply -f cert-manager-backup.yaml
If you have migrated from an old cluster, you will need to make sure to run a
similar ``kubectl apply`` command to restore your Secret resources too.
This document has moved to https://cert-manager.netlify.com/docs/tutorials/backup/.
This placeholder file will be removed in a later release.
docs/tasks/index.rst
+5 -15
View File
@@ -1,16 +1,6 @@
=====
Tasks
=====
==========
File moved
==========
This section contains guides on using specific features of cert-manager, such
as configuring different Issuer types and any special settings that you may
want to configure.
.. toctree::
:maxdepth: 2
issuers/index
issuing-certificates/index
backup-restore-crds
uninstall/index
upgrading/index
This document has moved to https://cert-manager.netlify.com/docs/configuration/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/index.rst
+5 -82
View File
@@ -1,83 +1,6 @@
==================
Setting up Issuers
==================
==========
File moved
==========
Before you can begin issuing certificates, you must configure at least one
Issuer or ClusterIssuer resource in your cluster.
These represent a certificate authority from which signed x509 certificates can
be obtained, such as Let's Encrypt, or your own signing key pair stored in a
Kubernetes Secret resource. They are referenced by Certificate resources in
order to request certificates from them.
An :doc:`Issuer </reference/issuers>` is scoped to a single namespace, and can
only fulfill :doc:`Certificate </reference/certificates>` resources within its
own namespace. This is useful in a multi-tenant environment where multiple
teams or independent parties operate within a single cluster.
On the other hand, a :doc:`ClusterIssuer </reference/clusterissuers>` is a
cluster wide version of an :doc:`Issuer </reference/issuers>`. It is able to be
referenced by :doc:`Certificate </reference/certificates>` resources in any
namespace.
Users often create ``letsencrypt-staging`` and ``letsencrypt-prod``
:doc:`ClusterIssuers </reference/clusterissuers>` if they operate a
single-tenant environment and want to expose a cluster-wide mechanism for
obtaining TLS certificates from `Let's Encrypt`_.
Supported issuer types
======================
cert-manager supports a number of different issuer backends, each with their
own different types of configuration.
Please follow one of the below linked guides to learn how to set up the issuer
types you require:
* :doc:`CA <./setup-ca>` - issue certificates signed by a X509 signing keypair,
stored in a Secret in the Kubernetes API server.
* :doc:`Self signed <./setup-selfsigned>` - issue self signed certificates.
* :doc:`ACME <./setup-acme/index>` - issue certificates obtained by performing
challenge validations against an ACME server such as `Let's Encrypt`_.
* :doc:`Vault <./setup-vault>`- issue certificates from a Vault instance
configured with the `Vault PKI backend`_.
* :doc:`Venafi <./setup-venafi>` - issue certificates from a Venafi_ Cloud
or Trust Protection Platform instance.
Additional information
======================
There are a few key things to know about Issuers, but for full information
you can refer to the :doc:`Issuer reference docs </reference/issuers>`.
.. _issuer_vs_clusterissuer:
Difference between Issuers and ClusterIssuers
---------------------------------------------
ClusterIssuers are a resource type similar to :doc:`Issuers </reference/issuers>`.
They are specified in exactly the same way, but they do not belong to a single
namespace and can be referenced by Certificate resources from multiple different
namespaces.
They are particularly useful when you want to provide the ability to obtain
certificates from a central authority (e.g. Letsencrypt, or your internal CA)
and you run single-tenant clusters.
The resource spec is identical, and you should set the
``certificate.spec.issuerRef.kind`` field to ClusterIssuer when creating your
Certificate resources.
.. toctree::
:maxdepth: 2
:caption: Contents:
setup-acme/index
setup-ca
setup-selfsigned
setup-vault
setup-venafi
.. _`Let's Encrypt`: https://letsencrypt.org
.. _`Vault PKI backend`: https://www.vaultproject.io/docs/secrets/pki/index.html
.. _Venafi: https://venafi.com
This document has moved to https://cert-manager.netlify.com/docs/configuration/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/setup-acme/dns01/acme-dns.rst
+5 -102
View File
@@ -1,103 +1,6 @@
=========================
ACME-DNS
=========================
==========
File moved
==========
.. code-block:: yaml
:emphasize-lines: 10-14
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: example-issuer
spec:
acme:
...
solvers:
- dns01:
acmedns:
host: https://acme.example.com
accountSecretRef:
name: acme-dns
key: acmedns.json
In general, clients to acme-dns perform registration on the users behalf and inform
them of the CNAME entries they must create. This is not possible in cert-manager, it
is a non-interactive system. Registration must be carried out beforehand and the resulting
credentials JSON uploaded to the cluster as a secret. In this example, we use ``curl`` and the
API endpoints directly. Information about setting up and configuring acme-dns is available on
the `acme-dns project page <https://github.com/joohoi/acme-dns>`_.
1. First, register with the acme-dns server, in this example, there is one running at "auth.example.com"
``curl -X POST http://auth.example.com/register`` will return a JSON with credentials for your registration:
.. code-block :: json
{
"username":"eabcdb41-d89f-4580-826f-3e62e9755ef2",
"password":"pbAXVjlIOE01xbut7YnAbkhMQIkcwoHO0ek2j4Q0",
"fulldomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com",
"subdomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf",
"allowfrom":[]
}
It is strongly recommended to restrict the update endpoint to the IP range of your pods.
This is done at registration time as follows:
``curl -X POST http://auth.example.com/register -H "Content-Type: application/json" --data '{"allowfrom": ["10.244.0.0/16"]}'``
Make sure to update the ``allowfrom`` field to match your cluster configuration. The JSON will now look like
.. code-block :: json
{
"username":"eabcdb41-d89f-4580-826f-3e62e9755ef2",
"password":"pbAXVjlIOE01xbut7YnAbkhMQIkcwoHO0ek2j4Q0",
"fulldomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com",
"subdomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf",
"allowfrom":["10.244.0.0/16"]
}
2. Save this JSON to a file with the key as your domain. You can specify multiple domains with the same credentials
if you like. In our example, the returned credentials can be used to verify ownership of "example.com" and
and "example.org".
.. code-block :: json
{
"example.com": {
"username":"eabcdb41-d89f-4580-826f-3e62e9755ef2",
"password":"pbAXVjlIOE01xbut7YnAbkhMQIkcwoHO0ek2j4Q0",
"fulldomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com",
"subdomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf",
"allowfrom":["10.244.0.0/16"]
},
"example.org": {
"username":"eabcdb41-d89f-4580-826f-3e62e9755ef2",
"password":"pbAXVjlIOE01xbut7YnAbkhMQIkcwoHO0ek2j4Q0",
"fulldomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com",
"subdomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf",
"allowfrom":["10.244.0.0/16"]
}
}
3. Next update your primary DNS server with CNAME record that will tell the verifier how to locate the challenge TXT
record. This is obtained from the "fulldomain" field in the registration:
``_acme-challenge.example.com CNAME d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com``
``_acme-challenge.example.org CNAME d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com``
Note that the "name" of the record is always the "_acme-challenge" subdomain, and the "value" of the record matches
exactly the "fulldomain" field from registration.
At verification time, the domain name ``d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com`` will be a TXT
record that is set to your validation token. When the verifier queries ``_acme-challenge.example.com``, it will
be directed to the correct location by this CNAME record. This proves that you control "example.com"
4. Create a secret from the credentials json that was saved in step 2, this secret is referenced
in the ``accountSecretRef`` field of your dns01 issuer settings.
``kubectl create secret generic acme-dns --from-file acmedns.json``
.. _`Let's Encrypt`: https://letsencrypt.org
This document has moved to https://cert-manager.netlify.com/docs/configuration/acme/dns01/acme-dns/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/setup-acme/dns01/akamai.rst
+5 -26
View File
@@ -1,27 +1,6 @@
=========================
Akamai FastDNS
=========================
==========
File moved
==========
.. code-block:: yaml
:emphasize-lines: 10-20
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: example-issuer
spec:
acme:
...
solvers:
- dns01:
akamai:
serviceConsumerDomain: akab-tho6xie2aiteip8p-poith5aej0ughaba.luna.akamaiapis.net
clientTokenSecretRef:
name: akamai-dns
key: clientToken
clientSecretSecretRef:
name: akamai-dns
key: clientSecret
accessTokenSecretRef:
name: akamai-dns
key: accessToken
This document has moved to https://cert-manager.netlify.com/docs/configuration/acme/dns01/akamai/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/setup-acme/dns01/azuredns.rst
+5 -69
View File
@@ -1,70 +1,6 @@
=========================
AzureDNS
=========================
==========
File moved
==========
Configuring the AzureDNS DNS-01 Challenge for a Kubernetes cluster requires creating a service principal in Azure.
For security purposes, it is appropriate to utilize RBAC to ensure that you properly maintain access control to your resources in Azure. The service principal that is generated by this tutorial has fine grained access to ONLY the DNS Zone in the specific resource group specified. It requires this permission so that it can read/write the _acme_challenge TXT records to the zone.
To create the service principal you can use the following script (requires ``azure-cli`` and ``jq``):
.. code-block:: bash
:linenos:
AZURE_CERT_MANAGER_SP_NAME=SOME_SERVICE_PRINCIPAL_NAME
AZURE_CERT_MANAGER_DNS_RESOURCE_GROUP=SOME_RESOURCE_GROUP
AZURE_CERT_MANAGER_DNS_NAME=SOME_DNS_ZONE
DNS_SP=$(az ad sp create-for-rbac --name $AZURE_CERT_MANAGER_SP_NAME)
AZURE_CERT_MANAGER_SP_APP_ID=$(echo $DNS_SP | jq -r '.appId')
AZURE_CERT_MANAGER_SP_PASSWORD=$(echo $DNS_SP | jq -r '.password')
# Lower the Permissions of the SP
az role assignment delete --assignee $AZURE_CERT_MANAGER_SP_APP_ID --role Contributor
# Give Access to DNS Zone
DNS_ID=$(az network dns zone show --name $AZURE_CERT_MANAGER_DNS_NAME --resource-group $AZURE_CERT_MANAGER_DNS_RESOURCE_GROUP --query "id" --output tsv)
az role assignment create --assignee $AZURE_CERT_MANAGER_SP_APP_ID --role "DNS Zone Contributor" --scope $DNS_ID
# Check Permissions
az role assignment list --assignee $AZURE_CERT_MANAGER_SP_APP_ID
# Create Secret
kubectl create secret generic azuredns-config \
--from-literal=CLIENT_SECRET=$AZURE_CERT_MANAGER_SP_PASSWORD
# Get the Service Principal App ID for configuration
echo "Principal: $AZURE_CERT_MANAGER_SP_APP_ID"
echo "Password: $AZURE_CERT_MANAGER_SP_PASSWORD"
You can configure the issuer like so:
.. code-block:: yaml
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: example-issuer
spec:
acme:
...
solvers:
- dns01:
azuredns:
# Service principal clientId (also called appId)
clientID: AZURE_SERVICE_PRINCIPAL_ID
# A secretKeyRef to a service principal ClientSecret (password)
# ref: https://docs.microsoft.com/en-us/azure/container-service/kubernetes/container-service-kubernetes-service-principal
clientSecretSecretRef:
name: AZUREDNS_SECRET_KEY_NAME
key: CLIENT_SECRET
# Azure subscription Id
subscriptionID: AZURE_SUBSCRIPTION_ID
# Azure AD tenant Id
tenantID: AZURE_TENANT_ID
# ResourceGroup name where dns zone is provisioned
resourceGroupName: AZURE_RESOURCE_GROUP
hostedZoneName: AZURE_DNS_ZONE_NAME
# Azure Cloud Environment, default to AzurePublicCloud
environment: AZURE_ENVIRONMENT
This document has moved to https://cert-manager.netlify.com/docs/configuration/acme/dns01/azuredns/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/setup-acme/dns01/cloudflare.rst
+5 -20
View File
@@ -1,21 +1,6 @@
=========================
Cloudflare
=========================
==========
File moved
==========
.. code-block:: yaml
:emphasize-lines: 10-14
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: example-issuer
spec:
acme:
...
solvers:
- dns01:
cloudflare:
email: my-cloudflare-acc@example.com
apiKeySecretRef:
name: cloudflare-api-key-secret
key: api-key
This document has moved to https://cert-manager.netlify.com/docs/configuration/acme/dns01/cloudflare/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/setup-acme/dns01/digitalocean.rst
+5 -27
View File
@@ -1,28 +1,6 @@
=========================
DigitalOcean
=========================
==========
File moved
==========
This provider uses a Kubernetes ``Secret`` Resource to work. In the
following example, the secret will have to be named ``digitalocean-dns``
and have a subkey ``access-token`` with the token in it.
To create a Personnal Access Token, see `DigitalOcean documentation <https://www.digitalocean.com/docs/api/create-personal-access-token/>`_.
Handy direct link: https://cloud.digitalocean.com/account/api/tokens/new
.. code-block:: yaml
:emphasize-lines: 10-13
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: example-issuer
spec:
acme:
...
solvers:
- dns01:
digitalocean:
tokenSecretRef:
name: digitalocean-dns
key: access-token
This document has moved to https://cert-manager.netlify.com/docs/configuration/acme/dns01/digitalocean/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/setup-acme/dns01/google.rst
+5 -100
View File
@@ -1,101 +1,6 @@
=========================
Google CloudDNS
=========================
==========
File moved
==========
This guide explains how to set up an Issuer, or ClusterIssuer, to use Google CloudDNS to solve DNS01 ACME challenges. It's advised you read the :doc:`DNS01 Challenge Provider <./index>` page first for a more general understanding of how cert-manager handles DNS01 challenges.
.. note::
This guide assumes that your cluster is hosted on Google Cloud Platform (GCP) and that you already have a domain set up with CloudDNS.
Set up a Service Account
========================
Cert-manager needs to be able to add records to CloudDNS in order to solve the DNS01 challenge. To enable this, a GCP service account must be created with the ``dns.admin`` role.
.. note::
For this guide the ``gcloud`` command will be used to set up the service account. Ensure that ``gcloud`` is in using the correct project and zone before entering the commands. These steps could also be completed using the Cloud Console.
.. code-block:: shell
export PROJECT_ID=myproject-id
gcloud iam service-accounts create dns01-solver \
--display-name "dns01-solver"
# Replace both uses of project-id with the id of your project
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:dns01-solver@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/dns.admin
Create a Service Account Secret
===============================
To access this service account cert-manager uses a key stored in a Kubernetes Secret. First, create a key for the service account and download it as JSON file, then create a Secret from this file.
If you did not create the service "dns01-solver" account before, you need to create it first:
.. code-block:: shell
gcloud iam service-accounts create dns01-solver
.. code-block:: shell
# Replace use of project-id with the id of your project
gcloud iam service-accounts keys create key.json \
--iam-account dns01-solver@$PROJECT_ID.iam.gserviceaccount.com
kubectl create secret generic clouddns-dns01-solver-svc-acct \
--from-file=key.json
.. note::
Keep the key file safe and do not share it, as it could be used to gain access to your cloud resources. The key file can be deleted once it has been used to generate the Secret.
.. note::
If you have already added the secret but get an error: `...due to error processing: error getting clouddns service account: secret "XXX" not found`, the secret may be in the wrong namespace. If you're configuring a `ClusterIssuer`, try moving the secret to the same namespace as cert-manager. If you're configuring an `Issuer`, the secret should be stored in the same namespace as the `Issuer` resource.
Create an Issuer That Uses CloudDNS
===================================
Next, create an Issuer (or ClusterIssuer) with a ``clouddns`` provider. An example Issuer manifest can be seen below with annotations.
.. code-block:: yaml
:linenos:
:emphasize-lines: 10-16
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: example-issuer
spec:
acme:
...
solvers:
- dns01:
clouddns:
# The ID of the GCP project
project: $PROJECT_ID
# This is the secret used to access the service account
serviceAccountSecretRef:
name: clouddns-dns01-solver-svc-acct
key: key.json
For more information about Issuers and ClusterIssuers, see :doc:`Setting Up Issuers </tasks/issuers/index>`.
Once an Issuer (or ClusterIssuer) has been created successfully a Certificate can then be added to verify that everything works.
.. code-block:: yaml
:linenos:
:emphasize-lines: 9-10
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
name: example-com
namespace: default
spec:
secretName: example-com-tls
issuerRef:
# The issuer created previously
name: example-issuer
commonName: example.com
dnsNames:
- example.com
- www.example.com
For more details about Certificates, see :doc:`Issuing Certificates </tasks/issuing-certificates/index>`.
This document has moved to https://cert-manager.netlify.com/docs/configuration/acme/dns01/google/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/setup-acme/dns01/index.rst
+5 -127
View File
@@ -1,128 +1,6 @@
=====================================
Configuring DNS01 Challenge Providers
=====================================
==========
File moved
==========
This page contains details on the different options available on the ``Issuer``
resource's DNS01 challenge solver configuration.
For more information on configuring ACME issuers and their API format, read the
:doc:`Setting up ACME Issuers <../index>` documentation.
DNS01 provider configuration must be specified on the Issuer resource, similar
to the examples in the setting up documentation:
You can read about how the DNS01 challenge type works on the
`Let's Encrypt challenge types page`_.
.. _`Let's Encrypt challenge types page`: https://letsencrypt.org/docs/challenge-types/#dns-01-challenge
.. code-block:: yaml
:linenos:
:emphasize-lines: 12-17
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: example-issuer
spec:
acme:
email: user@example.com
server: https://acme-staging-v02.api.letsencrypt.org/directory
privateKeySecretRef:
name: example-issuer-account-key
solvers:
- dns01:
clouddns:
project: my-project
serviceAccountSecretRef:
name: prod-clouddns-svc-acct-secret
key: service-account.json
Each issuer can specify multiple different DNS01 challenge providers, and
it is also possible to have multiple instances of the same DNS provider on a
single Issuer (e.g. two clouddns accounts could be set, each with their own
name).
For more information on utilising multiple solver types on a single Issuer,
read the multiple-solver-types_ section.
Setting nameservers for DNS01 self check
========================================
cert-manager will check the correct DNS records exist before attempting a DNS01
challenge.
By default, the DNS servers for this check will be taken from
``/etc/resolv.conf``.
If this is not desired (for example with multiple authoritative nameservers or
split-horizon DNS), the cert-manager controller exposes a flag that allows you
alter this behaviour:
Example usage::
--dns01-recursive-nameservers "8.8.8.8:53,1.1.1.1:53"
If you're using the `cert-manager` helm chart, you can set recursive nameservers
through `.Values.extraArgs` or at the command at helm install/upgrade time
with `--set`:
--set 'extraArgs={--dns01-recursive-nameservers=8.8.8.8:53\,1.1.1.1:53}'
.. _supported-dns01-providers:
Delegated Domains for DNS01
===========================
By default, cert-manager will not follow CNAME records pointing to subdomains.
If granting cert-manager access to the root DNS zone is not desired, then the
_acme-challenge.example.com subdomain can instead be delegated to some other,
less privileged domain.
Once a CNAME record has been configured to point at the desired domain, and the
DNS configuration/credentials for the zone that *should be updated* have been
provided, all that is left to be done is adding an additional field into the
relevant `dns01` solver:
.. code-block:: yaml
:linenos:
:emphasize-lines: 11
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
...
spec:
acme:
...
solvers:
- dns01:
# Valid values are None and Follow
cnameStrategy: Follow
clouddns:
...
cert-manager will then follow CNAME records recursively in order to determine
which DNS zone to update during DNS01 challenges.
*************************
Supported DNS01 providers
*************************
A number of different DNS providers are supported for the ACME issuer. Below is
a listing of available providers, their `.yaml` configurations, along with additional Kubernetes
and provider specific notes regarding their usage.
.. toctree::
:maxdepth: 1
acme-dns
akamai
azuredns
cloudflare
google
route53
digitalocean
rfc2136
webhook
This document has moved to https://cert-manager.netlify.com/docs/configuration/acme/dns01/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/setup-acme/dns01/rfc2136.rst
+5 -213
View File
@@ -1,214 +1,6 @@
RFC-2136
========
==========
File moved
==========
The goal of this document is to provide a configuration overview of the
various facilities required to deploy cert-manager against a RFC-2136
compliant DNS server such as BIND ``named``. This capability is also
commonly known as “dynamic DNS”.
Unlike the peer of other cert-manager DNS integrations, ``named`` is a bit of a
“Swiss Army Knife” of domain name servers. Over the years, it has been
highly optimized to provide maximal vertical scalability for a single
node, as well as horizontal scalability with service provider
interfaces. This flexibility makes it impossible to go into every possible
``named`` deployment that a user may run in to though. Instead, this
document will try to make sure your server is ready
to accept requests from cert-manager using command line tools, then get
on to the making the two work together.
Transaction Signatures ⇒ TSIG
-----------------------------
Dynamic DNS updates are essentially server queries which otherwise might
return resource records (RRs). Since DNS servers are commonly exposed to
the public internet, being able to push an unauthenticated update to any
server that responds to queries would be immediately untenable.
In the eyes of the ``named`` architects, the generic solution to this
problem space was twofold. The first is to require manual enablement of
updates at a zone level, such as ``example.com``. In a naive network,
there is no requirement that zone updates have any security to them, and
clients can be configured such that they can provide updates without any
authentication. An example of where this is useful is for machines
booting using DHCP, in this case the machines know about themselves and
the DNS server can be configured to accept updates when they come from
the address being configured.
This clearly has limitations in situations such as cert-manager and the
DNS-01 challenge. In this environment, a TXT RR must be created after
coordination with the ACME server. After negotiating with the ACME server,
a the TXT RR that is published on the domain validates that the
domain is legitimately engaged with the process of creating a
certificate for it. In the bigger picture of DNS, this
means that an arbitrary actor (cert-manager, in this case) must be able
to add one of these KV mappings to the domain and delete it after the
certificate has been issued. ``cert-manager`` does not have a convenient
physical characteristic such as a DHCP allocation to validate it's requests.
For cases like this, we need to be able to sign a request that is being
sent to the DNS server. We do that through TSIGs, or Transaction
SIGnatures.
Configuration Step 1 - Set up your DNS server for secure dynamic updates
------------------------------------------------------------------------
There are many excellent tutorials on the net that walk through
preparing a basic ``named`` server for dynamic updates:
- https://www.cyberciti.biz/faq/unix-linux-bind-named-configuring-tsig/
- https://tomthorp.me/blog/using-tsig-enable-secure-zone-transfers-between-bind-9x-servers
More complex ``named`` deployments will not use text files, but rather
may use LDAP or SQL for a database for resource records. An additional
wrinkle is metadata configuration, such as for zone metadata like
enabling dynamic updates or access control lists (ACLs) for a zone.
There are too many configurations to go into here, but you should be
able to find the documentation to do so.
Whatever your deployment is, the goal at this stage has nothing to do
with cert-manager and everything to do with a tool called ``nsupdate``
generating updates signed with TSIG. Once this is out of the way, you
can attack the cert-manager configuration with far greater confidence.
Using ``nsupdate``
~~~~~~~~~~~~~~~~~~
Most paths to configuring BIND ``named`` will go through using
``dnssec-keygen``. This command-line tool generates a named private key
that is used for signing TSIG requests. When a request is signed, both
the signature and the name of the private key are attached to the
request in an unencrypted form. In this manner, when the request is
received, the name of the private key can be used to by the recipient to
find the private key itself, build a new signature with it, and compare
the two for acceptance.
Since there are dozens of ways to have your ``named`` server
misconfigured, we’ll use ``nsupdate`` to test that the server behaves as
expected before we get there.
https://debian-administration.org/article/591/Using_the_dynamic_DNS_editor_nsupdate
is a solid breakdown of how to use the tool.
To get started, we’ll simply run ``nsupdate -k <keyID>`` where keyID is
the value returned from ``dnssec-keygen``. This will read the key from
disk and provide a command prompt to issue commands. In general, we want
to write a simple TXT RR and make sure we can delete it.
::
$ nsupdate -k <keyID>
> update add www1.example.com txt testing
> send
> … test here with ``nslookup``
> update delete www1.example.com txt
> send
> … test here with ``nslookup``
Any failures to write, read or delete the record will mean that
cert-manager will not be able to do so either, no matter how well it is
configured.
Configuration Step 2 - Set up cert-manager
------------------------------------------
Now we get to the fun stuff, seeing everything work. Remember that we
need to set up the ACME DNS-01 issuer and challenge mechanism as well as
the ``rfc2136`` provider. Since the documentation covers the other parts
sufficiently, let’s focus on the provider here.
.. code:: yaml
:emphasize-lines: 10-16
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: example-issuer
spec:
acme:
...
solvers:
- dns01:
rfc2136:
nameserver: <address of authoritative nameserver configured above>
tsigKeyName: <key name used in `dnssec-keygen`, use something semantically meaningful in both environments>
tsigAlgorithm: HMACSHA512 // should be matched to the algo you chose in `dnssec-keygen`
tsigSecretSecretRef:
name: <the name of the k8s secret holding the TSIG key.. not the key itself!>
key: <name of the key *inside* the secret>
For example:
.. code:: yaml
rfc2136:
nameserver: 1.2.3.4:53
tsigKeyName: example-com-secret
tsigAlgorithm: HMACSHA512
tsigSecretSecretRef:
name: tsig-secret
key: tsig-secret-key
For this example configuration, we’ll need the following two commands.
The first, on your ``named`` server generates the key. Note how
``example-com-secret`` is both in the ``tsigKeyName`` above and the
``dnssec-keygen`` command that follows.
::
dnssec-keygen -r /dev/urandom -a HMAC-SHA512 -b 512 -n HOST example-com-secret
Also note how the ``tsigAlgorithm`` is provided in both the
configuration and the keygen command. They are listed at
https://github.com/miekg/dns/blob/v1.0.12/tsig.go#L18-L23.
The second bit of configuration you need on the kubernetes side is to
create a secret. Pulling the secret key string from the
``<key>.private`` file generated above, use the secret in the
placeholder below:
::
kubectl -n cert-manager create secret generic tsig-secret --from-literal=tsig-secret-key=<somesecret>
Note how the ``tsig-secret`` and ``tsig-secret-key`` match the
configuration in the ``tsigSecretSecretRef`` above.
Rate Limits
-----------
The ``rfc2136`` provider waits until *all* nameservers to in your domain's SOA RR respond with the same result before
it contacts Let's Encrypt to complete the challenge process. This is because the challenge server contacts a
non-authoritative DNS server that does a recursive query (a query for records it does not maintain locally). If the
servers in the SOA do not contain the correct values, it's likely that the non-authoritative server will have
bad information as well, causing the request to go against rate limits and eventually locking the process out.
This process is in place to protect users from server misconfigurations creating a more subtle lockout that persists
after the server configuration has been repaired.
As documented elsewhere, it is prudent to fully debug configurations using the ACME staging servers before using
the production servers. The staging servers have less aggressive rate limits, but the certificates they issue are
not signed with a root certificate trusted by browsers.
What’s next?
------------
This configuration so far will actually do nothing. You still have to
request a certificate as in :doc:`/tasks/issuing-certificates/index`. Once a certficate is requested,
the provider will begin processing the request.
Troubleshooting
---------------
* Be sure that you have fully tested the DNS server updates using ``nsupdate`` first. Ideally, this is done from
a pod in the same namespace as the ``rfc2136`` provider to ensure there are no firewall issues.
* The logs for the ``cert-manager`` pod are your friend. Additional logs can be generated by adding the ``--v=5``
argument to the container launch.
* The TSIG key is encoded with ``base64``, but the Kubernetes API server also expects that key literals will be
decoded before they are stored. In some cases, a key must be double-encoded. (If you've tested using ``nsupdate``,
it's pretty easy to spot when you are running into this.)
* Pay attention to the refresh time of the zone you are working with. For zones with low traffic, it will not make a
significant difference to reduce the refresh time down to about five minutes while getting initial certificates.
Once the process is working, the beauty of ``cert-manager`` is it doesn't matter if a renewal takes hours due to
refresh times, it's all automated!
* Compared to the other providers that often use REST APIs to modify DNS RRs, this provider can take a little longer.
You can ``watch kubectl certificate yourcert`` to get a display of what's going on. It's not uncommon for the process
to take five minutes in total.
This document has moved to https://cert-manager.netlify.com/docs/configuration/acme/dns01/rfc2136/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/setup-acme/dns01/route53.rst
+5 -126
View File
@@ -1,127 +1,6 @@
=========================
Amazon Route53
=========================
==========
File moved
==========
This guide explains how to set up an Issuer, or ClusterIssuer, to use Amazon Route53 to solve DNS01 ACME challenges. It's advised you read the :doc:`DNS01 Challenge Provider <./index>` page first for a more general understanding of how cert-manager handles DNS01 challenges.
.. note::
This guide assumes that your cluster is hosted on Amazon Web Services (AWS) and that you already have a hosted zone in Route53.
Set up a IAM Role
========================
Cert-manager needs to be able to add records to Route53 in order to solve the DNS01 challenge. To enable this, create a IAM policy with the following permissions:
.. code-block:: json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "route53:GetChange",
"Resource": "arn:aws:route53:::change/*"
},
{
"Effect": "Allow",
"Action": [
"route53:ChangeResourceRecordSets",
"route53:ListResourceRecordSets"
],
"Resource": "arn:aws:route53:::hostedzone/*"
},
{
"Effect": "Allow",
"Action": "route53:ListHostedZonesByName",
"Resource": "*"
}
]
}
.. note::
The ``route53:ListHostedZonesByName`` statement can be removed if you specify
the (optional) ``hostedZoneID``. You can further tighten the policy by limiting the hosted
zone that cert-manager has access to (e.g. ``arn:aws:route53:::hostedzone/DIKER8JEXAMPLE``).
Credentials
========================
You have two options for the set up: Either create a user or a role and attach that policy from above.
Using a role is considered best practice because you do not have to store permanent credentials in a secret.
Cert-manager supports two ways of specifying credentials:
* explicit by providing a ``accessKeyID`` and ``secretAccessKey``
* or implicit (using `metadata service <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html>`_ or `env vars or credentials file <https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials>`_)
Cert-manager also supports specifying a ``role`` to enable cross-account access and/or to limit the access for the cert-manager. Integration with `kiam <https://github.com/uswitch/kiam>`_ and `kube2iam <https://github.com/jtblin/kube2iam>`_ should work out of the box.
Cross account access
_____________________
Example: Account A manages a Route53 DNS Zone. Now you want account X to be able to manage records in that zone.
First, create a role with the policy above (let's call the role ``dns-manager``) and attach a trust relationship like the one below. Make sure role ``cert-manager`` in account X exists:
.. code-block:: json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::XXXXXXXXXXX:role/cert-manager"
},
"Action": "sts:AssumeRole"
}
]
}
This allows the role ``cert-manager`` in account X to manage the Route53 DNS Zone in account A.
For more information visit the `official documentation <https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html>`_.
Creating a Issuer (or ClusterIssuer)
====================================
Here is an example configuration for a ClusterIssuer:
.. code:: yaml
apiVersion: cert-manager.io/v1alpha2
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
acme:
...
solvers:
# example: cross-account zone management for example.com
# this solver uses ambient credentials (i.e. inferred from the environment or EC2 Metadata Service)
# to assume a role in a different account
- selector:
dnsZones:
- "example.com"
dns01:
route53:
region: us-east-1
hostedZoneID: DIKER8JEXAMPLE # optional, see bpolicy above
role: arn:aws:iam::XXXXXXXXXXXX:role/dns-manager
# this solver handles foobar.cloud challenges
# and uses explicit credentials
- selector:
dnsZones:
- "foobar.cloud"
dns01:
route53:
region: eu-central-1
accessKeyID: AKIAIOSFODNN7EXAMPLE
secretAccessKeySecretRef:
name: prod-route53-credentials-secret
key: secret-access-key
# you can also assume a role with these credentials
role: arn:aws:iam::XXXXXXXXXXXX:role/dns-manager
This document has moved to https://cert-manager.netlify.com/docs/configuration/acme/dns01/route53/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/setup-acme/dns01/webhook.rst
+5 -32
View File
@@ -1,33 +1,6 @@
=========================
Webhook
=========================
==========
File moved
==========
The webhook issuer is a generic acme solver. The actual work is done by an external service. Look at the respective documentation of the `solver`.
Existing webhook solvers:
* `alidns-webhook <https://github.com/pragkent/alidns-webhook>`_
* `cert-manager-webhook-dnspod <https://github.com/qqshfox/cert-manager-webhook-dnspod>`_
* `cert-manager-webhook-selectel <https://github.com/selectel/cert-manager-webhook-selectel>`_
* `cert-manager-webhook-softlayer <https://github.com/cgroschupp/cert-manager-webhook-softlayer>`_
See more webhook solver on: https://github.com/topics/cert-manager-webhook
.. code-block:: yaml
:emphasize-lines: 10-14
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: example-issuer
spec:
acme:
...
solvers:
- dns01:
webhook:
groupName: <webhook-group-name>
solverName: <webhook-solver-name>
config:
...
<webhook-specific-configuration>
This document has moved to https://cert-manager.netlify.com/docs/configuration/acme/dns01/webhook/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/setup-acme/http01/index.rst
+5 -110
View File
@@ -1,111 +1,6 @@
===================================
Configuring HTTP01 Ingress Provider
===================================
==========
File moved
==========
This page contains details on the different options available on the ``Issuer``
resource's HTTP01 challenge solver configuration.
For more information on configuring ACME issuers and their API format, read the
:doc:`Setting up ACME Issuers <../index>` documentation.
How HTTP01 validations work
===========================
You can read about how the HTTP01 challenge type works on the
`Let's Encrypt challenge types page`_.
.. _`Let's Encrypt challenge types page`: https://letsencrypt.org/docs/challenge-types/#http-01-challenge
Options
=======
The HTTP01 Issuer supports a number of additional options.
For full details on the range of options available, read the
`reference documentation`_.
.. _`reference documentation`: https://docs.cert-manager.io/en/latest/reference/api-docs/index.html#acmeissuerhttp01config-v1alpha2
ingressClass
------------
If the ``ingressClass`` field is specified, cert-manager will create new
Ingress resources in order to route traffic to the 'acmesolver' pods, which
are responsible for responding to ACME challenge validation requests.
If this field is not specified, and ``ingressName`` is also not specified,
cert-manager will default to create **new** ingress resources but will **not**
set the ingress class on these resources, meaning **all** ingress controllers
installed in your cluster will server traffic for the challenge solver,
potentially occurring additional cost.
ingressName
-----------
If the 'ingressName' field is specified, cert-manager will edit the named
ingress resource in order to solve HTTP01 challenges.
This is useful for compatibility with ingress controllers such as ingress-gce_,
which utilise a unique IP address for each Ingress resource created.
This mode should be avoided when using ingress controllers that expose a single
IP for all ingress resources, as it can create compatibility problems with
certain ingress-controller specific annotations.
servicePort
-----------
In rare cases it might be not possible/desired to use NodePort as type for the
http01 challenge response service, e.g. because of Kubernetes limit
restrictions. To define which Kubernetes service type to use during challenge
response specify the following http01 config:
.. code-block:: yaml
http01:
# Valid values are ClusterIP and NodePort
serviceType: ClusterIP
By default type NodePort will be used when you don't set http01 or when you set
serviceType to an empty string. Normally there's no need to change this.
podTemplate
-----------
You may wish to change or add to the labels and annotations of solver pods.
These can be configured under the ``metadata`` field under ``podTemplate``.
Similarly, you can set the nodeSelector, tolerations and affinity of solver
pods by configuring under the ``spec`` field of the ``podTemplate``. No other
spec fields can be edited.
An example of how you could configure the template is as so:
.. code-block:: yaml
:linenos:
:emphasize-lines: 13-20
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: ...
spec:
acme:
server: ...
privateKeySecretRef:
name: ...
solvers:
- http01:
ingress:
podTemplate:
metadata:
labels:
foo: "bar"
env: "prod"
spec:
nodeSelector:
bar: baz
The added labels and annotations will merge on top of the cert-manager defaults,
overriding entries with the same key.
No other fields can be edited.
This document has moved to https://cert-manager.netlify.com/docs/configuration/acme/http01/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/setup-acme/index.rst
+5 -177
View File
@@ -1,178 +1,6 @@
=======================
Setting up ACME Issuers
=======================
==========
File moved
==========
The ACME Issuer type represents a single Account registered with the ACME
server.
When you create a new ACME Issuer, cert-manager will generate a private key
which is used to identify you with the ACME server.
To set up a basic ACME issuer, you should create a new Issuer or ClusterIssuer
resource.
You should read the guides linked at the bottom of this page to learn more
about the ACME challenge validation mechanisms that cert-manager supports and
how to configure the various DNS01 provider implementations.
Creating a basic ACME Issuer
============================
The below example configures a ClusterIssuer named ``letsencrypt-staging`` that
is configured to HTTP01 challenge solving with configuration suitable for
ingress controllers such as ingress-nginx_.
You should copy and paste this example into a new file named
``letsencrypt-staging.yaml`` and update the ``spec.acme.email`` field to be your
own email address.
.. code-block:: yaml
:linenos:
:emphasize-lines: 7-10, 13-14, 19
apiVersion: cert-manager.io/v1alpha2
kind: ClusterIssuer
metadata:
name: letsencrypt-staging
spec:
acme:
# You must replace this email address with your own.
# Let's Encrypt will use this to contact you about expiring
# certificates, and issues related to your account.
email: user@example.com
server: https://acme-staging-v02.api.letsencrypt.org/directory
privateKeySecretRef:
# Secret resource used to store the account's private key.
name: example-issuer-account-key
# Add a single challenge solver, HTTP01 using nginx
solvers:
- http01:
ingress:
class: nginx
You can then create this resource using ``kubectl apply``:
.. code-block:: shell
kubectl apply -f letsencrypt-staging.yaml
To verify that the account has been registered successfully, you can run
``kubectl describe`` and check the 'Ready' condition:
.. code-block:: shell
kubectl describe clusterissuer letsencrypt-staging
...
Status:
Acme:
Uri: https://acme-staging-v02.api.letsencrypt.org/acme/acct/7571319
Conditions:
Last Transition Time: 2019-01-30T14:52:03Z
Message: The ACME account was registered with the ACME server
Reason: ACMEAccountRegistered
Status: True
Type: Ready
Any Certificate you create that references this Issuer resource will use the
HTTP01 challenge solver you have configured above.
.. note::
Let's Encrypt does not support issuing wildcard certificates with HTTP-01 challenges.
To issue wildcard certificates, you must use the DNS-01 challenge.
.. _multiple-solver-types:
Adding multiple solver types
============================
You may want to use different types of challenge solver configuration for
different ingress controllers, for example if you want to issue wildcard
certificates using DNS01 alongside other certificates that are validated using
HTTP01.
The ``solvers`` stanza has an optional ``selector`` field, that can be used to
specify which Certificates, and further, what DNS names **on those certificates**
should be used to solve challenges.
For example, to configure HTTP01 using nginx ingress as the default solver,
along with a DNS01 solver that can be used for wildcard certificates:
.. code-block:: yaml
:linenos:
:emphasize-lines: 14-15
apiVersion: cert-manager.io/v1alpha2
kind: ClusterIssuer
metadata:
name: letsencrypt-staging
spec:
acme:
...
solvers:
- http01:
ingress:
class: nginx
- selector:
matchLabels:
use-cloudflare-solver: "true"
dns01:
cloudflare:
email: user@example.com
apiKeySecretRef:
name: cloudflare-apikey-secret
key: apikey
In order to utilise the configured cloudflare DNS01 solver, you must add the
``use-cloudflare-solver: "true"`` label to your Certificate resources.
Using multiple solvers for a single certificate
-----------------------------------------------
The solver's ``selector`` stanza has an additional field ``dnsNames`` that
further refines the set of domains that the solver configuration applies to.
If any ``dnsNames`` are specified, then that challenge solver will be used if
the domain being validated is named in that list.
For example:
.. code-block:: yaml
:linenos:
:emphasize-lines: 14-15
apiVersion: cert-manager.io/v1alpha2
kind: ClusterIssuer
metadata:
name: letsencrypt-staging
spec:
acme:
...
solvers:
- http01:
ingress:
class: nginx
- selector:
dnsNames:
- '*.example.com'
dns01:
cloudflare:
email: user@example.com
apiKeySecretRef:
name: cloudflare-apikey-secret
key: apikey
In this instance, a Certificate that specified both ``*.example.com`` and
``example.com`` would use the HTTP01 challenge solver for ``example.com`` and
the DNS01 challenge solver for ``*.example.com``.
It is possible to specify both ``matchLabels`` AND ``dnsNames`` on an ACME
solver selector.
.. toctree::
:maxdepth: 2
:caption: Contents:
http01/index
dns01/index
.. _`Let's Encrypt staging endpoint`: https://letsencrypt.org/docs/staging-environment/
This document has moved to https://cert-manager.netlify.com/docs/configuration/acme/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/setup-ca.rst
+5 -155
View File
@@ -1,156 +1,6 @@
=====================
Setting up CA Issuers
=====================
==========
File moved
==========
cert-manager can be used to obtain certificates using an arbitrary signing
key pair stored in a Kubernetes Secret resource.
This guide will show you how to configure and create a CA based issuer, backed
by a signing key pair stored in a Secret resource.
1. (Optional) Generate a signing key pair
=========================================
The CA Issuer does not automatically create and manage a signing key pair for
you. As a result, you will need to either supply your own or generate a self
signed CA using a tool such as openssl_ or cfssl_.
This guide will explain how to generate a new signing key pair, however you can
substitute it for your own so long as it has the ``CA`` flag set.
.. code-block:: shell
# Generate a CA private key
$ openssl genrsa -out ca.key 2048
# Create a self signed Certificate, valid for 10yrs with the 'signing' option set
$ openssl req -x509 -new -nodes -key ca.key -subj "/CN=${COMMON_NAME}" -days 3650 -reqexts v3_req -extensions v3_ca -out ca.crt
The output of these commands will be two files, ``ca.key`` and ``ca.crt``, the
key and certificate for your signing key pair. If you already have your own key
pair, you should name the private key and certificate ``ca.key`` and ``ca.crt``
respectively.
2. Save the signing key pair as a Secret
========================================
We are going to create an Issuer that will use this key pair to generate signed
certificates. You can read more about the Issuer resource in :doc:`the Issuer
reference docs </reference/issuers>`. To allow the Issuer to reference our key
pair we will store it in a Kubernetes Secret resource.
Issuers are namespaced resources and so they can only reference Secrets in
their own namespace. We will therefore put the key pair into the same namespace
as the Issuer. We could alternatively create a :doc:`ClusterIssuer
</reference/clusterissuers>`, a cluster-scoped version of an Issuer. For more
information on ClusterIssuers, read the :doc:`ClusterIssuer reference
documentation </reference/clusterissuers>`.
The following command will create a Secret containing a signing key pair in the
default namespace:
.. code-block:: shell
kubectl create secret tls ca-key-pair \
--cert=ca.crt \
--key=ca.key \
--namespace=default
3. Creating an Issuer referencing the Secret
============================================
We can now create an Issuer referencing the Secret resource we just created:
.. code-block:: yaml
:linenos:
:emphasize-lines: 8
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: ca-issuer
namespace: default
spec:
ca:
secretName: ca-key-pair
We are now ready to obtain certificates!
4. Obtain a signed Certificate
==============================
We can now create the following Certificate resource which specifies the
desired certificate. You can read more about the Certificate resource in
:doc:`the reference docs </reference/certificates>`.
.. code-block:: yaml
:linenos:
:emphasize-lines: 9, 10, 11, 12
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
name: example-com
namespace: default
spec:
secretName: example-com-tls
issuerRef:
name: ca-issuer
# We can reference ClusterIssuers by changing the kind here.
# The default value is Issuer (i.e. a locally namespaced Issuer)
kind: Issuer
commonName: example.com
organization:
- Example CA
dnsNames:
- example.com
- www.example.com
In order to use the Issuer to obtain a Certificate, we must create a
Certificate resource in the **same namespace as the Issuer**, as an Issuer is a
namespaced resource. We could alternatively create a :doc:`ClusterIssuer
</reference/clusterissuers>` if we wanted to reuse the signing key pair across
multiple namespaces.
Once we have created the Certificate resource, cert-manager will attempt to use
the Issuer ``ca-issuer`` to obtain a certificate. If successful, the
certificate will be stored in a Secret resource named ``example-com-tls`` in
the same namespace as the Certificate resource (``default``).
The example above explicitly sets the ``commonName`` field to ``example.com``.
cert-manager automatically adds the ``commonName`` field as a `DNS SAN`_ if it
is not already contained in the ``dnsNames`` field.
If we had **not** specified the ``commonName`` field, then the **first** DNS
SAN that is specified (under ``dnsNames``) would be used as the certificate's
common name.
After creating the above Certificate, we can check whether it has been obtained
successfully like so:
.. code-block:: shell
$ kubectl describe certificate example-com
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning ErrorCheckCertificate 26s cert-manager-controller Error checking existing TLS certificate: secret "example-com-tls" not found
Normal PrepareCertificate 26s cert-manager-controller Preparing certificate with issuer
Normal IssueCertificate 26s cert-manager-controller Issuing certificate...
Normal CertificateIssued 25s cert-manager-controller Certificate issued successfully
You can also check whether issuance was successful with
``kubectl get secret example-com-tls -o yaml``. You should see a base64 encoded
signed TLS key pair.
Once the certificate has been obtained, cert-manager will keep checking its
validity and attempt to renew it if it gets close to expiry.
cert-manager considers certificates to be close to expiry when the 'Not After'
field on the certificate is less than the current time plus 30 days. For CA
based Issuers, cert-manager will issue certificates with the 'Not After'
field set to the current time plus 365 days.
.. _openssl: https://github.com/openssl/openssl
.. _cfssl: https://github.com/cloudflare/cfssl
.. _`DNS SAN`: https://en.wikipedia.org/wiki/Subject_Alternative_Name
This document has moved to https://cert-manager.netlify.com/docs/configuration/ca/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/setup-selfsigned.rst
+5 -43
View File
@@ -1,44 +1,6 @@
===============================
Setting up self signing Issuers
===============================
==========
File moved
==========
.. toctree::
:maxdepth: 1
Self signed Issuers will issue self signed certificates.
This is useful when building PKI within Kubernetes, or as a means to generate a
root CA for use with the :doc:`CA Issuer <./setup-ca>`.
A self-signed Issuer contains no additional configuration fields, and can be
created with a resource like so:
.. code-block:: yaml
apiVersion: cert-manager.io/v1alpha2
kind: ClusterIssuer
metadata:
name: selfsigning-issuer
spec:
selfSigned: {}
.. note::
The presence of the ``selfSigned: {}`` line is enough to indicate that this Issuer
is of type 'self signed'.
Once created, you should be able to issue certificates like usual by
referencing the newly created Issuer in your ``issuerRef``:
.. code-block:: yaml
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
name: example-crt
spec:
secretName: my-selfsigned-cert
commonName: "my-selfsigned-root-ca"
isCA: true
issuerRef:
name: selfsigning-issuer
kind: ClusterIssuer
This document has moved to https://cert-manager.netlify.com/docs/configuration/selfsigned/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/setup-vault.rst
+5 -262
View File
@@ -1,263 +1,6 @@
========================
Setting up Vault Issuers
========================
==========
File moved
==========
Installing Vault
----------------
Vault installation is a complex subject. For a thorough tour of the subject
you can read the official HashiCorp Vault
`documentation <https://learn.hashicorp.com/vault/getting-started/install>`__.
Vault PKI Backend
-----------------
The PKI Secrets Engine needs to be initialized for cert-manager to be
able to generate certificate. The official Vault documentation can be
found
`here <https://www.vaultproject.io/docs/secrets/pki/index.html>`__.
Vault Authentication with a AppRole
===================================
This Vault authentication method uses a
`Vault AppRole <https://www.vaultproject.io/docs/auth/approle.html>`__.
The secret ID of the AppRole is stored in a secret.
Here an example of a secret containing the secretId of the AppRole:
.. code-block:: yaml
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: cert-manager-vault-approle
namespace: default
data:
secretId: "MDI..."
Where the secretId is the base 64 encoded value of the appRole *secretId*
giving access to the pki backend in Vault.
We can now create a cluster issuer referencing this secret:
.. code-block:: yaml
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: vault-issuer
namespace: default
spec:
vault:
path: pki_int/sign/example-dot-com
server: https://vault
caBundle: <base64 encoded caBundle PEM file>
auth:
appRole:
path: approle
roleId: "291b9d21-8ff5-..."
secretRef:
name: cert-manager-vault-approle
key: secretId
Where *path* is the Vault role path of the PKI backend and *server* is
the Vault server base URL. The *path* MUST USE the vault ``sign`` endpoint.
The Vault appRole credentials are supplied as the
Vault authentication method using the appRole created in Vault. The secretRef
references the Kubernetes secret created previously. More specifically, the field
*name* is the Kubernetes secret name and *key* is the name given as the
key value that store the *secretId*. The optional attribute *path* specifies
where the AppRole authentication is mounted in Vault. The attribute *path* default
value is *approle*.
An optional base64 encoded *caBundle* in PEM format can be provided to validate
the TLS connection to the Vault Server. When *caBundle* is set it replaces the CA
bundle inside the container running cert-manager.
This parameter has no effect if the connection used is in plain HTTP.
Once we have created the above Issuer we can use it to obtain a certificate.
.. code-block:: yaml
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
name: example-com
namespace: default
spec:
secretName: example-com-tls
issuerRef:
name: vault-issuer
commonName: example.com
dnsNames:
- www.example.com
The Certificate resource describes our desired certificate and the possible
methods that can be used to obtain it. You can learn more about the Certificate
resource in the :doc:`reference docs </reference/certificates>`.
If the certificate is obtained successfully, the resulting key pair will be
stored in a secret called ``example-com-tls`` in the same namespace as the Certificate.
The certificate will have a common name of ``example.com`` and the
`Subject Alternative Names`_ (SANs) will be ``example.com`` and ``www.example.com``.
In our Certificate we have referenced the ``vault-issuer`` Issuer above.
The Issuer must be in the same namespace as the Certificate.
If you want to reference a ClusterIssuer, which is a cluster-scoped version of
an Issuer, you must add ``kind: ClusterIssuer`` to the ``issuerRef`` stanza.
For more information on ClusterIssuers, read the
:doc:`ClusterIssuer reference docs </reference/clusterissuers>`.
Vault Authentication with a Token
=================================
This Vault authentication method uses a plain token. A Vault token is generated by
one of the many authentication backends supported by Vault. Tokens in Vault have
expiration and need to be refreshed. You need to be aware that cert-manager does not
refresh these tokens. Another process must be put in place to keep them from expiring.
For testing purposes a root token is generated at Vault installation time.
**WARNING: Root tokens do not expire, so should only be used for testing purposes.**
Please refer to the official token `documentation <https://www.vaultproject.io/docs/concepts/tokens.html>`__
for all the details.
Here an example of a secret Kubernetes resource containing the Vault token:
.. code-block:: yaml
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: cert-manager-vault-token
namespace: kube-system
data:
token: "MjI..."
Where the token value is the base 64 encoded value of the token giving
access to the PKI backend in Vault.
We can now create an issuer referencing this secret:
.. code-block:: yaml
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: vault-issuer
namespace: default
spec:
vault:
auth:
tokenSecretRef:
name: cert-manager-vault-token
key: token
path: pki_int/sign/example-dot-com
server: https://vault
caBundle: <base64 encoded caBundle PEM file>
Where *path* is the Vault role path of the PKI backend and *server* is
the Vault server base URL. The secret created previously is referenced in the issuer
with its *name* and *key* corresponding to the name of the Kubernetes secret and the
property name containing the token value respectively.
An optional base64 encoded *caBundle* in PEM format can be provided to validate
the TLS connection to the Vault Server. When *caBundle* is set it replaces the CA
bundle inside the container running cert-manager. This parameter as no effect if the
connection used is in plain HTTP.
Once we have created the above Issuer we can use it to obtain a certificate.
.. code-block:: yaml
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
name: example-com
namespace: default
spec:
secretName: example-com-tls
issuerRef:
name: vault-issuer
commonName: example.com
dnsNames:
- www.example.com
The Certificate resource describes our desired certificate and the possible
methods that can be used to obtain it. You can learn more about the Certificate
resource in the :doc:`reference docs </reference/certificates>`.
If the certificate is obtained successfully, the resulting key pair will be
stored in a secret called ``example-com-tls`` in the same namespace as the Certificate.
The certificate will have a common name of ``example.com`` and the
`Subject Alternative Names`_ (SANs) will be ``example.com`` and ``www.example.com``.
In our Certificate we have referenced the ``vault-issuer`` Issuer above.
The Issuer must be in the same namespace as the Certificate.
If you want to reference a ClusterIssuer, which is a cluster-scoped version of
an Issuer, you must add ``kind: ClusterIssuer`` to the ``issuerRef`` stanza.
For more information on ClusterIssuers, read the
:doc:`ClusterIssuer reference docs </reference/clusterissuers>`.
.. _`Subject Alternative Names`: https://en.wikipedia.org/wiki/Subject_Alternative_Name
Vault Authentication with Kubernetes Service Accounts
=====================================================
This Vault authentication method uses Service Account tokens created by
Kubernetes to authenticate requests to Vault for signing certificates. You can
find more information on how to configure vault for Kubernetes based Service
Account authentication in the `documentation
<https://www.vaultproject.io/docs/auth/kubernetes.html>`__. This authentication
expects three stanzas; a secret reference of the Service Account to use,
an optional authentication mount path that is defaulted to `kubernetes`, and
finally a Vault role that the Service Account is to assume.
Here is an example Vault issuer using the Kubernetes Service Account
authentication method.
.. code-block:: yaml
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: vault-issuer
namespace: default
spec:
vault:
path: pki_int/sign/example-dot-com
server: https://vault
caBundle: <base64 encoded caBundle PEM file>
auth:
kubernetes:
path: /kubernetes/cluster-1
role: my-app-1
secretRef:
name: my-service-account-secret
key: token
Once created and is ready you can create Certificates referencing this issuer in
the normal way.
.. code-block:: yaml
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
name: example-com
namespace: default
spec:
secretName: example-com-tls
issuerRef:
name: vault-issuer
commonName: example.com
dnsNames:
- www.example.com
This document has moved to https://cert-manager.netlify.com/docs/configuration/vault/.
This placeholder file will be removed in a later release.
docs/tasks/issuers/setup-venafi.rst
+5 -179
View File
@@ -1,180 +1,6 @@
=========================
Setting up Venafi Issuers
=========================
==========
File moved
==========
The Venafi Issuer types allows you to obtain certificates from `Venafi Cloud`_
and `Venafi Trust Protection Platform`_ instances.
Register your account at https://ui.venafi.cloud/enroll and get an API key from
your dashboard.
You can have multiple different Venafi Issuer types installed within the same
cluster, including mixtures of Cloud and TPP issuer types. This allows you to
be flexible with the types of Venafi account you use.
Automated certificate renewal and management are provided for Certificates
using the Venafi issuer.
.. note::
The Venafi Issuer has been recently added, and the exact structure of the
Issuer resource is subject to change. Such changes will be clearly
documented, and migration steps will be provided.
Creating an Issuer resource
===========================
A single Venafi Issuer represents a single 'zone' within the Venafi API,
therefore you must create an Issuer resource for each Venafi Zone you want to
obtain certificates from.
You can configure your Issuer resource to either issue certificates only within
a single namespace, or cluster-wide (using a ClusterIssuer resource).
For more information on the distinction between Issuer and ClusterIssuer
resources, read the :ref:`issuer_vs_clusterissuer` section.
Creating a Venafi Cloud Issuer
------------------------------
In order to set up a Venafi Cloud Issuer, you must first create a Kubernetes
Secret resource containing your Venafi Cloud API credentials:
.. code-block:: shell
kubectl create secret generic \
cloud-secret \
--namespace='NAMESPACE OF YOUR ISSUER RESOURCE' \
--from-literal=apikey='YOUR_CLOUD_API_KEY_HERE'
.. note::
If you are configuring your Issuer as a ClusterIssuer resource in order to
issue Certificates across your whole cluster, you must set the
``--namespace`` parameter to ``cert-manager``, which is the default 'cluster
resource namespace'.
This API key will be used by cert-manager to interact with the Venafi Cloud
service on your behalf.
Once the API key Secret has been created, you can create your Issuer or
ClusterIssuer resource. If you are creating a ClusterIssuer resource, you must
change the ``kind`` field to ``ClusterIssuer`` and remove the
``metadata.namespace`` field.
Save the below content after making your amendments to a file named
``venafi-cloud-issuer.yaml``:
.. code-block:: yaml
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: cloud-venafi-issuer
namespace: <NAMESPACE YOU WANT TO ISSUE CERTIFICATES IN>
spec:
venafi:
zone: "DevOps" # Set this to the Venafi policy zone you want to use
cloud:
apiTokenSecretRef:
name: cloud-secret
key: apikey
You can then create the Issuer using ``kubectl create -f``:
.. code-block:: shell
kubectl create -f venafi-cloud-issuer.yaml
Verify the Issuer has been initialised correctly using ``kubectl describe``:
.. code-block:: shell
kubectl describe issuer cloud-venafi-issuer --namespace='NAMESPACE OF YOUR ISSUER RESOURCE'
(TODO) include sample output
You are now ready to issue certificates using the newly provisioned Venafi
Issuer.
Read the :doc:`Issuing Certificates <../issuing-certificates/index>` document
for more information on how to create Certificate resources.
Creating a Venafi Trust Protection Platform Issuer
--------------------------------------------------
The Venafi Trust Protection integration allows you to obtain certificates from
a properly configured Venafi TPP instance.
The setup is similar to the Venafi Cloud configuration above, however some of
the connection parameters are slightly different.
.. note::
You **must** allow "User Provided CSRs" as part of your TPP policy, as this
is the only type supported by cert-manager at this time.
In order to set up a Venafi Trust Protection Platform Issuer, you must first
create a Kubernetes Secret resource containing your Venafi TPP API credentials:
.. code-block:: shell
kubectl create secret generic \
tpp-secret \
--namespace=<NAMESPACE OF YOUR ISSUER RESOURCE> \
--from-literal=username='YOUR_TPP_USERNAME_HERE' \
--from-literal=password='YOUR_TPP_PASSWORD_HERE'
.. note::
If you are configuring your Issuer as a ClusterIssuer resource in order to
issue Certificates across your whole cluster, you must set the
``--namespace`` parameter to ``cert-manager``, which is the default 'cluster
resource namespace'.
These credentials will be used by cert-manager to interact with your Venafi TPP
instance. Username attribute must be adhere to the <identity provider>:<username> format.
For example: ``local:admin``.
Once the Secret containing credentials has been created, you can create your
Issuer or ClusterIssuer resource. If you are creating a ClusterIssuer resource,
you must change the ``kind`` field to ``ClusterIssuer`` and remove the
``metadata.namespace`` field.
Save the below content after making your amendments to a file named
``venafi-tpp-issuer.yaml``:
.. code-block:: yaml
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: tpp-venafi-issuer
namespace: <NAMESPACE YOU WANT TO ISSUE CERTIFICATES IN>
spec:
venafi:
zone: devops\cert-manager # Set this to the Venafi policy zone you want to use
tpp:
url: https://tpp.venafi.example/vedsdk # Change this to the URL of your TPP instance
caBundle: <base64 encoded string of caBundle PEM file, or empty to use system root CAs>
credentialsRef:
name: tpp-secret
You can then create the Issuer using ``kubectl create -f``:
.. code-block:: shell
kubectl create -f venafi-tpp-issuer.yaml
Verify the Issuer has been initialised correctly using ``kubectl describe``:
.. code-block:: shell
kubectl describe issuer tpp-venafi-issuer --namespace='NAMESPACE OF YOUR ISSUER RESOURCE'
(TODO) include sample output
You are now ready to issue certificates using the newly provisioned Venafi
Issuer.
Read the :doc:`Issuing Certificates <../issuing-certificates/index>` document
for more information on how to create Certificate resources.
.. _Venafi Cloud: https://pki.venafi.com/venafi-cloud/
.. _Venafi Trust Protection Platform: https://venafi.com/
This document has moved to https://cert-manager.netlify.com/docs/configuration/venafi/.
This placeholder file will be removed in a later release.
docs/tasks/issuing-certificates/index.rst
+5 -114
View File
@@ -1,115 +1,6 @@
====================
Issuing Certificates
====================
==========
File moved
==========
The Certificate resource type is used to request certificates from different
Issuers.
In order to issue any certificates, you'll need to configure an Issuer resource
first.
If you have not configured any issuers yet, you should read the
:doc:`Setting up Issuers <../issuers/index>` guide.
Creating Certificate resources
==============================
A Certificate resource specifies fields that are used to generated certificate
signing requests which are then fulfilled by the issuer type you have
referenced.
Certificates specify which issuer they want to obtain the certificate from by
specifying the ``certificate.spec.issuerRef`` field.
A basic Certificate resource, for the ``example.com`` and ``www.example.com``
DNS names, ``spiffe://cluster.local/ns/sandbox/sa/example`` URI Subject
Alternative Name, that is valid for 90d and renews 15d before expiry is below:
.. code-block:: yaml
:linenos:
:emphasize-lines: 9, 10, 11, 12
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
name: example-com
namespace: default
spec:
secretName: example-com-tls
duration: 2160h # 90d
renewBefore: 360h # 15d
commonName: example.com
dnsNames:
- example.com
- www.example.com
uriSANs:
- spiffe://cluster.local/ns/sandbox/sa/example
issuerRef:
name: ca-issuer
# We can reference ClusterIssuers by changing the kind here.
# The default value is Issuer (i.e. a locally namespaced Issuer)
kind: Issuer
The signed certificate will be stored in a Secret resource named
``example-com-tls`` once the issuer has successfully issued the requested
certificate.
The Certificate will be issued using the issuer named ``ca-issuer`` in the
``default`` namespace (the same namespace as the Certificate resource).
.. note::
If you want to create an Issuer that can be referenced by Certificate
resources in **all** namespaces, you should create a
:doc:`ClusterIssuer </reference/clusterissuers>` resource and set the
``certificate.spec.issuerRef.kind`` field to ``ClusterIssuer``.
.. note::
The ``renewBefore`` and ``duration`` fields must be specified using Golang's
``time.Time`` string format, which does not allow the ``d`` (days) suffix.
You must specify these values using ``s``, ``m`` and ``h`` suffixes instead.
Failing to do so without installing the
:doc:`webhook </getting-started/webhook>` component can prevent cert-manager
from functioning correctly (`#1269`_).
.. note::
Take care when setting the ``renewBefore`` field to be very close to the
``duration`` as this can lead to a renewal loop, where the Certificate is
always in the renewal period. Some Issuers set the ``notBefore`` field on
their issued X.509 certificate before the issue time to fix clock-skew
issues, leading to the working duration of a certificate to be less than
the full duration of the certificate. For example, Let's Encrypt sets it
to be one hour before issue time, so the actual *working duration* of the
certificate is 89 days, 23 hours (the *full duration* remains 90 days).
A full list of the fields supported on the Certificate resource can be found in
the `API reference documentation`_.
.. _`#1269`: https://github.com/jetstack/cert-manager/issues/1269
.. _`API reference documentation`: https://docs.cert-manager.io/en/release-0.11/reference/api-docs/index.html#certificatespec-v1alpha2
Temporary certificates whilst issuing
=====================================
With some Issuer types, certificates can take a few minutes to be issued.
A temporary untrusted certificate will be issued whilst this process takes
places if another certificate does not already exist in the target Secret
resource.
This helps to improve compatibility with certain ingress controllers (e.g.
ingress-gce_) which require a TLS certificate to be present at all times in
order to function.
After the real, valid certificate has been obtained, cert-manager will replace
the temporary self signed certificate with the valid one, **but will retain the
same private key**.
You can disable issuing temporary certificate by setting feature gate flag
``--feature-gates=IssueTemporaryCertificate=false``
.. toctree::
:maxdepth: 2
ingress-shim
.. _ingress-gce: https://github.com/kubernetes/ingress-gce
This document has moved to https://cert-manager.netlify.com/docs/usage/certificate/.
This placeholder file will be removed in a later release.
docs/tasks/issuing-certificates/ingress-shim.rst
+5 -95
View File
@@ -1,96 +1,6 @@
=========================================================
Automatically creating Certificates for Ingress resources
=========================================================
==========
File moved
==========
cert-manager can be configured to automatically provision TLS certificates for
Ingress resources via annotations on your Ingresses.
A small sub-component of cert-manager, ingress-shim, is responsible for this.
How it works
============
ingress-shim watches Ingress resources across your cluster. If it observes an
Ingress with *any* of the annotations described in the 'Usage' section, it will
ensure a Certificate resource with the same name as the Ingress, and configured
as described on the Ingress exists. For example:
.. code-block:: yaml
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
annotations:
# add an annotation indicating the issuer to use.
cert-manager.io/cluster-issuer: nameOfClusterIssuer
name: myIngress
namespace: myIngress
spec:
rules:
- host: myingress.com
http:
paths:
- backend:
serviceName: myservice
servicePort: 80
path: /
tls: # < placing a host in the TLS config will indicate a cert should be created
- hosts:
- myingress.com
secretName: myingress-cert # < cert-manager will store the created certificate in this secret.
Configuration
=============
Since cert-manager v0.2.2, ingress-shim is deployed automatically as part of a
Helm chart installation.
If you would also like to use the old kube-lego_ ``kubernetes.io/tls-acme: "true"``
annotation for fully automated TLS, you will need to configure a default Issuer
when deploying cert-manager. This can be done by adding the following ``--set``
when deploying using Helm:
.. code-block:: shell
--set ingressShim.defaultIssuerName=letsencrypt-prod \
--set ingressShim.defaultIssuerKind=ClusterIssuer
In the above example, cert-manager will create Certificate resources that reference the ClusterIssuer `letsencrypt-prod` for all Ingresses that have a ``kubernetes.io/tls-acme: "true"`` annotation.
For more information on deploying cert-manager, read the :doc:`deployment guide </getting-started/index>`.
Supported annotations
=====================
You can specify the following annotations on ingresses in order to trigger
Certificate resources to be automatically created:
* ``cert-manager.io/issuer`` - the name of an Issuer to acquire the
certificate required for this ingress from. The Issuer **must** be in the same
namespace as the Ingress resource.
* ``cert-manager.io/cluster-issuer`` - the name of a ClusterIssuer to acquire
the certificate required for this ingress from. It does not matter which
namespace your Ingress resides, as ClusterIssuers are non-namespaced resources.
* ``kubernetes.io/tls-acme: "true"`` - this annotation requires additional
configuration of the ingress-shim (see above). Namely, a default issuer must be
specified as arguments to the ingress-shim container.
* ``acme.cert-manager.io/http01-ingress-class`` - this annotation allows you
to configure ingress class that will be used to solve challenges for this
ingress. Customising this is useful when you are trying to secure internal
services, and need to solve challenges using different ingress class to that
of the ingress. If not specified and the 'acme-http01-edit-in-place'
annotation is not set, this defaults to the ingress class of the ingress
resource.
* ``acme.cert-manager.io/http01-edit-in-place: "true"`` - 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" the existing ingress
will be modified. Any other value, or the absence of the annotation assumes
"false".
.. _kube-lego: https://github.com/jetstack/kube-lego
This document has moved to https://cert-manager.netlify.com/docs/usage/ingress/.
This placeholder file will be removed in a later release.
docs/tasks/uninstall/index.rst
+5 -15
View File
@@ -1,16 +1,6 @@
=========================
Uninstalling cert-manager
=========================
==========
File moved
==========
cert-manager supports running on Kubernetes_ and OpenShift_. The uninstallation
process 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
This document has moved to https://cert-manager.netlify.com/docs/tutorials/uninstall/.
This placeholder file will be removed in a later release.
docs/tasks/uninstall/kubernetes.rst
+5 -78
View File
@@ -1,79 +1,6 @@
==========================
Uninstalling on Kubernetes
==========================
==========
File moved
==========
Below is the processes for uninstalling cert-manager on Kubernetes. There are
two processes to chose depending on which method you used to install
cert-manager - static manifests or ``helm``.
.. warning::
To uninstall cert-manger you should always use the same process for installing
but in reverse. Deviating from the following process whether cert-manager has
been installed from static manifests or helm can cause issues and
potentially broken states. Please ensure you follow the below steps when
uninstalling to prevent this happening.
Before continuing, ensure that all cert-manager resources that have been created
by users have been deleted. You can check for any existing resources with the
following command:
.. code-block:: shell
kubectl get Issuers,ClusterIssuers,Certificates,CertificateRequests,Orders,Challenges --all-namespaces
O nce all these resources have been deleted you are ready to uninstall
cert-manager using the procedure determined by how you installed.
Uninstalling with regular manifests
===================================
Uninstalling from an installation with regular manifests is a case of running
the installation process, *in reverse*, using the delete command of ``kubectl``.
Delete the installation manifests using a link to your currently running
version vX.Y.Z like so:
.. code-block:: shell
kubectl delete -f https://github.com/jetstack/cert-manager/releases/download/vX.Y.Z/cert-manager.yaml
Uninstalling with Helm
======================
Uninstalling cert-manager from a ``helm`` installation is a case of running the
installation process, *in reverse*, using the delete command on both ``kubectl``
and ``helm``.
Firstly, delete the cert-manager installation using ``helm``. Ensure the
``--purge`` flag is applied.
.. code-block:: shell
helm delete cert-manager --purge
Next, delete the cert-manager namespace:
.. code-block:: shell
kubectl delete namespace cert-manager
Finally, delete the cert-manger `CustomResourceDefinitions`_ using the link to
the version vX.Y you installed:
.. code-block:: shell
kubectl delete -f https://raw.githubusercontent.com/jetstack/cert-manager/release-X.Y/deploy/manifests/00-crds.yaml
Namespace Stuck in Terminating State
====================================
If the namespace has been marked for deletion without deleting the cert-manager
installation first, the namespace may become stuck in a terminating state. This
is typically due to the fact that the `APIService`_ resource still exists
however the webhook is no longer running so is no longer reachable. To resolve
this, ensure you have run the above commands correctly, and if you're still
experiencing issues then run ``kubectl delete apiservice v1beta1.webhook.cert-manager.io``.
.. _`CustomResourceDefinitions`: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/
.. _`APIService`: https://kubernetes.io/docs/tasks/access-kubernetes-api/setup-extension-api-server
This document has moved to https://cert-manager.netlify.com/docs/tutorials/uninstall/kubernetes/.
This placeholder file will be removed in a later release.
docs/tasks/uninstall/openshift.rst
+5 -59
View File
@@ -1,60 +1,6 @@
=========================
Uninstalling on OpenShift
=========================
==========
File moved
==========
Below is the processes for uninstalling cert-manager on OpenShift.
.. warning::
To uninstall cert-manger you should always use the same process for installing
but in reverse. Deviating from the following process can cause issues and
potentially broken states. Please ensure you follow the below steps when
uninstalling to prevent this happening.
Login to your OpenShift cluster
===============================
Before you can uninstall 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 as the system:admin user
oc login -u system:admin
Uninstalling with regular manifests
===================================
Before continuing, ensure that all cert-manager resources that have been created
by users have been deleted. You can check for any existing resources with the
following command:
.. code-block:: shell
oc get Issuers,ClusterIssuers,Certificates,CertificateRequests,Orders,Challenges --all-namespaces
Once all these resources have been deleted you are ready to uninstall
cert-manager.
Uninstalling from an installation with regular manifests is a case of running
the installation process, *in reverse*, using the delete command of ``oc``.
Delete the installation manifests using a link to your currently running
version vX.Y.Z like so:
.. code-block:: shell
oc delete -f https://github.com/jetstack/cert-manager/releases/download/vX.Y.Z/cert-manager-openshift.yaml
Namespace Stuck in Terminating State
====================================
If the namespace has been marked for deletion without deleting the cert-manager
installation first, the namespace may become stuck in a terminating state. This
is typically due to the fact that the `APIService`_ resource still exists
however the webhook is no longer running so is no longer reachable. To resolve
this, ensure you have run the above commands correctly, and if you're still
experiencing issues then run ``oc delete apiservice v1beta1.webhook.cert-manager.io``.
.. _`CustomResourceDefinitions`: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/
.. _`APIService`: https://kubernetes.io/docs/tasks/access-kubernetes-api/setup-extension-api-server
This document has moved to https://cert-manager.netlify.com/docs/tutorials/uninstall/openshift/.
This placeholder file will be removed in a later release.
docs/tasks/upgrading/index.rst
+5 -97
View File
@@ -1,98 +1,6 @@
======================
Upgrading cert-manager
======================
==========
File moved
==========
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.
.. note::
Before performing upgrades of cert-manager, it is advised to take a backup
of all your cert-manager resources just in case an issue occurs whilst
upgrading. You can read how to backup and restore cert-manager in the
:doc:`../backup-restore-crds` guide.
Upgrading with Helm
===================
If you installed cert-manager using Helm, you can easily upgrade using the Helm
CLI.
.. note::
Before upgrading, please read the relevant instructions at the links below
for your from and to version.
Once you have read the relevant upgrading notes and taken any appropriate
actions, you can begin the upgrade process like so - replacing
``<release_name>`` with the name of your Helm release for cert-manager (usually
this is ``cert-manager``) and replacing ``<version>`` with the
version number you want to install:
.. code:: shell
# Install the cert-manager CustomResourceDefinition resources before
# upgrading the Helm chart
kubectl apply \
--validate=false \
-f https://raw.githubusercontent.com/jetstack/cert-manager/<version>/deploy/manifests/00-crds.yaml
# Add the Jetstack Helm repository if you haven't already
helm repo add jetstack https://charts.jetstack.io
# Ensure the local Helm chart repository cache is up to date
helm repo update
helm upgrade --version <version> <release_name> jetstack/cert-manager
This will upgrade you to the latest version of cert-manager, as listed in the
`Jetstack Helm chart repository`_.
.. note::
You can find out your release name using ``helm list | grep cert-manager``.
Upgrading using static manifests
================================
If you installed cert-manager using the static deployment manifests published
on each release, you can upgrade them in a similar way to how you first
installed them.
.. note::
Before upgrading, please read the relevant instructions at the links below
for your from and to version.
Once you have read the relevant notes and taken any appropriate actions, you
can begin the upgrade process like so - replacing ``<version>`` with the
version number you want to install:
.. code:: shell
kubectl apply \
--validate=false \
-f https://github.com/jetstack/cert-manager/releases/download/<version>/cert-manager.yaml
.. note::
If you are running Kubernetes v1.15 or below, you will need to add the
``--validate=false`` flag to your ``kubectl apply`` command above else you
will receive a validation error relating to the
``x-kubernetes-preserve-unknown-fields`` field in our
``CustomResourceDefinition`` resources.
This is a benign error and occurs due to the way ``kubectl`` performs
resource validation.
.. toctree::
:maxdepth: 1
upgrading-0.2-0.3
upgrading-0.3-0.4
upgrading-0.4-0.5
upgrading-0.5-0.6
upgrading-0.6-0.7
upgrading-0.7-0.8
upgrading-0.8-0.9
upgrading-0.9-0.10
upgrading-0.10-0.11
.. _`official Helm charts repository`: https://hub.helm.sh/charts/jetstack
.. _`static deployment manifests`: https://github.com/jetstack/cert-manager/blob/release-0.11/deploy/manifests
.. _`kubernetes/kubernetes#69590`: https://github.com/kubernetes/kubernetes/issues/69590
This document has moved to https://cert-manager.netlify.com/docs/TODO.
This placeholder file will be removed in a later release.
docs/tasks/upgrading/upgrading-0.10-0.11.rst
+5 -114
View File
@@ -1,115 +1,6 @@
=============================
Upgrading from v0.10 to v0.11
=============================
==========
File moved
==========
The v0.11 release marks the removal of the v1alpha1 API that was used in
previous versions of cert-manager, as well as our API group changing to be
``cert-manager.io`` instead of ``certmanager.k8s.io``.
We have also removed support for the **old style config format** that was
deprecated in the v0.8 release. This means you **must** transition to using the
new ``solvers`` style configuration format for your ACME issuers **before**
upgrading to v0.11. For more information, see the
:doc:`upgrading to v0.8 </tasks/upgrading/upgrading-0.7-0.8>` guide.
This makes for a fairly significant breaking change for users, as **all**
cert-manager resources, or even Ingresses that reference cert-manager
resources, will need to be updated to reflect these changes.
This upgrade should be performed in a few steps:
1) Back up existing cert-manager resources, as per the
:doc:`backup and restore guide <../backup-restore-crds>`.
2) :doc:`Uninstall cert-manager <../uninstall/index>`.
3) Ensure the old cert-manager CRD resources have also been deleted: ``kubectl get crd | grep certmanager.k8s.io``
4) Update the apiVersion on all your backed up resources from
``certmanager.k8s.io/v1alpha1`` to ``cert-manager.io/v1alpha2``.
5) Re-install cert-manager from scratch according to the :doc:`getting started guide </getting-started/index>`.
You must be sure to properly **backup**, **uninstall**, **re-install** and
**restore** your installation in order to ensure the upgrade is successful.
Additional annotation changes
=============================
As well as changing the API group used by our CRDs, we have also changed the
annotation-based configuration key to **also** reflect the new API group.
This means that if you use any cert-manager annotations on any of your other
resources (such as Ingresses, {Validating,Mutating}WebhookConfiguration, etc)
you will need to update them to reflect the new API group.
A full table of annotations, including the old and new equivalents:
+----------------------------------------------+-------------------------------------------+
| Old Annotation | New Annotation |
+----------------------------------------------+-------------------------------------------+
| certmanager.k8s.io/acme-http01-edit-in-place | acme.cert-manager.io/http01-edit-in-place |
+----------------------------------------------+-------------------------------------------+
| certmanager.k8s.io/acme-http01-ingress-class | acme.cert-manager.io/http01-ingress-class |
+----------------------------------------------+-------------------------------------------+
| certmanager.k8s.io/issuer | cert-manager.io/issuer |
+----------------------------------------------+-------------------------------------------+
| certmanager.k8s.io/cluster-issuer | cert-manager.io/cluster-issuer |
+----------------------------------------------+-------------------------------------------+
| certmanager.k8s.io/acme-challenge-type | DEPRECIATED |
+----------------------------------------------+-------------------------------------------+
| certmanager.k8s.io/acme-dns01-provider | DEPRECIATED |
+----------------------------------------------+-------------------------------------------+
| certmanager.k8s.io/alt-names | cert-manager.io/alt-names |
+----------------------------------------------+-------------------------------------------+
| certmanager.k8s.io/ip-sans | cert-manager.io/ip-sans |
+----------------------------------------------+-------------------------------------------+
| certmanager.k8s.io/common-name | cert-manager.io/common-name |
+----------------------------------------------+-------------------------------------------+
| certmanager.k8s.io/issuer-name | cert-manager.io/issuer-name |
+----------------------------------------------+-------------------------------------------+
| certmanager.k8s.io/issuer-kind | cert-manager.io/issuer-kind |
+----------------------------------------------+-------------------------------------------+
You can use the following bash magic to print a list of Ingress resources that
still contain an old annotation:
.. code-block:: shell
kubectl get ingress \
--all-namespaces \
-o json | \
jq '.items[] | select(.metadata.annotations| to_entries | map(.key)[] | test("certmanager")) | "Ingress resource \(.metadata.namespace)/\(.metadata.name) contains old annotations: (\( .metadata.annotations | to_entries | map(.key)[] | select( . | test("certmanager") ) ))"'
Ingress resource "demo/testcrt contains old annotations: (certmanager.k8s.io/cluster-issuer)"
Ingress resource "example/ingress-resource contains old annotations: (certmanager.k8s.io/cluster-issuer)"
In order to help with this migration, the following CLI tool will automatically
migrate these annotations for you. Note that it *will not* make any changes to
your cluster for you.
.. code-block:: shell
# Firstly, download the binary for your given platform
$ wget -O api-migration https://github.com/jetstack/cert-manager/releases/download/v0.11.0/api-migration-linux
# or for Darwin
$ wget -O api-migration https://github.com/jetstack/cert-manager/releases/download/v0.11.0/api-migration-darwin
# Mark the binary as executable and run the binary against your cluster
$ chmod +x api-migration && ./api-migration --kubeconfig /path/to/my/kubeconfig.yaml
# Follow the CLI ouput and check for the difference that has been made in files
$ diff ingress.yaml ingress-migrated.yaml
# Finally, once the new ingress resources have been reviewed, apply the manifests
$ kubectl apply -f ingress-migrated.yaml --kubeconfig /path/to/my/kubeconfig.yaml
You should make sure to update _all_ Ingress resources to ensure that your
certificates continue to be kept up to date.
Issuer/ClusterIssuer solvers
============================
Support for the deprecated ``spec.http01`` or ``spec.dns01`` fields in ``Issuer`` and ``ClusterIssuer`` have been removed. Any ``Issuer`` or ``ClusterIssuer`` objects must be converted to use the equivalent ``spec.solvers[].http01`` or ``spec.solvers[].dns01`` syntax. You can read more about the Issuer resource in the :doc:`Issuer reference docs </reference/issuers>`.
Any issuers that haven't been converted will result the ``cert-manager`` pod being unable to find any solvers at the expected location. This will result in errors like the following: ``no configured challenge solvers can be used for this challenge``
This document has moved to https://cert-manager.netlify.com/docs/TODO.
This placeholder file will be removed in a later release.
docs/tasks/upgrading/upgrading-0.2-0.3.rst
+5 -137
View File
@@ -1,138 +1,6 @@
===========================
Upgrading from v0.2 to v0.3
===========================
==========
File moved
==========
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 <deployment-namespace> --replicas=0 deployment <cert-manager-deployment-name>
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/v1alpha2
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
This document has moved to https://cert-manager.netlify.com/docs/TODO.
This placeholder file will be removed in a later release.
docs/tasks/upgrading/upgrading-0.3-0.4.rst
+5 -4
View File
@@ -1,5 +1,6 @@
===========================
Upgrading from v0.3 to v0.4
===========================
==========
File moved
==========
There are no special notes or considerations when upgrading from v0.3 to v0.4.
This document has moved to https://cert-manager.netlify.com/docs/TODO.
This placeholder file will be removed in a later release.
docs/tasks/upgrading/upgrading-0.4-0.5.rst
+5 -20
View File
@@ -1,21 +1,6 @@
===========================
Upgrading from v0.4 to v0.5
===========================
==========
File moved
==========
Version 0.5 of cert-manager introduces a new 'webhook' component, which is used
by the Kubernetes apiserver to validate our CRD resource types.
This should help in future to reduce errors caused by misconfigured Certificate
and Issuer resources.
When upgrading from a previous release using Helm, it is **essential** that
you perform one extra step before upgrading.
Disabling resource validation on the cert-manager namespace
===========================================================
Before upgrading, you should add the ``certmanager.k8s.io/disable-validation: "true"``
label to the ``cert-manager`` namespace.
This will allow the system resources that cert-manager requires to bootstrap
TLS to be created in its own namespace.
This document has moved to https://cert-manager.netlify.com/docs/TODO.
This placeholder file will be removed in a later release.
docs/tasks/upgrading/upgrading-0.5-0.6.rst
+5 -101
View File
@@ -1,102 +1,6 @@
===========================
Upgrading from v0.5 to v0.6
===========================
==========
File moved
==========
.. warning::
If you are upgrading from a release older than v0.5, please read the
`Upgrading from older versions using Helm`_ note at the bottom of this
document!
The upgrade process from v0.5 to v0.6 should be fairly seamless for most users.
As part of the new release, we have changed how we ship the
CustomResourceDefinition resources that cert-manager needs in order to operate
(as well as introducing two **new** CRD types).
Depending on the way you have installed cert-manager in the past, your upgrade
process will slightly vary:
Upgrading with the Helm chart
=============================
If you have previously deployed cert-manager v0.5 using the Helm installation
method, you will now need to perform one extra step before upgrading.
Due to issues with the way Helm handles CRD resources in Helm charts, we have
now moved the installation of these resources into a separate YAML manifest
that must be installed with ``kubectl apply`` before upgrading the chart.
You can follow the :doc:`regular upgrade guide <./index>` as
usual in order to upgrade from v0.5 to v0.6.
Upgrading with static manifests
===============================
The static manifests have moved into the ``deploy/manifests`` directory for
this release.
We now also no longer ship different manifests for different configurations, in
favour of a single ``cert-manager.yaml`` file which should work for all
Kubernetes clusters from Kubernetes v1.9 onwards.
You can follow the :doc:`regular upgrade guide <./index>` as
usual in order to upgrade from v0.5 to v0.6.
Upgrading from older versions using Helm
========================================
If you are upgrading from a version **older than v0.5** and
**have installed with Helm**, you will need to perform a fresh installation of
cert-manager due to issues with the Helm upgrade process.
This will involve the **removal of all cert-manager custom resources**.
This **will not** delete the Secret resources being used by your apps.
Before upgrading you will need to:
1. Read and follow the :doc:`backup guide <../backup-restore-crds>` to create a
backup of your configuration.
2. Delete the existing cert-manager Helm release (replacing 'cert-manager' with
the name of your Helm release):
.. code-block:: shell
# Uninstall the Helm chart
$ helm delete --purge cert-manager
# Ensure the cert-manager CustomResourceDefinition resources do not exist:
$ kubectl delete crd \
certificates.certmanager.k8s.io \
issuers.certmanager.k8s.io \
clusterissuers.certmanager.k8s.io
3. Perform a fresh install (as per the
:doc:`installation guide </getting-started/index>`):
.. code-block:: shell
# Install the cert-manager CRDs
$ kubectl apply \
-f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.6/deploy/manifests/00-crds.yaml
# Update helm repository cache
$ helm repo update
# Install cert-manager
$ helm install \
--name cert-manager \
--namespace cert-manager \
--version v0.6.6 \
stable/cert-manager
4. Follow the steps in the :doc:`restore guide <../backup-restore-crds>` to
restore your configuration.
5. Verify that your Issuers and Certificate resources are 'Ready':
.. code-block:: shell
$ kubectl get clusterissuer,issuer,certificates --all-namespaces
NAMESPACE NAME READY SECRET AGE
cert-manager cert-manager-webhook-ca True cert-manager-webhook-ca 1m
cert-manager cert-manager-webhook-webhook-tls True cert-manager-webhook-webhook-tls 1m
example-com example-com-tls True example-com-tls 11s
This document has moved to https://cert-manager.netlify.com/docs/TODO.
This placeholder file will be removed in a later release.
docs/tasks/upgrading/upgrading-0.6-0.7.rst
+5 -4
View File
@@ -1,5 +1,6 @@
===========================
Upgrading from v0.6 to v0.7
===========================
==========
File moved
==========
There are no special notes or considerations when upgrading from v0.6 to v0.7.
This document has moved to https://cert-manager.netlify.com/docs/TODO.
This placeholder file will be removed in a later release.
docs/tasks/upgrading/upgrading-0.7-0.8.rst
+5 -282
View File
@@ -1,283 +1,6 @@
===========================
Upgrading from v0.7 to v0.8
===========================
==========
File moved
==========
Upgrading from v0.7 to v0.8 is possible using the regular :doc:`upgrade guide <./index>`.
All resources should continue to operate as before.
As part of v0.8, a new format **for configure ACME Certificate resources** has
been introduced. Notably, challenge solver configuration has moved **from**
the Certificate resource (under ``certificate.spec.acme``) and now resides on
your configure **Issuer** resource, under ``issuer.spec.acme.solvers``.
This allows Certificate resources to be portable between different Issuer types.
Both the old and the new format of configuration are supported in the v0.8
release, so it is possible to **incrementally upgrade your resources** if you
have a large, multi-team deployment of cert-manager that makes it complex to
upgrade all manifests at once in place.
After upgrading, it is **strongly recommended** that you update your ACME
Issuer and Certificate resources to the :doc:`new format </tasks/issuers/setup-acme/index>`.
We will be removing support for the old format ahead of the 1.0 release.
The documentation has been updated to reflect configuring using the new format,
and as such, exhaustive information can be found in the :doc:`/tasks/issuers/setup-acme/index`
document.
Performing an incremental switch to the new format
==================================================
The following guide assumes you have 2 'solver types' currently in use across
your cert-manager deployment - one for DNS01 and another for HTTP01 using an
ingress class of ``nginx``. The nginx based HTTP01 solver will be configured as
the default solver type for Certificate resources that reference our issuer.
You can adjust the instructions below to fit your own configuration, either
with more or less solvers as appropriate.
First, we will modify our ACME Issuer to add the new HTTP01 and DNS01 solvers.
This operation **will not** effect any existing Certificates that already
explicitly set a ``certificate.spec.acme`` field:
.. code-block:: yaml
:linenos:
:emphasize-lines: 12-17, 28-52
apiVersion: certmanager.k8s.io/v1alpha2
kind: ClusterIssuer
metadata:
name: letsencrypt-staging
spec:
acme:
email: user@example.com
server: https://acme-staging-v02.api.letsencrypt.org/directory
privateKeySecretRef:
name: example-issuer-account-key
# The HTTP01 and DNS01 fields are now **deprecated**.
# We leave them in place here so that any Certificates that still
# specify a ``certificate.spec.acme`` stanza will continue to operate
# correctly.
# cert-manager will decide which configuration to use based on whether
# the Certificate contains a ``certificate.spec.acme`` stanza.
http01: {}
dns01:
providers:
- name: cloudflare
cloudflare:
email: my-cloudflare-acc@example.com
apiKeySecretRef:
name: cloudflare-api-key-secret
key: api-key
# Configure the challenge solvers.
solvers:
# An empty selector will 'match' all Certificate resources that
# reference this Issuer.
- selector: {}
http01:
ingress:
class: nginx
- selector:
# Any Certificate resources, or Ingress resources that use
# ingress-shim and match the below label selector will use this
# configured solver type instead of the default nginx based HTTP01
# solver above.
# You can continue to add new solver types if needed.
# The most specific 'match' will be used.
matchLabels:
use-cloudflare-solver: "true"
dns01:
# Adjust the configuration below according to your environment.
# You can view more example configurations for different DNS01
# providers in the documentation: https://docs.cert-manager.io/en/latest/tasks/issuers/setup-acme/dns01/index.html
cloudflare:
email: my-cloudflare-acc@example.com
apiKeySecretRef:
name: cloudflare-api-key-secret
key: api-key
By retaining both the old and the new configuration format on the Issuer
resource, we can begin the process of incrementally upgrading our Certificate
resources.
Any Certificate resources that you have manually created (i.e. not managed by
ingress-shim) must then be updated to remove the ``certificate.spec.acme``
stanza.
Given the above configuration, certificates will use the HTTP01 solver with the
``nginx`` ingress class in order to solve ACME challenges.
If a particular certificate requires a wildcard, or you simply want to use
DNS01 for that certificate instead of HTTP01, you can add the ``use-cloudflare-solver: "true"``
label to your Certificate resources and the appropriate ACME challenge solver
will be used.
Upgrading ingress-shim managed certificates to the new format
=============================================================
When using ingress-shim, cert-manager itself will create and manage your
Certificate resource for you.
In order to support both the old and the new format simultaneously,
ingress-shim will continue to set the ``certificate.spec.acme`` field on
Certificate resources it manages.
In order to force ingress-shim to also use the new format, you must **remove**
the old format configuration from your Issuer resources (i.e. ``issuer.spec.acme.http01``
and ``issuer.spec.acme.dns01``).
When ingress-shim detects that these fields are not specified, it will
clear/not set the ``certificate.spec.acme`` field.
If you are managing a certificate using ingress-shim that requires an
alternative solver type (other than the default solver configured on the issuer
which in this instance is the HTTP01 nginx solver), you can add labels to the
Ingress resource which will be automatically copied across to the Certificate
resource:
.. code-block:: yaml
:linenos:
:emphasize-lines: 6
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: my-test-ingress
labels:
use-cloudflare-solver: "true"
Confirming all Certificate resources are upgraded
=================================================
In order to check if any of your Certificate resources still have the old
configuration format, you can run the following command:
.. code-block:: shell
kubectl get certificate --all-namespaces \
-o custom-columns="NAMESPACE:.metadata.namespace,NAME:.metadata.name,OWNER:.metadata.ownerReferences[0].kind,OLD FORMAT:.spec.acme"
NAMESPACE NAME OWNER OLD FORMAT
default test <none> <none>
default test2 Ingress map[config:[map[domains:[abc.com] http01:map[ingressClass:nginx]]]]
In the above example, we can see there are two Certificate resources.
The ``test`` resource has been updated to no longer include the
``certificate.spec.acme`` field.
The ``test2`` resource still specifies the old configuration format, however it
**also** has an OwnerReference linking it to an **Ingress** resource.
This is because the ``test2`` Certificate resource is managed by ingress-shim.
As mentioned in the previous section, ingress-shim managed certificates will
only switch to the new format once the **old format** configuration on the
**Issuer** resource has been removed. This means we need to continue to the
next section in order to remove the old format configuration altogether from
**Issuer** resource in order for ingress-shim to automatically migrate the
``test2`` Certificate resource.
Removing old configuration altogether
=====================================
Once we've verified that all non-ingress-shim managed Certificate resources
have been updated to not specify the ``certificate.spec.acme`` stanza using the
command above, we can proceed to remove the ``issuer.spec.acme.http01`` and
``issuer.spec.acme.dns01`` stanzas from our Issuer resources.
Once completed, the Issuer resource from the previous section should look like
the following:
.. code-block:: yaml
:linenos:
apiVersion: certmanager.k8s.io/v1alpha2
kind: ClusterIssuer
metadata:
name: letsencrypt-staging
spec:
acme:
email: user@example.com
server: https://acme-staging-v02.api.letsencrypt.org/directory
privateKeySecretRef:
name: example-issuer-account-key
# Configure the challenge solvers.
solvers:
# An empty selector will 'match' all Certificate resources that
# reference this Issuer.
- selector: {}
http01:
ingress:
class: nginx
- selector:
# Any Certificate resources, or Ingress resources that use
# ingress-shim and match the below label selector will use this
# configured solver type instead of the default nginx based HTTP01
# solver above.
# You can continue to add new solver types if needed.
# The most specific 'match' will be used.
matchLabels:
use-cloudflare-solver: "true"
dns01:
# Adjust the configuration below according to your environment.
# You can view more example configurations for different DNS01
# providers in the documentation: https://docs.cert-manager.io/en/latest/tasks/issuers/setup-acme/dns01/index.html
cloudflare:
email: my-cloudflare-acc@example.com
apiKeySecretRef:
name: cloudflare-api-key-secret
key: api-key
After applying the above Issuer resource, you should re-run the command from
the last section to verify that the remaining ingress-shim managed Certificate
resources have also been updated to the new format:
.. code-block:: shell
kubectl get certificate --all-namespaces \
-o custom-columns="NAMESPACE:.metadata.namespace,NAME:.metadata.name,OWNER:.metadata.ownerReferences[0].kind,OLD FORMAT:.spec.acme"
NAMESPACE NAME OWNER OLD FORMAT
default test <none> <none>
default test2 Ingress <none>
Manually triggering a Certificate to be issued to validate the full config
==========================================================================
To be certain that you've correctly configured your new Issuer/Certificate
resources, it is advised you attempt to issue a new Certificate after removing
the old configuration format.
To do so, you can either:
* update the ``secretName`` field of an existing Certificate resource
* add an additional ``dnsName`` to one of your existing Certificate resources
* create a new Certificate resource
You should ensure that your Certificates are still be issued correctly to avoid
any potential issues at renewal time.
Special notes for ingress-gce users
===================================
Users of the ``ingress-gce`` ingress controller may find that their experience
configuring cert-manager to solve challenges using HTTP01 validation is
slightly more painful using the new format, as it requires the ``ingressName``
field to be specified as a distinct ``solver`` on the Issuer resource (as
opposed to in the past where the ingressName could be specified as a field on
the ``Certificate`` resource).
This is a `known issue`_, and a workaround is scheduled to be completed for
v0.9.
In the meantime, ingress-gce users can either choose to manually create a
new solver entry per Ingress resource they want to use to solve challenges, or
otherwise continue to use the **old format** until a suitable alternative
appears in v0.9.
.. _known issue: https://github.com/jetstack/cert-manager/issues/1666
This document has moved to https://cert-manager.netlify.com/docs/TODO.
This placeholder file will be removed in a later release.
docs/tasks/upgrading/upgrading-0.8-0.9.rst
+5 -19
View File
@@ -1,20 +1,6 @@
===========================
Upgrading from v0.8 to v0.9
===========================
==========
File moved
==========
Due to a change in the API group that cert-manager deployments use
(`apps/v1beta1` to `apps/v1`), cert-manager deployments must first be deleted
before applying the new version. This will cause downtime until the new version
has been applied. No data loss will occur during this operation however it is
always advised to backup your data during an upgrade, which you can follow
:doc:`here <../backup-restore-crds>`. To perform this action run:
.. code-block:: shell
kubectl delete deployments --namespace cert-manager \
cert-manager \
cert-manager-cainjector \
cert-manager-webhook
After this operation, follow the standard upgrade process as defined in the
:doc:`upgrade guide <./index>`.
This document has moved to https://cert-manager.netlify.com/docs/TODO.
This placeholder file will be removed in a later release.
docs/tasks/upgrading/upgrading-0.9-0.10.rst
+5 -21
View File
@@ -1,22 +1,6 @@
============================
Upgrading from v0.9 to v0.10
============================
==========
File moved
==========
Due to changes in the way the webhook component's TLS is bootstrapped in v0.10,
you will need to delete your webhook's Certificate and Issuer resources.
If you are using a deployment tool that automatically handles this (i.e. Helm),
there should be no additional action to take.
If you are using the 'static manifests' to install, you should run the following
after upgrading:
.. code-block:: shell
kubectl delete -n cert-manager issuer cert-manager-webhook-ca cert-manager-webhook-selfsign
kubectl delete -n cert-manager certificate cert-manager-webhook-ca cert-manager-webhook-webhook-tls
kubectl delete apiservice v1beta1.admission.certmanager.k8s.io
The Secret resources used to contain TLS assets for the webhook are now
automatically handled internally by cert-manager, so these resources are no
longer required.
This document has moved to https://cert-manager.netlify.com/docs/TODO.
This placeholder file will be removed in a later release.
docs/tutorials/acme/dns-validation.rst
+5 -175
View File
@@ -1,176 +1,6 @@
================================================
Issuing an ACME certificate using DNS validation
================================================
==========
File moved
==========
.. todo::
This guide needs rewriting to be clearer, splitting into sections and
potentially rewriting altogether.
cert-manager can be used to obtain certificates from a CA using the ACME_ protocol.
The ACME protocol supports various challenge mechanisms which are used to prove
ownership of a domain so that a valid certificate can be issued for that domain.
One such challenge mechanism is DNS-01. With a DNS-01 challenge, you prove
ownership of a domain by proving you control its DNS records.
This is done by creating a TXT record with specific content that proves you
have control of the domains DNS records.
The following Issuer defines the necessary information to enable DNS validation.
You can read more about the Issuer resource in the :doc:`Issuer reference docs </reference/issuers>`.
.. code-block:: yaml
:linenos:
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: letsencrypt-staging
namespace: default
spec:
acme:
server: https://acme-staging-v02.api.letsencrypt.org/directory
email: user@example.com
# Name of a secret used to store the ACME account private key
privateKeySecretRef:
name: letsencrypt-staging
# ACME DNS-01 provider configurations
solvers:
# An empty 'selector' means that this solver matches all domains
- selector: {}
dns01:
clouddns:
# The ID of the GCP project
# reference: https://docs.cert-manager.io/en/latest/tasks/issuers/setup-acme/dns01/google.html
project: $PROJECT_ID
# This is the secret used to access the service account
serviceAccountSecretRef:
name: clouddns-dns01-solver-svc-acct
key: key.json
# We only use cloudflare to solve challenges for foo.com.
# Alternative options such as 'matchLabels' and 'dnsZones' can be specified
# as part of a solver's selector too.
- selector:
dnsNames:
- foo.com
dns01:
cloudflare:
email: my-cloudflare-acc@example.com
# !! Remember to create a k8s secret before
# kubectl create secret generic cloudflare-api-key
apiKeySecretRef:
name: cloudflare-api-key-secret
key: api-key
We have specified the ACME server URL for Let's Encrypt's `staging environment`_.
The staging environment will not issue trusted certificates but is used to
ensure that the verification process is working properly before moving to
production. Let's Encrypt's production environment imposes much stricter
`rate limits`_, so to reduce the chance of you hitting those limits it is
highly recommended to start by using the staging environment. To move to
production, simply create a new Issuer with the URL set to
``https://acme-v02.api.letsencrypt.org/directory``.
The first stage of the ACME protocol is for the client to register with the
ACME server. This phase includes generating an asymmetric key pair which is
then associated with the email address specified in the Issuer. Make sure to
change this email address to a valid one that you own. It is commonly used to
send expiry notices when your certificates are coming up for renewal. The
generated private key is stored in a Secret named ``letsencrypt-staging``.
The ``dns01`` stanza contains a list of DNS-01 providers that can be used to
solve DNS challenges. Our Issuer defines two providers. This gives us a choice
of which one to use when obtaining certificates.
More information about the DNS provider configuration, including a list of
supported providers, can be found :ref:`in the dns01 reference docs <supported-dns01-providers>`.
Once we have created the above Issuer we can use it to obtain a certificate.
.. code-block:: yaml
:linenos:
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
name: example-com
namespace: default
spec:
secretName: example-com-tls
issuerRef:
name: letsencrypt-staging
commonName: '*.example.com'
dnsNames:
- example.com
- foo.com
The Certificate resource describes our desired certificate and the possible
methods that can be used to obtain it.
You can obtain certificates for wildcard domains just like any other. Make sure to
wrap wildcard domains with asterisks in your YAML resources, to avoid formatting issues.
If you specify both ``example.com`` and ``*.example.com`` on the same Certificate,
it will take slightly longer to perform validation as each domain will have to be
validated one after the other.
You can learn more about the Certificate resource in the :doc:`reference docs </reference/certificates>`.
If the certificate is obtained successfully, the resulting key pair will be
stored in a secret called ``example-com-tls`` in the same namespace as the Certificate.
The certificate will have a common name of ``*.example.com`` and the
`Subject Alternative Names`_ (SANs) will be ``*.example.com``, ``example.com`` and ``foo.com``.
In our Certificate we have referenced the ``letsencrypt-staging`` Issuer above.
The Issuer must be in the same namespace as the Certificate.
If you want to reference a ClusterIssuer, which is a cluster-scoped version of
an Issuer, you must add ``kind: ClusterIssuer`` to the ``issuerRef`` stanza.
For more information on ClusterIssuers, read the
:doc:`ClusterIssuer reference docs </reference/clusterissuers>`.
The ``acme`` stanza defines the configuration for our ACME challenges.
Here we have defined the configuration for our DNS challenges which will be used
to verify domain ownership.
For each domain mentioned in a ``dns01`` stanza, cert-manager will use the
provider's credentials from the referenced Issuer to create a TXT record called
``_acme-challenge``.
This record will then be verified by the ACME server in order to issue the
certificate.
Once domain ownership has been verified, any cert-manager affected records will
be cleaned up.
.. note::
It is your responsibility to ensure the selected provider is authoritative for
your domain.
After creating the above Certificate, we can check whether it has been obtained
successfully using ``kubectl describe``:
.. code-block:: shell
$ kubectl describe certificate example-com
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal CreateOrder 57m cert-manager Created new ACME order, attempting validation...
Normal DomainVerified 55m cert-manager Domain "*.example.com" verified with "dns-01" validation
Normal DomainVerified 55m cert-manager Domain "example.com" verified with "dns-01" validation
Normal DomainVerified 55m cert-manager Domain "foo.com" verified with "dns-01" validation
Normal IssueCert 55m cert-manager Issuing certificate...
Normal CertObtained 55m cert-manager Obtained certificate from ACME server
Normal CertIssued 55m cert-manager Certificate issued successfully
You can also check whether issuance was successful with
``kubectl get secret example-com-tls -o yaml``.
You should see a base64 encoded signed TLS key pair.
Once our certificate has been obtained, cert-manager will periodically check its
validity and attempt to renew it if it gets close to expiry.
cert-manager considers certificates to be close to expiry when the 'Not After'
field on the certificate is less than the current time plus 30 days.
.. _ACME: https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment
.. _`staging environment`: https://letsencrypt.org/docs/staging-environment/
.. _`rate limits`: https://letsencrypt.org/docs/rate-limits/
.. _`Subject Alternative Names`: https://en.wikipedia.org/wiki/Subject_Alternative_Name
This document has moved to https://cert-manager.netlify.com/docs/tutorials/acme/dns-validation/.
This placeholder file will be removed in a later release.
docs/tutorials/acme/http-validation.rst
+5 -161
View File
@@ -1,162 +1,6 @@
=================================================
Issuing an ACME certificate using HTTP validation
=================================================
==========
File moved
==========
cert-manager can be used to obtain certificates from a CA using the ACME_ protocol.
The ACME protocol supports various challenge mechanisms which are used to prove
ownership of a domain so that a valid certificate can be issued for that domain.
One such challenge mechanism is the HTTP-01 challenge. With a HTTP-01 challenge,
you prove ownership of a domain by ensuring that a particular file is present at
the domain.
It is assumed that you control the domain if you are able to publish the given
file under a given path.
The following Issuer defines the necessary information to enable HTTP validation.
You can read more about the Issuer resource in the :doc:`Issuer reference docs </reference/issuers>`.
.. code-block:: yaml
:linenos:
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
name: letsencrypt-staging
namespace: default
spec:
acme:
# The ACME server URL
server: https://acme-staging-v02.api.letsencrypt.org/directory
# Email address used for ACME registration
email: user@example.com
# Name of a secret used to store the ACME account private key
privateKeySecretRef:
name: letsencrypt-staging
# Enable the HTTP-01 challenge provider
solvers:
# An empty 'selector' means that this solver matches all domains
- selector: {}
http01:
ingress:
class: nginx
We have specified the ACME server URL for Let's Encrypt's `staging environment`_.
The staging environment will not issue trusted certificates but is used to
ensure that the verification process is working properly before moving to
production. Let's Encrypt's production environment imposes much stricter
`rate limits`_, so to reduce the chance of you hitting those limits it is
highly recommended to start by using the staging environment. To move to
production, simply create a new Issuer with the URL set to
``https://acme-v02.api.letsencrypt.org/directory``.
The first stage of the ACME protocol is for the client to register with the
ACME server. This phase includes generating an asymmetric key pair which is
then associated with the email address specified in the Issuer. Make sure to
change this email address to a valid one that you own. It is commonly used to
send expiry notices when your certificates are coming up for renewal. The
generated private key is stored in a Secret named ``letsencrypt-staging``.
We must provide one or more Solvers for handling the ACME challenge. In this case
we want to use HTTP validation so we specify an ``http01`` Solver. We could
optionally map different domains to use different Solver configurations.
Once we have created the above Issuer we can use it to obtain a certificate.
.. code-block:: yaml
:linenos:
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
name: example-com
namespace: default
spec:
secretName: example-com-tls
issuerRef:
name: letsencrypt-staging
commonName: example.com
dnsNames:
- www.example.com
The Certificate resource describes our desired certificate and the possible
methods that can be used to obtain it. You can learn more about the Certificate
resource in the :doc:`reference docs </reference/certificates>`.
If the certificate is obtained successfully, the resulting key pair will be
stored in a secret called ``example-com-tls`` in the same namespace as the Certificate.
The certificate will have a common name of ``example.com`` and the
`Subject Alternative Names`_ (SANs) will be ``example.com`` and ``www.example.com``.
In our Certificate we have referenced the ``letsencrypt-staging`` Issuer above.
The Issuer must be in the same namespace as the Certificate.
If you want to reference a ClusterIssuer, which is a cluster-scoped version of
an Issuer, you must add ``kind: ClusterIssuer`` to the ``issuerRef`` stanza.
For more information on ClusterIssuers, read the
:doc:`ClusterIssuer reference docs </reference/clusterissuers>`.
The ``acme`` stanza defines the configuration for our ACME challenges.
Here we have defined the configuration for our HTTP-01 challenges which will be
used to verify domain ownership.
To verify ownership of each domain mentioned in an ``http01`` stanza, cert-manager
will create a Pod, Service and Ingress that exposes an HTTP endpoint that satisfies
the HTTP-01 challenge.
The fields ``ingress`` and ``ingressClass`` in the ``http01`` stanza can be used
to control how cert-manager interacts with Ingress resources:
* If the ``ingress`` field is specified, then an Ingress resource with the same
name in the same namespace as the Certificate must already exist and it will
be modified only to add the appropriate rules to solve the challenge.
This field is useful for the GCLB ingress controller, as well as a number of
others, that assign a single public IP address for each ingress resource.
Without manual intervention, creating a new ingress resource would cause any
challenges to fail.
* If the ``ingressClass`` field is specified, a new ingress resource with a
randomly generated name will be created in order to solve the challenge.
This new resource will have an annotation with key ``kubernetes.io/ingress.class``
and value set to the value of the ``ingressClass`` field.
This works for the likes of the NGINX ingress controller.
* If neither are specified, new ingress resources will be created with a randomly
generated name, but they will not have the ingress class annotation set.
* If both are specified, then the ``ingress`` field will take precedence.
Once domain ownership has been verified, any cert-manager affected resources will
be cleaned up or deleted.
.. note::
It is your responsibilty to point each domain name at the correct IP address
for your ingress controller.
After creating the above Certificate, we can check whether it has been obtained
successfully using ``kubectl describe``:
.. code-block:: shell
$ kubectl describe certificate example-com
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal CreateOrder 57m cert-manager Created new ACME order, attempting validation...
Normal DomainVerified 55m cert-manager Domain "example.com" verified with "http-01" validation
Normal DomainVerified 55m cert-manager Domain "www.example.com" verified with "http-01" validation
Normal IssueCert 55m cert-manager Issuing certificate...
Normal CertObtained 55m cert-manager Obtained certificate from ACME server
Normal CertIssued 55m cert-manager Certificate issued successfully
You can also check whether issuance was successful with
``kubectl get secret example-com-tls -o yaml``.
You should see a base64 encoded signed TLS key pair.
Once our certificate has been obtained, cert-manager will periodically check its
validity and attempt to renew it if it gets close to expiry.
cert-manager considers certificates to be close to expiry when the 'Not After'
field on the certificate is less than the current time plus 30 days.
.. _ACME: https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment
.. _`staging environment`: https://letsencrypt.org/docs/staging-environment/
.. _`rate limits`: https://letsencrypt.org/docs/rate-limits/
.. _`Subject Alternative Names`: https://en.wikipedia.org/wiki/Subject_Alternative_Name
This document has moved to https://cert-manager.netlify.com/docs/tutorials/acme/http-validation/.
This placeholder file will be removed in a later release.
docs/tutorials/acme/index.rst
+5 -13
View File
@@ -1,14 +1,6 @@
=====================
ACME Issuer Tutorials
=====================
==========
File moved
==========
This sections contains tutorials relating to the ACME issuer.
.. toctree::
:maxdepth: 1
quick-start/index
dns-validation
http-validation
migrating-from-kube-lego
This document has moved to https://cert-manager.netlify.com/docs/tutorials/acme/ingress/.
This placeholder file will be removed in a later release.

Some files were not shown because too many files have changed in this diff Show More