aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorBogumil Zebek <bogumil.zebek@nokia.com>2020-03-25 11:54:11 +0100
committerZebek Bogumil <bogumil.zebek@nokia.com>2020-03-26 10:17:56 +0100
commit483ccbf2d8f0c71ebb15a4a47246a68a42e68f3e (patch)
tree607a4bc00b06c380bd25a692f8710bde80fe83d8
parent9600d1361dd6e662248fe0704d1436ae56d446a7 (diff)
Documentation
Issue-ID: AAF-1091 Signed-off-by: Zebek Bogumil <bogumil.zebek@nokia.com> Change-Id: I59df0545c4dd5adfde32c83988f89cd2d0c4676b
-rw-r--r--certService/README.md4
-rw-r--r--docs/Makefile23
-rw-r--r--docs/README.md21
-rw-r--r--docs/conf.py3
-rw-r--r--docs/index.rst21
-rw-r--r--docs/requirements-docs.txt1
-rw-r--r--docs/sections/architecture.rst18
-rw-r--r--docs/sections/build.rst61
-rw-r--r--docs/sections/configuration.rst28
-rw-r--r--docs/sections/img/certservice_high_level.jpgbin0 -> 24640 bytes
-rw-r--r--docs/sections/installation.rst21
-rw-r--r--docs/sections/logging.rst25
-rw-r--r--docs/sections/offeredapis.rst11
-rw-r--r--docs/sections/openapi.yaml158
-rw-r--r--docs/sections/release-notes.rst50
15 files changed, 440 insertions, 5 deletions
diff --git a/certService/README.md b/certService/README.md
index 8e7fccc4..61506e79 100644
--- a/certService/README.md
+++ b/certService/README.md
@@ -88,11 +88,11 @@ path:
cd /var/log/onap/aaf/certservice
```
You should see:
-audit.log error.log trace.log
+audit.log error.log debug.log
### RestAPI
API is described by Swagger ( OpenAPI 3.0 ) on endpoint /docs
( endpoint is defined in properties as springdoc.swagger-ui.path )
```
http://localchost:8080/docs
-``` \ No newline at end of file
+```
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 00000000..65513dc3
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+SOURCEDIR = .
+BUILDDIR = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+clean:
+ @echo "##### Clean build directory #####"
+ rm -rf $(BUILDDIR)
+ @echo "##### Done #####"
+
+.PHONY: help clean Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..15deadea
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,21 @@
+## AAF Certification Service documentation
+###Requirements
+ Python 3.x
+
+To generate a documentation locally follow below steps.
+
+1. Open **docs** folder in terminal
+2. Install all required dependencies
+
+ ```
+ python install -r requirements-docs.txt
+ ```
+3. Generate local documentation
+ ```
+ make html
+ ```
+ After command execution the documentation will be available in **_build/html** folder.
+4. Before you commit documentation changes please execute
+ ```
+ make clean
+ ```
diff --git a/docs/conf.py b/docs/conf.py
index 8f40e8b8..b37b90cf 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -7,6 +7,9 @@ linkcheck_ignore = [
'http://localhost',
]
+extensions = [
+ 'sphinxcontrib.openapi',
+]
intersphinx_mapping = {}
html_last_updated_fmt = '%d-%b-%y %H:%M'
diff --git a/docs/index.rst b/docs/index.rst
index 87b61527..e84df935 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -2,7 +2,22 @@
.. http://creativecommons.org/licenses/by/4.0
.. Copyright 2020 NOKIA
-AAF Cert Service
-------------------------------------------------
+AAF Certification Service
+=========================================
+
.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
+ :caption: Contents:
+
+ sections/architecture.rst
+ sections/build.rst
+ sections/offeredapis.rst
+ sections/logging.rst
+ sections/installation.rst
+ sections/configuration.rst
+ sections/release-notes.rst
+
+Indices and tables
+==================
+
+* :ref:`search`
diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
index b3188ddd..98fc25ce 100644
--- a/docs/requirements-docs.txt
+++ b/docs/requirements-docs.txt
@@ -10,6 +10,7 @@ sphinxcontrib-needs>=0.2.3
sphinxcontrib-nwdiag
sphinxcontrib-seqdiag
sphinxcontrib-swaggerdoc
+sphinxcontrib-openapi
sphinxcontrib-plantuml
sphinx_bootstrap_theme
lfdocs-conf
diff --git a/docs/sections/architecture.rst b/docs/sections/architecture.rst
new file mode 100644
index 00000000..654208d1
--- /dev/null
+++ b/docs/sections/architecture.rst
@@ -0,0 +1,18 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Architecture
+============
+
+The micro-service called CertService is designed for requesting certificates
+signed by external Certificate Authority (CA) using CMP over HTTP protocol. It uses CMPv2 client to send and receive CMPv2 messages.
+CertService's client will be also provided so other ONAP components (aka end components) can easily get certificate from CertService.
+End component is an ONAP component (e.g. DCAE collector or controller) which requires certificate from CMPv2 server
+to protect external traffic and uses CertService's client to get it.
+CertService's client communicates with CertService via REST API over HTTPS, while CertService with CMPv2 server via CMP over HTTP.
+
+.. image:: img/certservice_high_level.jpg
+ :width: 855px
+ :height: 178px
+ :alt: Interaction between components
diff --git a/docs/sections/build.rst b/docs/sections/build.rst
new file mode 100644
index 00000000..d533e330
--- /dev/null
+++ b/docs/sections/build.rst
@@ -0,0 +1,61 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Build
+=====
+
+Jenkins
+-------
+#. JJB Master
+
+ https://jenkins.onap.org/view/aaf/job/aaf-certservice-master-merge-java/
+
+#. JJB Stage
+
+ https://jenkins.onap.org/view/aaf/job/aaf-certservice-maven-docker-stage-master/
+
+#. JJB Release
+
+ https://jenkins.onap.org/view/aaf/job/aaf-certservice-maven-stage-master/
+ https://jenkins.onap.org/view/aaf/job/aaf-certservice-release-merge/
+
+#. JJB CSIT
+
+ https://jenkins.onap.org/view/CSIT/job/aaf-master-csit-certservice/
+
+Environment
+-----------
+
+* Java 11
+* Apache Maven 3.6.0
+* Linux
+* Docker 18.09.5
+* Python 2.7.x
+
+How to build images?
+--------------------
+
+#. Checkout the project from https://gerrit.onap.org/r/#/admin/projects/aaf/certservice
+#. Read information's stored in README.md file
+#. Use a Makefile to build images::
+
+ make build
+
+How to start service locally?
+-----------------------------------------------
+#. Start Cert Service with configured EJBCA::
+
+ make start-backend
+
+#. Run Cert Service Client::
+
+ make run-client
+
+#. Remove client container::
+
+ make stop-client
+
+#. Stop Cert Service and EJBCA::
+
+ make stop-backend
diff --git a/docs/sections/configuration.rst b/docs/sections/configuration.rst
new file mode 100644
index 00000000..47f2dd87
--- /dev/null
+++ b/docs/sections/configuration.rst
@@ -0,0 +1,28 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Configuration
+=============
+
+.. note::
+ * This section is used to describe the options a software component offers for configuration.
+
+ * Configuration is typically: provided for platform-component and sdk projects;
+ and referenced in developer and user guides.
+
+ * This note must be removed after content has been added.
+
+
+
+Example ...
+
+You can provide the following in ``basic.conf``
+
+``host=ADDRESS``
+ The address of the host
+
+``port=PORT``
+ The port used for signaling
+
+ Optional. Default: ``8080``
diff --git a/docs/sections/img/certservice_high_level.jpg b/docs/sections/img/certservice_high_level.jpg
new file mode 100644
index 00000000..11466983
--- /dev/null
+++ b/docs/sections/img/certservice_high_level.jpg
Binary files differ
diff --git a/docs/sections/installation.rst b/docs/sections/installation.rst
new file mode 100644
index 00000000..8ef137fc
--- /dev/null
+++ b/docs/sections/installation.rst
@@ -0,0 +1,21 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Installation
+============
+
+.. note::
+ * This section is used to describe how a software component is acquired and installed.
+
+ * This section is typically: provided for a platform-component and application; and
+ referenced in user guides.
+
+ * This note must be removed after content has been added.
+
+Environment
+-----------
+
+
+Steps
+-----
diff --git a/docs/sections/logging.rst b/docs/sections/logging.rst
new file mode 100644
index 00000000..159b5132
--- /dev/null
+++ b/docs/sections/logging.rst
@@ -0,0 +1,25 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Logging
+=======
+
+Where to Access Information
+---------------------------
+
+Certification Service logs are available in the Docker container
+
+ docker exec -it aaf-certservice-api bash
+
+Path to logs:
+
+ /var/log/onap/aaf/certservice
+
+Available log files:
+
+ * audit.log
+ * debug.log
+ * error.log
+
+
diff --git a/docs/sections/offeredapis.rst b/docs/sections/offeredapis.rst
new file mode 100644
index 00000000..fe5807a8
--- /dev/null
+++ b/docs/sections/offeredapis.rst
@@ -0,0 +1,11 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Offered APIs
+============
+
+AAF Cert Service Api
+--------------------
+
+.. openapi:: ../../certService/OpenAPI.yaml
diff --git a/docs/sections/openapi.yaml b/docs/sections/openapi.yaml
new file mode 100644
index 00000000..cee5a402
--- /dev/null
+++ b/docs/sections/openapi.yaml
@@ -0,0 +1,158 @@
+openapi: 3.0.1
+info:
+ title: CertService Documentation
+ description: Certification service API documentation
+ version: 1.0.0
+servers:
+ - url: http://localhost:8080
+ description: Generated server url
+tags:
+ - name: Actuator
+ description: Monitor and interact
+ externalDocs:
+ description: Spring Boot Actuator Web API Documentation
+ url: https://docs.spring.io/spring-boot/docs/current/actuator-api/html/
+paths:
+ /v1/certificate/{caName}:
+ get:
+ tags:
+ - CertificationService
+ summary: sign certificate
+ description: Web endpoint for requesting certificate signing. Used by system
+ components to gain certificate signed by CA.
+ operationId: signCertificate
+ parameters:
+ - name: caName
+ in: path
+ description: Name of certification authority that will sign CSR.
+ required: true
+ schema:
+ type: string
+ - name: CSR
+ in: header
+ description: Certificate signing request in form of PEM object encoded in
+ Base64 (with header and footer).
+ required: true
+ schema:
+ type: string
+ - name: PK
+ in: header
+ description: Private key in form of PEM object encoded in Base64 (with header
+ and footer).
+ required: true
+ schema:
+ type: string
+ responses:
+ "200":
+ description: certificate successfully signed
+ content:
+ application/json; charset=utf-8:
+ schema:
+ $ref: '#/components/schemas/CertificationModel'
+ "500":
+ description: something went wrong during connecting to cmp client
+ content:
+ application/json; charset=utf-8:
+ schema:
+ $ref: '#/components/schemas/ErrorResponseModel'
+ "404":
+ description: CA not found for given name
+ content:
+ application/json; charset=utf-8:
+ schema:
+ $ref: '#/components/schemas/ErrorResponseModel'
+ "400":
+ description: given CSR or/and PK is incorrect
+ content:
+ application/json; charset=utf-8:
+ schema:
+ $ref: '#/components/schemas/ErrorResponseModel'
+ /ready:
+ get:
+ tags:
+ - CertificationService
+ summary: check is container is ready
+ description: Web endpoint for checking if service is ready to be used.
+ operationId: checkReady
+ responses:
+ "200":
+ description: configuration is loaded and service is ready to use
+ content:
+ application/json; charset=utf-8:
+ schema:
+ type: string
+ "503":
+ description: configuration loading failed and service is unavailable
+ content:
+ application/json; charset=utf-8:
+ schema:
+ type: string
+ /reload:
+ get:
+ tags:
+ - CertificationService
+ summary: reload service configuration from file
+ description: Web endpoint for performing configuration reload. Used to reload
+ configuration file from file.
+ operationId: reloadConfiguration
+ responses:
+ "200":
+ description: configuration has been successfully reloaded
+ content:
+ application/json; charset=utf-8:
+ schema:
+ type: string
+ "500":
+ description: something went wrong during configuration loading
+ content:
+ application/json; charset=utf-8:
+ schema:
+ $ref: '#/components/schemas/ErrorResponseModel'
+ /actuator/health:
+ get:
+ tags:
+ - Actuator
+ summary: Actuator web endpoint 'health'
+ operationId: handle_0
+ responses:
+ "200":
+ description: default response
+ content: {}
+ /actuator/health/**:
+ get:
+ tags:
+ - Actuator
+ summary: Actuator web endpoint 'health-path'
+ operationId: handle_1
+ responses:
+ "200":
+ description: default response
+ content: {}
+ /actuator:
+ get:
+ tags:
+ - Actuator
+ summary: Actuator root web endpoint
+ operationId: links_2
+ responses:
+ "200":
+ description: default response
+ content: {}
+components:
+ schemas:
+ ErrorResponseModel:
+ type: object
+ properties:
+ errorMessage:
+ type: string
+ CertificationModel:
+ type: object
+ properties:
+ certificateChain:
+ type: array
+ items:
+ type: string
+ trustedCertificates:
+ type: array
+ items:
+ type: string
diff --git a/docs/sections/release-notes.rst b/docs/sections/release-notes.rst
new file mode 100644
index 00000000..bd00ac74
--- /dev/null
+++ b/docs/sections/release-notes.rst
@@ -0,0 +1,50 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+
+Release Notes
+=============
+
+Version: 1.0.0
+--------------
+
+:Release Date: 2020-03-25
+
+**New Features**
+
+The Frankfurt Release is the first release of the Certification Service.
+
+**Bug Fixes**
+
+ - No new fixes were implemented for this release
+
+**Known Issues**
+
+ N/A
+
+**Security Notes**
+
+ N/A
+
+*Fixed Security Issues*
+
+ N/A
+
+*Known Security Issues*
+
+ N/A
+
+*Known Vulnerabilities in Used Modules*
+
+ N/A
+
+**Upgrade Notes**
+
+**Deprecation Notes**
+
+**Other**
+
+===========
+
+End of Release Notes