diff options
Diffstat (limited to 'docs/sections/configuration.rst')
| -rw-r--r-- | docs/sections/configuration.rst | 126 |
1 files changed, 126 insertions, 0 deletions
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()); |