[OOM-CERT-SERVICE] Deprecate certServiceClient - update docs

- Remove certServiceClient description from docs
- Move descrption of CMPv2 provider to "How to use functionality"
- Update description of getting certs for CertService in OOM
- Update certService version to 2.4.0

Issue-ID: OOM-2744
Signed-off-by: Piotr Marcinkiewicz <piotr.marcinkiewicz@nokia.com>
Change-Id: I283755b8fbd579646f979c88ea3022266855c4dc

1 files changed, 117 insertions, 180 deletions

diff --git a/docs/sections/usage.rst b/docs/sections/usage.rst
index 0bbf348e..3031f364 100644
--- a/docs/sections/usage.rst
+++ b/docs/sections/usage.rst
@@ -1,211 +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
+.. Copyright 2020-2021 NOKIA
 
 How to use functionality
 =========================
-Common information to docker and Kubernetes modes described below
+Common information how to use CMPv2 certificate provider described below
 
-Basic information
------------------
-CertService client needs the following configuration parameters to work properly:
-
-1. Parameters for generating certification artifacts and connecting to CertService API to obtain certificate and trust anchors
-  
-  - REQUEST_URL *(default: https://oom-cert-service:8443/v1/certificate/)* - URL to CertService API
-  - REQUEST_TIMEOUT *(default: 30000[ms])* - Timeout in milliseconds for REST API calls
-  - OUTPUT_PATH *(required)* - Path where client will output generated certificate and trust anchor
-  - CA_NAME *(required)* - Name of CA which will enroll certificate. Must be same as configured on server side. Used in REST API calls
-  - OUTPUT_TYPE *(default: P12)* - Type of certificate which will be generated. Supported types: 
-      
-      - JKS - Java KeyStore (JKS)
-      - P12 - Public Key Cryptography Standard #12 (PKCS#12)
-      - PEM - Privacy-Enhanced Mail (PEM)
-
-
-2. Parameters to generate Certificate Signing Request (CSR):
-  
-  - COMMON_NAME *(required)* - Common name for which certificate from CMPv2 server should be issued
-  - ORGANIZATION *(required)* - Organization for which certificate from CMPv2 server should be issued
-  - ORGANIZATION_UNIT *(optional)* - Organization unit for which certificate from CMPv2 server should be issued
-  - LOCATION *(optional)* - Location for which certificate from CMPv2 server should be issued
-  - STATE *(required)* - State for which certificate from CMPv2 server should be issued
-  - COUNTRY *(required)* - Country for which certificate from CMPv2 server should be issued
-  - SANS *(optional)(SANS's should be separated by a comma e.g. test.onap.org,onap.com)* - Subject Alternative Names (SANs) for which certificate from CMPv2 server should be issued. The following SANs types are supported: DNS names, IPs, URIs, emails.
-
-3. Parameters to establish secure communication to CertService:
-
-  - KEYSTORE_PATH *(required)*
-  - KEYSTORE_PASSWORD *(required)*
-  - TRUSTSTORE_PATH *(required)*
-  - TRUSTSTORE_PASSWORD *(required)*
-
-CertService client image can be found on Nexus repository :
-
-.. code-block:: bash
-
-  nexus3.onap.org:10001/onap/org.onap.oom.platform.cert-service.oom-certservice-client:$VERSION
-
-
-As standalone docker container
+General information
 ------------------------------
-You need certificate and trust anchors to connect to CertService API via HTTPS. Information how to generate truststore and keystore files you can find in project repository README `Gerrit GitWeb <https://gerrit.onap.org/r/gitweb?p=oom%2Fplatform%2Fcert-service.git;a=summary>`__
-
-To run CertService client as standalone docker container execute following steps:
-
-1. Create file '*$PWD/client.env*' with environment variables as in example below:
 
-.. code-block:: bash
+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.
 
-  #Client envs
-  REQUEST_URL=<URL to CertService API>
-  REQUEST_TIMEOUT=10000
-  OUTPUT_PATH=/var/certs
-  CA_NAME=RA
-  OUTPUT_TYPE=P12
+Additional information can be found on a dedicated page:  https://wiki.onap.org/display/DW/CertService+and+K8s+Cert-Manager+integration.
 
-  #CSR config envs
-  COMMON_NAME=onap.org
-  ORGANIZATION=Linux-Foundation
-  ORGANIZATION_UNIT=ONAP
-  LOCATION=San-Francisco
-  STATE=California
-  COUNTRY=US
-  SANS=test.onap.org,onap.com,onap@onap.org,127.0.0.1,onap://cluster.local/
+By default CMPv2 provider is enabled.
 
-  #TLS config envs
-  KEYSTORE_PATH=/etc/onap/oom/certservice/certs/certServiceClient-keystore.jks
-  KEYSTORE_PASSWORD=<password to certServiceClient-keystore.jks>
-  TRUSTSTORE_PATH=/etc/onap/oom/certservice/certs/certServiceClient-truststore.jks
-  TRUSTSTORE_PASSWORD=<password to certServiceClient-truststore.jks>
-
-2. Run docker container as in following example (API and client must be running in same network):
-
-.. code-block:: bash
-
- docker run \
-    --rm \
-    --name oomcert-client \
-    --env-file <$PWD/client.env (same as in step1)> \
-    --network <docker network of cert service> \
-    --mount type=bind,src=<path to local host directory where certificate and trust anchor will be created>,dst=<OUTPUT_PATH (same as in step 1)> \
-    --volume <local path to keystore in JKS format>:<KEYSTORE_PATH> \
-    --volume <local path to truststore in JKS format>:<TRUSTSTORE_PATH> \
-    nexus3.onap.org:10001/onap/org.onap.oom.platform.cert-service.oom-certservice-client:$VERSION
+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.
 
-After successful creation of certifications, container exits with exit code 0, expected log looks like:
+**NOTE: a default instance of CMPv2Issuer is created when installing ONAP via OOM deployment.**
 
-.. code-block:: bash
+Here is a definition of a *CMPv2Issuer* provided with ONAP installation:
 
-   INFO 1 [           main] o.o.o.c.c.c.f.ClientConfigurationFactory : Successful validation of Client configuration. Configuration data: REQUEST_URL: https://oom-cert-service:8443/v1/certificate/, REQUEST_TIMEOUT: 10000, OUTPUT_PATH: /var/certs, CA_NAME: RA, OUTPUT_TYPE: P12
-   INFO 1 [           main] o.o.o.c.c.c.f.CsrConfigurationFactory    : Successful validation of CSR configuration. Configuration data: COMMON_NAME: onap.org, COUNTRY: US, STATE: California, ORGANIZATION: Linux-Foundation, ORGANIZATION_UNIT: ONAP, LOCATION: San-Francisco, SANS: [{SAN value: example.org, type: dNSName}, {SAN value: test.onap.org, type: dNSName}, {SAN value: onap@onap.org, type: rfc822Name}, {SAN value: 127.0.0.1, type: iPAddress}, {SAN value: onap://cluster.local/, type: uniformResourceIdentifier}]
-   INFO 1 [           main] o.o.o.c.c.c.KeyPairFactory               : KeyPair generation started with algorithm: RSA and key size: 2048
-   INFO 1 [           main] o.o.o.c.c.c.CsrFactory                   : Creation of CSR has been started with following parameters: COMMON_NAME: onap.org, COUNTRY: US, STATE: California, ORGANIZATION: Linux-Foundation, ORGANIZATION_UNIT: ONAP, LOCATION: San-Francisco, SANS: [{SAN value: example.org, type: dNSName}, {SAN value: test.onap.org, type: dNSName}, {SAN value: onap@onap.org, type: rfc822Name}, {SAN value: 127.0.0.1, type: iPAddress}, {SAN value: onap://cluster.local/, type: uniformResourceIdentifier}]
-   INFO 1 [           main] o.o.o.c.c.c.CsrFactory                   : Creation of CSR has been completed successfully
-   INFO 1 [           main] o.o.o.c.c.c.CsrFactory                   : Conversion of CSR to PEM has been started
-   INFO 1 [           main] o.o.o.c.c.c.PrivateKeyToPemEncoder       : Attempt to encode private key to PEM
-   INFO 1 [           main] o.o.o.c.c.h.HttpClient                   : Attempt to send request to API, on url: https://oom-cert-service:8443/v1/certificate/RA
-   INFO 1 [           main] o.o.o.c.c.h.HttpClient                   : Received response from API
-  DEBUG 1 [           main] o.o.o.c.c.c.c.ConvertedArtifactsCreator  : Attempt to create keystore files and saving data. File names: keystore.p12, keystore.pass
-   INFO 1 [           main] o.o.o.c.c.c.c.PemConverter               : Conversion of PEM certificates to PKCS12 keystore
-  DEBUG 1 [           main] o.o.o.c.c.c.w.CertFileWriter             : Attempt to save file keystore.p12 in path /var/certs
-  DEBUG 1 [           main] o.o.o.c.c.c.w.CertFileWriter             : Attempt to save file keystore.pass in path /var/certs
-  DEBUG 1 [           main] o.o.o.c.c.c.c.ConvertedArtifactsCreator  : Attempt to create truststore files and saving data. File names: truststore.p12, truststore.pass
-   INFO 1 [           main] o.o.o.c.c.c.c.PemConverter               : Conversion of PEM certificates to PKCS12 truststore
-  DEBUG 1 [           main] o.o.o.c.c.c.w.CertFileWriter             : Attempt to save file truststore.p12 in path /var/certs
-  DEBUG 1 [           main] o.o.o.c.c.c.w.CertFileWriter             : Attempt to save file truststore.pass in path /var/certs
-   INFO 1 [           main] o.o.o.c.c.AppExitHandler                 : Application exits with following exit code: 0 and message: Success
+.. 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:
 
-If container exits with non 0 exit code, you can find more information in logs, see :ref:`cert_logs` page.
+- group: certmanager.onap.org
 
-As init container for Kubernetes
---------------------------------
+- kind: CMPv2Issuer
 
-In order to run CertService client as init container for ONAP component you need to:
+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).
 
-    - define an init container and use CerService Client image
-    - provide client configuration through ENV variables in the init container
-    - define two volumes:
+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.
 
-        - first for generated certificates - it will be mounted in the init container and in the component container
-        - second with secret containing keys and certificates for secure communication between CertService Client and CertService - it will be mounted only in the init container
-    - mount both volumes to the init container
-    - mount first volume to the component container
+The following SANs types are supported: DNS names, IPs, URIs, emails.
 
-You can use the following deployment example as a reference:
+Here is an example of a *Certificate*:
 
 .. code-block:: yaml
 
-    ...
-  kind: Deployment
+  apiVersion: cert-manager.io/v1
+  kind: Certificate
   metadata:
-    ...
+    name: certificate_name
+    namespace: onap
   spec:
-  ...
-    template:
-    ...
-      spec:
-        containers:
-          - image: sample.image
-            name: sample.name 
-            ...
-            volumeMounts:
-              - mountPath: /var/certs #CERTS CAN BE FOUND IN THIS DIRECTORY
-                name: certs
-            ...
-        initContainers:
-          - name: cert-service-client
-            image: nexus3.onap.org:10001/onap/org.onap.oom.platform.cert-service.oom-certservice-client:latest
-            imagePullPolicy: Always
-            env:
-              - name: REQUEST_URL
-                value: https://oom-cert-service:8443/v1/certificate/
-              - name: REQUEST_TIMEOUT
-                value: "1000"
-              - name: OUTPUT_PATH
-                value: /var/certs
-              - name: CA_NAME
-                value: RA
-              - name: OUTPUT_TYPE
-                value: P12
-              - name: COMMON_NAME
-                value: onap.org
-              - name: ORGANIZATION
-                value: Linux-Foundation
-              - name: ORGANIZATION_UNIT
-                value: ONAP
-              - name: LOCATION
-                value: San-Francisco
-              - name: STATE
-                value: California
-              - name: COUNTRY
-                value: US
-              - name: SANS
-                value: test.onap.org,onap.com,onap@onap.org,127.0.0.1,onap://cluster.local/
-              - name: KEYSTORE_PATH
-                value: /etc/onap/oom/certservice/certs/certServiceClient-keystore.jks
-              - name: KEYSTORE_PASSWORD
-                value: secret
-              - name: TRUSTSTORE_PATH
-                value: /etc/onap/oom/certservice/certs/truststore.jks
-              - name: TRUSTSTORE_PASSWORD
-                value: secret
-            volumeMounts:
-              - mountPath: /var/certs
-                name: certs
-              - mountPath: /etc/onap/oom/certservice/certs/
-                name: tls-volume
-          ...
-        volumes: 
-        - name: certs
-          emptyDir: {}
-        - name tls-volume
-          secret:
-            secretName: oom-cert-service-client-tls-secret  # Value of global.oom.certService.client.secret.name
-        ...
+    # 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:       <none>
+    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)