Versions Compared

Old Version 42

changes.mady.by.user Vijay Venkatesh Kumar

Saved on

compared with

New Version Current

changes.mady.by.user Vijay Venkatesh Kumar

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Typically DCAE sub-components are developed individually under their own ONAP Gerrit/Git repos.  The initiation of a new repo generally starts during the release planning time, which usually starts around the code freeze time of the previous ONAP release.  Normally before the functionality freeze time (M2), projects that are planned to be included in a release are determined, and infrastructure items such as repo creation for new projects are completed.

Pre-requisites

...

For community members looking to contribute new service under ONAP DCAE project, below steps outline general steps to be followed by the service owners.

    • Review new service proposal with architecture team and project team. If new collectors, this typically requires review with ARC and VNFREQ team as this introduces new interface between xNF and DCAE.
    • Identify usecase this service will be targeted under (optional).
    • Capture external and internal dependencies and api consumed/provided .(this could be documented in wiki to start, but swagger spec required by M2)
    • Repository creation (PTL will submit request to RM, who will coordinate with TSC/LF support)
    • Work with PTL to scope the service and EPIC/US creations and release/sprints to target around M1
    • Push seed code (if available) into gerrit
      • Reference this ONAP WiKi page for details of configuring for using Gerrit: Configuring Gerrit.
    • Build/enhance functional component (mS) based on the usecase requirement
      • Setup Jenkins job 

Contribution Guidelines

  1. Setup required Jenkins job (under ci-management repo) for building artifacts/docker images

...

  1. , sonar-scans, CLM. As a DCAE contributor, to create new Jenkins job will require a new JJB file being created under the jjb/dcaegen2 directory of the ci-managerment project.

...

  1. The status of Jenkins jobs can be viewed at http://jenkins.onap.org.
  2. Push (seed) code into gerrit on the chosen repo (Reference this ONAP WiKi page for details of configuring for using Gerrit: Configuring Gerrit)
    1. Ensure complaince with all NFR's (Non-Functionrequirement)
    2. Leverage DCAE common sdk for config retrieval/dmaap pub & sub etc (DCAESDKIntegration)
    3. License text included in each file.  Apache 2 for coding files; CC4 for others.

...

  2. Ensure all committers and usecase owners/leads are looped into gerrit submission for review
  3. Once change is merged, review CLM/coverty scan report and address all CRITICAL/HIGH License/security issues identified

...

  1. (TSC MUST HAVE)
    1. Reports will be under https://nexus-iq.wl.linuxfoundation.org/assets/index.html  (access is restricted; work with committers to obtain the report)
  2. ONAP Deployment Integration
  3. DCAE MOD integration support (OPTIONAL from KOHN) 
    1. Every component to be onboarded into DCAE, should prepare a component spec (a.k.a spec) - which is meta data represented in json describing the component configuration model. The spec file should be added into component repo (under <repo><component>/dpo/spec directory).  For more info on component spec, refer documentation under RTD
  4. Add

...

  1. CSIT test (How to guide → Creating a CSIT Test). This can be done under "integration" repo or within component repo itself (see dcaegen2/services/pm-mapper or dcaegen2/collectors/datafile)
  2. Documentation
  3. Demo

Non-

...

Functional requirement

All new contribution MUST be complaint with Global requirements and approved "best Practice" requirements. Following list key NFR's

Note:

...

All above are common ONAP requirements for any new contributions.

...

Once the service code is delivered and container can be built, follow below DCAE Platform Integration steps

  • DCAE Platform Integration
  • Documentation
  • Demo
  • Deployment integration.

DCAE Platform Integration

Once the main functionality is build and components is executable as docker container/jar - it should be integrated with DCAE platform to enable dynamic instantiation and configuration management by DCAE controller.  

Build component spec (Design support)

Every component to be onboarded into DCAE, should prepare a component spec (a.k.a spec) - which is meta data represented in json describing the component configuration model. Details on spec creation and validation can be found under ONAP.readthedocs (corresponding source in gerrit)

MOD Integration (Design support)

For Frankurt, MicroService and Onboarding (MOD) is being introduced in DCAE. All DCAE mS will require to be onboarded through MOD. The pre-requisite for onboarding will similar as before i.e MS owner should create component_spec and policy_model if any required.

Note: For Guilin release MOD onboarding is optional. If the component is deployed independently, blueprint can be generated manually or using the bp-gen tool (described in next step)

Blueprint creation/test (Deployment support)

If the component are onboarded via MOD flow, the blueprints will be generated during distribution from MOD and loaded into DCAE Inventory. Once the blueprint is available inventory, components can be deployed using Dashboard UI.

Alternatively the components developer can hand-craft the blueprints or use bp-gen tool to generate the cloudify blueprint for deployment based on the spec file. This blueprint can be used for testing and integration.

All Components identified part of release must have their blueprints added into dcaegen2/platform/blueprint repository. DCAE-Bootstrap container build will include the available blueprint and load them into DCAE-inventory during deployment. Once the blueprints are available in inventory, the deployment can be triggered via Robot suite, CLAMP or DCAE-Dashboard. 

ConfigBindingService Integration (Code enhancement required)

All configuration (identified in component spec - parameters) itself are stored under CONSUL when blueprint gets executed part of component deployment. Some configuration such as topics are dynamic and may not be known for component owner to include in the docker image. Hence an important requirement for all onboarding services is to invoke the configbindingservice api during docker init script process to fetch the required application config.

DCAE has SDK/libraries which can be used for service components for easy integration.

Java Library  

Python Modules

However if library is not suite, then application can consume the ConfigBindingService API directly

Note: Using SDC libraries is recommended as any fixes or enhancement will only require version bump

Notification mechanism (Code enhancement required)

Note: If MS has ability to periodically poll CBS api's and check for updates - support for notification mechanism is optional.

When there are configuration changes (triggered via policy/clamp), the platform will fetch the configuration and store them in consul. The platform will also notify the services indicating there is new configuration (slide below indicates the flow involved)

Image Removed

To support this interface, the service component should include a script within the container and specify that in component spec

Component spec

"auxilary": {
    "policy": {
        "trigger_type": "docker",
        "script_path": "/opt/app/reconfigure.sh"
    }
}

The corresponding blueprint should include following

      docker_config:
        policy:
          script_path: /opt/app/mean/reconfigure.sh
          trigger_type: docker

This script must have necessary logic to invoke CBS API and cascade the information for application processing. For components not expecting dynamic changes, this step is optional.

S3P Support (Code enhancement required)

S3P (all scaling/resiliency/security/maintainability) goals should meet at the minimum level defined for DCAE project for the targeted release 

If the component is stateful, it should persist its state on external store (eg. pg, redis) to allow support for scaling and resiliency. This should be important design criteria for the component.  If the component fails to meet S3P goals, it will not be release candidate. And if the components either publish/subscribe into DMAAP topic, then secure connection to DMAAP must be supported (platform will provide aaf_username/aaf_password for each topic as configuration).

License Requirements

...

  1. The Copyright line for contributing organization inserted or updated reflecting the contribution year.

...

  1. For Java and Python code, coverage reporting: http://sonar.onap.org.
  2. For other languages, coverage reporting done in language native method.

TSC MUST HAVE are required for passing release candidate.



ONAP Deployment Integration

All ONAP component deployments are through helm-charts maintained under OOM repository; refer to https://docs.onap.org/projects/onap-dcaegen2/en/latest/sections/installation_oom.html for OOM/dcae chart structure.

New DCAE Microservice chart contribution should go under https://git.onap.org/oom/tree/kubernetes/dcaegen2-services; all DCAE component charts should leverage oom/kubernetes/dcaegen2-services/common/dcaegen2-services-common templates.  Refer to following link - https://docs.onap.org/projects/onap-dcaegen2/en/latest/sections/dcaeservice_helm_template.html for details on the supported features via this template.

     With Kohn release, all DCAE components will be enabled for daily/weekly deployments. This is controlled by override here - https://git.onap.org/oom/tree/kubernetes/onap/resources/overrides/onap-all.yaml. New components being added under ONAP, should update this yaml for enabling automated daily/weekly deployment. 


DCAE SDK Integration

With Jakarta release, Consul and ConfigBindingService interface has been deprecated from DCAE. All Microservice configuration are resolved through files mounted via Configmap created part of dcae-services helm chart deployment. CBS SDK library are available within DCAE which can be used by DCAE Microservices for configuration retrieval. For details on the API - refer CBS SDK Java Library . 

Corresponding CBS library available also for python components - Python Modules 

Additional DACE SDK/libraries is also available for DMAAP interface; for more info refer Java Library  

Its strongly recommended to use DCAE SDK library for consistency across DCAE services

...


Documentation

DCAE WIKI

 The project wiki space (https://wiki.onap.org/display/DW/DCAE+Documentation) can be used to documents general design about the components itself; can serve the community to know about the component itself and point to other repo/release documentation. 

...

All DCAE components release specific documentation are maintained as source under dcaegen2 repository.  his repo has documentation build setup and generated RTD under ONAP-RTD

Service component related RST can be added under separate directory under dcaegen2 repository. Post merge/build - corresponding RTD will be located under DCAE-Service component page of ONAP-RTD 

See Resource at the bottom for more information on RTD.

...

To be able to certify the component for release, the MS owner should present demo to project team (and integration team) using onap Jenkins build images/container and manual deployment via blueprint under DCAE platform. This demo should be ideally completed around M4 deadline to meet release timeline.

Demo Guidelines

    • Each demo should is expected to be under ~20 <20 min + ~5 with ~5 min Q&A
    • Demo scope to include following
          1. Specify Info on ONAP deployment dependencies/pre-requisite and how to validate them (can be explained from links under - DCAE R4 Service Component (On-demand) deployment Instruction)requisite 
          2. Walkthrough component blueprint/input files and Helm-charts configuration
          3. Deployment Demo (though Cloudify/clihelm)
          4. Deployment Validation (health check/logs)
          5. Functional Flow simulation (using scripts/curl for mocking up feed)
          6. Corresponding validation (logs and/or dmaap)
          7. Documentation references
    Common Q&A
    • Planned/Future Updates
        • List
    • of
        • Features/stories/bugs (with JIRA's) deferred
    • for
        • to next release
  • Complaint with ONAP Logging guidelines/CBS integration?
    • Can multiple instance be run in-parallel (for scaling)? Any external dependency for persistence?

Resources

JJB - https://wiki.onap.org/display/DW/Using+Standard+Jenkins+Job+%28JJB%29+Templates

CSIT  - Creating a CSIT Test

Documentation - 2017-09-19 Documentation Tutorial, Further information regarding documentation can also be found here:  http://onap.readthedocs.io/en/latest/index.html.

DCAE JIRA - https://jira.onap.org/secure/RapidBoard.jspa?rapidView=49&view=planning.nodetail