Merge "Murano documentation update"

doc/source/articles/app_pkg.rst

@@ -13,6 +13,8 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+.. _app_pkg:
+
 ====================================
 Composing application package manual
 ====================================
@@ -145,6 +147,7 @@ General application metadata should be described in the application manifest fil
 * **Author** - person or company name which created an application package
 * **Classes** - MuranoPL class list, on which application deployment is based
 * **Tags** - list of words, associated with this application. Will be helpful during the search. *Optional* parameter
+* **Require** - list of applications with versions, required by this application. Currently only used by repository importing mechanism. *Optional* parameter
 
 .. _Telnet Manifest:
 
@@ -164,8 +167,39 @@ Example *manifest.yaml*
      io.murano.apps.linux.Telnet: telnet.yaml
     UI: telnet.yaml
     Logo: telnet.png
+    Require:
+      io.murano.apps.TelnetHelper: 0.0.1
 
-Step 6.  Compose a zip archive
+Step 6.  Prepare images.lst file
+================================
+
+This step is optional. If you plan on providing images required by your
+application, you can include ``images.lst`` file with image specifications
+
+Example *images.lst*
+
+.. code-block:: yaml
+
+    Images:
+    - Name: 'my_image.qcow2'
+      Hash: '64d7c1cd2b6f60c92c14662941cb7913'
+      Meta:
+        title: 'tef'
+        type: 'linux'
+      DiskFormat: qcow2
+      ContainerFormat: bare
+    - Name: 'my_other_image.qcow2'
+      Hash: '64d7c1cd2b6f60c92c14662941cb7913'
+      Meta:
+        title: 'tef'
+        type: 'linux'
+      DiskFormat: qcow2
+      ContainerFormat: bare
+      Url: 'http://path.to/images/file.qcow2'
+
+If *Url* is omitted - the images would be searched for in the Murano Repository.
+
+Step 7.  Compose a zip archive
 ==============================
 
 An application archive should have the following structure
@@ -184,5 +218,7 @@ An application archive should have the following structure
     Image file should be placed in the root folder. It can have any name, just specify it in the manifest file or skip to use default *logo.png* name
 * *manifest.yaml*
     Application manifest file. It's an application entry point. The file name is fixed.
+* *images.lst*
+    List of required images. Optional file.
 
 Congratulations! Your application is ready to be uploaded to an Application Catalog.

doc/source/articles/client.rst

@@ -0,0 +1,217 @@
+..
+      Copyright 2015 Mirantis, Inc.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http//www.apache.org/licenses/LICENSE-2.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.
+
+.. _client:
+
+=============
+Murano client
+=============
+
+Module python-muranoclient comes with CLI *murano* utility, that interacts with
+Murano application catalog
+
+Installation
+============
+
+To install latest murano CLI client run the following command in your shell::
+
+    pip install python-muranoclient
+
+Alternatively you can checkout the latest version from
+https://github.com/stackforge/python-muranoclient
+
+
+Using CLI client
+================
+
+In order to use the CLI, you must provide your OpenStack username, password,
+tenant name or id, and auth endpoint. Use the corresponding arguments
+(``--os-username``, ``--os-password``, ``--os-tenant-name`` or
+``--os-tenant-id``, ``--os-auth-url`` and ``--murano-url``) or
+set corresponding environment variables::
+
+    export OS_USERNAME=user
+    export OS_PASSWORD=password
+    export OS_TENANT_NAME=tenant
+    export OS_AUTH_URL=http://auth.example.com:5000/v2.0
+    export MURANO_URL=http://murano.example.com:8082/
+
+Once you've configured your authentication parameters, you can run ``murano
+help`` to see a complete listing of available commands and arguments and
+``murano help <sub_command>`` to get help on specific subcommand.
+
+
+Bash completion
+===============
+
+To get the latest bash completion script download `murano.bash_completion`_
+from the source repository and add it to your completion scripts.
+
+
+.. _murano.bash_completion: https://raw.githubusercontent.com/stackforge/python-muranoclient/master/tools/murano.bash_completion
+
+
+Listing currently installed packages
+====================================
+
+To get list of currently installed packages run::
+
+    murano package-list
+
+To show details about specific package run::
+
+    murano package-show <PKG_ID>
+
+Importing packages in Murano
+============================
+
+``package-import`` subcommand can install packages in several different ways:
+    * from a locall file
+    * from a http url
+    * from murano app repository
+
+When creating a package you can specify it's categories with
+``-c/--categories`` and set it's publicity with ``--public``
+
+To import a local package run::
+
+    murano package-import /path/to/package.zip
+
+To import a package from http url run::
+
+    murano package-import http://example.com/path/to/package.zip
+
+And finally you can import a package from Murano repository. To do so you have
+to specify base url for the repository with ``--murano-repo-url`` or with the
+corresponding ``MURANO_REPO_URL`` environment variable. After doing so,
+running::
+
+    murano --murano-repo-url="http://example.com/" package-import io.app.foo
+
+would access specified repository and download app ``io.app.foo`` from it's
+app directory. This option supports an optional ``--version`` parameter, that
+would instruct murano client to download package of a specific version.
+
+``package-import`` inspects package requirements specified in the package's
+manifest under `Require` section and attempts to import them from
+Murano Repository.
+``package-import`` also inspects any image prerequisites, mentioned in the
+`images.lst` file in the package. If there are any image requirements client
+would inspect images already present in the image database. Unless image with
+the specific name and hash is present client would attempt to download it.
+
+For more info about specifiying images and requirements for the package see
+package creation docs: :ref:`app_pkg`.
+
+If any of the packages, being installed is already registerd in Murano, client
+would ask you what do do with it. You can specify the default action with
+``--exists-action``, passing `s` for skip, `u` for update, and `a` for abort.
+
+Importing bundles of packages in Murano
+=======================================
+
+``package-import`` subcommand can install packages in several different ways:
+    * from a locall file
+    * from a http url
+    * from murano app repository
+
+When creating a package you can specify it's categories with
+``-c/--categories`` and set it's publicity with ``--public``
+
+To import a local bundle run::
+
+    murano bundle-import /path/to/bundle
+
+To import a bundle from http url run::
+
+    murano bundle-import http://example.com/path/to/bundle
+
+To import a bundle from murano repository run::
+
+    murano bundle-import bundle_name
+
+Note: When importing from a local file packages would first be searched in a
+directory, relative to the directory containing the bundle file itself. This
+is done to facilitate installing bundles in an environment with no access to
+the repository itself.
+
+Deleting packages from murano
+=============================
+
+To delete a package run::
+
+    murano package-delete <PKG_ID>
+
+
+Downloading package file
+========================
+
+Running::
+
+    murano package-download <PKG_ID> > file.zip
+
+would download the zip arhive with specified package
+
+Creating a package
+==================
+
+Murano client is able to create application packages from package source
+files/directories. To find out more about this command run::
+
+    murano help package-create
+
+This command is useful, when application package files are spread across
+several directories, and for auto-generating packages from heat templates
+For more info about package composition please see package creation docs:
+:ref:`app_pkg`.
+
+
+Managing Environments
+=====================
+
+It is possible to create/update/delete environments with following commands::
+
+   murano environment-create <NAME>
+   murano environment-delete <NAME_OR_ID>
+   murano environment-list
+   murano environment-rename <OLD_NAME_OR_ID> <NEW_NAME>
+   murano environment-show <NAME_OR_ID>
+
+You can get list of deployments for environmet with::
+
+   murano deployment-list <NAME_OR_ID>
+
+Managing Categories
+===================
+
+It is possible to create/update/delete categories with following commands::
+
+   murano category-create <NAME>
+   murano category-delete <ID> [<ID> ...]
+   murano category-list
+   murano category-show <ID>
+
+Managing Environmet Templates
+=============================
+
+It is possible to manage environment templates with following commands::
+
+   murano env-template-create <NAME>
+   murano env-template-add-app <NAME> <FILE>
+   murano env-template-del-app <NAME> <FILE>
+   murano env-template-delete <ID>
+   murano env-template-list
+   murano env-template-show <ID>
+   murano env-template-update <ID> <NEW_NAME>

doc/source/articles/repository.rst

@@ -0,0 +1,63 @@
+..
+      Copyright 2015 Mirantis, Inc.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http//www.apache.org/licenses/LICENSE-2.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.
+
+.. _repository:
+
+=========================
+Murano package repository
+=========================
+
+Murano client and dashboard are both capable of installing packages and
+bundles of packages from murano repository. To do so you should set
+``MURANO_REPO_URL`` settings in murano dashboard or ``MURANO_REPO_URL`` env
+variable for the CLI client and use the respective command for package import.
+These commands would then automatically import all the prerequisites for the
+app being installed along with any images, mentioned in said apps.
+
+For more info about importing from repository see :ref:`client`.
+
+Setting up your own repository
+==============================
+
+It's fairly easy to set up your own murano package repository.
+To do so you need a web server, that would serve 3 directories:
+    * /apps/
+    * /bundles/
+    * /images/
+
+When importing an app by name client would append any version info, if present
+to the app name, ``.zip`` file extension and search for that file in the
+``apps`` directory.
+
+When importing a bundle by name client would append ``.bundle`` file
+extension to the bundle name and search it in the ``bundles`` directory.
+Bundle file is a json or a yaml file with the following structure:
+
+.. code-block:: json
+
+    {"Packages":
+        [
+            {"Name": "io.murano.apps.ApacheHttpServer"},
+            {"Version": "", "Name": "io.murano.apps.Nginx"},
+            {"Version": "0.0.1", "Name": "io.murano.apps.Lighttpd"}
+        ]
+    }
+
+Glance images can be auto-imported by client, when mentioned in ``images.lst``
+inside the package. Please see :ref:`app_pkg` for more info about pakcage
+composition.
+When importing images from ``image.lst`` file client simply searches for a
+file with the same name as the ``Name`` attribute of the image in the
+``images`` directory of the repository.

doc/source/index.rst

@@ -31,18 +31,20 @@ Key goal is to provide UI and API which allows to compose and deploy composite
 environments on the Application abstraction level and then manage their
 lifecycle.
 
-Murano consists of three source code repositories:
+Murano consists of several source code repositories:
     * `murano`_ - is the main repository. It contains code for Murano API
       server, Murano engine and MuranoPL
     * `murano-agent`_ - agent which runs on guest VMs and executes deployment
       plan
     * `murano-dashboard`_ - Murano UI implemented as a plugin for OpenStack
       Dashboard
+    * `python-muranoclient`_ - Client library and CLI client for Murano
 
 
 .. _murano: https://git.openstack.org/cgit/stackforge/murano/
 .. _murano-agent: https://git.openstack.org/cgit/stackforge/murano-agent/
 .. _murano-dashboard: https://git.openstack.org/cgit/stackforge/murano-dashboard/
+.. _python-muranoclient: https://git.openstack.org/cgit/stackforge/python-muranoclient/
 
 
 This documentation offers information on how Murano works and how to
@@ -77,6 +79,20 @@ contribute to the project.
    image_builders/index
    articles/test_docs
 
+**Client**
+
+.. toctree::
+   :maxdepth: 1
+
+   articles/client
+
+**Repository**
+
+.. toctree::
+   :maxdepth: 1
+
+   articles/repository
+
 **Guidelines**
 
 .. toctree::

doc/source/murano_pl/builtin_functions.rst

@@ -1,5 +1,5 @@
 ..
-      Copyright 2014 2014 Mirantis, Inc.
+      Copyright 2014 Mirantis, Inc.
 
       Licensed under the Apache License, Version 2.0 (the "License"); you may
       not use this file except in compliance with the License. You may obtain