From 483ccbf2d8f0c71ebb15a4a47246a68a42e68f3e Mon Sep 17 00:00:00 2001 From: Bogumil Zebek Date: Wed, 25 Mar 2020 11:54:11 +0100 Subject: Documentation Issue-ID: AAF-1091 Signed-off-by: Zebek Bogumil Change-Id: I59df0545c4dd5adfde32c83988f89cd2d0c4676b --- certService/README.md | 4 +- docs/Makefile | 23 ++++ docs/README.md | 21 ++++ docs/conf.py | 3 + docs/index.rst | 21 +++- docs/requirements-docs.txt | 1 + docs/sections/architecture.rst | 18 +++ docs/sections/build.rst | 61 +++++++++++ docs/sections/configuration.rst | 28 +++++ docs/sections/img/certservice_high_level.jpg | Bin 0 -> 24640 bytes docs/sections/installation.rst | 21 ++++ docs/sections/logging.rst | 25 +++++ docs/sections/offeredapis.rst | 11 ++ docs/sections/openapi.yaml | 158 +++++++++++++++++++++++++++ docs/sections/release-notes.rst | 50 +++++++++ 15 files changed, 440 insertions(+), 5 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/README.md create mode 100644 docs/sections/architecture.rst create mode 100644 docs/sections/build.rst create mode 100644 docs/sections/configuration.rst create mode 100644 docs/sections/img/certservice_high_level.jpg create mode 100644 docs/sections/installation.rst create mode 100644 docs/sections/logging.rst create mode 100644 docs/sections/offeredapis.rst create mode 100644 docs/sections/openapi.yaml create mode 100644 docs/sections/release-notes.rst 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 Binary files /dev/null and b/docs/sections/img/certservice_high_level.jpg 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 -- cgit 1.2.3-korg