diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/AAI REST API Documentation/AAIRESTAPI_AMSTERDAM.rst | 642 | ||||
| -rw-r--r-- | docs/Getting Started/AAI_Developer_Environment_Setup.rst | 265 | ||||
| -rw-r--r-- | docs/Getting Started/Edge_Rules.rst | 161 | ||||
| -rw-r--r-- | docs/Getting Started/How_to_AAI_data_snapshot_and_restore_in_ONAP_1_1.rst | 46 | ||||
| -rw-r--r-- | docs/Getting Started/How_to_Docker_setup_on_Single_VM.rst | 56 | ||||
| -rw-r--r-- | docs/Getting Started/Queries/Policy_Named_Query.rst | 182 | ||||
| -rw-r--r-- | docs/Getting Started/Queries/vnf_to_esr_system_info_Named_Query.rst | 368 | ||||
| -rw-r--r-- | docs/index.rst | 12 |
8 files changed, 1732 insertions, 0 deletions
diff --git a/docs/AAI REST API Documentation/AAIRESTAPI_AMSTERDAM.rst b/docs/AAI REST API Documentation/AAIRESTAPI_AMSTERDAM.rst new file mode 100644 index 00000000..9cff428b --- /dev/null +++ b/docs/AAI REST API Documentation/AAIRESTAPI_AMSTERDAM.rst @@ -0,0 +1,642 @@ +.. contents:: + :depth: 3 +.. + +AAI REST API + +| Copyright © 2017 AT&T Intellectual Property. +| All rights reserved. +| Licensed under the Creative Commons License, Attribution 4.0 Intl. + (the "License"); you may not use this documentation except in + compliance with the License. +| You may obtain a copy of the License at +| https://creativecommons.org/licenses/by/4.0/ +| Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied. See the License for the specific language governing + permissions and limitations under the License. +| ECOMP and OpenECOMP are trademarks and service marks of AT&T + Intellectual Property. + +\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ + +Overview +======== + +The AAI REST API provides access to the AAI active inventory graph. The +API is largely configured off of models and configuration files. Each +vertex in the graph has an API that can be called separately or, if part +of a tree structure, as a nested element with one or more generations +(parent, grandparent, etc.). + +The edges of the graph are provisioned using a relationship list +construct. For PUT methods, a relationship contains the vertex type or +category (related-to) and a list of relationship data which captures the +key pieces of data required to uniquely identify the resource. On a GET +method, the above information and a URL are returned. The URL can be +used to GET all the details of that object. The URL returned is suitable +for retrying failed commands but should not be expected to be cacheable +for very long periods (e.g., the version of the URL may get deprecated +when the release changes). + +Concurrency control for AAI is in place. The assumptions made for the +implementation are as follows: + +- A client always gets a resource before updating through PUT or + deleting it. + +- All resource updates and deletions are done via the AAI REST APIs + +- This solution will apply to PUT and DELETE operations. + +- The resource-version attribute is now in every container + +- The update API is not subject to concurrency control because it is + only intended to be used by clients who are the definitive source of + truth for the attributes they are changing. An update through the + update API will however reset the resource-version so clients using + PUT and DELETE will not risk updating with stale data. + +- The PATCH REST verb is not subject to concurrency control because it + is only intended to be used by clients who are the definitive source + of truth for the attributes they are changing. An update through the + update API will however reset the resource-version so clients using + PUT and DELETE will not risk updating with stale data. + +How to Use this Document +======================== + +When you click on the API documentation, you will see the Summary of +APIs broken down by namespace (e.g., cloud-infrastructure, business, +network, service-design-and-creation). You can search for **Tag:** +(matching the explicit case) to move from namespace to namespace through +the Summary. + +Search for **Paths** to skip past the Summary section where there will +be more detail about each API. Query parameters are provided here, as +well as links to our error codes. + +Search for **Schema definitions** to see the definitions of the +payloads. In your browser URL, you can type /#/definitions/node-name at +the end of the html address to skip directly to a payload definition. + +Note that the schema definitions now contain information about the +delete scope of a node (also referenced in this document) and some +related node information (also reference in this document as Edges). + +Once AAI has a model and configured it, the AAI development server can +be used to generate sample XML and JSON payloads, according to the +Accept header passed in the request. This is done by calling the +"plural" version of an API followed by the word example (e.g., +/vserver/vservers/example). This returns a GET result array with one +entry. That single entry can be sent in a PUT request with actual data +(the resource-id does not need to be in the PUT payload as it is on the +URL). + +Document Conventions +==================== + +Information that is largely guidance or aspirational will be show in +gray italicized text. This information should not be relied upon or +referenced at this point except with the understanding that it WILL +change. + +**Bold blue text** will be used to cover communication to our clients +that may not be enforced by AAI. The sources of truth (our clients) +populate AAI and are expected to send the correct information, having +applied business rules that live in the client systems. + +Deprecation Warnings and History +================================ + +V11 + +API retirements: + +- The actions/update API will be retired. Clients must switch to PATCH. + There is one grandfathered usage for vpe update flows which will be + retired in v11. + +- The edge tag query will be retired. + +Notable attribute and/or valid value changes (generally also impacts +events): + +- The persona-model-id and persona-version will be replaced with + model-invariant-id (same value as persona-model-id) and + model-version-id (the UUID of the specific version of a model). + Persona-model-customization-id will be replaced by + model-customization-id. + +- The operational-state attribute will be replaced by + operational-status and the only valid values will be in-service-path + and out-of-service-path + +- The vpn-binding object will be split in two to reflect more than one + route-target per binding. The route-target will be a child of + vpn-binding and some attributes will move from vpn-binding to + route-target. + +- The following license related attributes will be removed from + generic-vnf: license-key, entitlement-assignment-group-uuid, + entitlement-resource-uuid, license-assignment-group-uuid, and + license-key-uuid due to the introduction of the entitlement and + license children. + +Event Specific: + +- Normal impacts due to renaming or adding attributes, splitting + objects, etc. Please see swagger documentation for objects of + interest. + +- In v11, clients that require lineage, children, or relationship + information need to subscribe to a different DMaaP topic than the + current one. + +Relationship List + +- The related-link will be a URI and thus not contain + https://{serverroot} (impacts events) + +- Thhe related-link will be used on a PUT as the "first choice" to + identify the related resource. The relationship-data structure, which + contains the unordered set of keys, is still an acceptable way to + relate two objects but, *if both the relationship-data and the + related-link are passed, and they don't agree, the related-link will + be used without warning that the data is inconsistent*. + +- The relationship-data will be ignored on PUT. + +AAI API Definition +================== + +The API structure is composed of: + +- The HTTP command, which indicates the operation to perform + +- The HTTP URI, which defines what object this operation is related to + +- The HTTP version, which MUST be 1.1 + +Available HTTP commands are: + +- PUT: used to create or update an object + +- DELETE: used to delete an object or a set of objects + +- GET : used to query an object or set of objects + +- PATCH : used to update specific fields owned by the client doing the + update + +The HTTP URI is built according to this pattern: + +https://{serverRoot}/{namespace}/{resource} + +- (serverRoot} refers to the server base url: hostname+port+base + path+version. Port and base path are OPTIONAL but AAI will use port + 8443 and base path aai. The Amsterdam release version will be v11. + +- {namespace} refers to the API namespace. Supported namespaces are + cloud-infrastructure, business, service-design-and-creation, and + network + +- {resource} refers to how the object is identified according to the + namespace specifications. + +Example + +GET https://{hostname}:8443/aai +/v11/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id} + +The GET requests support a depth query parameter allowing a query to +stop after it has reached a certain point in the graph. This allows +clients to minimize the data that is returned to them. A depth=0 returns +the resource itself and none of its children. + +Data Assumptions +---------------- + +Given AAI is largely a correlation engine among disparate inventory +types, AAI will accept values as they are sent, without validating the +format or value of the input. It is incumbent upon the source of truth +to provide valid information to AAI. + +Clients should do a GET prior to a PUT and change only the data that +they mean to affect. The REST APIs expect the payload passed to replace +the resource in AAI. **This is vital in our concurrency scheme. The +client will be returned an opaque value per entity which needs to be +returned back in the PUT. AAI will reject the PUT or DELETE if the +opaque value doesn't match what AAI has stored for that entity.** + +If a leaf has been added to a model in vN+1, and a GET/PUT of a vN +resource is done, AAI should not affect the new leaf (i.e., it should be +left unchanged). + +PUT and Lists +------------- + +The PUT verb is used to both create and replace a resource. A given +resource may have child resources (e.g., customers have service +subscriptions; tenants have vservers and vservers have volumes). + +The following convention will be followed: + +If a resource is replaced and there are no tags for children, the +children that exist will be left alone. + +If a resource is replaced and there are tags for children, the children +will be replaced by the list passed. If the list is empty, then children +will be deleted. + +Note that the relationship list is a type of child resource. The same +conventions are followed. It is especially critical to ensure that you +do not send an incomplete relationship list and therefore remove edges +in the graph. See section 5.10 for more information on relationship +lists. + +PATCH +----- + +To move towards industry standards and to make our APIs easier to use by +clients who own specific attributes and do not require AAI to enforce +concurrency control around them, the PATCH verb has been introduced. + +- RFC Algorithm implemented JSON Merge PATCH + `tools.ietf.org/html/rfc7386 <https://tools.ietf.org/html/rfc7386>`__ + +- *HTTP Verb = PATCH* + +- PATCH requires a Content-Type of "application/merge-patch+json" in + your HTTP headers. + +- PATCH does not support XML + +- PATCH does not require a resource version to preform these + modifications + +- Clients should only send what they wish to modify and whose value + they "own" + +Example: + +PATCH \ `https://<hostname>:8443/aai/v11/network/generic-vnfs/generic-vnf/cscf0001v <https://aai-int1.test.att.com:8443/aai/v7/network/generic-vnfs/generic-vnf/cscf0001v>`__ + + { + + "vnf-id": "cscf0001v", This key needs to be here but you cannot +modify the key + + "regional-resource-zone": null, + + "ipv4-oam-address": "1.2.3.4" + +} + +This payload would result in the generic-vnf with the vnf-id = cscf0001v +having ipv4-oam-address set to "1.2.3.4" and regional-resource-zone +having its value removed from the database. + +Referential Integrity +--------------------- + +AAI is primarily a view to the relationships between customers, +products, services, physical and virtual components, etc. It stores just +the details it needs to be efficient to its tasks and knows how to get +more details if needed. + +As such, a transaction sent to AAI may be refused if would break +referential integrity. The referential integrity rules of AAI are still +evolving as we understand the services and customers that will use us. + +AAI uses a graph database on a NoSQL data store. The following are true +for AAI: + +- Some vertices are exposed to the outside world through APIs, others + are internal to how we store the data (i.e., it may look like one + resource to our customers but it is expressed as more than one vertex + in our graph) + +- Vertices that are internal to AAI will be deleted when the parent + vertex is deleted, if deletion of the parent leaves the child vertex + orphaned + +- Vertices that are exposed need to be managed using specific rules for + each vertex. + +- Vertices may have more than just parent/child relationships. One + example is a vserver, which will be owned by a tenant and used by a + VNF. + +Delete Rules +------------ + +The following options are available as actions to be take upon deletion +of a resource: + +- ERROR\_IF\_ANY\_EDGES – If the resource being deleted has any edges + at all, an error should be returned + +- ERROR\_IF\_ANY\_IN\_EDGES – if the resource being deleted has any + edges that point IN towards it, an error should be returned + +- THIS\_NODE\_ONLY – delete the vertex being requested by first + deleting its edge to other vertices, but do not delete the other + vertices. Note, the delete will be rejected if the deletion target + has DEPENDENT children (e.g., tenants that have vservers) + +- CASCADE\_TO\_CHILDREN – cascade the delete through vertices who have + a parentOf relationship to the vertex being deleted, as long as the + vertex is orphaned by the delete of its parent + +- ERROR\_4\_IN\_EDGES\_OR\_CASCADE – error if there are any in edges + and, if not, cascade to children + +Security +-------- + +All REST APIs must be called using https. + +The current release is configured to support BasicAuth. 2-way SSL using +client certificates should be configured for production deployments or +as needed. + +Headers +------- + +The following will be used for logging and interface diagnostic +purposes. + +- X-FromAppId Unique Application ID assigned to the user of these APIs + +- X-TransactionId Unique ID that identifies an API request + +The X-FromAppId will be assigned to each application by the AAI team. +The X-TransactionId must be unique to each transaction within the +context of an X-FromAppId. + +OpenECOMP components that call AAI use the Java UUID class to generate +unique ids for X-TransactionId. + +The Accept header should be set to either application/json or +application/xml. + ++-------------------------------+---------------+ +| Client | X-FromAppId | ++===============================+===============+ +| Policy | Policy | ++-------------------------------+---------------+ +| Master Service Orchestrator | MSO | ++-------------------------------+---------------+ +| SDN Controller | SDNC | ++-------------------------------+---------------+ +| Application Controller | APPC | ++-------------------------------+---------------+ + +Response Codes and Error Handling +--------------------------------- + +HTTP response codes and error codes are described in the API +documentation. + +URLs Sent To and Retrieved From AAI +----------------------------------- + +AAI receives URLs from clients that point back to that client in order +to get more details about the data sent to AAI. AAI expects the URLs +sent by clients (e.g., self links) to be URL encoded (UTF-8) and AAI +will store them unchanged. + +URLs that AAI constructs that point to AAI resources will be returned +URLEncoded (UTF-8) to clients. This affects URLs in relationship lists +and search results. + +AAI expects space to be %20, and not plus(+). + +The Relationship-List +--------------------- + +The REST interface does not lend itself to creating more than +parent-child relationships and the backend structure of AAI is a graph. +A goal of AAI is to do as little coding as possible to introduce a new +service into the service design and creation environment. + +To that end, we've introduced a relationship-list structure. AAI will +ask its clients to provide certain data in the relationship-list +structure. + +Each relationship has a related-to attribute and a list of key/value +pairs. The related-to attribute identifies the node type that the +resource being acted on is to be related to using the data in the +key/value pairs. AAI will encode a set of rules for each resource type +to verify that only valid edges are being made. AAI will keep the name +of the edge itself, the directionality and cardinality, and the edge +attributes within its own logic. + +If an attempt is made to add a relationship to a node that doesn't exist +(e.g., from a vserver to a vnf, and the vnf doesn't exist), a unique +message Id (3003) will be returned with a specific error code +(ERR.5.4.6129). Arguments will tell the client which node type was +missing (e.g., generic-vnf) and the key data for that node type +(generic-vnf.vnf-id). + +Single relationships can be PUT to the graph in the following way: + +https://{serverRoot}/{namespace}/{resource} +/relationship-list/relationship + +or + +https://{hostname}:8443/aai/v11/cloud-infrastructure/pservers/pserver/pserver-123456789-01/p-interfaces/p-interface/p-interface-name-123456789-01/l-interfaces/l-interface/l-interface-name-123456789-01/relationship-list/relationship + +with a payload containing the relationship information. + +XML: + +<relationship xmlns="http://org.openecomp.aai.inventory/v11"> + +<related-to>logical-link</related-to> + +<relationship-data> + + <relationship-key>logical-link.link-name</relationship-key> + + <relationship-value>logical-link-123456789-01</relationship-value> + +</relationship-data> + +</relationship> + +JSON: + +"related-to": "logical-link", + +"relationship-data": [ + +{ + + "relationship-key": "logical-link.link-name", + + "relationship-value": " logical-link-123456789-01" + +} + +] + +} + +Edges +===== + +The following are the properties used for edge definitions. T is true, F +is false + +- From and To are the node types for the ends of the edges. + +- EdgeLabel is the name of the label within the graph. + +- Direction shows the direction of the edge. + +- Multiplicity shows the multiplicity rule between two nodes. This + helps govern what AAI does when modifying relationships between edges + using the relationship REST APIs + +- ParentOf indicates whether From is a parent of To. + +- UsesResource specifies whether the From node uses resources of the To + node, to be able to view the data in the context of "what uses what". + +- hasDelTarget specifies whether to try to delete the To node when the + From node is deleted. + +- SVC-INFRA (deprecated) + +The configuration for different edges supported by the AAI model are +defined in the DbEdgeRules.java class. + +Indexed Attributes +=================== + +AAI supports query parameters on its indexed attributes. + +As an example, if you wanted to GET a tenant by tenant-name, you would +do something like + +/aai/vX/cloud-infrastructure/cloud-regions/cloud-region/cloud\_owner\_1/cloud-region\_1/tenants/tenant?tenant-name=value + +The properties that are indexed are defined in the aai-schema. + +Namespaces +========== + +Util Domain +----------- + +The util domain is where AAI locates utility functions. There is +currently one utility function, echo, which serves as a ping test that +authenticated authorized clients can call to ensure there is +connectivity with AAI. + +The URL for the echo utility is: + +https://load-balanced-address:8443/aai/util/echo + +If the response is unsuccessful, an error will be returned following the +standard format. + +The successful payload returns the X-FromAppId and X-TransactionId sent +by the client. + +Successful XML Response Payload +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +<Info> + +<responseMessages> + +<responseMessage> + +<messageId>INF0001</messageId> + +<text>Success X-FromAppId=%1 X-TransactionId=%2 (msg=%3) (rc=%4)</text> + +<variables> + +<variable>XYZ</variable> + +<variable>XYZ123</variable> + +<variable>Successful health check:OK</variable> + +<variable>0.0.0002</variable> + +</variables> + +</responseMessage> + +</responseMessages> + +</Info> + +Successful JSON Response Payload +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +{"responseMessages": {"responseMessage": [{ + +"messageId": "INF0001", + +"text": "Success X-FromAppId=%1 X-TransactionId=%2 (msg=%3) (rc=%4)", + +"variables": {"variable": [ + +"XYZ", + +"XYZ123", + +"Successful health check:OK", + +"0.0.0002" + +]} + +}]}} + +Cloud Infrastructure Domain +--------------------------- + +The Cloud Infrastructure domain (cloud-infrastructure) represents the +assets managed within a cloud infrastructure site. This includes the +physical servers, tenants, vservers and cloud-region. + +Network Domain +-------------- + +The network namespace contains virtual and physical network resources as +well as connection resources such as physical links, logical links, etc. + +Business Domain +--------------- + +The business namespace captures customers, service subscriptions, and +service instances. This domain is immature and will be evolving as +service design and creation starts to gel. + +Service Design and Creation +--------------------------- + +The service design and creation namespace captures data we invented +based on what we thought SDC would eventually provide. + +To date, there are only five containers: + +1. Service-capabilities capture the pairings of service to resources. + +2. Service captures the service model instances and this will be + deprecated in the future as things mature + +3. Models captures model definitions (subgraph definitions using the AAI + widgets) + +4. named-queries capture subgraph definitions that allow different data + to be retrieved for a given type of asset diff --git a/docs/Getting Started/AAI_Developer_Environment_Setup.rst b/docs/Getting Started/AAI_Developer_Environment_Setup.rst new file mode 100644 index 00000000..10f45dfa --- /dev/null +++ b/docs/Getting Started/AAI_Developer_Environment_Setup.rst @@ -0,0 +1,265 @@ +.. contents:: + :depth: 3 +.. _dev-setup: + + +A&AI Developer Environment Setup +================================ + +This guide will illustrate setting up an A&AI development environment in +Ubuntu 16.04. + +For this exercise, I set up a new instance of Ubuntu in Virtualbox and +gave it 16G RAM, 200GB dynamically allocated storage, and 3 processors. + +1. install openjdk 8 + + 1. sudo apt install openjdk-8-jdk + +2. Install single node hadoop/titan + + 1. $ wget + http://s3.thinkaurelius.com/downloads/titan/titan-1.0.0-hadoop1.zip + + 2. $ unzip titan-1.0.0-hadoop1.zip + + 3. $ cd titan-1.0.0-hadoop1 + + 4. $ sudo ./bin/titan.sh start + +3. Install haproxy + + 1. $ sudo apt-get -y install haproxy + + 2. | $ haproxy -v + | HA-Proxy version 1.6.3 2015/12/25 + | Copyright 2000-2015 Willy Tarreau + <willy@`haproxy.org <http://haproxy.org/>`__> + + 3. Install this haproxy.cfg file in /etc/haproxy + + `haproxy.cfg <file:///C:\download\attachments\10782088\haproxy.cfg%3fversion=2&modificationDate=1501018863000&api=v2>`__ + +1. $ sudo cp aai.pem /etc/ssl/private/aai.pem + +2. $ sudo chmod 640 /etc/ssl/private/aai.pem + +3. | $ sudo chown root:ssl-cert /etc/ssl/private/aai.pem + | `aai.pem <file:///C:\download\attachments\10782088\aai.pem%3fversion=1&modificationDate=1501019585000&api=v2>`__ + +4. sudo mkdir /usr/local/etc/haproxy + +5. Add these hostnames to the loopback interface in /etc/hosts: + + 1. 127.0.0.1 localhost + `aai-traversal.api.simpledemo.openecomp.org <http://aai-traversal.api.simpledemo.openecomp.org>`__ + aai-resour\ `ces.api.simpledemo.openecomp.or <http://ces.api.simpledemo.openecomp.org>`__\ g + +6. $ sudo service haproxy restart + +1. Set up repos. First, follow the initial setup instructions + in \ `Setting Up Your Development + Environment <file:///C:\display\DW\Setting+Up+Your+Development+Environment>`__ + + 1. $ mkdir -p ~/LF/AAI + + 2. $ cd ~/LF/AAI + + 3. $ git clone + ssh://%3Cusername%3E@gerrit.onap.org:29418/aai/aai-common + + 4. $ git + clone \ `ssh://<username>@gerrit.onap.org:29418/aai/traversal <ssh://%253Cusername%253E@gerrit.onap.org:29418/aai/traversal>`__ + + 5. $ git + clone \ `ssh://<username>@gerrit.onap.org:29418/aai/resources <ssh://%25253Cusername%25253E@gerrit.onap.org:29418/aai/resources>`__ + + 6. $ git clone + ssh://%3Cusername%3E@gerrit.onap.org:29418/aai/logging-service + + 7. If you did not originally create a settings.xml file when setting + up the dev environment, you may get an error on some of the repos + saying that oparent is unresolvable. Using the example + settings.xml file should solve this problem: \ `Setting Up Your + Development + Environment#MavenExamplesettings.xml <file:///C:\display\DW\Setting+Up+Your+Development+Environment#SettingUpYourDevelopmentEnvironment-MavenExamplesettings.xml>`__ + +2. Build aai-common, traversal, and resources + + 1. $ cd ~/LF/AAI/aai-common + + 2. | $ mvn clean install + | Should result in BUILD SUCCESS + + 3. $ cd ~/LF/AAI/resources + + 4. | $ mvn clean install + | Should result in BUILD SUCCESS + + 5. $ cd ~/LF/AAI/logging-service + + 6. | $ mvn clean install + | Should result in BUILD SUCCESS + + 7. | $ cd ~/LF/AAI/traversal + | I had to add the following to traversal/pom.xml to get + traversal to build: + + 8. <repositories> + + 9. <repository> + + 10. <id>maven-restlet</id> + + 11. <name>Restlet repository</name> + + 12. <url>https://maven.restlet.com</url> + + 13. </repository> + + </repositories> + +1. | mvn clean install + | Should result in BUILD SUCCESS + +1. Titan setup + + 1. | Modify both titan-cached.properties and + titan-realtime.properties to the following (for all MS’s that + will connect to the local Cassandra backend) + | storage.backend=\ *cassandra* + | storage.hostname=\ *localhost* + + 2. update + ~/LF/AAI/resources/aai-resources/bundleconfig-local/etc/appprops/titan-cached.properties + + 3. update + ~/LF/AAI/resources/aai-resources/bundleconfig-local/etc/appprops/titan-realtime.properties + + 4. update + ~/LF/AAI/traversal/aai-traversal/bundleconfig-local/etc/appprops/titan-cached.properties + + 5. update + ~/LF/AAI/traversal/aai-traversal/bundleconfig-local/etc/appprops/titan-realtime.properties + + 6. | The following property can be added to specify the keyspace + name, each time you do this step (g) should be done. If not + specified Titan will try to create/use a defaulted keyspace + named titan. + | storage.cassandra.keyspace=<keyspace name> + + 7. From the resources MS run the create db schema standalone program. + + 8. ***NOTE***: The first thing that would need to be done is adding + the schema to the local instance. (this will need to be done + whenever using a new keyspace or after wiping the data). + + Runnable class com.att.aai.dbgen.GenTester with the following vm + args. + + -DAJSC\_HOME=~/LF/AAI/resources + -DBUNDLECONFIG\_DIR="bundleconfig-local" + +1. | Here's the command I used, and it worked: + | $ cd ~/LF/AAI; java + -DAJSC\_HOME=/home/jimmy/LF/AAI/resources/aai-resources + -DBUNDLECONFIG\_DIR="bundleconfig-local" -cp + aai-common/aai-core/target/aai-core-1.1.0-SNAPSHOT.jar:resources/aai-resources/target/aai-resources.jar:resources/aai-resources/target/userjars/\* + org.openecomp.aai.dbgen.GenTester + +1. Start the "resources" microservice + + 1. | Resources runs on port 8446. Go to the resources directory + | $ cd ~/LF/AAI/resources + + 2. | Set the debug port to 9446 + | $ export MAVEN\_OPTS="-Xms1024m -Xmx5120m -XX:PermSize=2024m + -Xdebug -Xnoagent -Djava.compiler=NONE + -Xrunjdwp:transport=dt\_socket,address=9446,server=y,suspend=n" + + 3. | Start the microservice + | $ mvn -P runAjsc + +2. Verify the resources microservice (this example uses Postman utility + for Google Chrome) + + 1. Use basic auth, user = AAI, pw = AAI + + 2. Set the X-TransactionId header (in the example below, the value is + 9999) + + 3. Set the X-FromAppId header (in the example below, the value is + jimmy-postman) + + 4. Perform a GET of https://127.0.0.1:8443/aai/v11/network/vces + + 5. You should see an error as below, 404 Not Found, ERR.5.4.6114. + This indicates that the service is functioning normally: + ++------------------------------------------+ +| |C:\\9cb03b5a507d917b3f460df1c1d95eea| | ++------------------------------------------+ + +1. +2. Start the "traversal" microservice + + 1. | Traversal runs on port 8447. Go to the traversal directory + | $ cd ~/LF/AAI/traversal + + 2. | Set the debug port to 9447 + | $ export MAVEN\_OPTS="-Xms1024m -Xmx5120m -XX:PermSize=2024m + -Xdebug -Xnoagent -Djava.compiler=NONE + -Xrunjdwp:transport=dt\_socket,address=9447,server=y,suspend=n" + + 3. | Start the microservice + | $ mvn -P runAjsc + | Should see something like this: 2017-07-26 + 12:46:35.524:INFO:oejs.Server:com.att.ajsc.runner.Runner.main(): + Started @25827ms + +3. Verify the traversal microservice + + 1. | Set up the widget models + | This will set up the postman to add widget models: \ `Add Widget + Models.postman\_collection.json <file:///C:\download\attachments\10782088\Add%20Widget%20Models.postman_collection.json%3fversion=2&modificationDate=1501102559000&api=v2>`__\ `NamedQuery.postman\_collection.json <file:///C:\download\attachments\10782088\NamedQuery.postman_collection.json%3fversion=2&modificationDate=1501102582000&api=v2>`__ + + 2. Create a runner using this + file: \ `models.csv <file:///C:\download\attachments\10782088\models.csv%3fversion=1&modificationDate=1501100140000&api=v2>`__ + + 3. | Run the test runner + | |C:\\de01805e8408f48478705feb59a27e02| + + 4. | Add a named query called "getComponentList" (this named query is + used by + VID): \ `NamedQuery.postman\_collection.json <file:///C:\download\attachments\10782088\NamedQuery.postman_collection.json%3fversion=2&modificationDate=1501102582000&api=v2>`__ + | |C:\\5cdb29c4d0655cf5ede2011736938e58| + + 5. Add objects: \ `Add Instances for Named + Query.postman\_collection.json <file:///C:\download\attachments\10782088\Add%20Instances%20for%20Named%20Query.postman_collection.json%3fversion=1&modificationDate=1501102617000&api=v2>`__ (replacing + the xmlns "http://org.openecomp.aai.inventory/v11" with + "http://org.onap.aai.inventory/v11" in the Body of the PUT + request) + + 6. | Execute named-query: \ `Execute Named + Query.postman\_collection.json <file:///C:\download\attachments\10782088\Execute%20Named%20Query.postman_collection.json%3fversion=1&modificationDate=1501102658000&api=v2>`__ + | You should see something like the following: + | |C:\\a67954cfbcfebb8d7a7f48bba2a26195| + +4. Your A&AI instance is now running, both the resources and traversal + microservices are working properly with a local titan graph. + +5. Next: \ `Tutorial: Making and Testing a Schema Change in + A&AI <file:///C:\pages\viewpage.action%3fpageId=10783023>`__ + +.. |C:\\9cb03b5a507d917b3f460df1c1d95eea| image:: media/image1.png + :width: 4.87500in + :height: 2.87500in +.. |C:\\de01805e8408f48478705feb59a27e02| image:: media/image2.tmp + :width: 4.87500in + :height: 3.75000in +.. |C:\\5cdb29c4d0655cf5ede2011736938e58| image:: media/image3.png + :width: 4.87500in + :height: 4.15000in +.. |C:\\a67954cfbcfebb8d7a7f48bba2a26195| image:: media/image4.png + :width: 4.87500in + :height: 4.15000in diff --git a/docs/Getting Started/Edge_Rules.rst b/docs/Getting Started/Edge_Rules.rst new file mode 100644 index 00000000..8950d3eb --- /dev/null +++ b/docs/Getting Started/Edge_Rules.rst @@ -0,0 +1,161 @@ +.. contents:: + :depth: 3 +.. + +Edge Rules +========== + +- `Edge Rules Location <#EdgeRules-EdgeRulesLocation>`__ + +- `How to Interpret an Edge + Rule <#EdgeRules-HowtoInterpretanEdgeRule>`__ + + - `Mentally Constructing an + Edge <#EdgeRules-MentallyConstructinganEdge>`__ + + - `Quick guide for which is your in node and which is your out + node <#EdgeRules-Quickguideforwhichisyourinnod>`__ + +- `How to Read Multiplicity <#EdgeRules-HowtoReadMultiplicity>`__ + +- `Internal Edge Properties <#EdgeRules-InternalEdgeProperties>`__ + + - `Quick guide to our direction + syntax: <#EdgeRules-Quickguidetoourdirectionsynta>`__ + +Edge Rules Location +------------------- + +The edge rules json files are located in +aai-common/aai-core/src/main/resources/dbedgerules. + +How to Interpret an Edge Rule +----------------------------- + +Mentally Constructing an Edge +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Read the from/to/direction as a recipe for how to construct the edge. + +{ + + | "from": "tenant", + | "to": "vserver", + | "label": "owns", + | "direction": "OUT", + | "multiplicity": "One2Many", + | "contains-other-v": "${direction}", + | "delete-other-v": "NONE", + | "SVC-INFRA": "!${direction}", + | "prevent-delete": "${direction}" + +} + +1. Start by drawing the "from" node. + +2. Draw an edge off this node in the specified. So if it's OUT, point + the edge out away from the from node, if it's IN, point it into the + node. + +3. Draw the "to" node on the empty end of that edge. + +Essentially, "from" and "to" do not imply direction. Think of them as +more like "NodeA" and "NodeB". + +Quick guide for which is your in node and which is your out node +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ++-----------------+---------------+----------------+ +| **direction** | **in node** | **out node** | ++=================+===============+================+ +| OUT | to | from | ++-----------------+---------------+----------------+ +| IN | from | to | ++-----------------+---------------+----------------+ + +How to Read Multiplicity +------------------------ + +Multiplicity, by itself, has nothing to do with the edge direction or +the from/to nodes. Think of it as a property of the edge label. It +defines how many IN edges of this label and how many OUT edges of this +label are allowed. The format we use is defined by Titan to be In2Out. + +Ex: One2Many means on a node, there may be only one IN edge, and many +OUT edges. + +The from and to node types come in on top of this at the A&AI layer. +A&AI's code defines which node types may have those IN and OUT edges of +this label. + +{ + + | "from": "tenant", + | "to": "vserver", + | "label": "owns", + | "direction": "OUT", + | "multiplicity": "One2Many", + | "contains-other-v": "${direction}", + | "delete-other-v": "NONE", + | "SVC-INFRA": "!${direction}", + | "prevent-delete": "${direction}" + +} + +In this example, the vserver gets the IN edge, so it may have only one +edge from a tenant. The tenant gets the OUT edge, so it may get many +edges to vservers. + +Internal Edge Properties +------------------------ + +A&AI uses the following edge properties for internal processing. + +- contains-other-v + + - This property defines whether or not the other vertex is contained + within another when rendering the resources view + + - This property was previously known as isParent + + - If contains-other-v=OUT, this means that the outVertex contains + the inVertex + + - Or in other words, you can read contains-other-v=OUT as "I am an + edge, my OUT vertex contains my IN vertex" + +- delete-other-v + + - defines whether or not the other vertex is automatically included + in delete processing + + - this property was previously known as hasDelTarget + + - if delete-other-v=IN, this means that when deleting the inVertex + also delete the outVertex + +- SVC-INFRA + + - what direction should the traverser continue in when running + edge-tag-query + + - if SVC-INFRA=OUT, when on the outVertex traverse to the inVertex + and continue + +- prevent-delete + + - defines whether or not this edge can be deleted from a particular + direction + + - if prevent-delete=IN, prevent the deletion of the inVertex of the + edge, allow the outVertex to be deleted. + + - Or in other words, you can read it as "I am an edge, my IN vertex + cannot be deleted" + +Quick guide to our direction syntax: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +${direction} = same as value of "direction" property + +!${direction} = opposite diff --git a/docs/Getting Started/How_to_AAI_data_snapshot_and_restore_in_ONAP_1_1.rst b/docs/Getting Started/How_to_AAI_data_snapshot_and_restore_in_ONAP_1_1.rst new file mode 100644 index 00000000..004a0c98 --- /dev/null +++ b/docs/Getting Started/How_to_AAI_data_snapshot_and_restore_in_ONAP_1_1.rst @@ -0,0 +1,46 @@ +.. contents:: + :depth: 3 +.. + +How to A&AI data snapshot and restore in ONAP 1.1 +================================================= + +1. Check the containers that are running and get the container name for + resources micro service as this container contains both dataSnapshot + and restore scripts + +2. If the deployment was followed properly, then the container name + would have been + testconfig\_aai-resources.api.simpledemo.openecomp.org\_1 + +3. Run the following command to save the current snapshot of your data: + + docker exec -u aaiadmin -it + testconfig\_aai-resources.api.simpledemo.openecomp.org\_1 + /opt/app/aai-resources/bin/dataSnapshot.sh + +1. After running that command, you should see the following line in the + standard output: + + Snapshot written to + /opt/app/aai-resources/logs/data/dataSnapshots/dataSnapshot.graphSON.201709221713 + +1. This file dataSnapshot.graphSON.201709221713 can be found in + /opt/aai/logroot/AAI-RESOURCES/data/dataSnapshots on the host vm + +2. If you want to restore the data from the snapshot, then you would run + this command: + + docker exec -u aaiadmin -it + testconfig\_aai-resources.api.simpledemo.openecomp.org\_1 + /opt/app/aai-resources/bin/dataRestoreFromSnapshot.sh + dataSnapshot.graphSON.201709221713 + +1. The argument to the dataRestoreFromSnapshot.sh is the dataSnapshot + graphson file and it only needs the base name and expects to be found + in the host vm /opt/aai/logroot/AAI-RESOURCES/data/dataSnapshots. + +2. Once that command is run, you will be given a warning of 5 seconds to + quit the process as it will replace whatever you have in your A&AI + data with that snapshot and any current data thats not saved into a + snapshot will be lost. diff --git a/docs/Getting Started/How_to_Docker_setup_on_Single_VM.rst b/docs/Getting Started/How_to_Docker_setup_on_Single_VM.rst new file mode 100644 index 00000000..7776ebdb --- /dev/null +++ b/docs/Getting Started/How_to_Docker_setup_on_Single_VM.rst @@ -0,0 +1,56 @@ +.. contents:: + :depth: 3 +.. + +How to Docker setup on Single VM +================================ + +Step-by-step guide +------------------ + +1. You would need to have root access to the vm + +2. sudo su - root + +3. cd /opt + +4. git clone http://gerrit.onap.org/r/aai/test-config + +5. cd test-config + +6. In deploy\_vm1.sh comment out the lines 89-94 which should be an if + statement checking for the /opt/message-router folder + +7. Create a directory called /opt/config + + 1. mkdir /opt/config/ + +8. Create a file called /opt/config/nexus\_username.txt containing the + text: docker + + 1. echo "docker" > /opt/config/nexus\_username.txt + +9. Create a file called /opt/config/nexus\_password.txt containing the + text: docker + + 1. echo "docker" > /opt/config/nexus\_password.txt + +10. Create a file called /opt/config/dmaap\_topic.txt containing the + text: AAI-EVENT + + 1. echo " AAI-EVENT" > /opt/config/dmaap\_topic.txt + +11. Create a file called /opt/config/nexus\_docker\_repo.txt containing + text: nexus3.onap.org:10001 + + echo "nexus3.onap.org:10001" > /opt/config/nexus\_docker\_repo.txt + +1. Create a file called /opt/config/docker\_version.txt containing text: + 1.1-STAGING-latest + + echo "1.1-STAGING-latest" > /opt/config/docker\_version.txt + +1. Please note that in the previous step, docker version is currently + 1.1-STAGING-latest and this will be changed later + + ./deploy\_vm2.sh && ./deploy\_vm1.sh diff --git a/docs/Getting Started/Queries/Policy_Named_Query.rst b/docs/Getting Started/Queries/Policy_Named_Query.rst new file mode 100644 index 00000000..0dd004d0 --- /dev/null +++ b/docs/Getting Started/Queries/Policy_Named_Query.rst @@ -0,0 +1,182 @@ +.. contents:: + :depth: 3 +.. + +Policy Named Query +================== + +**Example Request** + +POST /aai/search/named-query + +{ + +"query-parameters": { + +"named-query": { + +"named-query-uuid": "a93ac487-409c-4e8c-9e5f-334ae8f99087" + +} + +}, + +"instance-filters":{ + +"instance-filter":[ { + +"generic-vnf": { + +"vnf-id": "de7cc3ab-0212-47df-9e64-da1c79234deb" + +} + +} ] } + +} + +**Example Response** + +{ + +"inventory-response-item": [ + +{ + +"model-name": "service-instance", + +"generic-vnf": { + +"vnf-id": "de7cc3ab-0212-47df-9e64-da1c79234deb", + +"vnf-name": "ZRDM2MMEX39", + +"vnf-type": "vMME Svc Jul 14/vMME VF Jul 14 1", + +"service-id": "a9a77d5a-123e-4ca2-9eb9-0b015d2ee0fb", + +"orchestration-status": "active", + +"in-maint": false, + +"is-closed-loop-disabled": false, + +"resource-version": "1503082370097", + +"model-invariant-id": "82194af1-3c2c-485a-8f44-420e22a9eaa4", + +"model-version-id": "46b92144-923a-4d20-b85a-3cbd847668a9" + +}, + +"extra-properties": {}, + +"inventory-response-items": { + +"inventory-response-item": [ + +{ + +"model-name": "service-instance", + +"service-instance": { + +"service-instance-id": "37b8cdb7-94eb-468f-a0c2-4e3c3546578e", + +"service-instance-name": "Changed Service Instance NAME", + +"model-invariant-id": "82194af1-3c2c-485a-8f44-420e22a9eaa4", + +"model-version-id": "46b92144-923a-4d20-b85a-3cbd847668a9", + +"resource-version": "1503082993532", + +"orchestration-status": "Active" + +}, + +"extra-properties": {}, + +"inventory-response-items": { + +"inventory-response-item": [ + +{ + +"model-name": "pnf", + +"generic-vnf": { + +"vnf-id": "jimmy-test", + +"vnf-name": "jimmy-test-vnf", + +"vnf-type": "vMME Svc Jul 14/vMME VF Jul 14 1", + +"service-id": "a9a77d5a-123e-4ca2-9eb9-0b015d2ee0fb", + +"orchestration-status": "active", + +"in-maint": false, + +"is-closed-loop-disabled": false, + +"resource-version": "1504013830207", + +"model-invariant-id": "862b25a1-262a-4961-bdaa-cdc55d69785a", + +"model-version-id": "e9f1fa7d-c839-418a-9601-03dc0d2ad687" + +}, + +"extra-properties": {} + +}, + +{ + +"model-name": "service-instance", + +"generic-vnf": { + +"vnf-id": "jimmy-test-vnf2", + +"vnf-name": "jimmy-test-vnf2-named", + +"vnf-type": "vMME Svc Jul 14/vMME VF Jul 14 1", + +"service-id": "a9a77d5a-123e-4ca2-9eb9-0b015d2ee0fb", + +"orchestration-status": "active", + +"in-maint": false, + +"is-closed-loop-disabled": false, + +"resource-version": "1504014833841", + +"model-invariant-id": "82194af1-3c2c-485a-8f44-420e22a9eaa4", + +"model-version-id": "46b92144-923a-4d20-b85a-3cbd847668a9" + +}, + +"extra-properties": {} + +} + +] + +} + +} + +] + +} + +} + +] + +} diff --git a/docs/Getting Started/Queries/vnf_to_esr_system_info_Named_Query.rst b/docs/Getting Started/Queries/vnf_to_esr_system_info_Named_Query.rst new file mode 100644 index 00000000..7ad412a9 --- /dev/null +++ b/docs/Getting Started/Queries/vnf_to_esr_system_info_Named_Query.rst @@ -0,0 +1,368 @@ +.. contents:: + :depth: 3 +.. + +vnf to esr-system-info Named Query +================================== + +**Example Request** + +POST https://127.0.0.1:8443/aai/search/named-query + +{ + +"query-parameters": { + +"named-query": { + +"named-query-uuid": "037eb932-edac-48f5-9782-c19c0aa5a031" + +} + +}, + +"instance-filters":{ + +"instance-filter":[ { + +"generic-vnf": { + +"vnf-id": "de7cc3ab-0212-47df-9e64-da1c79234deb" + +} + +} ] + +} + +} + +**Example Response** + +{ + +"inventory-response-item": [ + +{ + +"model-name": "service-instance", + +"generic-vnf": { + +"vnf-id": "de7cc3ab-0212-47df-9e64-da1c79234deb", + +"vnf-name": "ZRDM2MMEX39", + +"vnf-type": "vMME Svc Jul 14/vMME VF Jul 14 1", + +"service-id": "a9a77d5a-123e-4ca2-9eb9-0b015d2ee0fb", + +"orchestration-status": "active", + +"in-maint": false, + +"is-closed-loop-disabled": false, + +"resource-version": "1504805258328", + +"model-invariant-id": "82194af1-3c2c-485a-8f44-420e22a9eaa4", + +"model-version-id": "46b92144-923a-4d20-b85a-3cbd847668a9" + +}, + +"extra-properties": {}, + +"inventory-response-items": { + +"inventory-response-item": [ + +{ + +"vserver": { + +"vserver-id": "example-vserver-id-val-90579", + +"vserver-name": "example-vserver-name-val-92986", + +"vserver-name2": "example-vserver-name2-val-77692", + +"prov-status": "example-prov-status-val-23854", + +"vserver-selflink": "example-vserver-selflink-val-14328", + +"in-maint": true, + +"is-closed-loop-disabled": true, + +"resource-version": "1504808495581" + +}, + +"extra-properties": {}, + +"inventory-response-items": { + +"inventory-response-item": [ + +{ + +"tenant": { + +"tenant-id": "example-tenant-id-val-89637", + +"tenant-name": "example-tenant-name-val-36717", + +"resource-version": "1504808495527" + +}, + +"extra-properties": {}, + +"inventory-response-items": { + +"inventory-response-item": [ + +{ + +"cloud-region": { + +"cloud-owner": "example-cloud-owner-val-44086", + +"cloud-region-id": "example-cloud-region-id-val-67393", + +"cloud-type": "example-cloud-type-val-13758", + +"owner-defined-type": "example-owner-defined-type-val-38571", + +"cloud-region-version": "example-cloud-region-version-val-130", + +"identity-url": "example-identity-url-val-73825", + +"cloud-zone": "example-cloud-zone-val-97510", + +"complex-name": "example-complex-name-val-28459", + +"sriov-automation": false, + +"resource-version": "1504808495472" + +}, + +"extra-properties": {}, + +"inventory-response-items": { + +"inventory-response-item": [ + +{ + +"esr-system-info": { + +"esr-system-info-id": "example-esr-system-info-id-val-25777", + +"system-name": "example-system-name-val-29070", + +"type": "example-type-val-85254", + +"vendor": "example-vendor-val-94515", + +"version": "example-version-val-71880", + +"service-url": "example-service-url-val-36193", + +"user-name": "example-user-name-val-77399", + +"password": "example-password-val-46071", + +"system-type": "example-system-type-val-76197", + +"protocal": "example-protocal-val-52954", + +"ssl-cacert": "example-ssl-cacert-val-75021", + +"ssl-insecure": true, + +"ip-address": "example-ip-address-val-44431", + +"port": "example-port-val-93234", + +"cloud-domain": "example-cloud-domain-val-76370", + +"default-tenant": "example-tenant-id-val-89637", + +"resource-version": "1504808496522" + +}, + +"extra-properties": {} + +} + +] + +} + +} + +] + +} + +} + +] + +} + +}, + +{ + +"vserver": { + +"vserver-id": "example-vserver-id-val-2", + +"vserver-name": "example-vserver-name-val-2", + +"vserver-name2": "example-vserver-name2-val-2", + +"prov-status": "example-prov-status-val-2", + +"vserver-selflink": "example-vserver-selflink-val-2", + +"in-maint": true, + +"is-closed-loop-disabled": true, + +"resource-version": "1504817435622" + +}, + +"extra-properties": {}, + +"inventory-response-items": { + +"inventory-response-item": [ + +{ + +"tenant": { + +"tenant-id": "example-tenant-id-val-2", + +"tenant-name": "example-tenant-name-val-2", + +"resource-version": "1504817435574" + +}, + +"extra-properties": {}, + +"inventory-response-items": { + +"inventory-response-item": [ + +{ + +"cloud-region": { + +"cloud-owner": "example-cloud-owner-val-2", + +"cloud-region-id": "example-cloud-region-id-val-2", + +"cloud-type": "example-cloud-type-val-2", + +"owner-defined-type": "example-owner-defined-type-val-2", + +"cloud-region-version": "example-cloud-region-version-val-2", + +"identity-url": "example-identity-url-val-2", + +"cloud-zone": "example-cloud-zone-val-2", + +"complex-name": "example-complex-name-val-2", + +"sriov-automation": false, + +"resource-version": "1504817435502" + +}, + +"extra-properties": {}, + +"inventory-response-items": { + +"inventory-response-item": [ + +{ + +"esr-system-info": { + +"esr-system-info-id": "example-esr-system-info-id-val-2", + +"system-name": "example-system-name-val-2", + +"type": "example-type-val-2", + +"vendor": "example-vendor-val-2", + +"version": "example-version-val-2", + +"service-url": "example-service-url-val-2", + +"user-name": "example-user-name-val-2", + +"password": "example-password-val-2", + +"system-type": "example-system-type-val-2", + +"protocal": "example-protocal-val-2", + +"ssl-cacert": "example-ssl-cacert-val-2", + +"ssl-insecure": true, + +"ip-address": "example-ip-address-val-2", + +"port": "example-port-val-2", + +"cloud-domain": "example-cloud-domain-val-2", + +"default-tenant": "example-tenant-id-val-2", + +"resource-version": "1504817436023" + +}, + +"extra-properties": {} + +} + +] + +} + +} + +] + +} + +} + +] + +} + +} + +] + +} + +} + +] + +} diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..f1c8c617 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,12 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +A&AI Common Documentation Repository +------------------------------------------------ +.. toctree:: + :maxdepth: 3 + :numbered: + :titlesonly: + :glob: + + :AAI* + :Getting* |