diff --git a/docs/index.rst b/docs/index.rst index 6c2893664..530fd112e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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. diff --git a/docs/reference/certificates.rst b/docs/reference/certificates.rst index 1c9fd3b67..fc0e6be92 100644 --- a/docs/reference/certificates.rst +++ b/docs/reference/certificates.rst @@ -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 diff --git a/docs/reference/issuers.rst b/docs/reference/issuers.rst index 81a87685a..fbe68c718 100644 --- a/docs/reference/issuers.rst +++ b/docs/reference/issuers.rst @@ -130,6 +130,8 @@ currently supported Issuer types are: +------------------------------------------------------+----------------------------------------------------------------------+ | :doc:`Self signed ` | Supports issuing self signed certificates | +------------------------------------------------------+----------------------------------------------------------------------+ +| :doc:`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`` diff --git a/docs/tasks/issuers/index.rst b/docs/tasks/issuers/index.rst index 31a10a4f1..ca78bb82b 100644 --- a/docs/tasks/issuers/index.rst +++ b/docs/tasks/issuers/index.rst @@ -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 `. +.. _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 diff --git a/docs/tasks/issuers/setup-venafi.rst b/docs/tasks/issuers/setup-venafi.rst new file mode 100644 index 000000000..0b6fa8915 --- /dev/null +++ b/docs/tasks/issuers/setup-venafi.rst @@ -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: + 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= \ + --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: + 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: + 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/ diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index 0e4daaeeb..1b5a0cac6 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -12,4 +12,3 @@ For more information on performing individual tasks, read the :maxdepth: 2 acme/index - venafi/index diff --git a/docs/tutorials/venafi/creating-venafi-issuers.rst b/docs/tutorials/venafi/creating-venafi-issuers.rst deleted file mode 100644 index 3c67d4350..000000000 --- a/docs/tutorials/venafi/creating-venafi-issuers.rst +++ /dev/null @@ -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: - 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 \ No newline at end of file diff --git a/docs/tutorials/venafi/index.rst b/docs/tutorials/venafi/index.rst deleted file mode 100644 index 9c6d655ac..000000000 --- a/docs/tutorials/venafi/index.rst +++ /dev/null @@ -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