aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorrameshiyer27 <ramesh.murugan.iyer@est.tech>2023-05-10 23:36:09 +0100
committerRamesh Murugan Iyer <ramesh.murugan.iyer@est.tech>2023-05-15 08:47:26 +0000
commitb4dd833cd396ee047eec4ba5c993c0a04f39ee44 (patch)
treec107b0e16d4c9669b0256ed05640f69a8df196b1
parentb2d95fd5aaf18abc3de63f4d431e697048112bf5 (diff)
Add documentation for ACM
ACM user guide HowTo: My first composition Executing ACM workflow ACM participant guide Issue-ID: POLICY-4587 Signed-off-by: zrrmmua <ramesh.murugan.iyer@est.tech> Change-Id: I864a9bd48e5deb19d1e55fa4d8ac7163ff27f49c
-rw-r--r--docs/clamp/acm/acm-participant-guide.rst126
-rw-r--r--docs/clamp/acm/acm-user-guide.rst296
-rw-r--r--docs/clamp/acm/files/AC-deploy.json3
-rw-r--r--docs/clamp/acm/files/AC-depriming.json3
-rw-r--r--docs/clamp/acm/files/AC-instantiation.json71
-rw-r--r--docs/clamp/acm/files/AC-priming.json3
-rw-r--r--docs/clamp/acm/files/AC-undeploy.json3
-rw-r--r--docs/clamp/acm/files/acm-datatypes.yaml58
-rw-r--r--docs/clamp/acm/files/acm-nodetemplates.yaml50
-rw-r--r--docs/clamp/acm/files/acm-nodetypes.yaml113
-rw-r--r--docs/clamp/acm/files/acm-tosca.yaml225
-rw-r--r--docs/clamp/clamp.rst4
12 files changed, 954 insertions, 1 deletions
diff --git a/docs/clamp/acm/acm-participant-guide.rst b/docs/clamp/acm/acm-participant-guide.rst
new file mode 100644
index 00000000..0b576d6f
--- /dev/null
+++ b/docs/clamp/acm/acm-participant-guide.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) Nordix Foundation. All rights reserved.
+
+.. _acm-participant-guide-label:
+
+Participant developer guide
+###########################
+
+.. contents::
+ :depth: 4
+
+The ACM runtime delegates the user requests to the participants for performing the actual operations.
+Hence the participant module in ACM is implemented adhering to a list of ACM protocols along with their own functional logic.
+It works in a contract with the Participant Intermediary module for communicating with ACM-R.
+This guide explains the design considerations for a new participant implementation in ACM.
+
+Please refer the following section for a detailed understanding of Inbound and outbound messages a participant interacts with.
+
+.. toctree::
+ :maxdepth: 2
+
+ design-impl/participants/participants
+
+Design considerations for a participant
+---------------------------------------
+
+In ONAP, the ACM-runtime and participant modules are implemented in Java spring boot. The participant Intermediary module
+which is added as a maven dependency to the participants has the default implementations available for listening the kafka
+events coming in from the ACM-runtime, process them and delegate them to the appropriate handler class. Similarly the
+Intermediary module also has the publisher class implementations for publishing events back from the participants to the ACM-runtime.
+
+Hence the new participants has to have this Participant Intermediary module as a dependency and should implement the following
+interfaces from the Participant Intermediary. It should also be provided with the following mandatory properties in order to make the participant
+work in synchronisation with ACM-runtime.
+
+The participant application should be provided with the following Intermediary parameter values in the application properties
+and the same is configured for the 'ParticipantIntermediaryParameters' object in the code.
+
+1. participantId - A unique participant UUID that is used by the runtime to identify the participant.
+2. ReportingTimeIntervalMs - Time inertval the participant should report the status/heartbeat to the runtime.
+3. clampAutomationCompositionTopics - This property takes in the kafka topic names and servers for the intermediary module to use.
+ These values should be provided for both source and sink configs. The following example shows the topic parameters set for using DMaap.
+
+.. code-block:: bash
+
+ clampAutomationCompositionTopics:
+ topicSources:
+ -
+ topic: POLICY-ACRUNTIME-PARTICIPANT
+ servers:
+ - ${topicServer:localhost}
+ topicCommInfrastructure: dmaap
+ fetchTimeout: 15000
+ topicSinks:
+ -
+ topic: POLICY-ACRUNTIME-PARTICIPANT
+ servers:
+ - ${topicServer:localhost}
+ topicCommInfrastructure: dmaap
+
+4. participantSupportedElementTypes - This property takes a list of typeName and typeVersion fields to define the types of AC elements the participant deals with.
+ These are user defined name and version and the same should be defined for the AC elements that are included in the TOSCA based AC definitions.
+
+.. code-block:: bash
+
+ participantSupportedElementTypes:
+ -
+ typeName: org.onap.policy.clamp.acm.PolicyAutomationCompositionElement
+ typeVersion: 1.0.0
+
+Interfaces to Implement
+-----------------------
+AutomationCompositionElementListener:
+ Every participant should implement a handler class that implements the AutomationCompositionElementListener interface
+ from the Participant Intermediary. The intermediary listener class listens for the incoming events from the ACM-runtime
+ and invoke the handler class implementations for various operations. This class implements the methods for deploying,
+ undeploying, locking, unlocking , getting UseState, getting OperationalState requests that are coming from the ACM-runtime.
+ The methods are as follows.
+
+.. code-block:: bash
+
+ 1. void undeploy(UUID automationCompositionId, UUID automationCompositionElementId) throws PfModelException;
+ 2. void deploy(UUID automationCompositionId, AcElementDeploy element, Map<String, Object> properties) throws PfModelException;
+ 3. default void lock(UUID automationCompositionId, UUID automationCompositionElementId) throws PfModelException;
+ 4. default void unlock(UUID automationCompositionId, UUID automationCompositionElementId) throws PfModelException;
+
+These method from the interface are implemented independently as per the user requirement. These methods after handling the
+appropriate requests should also invoke the intermediary's publisher apis to notify the ACM-runtime with the acknowledgement events.
+
+APIs to invoke
+--------------
+ParticipantIntermediaryApi:
+ The participant intermediary api has the following methods that can be invoked from the participant for the following purposes.
+ 1. The requested operations are completed in the handler class and the ACM-runtime needs to be notified.
+ 2. To register the participant with the ACM-runtime during the startup.
+
+ The methods are as follows:
+
+ This following method is invoked to register the handler class that is implemented specific to the participant.
+
+.. code-block:: bash
+
+ void registerAutomationCompositionElementListener(AutomationCompositionElementListener automationCompositionElementListener);
+
+This following method is invoked to update the AC element state after each operation is completed in the participant.
+
+.. code-block:: bash
+
+ void updateAutomationCompositionElementState(UUID automationCompositionId, UUID id, DeployState newState,LockState lockState);
+
+
+In ONAP, the following participants are already implemented in java spring boot for various requirements. The maven modules
+can be referred here
+
+ `HTTP participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-http>`_.
+ `Kubernetes participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-kubernetes>`_.
+ `Policy participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-policy>`_.
+ `A1PMS participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-a1pms>`_.
+ `Kserve participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-kserve>`_.
+
+
+
+
+
+
diff --git a/docs/clamp/acm/acm-user-guide.rst b/docs/clamp/acm/acm-user-guide.rst
new file mode 100644
index 00000000..56dc66b7
--- /dev/null
+++ b/docs/clamp/acm/acm-user-guide.rst
@@ -0,0 +1,296 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (c) Nordix Foundation. All rights reserved.
+
+.. _acm-user-guide-label:
+
+ACM user guide
+##############
+
+.. contents::
+ :depth: 4
+
+This guide helps the user to define their own composition definitions and explains the procedure to execute them via the
+Clamp Automation Composition Management Framework. This guide briefly talks about the commissioning, instantiation and
+deployment steps once the composition definitions are created.
+
+Defining a composition
+======================
+
+A composition can be created in yaml/json format as per the TOSCA standard. Please refer to the below section to understand
+the Tosca fundamental concepts and how an Automation Composition definition can be realised in the TOSCA.
+
+
+.. toctree::
+ :maxdepth: 2
+
+ defining-acms
+
+HowTo: My First Automation Composition
+======================================
+
+An example scenario is considered where we have a microservice that can be installed with a helm chart in kubernetes and
+configured via REST api to perform some operation.This functionality can be realised as a composition in Tosca standard.
+The various sections of the composition definition includes:
+
+Data Types:
+-----------
+The user can define their own data types to be used in the composition definition. In this use case, we are defining three data types as follows.
+
+onap.datatypes.ToscaConceptIdentifier:
+ This is a composite data type that holds two key value pairs in it. This type is used as an identifier for automation
+ element types and participant types.This holds two string properties "name" and "version" and hence this data type can
+ be used for creating the other composition element ids.
+
+onap.datatypes.clamp.acm.httpAutomationCompositionElement.RestRequest:
+ The rest api request for configuring the microservice can use the RestRequest datatype for defining the request in TOSCA.
+ This holds the string properties "httpMethod", "path", "body" and an integer property "expectedResponse" for defining
+ the rest request.
+
+ Note that the "restRequestId" property which is of type "onap.datatypes.ToscaConceptIdentifier" that was defined in the
+ previous step.
+
+onap.datatypes.clamp.acm.httpAutomationCompositionElement.ConfigurationEntity:
+ This data type holds a list of rest requests in case a microservice requires more than one rest request for configuration.
+ This holds the "configurationEntityId" which is of type "onap.datatypes.ToscaConceptIdentifier" and "restSequence" property
+ to hold the list of "onap.datatypes.clamp.acm.httpAutomationCompositionElement.RestRequest"
+
+
+.. literalinclude:: files/acm-datatypes.yaml
+ :language: yaml
+
+
+Node Types:
+-----------
+A Node Type is a reusable entity that defines the type of one or more Node Templates.
+An Interface Type is a reusable entity that describes a set of operations that can be used to interact with or manage a
+node or relationship in a TOSCA topology. The actual acm elements will be created under the Node templates deriving from
+these node types. We are going to define the following element types for ACM:
+
+org.onap.policy.clamp.acm.Participant:
+ This is a participant element type to define various participants in ACM. It holds the string property "provider".
+
+org.onap.policy.clamp.acm.AutomationCompositionElement:
+ This node type defines the primitive Automation composition element type that includes various common properties for all
+ the ACM elements.
+ Here we are defining various timeout properties and startPhase parameter that are common for all the AC elements.
+
+ Note: This node type value should not be changed as the ACM framework identifies the AC elements based on this type.
+
+org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement:
+ This node type is used to define AC elements that are associated with kubernetes operations. It is further derived from the
+ "org.onap.policy.clamp.acm.AutomationCompositionElement" type and hence supports its common properties and also includes
+ additional properties related to helm charts.
+ We are going to create kubernetes AC elements of this type, under the Node templates.
+
+org.onap.policy.clamp.acm.HttpAutomationCompositionElement:
+ Node type for AC elements associated with REST operations. It is derived from the "org.onap.policy.clamp.acm.AutomationCompositionElement"
+ type and hence supports its common properties and also supports additional properties for REST operation.
+ We are going to create a REST AC element of this type, under the Node templates.
+
+org.onap.policy.clamp.acm.AutomationComposition:
+ Primitive node type for defining Automation composition definitions that comprises one or more AC elements in it.
+ The AC definition of this type will be created under the Node templates.
+
+ Note: This node type value should not be changed as the ACM framework identifies the AC definitions based on this type.
+
+.. literalinclude:: files/acm-nodetypes.yaml
+ :language: yaml
+
+Node Templates:
+---------------
+A Node Template specifies the occurrence of a manageable software component as part of an application's topology model
+which is defined in a TOSCA Service Template. We create the actual participants and AC elements involved in this use case
+under the node templates.
+There are no element properties supplied at this point since it will be provided by the user during the instantiation.
+
+org.onap.k8s.acm.K8SAutomationCompositionParticipant:
+ A kubernetes participant element that processes the kubernetes AC elements in the composition.
+ This element is of node type "org.onap.policy.clamp.acm.Participant"
+
+onap.policy.clamp.ac.element.K8S_AutomationCompositionElement:
+ An AC element for kubernetes helm chart installation of the microservice derived from the node type
+ "org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement".
+ The common element properties are provided with values as part of commissioning the definition.
+
+org.onap.policy.clamp.acm.HttpParticipant:
+ A http participant element that processes the REST AC elements in the composition.
+ This element is of type "org.onap.policy.clamp.acm.Participant"
+
+onap.policy.clamp.ac.element.Http_AutomationCompositionElement:
+ An AC element for REST operation in the microservice derived from the node type
+ "org.onap.policy.clamp.acm.HttpAutomationCompositionElement".
+ The common element properties startPhase and timeout are provided with values as part of commissioning the definition.
+
+onap.policy.clamp.ac.element.AutomationCompositionDefinition:
+ The actual Automation Composition definition that comprises the list of AC elements mapped to it.
+ This element is of node type "org.onap.policy.clamp.acm.AutomationComposition"
+
+.. literalinclude:: files/acm-nodetemplates.yaml
+ :language: yaml
+
+Completed tosca template :download:`click here <files/acm-tosca.yaml>`
+
+Once the Tosca template definition is created, the ACM workflow can be executed to create and deploy the compositions.
+Please refer the following section for running ACM workflow.
+
+ACM workflow
+============
+
+ACM framework exposes REST interfaces for creating and deploying the user defined compositions. In this section, the
+TOSCA template created in the previous step can be commissioned, and then AC instances can be created and deployed for
+the same.
+
+This section assumes that the user has read about the ACM APIs and Protocols documentation and understands the ACM
+operations on a high level before proceeding with the workflow.
+
+
+Prerequisites:
+ - ACM components including acm-runtime, required participants (http and kubernetes in this case) and Dmaap/kafka clients are deployed in docker or kubernetes environment.
+ - Kubernetes and Helm are installed.
+ - Chartmuseum server is installed to host the acelement microservice helm chart. (`Procedure to install chartmuseum <https://wiki.onap.org/display/DW/Microk8s+and+helm+setup+in+Ubuntu>`_.)
+ - The helm chart for ACM test microservice is available in the policy/clamp repository that can be cloned locally and uploaded to the chartmuseum using helm push.(`AC element helm chart <https://github.com/onap/policy-clamp/tree/master/examples/src/main/resources/clamp/acm/acelement-helm>`_.)
+
+Please refer the `ACM swagger document <https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/openapi.yaml>`_. for REST API information for all the ACM operations.
+This section guides through the various steps involved in executing the ACM workflow for deploying the test microservice element.
+
+Commissioning the AC definition
+-------------------------------
+Commissioning refers to storing the composition definition on the ACM database. The created tosca template is posted as a request payload.
+
+.. code-block:: bash
+
+ Invoke a POST request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions'
+
+This returns a 202 response on the successful creation of the composition definition.
+
+Note:
+ The rest response returns the compositionId on a successful creation that requires to be used in the subsequent requests.
+
+Prime AC definitions
+--------------------
+Priming associates the AC elements with suitable participants and sends the corresponding AC element information to the participants.
+
+.. code-block:: bash
+
+ Invoke a PUT request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}'
+
+Request payload
+
+.. literalinclude:: files/AC-priming.json
+ :language: json
+
+This returns a 202 response on a successful priming.
+
+Instantiate AutomationComposition
+---------------------------------
+Instantiation refers to creating an AC instance on the database by initialising the element properties for each element in the composition.
+These values requires to be provided by the user as per their use case requirement. In this case, we are passing the helm chart information
+of the test microservice for the Ac element "onap.policy.clamp.ac.element.K8S_AutomationCompositionElement" which will be processed and installed
+by the kubernetes participant on a deployment request.
+
+Similarly the REST request data that are to be executed on the microservice will be passed on for the http AC element "onap.policy.clamp.ac.element.Http_AutomationCompositionElement"
+which will be executed by the http participant. Please refer to the properties of the elements in the json payload.
+
+Note:
+ In this scenario, the kubernetes element requires to be invoked first to install the helm chart and then the http element needs to be invoked to configure the microservice.
+ This is achieved by using the "startPhase" property on the AC element properties. The elements with the startPhase value defined are executed on a sequence starting from the least value to the higher value.
+ Each element in the request payload is assigned with a uniques UUID which will be automatically generated by the GUI in the upcoming releases.
+
+.. code-block:: bash
+
+ Invoke a POST request
+ 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances'
+
+The compositionId retrieved from the previous step should be updated in the request body. This returns a 201 response on a successful instantiation.
+This also returns the instanceId in the response that can be used in the subsequent requests.
+
+Request payload
+
+.. literalinclude:: files/AC-instantiation.json
+ :language: json
+
+Deploy AC instance
+------------------
+Once the AC instance is created, the user can deploy the instance which in turn activates the corresponding participants to execute the intended operations.
+In this case, the kubernetes participant will be installing the test microservice helm chart on the kubernetes cluster and the http participant will be
+executing the REST requests on the microservice endpoints.
+
+.. code-block:: bash
+
+ Invoke a PUT request
+ 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
+
+This returns a 202 response on a successful deploy order request. The elements will be in "DEPLOYING" state until the completion and then the state of
+the elements are updated to "DEPLOYED"
+The current status of the deployment can be fetched through the following endpoint.
+
+.. code-block:: bash
+
+ Invoke a GET request
+ 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
+
+Request payload
+
+.. literalinclude:: files/AC-deploy.json
+ :language: json
+
+Note:
+ The user can further implement the admin states 'LOCK' and 'UNLOCK' on the participants to further cascade the deployment operations.
+ If these states are implemented, then a subsequent request to LOCK and UNLOCK requires to be triggered following the deployment.
+
+Once all the AC elements are deployed, there should be a test microservice pod running on the kubernetes cluster which is
+configured to send events on the kafka by the http participant. This can be verified on the test microservice application logs.
+The AC instances can also be undeployed and deleted by the user.
+
+UnDeploy AutomationComposition
+------------------------------
+The AC instances can be undeployed from the system by the participants.
+
+.. code-block:: bash
+
+ Invoke a PUT request
+ 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
+
+This returns a 202 response on successful deploy order request.
+
+Request payload
+
+.. literalinclude:: files/AC-undeploy.json
+ :language: json
+
+Uninstantiate AC instance
+-------------------------
+This deletes the AC instance from the database including all the element properties that are initialised.
+
+.. code-block:: bash
+
+ Invoke a DELETE request
+ 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
+
+This returns 200 on successful deletion of the instance.
+
+Deprime Ac defintions
+---------------------
+Once the AC instance is deleted, it can be deprimed from the participants to be safely deleted from the database.
+
+.. code-block:: bash
+
+ Invoke a PUT request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}'
+
+This returns a 202 response on a successful operation.
+
+Request payload
+
+.. literalinclude:: files/AC-depriming.json
+ :language: json
+
+Delete AC defintion
+-------------------
+The AC definitions can be deleted if there are no instances are running and it is not primed to the participants.
+
+.. code-block:: bash
+
+ Invoke a DELETE request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}'
+
+This return a 200 response on a successful deletion operation. \ No newline at end of file
diff --git a/docs/clamp/acm/files/AC-deploy.json b/docs/clamp/acm/files/AC-deploy.json
new file mode 100644
index 00000000..cf65ba65
--- /dev/null
+++ b/docs/clamp/acm/files/AC-deploy.json
@@ -0,0 +1,3 @@
+{
+ "deployOrder": "DEPLOY"
+} \ No newline at end of file
diff --git a/docs/clamp/acm/files/AC-depriming.json b/docs/clamp/acm/files/AC-depriming.json
new file mode 100644
index 00000000..d2311b97
--- /dev/null
+++ b/docs/clamp/acm/files/AC-depriming.json
@@ -0,0 +1,3 @@
+{
+ "primeOrder": "DEPRIME"
+} \ No newline at end of file
diff --git a/docs/clamp/acm/files/AC-instantiation.json b/docs/clamp/acm/files/AC-instantiation.json
new file mode 100644
index 00000000..ebe1e8bb
--- /dev/null
+++ b/docs/clamp/acm/files/AC-instantiation.json
@@ -0,0 +1,71 @@
+{
+ "name": "DemoInstance0",
+ "version": "1.0.1",
+ "compositionId": "COMPOSITIONIDPLACEHOLDER",
+ "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_AutomationCompositionElement",
+ "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": "policy-chartmuseum",
+ "address": "http://policy-chartmuseum:8080"
+ },
+ "overrideParams": {
+ "acelement.elementId.name": "onap.policy.clamp.ac.starter",
+ "service.nodeport": 30800
+ }
+ }
+ }
+ }
+ "709c62b3-8918-41b9-a747-d21eb79c6c24": {
+ "id": "709c62b3-8918-41b9-a747-d21eb79c6c24",
+ "definition": {
+ "name": "onap.policy.clamp.ac.element.Http_AutomationCompositionElement",
+ "version": "1.2.3"
+ },
+ "description": "Starter Automation Composition Element for the Demo",
+ "properties": {
+ "baseUrl": "http://acm-starter-ac-element-impl:8084",
+ "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
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+ }
+} \ No newline at end of file
diff --git a/docs/clamp/acm/files/AC-priming.json b/docs/clamp/acm/files/AC-priming.json
new file mode 100644
index 00000000..76fafeca
--- /dev/null
+++ b/docs/clamp/acm/files/AC-priming.json
@@ -0,0 +1,3 @@
+{
+ "primeOrder": "PRIME"
+} \ No newline at end of file
diff --git a/docs/clamp/acm/files/AC-undeploy.json b/docs/clamp/acm/files/AC-undeploy.json
new file mode 100644
index 00000000..148bca11
--- /dev/null
+++ b/docs/clamp/acm/files/AC-undeploy.json
@@ -0,0 +1,3 @@
+{
+ "deployOrder": "UNDEPLOY"
+} \ No newline at end of file
diff --git a/docs/clamp/acm/files/acm-datatypes.yaml b/docs/clamp/acm/files/acm-datatypes.yaml
new file mode 100644
index 00000000..ff23fbf2
--- /dev/null
+++ b/docs/clamp/acm/files/acm-datatypes.yaml
@@ -0,0 +1,58 @@
+data_types:
+ onap.datatypes.ToscaConceptIdentifier:
+ derived_from: tosca.datatypes.Root
+ properties:
+ name:
+ type: string
+ required: true
+ version:
+ type: string
+ required: true
+
+ onap.datatypes.clamp.acm.httpAutomationCompositionElement.RestRequest:
+ version: 1.0.0
+ derived_from: tosca.datatypes.Root
+ properties:
+ restRequestId:
+ 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
+ description: The REST method to use
+ path:
+ type: string
+ required: true
+ description: The path of the REST request relative to the base URL
+ body:
+ type: string
+ required: false
+ description: The body of the REST request for PUT and POST requests
+ expectedResponse:
+ type: integer
+ required: true
+ constraints: []
+ description: THe expected HTTP status code for the REST request
+ onap.datatypes.clamp.acm.httpAutomationCompositionElement.ConfigurationEntity:
+ version: 1.0.0
+ derived_from: tosca.datatypes.Root
+ properties:
+ configurationEntityId:
+ type: onap.datatypes.ToscaConceptIdentifier
+ required: true
+ description:
+ The name and version of a Configuration Entity to be handled
+ by the HTTP Automation Composition Element
+ restSequence:
+ type: list
+ entry_schema:
+ type: onap.datatypes.clamp.acm.httpAutomationCompositionElement.RestRequest
+ type_version: 1.0.0
+ description: A sequence of REST commands to send to the REST endpoint \ No newline at end of file
diff --git a/docs/clamp/acm/files/acm-nodetemplates.yaml b/docs/clamp/acm/files/acm-nodetemplates.yaml
new file mode 100644
index 00000000..8e17a1e4
--- /dev/null
+++ b/docs/clamp/acm/files/acm-nodetemplates.yaml
@@ -0,0 +1,50 @@
+topology_template:
+ node_templates:
+ org.onap.k8s.acm.K8SAutomationCompositionParticipant:
+ version: 2.3.4
+ type: org.onap.policy.clamp.acm.Participant
+ type_version: 1.0.1
+ description: Participant for K8S
+ properties:
+ provider: ONAP
+ onap.policy.clamp.ac.element.K8S_AutomationCompositionElement:
+ # Helm chart parameters for the microservice
+ 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 AC Element Starter
+ properties:
+ provider: ONAP
+ startPhase: 0
+ uninitializedToPassiveTimeout: 300
+ podStatusCheckInterval: 30
+ org.onap.policy.clamp.acm.HttpParticipant:
+ version: 2.3.4
+ type: org.onap.policy.clamp.acm.Participant
+ type_version: 1.0.1
+ description: Participant for Http requests
+ properties:
+ provider: ONAP
+ onap.policy.clamp.ac.element.Http_AutomationCompositionElement:
+ # Http config for AC Element microservice.
+ version: 1.2.3
+ 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
+ uninitializedToPassiveTimeout: 300
+ startPhase: 1
+
+ onap.policy.clamp.ac.element.AutomationCompositionDefinition:
+ version: 1.2.3
+ type: org.onap.policy.clamp.acm.AutomationComposition
+ type_version: 1.0.1
+ description: Automation composition for Demo
+ properties:
+ provider: ONAP
+ elements:
+ - name: onap.policy.clamp.ac.element.K8S_AutomationCompositionElement
+ version: 1.2.3
+ - name: onap.policy.clamp.ac.element.Http_AutomationCompositionElement
+ version: 1.2.3
diff --git a/docs/clamp/acm/files/acm-nodetypes.yaml b/docs/clamp/acm/files/acm-nodetypes.yaml
new file mode 100644
index 00000000..0c9ed362
--- /dev/null
+++ b/docs/clamp/acm/files/acm-nodetypes.yaml
@@ -0,0 +1,113 @@
+node_types:
+ 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.acm.AutomationCompositionElement:
+ version: 1.0.1
+ derived_from: tosca.nodetypes.Root
+ properties:
+ provider:
+ type: string
+ required: false
+ metadata:
+ common: true
+ description: Specifies the organization that provides the automation composition element
+ startPhase:
+ type: integer
+ required: false
+ constraints:
+ - greater_or_equal: 0
+ metadata:
+ common: true
+ 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
+ required: false
+ constraints:
+ - greater_or_equal: 0
+ default: 60
+ metadata:
+ common: true
+ description: The maximum time in seconds to wait for a state chage from uninitialized to passive
+ passiveToRunningTimeout:
+ type: integer
+ required: false
+ constraints:
+ - greater_or_equal: 0
+ default: 60
+ metadata:
+ common: true
+ description: The maximum time in seconds to wait for a state chage from passive to running
+ runningToPassiveTimeout:
+ type: integer
+ required: false
+ constraints:
+ - greater_or_equal: 0
+ default: 60
+ metadata:
+ common: true
+ description: The maximum time in seconds to wait for a state chage from running to passive
+ passiveToUninitializedTimeout:
+ type: integer
+ required: false
+ constraints:
+ - greater_or_equal: 0
+ default: 60
+ metadata:
+ common: true
+ description: The maximum time in seconds to wait for a state chage from passive to uninitialized
+ org.onap.policy.clamp.acm.AutomationComposition:
+ version: 1.0.1
+ derived_from: tosca.nodetypes.Root
+ properties:
+ provider:
+ type: string
+ required: false
+ metadata:
+ common: true
+ description: Specifies the organization that provides the automation composition element
+ elements:
+ type: list
+ required: true
+ metadata:
+ common: true
+ entry_schema:
+ 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.0
+ derived_from: org.onap.policy.clamp.acm.AutomationCompositionElement
+ properties:
+ chart:
+ type: dictionary
+ required: true
+ description: This consumes the helm chart information in key value pairs.
+ org.onap.policy.clamp.acm.HttpAutomationCompositionElement:
+ version: 1.0.0
+ derived_from: org.onap.policy.clamp.acm.AutomationCompositionElement
+ properties:
+ baseUrl:
+ type: string
+ required: true
+ description: The base URL to be prepended to each path, identifies the host for the REST endpoints.
+ httpHeaders:
+ type: map
+ required: false
+ entry_schema:
+ type: string
+ description: HTTP headers to send on REST requests
+ configurationEntities:
+ type: map
+ required: true
+ entry_schema:
+ type: org.onap.datatypes.policy.clamp.acm.httpAutomationCompositionElement.ConfigurationEntity
+ type_version: 1.0.0
+ description: The connfiguration entities the Automation Composition Element is managing and their associated REST requests \ No newline at end of file
diff --git a/docs/clamp/acm/files/acm-tosca.yaml b/docs/clamp/acm/files/acm-tosca.yaml
new file mode 100644
index 00000000..714760a8
--- /dev/null
+++ b/docs/clamp/acm/files/acm-tosca.yaml
@@ -0,0 +1,225 @@
+tosca_definitions_version: tosca_simple_yaml_1_3
+data_types:
+ onap.datatypes.ToscaConceptIdentifier:
+ derived_from: tosca.datatypes.Root
+ properties:
+ name:
+ type: string
+ required: true
+ version:
+ type: string
+ required: true
+
+ onap.datatypes.clamp.acm.httpAutomationCompositionElement.RestRequest:
+ version: 1.0.0
+ derived_from: tosca.datatypes.Root
+ properties:
+ restRequestId:
+ 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
+ description: The REST method to use
+ path:
+ type: string
+ required: true
+ description: The path of the REST request relative to the base URL
+ body:
+ type: string
+ required: false
+ description: The body of the REST request for PUT and POST requests
+ expectedResponse:
+ type: integer
+ required: true
+ constraints: []
+ description: THe expected HTTP status code for the REST request
+ onap.datatypes.clamp.acm.httpAutomationCompositionElement.ConfigurationEntity:
+ version: 1.0.0
+ derived_from: tosca.datatypes.Root
+ properties:
+ configurationEntityId:
+ type: onap.datatypes.ToscaConceptIdentifier
+ required: true
+ description:
+ The name and version of a Configuration Entity to be handled
+ by the HTTP Automation Composition Element
+ restSequence:
+ type: list
+ entry_schema:
+ type: onap.datatypes.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.acm.Participant:
+ version: 1.0.1
+ derived_from: tosca.nodetypes.Root
+ properties:
+ provider:
+ type: string
+ required: false
+ org.onap.policy.clamp.acm.AutomationCompositionElement:
+ version: 1.0.1
+ derived_from: tosca.nodetypes.Root
+ properties:
+ provider:
+ type: string
+ required: false
+ metadata:
+ common: true
+ description: Specifies the organization that provides the automation composition element
+ startPhase:
+ type: integer
+ required: false
+ constraints:
+ - greater_or_equal: 0
+ metadata:
+ common: true
+ 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
+ required: false
+ constraints:
+ - greater_or_equal: 0
+ default: 60
+ metadata:
+ common: true
+ description: The maximum time in seconds to wait for a state chage from uninitialized to passive
+ passiveToRunningTimeout:
+ type: integer
+ required: false
+ constraints:
+ - greater_or_equal: 0
+ default: 60
+ metadata:
+ common: true
+ description: The maximum time in seconds to wait for a state chage from passive to running
+ runningToPassiveTimeout:
+ type: integer
+ required: false
+ constraints:
+ - greater_or_equal: 0
+ default: 60
+ metadata:
+ common: true
+ description: The maximum time in seconds to wait for a state chage from running to passive
+ passiveToUninitializedTimeout:
+ type: integer
+ required: false
+ constraints:
+ - greater_or_equal: 0
+ default: 60
+ metadata:
+ common: true
+ description: The maximum time in seconds to wait for a state chage from passive to uninitialized
+ org.onap.policy.clamp.acm.AutomationComposition:
+ version: 1.0.1
+ derived_from: tosca.nodetypes.Root
+ properties:
+ provider:
+ type: string
+ required: false
+ metadata:
+ common: true
+ description: Specifies the organization that provides the automation composition element
+ elements:
+ type: list
+ required: true
+ metadata:
+ common: true
+ entry_schema:
+ 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.0
+ derived_from: org.onap.policy.clamp.acm.AutomationCompositionElement
+ properties:
+ chart:
+ type: dictionary
+ required: true
+ description: This consumes the helm chart information in key value pairs.
+ org.onap.policy.clamp.acm.HttpAutomationCompositionElement:
+ version: 1.0.0
+ derived_from: org.onap.policy.clamp.acm.AutomationCompositionElement
+ properties:
+ baseUrl:
+ type: string
+ required: true
+ description: The base URL to be prepended to each path, identifies the host for the REST endpoints.
+ httpHeaders:
+ type: map
+ required: false
+ entry_schema:
+ type: string
+ description: HTTP headers to send on REST requests
+ configurationEntities:
+ type: map
+ required: true
+ entry_schema:
+ type: org.onap.datatypes.policy.clamp.acm.httpAutomationCompositionElement.ConfigurationEntity
+ type_version: 1.0.0
+ description: The connfiguration entities the Automation Composition Element is managing and their associated REST requests
+
+topology_template:
+ node_templates:
+ org.onap.k8s.acm.K8SAutomationCompositionParticipant:
+ version: 2.3.4
+ type: org.onap.policy.clamp.acm.Participant
+ type_version: 1.0.1
+ description: Participant for K8S
+ properties:
+ provider: ONAP
+ org.onap.policy.clamp.ac.element.K8S_AutomationCompositionElement:
+ # Helm chart parameters for the microservice
+ 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 AC Element Starter
+ properties:
+ provider: ONAP
+ startPhase: 0
+ uninitializedToPassiveTimeout: 300
+ podStatusCheckInterval: 30
+ org.onap.policy.clamp.acm.HttpParticipant:
+ version: 2.3.4
+ type: org.onap.policy.clamp.acm.Participant
+ type_version: 1.0.1
+ description: Participant for Http requests
+ properties:
+ provider: ONAP
+ onap.policy.clamp.ac.element.Http_AutomationCompositionElement:
+ # Http config for AC Element microservice.
+ version: 1.2.3
+ 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
+ uninitializedToPassiveTimeout: 300
+ startPhase: 1
+
+ onap.policy.clamp.acm.AutomationCompositionElement:
+ version: 1.2.3
+ type: org.onap.policy.clamp.acm.AutomationComposition
+ type_version: 1.0.1
+ description: Automation composition for Demo
+ properties:
+ provider: ONAP
+ elements:
+ - name: onap.policy.clamp.ac.element.K8S_AutomationCompositionElement
+ version: 1.2.3
+ - name: onap.policy.clamp.ac.element.Http_AutomationCompositionElement
+ version: 1.2.3 \ No newline at end of file
diff --git a/docs/clamp/clamp.rst b/docs/clamp/clamp.rst
index 40ab6790..0f051155 100644
--- a/docs/clamp/clamp.rst
+++ b/docs/clamp/clamp.rst
@@ -16,10 +16,12 @@ described in TOSCA.
acm/defining-acms
acm/api-protocol/api-protocol-tree
acm/design-impl/design-impl
+ acm/acm-user-guide
+ acm/acm-participant-guide
.. note::
Policy/CLAMP was merged into the Policy Framework in the Honolulu release of ONAP. Prior to that release, it was
- a separate project. The release notes for CLAMP when it existed as a separate proejct are located below.
+ a separate project. The release notes for CLAMP when it existed as a separate project are located below.
.. toctree::
:maxdepth: 1