Update CertClient Documentation

Update and Move CertClient description to usage page, add empty troubleshooting page.

Issue-ID: AAF-1091
Signed-off-by: Tomasz Wrobel <tomasz.wrobel@nokia.com>
Change-Id: I0b9ef819875f5c20942208957b828185d08b8950

diff --git a/docs/index.rst b/docs/index.rst
index 7a55a2c..d85e365 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,10 +13,12 @@ AAF Certification Service
    sections/architecture.rst
    sections/build.rst
    sections/offeredapis.rst
+   sections/usage.rst
    sections/logging.rst
    sections/installation.rst
    sections/configuration.rst
    sections/release-notes.rst
+   sections/troubleshooting.rst
 
 Indices and tables
 ==================

diff --git a/docs/sections/configuration.rst b/docs/sections/configuration.rst
index c71d28c..f6078a4 100644 (file)
--- a/docs/sections/configuration.rst
+++ b/docs/sections/configuration.rst
@@ -5,46 +5,6 @@
 Configuration
 =============
 
-Standalone docker container
----------------------------
-
-Certification Service Client image:
-
-.. code-block:: 
-
-  nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest 
-
-
-1. Create file with environments as in example below.
-
-.. code-block:: 
-
-  #Client envs
-  REQUEST_URL=http://aaf-cert-service:8080/v1/certificate/
-  REQUEST_TIMEOUT=1000
-  OUTPUT_PATH=/var/certs
-  CA_NAME=RA
-  #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
-
-
-2. Run docker container with environments file and docker network (API and client must be running in same network).
-
-.. code-block:: bash
-
-  AAFCERT_CLIENT_IMAGE=nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest
-  DOCKER_ENV_FILE= <path to environment file>
-  NETWORK_CERT_SERVICE= <docker network of cert service>
-  DOCKER_VOLUME="<absolute path to local dir>:<output path>"
-
-  docker run --env-file $DOCKER_ENV_FILE --network $NETWORK_CERT_SERVICE --volume $DOCKER_VOLUME $AAFCERT_CLIENT_IMAGE
-
 
 Configuring Cert Service
 ------------------------
@@ -234,64 +194,3 @@ If you wish to configure the EJBCA server, you can find Documentation for EJBCA
 
 If you want to understand how CMP works on EJBCA in more detail, you can find Details here: https://download.primekey.com/docs/EJBCA-Enterprise/6_14_0/CMP.html
 
-Init Container for K8s
-----------------------
-
-Example deployment:
-
-.. code-block:: yaml
-
-    ...
-  kind: Deployment
-  metadata:
-    ...
-  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.aaf.certservice.aaf-certservice-client:latest
-            imagePullPolicy: Always
-            env:
-              - name: REQUEST_URL
-                value: http://aaf-cert-service:8080/v1/certificate/
-              - name: REQUEST_TIMEOUT
-                value: "1000"
-              - name: OUTPUT_PATH
-                value: /var/certs
-              - name: CA_NAME
-                value: RA
-              - 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
-            volumeMounts:
-              - mountPath: /var/certs
-                name: certs
-          ...
-        volumes: 
-          -emptyDir: {}
-           name: certs
-        ...
-
- 
\ No newline at end of file

diff --git a/docs/sections/logging.rst b/docs/sections/logging.rst
index 5d9aac8..abf951f 100644 (file)
--- a/docs/sections/logging.rst
+++ b/docs/sections/logging.rst
@@ -2,6 +2,8 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. Copyright 2020 NOKIA
 
+.. _cert_logs:
+
 Logging
 =======
 
@@ -50,6 +52,7 @@ Available log files:
 User cannot change logging levels.
 
 
+
 Certification Service Client
 ----------------------------
 To see console Certification Service Client logs use :

diff --git a/docs/sections/troubleshooting.rst b/docs/sections/troubleshooting.rst
new file mode 100644 (file)
index 0000000..1d454cc
--- /dev/null
+++ b/docs/sections/troubleshooting.rst
@@ -0,0 +1,9 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Troubleshooting
+===============
+
+
+

diff --git a/docs/sections/usage.rst b/docs/sections/usage.rst
new file mode 100644 (file)
index 0000000..fd9a2b6
--- /dev/null
+++ b/docs/sections/usage.rst
@@ -0,0 +1,171 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+How to use functionality
+========================
+
+Basic information
+-----------------
+Certification Client needs the following configuration parameters to work properly:
+
+1. Parameters for connection to certification service API and generate trustore and keystore
+  
+  - REQUEST_URL *(default: https://aaf-cert-service:8443/v1/certificate/)*
+  - REQUEST_TIMEOUT *(default: 30000)*
+  - OUTPUT_PATH *(required)*
+  - CA_NAME *(required)* 
+
+
+2. Parameters for generate CSR file:
+  
+  - COMMON_NAME *(required)*
+  - ORGANIZATION *(required)*
+  - ORGANIZATION_UNIT *(optional)*
+  - LOCATION *(optional)*
+  - STATE *(required)*
+  - COUNTRY *(required)*
+  - SANS *(optional)(SANS's should be separated by a colon)*
+
+3. Parameters for secure connection: 
+
+  - KEYSTORE_PATH *(required)*
+  - KEYSTORE_PASSWORD *(required)*
+  - TRUSTSTORE_PATH *(required)*
+  - TRUSTSTORE_PASSWORD *(required)*
+
+Certification Service Client image can be find on Nexus repository :
+
+.. code-block:: bash
+
+  nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest 
+
+
+As standalone docker container
+------------------------------
+You need certification files to connect to certification service 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=aaf%2Fcertservice.git;a=summary>`__
+
+To run Certification Client as standalone docker container execute following steps: 
+
+1. Create file with environments as in example below:
+
+.. code-block:: bash
+
+  #Client envs
+  REQUEST_URL=<url to certification service API>
+  REQUEST_TIMEOUT=10000
+  OUTPUT_PATH=/var/certs
+  CA_NAME=RA
+  #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
+  #Tls config envs
+  KEYSTORE_PATH=/etc/onap/aaf/certservice/certs/certServiceClient-keystore.jks
+  KEYSTORE_PASSWORD=<password to keystore.jks>
+  TRUSTSTORE_PATH=/etc/onap/aaf/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 aafcert-client \
+    --env-file <path to environments file> \
+    --network <docker network of cert service> \
+    --mount type=bind,src=<path to local directory>,dst=<OUTPUT_PATH> \
+    --volume <local path to keystore.jks>:<KEYSTORE_PATH> \
+    --volume <local path to trustore.jks>:<TRUSTSTORE_PATH> \
+    nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest 
+
+
+
+After successful creation of certifications, container exits with exit code 0, expected logs looks like:
+
+.. code-block:: bash
+
+  INFO 1 [           main] o.o.a.c.c.c.f.ClientConfigurationFactory : Successful validation of Client configuration. Configuration data: REQUEST_URL: https://aaf-cert-service:8443/v1/certificate/, REQUEST_TIMEOUT: 10000, OUTPUT_PATH: /var/certs, CA_NAME: RA
+  INFO 1 [           main] o.o.a.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: test.onap.org:onap.org
+  INFO 1 [           main] o.o.a.c.c.c.KeyPairFactory               : KeyPair generation started with algorithm: RSA and key size: 2048
+  INFO 1 [           main] o.o.a.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: test.onap.org:onap.org
+  INFO 1 [           main] o.o.a.c.c.c.CsrFactory                   : Creation of CSR has been completed successfully
+  INFO 1 [           main] o.o.a.c.c.c.CsrFactory                   : Conversion of CSR to PEM has been started
+  INFO 1 [           main] o.o.a.c.c.c.PrivateKeyToPemEncoder       : Attempt to encode private key to PEM
+  INFO 1 [           main] o.o.a.c.c.h.HttpClient                   : Attempt to send request to API, on url: https://aaf-cert-service:8443/v1/certificate/RA 
+  INFO 1 [           main] o.o.a.c.c.h.HttpClient                   : Received response from API
+  INFO 1 [           main] o.o.a.c.c.c.c.PemToPKCS12Converter       : Conversion of PEM certificates to PKCS12 keystore
+  DEBUG 1 [           main] o.o.a.c.c.c.c.PKCS12FilesCreator         : Attempt to create PKCS12 keystore files and saving data. Keystore path: /var/certs/keystore.jks
+  INFO 1 [           main] o.o.a.c.c.c.c.PemToPKCS12Converter       : Conversion of PEM certificates to PKCS12 truststore
+  DEBUG 1 [           main] o.o.a.c.c.c.c.PKCS12FilesCreator         : Attempt to create PKCS12 truststore files and saving data. Truststore path: /var/certs/truststore.jks
+  INFO 1 [           main] o.o.a.c.c.AppExitHandler                 : Application exits with following exit code: 0 and message: Success
+
+
+If container exits with non 0 exit code, you can find more information in logs, see :ref:`cert_logs` page.
+
+As init container for Kubernetes
+--------------------------------
+
+To run Certification Client as init container for ONAP component, add following configuration to deploymnet:
+
+.. code-block:: yaml
+
+    ...
+  kind: Deployment
+  metadata:
+    ...
+  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.aaf.certservice.aaf-certservice-client:latest
+            imagePullPolicy: Always
+            env:
+              - name: REQUEST_URL
+                value: http://aaf-cert-service:8080/v1/certificate/
+              - name: REQUEST_TIMEOUT
+                value: "1000"
+              - name: OUTPUT_PATH
+                value: /var/certs
+              - name: CA_NAME
+                value: RA
+              - 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
+            volumeMounts:
+              - mountPath: /var/certs
+                name: certs
+          ...
+        volumes: 
+          -emptyDir: {}
+           name: certs
+        ...
+
+ 
\ No newline at end of file