.. This work is licensed under a .. Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 .. THIS IS USED INTERNALLY IN POLICY ONLY .. _api-label: Policy Life Cycle API ##################### .. contents:: :depth: 2 The purpose of this API is to support CRUD of TOSCA *PolicyType* and *Policy* entities. This API is provided by the *PolicyDevelopment* component of the Policy Framework, see the :ref:`The ONAP Policy Framework Architecture ` page. The Policy design API backend is running in an independent building block component of the policy framework that provides REST services for the aforementioned CRUD behaviors. The Policy design API component interacts with a policy database for storing and fetching new policies or policy types as needed. Apart from CRUD, an API is also exposed for clients to retrieve healthcheck status of the API REST service and statistics report including a variety of counters that reflect the history of API invocation. We strictly follow `TOSCA Specification `_ to define policy types and policies. A policy type defines the schema for a policy, expressing the properties, targets, and triggers that a policy may have. The type (string, int etc) and constraints (such as the range of legal values) of each property is defined in the Policy Type. Both Policy Type and policy are included in a TOSCA Service Template, which is used as the entity passed into an API POST call and the entity returned by API GET and DELETE calls. More details are presented in following sections. Policy Types and Policies can be composed for any given domain of application. All Policy Types and Policies must be composed as well-formed TOSCA Service Templates. One Service Template can contain multiple policies and policy types. Child policy types can inherit from parent policy types, so a hierarchy of policy types can be built up. For example, the HpaPolicy Policy Type in the table below is a child of a Resource Policy Type, which is a child of an Optimization policy. See also `the examples in Github `_. :: onap.policies.Optimization.yaml onap.policies.optimization.Resource.yaml onap.policies.optimization.resource.AffinityPolicy.yaml onap.policies.optimization.resource.DistancePolicy.yaml onap.policies.optimization.resource.HpaPolicy.yaml onap.policies.optimization.resource.OptimizationPolicy.yaml onap.policies.optimization.resource.PciPolicy.yaml onap.policies.optimization.resource.Vim_fit.yaml onap.policies.optimization.resource.VnfPolicy.yaml onap.policies.optimization.Service.yaml onap.policies.optimization.service.QueryPolicy.yaml onap.policies.optimization.service.SubscriberPolicy.yaml Custom data types can be defined in TOSCA for properties specified in Policy Types. Data types can also inherit from parents, so a hierarchy of data types can also be built up. .. warning:: When creating a Policy Type, the ancestors of the Policy Type and all its custom Data Type definitions and ancestors MUST either already exist in the database or MUST also be defined in the incoming TOSCA Service Template. Requests with missing or bad references are rejected by the API. Each Policy Type can have multiple Policy instances created from it. Therefore, many Policy instances of the HpaPolicy Policy Type above can be created. When a policy is created, its Policy Type is specified in the *type* and *type_version* fields of the policy. .. warning:: The Policy Type specified for a Policy MUST exist in the database before the policy can be created. Requests with missing or bad Policy Type references are rejected by the API. The API allows applications to create, update, delete, and query *PolicyType* entities so that they become available for use in ONAP by applications such as CLAMP. Some Policy Type entities are preloaded in the Policy Framework. .. warning:: If a TOSCA entity (Data Type, Policy Type, or Policy with a certain version) already exists in the database and an attempt is made to re-create the entity with different fields, the API will reject the request with the error message "entity in incoming fragment does not equal existing entity". In such cases, delete the Policy or Policy Type and re-create it using the API. The TOSCA fields below are valid on API calls: ============ ======= ======== ========== =============================================================================== **Field** **GET** **POST** **DELETE** **Comment** ============ ======= ======== ========== =============================================================================== (name) M M M The definition of the reference to the Policy Type, GET allows ranges to be specified version O M C GET allows ranges to be specified, must be specified if more than one version of the Policy Type exists and a specific version is required description R O N/A Desciption of the Policy Type derived_from R C N/A Must be specified when a Policy Type is derived from another Policy Type such as in the case of derived Monitoring Policy Types. The referenced Policy Type must either already exist in the database or be defined as another policy type in the incoming TOSCA service template metadata R O N/A Metadata for the Policy Type properties R M N/A This field holds the specification of the specific Policy Type in ONAP. Any user defined data types specified on properties must either already exist in the database or be defined in the incoming TOSCA service template targets R O N/A A list of node types and/or group types to which the Policy Type can be applied triggers R O N/A Specification of policy triggers, not currently supported in ONAP ============ ======= ======== ========== =============================================================================== .. note:: On this and subsequent tables, use 
#!/bin/bash
#
echo '============== STARTING SCRIPT TO BUILD DOCKER IMAGES ================='
DOCKER_REPOSITORY=nexus3.onap.org:10003
MVN_VERSION=$(cat packages/apex-pdp-docker/target/version)
MVN_MAJMIN_VERSION=$(cut -f 1,2 -d . packages/apex-pdp-docker/target/version)
TIMESTAMP=$(date -u +%Y%m%dT%H%M%S)
PROXY_ARGS=""
IMAGE=policy-apex-pdp

if [ $HTTP_PROXY ]; then
    PROXY_ARGS+="--build-arg HTTP_PROXY=${HTTP_PROXY}"
fi
if [ $HTTPS_PROXY ]; then
    PROXY_ARGS+=" --build-arg HTTPS_PROXY=${HTTPS_PROXY}"
fi

echo $DOCKER_REPOSITORY
echo $MVN_VERSION
echo $MVN_MAJMIN_VERSION
echo $TIMESTAMP

if [[ -z $MVN_VERSION ]]
then
    echo "MVN_VERSION is empty"
    exit 1
fi

if [[ -z $MVN_MAJMIN_VERSION ]]
then
    echo "MVN_MAJMIN_VERSION is empty"
    exit 1
fi

if [[ $MVN_VERSION == *"SNAPSHOT"* ]]
then
    MVN_MAJMIN_VERSION="${MVN_MAJMIN_VERSION}-SNAPSHOT"
else
    MVN_MAJMIN_VERSION="${MVN_MAJMIN_VERSION}-STAGING"
fi

echo $MVN_MAJMIN_VERSION

echo "Building $IMAGE"

#
# This is the local latest tagged image. The Dockerfile's need this to build images
#
TAGS="--tag onap/${IMAGE}:latest"
#
# This has the nexus repo prepended and only major/minor version with latest
#
TAGS="${TAGS} --tag ${DOCKER_REPOSITORY}/onap/${IMAGE}:${MVN_MAJMIN_VERSION}-latest"
#
# This has the nexus repo prepended and major/minor/patch version with timestamp
#
TAGS="${TAGS} --tag ${DOCKER_REPOSITORY}/onap/${IMAGE}:${MVN_VERSION}-${TIMESTAMP}Z"

echo $TAGS

docker build --quiet ${PROXY_ARGS} $TAGS packages/apex-pdp-docker/target/$IMAGE

if [ $? -ne 0 ]
then
    echo "Docker build failed"
    docker images
    exit 1
fi

docker images

#
# Push image
#
echo "Pushing $IMAGE"
docker push ${DOCKER_REPOSITORY}/onap/$IMAGE:${MVN_MAJMIN_VERSION}-latest

if [ $? -ne 0 ]
then
    echo "Docker push failed"
    exit 1
fi

docker push ${DOCKER_REPOSITORY}/onap/$IMAGE:${MVN_VERSION}-${TIMESTAMP}Z

if [ $? -ne 0 ]
then
    echo "Docker push failed"
    exit 1
fi
to delete them one by one. Sample API Curl Commands ------------------------- From an API client perspective, using *http* or *https* does not make much difference to the curl command. Here we list some sample curl commands (using *http*) for POST, GET and DELETE monitoring and operational policies that are used in vFirewall use case. JSON payload for POST calls can be downloaded from policy table above. If you are accessing the api from the container, the default *ip* and *port* would be **https:/policy-api:6969/policy/api/v1/**. Create vFirewall Monitoring Policy:: curl --user 'healthcheck:zb!XztG34' -X POST "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies" -H "Accept: application/json" -H "Content-Type: application/json" -d @vFirewall.policy.monitoring.input.tosca.json Get vFirewall Monitoring Policy:: curl --user 'healthcheck:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json" Delete vFirewall Monitoring Policy:: curl --user 'healthcheck:zb!XztG34' -X DELETE "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json" Create vFirewall Operational Policy:: curl --user 'healthcheck:zb!XztG34' -X POST "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies" -H "Accept: application/json" -H "Content-Type: application/json" -d @vFirewall.policy.operational.input.tosca.json Get vFirewall Operational Policy:: curl --user 'healthcheck:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies/operational.modifyconfig/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json" Delete vFirewall Operational Policy:: curl --user 'healthcheck:zb!XztG34' -X DELETE "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies/operational.modifyconfig/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json" Get all available policies:: curl --user 'healthcheck:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policies" -H "Accept: application/json" -H "Content-Type: application/json" Get version 1.0.0 of vFirewall Monitoring Policy:: curl --user 'healthcheck:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json" Delete version 1.0.0 of vFirewall Monitoring Policy:: curl --user 'healthcheck:zb!XztG34' -X DELETE "http://{ip}:{port}/policy/api/v1/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"