diff options
author | 2020-03-25 11:54:11 +0100 | |
---|---|---|
committer | 2020-03-26 10:17:56 +0100 | |
commit | 483ccbf2d8f0c71ebb15a4a47246a68a42e68f3e (patch) | |
tree | 607a4bc00b06c380bd25a692f8710bde80fe83d8 /docs | |
parent | 9600d1361dd6e662248fe0704d1436ae56d446a7 (diff) |
Documentation
Issue-ID: AAF-1091
Signed-off-by: Zebek Bogumil <bogumil.zebek@nokia.com>
Change-Id: I59df0545c4dd5adfde32c83988f89cd2d0c4676b
Diffstat (limited to 'docs')
-rw-r--r-- | docs/Makefile | 23 | ||||
-rw-r--r-- | docs/README.md | 21 | ||||
-rw-r--r-- | docs/conf.py | 3 | ||||
-rw-r--r-- | docs/index.rst | 21 | ||||
-rw-r--r-- | docs/requirements-docs.txt | 1 | ||||
-rw-r--r-- | docs/sections/architecture.rst | 18 | ||||
-rw-r--r-- | docs/sections/build.rst | 61 | ||||
-rw-r--r-- | docs/sections/configuration.rst | 28 | ||||
-rw-r--r-- | docs/sections/img/certservice_high_level.jpg | bin | 0 -> 24640 bytes | |||
-rw-r--r-- | docs/sections/installation.rst | 21 | ||||
-rw-r--r-- | docs/sections/logging.rst | 25 | ||||
-rw-r--r-- | docs/sections/offeredapis.rst | 11 | ||||
-rw-r--r-- | docs/sections/openapi.yaml | 158 | ||||
-rw-r--r-- | docs/sections/release-notes.rst | 50 |
14 files changed, 438 insertions, 3 deletions
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 Binary files differnew file mode 100644 index 00000000..11466983 --- /dev/null +++ b/docs/sections/img/certservice_high_level.jpg 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 |