[doc] Add CLI deployment instructions section

Includes additional labels for cross-references

Change-Id: I5101790360f051244f96abbd55ecbac82996c661

doc/source/articles/workflow.rst

@@ -13,6 +13,8 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+.. _murano-workflow:
+
 ===============
 Murano workflow
 ===============

doc/source/draft/appdev-guide/murano_pl/class_templ.rst

@@ -410,6 +410,9 @@ need to insert dashes before each construct. For example::
         - code
         - block
 
+
+.. _object-model:
+
 Object model
 ------------
 

doc/source/draft/enduser-guide/deploying_using_cli.rst

@@ -0,0 +1,174 @@
+..
+      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.
+
+.. _deploying-using-cli:
+
+================================
+Deploying environments using CLI
+================================
+
+The main tool for deploying murano environments is murano-dashboard. It is
+designed to be easy-to-use and intuitive. But it is not the only tool you can
+use to deploy a murano environment, murano CLI client also possesses required
+functionality for the task. This is an advanced scenario, however, that
+requires knowledge of :ref:`internal murano workflow <murano-workflow>`,
+:ref:`murano object model <object-model>`, and
+:ref:`murano environment <environment>` life cycle.
+This scenario is suitable for deployments without
+horizon or deployment automation.
+
+
+.. note::
+
+    This is an advanced mechanism and you should use it only when you are
+    confident in what you are doing. For everyday use it is recommended to use
+    murano-dashboard.
+
+Create environment
+~~~~~~~~~~~~~~~~~~
+
+This command creates a new murano environment, ready for configuration.
+For convenience this guide will refer to environment ID as ``$ENV_ID``
+from now on.
+
+.. code-block:: console
+
+  murano environment-create deployed_from_cli
+
+  +----------------------------------+-------------------+---------------------+---------------------+
+  | ID                               | Name              | Created             | Updated             |
+  +----------------------------------+-------------------+---------------------+---------------------+
+  | a66e5ea35e9d4da48c2abc37b5a9753a | deployed_from_cli | 2015-10-06T13:50:45 | 2015-10-06T13:50:45 |
+  +----------------------------------+-------------------+---------------------+---------------------+
+
+Create configuration session
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Murano uses configuration sessions to allow several users to edit and configure
+the same environment concurrently. Most of environment-related commands
+require :option:`--session-id` parameter.
+For convenience this guide will refer to session ID as ``$SESS_ID``
+from now on.
+
+.. code-block:: console
+
+  murano environment-session-create $ENV_ID
+
+  +----------+----------------------------------+
+  | Property | Value                            |
+  +----------+----------------------------------+
+  | id       | 5cbe7e561ffc484ebf11aabf83f9f4c6 |
+  +----------+----------------------------------+
+
+
+Add apps to environment
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To manipulate environments object model from CLI you can use
+the :command:`environment-apps-edit` command.
+
+.. code-block:: console
+
+  murano environment-apps-edit --session-id $SESS_ID $ENV_ID object_model_patch.json
+
+The :file:`object_model_patch.json` contains the ``jsonpatch`` object. This
+object is applied to the ``/services`` key of the environment in question.
+Here is the example of the :file:`object_model_patch.json` file content:
+
+.. code-block:: json
+
+    [
+        { "op": "add", "path": "/-", "value":
+            {
+                "instance": {
+                    "availabilityZone": "nova",
+                    "name": "xwvupifdxq27t1",
+                    "image": "fa578106-b3c1-4c42-8562-4e2e2d2a0a0c",
+                    "keyname": "",
+                    "flavor": "m1.small",
+                    "assignFloatingIp": false,
+                    "?": {
+                        "type": "io.murano.resources.LinuxMuranoInstance",
+                        "id": "===id1==="
+                    }
+                },
+                "name": "ApacheHttpServer",
+                "enablePHP": true,
+                "?": {
+                    "type": "io.murano.apps.apache.ApacheHttpServer",
+                    "id": "===id2==="
+                }
+            }
+        }
+    ]
+
+For convenience, the murano client replaces ``"===id1==="``, ``"===id2==="``
+(and so on) strings with UUIDs. This way you can ensure, that object IDs
+inside your object model are unique.
+To learn more about jsonpatch consult jsonpatch.com_ and `RFC 6902`_.
+The :command:`murano-environment-edit` command fully supports jsonpatch.
+This means that you can alter, add, or remove parts of your apps
+object model.
+
+Verify your object model
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To verify whether your object model is correct, check the environment by
+running the :command:`environment-show` command with the
+:option:`--session-id` parameter
+
+.. code-block:: console
+
+    murano environment-show $ENV_ID --session-id $SESS_ID --only-apps
+
+    [
+      {
+        "instance": {
+          "availabilityZone": "nova",
+          "name": "xwvupifdxq27t1",
+          "assignFloatingIp": false,
+          "keyname": "",
+          "flavor": "m1.small",
+          "image": "fa578106-b3c1-4c42-8562-4e2e2d2a0a0c",
+          "?": {
+            "type": "io.murano.resources.LinuxMuranoInstance",
+            "id": "fc4fe975f5454bab99bb0e309249e2d2"
+          }
+        },
+        "?": {
+          "status": "pending",
+          "type": "io.murano.apps.apache.ApacheHttpServer",
+          "id": "69cdf10d31e64196b4de894e7ea4f1be"
+        },
+        "enablePHP": true,
+        "name": "ApacheHttpServer"
+      }
+    ]
+
+
+Deploy your environment
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To deploy session ``$SESS_ID`` of your environment use
+the :command:`murano environment-deploy` command.
+
+.. code-block:: console
+
+    murano environment-deploy $ENV_ID --session-id $SESS_ID
+
+You can later use the :command:`murano environment-show` command to
+track deployment status.
+
+
+.. _jsonpatch.com: http://jsonpatch.com
+.. _RFC 6902: http://tools.ietf.org/html/rfc6902

doc/source/draft/index.rst

@@ -52,6 +52,7 @@ Using Murano
    enduser-guide/manage_applications
    enduser-guide/log_into_murano_instance
    enduser-guide/troubleshooting
+   enduser-guide/deploying_using_cli
 
 Deploying Murano
 ~~~~~~~~~~~~~~~~

doc/source/specification/murano-api.rst

@@ -16,6 +16,8 @@
 Glossary
 ========
 
+.. _environment:
+
 * **Environment**
 
     The environment is a set of applications managed by a single tenant. They could be related logically with each other or not.