diff options
| -rw-r--r-- | docs/clamp/acm/acm-participant-guide.rst | 126 | ||||
| -rw-r--r-- | docs/clamp/acm/acm-user-guide.rst | 296 | ||||
| -rw-r--r-- | docs/clamp/acm/files/AC-deploy.json | 3 | ||||
| -rw-r--r-- | docs/clamp/acm/files/AC-depriming.json | 3 | ||||
| -rw-r--r-- | docs/clamp/acm/files/AC-instantiation.json | 71 | ||||
| -rw-r--r-- | docs/clamp/acm/files/AC-priming.json | 3 | ||||
| -rw-r--r-- | docs/clamp/acm/files/AC-undeploy.json | 3 | ||||
| -rw-r--r-- | docs/clamp/acm/files/acm-datatypes.yaml | 58 | ||||
| -rw-r--r-- | docs/clamp/acm/files/acm-nodetemplates.yaml | 50 | ||||
| -rw-r--r-- | docs/clamp/acm/files/acm-nodetypes.yaml | 113 | ||||
| -rw-r--r-- | docs/clamp/acm/files/acm-tosca.yaml | 225 | ||||
| -rw-r--r-- | docs/clamp/clamp.rst | 4 |
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 |