From d432cc77ffa23c3d4ca1e34d533dac3cca67c931 Mon Sep 17 00:00:00 2001 From: Jan Malkiewicz Date: Wed, 25 Nov 2020 09:21:11 +0100 Subject: [OOM-K8S-CERT-EXTERNAL-PROVIDER] Add documentation for k8s external provider Issue-ID: OOM-2560 Signed-off-by: Jan Malkiewicz Change-Id: I76659e1369c2a6ec43f9d31326ff0c43d6a1ccdc --- docs/index.rst | 1 + docs/sections/external-provider.rst | 138 ++++++++++++++++++++++++++++++++++++ 2 files changed, 139 insertions(+) create mode 100644 docs/sections/external-provider.rst diff --git a/docs/index.rst b/docs/index.rst index 97bfcac3..6d8e329c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,6 +12,7 @@ OOM Certification Service sections/introduction.rst sections/architecture.rst + sections/external-provider.rst sections/build.rst sections/offeredapis.rst sections/usage.rst diff --git a/docs/sections/external-provider.rst b/docs/sections/external-provider.rst new file mode 100644 index 00000000..2ae1de9b --- /dev/null +++ b/docs/sections/external-provider.rst @@ -0,0 +1,138 @@ +.. 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. + +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 + # DNS SAN + dnsNames: + - localhost + - certissuer.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