.. THIS IS USED INTERNALLY IN POLICY ONLY
.. _api-label:
+Policy Life Cycle API
+#####################
+
1. Policy Life Cycle API
-########################
+========================
1.1 Overview
------------
2. APIs exposed
-###############
+===============
2.1 Global API Table
--------------------
-Below is a global API table from where swagger JSON for different types of policy design API can be downloaded.
+Below you can download the swagger YAML for Policy Framework Lifecycle API.
+You can find *Tosca Node Template Design* and *Policy Design* operations.
.. csv-table::
- :header: "API name", "Swagger JSON"
+ :header: "API name", "Swagger YAML"
:widths: 10,5
- "Healthcheck API", ":download:`link <swagger/healthcheck-api.json>`"
- "Statistics API", ":download:`link <swagger/statistics-api.json>`"
- "Tosca Policy Type API", ":download:`link <swagger/policytype-api.json>`"
- "Tosca Policy API", ":download:`link <swagger/policy-api.json>`"
- "Tosca NodeTemplate API", ":download:`link <swagger/nodetemplates-api.json>`"
+ "Policy Framework Lifecycle API", ":download:`link <https://raw.githubusercontent.com/onap/policy-api/master/main/src/main/resources/openapi/openapi.yaml>`"
2.2 API Swagger
---------------
x-onap-requestid is used to track REST transactions for logging purpose, as described above.
-.. swaggerv2doc:: swagger/healthcheck-api.json
-
-.. swaggerv2doc:: swagger/statistics-api.json
-.. swaggerv2doc:: swagger/policytype-api.json
+.. csv-table::
+ :header: "SWAGGER"
+ :widths: 10
-.. swaggerv2doc:: swagger/policy-api.json
+ `To view the full SWAGGER click here <./local-swagger.html>`_
+
+.. note::
+ Note that the context-path is not present in the document, because it is in the `application.yaml <https://github.com/onap/policy-api/blob/master/main/src/main/resources/application.yaml>`_
+ So the final url is composed by:
+
+ .. csv-table::
+ :header: "Scheme","Host","Context-Path","Path"
+ :widths: 3,3,3,3
+
+ "http","://<IP>:<PORT>","/policy/api/v1/","healthcheck"
2.3 Creating MetadataSet for policy
"apex.decisionmaker.policy", `apex.policy.decisionmaker.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/apex.policy.decisionmaker.input.tosca.yaml>`_
-The following node template Apis are introduced to handle the policy metadataSets as independent entities that can be later mapped to a tosca policy during policy creation.
-
-.. swaggerv2doc:: swagger/nodetemplates-api.json
+`The node template Apis <./local-swagger.html#tag/Tosca-Node-Template-Design>`_
+are introduced to handle the policy metadataSets as independent entities that can be later mapped to a tosca policy during policy creation.
When making a POST policy API call, the client must not only provide well-formed JSON/YAML,
but also must conform to the TOSCA specification. For example. the "type" field for a TOSCA
3. Policy API application configuration
-#######################################
+=======================================
Starting from Jakarta Release policy-api is a Springboot based microservice.
-The policy-api application configuration is packaged as a K8S ConfigMap object via `Policy-API OOM charts <https://gerrit.onap.org/r/gitweb?p=oom.git;a=blob;f=kubernetes/policy/components/policy-api/resources/config/apiParameters.yaml;h=c08b035d53f299fe0e08b45bd95a760283acce66;hb=refs/heads/master>`_
+The policy-api application configuration is packaged as a K8S ConfigMap object via `Policy-API OOM charts <https://raw.githubusercontent.com/onap/oom/master/kubernetes/policy/components/policy-api/resources/config/apiParameters.yaml>`_
referential integrity. On delete requests, a check is made to ensure that no Automation
Composition Instances exist for the Automation Composition Type to be deleted.
-.. swaggerv2doc:: swagger/acm-comissioning.json
+.. csv-table::
+ :header: "Commissioning API"
+ :widths: 10
+
+ `ACM-R Commissioning Swagger <./local-swagger.html#tag/Automation-Composition-Definition>`_
Instantiation API
here: :ref:`4.1 Management of Automation Composition Instance Configurations
<management-acm-instance-configs>`.
-.. swaggerv2doc:: swagger/acm-instantiation.json
+.. csv-table::
+ :header: "Instantiation API"
+ :widths: 10
+
+ `ACM-R Instantiation Swagger <./local-swagger.html#tag/Automation-Composition-Instance>`_
Instantiation Automation Composition Instance Lifecycle Management
can be retrieved. In addition, the quantity of statistical information to be returned can be
scoped.
-.. swaggerv2doc:: swagger/acm-monitoring.json
+.. csv-table::
+ :header: "Monitoring API"
+ :widths: 10
+
+ `ACM-R Monitoring Swagger <./local-swagger.html#tag/Participant-Monitoring>`_
+
Pass Through API
================
participant can be used to configure the microservice over its REST interface.Of course,
the HTTP participant works towards any REST service, it is not restricted to REST
services started by participants.
-
+Supported message Broker are DMaap and Strimzi-Kafka.
.. image:: ../../images/participants/http-participant.png
participant is running two HTTP Automation Composition Elements, one for Automation Composition A and one for
Automation Composition B.
-Configuring a Automation Composition Element on the HTTP participant for a Automation Composition
--------------------------------------------------------------------------------------------------
+Supported Element Types
+-----------------------
+Supported Element Types for Http participant will be used to define the HTTP participant Element Definition Types in tosca template.
+Participant Supported Element Types is defined in Http participant application.yaml.
+
+.. code-block:: YAML
+
+ participantSupportedElementTypes:
+ -
+ typeName: org.onap.policy.clamp.acm.HttpAutomationCompositionElement
+ typeVersion: 1.0.0
+
+
+Configuring an Automation Composition Definition and Instance for the HTTP participant
+--------------------------------------------------------------------------------------
A *Configuration Entity* describes a concept that is managed by the HTTP participant. A
Configuration Entity can be created, Read, Updated, and Deleted (CRUD). The user defines
the Configuration Entities that it wants its HTTP Automation Composition Element to manage and
provides a sequence of parameterized REST commands to Create, Read, Update, and Delete
each Configuration Entity.
-Sample tosca template defining a http participant and a automation composition element for a automation composition. :download:`click here <tosca/tosca-http-participant.yml>`
+Sample tosca template defining a http participant and a AC element definition. :download:`click here <tosca/tosca-http-participant.yml>`
-The user configures the following properties in the TOSCA for the HTTP participant:
+The user defines the following properties in the TOSCA for the HTTP participant:
.. list-table::
:widths: 15 10 50
- HttpStatus
- The expected HTTP response code fo the REST request
+Sample Automation Composition instances.
+In that example the user fills the properties defined in the TOSCA for the HTTP participant :download:`click here <tosca/automation-composition-http.yml>`
+
Http participant Interactions:
------------------------------
-The http participant interacts with Automation Composition Runtime on the northbound via DMaap. It interacts with any microservice on the southbound over http for configuration.
+The http participant interacts with Automation Composition Runtime on the northbound via Message Broker. It interacts with any microservice on the southbound over http for configuration.
-The communication for the Automation Composition updates and state change requests are sent from the Automation Composition Runtime to the participant via DMaap.
+The communication for the Automation Composition updates and state change requests are sent from the Automation Composition Runtime to the participant via Message Broker.
The participant invokes the appropriate http endpoint of the microservice based on the received messages from the Automation Composition Runtime.
Http participant Workflow:
--------------------------
-Once the participant is started, it sends a "REGISTER" event to the DMaap topic which is then consumed by the Automation Composition Runtime to register this participant on the runtime database.
-The user can commission the tosca definitions from the Policy Gui to the Automation Composition Runtime that further updates the participant with these definitions via DMaap.
-Once the automation composition definitions are available in the runtime database, the Automation Composition can be instantiated with the default state "UNINITIALISED" from the Policy Gui.
+Once the participant is started, it sends a "REGISTER" event to the Message Broker topic which is then consumed by the Automation Composition Runtime to register this participant on the runtime database.
+The user can commission the tosca definitions from the Policy Gui to the Automation Composition Runtime.
+Once the automation composition definitions are available in the runtime database the user can prime them and further updates the participant with these definitions via Message Broker.
+After primed, the Automation Composition can be instantiated with the default state "UNDEPLOYED" from the Policy Gui.
-When the state of the Automation Composition is changed from "UNINITIALISED" to "PASSIVE" from the Policy Gui, the http participant receives the automation composition state change event from the runtime and
+When the state of the Automation Composition is changed from "UNDEPLOYED" to "DEPLOYED" from the Policy Gui, the http participant receives the automation composition state change event from the runtime and
configures the microservice of the corresponding Automation Composition Element over http.
The configuration entity for a microservice is associated with each Automation Composition Element for the http participant.
The http participant holds the executed http requests information along with the responses received.
The participant is used in a generic way to configure any entity over http and it does not hold the information about the microservice to unconfigure/revert the configurations when the
-state of Automation Composition changes from "PASSIVE" to "UNINITIALISED".
+state of Automation Composition changes from "DEPLOYED" to "UNDEPLOYED".
that are configured on the helm client. The participant acts as a wrapper around the helm client and creates the required
resources in the k8s cluster.
+Supported message Broker are DMaap and Strimzi-Kafka.
+
The kubernetes participant also exposes REST endpoints for onboarding, installing and uninstalling of helm charts from the
local chart database which facilitates the user to also use this component as a standalone application for helm operations.
-In Kohn version, the kubernetes participant supports the following methods of installation of helm charts.
+By Kohn version, the kubernetes participant supports the following methods of installation of helm charts.
- Installation of helm charts from configured helm repositories and remote repositories passed via TOSCA in CLAMP.
Note:
- - If the kubernetes participant is deployed outside the cluster , the config file of the k8s cluster needs to be copied to the `./kube` folder of kubernetes participant's home directory to make the participant work with the external cluster.
+ - If the kubernetes participant is deployed outside the cluster, the config file of the k8s cluster needs to be copied to the `./kube` folder of kubernetes participant's home directory to make the participant work with the external cluster.
- If the participant needs additional permission to create resources on the cluster, cluster-admin role binding can be created for the service account of the participant with the below command.
.. image:: ../../images/participants/k8s-participant.png
+Supported Element Types
+-----------------------
+Supported Element Types for Kubernetes participant will be used to define the Kubernetes participant Element Definition Types in tosca template.
+Participant Supported Element Types is defined in Kubernetes participant application.yaml.
+
+.. code-block:: YAML
+
+ participantSupportedElementTypes:
+ -
+ typeName: org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement
+ typeVersion: 1.0.0
+
Defining a TOSCA CL definition for kubernetes participant:
----------------------------------------------------------
A *chart* parameter map describes the helm chart parameters in tosca template for a microservice that is used by the kubernetes participant for the deployment.
A Automation Composition element in TOSCA is mapped to the kubernetes participant and also holds the helm chart parameters for a microservice defined under the properties of the Automation Composition Element.
-Sample tosca template defining a participant and a automation composition element for a automation composition. :download:`click here <tosca/tosca-k8s-participant.yml>`
+Sample tosca template defining a participant and a AC element definition. :download:`click here <tosca/tosca-k8s-participant.yml>`
Configuring a Automation Composition Element on the kubernetes participant for a Automation Composition
-------------------------------------------------------------------------------------------------------
-The user configures the following properties in the TOSCA template for the kubernetes participant:
+The user defines the following properties in the TOSCA template for the kubernetes participant:
.. list-table::
:widths: 15 10 50
- String
- The password to login the helm repository
+Sample Automation Composition instances.
+In that example the user fills the properties defined in the TOSCA for the Kubernetes participant :download:`click here <tosca/automation-composition-k8s.yml>`
Kubernetes participant Interactions:
------------------------------------
-The kubernetes participant interacts with Automation Composition Runtime on the northbound via DMaap. It interacts with the helm client on the southbound for performing various helm operations to the k8s cluster.
+The kubernetes participant interacts with Automation Composition Runtime on the northbound via Message Broker. It interacts with the helm client on the southbound for performing various helm operations to the k8s cluster.
-The communication for the Automation Composition updates and state change requests are sent from the Automation Composition Runtime to the participant via DMaap.
+The communication for the Automation Composition updates and state change requests are sent from the Automation Composition Runtime to the participant via Message Broker.
The participant performs appropriate operations on the k8s cluster via helm client based on the received messages from the Automation Composition Runtime.
kubernetes participant Workflow:
--------------------------------
-Once the participant is started, it sends a "REGISTER" event to the DMaap topic which is then consumed by the Automation Composition Runtime to register this participant on the runtime database.
-The user can commission the tosca definitions from the Policy Gui to the Automation Composition Runtime that further updates the participant with these definitions via DMaap.
-Once the automation composition definitions are available in the runtime database, the Automation Composition can be instantiated with the default state "UNINITIALISED" from the Policy Gui.
+Once the participant is started, it sends a "REGISTER" event to the Message Broker topic which is then consumed by the Automation Composition Runtime to register this participant on the runtime database.
+The user can commission the tosca definitions from the Policy Gui to the Automation Composition Runtime.
+Once the automation composition definitions are available in the runtime database, the user can prime them and further updates the participant with these definitions via Message Broker.
+After primed, the Automation Composition can be instantiated with the default state "UNDEPLOYED" from the Policy Gui.
-When the state of the Automation Composition is changed from "UNINITIALISED" to "PASSIVE" from the Policy Gui, the kubernetes participant receives the automation composition state change event from the runtime and
+When the state of the Automation Composition is changed from "UNDEPLOYED" to "DEPLOYED" from the Policy Gui, the kubernetes participant receives the automation composition state change event from the runtime and
deploys the helm charts associated with each Automation Composition Elements by creating appropriate namespace on the cluster.
If the repository of the helm chart is not passed via TOSCA, the participant looks for the helm chart in the configured helm repositories of helm client.
The participant also monitors the deployed pods for the configured time until the pods comes to RUNNING state.
It holds the deployment information of the pods including the current status of the pods after the deployment.
-When the state of the Automation Composition is changed from "PASSIVE" to "UNINITIALISED" back, the participant also undeploys the helm charts from the cluster that are part of the Automation Composition Element.
+When the state of the Automation Composition is changed from "DEPLOYED" to "UNDEPLOYED" back, the participant also undeploys the helm charts from the cluster that are part of the Automation Composition Element.
--- /dev/null
+name: DemoInstance0
+version: 1.0.1
+compositionId: {{compositionId}}
+description: Demo automation composition instance 0
+elements:
+
+ 709c62b3-8918-41b9-a747-d21eb79c6c24:
+ id: 709c62b3-8918-41b9-a747-d21eb79c6c24
+ definition:
+ name: onap.policy.clamp.ac.element.Http_StarterAutomationCompositionElement
+ version: 1.2.3
+ description: Starter Automation Composition Element for the Demo
+ properties:
+ baseUrl: http://cluster-ip:30800
+ httpHeaders:
+ Content-Type: application/json
+ Authorization: Basic YWNtVXNlcjp6YiFYenRHMzQ=
+ configurationEntities:
+ - configurationEntityId:
+ name: onap.policy.clamp.ac.starter
+ version: 1.0.0
+ restSequence:
+ - restRequestId:
+ name: request1
+ version: 1.0.1
+ httpMethod: POST
+ path: /onap/policy/clamp/acelement/v2/activate
+ body: '{ "receiverId": { "name": "onap.policy.clamp.ac.startertobridge", "version": "1.0.0" }, "timerMs": 20000, "elementType": "STARTER", "topicParameterGroup": { "server": "message-router:3904", "listenerTopic": "POLICY_UPDATE_MSG", "publisherTopic": "AC_ELEMENT_MSG", "fetchTimeout": 15000, "topicCommInfrastructure": "dmaap" } }'
+ expectedResponse: 201
--- /dev/null
+name: DemoInstance0
+version: 1.0.1
+compositionId: {{compositionId}}
+description: Demo automation composition instance 0
+elements:
+
+ 709c62b3-8918-41b9-a747-d21eb79c6c21:
+ id: 709c62b3-8918-41b9-a747-d21eb79c6c21
+ definition:
+ name: onap.policy.clamp.ac.element.K8S_StarterAutomationCompositionElement
+ version: 1.2.3
+ description: Starter Automation Composition Element for the Demo
+ properties:
+ chart:
+ chartId:
+ name: acelement
+ version: 0.1.0
+ namespace: default
+ releaseName: acm-starter
+ podName: acm-starter
+ repository:
+ repoName: chartmuseum
+ address: 'http://cluster-ip:8080'
+ overrideParams:
+ acelement.elementId.name: onap.policy.clamp.ac.starter
+ service.nodeport: 30800
version:
type: string
required: true
- onap.datatype.controlloop.Target:
- derived_from: tosca.datatypes.Root
- description: Definition for a entity in A&AI to perform a control loop operation on
- properties:
- targetType:
- type: string
- description: Category for the target type
- required: true
- constraints:
- - valid_values:
- - VNF
- - VM
- - VFMODULE
- - PNF
- entityIds:
- type: map
- description: |
- Map of values that identify the resource. If none are provided, it is assumed that the
- entity that generated the ONSET event will be the target.
- required: false
- metadata:
- clamp_possible_values: ClampExecution:CSAR_RESOURCES
- entry_schema:
- type: string
- onap.datatype.controlloop.Actor:
- derived_from: tosca.datatypes.Root
- description: An actor/operation/target definition
- properties:
- actor:
- type: string
- description: The actor performing the operation.
- required: true
- metadata:
- clamp_possible_values: Dictionary:DefaultActors,ClampExecution:CDS/actor
- operation:
- type: string
- description: The operation the actor is performing.
- metadata:
- clamp_possible_values: Dictionary:DefaultOperations,ClampExecution:CDS/operation
- required: true
- target:
- type: onap.datatype.controlloop.Target
- description: The resource the operation should be performed on.
- required: true
- payload:
- type: map
- description: Name/value pairs of payload information passed by Policy to the actor
- required: false
- metadata:
- clamp_possible_values: ClampExecution:CDS/payload
- entry_schema:
- type: string
- onap.datatype.controlloop.Operation:
- derived_from: tosca.datatypes.Root
- description: An operation supported by an actor
- properties:
- id:
- type: string
- description: Unique identifier for the operation
- required: true
- description:
- type: string
- description: A user-friendly description of the intent for the operation
- required: false
- operation:
- type: onap.datatype.controlloop.Actor
- description: The definition of the operation to be performed.
- required: true
- timeout:
- type: integer
- description: The amount of time for the actor to perform the operation.
- required: true
- retries:
- type: integer
- description: The number of retries the actor should attempt to perform the operation.
- required: true
- default: 0
- success:
- type: string
- description: Points to the operation to invoke on success. A value of "final_success" indicates and end to the operation.
- required: false
- default: final_success
- failure:
- type: string
- description: Points to the operation to invoke on Actor operation failure.
- required: false
- default: final_failure
- failure_timeout:
- type: string
- description: Points to the operation to invoke when the time out for the operation occurs.
- required: false
- default: final_failure_timeout
- failure_retries:
- type: string
- description: Points to the operation to invoke when the current operation has exceeded its max retries.
- required: false
- default: final_failure_retries
- failure_exception:
- type: string
- description: Points to the operation to invoke when the current operation causes an exception.
- required: false
- default: final_failure_exception
- failure_guard:
- type: string
- description: Points to the operation to invoke when the current operation is blocked due to guard policy enforcement.
- required: false
- default: final_failure_guard
- org.onap.datatypes.policy.clamp.controlloop.httpControlLoopElement.RestRequest:
+
+ org.onap.datatypes.policy.clamp.acm.httpAutomationCompositionElement.RestRequest:
version: 1.0.0
derived_from: tosca.datatypes.Root
properties:
restRequestId:
- type: onap.datatypes.ToscaConceptIdentifier
- type_version: 0.0.0
+ type: onap.datatypes.ToscaConceptIdentifier
required: true
description: The name and version of a REST request to be sent to a REST endpoint
httpMethod:
type: string
required: true
constraints:
- - valid_values: [POST, PUT, GET, DELETE]
+ - valid_values:
+ - POST
+ - PUT
+ - GET
+ - DELETE
description: The REST method to use
path:
type: string
expectedResponse:
type: integer
required: true
- constraints:
- - in_range: [100, 599]
+ constraints: []
description: THe expected HTTP status code for the REST request
- org.onap.datatypes.policy.clamp.controlloop.httpControlLoopElement.ConfigurationEntity:
+ org.onap.datatypes.policy.clamp.acm.httpAutomationCompositionElement.ConfigurationEntity:
version: 1.0.0
derived_from: tosca.datatypes.Root
properties:
configurationEntityId:
- type: onap.datatypes.ToscaConceptIdentifier
- type_version: 0.0.0
+ type: onap.datatypes.ToscaConceptIdentifier
required: true
- description: The name and version of a Configuration Entity to be handled by the HTTP Control Loop Element
+ description: The name and version of a Configuration Entity to be handled
+ by the HTTP Automation Composition Element
restSequence:
type: list
entry_schema:
- type: org.onap.datatypes.policy.clamp.controlloop.httpControlLoopElement.RestRequest
+ type: org.onap.datatypes.policy.clamp.acm.httpAutomationCompositionElement.RestRequest
type_version: 1.0.0
description: A sequence of REST commands to send to the REST endpoint
+
node_types:
- org.onap.policy.clamp.controlloop.Participant:
+ org.onap.policy.clamp.acm.Participant:
version: 1.0.1
derived_from: tosca.nodetypes.Root
properties:
provider:
type: string
required: false
- org.onap.policy.clamp.controlloop.ControlLoopElement:
+ org.onap.policy.clamp.acm.AutomationCompositionElement:
version: 1.0.1
derived_from: tosca.nodetypes.Root
properties:
required: false
metadata:
common: true
- description: Specifies the organization that provides the control loop element
- participant_id:
- type: onap.datatypes.ToscaConceptIdentifier
- required: true
- metadata:
- common: true
- participantType:
- type: onap.datatypes.ToscaConceptIdentifier
- required: true
- metadata:
- common: true
- description: The identity of the participant type that hosts this type of Control Loop Element
+ description: Specifies the organization that provides the automation composition element
startPhase:
type: integer
required: false
- greater_or_equal: 0
metadata:
common: true
- description: A value indicating the start phase in which this control loop element will be started, the
- first start phase is zero. Control Loop Elements are started in their start_phase order and stopped
- in reverse start phase order. Control Loop Elements with the same start phase are started and
+ description: A value indicating the start phase in which this automation composition element will be started, the
+ first start phase is zero. Automation Composition Elements are started in their start_phase order and stopped
+ in reverse start phase order. Automation Composition Elements with the same start phase are started and
stopped simultaneously
uninitializedToPassiveTimeout:
type: integer
metadata:
common: true
description: The maximum time in seconds to wait for a state chage from passive to uninitialized
- org.onap.policy.clamp.controlloop.ControlLoop:
+ org.onap.policy.clamp.acm.AutomationComposition:
version: 1.0.1
derived_from: tosca.nodetypes.Root
properties:
required: false
metadata:
common: true
- description: Specifies the organization that provides the control loop element
+ description: Specifies the organization that provides the automation composition element
elements:
type: list
required: true
common: true
entry_schema:
type: onap.datatypes.ToscaConceptIdentifier
- description: Specifies a list of control loop element definitions that make up this control loop definition
- org.onap.policy.clamp.controlloop.HttpControlLoopElement:
- version: 1.0.1
- derived_from: org.onap.policy.clamp.controlloop.ControlLoopElement
+ description: Specifies a list of automation composition element definitions that make up this automation composition definition
+ org.onap.policy.clamp.acm.HttpAutomationCompositionElement:
+ version: 1.0.0
+ derived_from: org.onap.policy.clamp.acm.AutomationCompositionElement
properties:
baseUrl:
type: string
type: map
required: true
entry_schema:
- type: org.onap.datatypes.policy.clamp.controlloop.httpControlLoopElement.ConfigurationEntity
+ type: org.onap.datatypes.policy.clamp.acm.httpAutomationCompositionElement.ConfigurationEntity
type_version: 1.0.0
- description: The connfiguration entities the Control Loop Element is managing and their associated REST requests
+ description: The connfiguration entities the Automation Composition Element is managing and their associated REST requests
topology_template:
node_templates:
- org.onap.controlloop.HttpControlLoopParticipant:
+ org.onap.policy.clamp.acm.HttpParticipant:
version: 2.3.4
- type: org.onap.policy.clamp.controlloop.Participant
+ type: org.onap.policy.clamp.acm.Participant
type_version: 1.0.1
description: Participant for Http requests
properties:
provider: ONAP
- org.onap.domain.database.Http_PMSHMicroserviceControlLoopElement:
- # Consul http config for PMSH.
+ onap.policy.clamp.ac.element.Http_StarterAutomationCompositionElement:
+ # Http config for AC Element Starter.
version: 1.2.3
- type: org.onap.policy.clamp.controlloop.HttpControlLoopElement
- type_version: 1.0.1
- description: Control loop element for the http requests of PMSH microservice
+ type: org.onap.policy.clamp.acm.HttpAutomationCompositionElement
+ type_version: 1.0.0
+ description: Automation composition element for the http requests of AC Element Starter microservice
properties:
provider: ONAP
- participant_id:
- name: HttpParticipant0
- version: 1.0.0
- participantType:
- name: org.onap.k8s.controlloop.HttpControlLoopParticipant
- version: 2.3.4
- uninitializedToPassiveTimeout: 180
- baseUrl: http://consul-server-ui:8500
- httpHeaders:
- Content-Type: application/json
- configurationEntities:
- - configurationEntityId:
- name: entity1
- version: 1.0.1
- restSequence:
- - restRequestId:
- name: request1
- version: 1.0.1
- httpMethod: PUT
- path: v1/kv/dcae-pmsh2
- body: '{
- "control_loop_name":"pmsh-control-loop",
- "operational_policy_name":"pmsh-operational-policy",
- "aaf_password":"demo123456!",
- "aaf_identity":"dcae@dcae.onap.org",
- "cert_path":"/opt/app/pmsh/etc/certs/cert.pem",
- "key_path":"/opt/app/pmsh/etc/certs/key.pem",
- "ca_cert_path":"/opt/app/pmsh/etc/certs/cacert.pem",
- "enable_tls":"true",
- "pmsh_policy":{
- "subscription":{
- "subscriptionName":"ExtraPM-All-gNB-R2B",
- "administrativeState":"UNLOCKED",
- "fileBasedGP":15,
- "fileLocation":"\/pm\/pm.xml",
- "nfFilter":{
- "nfNames":[
- "^pnf.*",
- "^vnf.*"
- ],
- "modelInvariantIDs":[
- ],
- "modelVersionIDs":[
- ],
- "modelNames":[
- ]
- },
- "measurementGroups":[
- {
- "measurementGroup":{
- "measurementTypes":[
- {
- "measurementType":"countera"
- },
- {
- "measurementType":"counterb"
- }
- ],
- "managedObjectDNsBasic":[
- {
- "DN":"dna"
- },
- {
- "DN":"dnb"
- }
- ]
- }
- },
- {
- "measurementGroup":{
- "measurementTypes":[
- {
- "measurementType":"counterc"
- },
- {
- "measurementType":"counterd"
- }
- ],
- "managedObjectDNsBasic":[
- {
- "DN":"dnc"
- },
- {
- "DN":"dnd"
- }
- ]
- }
- }
- ]
- }
- },
- "streams_subscribes":{
- "aai_subscriber":{
- "type":"message_router",
- "dmaap_info":{
- "topic_url":"https://10.152.183.151:3905/events/AAI_EVENT",
- "client_role":"org.onap.dcae.aaiSub",
- "location":"san-francisco",
- "client_id":"1575976809466"
- }
- },
- "policy_pm_subscriber":{
- "type":"message_router",
- "dmaap_info":{
- "topic_url":"https://10.152.183.151:3905/events/org.onap.dmaap.mr.PM_SUBSCRIPTIONS",
- "client_role":"org.onap.dcae.pmSubscriber",
- "location":"san-francisco",
- "client_id":"1575876809456"
- }
- }
- },
- "streams_publishes":{
- "policy_pm_publisher":{
- "type":"message_router",
- "dmaap_info":{
- "topic_url":"https://10.152.183.151:3905/events/org.onap.dmaap.mr.PM_SUBSCRIPTIONS",
- "client_role":"org.onap.dcae.pmPublisher",
- "location":"san-francisco",
- "client_id":"1475976809466"
- }
- },
- "other_publisher":{
- "type":"message_router",
- "dmaap_info":{
- "topic_url":"https://10.152.183.151:3905/events/org.onap.dmaap.mr.SOME_OTHER_TOPIC",
- "client_role":"org.onap.dcae.pmControlPub",
- "location":"san-francisco",
- "client_id":"1875976809466"
- }
- }
- }
- }'
- expectedResponse: 200
- org.onap.domain.sample.GenericK8s_ControlLoopDefinition:
+ uninitializedToPassiveTimeout: 300
+ startPhase: 1
+
+ onap.policy.clamp.ac.element.AutomationCompositionDefinition:
version: 1.2.3
- type: org.onap.policy.clamp.controlloop.ControlLoop
- type_version: 1.0.0
- description: Control loop for Hello World
+ type: org.onap.policy.clamp.acm.AutomationComposition
+ type_version: 1.0.1
+ description: Automation composition for Demo
properties:
provider: ONAP
elements:
- - name: org.onap.domain.database.Http_PMSHMicroserviceControlLoopElement
+ - name: onap.policy.clamp.ac.element.Http_StarterAutomationCompositionElement
version: 1.2.3
version:
type: string
required: true
- onap.datatype.acm.Target:
- derived_from: tosca.datatypes.Root
- description: Definition for a entity in A&AI to perform a automation composition operation on
- properties:
- targetType:
- type: string
- description: Category for the target type
- required: true
- constraints:
- - valid_values:
- - VNF
- - VM
- - VFMODULE
- - PNF
- entityIds:
- type: map
- description: |
- Map of values that identify the resource. If none are provided, it is assumed that the
- entity that generated the ONSET event will be the target.
- required: false
- metadata:
- clamp_possible_values: ClampExecution:CSAR_RESOURCES
- entry_schema:
- type: string
- onap.datatype.acm.Actor:
- derived_from: tosca.datatypes.Root
- description: An actor/operation/target definition
- properties:
- actor:
- type: string
- description: The actor performing the operation.
- required: true
- metadata:
- clamp_possible_values: Dictionary:DefaultActors,ClampExecution:CDS/actor
- operation:
- type: string
- description: The operation the actor is performing.
- metadata:
- clamp_possible_values: Dictionary:DefaultOperations,ClampExecution:CDS/operation
- required: true
- target:
- type: onap.datatype.acm.Target
- description: The resource the operation should be performed on.
- required: true
- payload:
- type: map
- description: Name/value pairs of payload information passed by Policy to the actor
- required: false
- metadata:
- clamp_possible_values: ClampExecution:CDS/payload
- entry_schema:
- type: string
- onap.datatype.acm.Operation:
- derived_from: tosca.datatypes.Root
- description: An operation supported by an actor
- properties:
- id:
- type: string
- description: Unique identifier for the operation
- required: true
- description:
- type: string
- description: A user-friendly description of the intent for the operation
- required: false
- operation:
- type: onap.datatype.acm.Actor
- description: The definition of the operation to be performed.
- required: true
- timeout:
- type: integer
- description: The amount of time for the actor to perform the operation.
- required: true
- retries:
- type: integer
- description: The number of retries the actor should attempt to perform the operation.
- required: true
- default: 0
- success:
- type: string
- description: Points to the operation to invoke on success. A value of "final_success" indicates and end to the operation.
- required: false
- default: final_success
- failure:
- type: string
- description: Points to the operation to invoke on Actor operation failure.
- required: false
- default: final_failure
- failure_timeout:
- type: string
- description: Points to the operation to invoke when the time out for the operation occurs.
- required: false
- default: final_failure_timeout
- failure_retries:
- type: string
- description: Points to the operation to invoke when the current operation has exceeded its max retries.
- required: false
- default: final_failure_retries
- failure_exception:
- type: string
- description: Points to the operation to invoke when the current operation causes an exception.
- required: false
- default: final_failure_exception
- failure_guard:
- type: string
- description: Points to the operation to invoke when the current operation is blocked due to guard policy enforcement.
- required: false
- default: final_failure_guard
+
node_types:
org.onap.policy.clamp.acm.Participant:
version: 1.0.1
metadata:
common: true
description: Specifies the organization that provides the automation composition element
- participant_id:
- type: onap.datatypes.ToscaConceptIdentifier
- required: true
- metadata:
- common: true
- participantType:
- type: onap.datatypes.ToscaConceptIdentifier
- required: true
- metadata:
- common: true
- description: The identity of the participant type that hosts this type of automation composition Element
startPhase:
type: integer
required: false
type: onap.datatypes.ToscaConceptIdentifier
description: Specifies a list of automation composition element definitions that make up this automation composition definition
org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement:
- version: 1.0.1
+ version: 1.0.0
derived_from: org.onap.policy.clamp.acm.AutomationCompositionElement
properties:
chart:
description: Participant for K8S
properties:
provider: ONAP
- org.onap.domain.database.PMSH_K8SMicroserviceAutomationCompositionElement:
- # Chart from new repository
+ onap.policy.clamp.ac.element.K8S_StarterAutomationCompositionElement:
+ # Chart from any chart repository configured on helm client.
version: 1.2.3
type: org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement
type_version: 1.0.0
- description: Automation composition element for the K8S microservice for PMSH
+ description: Automation composition element for the K8S microservice for AC Element Starter
properties:
provider: ONAP
- participant_id:
- name: K8sParticipant0
- version: 1.0.0
- participantType:
- name: org.onap.k8s.acm.K8SAutomationCompositionParticipant
- version: 2.3.4
- chart:
- chartId:
- name: dcae-pmsh
- version: 8.0.0
- namespace: onap
- releaseName: pmshms
- repository:
- repoName: chartmuseum
- protocol: http
- address: chart-museum
- port: 80
- userName: onapinitializer
- password: demo123456!
- overrideParams:
- global.masterPassword: test
+ startPhase: 0
+ uninitializedToPassiveTimeout: 300
+ podStatusCheckInterval: 30
- org.onap.domain.database.Local_K8SMicroserviceAutomationCompositionElement:
- # Chart installation without passing repository info
- version: 1.2.3
- type: org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement
- type_version: 1.0.0
- description: Automation composition element for the K8S microservice for local chart
- properties:
- provider: ONAP
- participant_id:
- name: K8sParticipant0
- version: 1.0.0
- participantType:
- name: org.onap.k8s.acm.K8SAutomationCompositionParticipant
- version: 2.3.4
- chart:
- chartId:
- name: nginx-ingress
- version: 0.9.1
- releaseName: nginxms
- namespace: test
- org.onap.domain.sample.GenericK8s_AutomationCompositionDefinition:
+ onap.policy.clamp.ac.element.AutomationCompositionDefinition:
version: 1.2.3
type: org.onap.policy.clamp.acm.AutomationComposition
- type_version: 1.0.0
- description: Automation composition for Hello World
+ type_version: 1.0.1
+ description: Automation composition for Demo
properties:
provider: ONAP
elements:
- - name: org.onap.domain.database.PMSH_K8SMicroserviceAutomationCompositionElement
- version: 1.2.3
- - name: org.onap.domain.database.Local_K8SMicroserviceAutomationCompositionElement
+ - name: onap.policy.clamp.ac.element.K8S_StarterAutomationCompositionElement
version: 1.2.3
'sphinxcontrib.seqdiag',
'sphinxcontrib.swaggerdoc',
'sphinxcontrib.plantuml',
- 'sphinx_toolbox.collapse'
+ 'sphinx_toolbox.collapse',
+ 'sphinxcontrib.redoc'
+]
+
+redoc = [
+ {
+ 'name': 'Policy API',
+ 'page': 'api/local-swagger',
+ 'spec': 'https://raw.githubusercontent.com/onap/policy-api/master/main/src/main/resources/openapi/openapi.yaml',
+ 'opts': {
+ 'lazy-rendering': True,
+ 'suppress-warnings': True,
+ 'hide-hostname': True,
+ }
+ },
+ {
+ 'name': 'Policy PAP',
+ 'page': 'pap/local-swagger',
+ 'spec': 'https://raw.githubusercontent.com/onap/policy-pap/master/main/src/main/resources/openapi/openapi.yaml',
+ 'opts': {
+ 'lazy-rendering': False,
+ 'suppress-warnings': True,
+ 'hide-hostname': True,
+ }
+ },
+ {
+ 'name': 'Policy XACML',
+ 'page': 'xacml/local-swagger',
+ 'spec': 'https://raw.githubusercontent.com/onap/policy-xacml-pdp/master/main/src/main/resources/openapi/openapi.yaml',
+ 'opts': {
+ 'lazy-rendering': False,
+ 'suppress-warnings': True,
+ 'hide-hostname': True,
+ }
+ },
+ {
+ 'name': 'Policy ACM-R',
+ 'page': 'clamp/acm/api-protocol/local-swagger',
+ 'spec': 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/openapi.yaml',
+ 'opts': {
+ 'lazy-rendering': False,
+ 'suppress-warnings': True,
+ 'hide-hostname': True,
+ }
+ },
]
#
app.add_css_file("css/ribbon.css")
linkcheck_ignore = [
- r'http://localhost:\d+/'
+ r'http://localhost:\d+/',
+ r'./local-swagger.html(.*?)'
]
.. Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
+.. _docker-label:
Policy Docker Usage
--------------------------
api/api
pap/pap
xacml/decision-api
+ clamp/acm/api-protocol/acm-rest-apis
Postman Environment for API Testing
-----------------------------------
The following environment file from postman can be used for testing API's. All you need to do is fill in the IP and Port information for the installation that you have created.
-:download:`link <PolicyAPI.postman_environment.json>`
+:download:`Postman Environment <PolicyAPI.postman_environment.json>`
+
+.. note::
+ If you are testing on a Docker Installation use *http* as **protocol**, *localhost* as **IP**,
+ and the values set in the `export-ports.sh <https://raw.githubusercontent.com/onap/policy-docker/master/compose/export-ports.sh>`_ as **PORT**.
+ More information in: :ref:`Docker Installation <docker-label>`
Postman Collection for API Testing
----------------------------------
Postman collection for `Policy Framework Decision API <https://github.com/onap/policy-xacml-pdp/blob/master/postman/decision-api-collection.json>`_
-API Swagger Generation
-----------------------
+API Swagger
+-----------
The standard for API definition in the RESTful API world is the OpenAPI Specification (OAS). The OAS, which is based on
the original "Swagger Specification," is being widely used in API developments.
-Execute the below curl command for swagger generation by filling in the authorization details, IP and Port information:
+OAS 3.0 is used to describe the API contracts, and those documents are added as a source artifacts.
+
+`Swagger Specification for Policy API <https://github.com/onap/policy-api/blob/master/main/src/main/resources/openapi/openapi.yaml>`_
+
+`Swagger Specification for Policy PAP <https://github.com/onap/policy-pap/blob/master/main/src/main/resources/openapi/openapi.yaml>`_
+
+`Swagger Specification for Policy XACML-PDP <https://github.com/onap/policy-xacml-pdp/blob/master/main/src/main/resources/openapi/openapi.yaml>`_
+
+`Swagger Specification for Policy ACM-R <https://github.com/onap/policy-clamp/blob/master/runtime-acm/src/main/resources/openapi/openapi.yaml>`_
+
+`Swagger Specification for Policy DROOLS-PDP <https://github.com/onap/policy-drools-pdp/blob/master/feature-healthcheck/src/main/resources/openapi/openapi.yaml>`_
+
-.. code-block:: bash
+The YAML document can be imported in an web editor such as `Editor Swagger <https://editor.swagger.io/>`_
- “curl -k --user ‘{user_id}:{password}’ https://{ip}:{port}/swagger.json”
+An "OpenApi first" approach is adopted, so starting from the Swagger document we auto-generate interfaces that are implemented in the API controllers.
+.. note::
+ The Swagger document can still be extracted from the code in the API that uses *Spring-Doc* dependency at the endpoint "../v3/api-docs/"
+ For Example ACM-Runtime endpoint
+
+ ``http://<IP>:<PORT>/onap/policy/clamp/acm/v3/api-docs``
.. _pap-label:
-Policy Administration Point (PAP) Architecture
-##############################################
+Policy Administration Point API
+###############################
.. contents::
:depth: 3
.. toctree::
InternalPapPdp.rst
+Policy Administration Point (PAP) Architecture
+==============================================
+
The Policy Administration Point (PAP) keeps track of PDPs, supporting the deployment of PDP groups and the deployment
of policies across those PDP groups. Policies are created using the Policy API, but are deployed via the PAP.
"x-patchversion", "0", "PATCH version of the API"
"x-onap-requestid", "e1763e61-9eef-4911-b952-1be1edd9812b", "described above; used for logging purposes"
-:download:`Download Health Check PAP API Swagger <swagger/health-check-pap.json>`
+.. csv-table::
+ :header: "/healthcheck"
+ :widths: 10
-.. swaggerv2doc:: swagger/health-check-pap.json
+ `Health Check PAP Swagger <./local-swagger.html#tag/HealthCheckRestControllerV1>`_
This operation performs a health check on the PAP.
.. literalinclude:: response/health-check-pap-resp.json
:language: json
-:download:`Download Consolidated Health Check PAP API Swagger <swagger/consolidated-healthcheck-pap.json>`
+.. csv-table::
+ :header: "/pdps/healthcheck"
+ :widths: 10
-.. swaggerv2doc:: swagger/consolidated-healthcheck-pap.json
+ `Consolidated Health Check PAP Swagger <./local-swagger.html#tag/PolicyComponentsHealthCheckControllerV1>`_
This operation performs a health check of all policy components. The response
contains the health check result of each component. The consolidated health check
.. literalinclude:: response/consolidated-healthcheck-pap-resp.json
:language: json
-:download:`Download Statistics PAP API Swagger <swagger/statistics-pap.json>`
+.. csv-table::
+ :header: "/statistics"
+ :widths: 10
-.. swaggerv2doc:: swagger/statistics-pap.json
+ `Statistics PAP Swagger <./local-swagger.html#tag/StatisticsRestControllerV1>`_
This operation allows statistics for PDP groups, PDP subgroups, and individual PDPs to be retrieved.
.. literalinclude:: response/statistics-pap-resp.json
:language: json
-:download:`Download State Change PAP Swagger <swagger/state-change-pap.json>`
+.. csv-table::
+ :header: "/pdps/groups/{name}"
+ :widths: 10
-.. swaggerv2doc:: swagger/state-change-pap.json
+ `PDP State Change PAP Swagger <./local-swagger.html#tag/PdpGroupStateChangeControllerV1>`_
The state of PDP groups is managed by this operation. PDP groups can be in states PASSIVE, TEST, SAFE, or ACTIVE. For a full
description of PDP group states, see the :ref:`ONAP Policy Framework Architecture <architecture-label>` page.
-:download:`Download Group Batch PAP API Swagger <swagger/groups-batch-pap.json>`
+.. csv-table::
+ :header: "/pdps/groups/batch"
+ :widths: 10
-.. swaggerv2doc:: swagger/groups-batch-pap.json
+ `Group Batch PAP Swagger <./local-swagger.html#tag/PdpGroupCreateOrUpdateControllerV1>`_
This operation allows the PDP groups and subgroups to be created and updated. Many PDP groups can be created or updated
in a single POST operation by specifying more than one PDP group in the POST operation body.
.. literalinclude:: request/groups-batch-pap-req.json
:language: json
-:download:`Download Group Delete PAP API Swagger <swagger/group-delete-pap.json>`
+.. csv-table::
+ :header: "/pdps/groups/{name}"
+ :widths: 10
-.. swaggerv2doc:: swagger/group-delete-pap.json
+ `PdpGroup Delete PAP Swagger <./local-swagger.html#tag/PdpGroupDeleteControllerV1>`_
The API also allows PDP groups to be deleted. DELETE operations are only permitted on PDP groups in PASSIVE state.
-:download:`Download Group Query PAP API Swagger <swagger/group-query-pap.json>`
+.. csv-table::
+ :header: "/pdps"
+ :widths: 10
-.. swaggerv2doc:: swagger/group-query-pap.json
+ `PdpGroup Query PAP Swagger <./local-swagger.html#tag/PdpGroupQueryControllerV1>`_
This operation allows the PDP groups and subgroups to be listed as well as the policies that are deployed on each PDP
group and subgroup.
.. literalinclude:: response/group-query-pap-resp.json
:language: json
-:download:`Download Deployments Batch PAP API Swagger <swagger/deployments-batch-pap.json>`
+.. csv-table::
+ :header: "/pdps/deployments/batch"
+ :widths: 10
-.. swaggerv2doc:: swagger/deployments-batch-pap.json
+ `Deployments Update PAP Swagger <./local-swagger.html#tag/PdpGroupDeployControllerV1>`_
This operation allows policies to be deployed on specific PDP groups.
Each subgroup includes an "action" property, which is used to indicate
.. literalinclude:: response/deployment-pap-resp.json
:language: json
-:download:`Download Deploy PAP API Swagger <swagger/policy-deploy-pap.json>`
+.. csv-table::
+ :header: "/pdps/policies"
+ :widths: 10
-.. swaggerv2doc:: swagger/policy-deploy-pap.json
+ `Deploy PAP Swagger <./local-swagger.html#operation/deployPolicies>`_
This operation allows policies to be deployed across all relevant PDP groups.
PAP will deploy the specified policies to all relevant subgroups. Only the
.. literalinclude:: response/deployment-pap-resp.json
:language: json
-:download:`Download Undeploy PAP API Swagger <swagger/policy-undeploy-pap.json>`
+.. csv-table::
+ :header: "/pdps/policies/{name}"
+ :widths: 10
-.. swaggerv2doc:: swagger/policy-undeploy-pap.json
+ `Undeploy PAP Swagger <./local-swagger.html#operation/deletePolicy>`_
This operation allows policies to be undeployed from PDP groups.
.. literalinclude:: response/deployment-pap-resp.json
:language: json
-:download:`Download Policy Status PAP API Swagger <swagger/policy-status-pap.json>`
+.. csv-table::
+ :header: "/policies/status"
+ :widths: 10
+
+ `All Policy Status PAP Swagger <./local-swagger.html#operation/getStatusOfAllPolicies>`_
-.. swaggerv2doc:: swagger/policy-status-pap.json
This operation allows the status of all policies that are deployed or undeployed to be listed together.
The result can be filtered based on pdp group name, policy name & version.
.. literalinclude:: response/policy-status-pap-resp.json
:language: json
-:download:`Download Deployed Policy PAP API Swagger <swagger/deployed-policy-pap.json>`
+.. csv-table::
+ :header: "/policies/deployed"
+ :widths: 10
-.. swaggerv2doc:: swagger/deployed-policy-pap.json
+ `Deployed Policy Status PAP Swagger <./local-swagger.html#operation/queryAllDeployedPolicies>`_
This operation allows the deployed policies to be listed together with their respective deployment status.
The result can be filtered based on policy name & version.
.. literalinclude:: response/deployed-policy-pap-resp.json
:language: json
-:download:`Download PDP Statistics PAP API Swagger <swagger/pdp-statistics-pap.json>`
+.. csv-table::
+ :header: "/pdps/statistics"
+ :widths: 10
-.. swaggerv2doc:: swagger/pdp-statistics-pap.json
+ `Policy Statistics PAP Swagger <./local-swagger.html#tag/StatisticsRestControllerV1>`_
This operation allows the PDP statistics to be retrieved for all registered PDPs.
The result can be filtered based on PDP group, PDP subgroup & PDP instance.
.. literalinclude:: response/pdp-statistics-pap-resp.json
:language: json
-:download:`Download Policy Audit PAP API Swagger <swagger/policy-audit-pap.json>`
+.. csv-table::
+ :header: "/policies/audit"
+ :widths: 10
-.. swaggerv2doc:: swagger/policy-audit-pap.json
+ `Policy Status PAP Swagger <./local-swagger.html#tag/PolicyAuditControllerV1>`_
This operation allows the audit records of policies to be listed together.
The result can be filtered based on pdp group name, policy name & version.
sphinxcontrib-spelling
sphinxcontrib-plantuml
sphinx_toolbox
+sphinxcontrib-redoc
x-onap-requestid is used to track REST transactions for logging purpose, as described above.
-:download:`Download the Decision API Swagger <swagger.json>`
+.. csv-table::
+ :header: "Swagger"
+ :widths: 10
-.. swaggerv2doc:: swagger.json
+ `Decision API Swagger <./local-swagger.html>`_
End of Document
Code Review / policy / parent.git / commitdiff