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

Merge pull request #1454 from munnerz/update-venafi

Browse Source 
Move Venafi tutorial to a Setting up Venafi Issuers doc
This commit is contained in:
jetstack-bot 2019-03-08 09:39:12 +00:00 committed by GitHub
commit aeef7dc461
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 189 additions and 181 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/index.rst
View File

@ -9,7 +9,7 @@ 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`_, a simple signing keypair, or self signed.
`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.

1
docs/reference/certificates.rst
View File

@ -76,6 +76,7 @@ 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

2
docs/reference/issuers.rst
View File

@ -130,6 +130,8 @@ currently supported Issuer types are:
+------------------------------------------------------+----------------------------------------------------------------------+
| :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``

6
docs/tasks/issuers/index.rst
View File

@ -41,6 +41,8 @@ types you require:
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
======================
@ -48,6 +50,8 @@ 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
---------------------------------------------
@ -72,6 +76,8 @@ Certificate resources.
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

179
docs/tasks/issuers/setup-venafi.rst Normal file
View File

@ -0,0 +1,179 @@
=========================
Setting up Venafi Issuers
=========================
The Venafi Issuer types allows you to obtain certificates from `Venafi Cloud`_
and `Venafi Trust Protection Platform`_ instances.
Register your account at https://api.venafi.cloud/login 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 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: certmanager.k8s.io/v1alpha1
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>` 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=user='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.
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: certmanager.k8s.io/v1alpha1
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>
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/

1
docs/tutorials/index.rst
View File

@ -12,4 +12,3 @@ For more information on performing individual tasks, read the
:maxdepth: 2
acme/index
venafi/index

167
docs/tutorials/venafi/creating-venafi-issuers.rst
View File

@ -1,167 +0,0 @@
Setting up a Venafi Cloud or TPP Issuer
=======================================
The Venafi issuer is an extension which supports certificate management from
Venafi Cloud and Venafi Trust Protection Platform.
Deploying cert-manager
----------------------
.. note::
Please also see the 'Getting Started' guide on the left for more info on how
to deploy cert-manager.
.. note::
This guide assumes you already have a functioning Kubernetes cluster
of version 1.9 or greater.
You can run the following to deploy cert-manager with the Venafi integration
for the first time:
.. code-block:: shell
kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/venafi/contrib/manifests/cert-manager/with-rbac.yaml
.. note::
This step only needs to be performed once!
.. note::
Please verify that no errors were output when you run this command.
Creating Venafi Cloud issuer
----------------------------
Register your account at https://api.venafi.cloud/login and get API key there.
Create a secret containing your authentication credentials for the issuer to
use (in this example, the Issuer will utilise Venafi Cloud and will only issue
certificates in the ``default`` namespace).
.. code-block:: shell
kubectl create secret generic cloudsecret --from-literal=apikey='YOUR_CLOUD_API_KEY_HERE'
Create the issuer, referencing the secret we just created:
.. code-block:: yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: Issuer
metadata:
name: cloud-venafi-issuer
spec:
venafi:
zone: "DevOps"
cloud:
apiTokenSecretRef:
name: cloudsecret
key: apikey
You can create multiple issuers pointing to different Venafi Cloud zones, or
even have 1 issuer pointing to Venafi Platform and another pointing to Venafi
Cloud.
We can then create a certificate resource that utilises this newly configured
issuer:
.. code-block:: yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: Certificate
metadata:
name: cert4-venafi-localhost
spec:
commonName: cert4.venafi.localhost
secretName: cert4-venafi-localhost
issuerRef:
name: cloud-venafi-issuer
To see the full list of options available on the Certificate resource, take a
look at the ``API reference documentation``.
Creating Venafi Platform issuer
-------------------------------
Similar to how we created credentials and an Issuer resource for TPP Cloud
above, we can also create Issuers for Venafi TPP instances.
Again, you can have multiple Issuer's for different Venafi zones, and even run
Venafi Cloud Issuers alongside Venafi TPP Issuers.
**Requirements for Venafi Platform policy**
1. You **must** allow "User Provided CSRs" as part of your TPP policy, as this
is the only type supported by the underlying ``vcert`` library we use.
2. MSCA configuration should have http URI set before the ldap URI in
X509 extensions, otherwise NGINX ingress controller couldn't get
certificate chain from URL and OSCP will not work. Example:
TODO: verify this/make it clearer
::
X509v3 extensions:
X509v3 Subject Alternative Name:
DNS:test-cert-manager1.venqa.venafi.com}}
X509v3 Subject Key Identifier: }}
61:5B:4D:40:F2:CF:87:D5:75:5E:58:55:EF:E8:9E:02:9D:E1:81:8E}}
X509v3 Authority Key Identifier: }}
keyid:3C:AC:9C:A6:0D:A1:30:D4:56:A7:3D:78:BC:23:1B:EC:B4:7B:4D:75}}X509v3 CRL Distribution Points:Full Name:
URI:http://qavenafica.venqa.venafi.com/CertEnroll/QA%20Venafi%20CA.crl}}
URI:ldap:///CN=QA%20Venafi%20CA,CN=qavenafica,CN=CDP,CN=Public%20Key%20Services,CN=Services,CN=Configuration,DC=venqa,DC=venafi,DC=com?certificateRevocationList?base?objectClass=cRLDistributionPoint}}{{Authority Information Access: }}
CA Issuers - URI:http://qavenafica.venqa.venafi.com/CertEnroll/qavenafica.venqa.venafi.com_QA%20Venafi%20CA.crt}}
CA Issuers - URI:ldap:///CN=QA%20Venafi%20CA,CN=AIA,CN=Public%20Key%20Services,CN=Services,CN=Configuration,DC=venqa,DC=venafi,DC=com?cACertificate?base?objectClass=certificationAuthority}}
3. Option in Venafi Platform CA configuration template "Automatically include
CN as DNS SAN" should be set to true. (TODO this shouldn't be a requirement)
**Create a secret with Venafi Platform credentials:**
Like before, we create a Secret resource containing our Venafi TPP credentials:
.. code-block:: shell
kubectl create secret generic tppsecret \
--from-literal=user=admin \
--from-literal=password=tpppassword
**Optionally. Encode Venafi Platform CA bundle**
To include CA bundle into venafi options you need to encode it into base64 encoded string. Example:
.. code-block:: shell
cat /opt/venafi/bundle.pem | base64 | tr -d '\n'
**Create Venafi Platform issuer**
.. code-block:: yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: Issuer
metadata:
name: tpp-venafi-issuer
spec:
venafi:
zone: devops\cert-manager # must exist in the TPP console
tpp:
url: https://tpp.venafi.example/vedsdk
caBundle: <base64 encoded string of caBundle PEM file>
credentialsRef:
name: tppsecret
**Create a certificate**
Just the same as before, we can create a Certificate resource that utilises the
TPP Issuer we just created:
.. code-block:: yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: Certificate
metadata:
name: hellodemo-venafi-localhost
spec:
commonName: hellodemo.venafi.localhost
secretName: hellodemo-venafi-localhost
issuerRef:
name: tpp-venafi-issuer

12
docs/tutorials/venafi/index.rst
View File

@ -1,12 +0,0 @@
=======================
Venafi Issuer Tutorials
=======================
This section contains tutorials that utilise the Venafi Issuer.
They are designed to help teach the underlying concepts of cert-manager whils
also helping 'quickstart' common use-cases for the project.
.. toctree::
:maxdepth: 1
creating-venafi-issuers