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