openstack/deb-murano
Code Issues Proposed changes

Merge "Murano documentation update"

Browse Source
This commit is contained in:
Jenkins 2015-04-10 20:13:20 +00:00 committed by Gerrit Code Review
commit 47d8455620
5 changed files with 335 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
doc/source/articles/app_pkg.rst
View File

@ -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.

217
doc/source/articles/client.rst Normal file
View File

@ -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>

63
doc/source/articles/repository.rst Normal file
View File

@ -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.

18
doc/source/index.rst
View File

@ -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::

2
doc/source/murano_pl/builtin_functions.rst
View File

@ -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