Github user dankilman commented on a diff in the pull request: https://github.com/apache/incubator-ariatosca/pull/25#discussion_r88401147 --- Diff: README.md --- @@ -1,4 +1,193 @@ -Aria +ARIA ==== -See http://ariatosca.org/ +[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, as well as a +language-agnostic RESTful API that can be deployed as a microservice. + +On its own, ARIA provides built-in tools for blueprint validation and for creating ready-to-run +service instances. + +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: + +<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. + +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. + + +Quick Start +----------- + +You need Python 2.6 or 2.7. Python 3+ is not currently supported. + +To install, we recommend using [pip](https://pip.pypa.io/) and a +[virtualenv](https://virtualenv.pypa.io/en/stable/). In Debian-based systems: + + sudo apt install python-setuptools + sudo -H easy_install pip + sudo -H pip install virtualenv + +To install the latest development snapshot of ARIA: + + virtualenv env + . 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: + + aria parse blueprints/tosca/node-cellar/node-cellar.yaml + +You can also get it in JSON or YAML formats: + + aria parse blueprints/tosca/node-cellar/node-cellar.yaml --json + +Or get an overview of the relationship graph: + + aria parse blueprints/tosca/node-cellar/node-cellar.yaml --graph + +You can provide inputs as JSON, overriding default values provided in the blueprint + + aria parse blueprints/tosca/node-cellar/node-cellar.yaml --inputs='{"openstack_credential": {"user": "username"}}' + +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": + + aria parse blueprints/tosca/node-cellar/node-cellar.yaml --inputs=blueprints/tosca/node-cellar/inputs.yaml + + +CLI Tool +-------- + +Though ARIA is fully exposed as an API, it also comes with a CLI tool to allow you to +work from the shell: + + aria parse blueprints/tosca/node-cellar/node-cellar.yaml instance + +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. + +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`. + +Your customer consumer can be an entry point into a powerful TOSCA-based tool or application, such +as an orchestrator, a graphical modeling tool, etc. + + +Development +----------- + +Instead of installing with `pip`, it would be easier to work directly with the source files: + + pip install virtualenv + virtualenv env + . env/bin/activate + git clone http://git-wip-us.apache.org/repos/asf/incubator-ariatosca.git + cd incubator-ariatosca + pip install -e . + +To run tests: + + pip install tox + tox + +To build the documentation: --- End diff -- we currently have no make file (or docs), so probably best to remove this line
--- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. ---