From b60a5b93db07a50c0df21dc23878d4fcf00cfa78 Mon Sep 17 00:00:00 2001 From: Jan Malkiewicz Date: Fri, 18 Dec 2020 08:36:41 +0100 Subject: [CMPV2] Enhance documentation for CMPv2 cert provider Issue-ID: OOM-2560 Signed-off-by: Jan Malkiewicz Change-Id: I0a8a1979ca815a76b2e3318cc357da848fe52a9e --- docs/index.rst | 2 +- docs/sections/cmpv2-cert-provider.rst | 148 ++++++++++++++++++++++++++++++++++ docs/sections/external-provider.rst | 146 --------------------------------- 3 files changed, 149 insertions(+), 147 deletions(-) create mode 100644 docs/sections/cmpv2-cert-provider.rst delete mode 100644 docs/sections/external-provider.rst (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 67d83c6e..d14bbfbe 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,7 +12,7 @@ OOM Certification Service sections/introduction.rst sections/architecture.rst - sections/external-provider.rst + sections/cmpv2-cert-provider.rst sections/build.rst sections/offeredapis.rst sections/usage.rst diff --git a/docs/sections/cmpv2-cert-provider.rst b/docs/sections/cmpv2-cert-provider.rst new file mode 100644 index 00000000..1aca0733 --- /dev/null +++ b/docs/sections/cmpv2-cert-provider.rst @@ -0,0 +1,148 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2020 NOKIA + +CMPv2 certificate provider +============================== + +General information +------------------------------ + +CMPv2 certificate provider is a part of certificate distribution infrastructure in ONAP. +The main functionality of the provider is to forward Certificate Signing Requests (CSRs) created by cert-mananger (https://cert-manager.io) to CertServiceAPI. + +Additional information can be found on a dedicated page: https://wiki.onap.org/display/DW/CertService+and+K8s+Cert-Manager+integration. + + +CMPv2 Issuer +------------------------------ + +In order to be able to request a certificate via CMPv2 provider a *CMPv2Issuer* CRD (Customer Resource Definition) instance has to be created. + +It is important to note that the attribute *kind* has to be set to **CMPv2Issuer**, all other attributes can be set as needed. + +**NOTE: a default instance of CMPv2Issuer is created when installing ONAP via OOM deployment.** + +Here is a definition of a *CMPv2Issuer* provided with ONAP installation: + +.. code-block:: yaml + + apiVersion: certmanager.onap.org/v1 + kind: CMPv2Issuer + metadata: + name: cmpv2-issuer-onap + namespace: onap + spec: + url: https://oom-cert-service:8443 + healthEndpoint: actuator/health + certEndpoint: v1/certificate + caName: RA + certSecretRef: + name: cmpv2-issuer-secret + certRef: cmpv2Issuer-cert.pem + keyRef: cmpv2Issuer-key.pem + cacertRef: cacert.pem + + +Certificate enrolling +------------------------------ + +In order to request a certificate a K8s *Certificate* CRD (Custom Resource Definition) has to be created. + +It is important that in the section issuerRef following attributes have those values: + +- group: certmanager.onap.org + +- kind: CMPv2Issuer + +After *Certificate* CRD has been placed cert manager will send a *CSR* (Certificate Sign Request) to CA (Certificate Authority) via CMPv2 provider. +Signed certificate as well as trust anchor (CA root certificate) will be stored in the K8s *secret* specified in *Certificate* CRD (see secretName attribute). + +By default certificates will be stored in PEM format. It is possible to get certificates also in JKS and P12 format - see example below - more information can be found on official cert manager page. + +The following SANs types are supported: DNS names, IPs, URIs, emails. + +Here is an example of a *Certificate*: + +.. code-block:: yaml + + apiVersion: cert-manager.io/v1 + kind: Certificate + metadata: + name: certificate_name + namespace: onap + spec: + # The secret name to store the signed certificate + secretName: secret_name + # Common Name + commonName: certissuer.onap.org + subject: + organizations: + - Linux-Foundation + countries: + - US + localities: + - San-Francisco + provinces: + - California + organizationalUnits: + - ONAP + # SANs + dnsNames: + - localhost + - certissuer.onap.org + ipAddresses: + - "127.0.0.1" + uris: + - onap://cluster.local/ + emailAddresses: + - onap@onap.org + # The reference to the CMPv2 issuer + issuerRef: + group: certmanager.onap.org + kind: CMPv2Issuer + name: cmpv2-issuer-onap + # Section keystores is optional and defines in which format certificates will be stored + # If this section is omitted than only PEM format will be present in the secret + keystores: + jks: + create: true + passwordSecretRef: # Password used to encrypt the keystore + name: certservice-key + key: key + pkcs12: + create: true + passwordSecretRef: # Password used to encrypt the keystore + name: certservice-key + key: key + + +Here is an example of generated *secret* containing certificates: + +.. code-block:: yaml + + Name: secret_name + Namespace: onap + Labels: + Annotations: cert-manager.io/alt-names: localhost,certissuer.onap.org + cert-manager.io/certificate-name: certificate_name + cert-manager.io/common-name: certissuer.onap.org + cert-manager.io/ip-sans: + cert-manager.io/issuer-group: certmanager.onap.org + cert-manager.io/issuer-kind: CMPv2Issuer + cert-manager.io/issuer-name: cmpv2-issuer-onap + cert-manager.io/uri-sans: + + Type: kubernetes.io/tls + + Data + ==== + tls.crt: 1675 bytes <-- Certificate (PEM) + tls.key: 1679 bytes <-- Private Key (PEM) + truststore.jks: 1265 bytes <-- Trusted anchors (JKS) + ca.crt: 1692 bytes <-- Trusted anchors (PEM) + keystore.jks: 3786 bytes <-- Certificate and Private Key (JKS) + keystore.p12: 4047 bytes <-- Certificate and Private Key (P12) + + + diff --git a/docs/sections/external-provider.rst b/docs/sections/external-provider.rst deleted file mode 100644 index fe89762a..00000000 --- a/docs/sections/external-provider.rst +++ /dev/null @@ -1,146 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2020 NOKIA - -K8s external provider -============================== - -General information ------------------------------- - -Cert Service K8s external provider is a part of certificate distribution infrastructure in ONAP. -The main functionality of the provider is to forward Certificate Signing Requests (CSRs) created by cert-mananger (https://cert-manager.io) to CertServiceAPI. - -Additional information can be found on a dedicated page: https://wiki.onap.org/display/DW/CertService+and+K8s+Cert-Manager+integration. - - -CMPv2 Issuer ------------------------------- - -In order to be able to request a certificate via K8s external provider a *CMPv2Issuer* CRD (Customer Resource Definition) instance has to be created. - -It is important to note that the attribute *kind* has to be set to **CMPv2Issuer**, all other attributes can be set as needed. - -NOTE: a default instance of CMPv2Issuer is created when installing ONAP via OOM deployment (values can also be adjusted as needed) - -Here is an example of a *CMPv2Issuer*: - -.. code-block:: yaml - - apiVersion: certmanager.onap.org/v1 - kind: CMPv2Issuer - metadata: - name: cmpv2-issuer - namespace: onap - spec: - url: https://oom-cert-service:8443 - healthEndpoint: actuator/health - certEndpoint: v1/certificate - caName: RA - certSecretRef: - name: cmpv2-issuer-secret - certRef: cmpv2Issuer-cert.pem - keyRef: cmpv2Issuer-key.pem - cacertRef: cacert.pem - - -Certificate enrolling ------------------------------- - -In order to request a certificate a K8s *Certificate* CRD (Custom Resource Definition) has to be created. - -It is important that in the section issuerRef following attributes have correct values: - - group: **certmanager.onap.org** - - kind: **CMPv2Issuer** - -After *Certificate* CRD has been placed cert manager will send a *CSR* (Certificate Sign Request) to CA (Certificate Authority) via K8s external provider. -Signed certificate as well as trust anchor (CA root certificate) will be stored in the K8s *secret* specified in *Certificate* CRD (see secretName attribute). - -By default certificates will be stored in PEM format. It is possible to get certificates also in JKS and P12 format - see example below - more information can be found on official cert manager page. - -The following SANs types are supported: DNS names, IPs, URIs, emails. - -Here is an example of a *Certificate*: - -.. code-block:: yaml - - apiVersion: cert-manager.io/v1 - kind: Certificate - metadata: - name: certificate_name - namespace: onap - spec: - # The secret name to store the signed certificate - secretName: secret_name - # Common Name - commonName: certissuer.onap.org - subject: - organizations: - - Linux-Foundation - countries: - - US - localities: - - San-Francisco - provinces: - - California - organizationalUnits: - - ONAP - # SANs - dnsNames: - - localhost - - certissuer.onap.org - ipAddresses: - - "127.0.0.1" - uris: - - onap://cluster.local/ - emailAddresses: - - onap@onap.org - # The reference to the CMPv2 issuer - issuerRef: - group: certmanager.onap.org - kind: CMPv2Issuer - name: cmpv2-issuer - # Section keystores is optional and defines in which format certificates will be stored - # If this section is omitted than only PEM format will be present in the secret - keystores: - jks: - create: true - passwordSecretRef: # Password used to encrypt the keystore - name: certservice-key - key: key - pkcs12: - create: true - passwordSecretRef: # Password used to encrypt the keystore - name: certservice-key - key: key - - -Here is an example of generated *secret* containing certificates: - -.. code-block:: yaml - - Name: secret_name - Namespace: onap - Labels: - Annotations: cert-manager.io/alt-names: localhost,certissuer.onap.org - cert-manager.io/certificate-name: certificate_name - cert-manager.io/common-name: certissuer.onap.org - cert-manager.io/ip-sans: - cert-manager.io/issuer-group: certmanager.onap.org - cert-manager.io/issuer-kind: CMPv2Issuer - cert-manager.io/issuer-name: cmpv2-issuer-onap - cert-manager.io/uri-sans: - - Type: kubernetes.io/tls - - Data - ==== - tls.crt: 1675 bytes <-- Certificate (PEM) - tls.key: 1679 bytes <-- Private Key (PEM) - truststore.jks: 1265 bytes <-- Trusted anchors (JKS) - ca.crt: 1692 bytes <-- Trusted anchors (PEM) - keystore.jks: 3786 bytes <-- Certificate and Private Key (JKS) - keystore.p12: 4047 bytes <-- Certificate and Private Key (P12) - - - -- cgit 1.2.3-korg