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
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,10 +13,12 @@
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
--- 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 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
--- 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 @@
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
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
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