ariatosca-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r..@apache.org
Subject incubator-ariatosca git commit: ARIA-166 Update README file [Forced Update!]
Date Thu, 08 Jun 2017 15:29:17 GMT
Repository: incubator-ariatosca
Updated Branches:
  refs/heads/ARIA-166-update-readme 1d3ece965 -> 98676df53 (forced update)


ARIA-166 Update README file


Project: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/commit/98676df5
Tree: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/tree/98676df5
Diff: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/diff/98676df5

Branch: refs/heads/ARIA-166-update-readme
Commit: 98676df53f11ddacbd739068025f2cc0c3b50b4a
Parents: 5afa2f7
Author: Ran Ziv <ran@gigaspaces.com>
Authored: Thu Jun 8 18:26:29 2017 +0300
Committer: Ran Ziv <ran@gigaspaces.com>
Committed: Thu Jun 8 18:29:05 2017 +0300

----------------------------------------------------------------------
 README.md | 219 +++++++++++++++++----------------------------------------
 1 file changed, 66 insertions(+), 153 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/98676df5/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index e534645..e5f89ae 100644
--- a/README.md
+++ b/README.md
@@ -4,198 +4,111 @@ ARIA
 [![Build Status](https://travis-ci.org/apache/incubator-ariatosca.svg?branch=master)](https://travis-ci.org/apache/incubator-ariatosca)
 [![Appveyor Build Status](https://ci.appveyor.com/api/projects/status/ltv89jk63ahiu306?svg=true)](https://ci.appveyor.com/project/ApacheSoftwareFoundation/incubator-ariatosca/history)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![PyPI release](https://img.shields.io/pypi/v/ariatosca.svg?style=plastic)](https://pypi.python.org/pypi/ariatosca)
+![Python Versions](https://img.shields.io/pypi/pyversions/ariatosca.svg?style=plastic)
+![Wheel](https://img.shields.io/pypi/wheel/ariatosca.svg?style=plastic)
+![Contributors](https://img.shields.io/github/contributors/apache/incubator-ariatosca.svg?style=plastic)
+[![Open Pull Requests](https://img.shields.io/github/issues-pr/apache/incubator-ariatosca.svg?style=plastic)](https://github.com/apache/incubator-ariatosca/pulls)
+[![Closed Pull Requests](https://img.shields.io/github/issues-pr-closed-raw/apache/incubator-ariatosca.svg?style=plastic)](https://github.com/apache/incubator-ariatosca/pulls?q=is%3Apr+is%3Aclosed)
 
 
-[ARIA](http://ariatosca.org/) is a minimal TOSCA orchestrator, as well as a platform for
building
-TOSCA-based products. Its features can be accessed via a well-documented Python API.
+[ARIA](http://ariatosca.incubator.apache.org/) is a an open-source, lightweight, library
and CLI for orchestration that open-source projects can consume to build TOSCA-based orchestration
solutions for resources and services orchestration. It supports NFV and hybrid Cloud scenarios.
 
-On its own, ARIA provides built-in tools for blueprint validation and for creating ready-to-run
-service instances. 
+ARIA can be utilized by any organization that wants to implement TOSCA-based orchestration
in its solutions, whether a multi-cloud enterprise application, or an NFV or SDN solution
for multiple virtual infrastructure managers.
 
-ARIA adheres strictly and meticulously to the
-[TOSCA Simple Profile v1.0 cos01 specification](http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.0/cos01/TOSCA-Simple-Profile-YAML-v1.0-cos01.html),
-providing state-of-the-art validation at seven different levels:
+With ARIA, you can utilize TOSCA's cloud portability out-of-the-box, to test and run your
applications, from template to deployment. 
 
-<ol start="0">
-<li>Platform errors. E.g. network, hardware, or even an internal bug in ARIA (let us
know,
-	please!).</li>
-<li>Syntax and format errors. E.g. non-compliant YAML, XML, JSON.</li>
-<li>Field validation. E.g. assigning a string where an integer is expected, using a
list instead of
-	a dict.</li>
-<li>Relationships between fields within a type. This is "grammar" as it applies to
rules for
-    setting the values of fields in relation to each other.</li>
-<li>Relationships between types. E.g. referring to an unknown type, causing a type
inheritance
-    loop.</li>
-<li>Topology. These errors happen if requirements and capabilities cannot be matched
in order to
-	assemble a valid topology.</li>
-<li>External dependencies. These errors happen if requirement/capability matching fails
due to
-    external resources missing, e.g. the lack of a valid virtual machine, API credentials,
etc.
-    </li> 
-</ol>
 
-Validation errors include a plain English message and when relevant the exact location (file,
row,
-column) of the data the caused the error.
+Installation
+----------------
 
-The ARIA API documentation always links to the relevant section of the specification, and
likewise
-we provide an annotated version of the specification that links back to the API documentation.
+ARIA is [available on PyPI](https://pypi.python.org/pypi/ariatosca).    
 
+ARIA requires Python 2.6/2.7. Python 3+ is not currently supported.
 
-Quick Start
------------
+ARIA itself is in a `wheel` format compatible with all platforms. 
+Some dependencies, however, might require compilation (based on a given platform), and therefore
possibly some system dependencies are required as well.
 
-You need Python 2.6 or 2.7. Python 3+ is not currently supported.
+On Ubuntu or other Debian-based systems:
 
-To install, we recommend using [pip](https://pip.pypa.io/) and a
-[virtualenv](https://virtualenv.pypa.io/en/stable/).
+	sudo apt install python-setuptools python-dev build-essential libssl-dev libffi-dev
 
-In Debian-based systems:
+On Archlinux:
 
-	sudo apt install python-setuptools
-	sudo -H easy_install pip
-	sudo -H pip install virtualenv
-	virtualenv env
+	sudo pacman -S python-setuptools
 
-Or in Archlinux-based systems:
 
-	pacman -S python2 python-setuptools python-pip
-	pip install virtualenv
-	virtualenv env -p $(type -p python2)
+To install ARIA directly from PyPI (using a `wheel`), use:
 
-To install the latest development snapshot of ARIA:
+    pip install aria
 
-	. env/bin/activate
-	pip install git+http://git-wip-us.apache.org/repos/asf/incubator-ariatosca.git
 
-To test it, let's create a service instance from a TOSCA blueprint:
+To install ARIA from source, download the source tarball from [PyPI](https://pypi.python.org/pypi/ariatosca),
+extract it, and then when inside the extracted directory, use:
 
-	aria parse blueprints/tosca/node-cellar/node-cellar.yaml
-	
-You can also get it in JSON or YAML formats:
+    pip install .
+    
+The source package comes along with relevant examples, documentation,
+`requirements.txt` (for installing specifically the frozen dependencies' versions with which
ARIA was tested) and more.
 
-	aria parse blueprints/tosca/node-cellar/node-cellar.yaml --json
 
-Or get an overview of the relationship graph:
+<br>
+Note that for the `pip install` commands mentioned above, you must use a privileged user,
or use virtualenv.
 
-	aria parse blueprints/tosca/node-cellar/node-cellar.yaml --graph
 
-You can provide inputs as JSON, overriding default values provided in the blueprint
+Getting Started
+---------------
 
-	aria parse blueprints/tosca/node-cellar/node-cellar.yaml --inputs='{"openstack_credential":
{"user": "username"}}'
+This section will describe how to run a simple "Hello World" example.
 
-Instead of providing them explicitly, you can also provide them in a file or URL, in either
JSON or
-YAML. If you do so, the value must end in ".json" or ".yaml":
+First, provide ARIA with your service-template, naming it `my-service-template`:
 
-	aria parse blueprints/tosca/node-cellar/node-cellar.yaml --inputs=blueprints/tosca/node-cellar/inputs.yaml
+	aria service-templates store examples/hello-world/helloworld.yaml my-service-template
+	
+Now create a service based on this service-template, naming it `my-service`:
+	
+	aria services create my-service -t my-service-template
+	
+Finally, start an `install` workflow execution on `my-service` like so:
 
+	aria executions start install -s my-service
 
-CLI
----
+<br>
+You should now have a simple web-server running on your local machine.
+You can try visiting http://localhost:9090 to view your deployed application.
 
-Though ARIA is fully exposed as an API, it also comes with a CLI tool to allow you to work
from the
-shell:
+To uninstall and clean your environment, follow these steps:
 
-	aria parse blueprints/tosca/node-cellar/node-cellar.yaml instance
+    aria executions start uninstall -s my-service
+    aria services delete my-service
+    aria service-templates delete my-service-template
 
-The `parse` command supports the following directives to create variations of the default
consumer
-chain:
 
-* `presentation`: emits a colorized textual representation of the Python presentation classes
-   wrapping the blueprint.
-* `model`: emits a colorized textual representation of the complete service model derived
from the
-   validated blueprint. This includes all the node templates, with their requirements satisfied
at
-   the level of relating to other node templates.
-* `types`: emits a colorized textual representation of the type hierarchies.
-* `instance`: **this is the default command**; emits a colorized textual representation of
a
-   service instance instantiated from the service model. Here the node templates are each
used to
-   create one or more nodes, with the appropriate relationships between them. Note that every
time
-   you run this consumer, you will get a different set of node IDs. Use `--graph` to see
just the
-   node relationship graph.
-   
-For all these commands, you can also use `--json` or `--yaml` flags to emit in those formats.
+Contribution
+------------
 
-Additionally, The CLI tool lets you specify the complete classname of your own custom consumer
to
-chain at the end of the default consumer chain, after `instance`.
+You are welcome and encouraged to participate and contribute to the ARIA project.
 
-Your custom consumer can be an entry point into a powerful TOSCA-based tool or application,
such as
-an orchestrator, a graphical modeling tool, etc.
+Please see our guide to [Contributing to ARIA](https://cwiki.apache.org/confluence/display/ARIATOSCA/Contributing+to+ARIA).
 
+Feel free to also provide feedback on the mailing lists (see [Resources](#user-content-Resources)
section).
 
-Development
------------
 
-Instead of installing with `pip`, it would be easier to work directly with the source files:
+Resources
+---------
 
-	pip install virtualenv
-	virtualenv env
-	. env/bin/activate
-	git clone http://git-wip-us.apache.org/repos/asf/incubator-ariatosca.git ariatosca
-	cd ariatosca
-	pip install -e .
+* [ARIA homepage](http://ariatosca.incubator.apache.org/)
+* [ARIA wiki](https://cwiki.apache.org/confluence/display/AriaTosca)
+* [Issue tracker](https://issues.apache.org/jira/browse/ARIA)
 
-To run tests:
+* Dev mailing list: dev@ariatosca.incubator.apache.org
+* User mailing list: user@ariatosca.incubator.apache.org
 
-	pip install tox
-	tox
+See information on how to subscribe to mailing list [here](https://www.apache.org/foundation/mailinglists.html).
 
-Here's a quick example of using the API to parse YAML text into a service instance:
+For past correspondence, see the [dev mailing list archive](http://mail-archives.apache.org/mod_mbox/incubator-ariatosca-dev/).
 
-	from aria import install_aria_extensions
-	from aria.parser.consumption import ConsumptionContext, ConsumerChain, Read, Validate, Model,
Instance
-	from aria.parser.loading import LiteralLocation
-	
-	def parse_text(payload, file_search_paths=[]):
-	    context = ConsumptionContext()
-	    context.presentation.location = LiteralLocation(payload)
-	    context.loading.file_search_paths += file_search_paths
-	    ConsumerChain(context, (Read, Validate, Model, Instance)).consume()
-	    if not context.validation.dump_issues():
-	        return context.modeling.instance
-	    return None
-	
-	install_aria_extensions()
-
-	print parse_text("""
-	tosca_definitions_version: tosca_simple_yaml_1_0
-	topology_template:
-	  node_templates:
-	    MyNode:
-	      type: tosca.nodes.Compute 
-	""")
-
-
-Parser API Architecture
------------------------
-
-ARIA's parsing engine comprises individual "consumers" (in the `aria.parser.consumption`
package)
-that do things with blueprints. When chained together, each performs a different task, adds
its own
-validations, and can provide its own output.
-
-Parsing happens in five phases, represented in five packages:
-
-* `aria.parser.loading`: Loaders are used to read the TOSCA data, usually as text. For example
-  UriTextLoader will load text from URIs (including files).
-* `aria.parser.reading`: Readers convert data from the loaders into agnostic raw data. For
-  example, `YamlReader` converts YAML text into Python dicts, lists, and primitives.
-* `aria.parser.presentation`: Presenters wrap the agnostic raw data in a nice
-  Python facade (a "presentation") that makes it much easier to work with the data, including
-  utilities for validation, querying, etc. Note that presenters are _wrappers_: the agnostic
raw
-  data is always maintained intact, and can always be accessed directly or written back to
files.
-* `aria.parser.modeling.model`: Here the topology is normalized into a coherent structure
of
-  node templates, requirements, and capabilities. Types are inherited and properties are
assigned.
-  The service model is a _new_ structure, which is not mapped to the YAML. In fact, it is
possible
-  to generate the model programmatically, or from a DSL parser other than TOSCA.
-* `aria.parser.modeling.instance`: The service instance is an instantiated service model.
Node
-  templates turn into node instances (with unique IDs), and requirements are satisfied by
matching
-  them to capabilities. This is where level 5 validation errors are detected (see above).
-
-The phases do not have to be used in order. Indeed, consumers do not have to be used at all:
ARIA
-can be used to _produce_ blueprints. For example, it is possible to fill in the
-`aria.parser.presentation` classes programmatically, in Python, and then write the presentation
-to a YAML file as compliant TOSCA. The same technique can be used to convert from one DSL
(consume
-it) to another (write it).
-
-The term "agnostic raw data" (ARD?) appears often in the documentation. It denotes data structures
-comprising _only_ Python dicts, lists, and primitives, such that they can always be converted
to and
-from language-agnostic formats such as YAML, JSON, and XML. A considerable effort has been
made to
-conserve the agnostic raw data at all times. Thus, though ARIA makes good use of the dynamic
power
-of Python, you will _always_ be able to use ARIA with other systems.
+
+License
+-------
+ARIA is licensed under the [Apache License 2.0](https://github.com/apache/incubator-ariatosca/blob/master/LICENSE).


Mime
View raw message