docs/sections/usage.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2020 NOKIA
   4
   5 How to use functionality
   6 ========================
   7
   8 Basic information
   9 -----------------
  10 Certification Client needs the following configuration parameters to work properly:
  11
  12 1. Parameters for connection to certification service API and generate trustore and keystore
  13
  14   - REQUEST_URL *(default: https://aaf-cert-service:8443/v1/certificate/)*
  15   - REQUEST_TIMEOUT *(default: 30000)*
  16   - OUTPUT_PATH *(required)*
  17   - CA_NAME *(required)*
  18
  19
  20 2. Parameters for generate CSR file:
  21
  22   - COMMON_NAME *(required)*
  23   - ORGANIZATION *(required)*
  24   - ORGANIZATION_UNIT *(optional)*
  25   - LOCATION *(optional)*
  26   - STATE *(required)*
  27   - COUNTRY *(required)*
  28   - SANS *(optional)(SANS's should be separated by a colon)*
  29
  30 3. Parameters for secure connection:
  31
  32   - KEYSTORE_PATH *(required)*
  33   - KEYSTORE_PASSWORD *(required)*
  34   - TRUSTSTORE_PATH *(required)*
  35   - TRUSTSTORE_PASSWORD *(required)*
  36
  37 Certification Service Client image can be find on Nexus repository :
  38
  39 .. code-block:: bash
  40
  41   nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest
  42
  43
  44 As standalone docker container
  45 ------------------------------
  46 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>`__
  47
  48 To run Certification Client as standalone docker container execute following steps:
  49
  50 1. Create file with environments as in example below:
  51
  52 .. code-block:: bash
  53
  54   #Client envs
  55   REQUEST_URL=<url to certification service API>
  56   REQUEST_TIMEOUT=10000
  57   OUTPUT_PATH=/var/certs
  58   CA_NAME=RA
  59   #Csr config envs
  60   COMMON_NAME=onap.org
  61   ORGANIZATION=Linux-Foundation
  62   ORGANIZATION_UNIT=ONAP
  63   LOCATION=San-Francisco
  64   STATE=California
  65   COUNTRY=US
  66   SANS=test.onap.org:onap.com
  67   #Tls config envs
  68   KEYSTORE_PATH=/etc/onap/aaf/certservice/certs/certServiceClient-keystore.jks
  69   KEYSTORE_PASSWORD=<password to keystore.jks>
  70   TRUSTSTORE_PATH=/etc/onap/aaf/certservice/certs/certServiceClient-truststore.jks
  71   TRUSTSTORE_PASSWORD=<password to certServiceClient-truststore.jks>
  72
  73 2. Run docker container as in following example (API and client must be running in same network):
  74
  75 .. code-block:: bash
  76
  77  docker run \
  78     --rm \
  79     --name aafcert-client \
  80     --env-file <path to environments file> \
  81     --network <docker network of cert service> \
  82     --mount type=bind,src=<path to local directory>,dst=<OUTPUT_PATH> \
  83     --volume <local path to keystore.jks>:<KEYSTORE_PATH> \
  84     --volume <local path to trustore.jks>:<TRUSTSTORE_PATH> \
  85     nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest
  86
  87
  88
  89 After successful creation of certifications, container exits with exit code 0, expected logs looks like:
  90
  91 .. code-block:: bash
  92
  93   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
  94   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
  95   INFO 1 [           main] o.o.a.c.c.c.KeyPairFactory               : KeyPair generation started with algorithm: RSA and key size: 2048
  96   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
  97   INFO 1 [           main] o.o.a.c.c.c.CsrFactory                   : Creation of CSR has been completed successfully
  98   INFO 1 [           main] o.o.a.c.c.c.CsrFactory                   : Conversion of CSR to PEM has been started
  99   INFO 1 [           main] o.o.a.c.c.c.PrivateKeyToPemEncoder       : Attempt to encode private key to PEM
 100   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
 101   INFO 1 [           main] o.o.a.c.c.h.HttpClient                   : Received response from API
 102   INFO 1 [           main] o.o.a.c.c.c.c.PemToPKCS12Converter       : Conversion of PEM certificates to PKCS12 keystore
 103   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
 104   INFO 1 [           main] o.o.a.c.c.c.c.PemToPKCS12Converter       : Conversion of PEM certificates to PKCS12 truststore
 105   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
 106   INFO 1 [           main] o.o.a.c.c.AppExitHandler                 : Application exits with following exit code: 0 and message: Success
 107
 108
 109 If container exits with non 0 exit code, you can find more information in logs, see :ref:`cert_logs` page.
 110
 111 As init container for Kubernetes
 112 --------------------------------
 113
 114 To run Certification Client as init container for ONAP component, add following configuration to deploymnet:
 115
 116 .. code-block:: yaml
 117
 118     ...
 119   kind: Deployment
 120   metadata:
 121     ...
 122   spec:
 123   ...
 124     template:
 125     ...
 126       spec:
 127         containers:
 128           - image: sample.image
 129             name: sample.name
 130             ...
 131             volumeMounts:
 132               - mountPath: /var/certs #CERTS CAN BE FOUND IN THIS DIRECTORY
 133                 name: certs
 134             ...
 135         initContainers:
 136           - name: cert-service-client
 137             image: nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest
 138             imagePullPolicy: Always
 139             env:
 140               - name: REQUEST_URL
 141                 value: http://aaf-cert-service:8080/v1/certificate/
 142               - name: REQUEST_TIMEOUT
 143                 value: "1000"
 144               - name: OUTPUT_PATH
 145                 value: /var/certs
 146               - name: CA_NAME
 147                 value: RA
 148               - name: COMMON_NAME
 149                 value: onap.org
 150               - name: ORGANIZATION
 151                 value: Linux-Foundation
 152               - name: ORGANIZATION_UNIT
 153                 value: ONAP
 154               - name: LOCATION
 155                 value: San-Francisco
 156               - name: STATE
 157                 value: California
 158               - name: COUNTRY
 159                 value: US
 160               - name: SANS
 161                 value: test.onap.org:onap.com
 162             volumeMounts:
 163               - mountPath: /var/certs
 164                 name: certs
 165           ...
 166         volumes:
 167           -emptyDir: {}
 168            name: certs
 169         ...
 170
 171