diff --git a/doc/source/administrator-guide/admin_index.rst b/doc/source/administrator-guide/admin_index.rst new file mode 100644 index 000000000..c5b27f8a8 --- /dev/null +++ b/doc/source/administrator-guide/admin_index.rst @@ -0,0 +1,22 @@ +.. index:: Murano Administrator Guide + +.. _admin-guide: + +Deploying Murano +~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 2 + + deploy_murano + prepare_lab + configuration + manage_packages + manage_images + manage_categories + murano_repository + murano_agent + policy_enf + configure_cloud_foundry_service_broker + using_glare.rst + admin_troubleshooting \ No newline at end of file diff --git a/doc/source/draft/admin-guide/admin_troubleshooting.rst b/doc/source/administrator-guide/admin_troubleshooting.rst similarity index 52% rename from doc/source/draft/admin-guide/admin_troubleshooting.rst rename to doc/source/administrator-guide/admin_troubleshooting.rst index f9025fcd4..edea90d30 100644 --- a/doc/source/draft/admin-guide/admin_troubleshooting.rst +++ b/doc/source/administrator-guide/admin_troubleshooting.rst @@ -1,8 +1,5 @@ .. _admin-troubleshooting: -.. toctree:: - :maxdepth: 2 - =============== Troubleshooting =============== @@ -10,36 +7,34 @@ Troubleshooting Log location ~~~~~~~~~~~~ -By default, logs are sent to stdout. -Let's consider how log files can be set up. +By default, logs are sent to stdout. Consider how to set up the log files. Murano API + Engine ------------------- To define a file where to store logs, use the ``log_file`` option in the -:file:`murano.conf` file. You can provide an absolute or relative path. +:file:`murano.conf` file. You can provide an absolute or a relative path. -To enable detailed log file configuration, set up :file:`logging.conf`. +To enable a detailed log file configuration, set up :file:`logging.conf`. The example is provided in :file:`etc/murano` directory. The log configuration file location is set with the ``log_config_append`` option in the murano configuration file. - Murano applications ------------------- -Murano applications have a separate logging handler and a separate file -where all logs from application definitions should be provided. -Open the :file:`logging.conf` file and check the -``args: ('applications.log',)`` option in the ``handler_applications`` section. +Murano applications have a separate logging handler and a separate file where +all logs from application definitions should be provided. Open the +:file:`logging.conf` file and check the ``args: ('applications.log',)`` +option in the ``handler_applications`` section. Verify that ``log_config_append`` is not empty and set to the :file:`logging.conf` location. -Problems during configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Issues during configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If any problems occur, first of all verify that: +If any issues occur, first of all verify the following: * All murano components have consistent versions: murano-dashboard and murano-engine should use the same or compatible python-muranoclient version. @@ -48,21 +43,22 @@ If any problems occur, first of all verify that: * The database is synced with code by running: .. code-block:: console + murano-db-manage --config-file murano.conf upgrade **Failed to execute `murano-db-manage`** -* Make sure :option:`--config-file` option is provided. -* Check `connection` parameter in provided configuration file. It should be a - `connection string `_. +* Make sure the :option:`--config-file` option is provided. +* Check `connection` parameter in the provided configuration file. It should + be a `connection string `_. -* Check that MySQL or PostgreSQL (depending of what you provided in +* Check that MySQL or PostgreSQL (depending of what you provided in the connection string) Python modules are installed on the system. **Applications panel is not seen in horizon** -* Make sure that :file:`_50_murano.py` file is copied to - ``openstack-dashboard/local/enabled`` directory and there is no other file, +* Make sure that the :file:`_50_murano.py` file is copied to the + ``openstack-dashboard/local/enabled`` directory and there is no other file starting with ``_50``. * Check that murano data is not inserted twice in the settings file and as a @@ -71,50 +67,50 @@ If any problems occur, first of all verify that: **Applications panel can be browsed, but 'Unable to communicate to murano-api server.' appears** If you have murano registered in keystone, verify the endpoint URL is valid -and service has *application-catalog* name. If you don't want to register +and service has *application-catalog* name. If you do not want to register the murano service in keystone, just add ``MURANO_API_URL`` option to the horizon local setting. -Problems during deployment -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Issues during deployment +~~~~~~~~~~~~~~~~~~~~~~~~ Besides identifying errors from log files, there is another and more flexible -way to browse deployment errors - directly from UI. When the *Deploy Failed* +way to browse deployment errors -- directly from UI. When the *Deploy Failed* status appears, navigate to :menuselection:`Environment Components` and click -the Latest Deployment Log tab. You can see steps of the deployment and the one -that failed would have red color. +the :guilabel:`Latest Deployment Log` tab. You can see steps of the deployment +and the one that failed would have red color. **while scanning a simple key in "", line 32, column 3: ...** -There is an error in YAML file format. -Before uploading a package, validate your file in an online YAML validator -like `YAMLint `_. +There is an error in the YAML file format. Before uploading a package, +validate your file in an online YAML validator like +`YAMLint `_. Later `validation tool `_ to check package closely while uploading will be added. **NoPackageForClassFound: Package for class io.murano.Environment is not found** -Verify that murano core package is uploaded. -If not, the content of `meta/io.murano` folder should be zipped and -uploaded to Murano. +Verify that murano core package is uploaded. If not, the content of the +``meta/io.murano`` folder should be zipped and uploaded to Murano. **[keystoneclient.exceptions.AuthorizationFailure]:** **Authorization failed: You are not authorized to perform the requested action. (HTTP 403)** -Token expires during the deployment. Usually the default standard token lifetime -is one hour. The error occurs frequently as, in most cases, a deployment takes -longer than that or does not start right after token is generated. +The token expires during the deployment. Usually the default standard token +lifetime is one hour. The error occurs frequently as, in most cases, a +deployment takes longer than that or does not start right after a token is +generated. Workarounds: * Use trusts. Only possible in the v3 version. Read more in the `official documentation `_ or `here `_. - Do not forget to check corresponding heat and murano settings. Trusts are - enabled by default in murano and heat since Kilo release. + Do not forget to check the corresponding heat and murano settings. Trusts + are enabled by default in murano and heat since Kilo release. - In murano the corresponding configuration option is located in *engine* - section: + In murano, the corresponding configuration option is located in the + ``engine`` section: .. code-block:: console @@ -126,58 +122,57 @@ Workarounds: # value) use_trusts = true - If your Keystone runs v2 version, check out the solutions below. + If your Keystone runs v2 version, see the solutions below. * Make logout/login to compose a new token and start the deployment again. - Would not help for long deployment or if token lifetime is too small. + Would not help for long deployment or if the token lifetime is too small. * Increase the token lifetime in the keystone configuration file. **The murano-agent did not respond within 3600 seconds** -* Need to check transport access to the virtual machine (verify that the - router has a gateway). +* Check transport access to the virtual machine: verify that the router has a + gateway. * Check the RabbitMQ settings: verify that the agent has valid RabbitMQ parameters. - Go to the spawned virtual machine and open :file:`*/etc/murano/agent.conf` on the - Linux-based machine or :file:`C:\\Murano\\Agent\\agent.conf` on Windows-based - machine. Also, you can examine agent logs, located by default at - :file:`/var/log/murano-agent.log` The first part of the log file contains - reconnection attempts to the RabbitMQ since the valid RabbitMQ address - and queue have not been obtained yet. + Go to the spawned virtual machine and open :file:`*/etc/murano/agent.conf` + on the Linux-based machine or :file:`C:\\Murano\\Agent\\agent.conf` on the + Windows-based machine. Additionally, you can examine agent logs that by + default are located at :file:`/var/log/murano-agent.log` The first part of + the log file contains reconnection attempts to the RabbitMQ since the valid + RabbitMQ address and queue have not been obtained yet. * Verify that the ``driver`` option in ``[oslo_messaging_notifications]`` group is set to ``messagingv2``. **murano.engine.system.agent.AgentException** -Agent started the execution plan, but something went wrong. Examine agent logs -(see the previous paragraph for the logs placement information). Also, try to -manually execute the application scripts. +The agent started the execution plan but something went wrong. Examine agent +logs (see the previous paragraph for the logs placement information). Also, +try to manually execute the application scripts. **[exceptions.EnvironmentError]: Unexpected stack state NOT_FOUND or UPDATE_FAILED** -A problem with heat stack creation, examine the heat log file. Try to -manually spawn the instance. If in the reason of stack creation fail is -``no valid host was found``, probably there is not enough resources or -something is wrong with nova-scheduler. +An issue with heat stack creation, examine the heat log file. Try to manually +spawn the instance. If the reason of the stack creation fail is ``no valid +host was found``, there might be not enough resources or something is wrong +with the nova-scheduler. **Router could not be created, no external network found** -Find the ``external_network`` parameter in the *networking* section of -murano configuration file and verify that the specified external network does exist -through Web UI or by executing the :command:`openstack network list --external` command. +Find the ``external_network`` parameter in the ``networking`` section of the +murano configuration file and verify that the specified external network does +exist through Web UI or by executing the +:command:`openstack network list --external` command. **Deployment log in the UI contains incomplete reports** Sometimes logs contain only two messages after the application deployment. -There are no messages, provided in applications themselves: +There are no messages provided in applications themselves: .. code-block:: console 2015-09-21 11:14:58 — Action deploy is scheduled 2015-09-21 11:16:43 — Deployment finished successfully -To fix the problem, set the ``driver`` option in the :file:`murano.config` -file to ``messagingv2``. - - +To fix the issue, set the ``driver`` option in the :file:`murano.config` file +to ``messagingv2``. \ No newline at end of file diff --git a/doc/source/draft/admin-guide/configuration.rst b/doc/source/administrator-guide/configuration.rst similarity index 99% rename from doc/source/draft/admin-guide/configuration.rst rename to doc/source/administrator-guide/configuration.rst index fa5538708..83dee2bfe 100644 --- a/doc/source/draft/admin-guide/configuration.rst +++ b/doc/source/administrator-guide/configuration.rst @@ -1,8 +1,5 @@ .. _configuration: -.. toctree:: - :maxdepth: 2 - ============= Configuration ============= diff --git a/doc/source/draft/admin-guide/configure_cloud_foundry_service_broker.rst b/doc/source/administrator-guide/configure_cloud_foundry_service_broker.rst similarity index 99% rename from doc/source/draft/admin-guide/configure_cloud_foundry_service_broker.rst rename to doc/source/administrator-guide/configure_cloud_foundry_service_broker.rst index 25450560b..d81d8919b 100644 --- a/doc/source/draft/admin-guide/configure_cloud_foundry_service_broker.rst +++ b/doc/source/administrator-guide/configure_cloud_foundry_service_broker.rst @@ -1,8 +1,5 @@ .. _configure_service_broker: -.. toctree:: - :maxdepth: 2 - ======================================= Murano service broker for Cloud Foundry ======================================= diff --git a/doc/source/draft/admin-guide/deploy_murano.rst b/doc/source/administrator-guide/deploy_murano.rst similarity index 100% rename from doc/source/draft/admin-guide/deploy_murano.rst rename to doc/source/administrator-guide/deploy_murano.rst diff --git a/doc/source/draft/admin-guide/deploy_murano/configure_ssl.rst b/doc/source/administrator-guide/deploy_murano/configure_ssl.rst similarity index 100% rename from doc/source/draft/admin-guide/deploy_murano/configure_ssl.rst rename to doc/source/administrator-guide/deploy_murano/configure_ssl.rst diff --git a/doc/source/draft/admin-guide/deploy_murano/devstack.rst b/doc/source/administrator-guide/deploy_murano/devstack.rst similarity index 100% rename from doc/source/draft/admin-guide/deploy_murano/devstack.rst rename to doc/source/administrator-guide/deploy_murano/devstack.rst diff --git a/doc/source/draft/admin-guide/deploy_murano/install_manually.rst b/doc/source/administrator-guide/deploy_murano/install_manually.rst similarity index 100% rename from doc/source/draft/admin-guide/deploy_murano/install_manually.rst rename to doc/source/administrator-guide/deploy_murano/install_manually.rst diff --git a/doc/source/draft/admin-guide/deploy_murano/prerequisites.rst b/doc/source/administrator-guide/deploy_murano/prerequisites.rst similarity index 100% rename from doc/source/draft/admin-guide/deploy_murano/prerequisites.rst rename to doc/source/administrator-guide/deploy_murano/prerequisites.rst diff --git a/doc/source/draft/admin-guide/figures/add-interface.png b/doc/source/administrator-guide/figures/add-interface.png similarity index 100% rename from doc/source/draft/admin-guide/figures/add-interface.png rename to doc/source/administrator-guide/figures/add-interface.png diff --git a/doc/source/draft/admin-guide/policy_enforcement/deploy-log.png b/doc/source/administrator-guide/figures/deploy-log.png similarity index 100% rename from doc/source/draft/admin-guide/policy_enforcement/deploy-log.png rename to doc/source/administrator-guide/figures/deploy-log.png diff --git a/doc/source/draft/admin-guide/figures/network-topology-1.png b/doc/source/administrator-guide/figures/network-topology-1.png similarity index 100% rename from doc/source/draft/admin-guide/figures/network-topology-1.png rename to doc/source/administrator-guide/figures/network-topology-1.png diff --git a/doc/source/draft/admin-guide/figures/network-topology-2.png b/doc/source/administrator-guide/figures/network-topology-2.png similarity index 100% rename from doc/source/draft/admin-guide/figures/network-topology-2.png rename to doc/source/administrator-guide/figures/network-topology-2.png diff --git a/doc/source/draft/admin-guide/policy_enforcement/new-inst.png b/doc/source/administrator-guide/figures/new-inst.png similarity index 100% rename from doc/source/draft/admin-guide/policy_enforcement/new-inst.png rename to doc/source/administrator-guide/figures/new-inst.png diff --git a/doc/source/draft/admin-guide/manage_categories.rst b/doc/source/administrator-guide/manage_categories.rst similarity index 73% rename from doc/source/draft/admin-guide/manage_categories.rst rename to doc/source/administrator-guide/manage_categories.rst index 4f4720855..ca80e7dbb 100644 --- a/doc/source/draft/admin-guide/manage_categories.rst +++ b/doc/source/administrator-guide/manage_categories.rst @@ -1,8 +1,5 @@ .. _manage-categories: -.. toctree:: - :maxdepth: 2: - =================== Managing categories =================== diff --git a/doc/source/draft/admin-guide/manage_images.rst b/doc/source/administrator-guide/manage_images.rst similarity index 80% rename from doc/source/draft/admin-guide/manage_images.rst rename to doc/source/administrator-guide/manage_images.rst index da98566cc..fea673b60 100644 --- a/doc/source/draft/admin-guide/manage_images.rst +++ b/doc/source/administrator-guide/manage_images.rst @@ -1,8 +1,5 @@ .. _manage-images: -.. toctree:: - :maxdepth: 2: - =============== Managing images =============== diff --git a/doc/source/draft/admin-guide/manage_packages.rst b/doc/source/administrator-guide/manage_packages.rst similarity index 98% rename from doc/source/draft/admin-guide/manage_packages.rst rename to doc/source/administrator-guide/manage_packages.rst index 220ef8990..c0a056718 100644 --- a/doc/source/draft/admin-guide/manage_packages.rst +++ b/doc/source/administrator-guide/manage_packages.rst @@ -1,8 +1,5 @@ .. _manage-packages: -.. toctree:: - :maxdepth: 1: - ================= Managing packages ================= diff --git a/doc/source/draft/admin-guide/murano_agent.rst b/doc/source/administrator-guide/murano_agent.rst similarity index 99% rename from doc/source/draft/admin-guide/murano_agent.rst rename to doc/source/administrator-guide/murano_agent.rst index aec2ac072..8f3d3fdfa 100644 --- a/doc/source/draft/admin-guide/murano_agent.rst +++ b/doc/source/administrator-guide/murano_agent.rst @@ -1,8 +1,5 @@ .. _murano-agent: -.. toctree:: - :maxdepth: 2: - ============ Murano agent ============ diff --git a/doc/source/draft/admin-guide/murano_repository.rst b/doc/source/administrator-guide/murano_repository.rst similarity index 85% rename from doc/source/draft/admin-guide/murano_repository.rst rename to doc/source/administrator-guide/murano_repository.rst index 49bc42da0..d0367af58 100644 --- a/doc/source/draft/admin-guide/murano_repository.rst +++ b/doc/source/administrator-guide/murano_repository.rst @@ -1,8 +1,5 @@ .. _murano-repository: -.. toctree:: - :maxdepth: 2: - ================= Murano repository ================= diff --git a/doc/source/draft/admin-guide/policy_enf.rst b/doc/source/administrator-guide/policy_enf.rst similarity index 85% rename from doc/source/draft/admin-guide/policy_enf.rst rename to doc/source/administrator-guide/policy_enf.rst index 6b5dcda3b..ecddc14d5 100644 --- a/doc/source/draft/admin-guide/policy_enf.rst +++ b/doc/source/administrator-guide/policy_enf.rst @@ -39,9 +39,13 @@ the deployment fails as well. .. _Congress: https://wiki.openstack.org/wiki/Congress +This section contains the following subsections: -.. include:: /draft/admin-guide/policy_enforcement/policy_enf_setup.rst -.. include:: /draft/admin-guide/policy_enforcement/policy_enf_rules.rst -.. include:: /draft/admin-guide/policy_enforcement/policy_enf_dev.rst -.. include:: /draft/admin-guide/policy_enforcement/policy_enf_modify.rst +.. toctree:: + :maxdepth: 2 + + policy_enforcement/policy_enf_setup + policy_enforcement/policy_enf_rules + policy_enforcement/policy_enf_dev + policy_enforcement/policy_enf_modify diff --git a/doc/source/draft/admin-guide/policy_enforcement/policy_enf_dev.rst b/doc/source/administrator-guide/policy_enforcement/policy_enf_dev.rst similarity index 100% rename from doc/source/draft/admin-guide/policy_enforcement/policy_enf_dev.rst rename to doc/source/administrator-guide/policy_enforcement/policy_enf_dev.rst diff --git a/doc/source/draft/admin-guide/policy_enforcement/policy_enf_modify.rst b/doc/source/administrator-guide/policy_enforcement/policy_enf_modify.rst similarity index 100% rename from doc/source/draft/admin-guide/policy_enforcement/policy_enf_modify.rst rename to doc/source/administrator-guide/policy_enforcement/policy_enf_modify.rst diff --git a/doc/source/draft/admin-guide/policy_enforcement/policy_enf_rules.rst b/doc/source/administrator-guide/policy_enforcement/policy_enf_rules.rst similarity index 95% rename from doc/source/draft/admin-guide/policy_enforcement/policy_enf_rules.rst rename to doc/source/administrator-guide/policy_enforcement/policy_enf_rules.rst index 7a76766d2..491abb6c6 100644 --- a/doc/source/draft/admin-guide/policy_enforcement/policy_enf_rules.rst +++ b/doc/source/administrator-guide/policy_enforcement/policy_enf_rules.rst @@ -65,7 +65,7 @@ the procedure below. - Select an application from the murano applications. - Create a ``m1.medium`` instance, which uses 4096 MB RAM. - .. image:: /draft/admin-guide/policy_enforcement/new-inst.png + .. image:: ../figures/new-inst.png :alt: Create new instance :width: 100 % @@ -74,7 +74,7 @@ the procedure below. Deployment fails as the rule is violated: environment is in the ``Deploy FAILURE`` status. Check the deployment logs for details: -.. image:: /draft/admin-guide/policy_enforcement/deploy-log.png +.. image:: ../figures/deploy-log.png :alt: Deployment log :width: 100 % diff --git a/doc/source/draft/admin-guide/policy_enforcement/policy_enf_setup.rst b/doc/source/administrator-guide/policy_enforcement/policy_enf_setup.rst similarity index 100% rename from doc/source/draft/admin-guide/policy_enforcement/policy_enf_setup.rst rename to doc/source/administrator-guide/policy_enforcement/policy_enf_setup.rst diff --git a/doc/source/draft/admin-guide/prepare_lab.rst b/doc/source/administrator-guide/prepare_lab.rst similarity index 89% rename from doc/source/draft/admin-guide/prepare_lab.rst rename to doc/source/administrator-guide/prepare_lab.rst index 3d217d815..6030605cc 100644 --- a/doc/source/draft/admin-guide/prepare_lab.rst +++ b/doc/source/administrator-guide/prepare_lab.rst @@ -1,18 +1,3 @@ -.. - Copyright 2015-2016 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. - ======================== Prepare a lab for murano ======================== @@ -21,7 +6,6 @@ It also contains a description of a test which you may use to check if your hardware fits the requirements. To do this, run the test and compare the results with baseline data provided. - .. _system_prerequisites: System prerequisites diff --git a/doc/source/draft/admin-guide/using_glare.rst b/doc/source/administrator-guide/using_glare.rst similarity index 98% rename from doc/source/draft/admin-guide/using_glare.rst rename to doc/source/administrator-guide/using_glare.rst index 1491bb162..08fea9bf8 100644 --- a/doc/source/draft/admin-guide/using_glare.rst +++ b/doc/source/administrator-guide/using_glare.rst @@ -1,9 +1,8 @@ .. _glare_usage: - -=================================== +===================================== Using Glare as a storage for packages -=================================== +===================================== DevStack installation --------------------- diff --git a/doc/source/appdev-guide/app_debugging.rst b/doc/source/appdev-guide/developerguide/app_debugging.rst similarity index 100% rename from doc/source/appdev-guide/app_debugging.rst rename to doc/source/appdev-guide/developerguide/app_debugging.rst diff --git a/doc/source/appdev-guide/app_development_framework.rst b/doc/source/appdev-guide/developerguide/app_development_framework.rst similarity index 99% rename from doc/source/appdev-guide/app_development_framework.rst rename to doc/source/appdev-guide/developerguide/app_development_framework.rst index 6cf208dd4..ae7c6b707 100644 --- a/doc/source/appdev-guide/app_development_framework.rst +++ b/doc/source/appdev-guide/developerguide/app_development_framework.rst @@ -100,7 +100,8 @@ Create a one-component single-server application #. Optional. Add other methods that handle certain stages of the application workflow, such as ``onBeforeInstall``, ``onCompleteInstallation``, ``onConfigureServer``, ``onCompleteConfiguration``, and others. For details - about these methods, see the :ref:`Software Components` section. + about these methods, see the + :ref:`Software components ` section. Create a one-component multi-server application ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -430,6 +431,7 @@ Servers replication Classes for grouping and replication of other kinds of resources are to be implemented later. +.. _software-components: Software Components ~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/appdev-guide/app_migrating.rst b/doc/source/appdev-guide/developerguide/app_migrating.rst similarity index 58% rename from doc/source/appdev-guide/app_migrating.rst rename to doc/source/appdev-guide/developerguide/app_migrating.rst index 2fee5d9e7..0402e1d59 100644 --- a/doc/source/appdev-guide/app_migrating.rst +++ b/doc/source/appdev-guide/developerguide/app_migrating.rst @@ -1,8 +1,5 @@ .. _app_migrating: -.. toctree:: - :maxdepth: 2 - ======================================= Migrating applications between releases ======================================= @@ -11,7 +8,10 @@ This document describes how a developer of murano application can update existing packages to make them synchronized with all implemented features and requirements. -.. include:: app_migrating/app_migrate_to_juno.rst -.. include:: app_migrating/app_migrate_to_kilo.rst -.. include:: app_migrating/app_migrate_to_liberty.rst -.. include:: app_migrating/app_migrate_to_newton.rst +.. toctree:: + :maxdepth: 1 + + app_migrating/app_migrate_to_juno + app_migrating/app_migrate_to_kilo + app_migrating/app_migrate_to_liberty + app_migrating/app_migrate_to_newton diff --git a/doc/source/appdev-guide/app_migrating/app_migrate_to_juno.rst b/doc/source/appdev-guide/developerguide/app_migrating/app_migrate_to_juno.rst similarity index 80% rename from doc/source/appdev-guide/app_migrating/app_migrate_to_juno.rst rename to doc/source/appdev-guide/developerguide/app_migrating/app_migrate_to_juno.rst index bab4a22cf..375eabf02 100644 --- a/doc/source/appdev-guide/app_migrating/app_migrate_to_juno.rst +++ b/doc/source/appdev-guide/developerguide/app_migrating/app_migrate_to_juno.rst @@ -1,18 +1,3 @@ -.. - 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. - .. _app_migrate_to_juno: diff --git a/doc/source/appdev-guide/app_migrating/app_migrate_to_kilo.rst b/doc/source/appdev-guide/developerguide/app_migrating/app_migrate_to_kilo.rst similarity index 85% rename from doc/source/appdev-guide/app_migrating/app_migrate_to_kilo.rst rename to doc/source/appdev-guide/developerguide/app_migrating/app_migrate_to_kilo.rst index bd54fcd47..cf64d244a 100644 --- a/doc/source/appdev-guide/app_migrating/app_migrate_to_kilo.rst +++ b/doc/source/appdev-guide/developerguide/app_migrating/app_migrate_to_kilo.rst @@ -1,18 +1,3 @@ -.. - 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. - .. _app_migrate_to_kilo: Migrate applications to Stable/Kilo diff --git a/doc/source/appdev-guide/app_migrating/app_migrate_to_liberty.rst b/doc/source/appdev-guide/developerguide/app_migrating/app_migrate_to_liberty.rst similarity index 92% rename from doc/source/appdev-guide/app_migrating/app_migrate_to_liberty.rst rename to doc/source/appdev-guide/developerguide/app_migrating/app_migrate_to_liberty.rst index adf9a6e03..b9a02a318 100644 --- a/doc/source/appdev-guide/app_migrating/app_migrate_to_liberty.rst +++ b/doc/source/appdev-guide/developerguide/app_migrating/app_migrate_to_liberty.rst @@ -1,18 +1,3 @@ -.. - 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. - .. _app_migrate_to_liberty: Migrate applications to Stable/Liberty diff --git a/doc/source/appdev-guide/app_migrating/app_migrate_to_newton.rst b/doc/source/appdev-guide/developerguide/app_migrating/app_migrate_to_newton.rst similarity index 89% rename from doc/source/appdev-guide/app_migrating/app_migrate_to_newton.rst rename to doc/source/appdev-guide/developerguide/app_migrating/app_migrate_to_newton.rst index cab73b22e..5b5df4014 100644 --- a/doc/source/appdev-guide/app_migrating/app_migrate_to_newton.rst +++ b/doc/source/appdev-guide/developerguide/app_migrating/app_migrate_to_newton.rst @@ -1,18 +1,3 @@ -.. - Copyright 2016 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. - .. _app_migrate_to_newton: Migrate applications to Stable/Newton diff --git a/doc/source/appdev-guide/app_unit_tests.rst b/doc/source/appdev-guide/developerguide/app_unit_tests.rst similarity index 99% rename from doc/source/appdev-guide/app_unit_tests.rst rename to doc/source/appdev-guide/developerguide/app_unit_tests.rst index b46825281..dcd4f206c 100644 --- a/doc/source/appdev-guide/app_unit_tests.rst +++ b/doc/source/appdev-guide/developerguide/app_unit_tests.rst @@ -1,8 +1,5 @@ .. _app-unit-tests: -.. toctree:: - :maxdepth: 2 - ====================== Application unit tests ====================== diff --git a/doc/source/appdev-guide/cinder_volume_supporting.rst b/doc/source/appdev-guide/developerguide/cinder_volume_supporting.rst similarity index 99% rename from doc/source/appdev-guide/cinder_volume_supporting.rst rename to doc/source/appdev-guide/developerguide/cinder_volume_supporting.rst index e9eb36c6f..6d30756f0 100644 --- a/doc/source/appdev-guide/cinder_volume_supporting.rst +++ b/doc/source/appdev-guide/developerguide/cinder_volume_supporting.rst @@ -1,6 +1,5 @@ .. _cinder_volume_supporting: - Cinder volume support ~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/appdev-guide/developerguide/developer_index.rst b/doc/source/appdev-guide/developerguide/developer_index.rst new file mode 100644 index 000000000..98dc89c20 --- /dev/null +++ b/doc/source/appdev-guide/developerguide/developer_index.rst @@ -0,0 +1,22 @@ +.. _developer-guide: + +Developer guide +~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + exec_plan + hot_packages + murano_pl + murano_packages + murano_bundles + app_migrating + app_unit_tests + cinder_volume_supporting + multi_region + examples + use_cases + app_development_framework + app_debugging + garbage_collection \ No newline at end of file diff --git a/doc/source/appdev-guide/examples.rst b/doc/source/appdev-guide/developerguide/examples.rst similarity index 98% rename from doc/source/appdev-guide/examples.rst rename to doc/source/appdev-guide/developerguide/examples.rst index c1a001302..cc53912f8 100644 --- a/doc/source/appdev-guide/examples.rst +++ b/doc/source/appdev-guide/developerguide/examples.rst @@ -1,8 +1,5 @@ .. _examples: -.. toctree:: - :maxdepth: 2 - ======== Examples ======== diff --git a/doc/source/appdev-guide/exec_plan.rst b/doc/source/appdev-guide/developerguide/exec_plan.rst similarity index 99% rename from doc/source/appdev-guide/exec_plan.rst rename to doc/source/appdev-guide/developerguide/exec_plan.rst index fba670720..40e85085e 100644 --- a/doc/source/appdev-guide/exec_plan.rst +++ b/doc/source/appdev-guide/developerguide/exec_plan.rst @@ -1,8 +1,5 @@ .. _exec_plan: -.. toctree:: - :maxdepth: 2 - ======================= Execution plan template ======================= diff --git a/doc/source/appdev-guide/garbage_collection.rst b/doc/source/appdev-guide/developerguide/garbage_collection.rst similarity index 98% rename from doc/source/appdev-guide/garbage_collection.rst rename to doc/source/appdev-guide/developerguide/garbage_collection.rst index 605eb3139..c67d1f4ad 100644 --- a/doc/source/appdev-guide/garbage_collection.rst +++ b/doc/source/appdev-guide/developerguide/garbage_collection.rst @@ -1,4 +1,4 @@ -.. garbage_collection:: +.. garbage_collection: ===================================== Garbage collection system in MuranoPL @@ -46,7 +46,7 @@ the following will happen: Garbage collector methods ~~~~~~~~~~~~~~~~~~~~~~~~~ -Murano garbage collector class (``io.murano.system.GC`) has +Murano garbage collector class (``io.murano.system.GC``) has the following methods: ``collect()`` diff --git a/doc/source/appdev-guide/hotpackages/compose.rst b/doc/source/appdev-guide/developerguide/hot_packages.rst similarity index 63% rename from doc/source/appdev-guide/hotpackages/compose.rst rename to doc/source/appdev-guide/developerguide/hot_packages.rst index 23c09c92b..4f6a47438 100644 --- a/doc/source/appdev-guide/hotpackages/compose.rst +++ b/doc/source/appdev-guide/developerguide/hot_packages.rst @@ -1,3 +1,9 @@ +.. _hot-packages: + +============ +HOT packages +============ + .. _compose_package: Compose a package @@ -78,10 +84,64 @@ Application package could be composed manually. Follow the 5 steps below. `Browse` page looks like: -.. image:: /draft/appdev-guide/hotpackages/chef_server.png +.. image:: ../figures/chef_server.png The configuration form, where you can enter template parameters, will be generated automatically and looks as follows: -.. image:: /draft/appdev-guide/hotpackages/chef_server_form.png +.. image:: ../figures/chef_server_form.png After filling the form the application is ready to be deployed. + +Hot packages with nested Heat templates +--------------------------------------- + +In Murano HOT packages it is possible to allow Heat nested templates to be +saved and deployed as part of a Murano Heat applications. Such templates +should be placed in package under ‘/Resources/HotFiles’. Adding additional +templates to a package is optional. When a Heat generated package is being +deployed, if there are any Heat nested templates located in the package under +‘/Resources/HotFiles’, they are sent to Heat together with the main template +and params during stack creation. + +These nested templates can be referenced by putting the template name into the +``type`` attribute of resource definition, in the main template. This +mechanism then compose one logical stack with these multiple templates. The +following examples illustrate how you can use a custom template to define new +types of resources. These examples use a custom template stored in a +``sub_template.yaml`` file + + .. code-block:: yaml + + heat_template_version: 2015-04-30 + + parameters: + key_name: + type: string + description: Name of a KeyPair + + resources: + server: + type: OS::Nova::Server + properties: + key_name: {get_param: key_name} + flavor: m1.small + image: ubuntu-trusty + +Use the template filename as type +--------------------------------- + +The following main template defines the ``sub_template.yaml`` file as value for +the type property of a resource + + .. code-block:: yaml + + heat_template_version: 2015-04-30 + + resources: + my_server: + type: sub_template.yaml + properties: + key_name: my_key + +.. note:: + This feature is supported Liberty onwards. \ No newline at end of file diff --git a/doc/source/appdev-guide/multi_region.rst b/doc/source/appdev-guide/developerguide/multi_region.rst similarity index 99% rename from doc/source/appdev-guide/multi_region.rst rename to doc/source/appdev-guide/developerguide/multi_region.rst index a3f0bfc24..4f6c0a502 100644 --- a/doc/source/appdev-guide/multi_region.rst +++ b/doc/source/appdev-guide/developerguide/multi_region.rst @@ -110,7 +110,7 @@ The environment will create ``Network`` objects for regions from the ``ExistingNeutronNetwork`` template. Example: -.. code-block:: shell +.. code-block:: console OS_REGION_NAME="RegionOne" openstack network create OS_REGION_NAME="RegionTwo" openstack network create diff --git a/doc/source/appdev-guide/murano_bundles.rst b/doc/source/appdev-guide/developerguide/murano_bundles.rst similarity index 98% rename from doc/source/appdev-guide/murano_bundles.rst rename to doc/source/appdev-guide/developerguide/murano_bundles.rst index 5988b5632..bad3569ce 100644 --- a/doc/source/appdev-guide/murano_bundles.rst +++ b/doc/source/appdev-guide/developerguide/murano_bundles.rst @@ -1,8 +1,5 @@ .. _murano-bundles: -.. toctree:: - :maxdepth: 2 - ============== Murano bundles ============== diff --git a/doc/source/appdev-guide/developerguide/murano_packages.rst b/doc/source/appdev-guide/developerguide/murano_packages.rst new file mode 100644 index 000000000..75d44e6f8 --- /dev/null +++ b/doc/source/appdev-guide/developerguide/murano_packages.rst @@ -0,0 +1,12 @@ +.. _murano-packages: + +=============== +Murano packages +=============== + +.. toctree:: + :maxdepth: 1 + + muranopackages/package_structure + muranopackages/dynamic_ui + muranopackages/repository diff --git a/doc/source/appdev-guide/developerguide/murano_pl.rst b/doc/source/appdev-guide/developerguide/murano_pl.rst new file mode 100644 index 000000000..387da6c55 --- /dev/null +++ b/doc/source/appdev-guide/developerguide/murano_pl.rst @@ -0,0 +1,22 @@ +.. _murano-pl: + +================== +MuranoPL Reference +================== + +To develop applications, murano project refers to Murano Programming +Language (MuranoPL). It is represented by easily readable YAML and +YAQL languages. The sections below describe these languages. + +.. toctree:: + :maxdepth: 1 + + murano_pl/yaml + murano_pl/yaql + murano_pl/class_templ + murano_pl/core_lib + murano_pl/reflection + murano_pl/statics + murano_pl/metadata + murano_pl/versioning + murano_pl/actions \ No newline at end of file diff --git a/doc/source/appdev-guide/murano_pl/actions.rst b/doc/source/appdev-guide/developerguide/murano_pl/actions.rst similarity index 99% rename from doc/source/appdev-guide/murano_pl/actions.rst rename to doc/source/appdev-guide/developerguide/murano_pl/actions.rst index d4de1d971..03268218f 100644 --- a/doc/source/appdev-guide/murano_pl/actions.rst +++ b/doc/source/appdev-guide/developerguide/murano_pl/actions.rst @@ -1,6 +1,3 @@ -.. toctree:: - :maxdepth: 2 - .. _actions: ============== diff --git a/doc/source/appdev-guide/murano_pl/class_templ.rst b/doc/source/appdev-guide/developerguide/murano_pl/class_templ.rst similarity index 99% rename from doc/source/appdev-guide/murano_pl/class_templ.rst rename to doc/source/appdev-guide/developerguide/murano_pl/class_templ.rst index 05b49d0f9..64f4b4f24 100644 --- a/doc/source/appdev-guide/murano_pl/class_templ.rst +++ b/doc/source/appdev-guide/developerguide/murano_pl/class_templ.rst @@ -1,4 +1,3 @@ - .. _class_templ: Common class structure @@ -693,11 +692,4 @@ There are two ways to specify references: be defined elsewhere in an object tree. Object references distinguished from strings having the same value by evaluating property contracts. The former case would have ``$.class(Name)`` while the later - the - ``$.string()`` contract. - - - - - - - + ``$.string()`` contract. \ No newline at end of file diff --git a/doc/source/appdev-guide/murano_pl/core_lib.rst b/doc/source/appdev-guide/developerguide/murano_pl/core_lib.rst similarity index 100% rename from doc/source/appdev-guide/murano_pl/core_lib.rst rename to doc/source/appdev-guide/developerguide/murano_pl/core_lib.rst diff --git a/doc/source/appdev-guide/murano_pl/metadata.rst b/doc/source/appdev-guide/developerguide/murano_pl/metadata.rst similarity index 100% rename from doc/source/appdev-guide/murano_pl/metadata.rst rename to doc/source/appdev-guide/developerguide/murano_pl/metadata.rst diff --git a/doc/source/appdev-guide/murano_pl/reflection.rst b/doc/source/appdev-guide/developerguide/murano_pl/reflection.rst similarity index 100% rename from doc/source/appdev-guide/murano_pl/reflection.rst rename to doc/source/appdev-guide/developerguide/murano_pl/reflection.rst diff --git a/doc/source/appdev-guide/murano_pl/statics.rst b/doc/source/appdev-guide/developerguide/murano_pl/statics.rst similarity index 86% rename from doc/source/appdev-guide/murano_pl/statics.rst rename to doc/source/appdev-guide/developerguide/murano_pl/statics.rst index e0a03dfda..93b970ae8 100644 --- a/doc/source/appdev-guide/murano_pl/statics.rst +++ b/doc/source/appdev-guide/developerguide/murano_pl/statics.rst @@ -18,14 +18,15 @@ is, an object that represents the class rather than class instance. For any given class `foo.Bar` its type object may be retrieved using any of the following ways: - * Using ``ns:Bar`` notation considering that `ns` is declared in `Namespaces` - section (and it is `foo` in this case), - * Using ``:Bar`` syntax if `Bar` is in the current namespace (that is, what - ``=:Bar`` would mean if ``=`` was a valid namespace prefix), - * Using ``type()`` function with a fully qualified class name: ``type('foo.Bar')``, - * By obtaining a type of class instance: ``type($object)`` (available for - packages with format version starting from `1.3`), - * Through reflection: ``typeinfo($object).type``. + +* Using ``ns:Bar`` notation considering that `ns` is declared in `Namespaces` + section (and it is `foo` in this case), +* Using ``:Bar`` syntax if `Bar` is in the current namespace (that is, what + ``=:Bar`` would mean if ``=`` was a valid namespace prefix), +* Using ``type()`` function with a fully qualified class name: ``type('foo.Bar')``, +* By obtaining a type of class instance: ``type($object)`` (available for + packages with format version starting from `1.3`), +* Through reflection: ``typeinfo($object).type``. No matter what method was used to get type object, the returned object will be the same because there can be only one type object per class. @@ -157,10 +158,11 @@ Using extension lookup order When somewhere in the code the ``$foo.bar()`` expression is encountered, MuranoPL uses the following order to locate bar() ``implementation``: - - If there is an instance or static method in ``$foo``'s class, it will be used. - - Otherwise if the current class (where this expression was encountered) has - an extension method called ``bar`` and ``$foo`` satisfies the contract of - its first argument, then this method will be called. + +* If there is an instance or static method in ``$foo``'s class, it will be used. +* Otherwise if the current class (where this expression was encountered) has + an extension method called ``bar`` and ``$foo`` satisfies the contract of + its first argument, then this method will be called. Normally, if no method was found an exception will be raised. However, additional extension methods can be imported into the current context. This is diff --git a/doc/source/appdev-guide/murano_pl/versioning.rst b/doc/source/appdev-guide/developerguide/murano_pl/versioning.rst similarity index 100% rename from doc/source/appdev-guide/murano_pl/versioning.rst rename to doc/source/appdev-guide/developerguide/murano_pl/versioning.rst diff --git a/doc/source/appdev-guide/murano_pl/yaml.rst b/doc/source/appdev-guide/developerguide/murano_pl/yaml.rst similarity index 100% rename from doc/source/appdev-guide/murano_pl/yaml.rst rename to doc/source/appdev-guide/developerguide/murano_pl/yaml.rst diff --git a/doc/source/appdev-guide/murano_pl/yaql.rst b/doc/source/appdev-guide/developerguide/murano_pl/yaql.rst similarity index 100% rename from doc/source/appdev-guide/murano_pl/yaql.rst rename to doc/source/appdev-guide/developerguide/murano_pl/yaql.rst diff --git a/doc/source/appdev-guide/muranopackages/dynamic_ui.rst b/doc/source/appdev-guide/developerguide/muranopackages/dynamic_ui.rst similarity index 99% rename from doc/source/appdev-guide/muranopackages/dynamic_ui.rst rename to doc/source/appdev-guide/developerguide/muranopackages/dynamic_ui.rst index 3204afff7..e481178d3 100644 --- a/doc/source/appdev-guide/muranopackages/dynamic_ui.rst +++ b/doc/source/appdev-guide/developerguide/muranopackages/dynamic_ui.rst @@ -397,7 +397,7 @@ field attributes. The most common attributes are the following: have *expr* key, under that key either some `YAQL `_ expression is stored, either one-element dictionary with *regexpValidator* - key (and some regexp string as value). + key (and some regexp string as value). Another possible key of a validator dictionary is *message*, and although it is not required, it is highly desirable to specify it - otherwise, when validator fails (i.e. regexp doesn't match or YAQL expression evaluates to diff --git a/doc/source/appdev-guide/muranopackages/package_structure.rst b/doc/source/appdev-guide/developerguide/muranopackages/package_structure.rst similarity index 94% rename from doc/source/appdev-guide/muranopackages/package_structure.rst rename to doc/source/appdev-guide/developerguide/muranopackages/package_structure.rst index 648431d98..b34953508 100644 --- a/doc/source/appdev-guide/muranopackages/package_structure.rst +++ b/doc/source/appdev-guide/developerguide/muranopackages/package_structure.rst @@ -38,4 +38,4 @@ The application package root folder should contain the following: Here is the visual representation of the Murano application package structure: -.. image:: /draft/appdev-guide/muranopackages/structure.png +.. image:: ../../figures/structure.png diff --git a/doc/source/appdev-guide/muranopackages/repository.rst b/doc/source/appdev-guide/developerguide/muranopackages/repository.rst similarity index 100% rename from doc/source/appdev-guide/muranopackages/repository.rst rename to doc/source/appdev-guide/developerguide/muranopackages/repository.rst diff --git a/doc/source/appdev-guide/use_cases.rst b/doc/source/appdev-guide/developerguide/use_cases.rst similarity index 99% rename from doc/source/appdev-guide/use_cases.rst rename to doc/source/appdev-guide/developerguide/use_cases.rst index c0ea102e2..1582f1e58 100644 --- a/doc/source/appdev-guide/use_cases.rst +++ b/doc/source/appdev-guide/developerguide/use_cases.rst @@ -1,8 +1,5 @@ .. _use-cases: -.. toctree:: - :maxdepth: 2 - ========= Use-cases ========= diff --git a/doc/source/appdev-guide/faq.rst b/doc/source/appdev-guide/faq.rst index 401268eea..e4b5bf83a 100644 --- a/doc/source/appdev-guide/faq.rst +++ b/doc/source/appdev-guide/faq.rst @@ -1,8 +1,5 @@ .. _faq: -.. toctree:: - :maxdepth: 2 - === FAQ === diff --git a/doc/source/appdev-guide/hotpackages/chef_server.png b/doc/source/appdev-guide/figures/chef_server.png similarity index 100% rename from doc/source/appdev-guide/hotpackages/chef_server.png rename to doc/source/appdev-guide/figures/chef_server.png diff --git a/doc/source/appdev-guide/hotpackages/chef_server_form.png b/doc/source/appdev-guide/figures/chef_server_form.png similarity index 100% rename from doc/source/appdev-guide/hotpackages/chef_server_form.png rename to doc/source/appdev-guide/figures/chef_server_form.png diff --git a/doc/source/appdev-guide/logo.png b/doc/source/appdev-guide/figures/logo.png similarity index 100% rename from doc/source/appdev-guide/logo.png rename to doc/source/appdev-guide/figures/logo.png diff --git a/doc/source/appdev-guide/step_1.png b/doc/source/appdev-guide/figures/step_1.png similarity index 100% rename from doc/source/appdev-guide/step_1.png rename to doc/source/appdev-guide/figures/step_1.png diff --git a/doc/source/appdev-guide/step_2.png b/doc/source/appdev-guide/figures/step_2.png similarity index 100% rename from doc/source/appdev-guide/step_2.png rename to doc/source/appdev-guide/figures/step_2.png diff --git a/doc/source/appdev-guide/muranopackages/structure.png b/doc/source/appdev-guide/figures/structure.png similarity index 100% rename from doc/source/appdev-guide/muranopackages/structure.png rename to doc/source/appdev-guide/figures/structure.png diff --git a/doc/source/appdev-guide/muranopackages/structure.vdx b/doc/source/appdev-guide/figures/structure.vdx similarity index 100% rename from doc/source/appdev-guide/muranopackages/structure.vdx rename to doc/source/appdev-guide/figures/structure.vdx diff --git a/doc/source/appdev-guide/hot_packages.rst b/doc/source/appdev-guide/hot_packages.rst deleted file mode 100644 index 534ac3065..000000000 --- a/doc/source/appdev-guide/hot_packages.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. _hot-packages: - -============ -HOT packages -============ - -.. include:: hotpackages/compose.rst - -Hot packages with nested Heat templates ---------------------------------------- - -In Murano HOT packages it is possible to allow Heat nested templates to be -saved and deployed as part of a Murano Heat applications. Such templates -should be placed in package under ‘/Resources/HotFiles’. Adding additional -templates to a package is optional. When a Heat generated package is being -deployed, if there are any Heat nested templates located in the package under -‘/Resources/HotFiles’, they are sent to Heat together with the main template -and params during stack creation. - -These nested templates can be referenced by putting the template name into the -``type`` attribute of resource definition, in the main template. This -mechanism then compose one logical stack with these multiple templates. The -following examples illustrate how you can use a custom template to define new -types of resources. These examples use a custom template stored in a -``sub_template.yaml`` file - - .. code-block:: yaml - - heat_template_version: 2015-04-30 - - parameters: - key_name: - type: string - description: Name of a KeyPair - - resources: - server: - type: OS::Nova::Server - properties: - key_name: {get_param: key_name} - flavor: m1.small - image: ubuntu-trusty - -Use the template filename as type ---------------------------------- - -The following main template defines the ``sub_template.yaml`` file as value for -the type property of a resource - - .. code-block:: yaml - - heat_template_version: 2015-04-30 - - resources: - my_server: - type: sub_template.yaml - properties: - key_name: my_key - -.. note:: - This feature is supported Liberty onwards. \ No newline at end of file diff --git a/doc/source/appdev-guide/murano_packages.rst b/doc/source/appdev-guide/murano_packages.rst deleted file mode 100644 index 9af8dd551..000000000 --- a/doc/source/appdev-guide/murano_packages.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _murano-packages: - -.. toctree:: - :maxdepth: 2 - -=============== -Murano packages -=============== - -.. include:: muranopackages/package_structure.rst -.. include:: muranopackages/dynamic_ui.rst -.. include:: muranopackages/repository.rst diff --git a/doc/source/appdev-guide/murano_pl.rst b/doc/source/appdev-guide/murano_pl.rst deleted file mode 100644 index b6d71aba2..000000000 --- a/doc/source/appdev-guide/murano_pl.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _murano-pl: - -================== -MuranoPL Reference -================== - -.. toctree:: - :maxdepth: 2 - -To develop applications, murano project refers to Murano Programming -Language (MuranoPL). It is represented by easily readable YAML and -YAQL languages. The sections below describe these languages. - -.. include:: murano_pl/yaml.rst -.. include:: murano_pl/yaql.rst -.. include:: murano_pl/class_templ.rst -.. include:: murano_pl/core_lib.rst -.. include:: murano_pl/reflection.rst -.. include:: murano_pl/statics.rst -.. include:: murano_pl/metadata.rst -.. include:: murano_pl/versioning.rst -.. include:: murano_pl/actions.rst - diff --git a/doc/source/appdev-guide/step_by_step.rst b/doc/source/appdev-guide/step-by-step/step_by_step.rst similarity index 99% rename from doc/source/appdev-guide/step_by_step.rst rename to doc/source/appdev-guide/step-by-step/step_by_step.rst index b38857552..e7e084afa 100644 --- a/doc/source/appdev-guide/step_by_step.rst +++ b/doc/source/appdev-guide/step-by-step/step_by_step.rst @@ -1,8 +1,8 @@ .. _step-by-step: -============ -Step-by-Step -============ +================== +Step-by-step guide +================== The goal of this manual is to walk you through the steps that should be taken while composing an application package @@ -417,7 +417,7 @@ side of the form and its description on the right. Please take a look at the :guilabel:`Configure Application: Apache HTTP Server` dialog: -.. image:: step_1.png +.. image:: ../figures/step_1.png .. note:: The :guilabel:`assignFloatingIP` and :guilabel:`enablePHP` @@ -425,8 +425,7 @@ Please take a look at the :guilabel:`Configure Application: Apache HTTP Server` Here is how the second dialog looks like: -.. image:: step_2.png - +.. image:: ../figures/step_2.png For more information about Dynamic UI, please refer to :ref:`the main reference `. @@ -588,8 +587,7 @@ The recommended size is 70x70 px, and the square shape is preferable. There are no limits regarding the image filename. In Apache HTTP Server we use the default name ``logo.png``: -.. image:: logo.png - +.. image:: ../figures/logo.png Step 7. Compose a zip archive ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/appendix/appendix_index.rst b/doc/source/appendix/appendix_index.rst new file mode 100644 index 000000000..61e7575df --- /dev/null +++ b/doc/source/appendix/appendix_index.rst @@ -0,0 +1,54 @@ +Appendix +~~~~~~~~ + +.. toctree:: + :maxdepth: 2 + + murano_concepts + tutorials + rest_api_spec + cli_ref + glossary + +Miscellaneous +~~~~~~~~~~~~~ + +**Background Concepts for Murano** + +.. toctree:: + :maxdepth: 1 + + articles/workflow + + +**Tutorials** + +.. toctree:: + :maxdepth: 1 + + image_builders/index + articles/test_docs + + +**Guidelines** + +.. toctree:: + :maxdepth: 1 + + contributing + guidelines + +**Gerrit review dashboard** + +.. toctree:: + :maxdepth: 1 + + murano_gerrit_dashboard + + +**API specification** + +.. toctree:: + :maxdepth: 1 + + specification/index \ No newline at end of file diff --git a/doc/source/articles/ad-ui.rst b/doc/source/appendix/articles/ad-ui.rst similarity index 92% rename from doc/source/articles/ad-ui.rst rename to doc/source/appendix/articles/ad-ui.rst index 5e4033098..81cadb818 100644 --- a/doc/source/articles/ad-ui.rst +++ b/doc/source/appendix/articles/ad-ui.rst @@ -1,18 +1,3 @@ -.. - Copyright 2014 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 - 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. - .. _adUI: ============================================= diff --git a/doc/source/articles/multi_region.rst b/doc/source/appendix/articles/multi_region.rst similarity index 77% rename from doc/source/articles/multi_region.rst rename to doc/source/appendix/articles/multi_region.rst index 93d879329..da091c04b 100644 --- a/doc/source/articles/multi_region.rst +++ b/doc/source/appendix/articles/multi_region.rst @@ -1,18 +1,3 @@ -.. - Copyright 2016 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. - .. _multi-region: ============================= diff --git a/doc/source/articles/telnet.rst b/doc/source/appendix/articles/telnet.rst similarity index 87% rename from doc/source/articles/telnet.rst rename to doc/source/appendix/articles/telnet.rst index 19cd0d58e..d1786ad98 100644 --- a/doc/source/articles/telnet.rst +++ b/doc/source/appendix/articles/telnet.rst @@ -1,19 +1,3 @@ -.. - Copyright 2014 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 - 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. -.. - .. _TelnetUI: =================================== diff --git a/doc/source/articles/telnet_example.rst b/doc/source/appendix/articles/telnet_example.rst similarity index 72% rename from doc/source/articles/telnet_example.rst rename to doc/source/appendix/articles/telnet_example.rst index 741d05f26..2029b2402 100644 --- a/doc/source/articles/telnet_example.rst +++ b/doc/source/appendix/articles/telnet_example.rst @@ -1,16 +1,3 @@ -.. - 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. -.. .. _telnet-example: Telnet Example diff --git a/doc/source/articles/test_docs.rst b/doc/source/appendix/articles/test_docs.rst similarity index 100% rename from doc/source/articles/test_docs.rst rename to doc/source/appendix/articles/test_docs.rst diff --git a/doc/source/articles/workflow.rst b/doc/source/appendix/articles/workflow.rst similarity index 87% rename from doc/source/articles/workflow.rst rename to doc/source/appendix/articles/workflow.rst index 010d7cb8b..490e4590a 100644 --- a/doc/source/articles/workflow.rst +++ b/doc/source/appendix/articles/workflow.rst @@ -1,18 +1,3 @@ -.. - Copyright 2014 Hewlett-Packard Development Company, L.P. - - 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. - .. _murano-workflow: =============== diff --git a/doc/source/draft/appendix/cli_ref.rst b/doc/source/appendix/cli_ref.rst similarity index 92% rename from doc/source/draft/appendix/cli_ref.rst rename to doc/source/appendix/cli_ref.rst index 5d539d9bb..b5cc7622b 100644 --- a/doc/source/draft/appendix/cli_ref.rst +++ b/doc/source/appendix/cli_ref.rst @@ -1,8 +1,5 @@ .. _cli-ref: -.. toctree:: - :maxdepth: 2 - ========================== Murano command-line client ========================== @@ -42,7 +39,7 @@ Subcommands * *category-list* List all available categories. -* *category-show +* *category-show* * *deployment-list* List deployments for an environment. @@ -169,13 +166,13 @@ Murano optional arguments **--murano-repo-url MURANO_REPO_URL** Defaults to env[MURANO_REPO_URL] or - `http://storage.apps.openstack.org_ ` + `http://storage.apps.openstack.org_` Application catalog API v1 commands =================================== murano bundle-import --------------------- +~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -188,13 +185,13 @@ treat Names of packages in a bundle as file names, relative to location of bundle file. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** Bundle URL, bundle name, or path to the bundle file Optional arguments -~~~~~~~~~~~~~~~~~~ +------------------ **--is-public** Make packages available to users from other project @@ -203,7 +200,7 @@ Optional arguments Default action when a package already exists murano category-create ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -212,13 +209,13 @@ murano category-create Create a category. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** Category name murano category-delete ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -227,13 +224,13 @@ murano category-delete Delete a category. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** ID of a category(s) to delete murano category-list --------------------- +~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -242,20 +239,20 @@ murano category-list List all available categories. murano category-show --------------------- +~~~~~~~~~~~~~~~~~~~~ .. code-block::console usage: murano category-show Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** ID of a category(s) to show murano deployment-list ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -264,13 +261,13 @@ murano deployment-list List deployments for an environment. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** Environment ID for which to list deployments murano env-template-add-app ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -279,7 +276,7 @@ murano env-template-add-app Add application to the environment template. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** Environment template name @@ -288,7 +285,7 @@ Positional arguments Path to the template. murano env-template-create --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -297,12 +294,14 @@ murano env-template-create Create an environment template. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** Environment template name murano env-template-del-app +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block::console usage: murano env-template-del-app @@ -310,7 +309,7 @@ murano env-template-del-app Delete application to the environment template. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** Environment template ID @@ -319,7 +318,7 @@ Positional arguments Application ID murano env-template-delete --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -328,13 +327,13 @@ murano env-template-delete Delete an environment template. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** ID of environment(s) template to delete murano env-template-list ------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -343,7 +342,7 @@ murano env-template-list List the environments templates. murano env-template-show ------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -352,13 +351,13 @@ murano env-template-show Display environment template details. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** Environment template ID murano env-template-update --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -367,7 +366,7 @@ murano env-template-update Update an environment template. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** Environment template ID @@ -376,7 +375,7 @@ Positional arguments Environment template name murano environment-create -------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -385,13 +384,13 @@ murano environment-create Create an environment. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** Environment name murano environment-delete -------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -400,19 +399,19 @@ murano environment-delete Delete an environment. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** ID or name of environment(s) to delete Optional arguments -~~~~~~~~~~~~~~~~~~ +------------------ **--abandon** If set will abandon environment without deleting any of its resources murano environment-list ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -421,7 +420,7 @@ murano environment-list List the environments. murano environment-rename -------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -430,7 +429,7 @@ murano environment-rename Rename an environment. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** Environment ID or name @@ -439,7 +438,7 @@ Positional arguments A name to which the environment will be renamed murano environment-show ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -448,13 +447,13 @@ murano environment-show Display environment details. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** Environment ID or name murano package-create ---------------------- +~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -468,7 +467,7 @@ murano package-create Create an application package. Optional arguments -~~~~~~~~~~~~~~~~~~ +------------------ **-t , --template ** Path to the Heat template to import as an Application Definition @@ -507,7 +506,7 @@ Optional arguments Path to the package logo murano package-delete -=================== +~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -516,13 +515,13 @@ murano package-delete Delete a package. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** Package ID to delete murano package-download ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -531,7 +530,7 @@ murano package-download Download a package to a filename or stdout. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** Package ID to download @@ -540,7 +539,7 @@ Positional arguments Filename for download (defaults to stdout) murano package-import -===================== +~~~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -553,13 +552,13 @@ Import a package. ``FILE`` can be either a path to a zip file, URL or a FQPN. ``categories`` can be separated by a comma. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** URL of the murano zip package, FQPN, or path to zip package Optional arguments -~~~~~~~~~~~~~~~~~~ +------------------ **-c \[ \[ ...]], --categories \[ \[ ...]]** Category list to attach @@ -575,7 +574,7 @@ Optional arguments Default action when package already exists murano package-list -------------------- +~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -584,12 +583,12 @@ murano package-list List available packages. Optional arguments -~~~~~~~~~~~~~~~~~~ +------------------ **--include-disabled** murano package-show -=================== +~~~~~~~~~~~~~~~~~~~ .. code-block::console @@ -598,26 +597,26 @@ murano package-show Display details for a package. Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** Package ID to show murano service-show -------------------- +~~~~~~~~~~~~~~~~~~~ .. code-block::console usage: murano service-show \[-p ] Positional arguments -~~~~~~~~~~~~~~~~~~~~ +-------------------- **** Environment ID to show applications from Optional arguments -~~~~~~~~~~~~~~~~~~ +------------------ **-p , --path ** diff --git a/doc/source/appendix/contributing.rst b/doc/source/appendix/contributing.rst new file mode 100644 index 000000000..b1cd2f37d --- /dev/null +++ b/doc/source/appendix/contributing.rst @@ -0,0 +1 @@ +.. include:: ../../../CONTRIBUTING.rst diff --git a/doc/source/draft/appendix/glossary.rst b/doc/source/appendix/glossary.rst similarity index 58% rename from doc/source/draft/appendix/glossary.rst rename to doc/source/appendix/glossary.rst index 55d8ee820..0c1e38e76 100644 --- a/doc/source/draft/appendix/glossary.rst +++ b/doc/source/appendix/glossary.rst @@ -1,8 +1,5 @@ .. _glossary: -.. toctree:: - :maxdepth: 2 - ======== Glossary ======== diff --git a/doc/source/guidelines.rst b/doc/source/appendix/guidelines.rst similarity index 100% rename from doc/source/guidelines.rst rename to doc/source/appendix/guidelines.rst diff --git a/doc/source/appendix/image_builders/index.rst b/doc/source/appendix/image_builders/index.rst new file mode 100644 index 000000000..faa1d50fd --- /dev/null +++ b/doc/source/appendix/image_builders/index.rst @@ -0,0 +1,12 @@ +.. _building_images: + +===================== +Building Murano Image +===================== + +.. toctree:: + :maxdepth: 2 + + windows + linux + upload diff --git a/doc/source/image_builders/linux.rst b/doc/source/appendix/image_builders/linux.rst similarity index 70% rename from doc/source/image_builders/linux.rst rename to doc/source/appendix/image_builders/linux.rst index 86676f953..93de1eb33 100644 --- a/doc/source/image_builders/linux.rst +++ b/doc/source/appendix/image_builders/linux.rst @@ -1,18 +1,3 @@ -.. - 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 - 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. - =========== Linux Image =========== diff --git a/doc/source/image_builders/upload.rst b/doc/source/appendix/image_builders/upload.rst similarity index 81% rename from doc/source/image_builders/upload.rst rename to doc/source/appendix/image_builders/upload.rst index 1be2b0e2e..d1029bdcb 100644 --- a/doc/source/image_builders/upload.rst +++ b/doc/source/appendix/image_builders/upload.rst @@ -1,19 +1,3 @@ -.. - 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 - 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. -.. - .. _upload_images: ======================== diff --git a/doc/source/image_builders/windows.rst b/doc/source/appendix/image_builders/windows.rst similarity index 89% rename from doc/source/image_builders/windows.rst rename to doc/source/appendix/image_builders/windows.rst index b6c45571f..1ed749d70 100644 --- a/doc/source/image_builders/windows.rst +++ b/doc/source/appendix/image_builders/windows.rst @@ -1,18 +1,3 @@ -.. - 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 - 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. - MS Windows image builder for OpenStack Murano ============================================= diff --git a/doc/source/draft/appendix/murano_concepts.rst b/doc/source/appendix/murano_concepts.rst similarity index 82% rename from doc/source/draft/appendix/murano_concepts.rst rename to doc/source/appendix/murano_concepts.rst index b0524793f..627a52c81 100644 --- a/doc/source/draft/appendix/murano_concepts.rst +++ b/doc/source/appendix/murano_concepts.rst @@ -1,8 +1,5 @@ .. _murano-concepts: -.. toctree:: - :maxdepth: 2: - ========================================= High-level definitions of Murano concepts ========================================= diff --git a/doc/source/murano_gerrit_dashboard.rst b/doc/source/appendix/murano_gerrit_dashboard.rst similarity index 100% rename from doc/source/murano_gerrit_dashboard.rst rename to doc/source/appendix/murano_gerrit_dashboard.rst diff --git a/doc/source/draft/appendix/rest_api_spec.rst b/doc/source/appendix/rest_api_spec.rst similarity index 74% rename from doc/source/draft/appendix/rest_api_spec.rst rename to doc/source/appendix/rest_api_spec.rst index b6050be75..4f678f2e6 100644 --- a/doc/source/draft/appendix/rest_api_spec.rst +++ b/doc/source/appendix/rest_api_spec.rst @@ -1,8 +1,5 @@ .. _rest-api-spec: -.. toctree:: - :maxdepth: 2: - ====================== REST API specification ====================== diff --git a/doc/source/specification/index.rst b/doc/source/appendix/specification/index.rst similarity index 76% rename from doc/source/specification/index.rst rename to doc/source/appendix/specification/index.rst index d245cd633..b66b46a48 100644 --- a/doc/source/specification/index.rst +++ b/doc/source/appendix/specification/index.rst @@ -1,18 +1,3 @@ -.. - 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 - 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. - =========================== Murano API v1 specification =========================== diff --git a/doc/source/specification/murano-api.rst b/doc/source/appendix/specification/murano-api.rst similarity index 98% rename from doc/source/specification/murano-api.rst rename to doc/source/appendix/specification/murano-api.rst index 872ca29d2..f6004ac4a 100644 --- a/doc/source/specification/murano-api.rst +++ b/doc/source/appendix/specification/murano-api.rst @@ -1,22 +1,7 @@ -.. - 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 - 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. - Glossary ======== -.. _environment: +.. _glossary-environment: * **Environment** @@ -24,7 +9,7 @@ Glossary Applications within a single environment may comprise of complex configuration while applications in different environments are always independent from one another. Each environment is associated with a single OpenStack project. -.. _`sessions`: +.. _glossary-sessions: * **Session** @@ -325,8 +310,10 @@ Delete environment Environment configuration API ============================= -Multiple `sessions`_ could be opened for one environment simultaneously, but only one session going -to be deployed. First session that starts deploying is going to be deployed; other ones become invalid and could not be deployed at all. +Multiple :ref:`sessions ` could be opened for one environment +simultaneously, but only one session going to be deployed. First session that +starts deploying is going to be deployed; other ones become invalid and could +not be deployed at all. User could not open new session for environment that in *deploying* state (that’s why we call it "almost lock free" model). diff --git a/doc/source/specification/murano-env-temp.rst b/doc/source/appendix/specification/murano-env-temp.rst similarity index 97% rename from doc/source/specification/murano-env-temp.rst rename to doc/source/appendix/specification/murano-env-temp.rst index 8ea8b3ec1..2ec575176 100644 --- a/doc/source/specification/murano-env-temp.rst +++ b/doc/source/appendix/specification/murano-env-temp.rst @@ -1,18 +1,3 @@ -.. - Copyright 2015 Telefonica I+D, 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. - Environment template API ======================== diff --git a/doc/source/specification/murano-repository.rst b/doc/source/appendix/specification/murano-repository.rst similarity index 71% rename from doc/source/specification/murano-repository.rst rename to doc/source/appendix/specification/murano-repository.rst index b2fb3372f..bb8a56416 100644 --- a/doc/source/specification/murano-repository.rst +++ b/doc/source/appendix/specification/murano-repository.rst @@ -1,18 +1,3 @@ -.. - 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 - 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. - Application catalog API ======================= @@ -56,38 +41,54 @@ For an admin role all packages are available. **Parameters** -+----------------------+-------------+------------------------------------------------------------------------------------------------------------------------------+ -| Attribute | Type | Description | -+======================+=============+==============================================================================================================================+ -| ``catalog`` | bool | If false (default) - search packages, that current user can edit (own for non-admin, all for admin) | -| | | If true - search packages, that current user can deploy (i.e. his own + public) | -+----------------------+-------------+------------------------------------------------------------------------------------------------------------------------------+ -| ``marker`` | string | A package identifier marker may be specified. When present only packages which occur after the identifier ID will be listed | -+----------------------+-------------+------------------------------------------------------------------------------------------------------------------------------+ -| ``limit`` | string | When present the maximum number of results returned will not exceed the specified value. | -| | | The typical pattern of limit and marker is to make an initial limited request and then to use the ID of the last package from| -| | | the response as the marker parameter in a subsequent limited request. | -+----------------------+-------------+------------------------------------------------------------------------------------------------------------------------------+ -| ``order_by`` | string | Allows to sort packages by: `fqn`, `name`, `created`. Created is default value. | -+----------------------+-------------+------------------------------------------------------------------------------------------------------------------------------+ -| ``type`` | string | Allows to point a type of package: `application`, `library` | -+----------------------+-------------+------------------------------------------------------------------------------------------------------------------------------+ -| ``category`` | string | Allows to point a categories for a search | -+----------------------+-------------+------------------------------------------------------------------------------------------------------------------------------+ -| ``fqn`` | string | Allows to point a fully qualified package name for a search | -+----------------------+-------------+------------------------------------------------------------------------------------------------------------------------------+ -| ``owned`` | bool | Search only from packages owned by current project | -+----------------------+-------------+------------------------------------------------------------------------------------------------------------------------------+ -| ``id`` | string | Allows to point an id for a search | -+----------------------+-------------+------------------------------------------------------------------------------------------------------------------------------+ -| ``include_disabled`` | bool | Include disabled packages in a the result | -+----------------------+-------------+------------------------------------------------------------------------------------------------------------------------------+ -| ``search`` | string | Gives opportunity to search specified data by all the package parameters and order packages | -+----------------------+-------------+------------------------------------------------------------------------------------------------------------------------------+ -| ``class_name`` | string | Search only for packages, that use specified class | -+----------------------+-------------+------------------------------------------------------------------------------------------------------------------------------+ -| ``name`` | string | Allows to point a package name for a search | -+----------------------+-------------+------------------------------------------------------------------------------------------------------------------------------+ ++---------------------+--------+---------------------------------------------+ +| Attribute | Type | Description | ++=====================+========+=============================================+ +| ``catalog`` | bool | If false (default) - search packages, that | +| | | current user can edit (own for non-admin, | +| | | all for admin) | +| | | If true - search packages, that current user| +| | | can deploy (i.e. his own + public) | ++---------------------+--------+---------------------------------------------+ +| ``marker`` | string | A package identifier marker may be | +| | | specified. When present only packages which | +| | | occur after the identifier ID will be listed| ++---------------------+--------+---------------------------------------------+ +| ``limit`` | string | When present the maximum number of results | +| | | returned will not exceed the specified | +| | | value. The typical pattern of limit and | +| | | marker is to make an initial limited request| +| | | and then to use the ID of the last package | +| | | from the response as the marker parameter in| +| | | a subsequent limited request. | ++---------------------+--------+---------------------------------------------+ +| ``order_by`` | string | Allows to sort packages by: `fqn`, `name`, | +| | | `created`. Created is default value. | ++---------------------+--------+---------------------------------------------+ +| ``type`` | string | Allows to point a type of package: | +| | | `application`, `library` | ++---------------------+--------+---------------------------------------------+ +| ``category`` | string | Allows to point a categories for a search | ++---------------------+--------+---------------------------------------------+ +| ``fqn`` | string | Allows to point a fully qualified package | +| | | name for a search | ++---------------------+--------+---------------------------------------------+ +| ``owned`` | bool | Search only from packages owned by current | +| | | project | ++---------------------+--------+---------------------------------------------+ +| ``id`` | string | Allows to point an id for a search | ++---------------------+--------+---------------------------------------------+ +| ``include_disabled``| bool | Include disabled packages in a the result | ++---------------------+--------+---------------------------------------------+ +| ``search`` | string | Gives opportunity to search specified data | +| | | by all the package parameters and order | +| | | packages | ++---------------------+--------+---------------------------------------------+ +| ``class_name`` | string | Search only for packages, that use specified| +| | | class | ++---------------------+--------+---------------------------------------------+ +| ``name`` | string | Allows to point a package name for a search | ++---------------------+--------+---------------------------------------------+ **Response 200 (application/json)** @@ -430,12 +431,11 @@ List categories * `/v1/catalog/categories [GET]` - +----------+----------------------------------+----------------------------------+ - | Method | URI | Description | - +==========+==================================+==================================+ - | GET | /catalog/categories | Get list of existing categories | - +----------+----------------------------------+----------------------------------+ - + +----------+------------------------------+---------------------------------+ + | Method | URI | Description | + +==========+==============================+=================================+ + | GET | /catalog/categories | Get list of existing categories | + +----------+------------------------------+---------------------------------+ Retrieve list of all available application categories @@ -476,11 +476,11 @@ Get category details *Request* -+----------+-----------------------------------+----------------------------------+ -| Method | URI | Description | -+==========+===================================+==================================+ -| GET | /catalog/categories/ | Get category detail | -+----------+-----------------------------------+----------------------------------+ ++----------+-----------------------------------+-----------------------------+ +| Method | URI | Description | ++==========+===================================+=============================+ +| GET | /catalog/categories/ | Get category detail | ++----------+-----------------------------------+-----------------------------+ *Parameters* @@ -527,19 +527,20 @@ Add new category *Parameters* -+----------------------+------------+--------------------------------------------------------+ -| Attribute | Type | Description | -+======================+============+========================================================+ -| name | string | Environment name; only alphanumeric characters and '-' | -+----------------------+------------+--------------------------------------------------------+ ++----------------------+------------+----------------------------------------+ +| Attribute | Type | Description | ++======================+============+========================================+ +| name | string | Environment name; only alphanumeric | +| | | characters and '-' | ++----------------------+------------+----------------------------------------+ *Request* -+----------+----------------------------------+----------------------------------+ -| Method | URI | Description | -+==========+==================================+==================================+ -| POST | /catalog/categories | Create new category | -+----------+----------------------------------+----------------------------------+ ++----------+----------------------------------+------------------------------+ +| Method | URI | Description | ++==========+==================================+==============================+ +| POST | /catalog/categories | Create new category | ++----------+----------------------------------+------------------------------+ *Content-Type* application/json @@ -578,11 +579,12 @@ Delete category *Request* -+----------+-----------------------------------+-----------------------------------+ -| Method | URI | Description | -+==========+===================================+===================================+ -| DELETE | /catalog/categories/ | Delete category with specified id | -+----------+-----------------------------------+-----------------------------------+ ++----------+-----------------------------------+-----------------------------+ +| Method | URI | Description | ++==========+===================================+=============================+ +| DELETE | /catalog/categories/ | Delete category with | +| | | specified ID | ++----------+-----------------------------------+-----------------------------+ *Parameters:* diff --git a/doc/source/draft/appendix/tutorials.rst b/doc/source/appendix/tutorials.rst similarity index 88% rename from doc/source/draft/appendix/tutorials.rst rename to doc/source/appendix/tutorials.rst index cdb2514a9..08af588f0 100644 --- a/doc/source/draft/appendix/tutorials.rst +++ b/doc/source/appendix/tutorials.rst @@ -3,9 +3,6 @@ .. meta:: :robots: noindex -.. toctree:: - :maxdepth: 2 - ========= Tutorials ========= diff --git a/doc/source/articles/debug_tips.rst b/doc/source/articles/debug_tips.rst deleted file mode 100644 index ac56f3a36..000000000 --- a/doc/source/articles/debug_tips.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. - 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 - 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. - -===================================== -Murano TroubleShooting and Debug Tips -===================================== - -During installation and setting environment of new projects (tenants) you -can run into different problems. This section intends to reduce the time -spent on the solution of these problems. - -Problems during configuration -============================= - -Log location -++++++++++++ - -*Murano* is a multi component project, there several places where logs could be found. - -The location of the log file completely depends on the setting in the config file of the corresponding component. -*log_file* parameter points to the log file, and if it's omitted or commented logging will be sent to stdout. - - -Possible problem list -+++++++++++++++++++++++ - -* `murano-db-manage` failed to execute - - * Check `connection` parameter in provided config file. It should be a `connection string `_. - -* Murano Dashboard is not working - - * Make sure, that *prepare_murano.sh* script was executed and *murano* file located in *enabled* folder under openstack_dashboard repository. - * Check, that murano data is not inserted twice in the settings file and as a plugin. - - -Problems during deployment -========================== - -Besides identifying errors from log files, there is another and more flexible way to browse deployment errors - directly from UI. -After *Deploy Failed* status is appeared navigate to environment components and open *Deployment History* page. -Click on the *Show details* button located at the corresponding deployment row of the table. Then go to the *Logs* tab. -You can see steps of the deployments and the one that failed would have red color. - -* Deployment freeze after ``Begin execution: io.murano.system.Agent.call`` problem with connection between Murano Agent and spawned instance. - - * Need to check transport access to the virtual machine (check router has gateway). - * Check for rabbitMq settings: verify that agent has been obtained valid rabbit parameters. - Go to the spawned virtual machine and open */etc/murano/agent.conf* or *C:\Murano\Agent\agent.conf* on Windows-based machine. - Also, you can examine agent logs, located by default at */var/log/murano-agent.log* - The first part of the log file will contain reconnection attempts to the rabbit - since the valid rabbit address and queue have not been obtained yet. - * Check that *driver* option is set to `messagingv2` - * Check that linux image name is not starts with 'w' letter - -* ``[exceptions.EnvironmentError]: Unexpected stack state NOT_FOUND`` - problem with heat stack creation, need to examine Heat log file. - If you are running the deployment on a new tenant check that the router exists and it has gateway to the external network. -* ``Router could not be created, no external network found`` - Find `external_network` parameter in config file and check - that specified external network is really exist via UI or by executing :command:`openstack network list --external` command. -* ``NoPackageForClassFound: Package for class io.murano. Environment is not found`` - Check that murano core package is uploaded. - If no, the content of `meta/io.murano` folder should be zipped and uploaded to Murano. diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst deleted file mode 100644 index ac7b6bcf3..000000000 --- a/doc/source/contributing.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/contributor-guide/contributor_index.rst b/doc/source/contributor-guide/contributor_index.rst new file mode 100644 index 000000000..a5abd9234 --- /dev/null +++ b/doc/source/contributor-guide/contributor_index.rst @@ -0,0 +1,17 @@ +.. index:: Murano Contributor Guide + +.. _contributor-guide: + +Contributor guide +~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 2 + + how_to_contribute + dev_guidelines + plugins + dev_env + testing + doc_guidelines + stable_branches \ No newline at end of file diff --git a/doc/source/draft/contributor-guide/dev_env.rst b/doc/source/contributor-guide/dev_env.rst similarity index 74% rename from doc/source/draft/contributor-guide/dev_env.rst rename to doc/source/contributor-guide/dev_env.rst index 4946601de..8ac49d4e4 100644 --- a/doc/source/draft/contributor-guide/dev_env.rst +++ b/doc/source/contributor-guide/dev_env.rst @@ -1,8 +1,5 @@ .. _dev-env: -.. toctree:: - :maxdepth: 2 - ======================= Development environment ======================= diff --git a/doc/source/draft/contributor-guide/dev_guidelines.rst b/doc/source/contributor-guide/dev_guidelines.rst similarity index 97% rename from doc/source/draft/contributor-guide/dev_guidelines.rst rename to doc/source/contributor-guide/dev_guidelines.rst index fd9ac8996..ea9d3fc0b 100644 --- a/doc/source/draft/contributor-guide/dev_guidelines.rst +++ b/doc/source/contributor-guide/dev_guidelines.rst @@ -1,8 +1,5 @@ .. _dev-guidelines: -.. toctree:: - :maxdepth: 2 - ====================== Development guidelines ====================== diff --git a/doc/source/draft/contributor-guide/doc_guidelines.rst b/doc/source/contributor-guide/doc_guidelines.rst similarity index 76% rename from doc/source/draft/contributor-guide/doc_guidelines.rst rename to doc/source/contributor-guide/doc_guidelines.rst index 8b907cb42..54f7715a8 100644 --- a/doc/source/draft/contributor-guide/doc_guidelines.rst +++ b/doc/source/contributor-guide/doc_guidelines.rst @@ -1,8 +1,5 @@ .. _doc-guidelines: -.. toctree:: - :maxdepth: 2 - ======================== Documentation guidelines ======================== diff --git a/doc/source/draft/contributor-guide/how_to_contribute.rst b/doc/source/contributor-guide/how_to_contribute.rst similarity index 100% rename from doc/source/draft/contributor-guide/how_to_contribute.rst rename to doc/source/contributor-guide/how_to_contribute.rst diff --git a/doc/source/contributor-guide/plugins.rst b/doc/source/contributor-guide/plugins.rst new file mode 100644 index 000000000..5c1deff04 --- /dev/null +++ b/doc/source/contributor-guide/plugins.rst @@ -0,0 +1,19 @@ +.. _plugins: + +=============== +Murano plug-ins +=============== + +Murano plug-ins help to extend the capability of murano. +There are two types of murano plug-ins which serve different purposes: + +* Extend murano Core Library by implementing additional functionality. +* Add new package type classes. + +This section contains the following topics: + +.. toctree:: + :maxdepth: 2 + + plugins/murano_plugins + plugins/manage_plugins \ No newline at end of file diff --git a/doc/source/draft/contributor-guide/plugins.rst b/doc/source/contributor-guide/plugins/manage_plugins.rst similarity index 84% rename from doc/source/draft/contributor-guide/plugins.rst rename to doc/source/contributor-guide/plugins/manage_plugins.rst index 2bc10dbcb..5d45b894d 100644 --- a/doc/source/draft/contributor-guide/plugins.rst +++ b/doc/source/contributor-guide/plugins/manage_plugins.rst @@ -1,28 +1,7 @@ -.. _plugins: - -.. toctree:: - :maxdepth: 2 - -=============== -Murano plug-ins -=============== - -Murano plug-ins help to extend the capability of murano. - -Murano plug-in types -~~~~~~~~~~~~~~~~~~~~ - -There are two types of murano plug-ins which serve different purposes: - -* Extend murano Core Library by implementing additional functionality. -* Add new package type classes. - -.. include:: plugins/muranopl_extensions.rst - -.. include:: plugins/package_type_plugins.rst +.. _manage_plugins: Creating a Murano plug-in -~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- Murano plug-in is a setuptools-compliant python package with ``setup.py`` and all other necessary files. For more information about defining stevedore @@ -30,7 +9,7 @@ plug-ins, see `stevedore documentation `_. The structure of the demo application package ---------------------------------------------- ++++++++++++++++++++++++++++++++++++++++++++++ The package must meet the following requirements: @@ -58,7 +37,7 @@ SemVer three-component format (major.minor.patch). Missing version components are assumed to be zero (thus 1.0 becomes 1.0.0). Installing a plug-in -~~~~~~~~~~~~~~~~~~~~ +-------------------- To use a plug-in, install it on murano nodes in the same Python environment with murano engine service. @@ -78,7 +57,7 @@ To install a plug-in: the applications that use the capabilities that a plug-in provides. Plug-in versioning -~~~~~~~~~~~~~~~~~~ +------------------ Plug-ins located in Murano repository have the same version as Murano. Therefore, to use a specific version of such plug-in, checkout to this version. @@ -98,10 +77,10 @@ Major.Minor.Patch. For more information about versioning, refer to Enable Glare to use versioning. Organization -~~~~~~~~~~~~ +------------ Documentation -------------- ++++++++++++++ Documentation helps users understand what your plug-in does. For plug-ins located in the Murano repository, create a ``README.rst`` file in the main @@ -109,7 +88,7 @@ folder of the plug-in. The ``README.rst`` file may contain information about the plug-in and an installation guide. Code ----- +++++ The code of your plug-in may be located in the following repositories: @@ -119,7 +98,7 @@ The code of your plug-in may be located in the following repositories: * A separate repository. In this case, create your own project. Bugs ----- +++++ All bugs for specific plug-ins are reported in their projects. Bugs related to plug-ins located in Murano repository should be reported in the `Murano diff --git a/doc/source/draft/contributor-guide/plugins/package_type_plugins.rst b/doc/source/contributor-guide/plugins/murano_plugins.rst similarity index 75% rename from doc/source/draft/contributor-guide/plugins/package_type_plugins.rst rename to doc/source/contributor-guide/plugins/murano_plugins.rst index 404ba334c..36fca354e 100644 --- a/doc/source/draft/contributor-guide/plugins/package_type_plugins.rst +++ b/doc/source/contributor-guide/plugins/murano_plugins.rst @@ -1,9 +1,49 @@ +.. _muranopl_extensions: + +MuranoPL extension plug-ins +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Murano plug-ins allow extending MuranoPL with new classes. Therefore, using +such plug-ins applications with MuranoPL format, you access some additional +functionality defined in a plug-in. For example, the Magnum plug-in, which +allows murano to deploy applications such as Kubernetes using the capabilities +of the Magnum client. + +MuranoPL extension plug-ins can be used for the following purposes: + +* Providing interaction with external services. + + For example, you want to interact with the OpenStack Image service to get + information about images suitable for deployment. A plug-in may request image + data from glance during deployment, performing any necessary checks. + +* Enabling connections between murano applications and external hardware + + For example, you have an external load balancer located on a powerful + hardware and you want your applications launched in OpenStack to use that + load balancer. You can write a plug-in that interacts with the load balancer + API. Once done, add new apps to the pool of your load balancer or make any + other configurations from within your application definition. + +* Extending Core Library class functionality, which is responsible for creating + networks, interaction with murano-agent, and others + + For example, you want to create networks with special parameters for all of + your applications. You can just copy the class that is responsible for + network management from the Murano Core library, make the desired + modification, and load the new class as a plug-in. Both classes will be + available, and it is up to you to decide which way to create your networks. + +* Optimization of frequently used operations. Plug-in classes are written in + Python, therefore, the opportunity for improvement is significant. + + Murano provides a number of optimization opportunities depending on the + improvement needs. For example, classes in the Murano Core Library can be + rewritten in C and used from Python code to improve their performance in + particular use cases. + .. _package_type_plugins: -.. toctree:: - :maxdepth: 2 - - MuranoPL package type plug-ins ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -200,4 +240,4 @@ implementation of: This allows plug-in developers to concentrate on dynamic aspects of the package type plug-in while keeping all static aspects (descriptions, logos and so on) consistent across all package types (at least those who inherit from -`PackageBase`). +`PackageBase`). \ No newline at end of file diff --git a/doc/source/draft/contributor-guide/stable_branches.rst b/doc/source/contributor-guide/stable_branches.rst similarity index 99% rename from doc/source/draft/contributor-guide/stable_branches.rst rename to doc/source/contributor-guide/stable_branches.rst index 3cc959af7..255caa1f6 100644 --- a/doc/source/draft/contributor-guide/stable_branches.rst +++ b/doc/source/contributor-guide/stable_branches.rst @@ -1,8 +1,5 @@ .. _stable_branches: -.. toctree:: - :maxdepth: 2 - ============================== Backporting to stable/branches ============================== diff --git a/doc/source/draft/contributor-guide/testing.rst b/doc/source/contributor-guide/testing.rst similarity index 90% rename from doc/source/draft/contributor-guide/testing.rst rename to doc/source/contributor-guide/testing.rst index 4b289d370..adc82211c 100644 --- a/doc/source/draft/contributor-guide/testing.rst +++ b/doc/source/contributor-guide/testing.rst @@ -1,8 +1,5 @@ .. _testing: -.. toctree:: - :maxdepth: 2 - ======= Testing ======= diff --git a/doc/source/draft/contributor-guide/plugins/muranopl_extensions.rst b/doc/source/draft/contributor-guide/plugins/muranopl_extensions.rst deleted file mode 100644 index ebf0c6911..000000000 --- a/doc/source/draft/contributor-guide/plugins/muranopl_extensions.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _muranopl_extensions: - -.. toctree:: - :maxdepth: 2 - - -MuranoPL extension plug-ins -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Murano plug-ins allow extending MuranoPL with new classes. Therefore, using -such plug-ins applications with MuranoPL format, you access some additional -functionality defined in a plug-in. For example, the Magnum plug-in, which -allows murano to deploy applications such as Kubernetes using the capabilities -of the Magnum client. - -MuranoPL extension plug-ins can be used for the following purposes: - -* Providing interaction with external services. - - For example, you want to interact with the OpenStack Image service to get - information about images suitable for deployment. A plug-in may request image - data from glance during deployment, performing any necessary checks. - -* Enabling connections between murano applications and external hardware - - For example, you have an external load balancer located on a powerful - hardware and you want your applications launched in OpenStack to use that - load balancer. You can write a plug-in that interacts with the load balancer - API. Once done, add new apps to the pool of your load balancer or make any - other configurations from within your application definition. - -* Extending Core Library class functionality, which is responsible for creating - networks, interaction with murano-agent, and others - - For example, you want to create networks with special parameters for all of - your applications. You can just copy the class that is responsible for - network management from the Murano Core library, make the desired - modification, and load the new class as a plug-in. Both classes will be - available, and it is up to you to decide which way to create your networks. - -* Optimization of frequently used operations. Plug-in classes are written in - Python, therefore, the opportunity for improvement is significant. - - Murano provides a number of optimization opportunities depending on the - improvement needs. For example, classes in the Murano Core Library can be - rewritten in C and used from Python code to improve their performance in - particular use cases. diff --git a/doc/source/draft/index.rst b/doc/source/draft/index.rst deleted file mode 100644 index 2d30eef63..000000000 --- a/doc/source/draft/index.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. meta:: - :robots: noindex, nofollow - -.. _content: - -====================================== -Welcome to Murano Documentation (BETA) -====================================== - -**Murano** is an open source OpenStack project that -combines an application catalog with versatile -tooling to simplify and accelerate packaging and -deployment. It can be used with almost any application -and service in OpenStack. - -This documentation guides application developers -through the process of composing an application -package to get it ready for uploading to Murano. - -Besides the deployment rules and requirements, -it contains information on how to manage images, -categories, and repositories using the murano client that -will surely be helpful for cloud administrators. - -It also explains to end users how they can use the catalog -directly from the dashboard. These include guidance on how -to manage applications and environments. - -And of course, it provides information on how to contribute -to the project. - -Deploying Murano -~~~~~~~~~~~~~~~~ - -.. toctree:: - :maxdepth: 2 - - admin-guide/deploy_murano - admin-guide/prepare_lab - admin-guide/configuration - admin-guide/manage_packages - admin-guide/manage_images - admin-guide/manage_categories - admin-guide/murano_repository - admin-guide/murano_agent - admin-guide/policy_enf - admin-guide/configure_cloud_foundry_service_broker - admin-guide/using_glare.rst - admin-guide/admin_troubleshooting - -Contributing -~~~~~~~~~~~~ - -.. toctree:: - :maxdepth: 2 - - contributor-guide/how_to_contribute - contributor-guide/dev_guidelines - contributor-guide/plugins - contributor-guide/dev_env - contributor-guide/testing - contributor-guide/doc_guidelines - contributor-guide/stable_branches - -Appendix -~~~~~~~~ - -.. toctree:: - :maxdepth: 2 - - appendix/glossary - appendix/murano_concepts - appendix/tutorials - appendix/rest_api_spec - appendix/cli_ref diff --git a/doc/source/enduser-guide/quickstart.rst b/doc/source/enduser-guide/quickstart/quickstart.rst similarity index 91% rename from doc/source/enduser-guide/quickstart.rst rename to doc/source/enduser-guide/quickstart/quickstart.rst index 4340e22db..b03f334ab 100644 --- a/doc/source/enduser-guide/quickstart.rst +++ b/doc/source/enduser-guide/quickstart/quickstart.rst @@ -24,7 +24,7 @@ To upload an application to the catalog: #. Click on the :guilabel:`Import Package` button: - .. image:: figures/qs_package_import.png + .. image:: ../figures/qs_package_import.png :alt: Packages page :width: 600 px @@ -38,21 +38,21 @@ To upload an application to the catalog: * Click :guilabel:`Next` to continue: - .. image:: figures/qs_package_url.png + .. image:: ../figures/qs_package_url.png :width: 600 px :alt: Import Package dialog 1 #. View the package details in the new dialog, click :guilabel:`Next` to continue: - .. image:: figures/qs_package_details.png + .. image:: ../figures/qs_package_details.png :width: 600 px :alt: Import Package dialog 2 #. Select the :guilabel:`Application Servers` from the application category list, click :guilabel:`Create` to import the application package: - .. image:: figures/qs_app_category.png + .. image:: ../figures/qs_app_category.png :width: 600 px :alt: Import Package dialog 3 @@ -73,20 +73,20 @@ and deploy the environment: #. Click on the :guilabel:`Quick Deploy` button from the required application from the list. Lets deploy Apache HTTP Server, for example: - .. image:: figures/qs_apps.png + .. image:: ../figures/qs_apps.png :width: 600 px :alt: Applications page #. Check :guilabel:`Assign Floating IP` and click :guilabel:`Next` to proceed: - .. image:: figures/qs_quick_deploy.png + .. image:: ../figures/qs_quick_deploy.png :width: 600 px :alt: Configure Application dialog 1 #. Select the :guilabel:`Instance Image` from the drop-down list and click :guilabel:`Create`: - .. image:: figures/qs_quick_deploy_2.png + .. image:: ../figures/qs_quick_deploy_2.png :width: 600 px :alt: Configure Application dialog 2 @@ -95,7 +95,7 @@ and deploy the environment: Click the :guilabel:`Deploy This Environment` button to start the deployment: - .. image:: figures/qs_quick_env.png + .. image:: ../figures/qs_quick_env.png :width: 600 px :alt: Environment "quick-env-1" page @@ -132,5 +132,4 @@ To delete an application that belongs to the environment: Due to a known bug in Murano Kilo, resources allocated by a deleted application might not be reclaimed until the deletion of an environment. See `LP1417136 `_ - for the details. - + for the details. \ No newline at end of file diff --git a/doc/source/enduser-guide/user_index.rst b/doc/source/enduser-guide/user_index.rst new file mode 100644 index 000000000..145809377 --- /dev/null +++ b/doc/source/enduser-guide/user_index.rst @@ -0,0 +1,14 @@ +.. _user-guide: + +User guide +~~~~~~~~~~ + +.. toctree:: + :maxdepth: 2 + + userguide/manage_environments + userguide/manage_applications + userguide/log_in_to_murano_instance + userguide/use_cli + userguide/deploying_using_cli + ../../appendix/articles/multi_region \ No newline at end of file diff --git a/doc/source/enduser-guide/deploying_using_cli.rst b/doc/source/enduser-guide/userguide/deploying_using_cli.rst similarity index 100% rename from doc/source/enduser-guide/deploying_using_cli.rst rename to doc/source/enduser-guide/userguide/deploying_using_cli.rst diff --git a/doc/source/enduser-guide/install_client.rst b/doc/source/enduser-guide/userguide/install_client.rst similarity index 97% rename from doc/source/enduser-guide/install_client.rst rename to doc/source/enduser-guide/userguide/install_client.rst index 01fdc709e..ea5ba47e5 100644 --- a/doc/source/enduser-guide/install_client.rst +++ b/doc/source/enduser-guide/userguide/install_client.rst @@ -1,8 +1,5 @@ .. _install-client: -.. toctree:: - :maxdepth: 2 - Install and use the murano client ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/enduser-guide/log_in_to_murano_instance.rst b/doc/source/enduser-guide/userguide/log_in_to_murano_instance.rst similarity index 91% rename from doc/source/enduser-guide/log_in_to_murano_instance.rst rename to doc/source/enduser-guide/userguide/log_in_to_murano_instance.rst index b0c131687..ae925a456 100644 --- a/doc/source/enduser-guide/log_in_to_murano_instance.rst +++ b/doc/source/enduser-guide/userguide/log_in_to_murano_instance.rst @@ -1,8 +1,5 @@ .. _login-murano-instance: -.. toctree:: - :maxdepth: 2: - ================================= Log in to murano-spawned instance ================================= @@ -30,7 +27,7 @@ To log in to murano-spawned instance, perform the following steps: If you do not have a key pair, click the plus sign to create one directly from the :guilabel:`Configure Application` dialog. - .. image:: figures/add_key_pair.png + .. image:: ../figures/add_key_pair.png :alt: Application creation: key pair :width: 630 px @@ -39,7 +36,7 @@ To log in to murano-spawned instance, perform the following steps: * Deployment logs - .. image:: figures/app_logs.png + .. image:: ../figures/app_logs.png :alt: Application logs: IP is provided :width: 630 px @@ -48,7 +45,7 @@ To log in to murano-spawned instance, perform the following steps: See the :guilabel:`Instance name` link on the :guilabel:`Component Details` page. - .. image:: figures/app_details.png + .. image:: ../figures/app_details.png :alt: Application details: instance details link :width: 630 px diff --git a/doc/source/enduser-guide/manage_applications.rst b/doc/source/enduser-guide/userguide/manage_applications.rst similarity index 88% rename from doc/source/enduser-guide/manage_applications.rst rename to doc/source/enduser-guide/userguide/manage_applications.rst index 1c7378931..ae5bbb57c 100644 --- a/doc/source/enduser-guide/manage_applications.rst +++ b/doc/source/enduser-guide/userguide/manage_applications.rst @@ -1,8 +1,5 @@ .. _manage_applications: -.. toctree:: - :maxdepth: 2 - ===================== Managing applications ===================== @@ -40,7 +37,7 @@ Perform the following steps to import an application package from a #. Click the :guilabel:`Import Package` button on the top right of the page. - .. image:: figures/import_package.png + .. image:: ../figures/import_package.png :alt: Packages page: Import Package 1 :width: 630 px @@ -48,7 +45,7 @@ Perform the following steps to import an application package from a choose :guilabel:`File`, then click :guilabel:`Browse` to select a .zip file you want to import, and then click :guilabel:`Next`. - .. image:: figures/browse_zip_file.png + .. image:: ../figures/browse_zip_file.png :alt: Import Package dialog: zip file :width: 630 px @@ -58,7 +55,7 @@ Perform the following steps to import an application package from a necessary, verify and update the information about the package, then click the :guilabel:`Create` button. - .. image:: figures/add_pkg_info.png + .. image:: ../figures/add_pkg_info.png :alt: Import Package dialog: Description :width: 630 px @@ -93,7 +90,7 @@ murano applications repository: #. Click the :guilabel:`Import Package` button on the top right of the page. - .. image:: figures/import_package.png + .. image:: ../figures/import_package.png :alt: Packages page: Import Package 2 :width: 630 px @@ -102,7 +99,7 @@ murano applications repository: click :guilabel:`Next`. Note that you may also specify the version of the package. - .. image:: figures/repository.png + .. image:: ../figures/repository.png :alt: Import Package dialog: Repository :width: 630 px @@ -112,7 +109,7 @@ murano applications repository: necessary, verify and update the information about the package, then click the :guilabel:`Create` button. - .. image:: figures/add_pkg_info.png + .. image:: ../figures/add_pkg_info.png :alt: Import Package dialog: Description :width: 630 px @@ -135,7 +132,7 @@ Perform the following steps to import a bundle of applications: #. Click the :guilabel:`Import Bundle` button on the top right of the page. - .. image:: figures/import_bundle.png + .. image:: ../figures/import_bundle.png :alt: Packages page: Import Bundle :width: 630 px @@ -143,7 +140,7 @@ Perform the following steps to import a bundle of applications: :guilabel:`Repository`, enter the bundle name, and then click :guilabel:`Create`. - .. image:: figures/bundle_name.png + .. image:: ../figures/bundle_name.png :alt: Import Bundle dialog :width: 630 px @@ -168,14 +165,14 @@ The page is divided into two sections: To view all the applications of a specific category, select it from the :guilabel:`App Category` drop-down list: - .. image:: figures/app_category.png + .. image:: ../figures/app_category.png :alt: Applications page: App Category :width: 630 px To filter applications by tags or words from the application name or description, use the rightmost filter: - .. image:: figures/app_filter.png + .. image:: ../figures/app_filter.png :alt: Applications page: Filter :width: 630 px @@ -187,7 +184,7 @@ For example, there is an application that has the word *document-oriented* in description. Let's find it with the filter. The following screenshot shows you the result. - .. image:: figures/app_filter_example.png + .. image:: ../figures/app_filter_example.png :alt: Applications page: example :width: 630 px @@ -202,7 +199,7 @@ the following steps: #. Select a package or multiple packages you want to delete and click :guilabel:`Delete Packages`. - .. image:: figures/select_packages.png + .. image:: ../figures/select_packages.png :alt: Packages page: Select packages :width: 630 px @@ -240,7 +237,7 @@ From environment details page application into the :guilabel:`Drop Components here` field under the :guilabel:`Application Components` section. - .. image:: figures/add_to_env/drag_and_drop.png + .. image:: ../figures/add_to_env/drag_and_drop.png :alt: Environment Components page: Drag and drop a component :width: 630 px @@ -257,13 +254,13 @@ the Environment Components page. #. On the Environment Components page, click :guilabel:`Add Component`. - .. image:: figures/add_to_env/add_component.png + .. image:: ../figures/add_to_env/add_component.png :alt: Environment Components page: Add component :width: 630 px #. Find the application you want to add and click :guilabel:`Add to Env`. - .. image:: figures/add_to_env/add_to_env.png + .. image:: ../figures/add_to_env/add_to_env.png :alt: Applications page: Add to Env :width: 630 px @@ -275,7 +272,7 @@ the Environment Components page. then click :guilabel:`Create` and repeat the steps above. Otherwise, just click :guilabel:`Create`. - .. image:: figures/add_to_env/add_more_apps.png + .. image:: ../figures/add_to_env/add_more_apps.png :alt: Configure Application dialog: Add more applications :width: 630 px @@ -305,7 +302,7 @@ From applications catalog page #. Find the application you want to add and click :guilabel:`Quick Deploy`. Let's add Apache Tomcat, for example. - .. image:: figures/add_to_env/quick_deploy.png + .. image:: ../figures/add_to_env/quick_deploy.png :alt: Applications page: Quick Deploy :width: 630 px @@ -315,14 +312,14 @@ From applications catalog page :guilabel:`Next`, then click :guilabel:`Create`. In the example below we assign a floating IP address. - .. image:: figures/add_to_env/configure_app.png + .. image:: ../figures/add_to_env/configure_app.png :alt: Configure Application dialog :width: 630 px Now the Apache Tomcat application is successfully added to an automatically created ``quick-env-1`` environment. - .. image:: figures/add_to_env/quick_env.png + .. image:: ../figures/add_to_env/quick_env.png :alt: Environment Components page: Select packages :width: 630 px @@ -333,14 +330,14 @@ automatically created ``quick-env-1`` environment. #. From the :guilabel:`Environment` drop-down list, select the required environment. - .. image:: figures/add_to_env/add_from_cat.png + .. image:: ../figures/add_to_env/add_from_cat.png :alt: Applications page: Select environment :width: 630 px #. Find the application you want to add and click :guilabel:`Add to Env`. Let's add Apache Tomcat, for example. - .. image:: figures/add_to_env/add_to_env.png + .. image:: ../figures/add_to_env/add_to_env.png :alt: Applications page: Add to Env :width: 630 px @@ -349,7 +346,7 @@ automatically created ``quick-env-1`` environment. application author. In the example below we assign a floating IP address. - .. image:: figures/add_to_env/configure_app.png + .. image:: ../figures/add_to_env/configure_app.png :alt: Configure Application dialog :width: 630 px @@ -357,7 +354,7 @@ automatically created ``quick-env-1`` environment. to the environment`, then click :guilabel:`Create` and repeat the steps above. Otherwise, just click :guilabel:`Create`. - .. image:: figures/add_to_env/add_more_apps.png + .. image:: ../figures/add_to_env/add_more_apps.png :alt: Configure Application dialog: Add more applications :width: 630 px @@ -375,7 +372,7 @@ following one of the options below: #. Select :guilabel:`Deploy Environment` from the Actions drop-down list next to the environment you want to deploy. - .. image:: figures/deploy_env_2.png + .. image:: ../figures/deploy_env_2.png :width: 630 px :alt: Environments page @@ -390,14 +387,14 @@ following one of the options below: #. Click the name of the environment you want to deploy. - .. image:: figures/environments.png + .. image:: ../figures/environments.png :width: 630 px :alt: Environments page #. On the Environment Components page, click :guilabel:`Deploy This Environment` to start the deployment. - .. image:: figures/deploy_env.png + .. image:: ../figures/deploy_env.png :width: 630 px :alt: Environment Components page @@ -430,7 +427,7 @@ To browse a component details, perform the following steps: #. In the :guilabel:`Component List` section, click the name of the required component. - .. image:: figures/component-details.png + .. image:: ../figures/component-details.png :width: 630 px :alt: Components details @@ -458,25 +455,25 @@ The topology is helpful to visually display complex components, for example Kubernetes. The red icons reflect errors during the deployment while the green ones show success. -.. image:: figures/topology_kubernetes.png +.. image:: ../figures/topology_kubernetes.png :alt: Topology tab: Deployment failed :width: 630 px The following elements of the topology are virtual machine and an instance of dependent MuranoPL class: -+------------------------------------------+----------------------------+ -| Element | Meaning | -+==========================================+============================+ -| .. image:: figures/topology_element_1.png| Virtual machine | -+------------------------------------------+----------------------------+ -| .. image:: figures/topology_element_2.png| Instance | -+------------------------------------------+----------------------------+ ++---------------------------------------------+----------------------------+ +| Element | Meaning | ++=============================================+============================+ +| .. image:: ../figures/topology_element_1.png| Virtual machine | ++---------------------------------------------+----------------------------+ +| .. image:: ../figures/topology_element_2.png| Instance | ++---------------------------------------------+----------------------------+ Position your mouse pointer over an element to see its name, ID, and other details. -.. image:: figures/topology_wordpress.png +.. image:: ../figures/topology_wordpress.png :alt: Topology tab: Deployment successful :width: 630 px @@ -513,7 +510,7 @@ below: #. Click the :guilabel:`Logs` tab to see the logs. - .. image:: figures/logs.png + .. image:: ../figures/logs.png :alt: Deployment Logs page :width: 630 px @@ -546,7 +543,7 @@ steps below: #. Click the :guilabel:`Logs` tab to see the component logs. - .. image:: figures/env-component-logs.png + .. image:: ../figures/env-component-logs.png :alt: Component Logs page :width: 630 px @@ -561,7 +558,7 @@ To delete an application that belongs to the environment: #. Click on the name of the environment you want to delete an application from. - .. image:: figures/environments.png + .. image:: ../figures/environments.png :width: 630 px :alt: Environments page @@ -569,7 +566,7 @@ To delete an application that belongs to the environment: :guilabel:`Delete Component` button next to the application you want to delete. Then confirm the deletion. - .. image:: figures/delete_application.png + .. image:: ../figures/delete_application.png :width: 630 px :alt: Environment Components page diff --git a/doc/source/enduser-guide/manage_environments.rst b/doc/source/enduser-guide/userguide/manage_environments.rst similarity index 97% rename from doc/source/enduser-guide/manage_environments.rst rename to doc/source/enduser-guide/userguide/manage_environments.rst index dadc2f41e..be31ff95f 100644 --- a/doc/source/enduser-guide/manage_environments.rst +++ b/doc/source/enduser-guide/userguide/manage_environments.rst @@ -1,8 +1,5 @@ .. _manage-environments: -.. toctree:: - :maxdepth: 2 - ===================== Managing environments ===================== @@ -35,7 +32,7 @@ To create an environment, perform the following steps: specific network, if necessary, or leave the default :guilabel:`Create New` option to generate a new network. - .. image:: figures/env_default_network.png + .. image:: ../figures/env_default_network.png :alt: Create an environment: Environment Default Network :width: 630 px @@ -93,7 +90,7 @@ click the name of an environment or simply click the rightmost * Track a component status * Call murano actions of a particular application in a deployed environment: - .. figure:: figures/murano_actions.png + .. figure:: ../figures/murano_actions.png :width: 100% For more information on murano actions, see: diff --git a/doc/source/enduser-guide/use_cli.rst b/doc/source/enduser-guide/userguide/use_cli.rst similarity index 99% rename from doc/source/enduser-guide/use_cli.rst rename to doc/source/enduser-guide/userguide/use_cli.rst index 42dd6a881..4aa3db90c 100644 --- a/doc/source/enduser-guide/use_cli.rst +++ b/doc/source/enduser-guide/userguide/use_cli.rst @@ -1,8 +1,5 @@ .. _use-cli: -.. toctree:: - :maxdepth: 2 - ========= Using CLI ========= @@ -13,7 +10,10 @@ the Application Catalog through the command-line interface (CLI). Using python-muranoclient, the CLI client for murano, you can easily manage your environments, packages, categories, and deploy environments. -.. include:: install_client.rst +.. toctree:: + :maxdepth: 1 + + install_client Manage environments ~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/image_builders/index.rst b/doc/source/image_builders/index.rst deleted file mode 100644 index 489676b36..000000000 --- a/doc/source/image_builders/index.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. - 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 - 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. -.. - -.. _building_images: - -===================== -Building Murano Image -===================== - -.. toctree:: - :maxdepth: 2 - - windows - linux - upload diff --git a/doc/source/index.rst b/doc/source/index.rst index d063f05ba..1f6ec95f3 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,58 +1,25 @@ -.. - 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 - 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. - =============================== Welcome to Murano Documentation =============================== -**Murano** is an open source OpenStack project that -combines an application catalog with versatile -tooling to simplify and accelerate packaging and -deployment. It can be used with almost any application -and service in OpenStack. +**Murano** is an open source OpenStack project that combines an application +catalog with versatile tooling to simplify and accelerate packaging and +deployment. It can be used with almost any application and service in +OpenStack. Murano project consists of several source code repositories: -* `murano`_ - is the main repository. It contains code for Murano API server, +* `murano`_ -- 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 +* `murano-agent`_ -- the agent that runs on guest VMs and executes the + deployment plan. +* `murano-dashboard`_ -- Murano UI implemented as a plugin for the OpenStack Dashboard. -* `python-muranoclient`_ - Client library and CLI client for Murano. - -This documentation guides application developers -through the process of composing an application -package to get it ready for uploading to Murano. - -Besides the deployment rules and requirements, -it contains information on how to manage images, -categories, and repositories using the murano client that -will surely be helpful for cloud administrators. - -It also explains to end users how they can use the catalog -directly from the dashboard. These include guidance on how -to manage applications and environments. - -And it provides information on how to contribute to the project. +* `python-muranoclient`_ -- Client library and CLI client for Murano. .. note:: - `Deploying Murano` and `Contributing` guides are under development - at the moment. The most recently updated information is published - as the :ref:`BETA version of the Murano documentation `. - + `Administrator Documentation`, `Contributor Documentation`, and `Appendix` + are under development at the moment. .. Links @@ -66,106 +33,62 @@ Introduction to Murano ~~~~~~~~~~~~~~~~~~~~~~ .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - intro/key_features - intro/target_users - intro/architecture - intro/use_cases + intro/overview_index Using Murano ~~~~~~~~~~~~ -This guide provides murano end users with information on how they can use the -Application Catalog directly from the Dashboard and through the command-line -interface (CLI). The screenshots provided in this guide are of the Liberty -release. +Learn how to use the Application Catalog directly from the Dashboard and +through the command-line interface (CLI), manage applications and environments. +The screenshots provided in this guide are of the Liberty release. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - enduser-guide/quickstart - enduser-guide/manage_environments - enduser-guide/manage_applications - enduser-guide/log_in_to_murano_instance - enduser-guide/use_cli - enduser-guide/deploying_using_cli - articles/multi_region + enduser-guide/quickstart/quickstart + enduser-guide/user_index +Administrator Documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Developing Applications +Learn how to manage images, categories, and repositories using the Murano +client. + +.. toctree:: + :maxdepth: 1 + + administrator-guide/admin_index + +Developer Documentation ~~~~~~~~~~~~~~~~~~~~~~~ -.. toctree:: - :maxdepth: 2 +Learn how to compose an application package and get it ready for uploading to +Murano. - appdev-guide/step_by_step - appdev-guide/exec_plan - appdev-guide/hot_packages - appdev-guide/murano_pl - appdev-guide/murano_packages - appdev-guide/murano_bundles - appdev-guide/app_migrating - appdev-guide/app_unit_tests - appdev-guide/cinder_volume_supporting - appdev-guide/multi_region - appdev-guide/examples - appdev-guide/use_cases - appdev-guide/app_development_framework - appdev-guide/app_debugging - appdev-guide/garbage_collection +.. toctree:: + :maxdepth: 1 + + appdev-guide/step-by-step/step_by_step + appdev-guide/developerguide/developer_index appdev-guide/faq +Contributor Documentation +~~~~~~~~~~~~~~~~~~~~~~~~~ -Miscellaneous -~~~~~~~~~~~~~ - -**Background Concepts for Murano** +Learn how to contribute to the project. .. toctree:: :maxdepth: 1 - articles/workflow + contributor-guide/contributor_index - -**Tutorials** +Other Documentation +~~~~~~~~~~~~~~~~~~~ .. toctree:: :maxdepth: 1 - image_builders/index - articles/test_docs - - -**Guidelines** - -.. toctree:: - :maxdepth: 2 - - contributing - guidelines - articles/debug_tips - -**Gerrit review dashboard** - -.. toctree:: - :maxdepth: 1 - - murano_gerrit_dashboard - - -**API specification** - -.. toctree:: - :maxdepth: 1 - - specification/index - - -Indices and tables -~~~~~~~~~~~~~~~~~~ - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + appendix/appendix_index \ No newline at end of file diff --git a/doc/source/intro/architecture.rst b/doc/source/intro/architecture.rst index aa06b7bbd..86bdba899 100644 --- a/doc/source/intro/architecture.rst +++ b/doc/source/intro/architecture.rst @@ -34,5 +34,4 @@ The external services used by Murano are: creates heat templates based on application definitions. * the **Identity service** (Keystone) to make murano API available - to all OpenStack users. - + to all OpenStack users. \ No newline at end of file diff --git a/doc/source/intro/key_features.rst b/doc/source/intro/key_features.rst index a63b95fba..1a23bb7a8 100644 --- a/doc/source/intro/key_features.rst +++ b/doc/source/intro/key_features.rst @@ -1,8 +1,5 @@ .. _key-features: -.. toctree:: - :maxdepth: 2 - ============ Key features ============ diff --git a/doc/source/intro/overview_index.rst b/doc/source/intro/overview_index.rst new file mode 100644 index 000000000..61fe57004 --- /dev/null +++ b/doc/source/intro/overview_index.rst @@ -0,0 +1,12 @@ +.. _overview: + +Overview +~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + key_features + target_users + architecture + use_cases \ No newline at end of file diff --git a/doc/source/intro/target_users.rst b/doc/source/intro/target_users.rst index d6b19551f..1f319be07 100644 --- a/doc/source/intro/target_users.rst +++ b/doc/source/intro/target_users.rst @@ -1,7 +1,7 @@ .. _target_users: ============ -Target Users +Target users ============ Cloud end users want to simply use applications as diff --git a/doc/source/intro/use_cases.rst b/doc/source/intro/use_cases.rst index b53caca41..7375b4c19 100644 --- a/doc/source/intro/use_cases.rst +++ b/doc/source/intro/use_cases.rst @@ -1,7 +1,4 @@ -.. _use-cases: - -.. toctree:: - :maxdepth: 2 +.. _intro-use-cases: ========= Use cases