diff options
Diffstat (limited to 'docs/sections')
| -rw-r--r-- | docs/sections/architecture.rst | 97 | ||||
| -rw-r--r-- | docs/sections/build.rst | 43 | ||||
| -rw-r--r-- | docs/sections/configuration.rst | 126 | ||||
| -rw-r--r-- | docs/sections/delivery.rst | 23 | ||||
| -rw-r--r-- | docs/sections/offeredapis.rst | 18 | ||||
| -rw-r--r-- | docs/sections/release-notes.rst | 105 |
6 files changed, 412 insertions, 0 deletions
diff --git a/docs/sections/architecture.rst b/docs/sections/architecture.rst new file mode 100644 index 0000000..a04626d --- /dev/null +++ b/docs/sections/architecture.rst @@ -0,0 +1,97 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2022 Nordix Foundation + +Architecture +============ + +.. + * This section is used to describe a software component from a high level + view of capability, common usage scenarios, and interactions with other + components required in the usage scenarios. + + * The architecture section is typically: provided in a platform-component + and sdk collections; and referenced from developer and user guides. + + * This note must be removed after content has been added. + + +Capabilities +------------ + +The SDC Distribution client is a library that applications can use to simplify the handling of +distribution related notifications from/to SDC and to download artifacts from SDC based on those notification. + +.. note:: + + As of version 2.0.0, the client uses kafka as it's message bus to publish/subscribe to/from the + relevant SDC distribution topics. + + All previous releases of the client use DMaaP Message Router as it's message bus. + +Usage Scenarios +--------------- +- **Get Distribution Notification event** + + The client polls the relevant NOTIFICATION topic for distribution events sent from SDC. + +- **Get Deployment Artifact from SDC** + + Once a new notification event is received, the client will download the relevant artifacts that it + has defined as part of it configuration. + +- **Send Distribution Status event** + + As part of the processing of the downloaded artifacts, the client will publish it's progress to SDC + via the relevant STATUS topic. + Once the download has ben successfully completed, the client must publish it's final response + COMPONENT_DONE_OK to the STATUS topic. + + +Interactions +------------ + +Kafka +^^^^^ +The client uses kafka as it's messaging bus to publish and subscribe to the relevant SDC topics. + +.. _SDCE-6 Swagger api: https://docs.onap.org/projects/onap-sdc/en/latest/_downloads/4eca2a3848d70e58566570a5ef889efb/swagger-sdce-6.json +.. _SDCE-7 Swagger api: https://docs.onap.org/projects/onap-sdc/en/latest/_downloads/542e76906472dae2e00adfad5fc7d879/swagger-sdce-7.json + +SDC +^^^ +**The client interacts with the following SDC apis on initialization:** + +- ``/sdc/v1/artifactTypes`` + + Get the current artifact types from SDC to validate against the clients configured list. + + See `SDCE-6 Swagger api`_ for more details + +- ``/sdc/v1/distributionKafkaData`` + + Get the kafka distribution config from SDC to be used during publish and subscribe + + See `SDCE-6 Swagger api`_ for more details + +.. image:: ../images/sdc_client_init.png + + + + +**The client interacts with the following SDC apis during distribution:** + +- ``/sdc/v1/catalog/services/{serviceName}/{serviceVersion}/resourceInstances/{resourceInstanceName}/artifacts/{artifactName}`` + + Get the artifact for a particular resource instance defined in the artifactUrl of the notification event + + See `SDCE-7 Swagger api`_ for more details + +- ``/sdc/v1/catalog/services/{serviceName}/{serviceVersion}/artifacts/{artifactName}`` + + Get the artifact defined in the artifactUrl of the notification event + + See `SDCE-7 Swagger api`_ for more details + + +.. image:: ../images/sdc_distrib_flow.png diff --git a/docs/sections/build.rst b/docs/sections/build.rst new file mode 100644 index 0000000..4ef3e71 --- /dev/null +++ b/docs/sections/build.rst @@ -0,0 +1,43 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2022 Nordix Foundation + +.. _build: + +Build +===== + +.. + * This section is used to describe how a software component is built from + source into something ready for use either in a run-time environment or to + build other components. + + * This section is typically provided for a platform-component, application, + and sdk; and referenced in developer guides. + + +Environment +----------- + +- JDK 11 + +- Maven 3.6.* + + - local .m2 settings.xml set to https://git.onap.org/oparent/plain/settings.xml + +For more information regarding Env set up see `Setting Up Your Development Environment`_. + +.. _Setting Up Your Development Environment: https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment + + +.. _Build steps: + +Steps +----- + +Run the following from project root: + +``mvn clean install`` + +The result is JAR file under the ``sdc-distribution-client/target`` folder + diff --git a/docs/sections/configuration.rst b/docs/sections/configuration.rst new file mode 100644 index 0000000..964d771 --- /dev/null +++ b/docs/sections/configuration.rst @@ -0,0 +1,126 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2022 Nordix Foundation + +.. _config: + +Configuration +============= + +The sdc-distribution-client configuration in ONAP is generally done via a config file +loaded to the container. + +Pre-requisites +-------------- +The parent project must provide a mechanism to load the configuration at runtime. + +This configuration is then passed as input to the parent projects implementation of the +sdc-distribution-client's IConfiguration interface. + +For more detailed information regarding the abstract methods of the interface that must be +overridden byt the parent project, please refer to the javadocs. + +Client configuration +-------------------- +The table below shows a brief outline of the client config. + +.. note:: + Attention should be given to any methods which provide default values. + ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| Name | Description | Type | Required | Default | ++===========================+===============================================================+=========+==========+=========+ +| sdcAddress | SDC Distribution Engine address | String | Y | NA | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| user | User Name for SDC distribution consumer authentication | String | Y | NA | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| password | User Password for SDC distribution consumer authentication | String | Y | NA | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| environmentName | The environment name. Must match what is set in SDC | String | Y | NA | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| useHttpsWithSdc | Whether to use https towards SDC | boolean | N | true | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| keyStorePath | Y If useHttpsWithSdc is true | String | See desc | NA | +| | N if activateServerTLSAuth set to false | | | | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| keyStorePassword | Y If useHttpsWithSdc is true | String | See desc | NA | +| | N if activateServerTLSAuth set to false | | | | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| activateServerTLSAuth | mTLS setting. | boolean | Y | NA | +| | If false, KeyStore path and password must be set | | | | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| consumeProduceStatusTopic | Whether to consume from both SDC distribution topics | boolean | N | false | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| consumerGroup | Group Id to use when consuming from the NOTIFICATION topic | String | Y | NA | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| consumerId | Consumer Id to use when consuming from the NOTIFICATION topic | String | Y | NA | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| pollingInterval | Interval between polls on the NOTIFICATION topic in sec | int | Y | NA | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| pollingTimeout | NOTIFICATION topic polling timeout in sec | int | Y | NA | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| relevantArtifactTypes | List of artifact types the client should consume | String | Y | NA | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| filterEmptyResource | See IConfiguration interface javadoc for more detail | boolean | Y | NA | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| useSystemProxy | Whether to use system or config proxies towards SDC | boolean | N | false | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| httpsProxyHost | The https proxy host to use towards SDC | String | N | null | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| httpsProxyPort | The https proxy port to use towards SDC | int | N | 0 | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| httpProxyHost | The http proxy host to use towards SDC | String | N | null | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ +| httpProxyPort | The http proxy port to use towards SDC | int | N | 0 | ++---------------------------+---------------------------------------------------------------+---------+----------+---------+ + + +Client Kafka config +^^^^^^^^^^^^^^^^^^^ + +The client will use kafka as a messaging bus to publish and subscribe to the relevant SDC topics. + +The client's kafka configuration in ONAP should be handled via Strimzi kafka's +KafkaUser custom resource definition which provides access control to the relevant kafka topics. + +This is done at helm chart level for each component that requires access to kafka topics. + ++-----------------------+---------------------------------------------------------------+--------+----------+----------------------------------------------+ +| Name | Description | Type | Required | Default | ++=======================+===============================================================+========+==========+==============================================+ +| kafkaSecurityProtocol | The kafka security.protocol to use towards the kafka endpoint | String | N | SASL_PLAINTEXT | ++-----------------------+---------------------------------------------------------------+--------+----------+----------------------------------------------+ +| kafkaSaslMechanism | The kafka sasl.mechanism to use towards the kafka endpoint | String | N | SCRAM-SHA-512 | ++-----------------------+---------------------------------------------------------------+--------+----------+----------------------------------------------+ +| KafkaSaslJaasConfig | The kafka sasl.jaas.config to use towards the kafka endpoint | String | Y | Environment variable set to SASL_JAAS_CONFIG | ++-----------------------+---------------------------------------------------------------+--------+----------+----------------------------------------------+ + +.. note:: + The sasl.jaas.config for the client to use will default to an environment variable set as SASL_JAAS_CONFIG. + + This is expected to be in the form of org.apache.kafka.common.security.scram.ScramLoginModule required username="user" password="password"; + + +Initializing the client +^^^^^^^^^^^^^^^^^^^^^^^ + +Once the client config is loaded, it can then be passed to the IDistributionClient to initialize. + +.. code-block:: java + + // CustomClientConfig implementing IConfiguration + CustomClientConfig config = loadClientConfig(); + + IDistributionClient client = DistributionClientFactory.createDistributionClient(); + + // MyNotificationCallback implementing INotificationCallback + MyNotificationCallback callback; + + IDistributionClientResult result = client.init(config, callback); + //Verify the result is SUCCESS, otherwise there’s a problem setting up vs either SDC or Kafka clients + System.out.println(result.getDistributionMessageResult()); + + System.out.println("Starting client..."); + IDistributionClientResult startResult = client.start(); + // Verify the result is SUCCESS, otherwise there’s a problem in receiving/sending notifications to/from kafka topics + System.out.println(startResult.getDistributionMessageResult()); diff --git a/docs/sections/delivery.rst b/docs/sections/delivery.rst new file mode 100644 index 0000000..135dcd3 --- /dev/null +++ b/docs/sections/delivery.rst @@ -0,0 +1,23 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2022 Nordix Foundation + +Delivery +======== + +.. + * This section is used to describe the delivery of a software component. + For a run-time component, this might be executable images, containers, etc. + For an SDK, this might be libraries. + + * This section is typically provided for a platform-component and sdk; + and referenced in developer and user guides. + +Deliverables +------------ + +SDC distribution client is delivered as a jar library and hosted on https://nexus.onap.org/ + +To include it as a dependency in your project, see `SDC Distribution Client mvn`_. + +.. _SDC Distribution Client mvn: https://mvnrepository.com/artifact/org.onap.sdc.sdc-distribution-client/sdc-distribution-client diff --git a/docs/sections/offeredapis.rst b/docs/sections/offeredapis.rst new file mode 100644 index 0000000..7e59f76 --- /dev/null +++ b/docs/sections/offeredapis.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 (C) 2022 Nordix Foundation + +.. _api_docs: + +Offered APIs +============ + +The api javadocs for interfaces provided by the sdc distribution client can be compiled by building the project. + +See :ref:`build steps<Build Steps>` for more information. + +The javadocs can be then found under the ``sdc-distribution-client/target/apidocs`` folder. + +The main interface that must be implemented by clients is the IConfiguration interface. + +See the :ref:`configuration section<config>` configuration section for more details. diff --git a/docs/sections/release-notes.rst b/docs/sections/release-notes.rst new file mode 100644 index 0000000..cf7b0cf --- /dev/null +++ b/docs/sections/release-notes.rst @@ -0,0 +1,105 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 + International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2022 Nordix Foundation + +.. _release_notes: + + +.. =========================== +.. * * * LONDON * * * +.. =========================== + + +************* +Release Notes +************* + +.. + * The release note needs to be updated for each ONAP release + * Except the section "Release data" all other sections are optional and should be + applied where applicable + * Only the current release is to be documented in this document + * This note needs to be removed before publishing the final result + + +London +======== + + +Abstract +======== + +This document provides the release notes for the London release. + +Summary +======= +Client migration to use kafka as it's main messaging bus to publish and subscribe to the +SDC distribution topics. +Removal of all interaction with DMaaP Message Router apis. + +Release Data +============ + ++--------------------------------------+--------------------------------------+ +| **Project** | sdc/sdc-distribution-client | +| | | ++--------------------------------------+--------------------------------------+ +| **Jars** | sdc-distribution-client 2.0.0 | +| | | ++--------------------------------------+--------------------------------------+ + +New features +------------ +Modify client to use kafka native to publish and subscribe to SDC topics +https://jira.onap.org/browse/DMAAP-1745 + +Deliverables +------------ + +Software Deliverables +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: xml + + <groupId>org.onap.sdc.sdc-distribution-client</groupId> + <artifactId>sdc-distribution-client</artifactId> + <version>2.0.0</version> + +Known Limitations, Issues and Workarounds +========================================= + +System Limitations +------------------ +NA + +Known Vulnerabilities +--------------------- +NA + +Workarounds +----------- +NA + +Security Notes +-------------- +NA + +References +========== + +For more information on the ONAP London release, please see: + +#. `ONAP Home Page`_ +#. `ONAP Documentation`_ +#. `ONAP Release Downloads`_ +#. `ONAP Wiki Page`_ +#. `SDC ReadTheDocs`_ +#. `SDC Portal`_ + +.. _`ONAP Home Page`: https://www.onap.org +.. _`ONAP Wiki Page`: https://wiki.onap.org +.. _`ONAP Documentation`: https://docs.onap.org +.. _`ONAP Release Downloads`: https://git.onap.org +.. _`SDC ReadTheDocs`: https://docs.onap.org/projects/onap-sdc/en/latest/ +.. _`SDC Portal`: https://wiki.onap.org/display/DW/Service+Design+and+Creation+%28SDC%29+Portal |