summaryrefslogtreecommitdiffstats
path: root/tosca2heat/heat-translator/doc
diff options
context:
space:
mode:
Diffstat (limited to 'tosca2heat/heat-translator/doc')
-rw-r--r--tosca2heat/heat-translator/doc/source/conf.py74
-rw-r--r--tosca2heat/heat-translator/doc/source/contributing.rst1
-rw-r--r--tosca2heat/heat-translator/doc/source/index.rst29
-rw-r--r--tosca2heat/heat-translator/doc/source/installation.rst15
-rw-r--r--tosca2heat/heat-translator/doc/source/usage.rst118
5 files changed, 0 insertions, 237 deletions
diff --git a/tosca2heat/heat-translator/doc/source/conf.py b/tosca2heat/heat-translator/doc/source/conf.py
deleted file mode 100644
index e051aeb..0000000
--- a/tosca2heat/heat-translator/doc/source/conf.py
+++ /dev/null
@@ -1,74 +0,0 @@
-# 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.
-
-import os
-import sys
-
-sys.path.insert(0, os.path.abspath('../..'))
-# -- General configuration ----------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = [
- 'sphinx.ext.autodoc',
- #'sphinx.ext.intersphinx',
- 'oslosphinx'
-]
-
-# autodoc generation is a bit aggressive and a nuisance when doing heavy
-# text edit cycles.
-# execute "export SPHINX_DEBUG=1" in your terminal to disable
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = u'heat-translator'
-copyright = u'2013, OpenStack Foundation'
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-add_module_names = True
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# -- Options for HTML output --------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages. Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-# html_theme_path = ["."]
-# html_theme = 'default'
-# html_static_path = ['static']
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = '%sdoc' % project
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass
-# [howto/manual]).
-latex_documents = [
- ('index',
- '%s.tex' % project,
- u'%s Documentation' % project,
- u'OpenStack Foundation', 'manual'),
-]
-
-# Example configuration for intersphinx: refer to the Python standard library.
-#intersphinx_mapping = {'http://docs.python.org/': None}
diff --git a/tosca2heat/heat-translator/doc/source/contributing.rst b/tosca2heat/heat-translator/doc/source/contributing.rst
deleted file mode 100644
index 8cb3146..0000000
--- a/tosca2heat/heat-translator/doc/source/contributing.rst
+++ /dev/null
@@ -1 +0,0 @@
-.. include:: ../../CONTRIBUTING.rst \ No newline at end of file
diff --git a/tosca2heat/heat-translator/doc/source/index.rst b/tosca2heat/heat-translator/doc/source/index.rst
deleted file mode 100644
index dd3f04f..0000000
--- a/tosca2heat/heat-translator/doc/source/index.rst
+++ /dev/null
@@ -1,29 +0,0 @@
-.. heat-translator documentation master file, created by
- sphinx-quickstart on Tue Jul 9 22:26:36 2013.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
-
-Welcome to heat-translator's documentation!
-===========================================
-
-The heat-translator tool is aimed to translate non-heat templates to OpenStack
-Heat Orchestration Template (HOT). Initially the tool is aimed to translate
-OASIS Topology and Orchestration Specification for Cloud Applications (TOSCA)
-to HOT. However, the tool can be easily extended to support any non-heat
-template format to produce HOT.
-
-Contents:
-
-.. toctree::
- :maxdepth: 2
-
- installation
- usage
- contributing
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/tosca2heat/heat-translator/doc/source/installation.rst b/tosca2heat/heat-translator/doc/source/installation.rst
deleted file mode 100644
index 71c5237..0000000
--- a/tosca2heat/heat-translator/doc/source/installation.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-============
-Installation
-============
-
-Assuming that OpenStackClient (OSC) is available in your environment, you can easily install Heat-Translator to use with OSC by following three steps::
-
- git clone https://github.com/openstack/heat-translator
- cd heat-translator
- sudo python setup.py install
-
-You can also clone the project and use it without any specific OpenStack environment set up as below::
-
- git clone https://github.com/openstack/heat-translator
-
-Heat-Translator can be installed via PyPI package as well. Refer to https://pypi.python.org/pypi/heat-translator for available packages.
diff --git a/tosca2heat/heat-translator/doc/source/usage.rst b/tosca2heat/heat-translator/doc/source/usage.rst
deleted file mode 100644
index 383c696..0000000
--- a/tosca2heat/heat-translator/doc/source/usage.rst
+++ /dev/null
@@ -1,118 +0,0 @@
-=====
-Usage
-=====
-
-Use Heat-Translator with OpenStackClient (OSC)
-----------------------------------------------
-Assuming that OpenStackClient (OSC) is available in your environment, you can easily install Heat-Translator to use with OSC by following three steps::
-
- git clone https://github.com/openstack/heat-translator
- cd heat-translator
- sudo python setup.py install
-
-Alternatively, you can install a particular release of Heat-Translator as available at https://pypi.python.org/pypi/heat-translator.
-
-Once installation is complete, Heat-Translator is ready to use. The only required argument is ``--template-file``. By default, the ``--template-type`` is set to ``tosca`` which is the
-only supported template type at present. Currently you can use Heat-Translator in following three ways.
-
-Translate and get output on command line. For example: ::
-
- openstack translate template --template-file /home/openstack/heat-translator/translator/tests/data/tosca_helloworld.yaml --template-type tosca
-
-Translate and save output of translated file to a desired destination. For example: ::
-
- openstack translate template --template-file /home/openstack/heat-translator/translator/tests/data/tosca_helloworld.yaml --template-type tosca --output-file /tmp/hot_hello_world.yaml
-
-Do not translate but only validate template file. For example: ::
-
- openstack translate template --template-file /home/openstack/heat-translator/translator/tests/data/tosca_helloworld.yaml --template-type tosca --validate-only=true
-
-You can learn more about available options by running following help command::
-
- openstack help translate template
-
-
-Use Heat-Translator on its own
-------------------------------
-Heat-Translator can be used without any specific OpenStack environment set up as below::
-
- git clone https://github.com/openstack/heat-translator
- python heat_translator.py --template-file==<path to the YAML template> --template-type=<type of template e.g. tosca> --parameters="purpose=test"
-
-The heat_translator.py test program is at the root level of the project. The program has currently tested with TOSCA templates.
-The only required argument is ``--template-file``. By default, the ``--template-type`` is set to ``tosca`` which is the only supported template type at present.
-The value to the ``--template-file`` is a path to the file that needs to be translated. The file, flat YAML template or CSAR, can be specified as a local file in your
-system or via URL.
-
-For example, a TOSCA hello world template can be translated by running the following command from the project location::
-
- python heat_translator.py --template-file=translator/tests/data/tosca_helloworld.yaml
-
-This should produce a translated Heat Orchestration Template on the command line. The translated content can be saved to a desired file by setting --output-file=<path>.
-For example: ::
-
- python heat_translator.py --template-file=translator/tests/data/tosca_helloworld.yaml --template-type=tosca --output-file=/tmp/hot_helloworld.yaml
-
-An optional argument can be provided to handle user inputs parameters. Also, a template file can only be validated instead of translation by using --validate-only=true
-optional argument. The command below shows an example usage::
-
- python heat_translator.py --template-file=<path to the YAML template> --template-type=<type of template e.g. tosca> --validate-only=true
-
-Alternatively, you can install a particular release of Heat-Translator as available at https://pypi.python.org/pypi/heat-translator.
-In this case, you can simply run translation via CLI entry point::
- heat-translator --template-file=translator/tests/data/tosca_helloworld.yaml --template-type=tosca
-
-Things To Consider
-------------------
-* When use Heat-Translator in an OpenStack environment, please ensure that you have one or more preferred flavors and images available in your OpenStack
- environment. To find an appropriate flavor and image, that meets constraints defined in the TOSCA template for the HOST and OS capabilities of TOSCA Compute node,
- the Heat-Translator project first runs a query against Nova flavors and Glance images. During the query call, it uses the metadata of flavors and images.
- If call to Nova or Glance can not be made or no flavor or image is found, the Heat-Translator project will set flavor and image from a pre-defined set of values (as listed in /home/openstack/heat-translator/translator/hot/tosca/tosca_compute.py)
- with the best possible match to the constraints defined in the TOSCA template.
-* The ``key_name`` property of Nova server is irrelevant to the TOSCA specification and can not be used in TOSCA template. In order to use it in
- the translated templates, the user must provide it via parameters, and the heat-translator will set it to all resources of ``OS::Nova::Server`` type.
-* Since properties of TOSCA Compute OS and HOST capabilities are optional, the user should make sure that either they set these properties correctly
- in the TOSCA template or provide them via CLI parameters in order to find best match of flavor and image.
-* The ``flavor`` and ``image`` properties of ``OS::Nova::Server`` resource is irrelevant to the TOSCA specification and can not be used in the TOSCA
- template as such. Heat-Translator sets these properties in the translated template based on constraints defined per TOSCA Compute OS and HOST
- capabilities. However, user may required to use these properties in template in certain circumstances, so in that case, TOSCA Compute can be extended
- with these properties and later used in the node template. For a good example, refer to the ``translator/tests/data/test_tosca_flavor_and_image.yaml`` test
- template.
-* The Heat-Translator can be used to automatically deploy translated TOSCA template given that your environment has python-heatclient and python-keystoneclient.
- This can be achieved by providing ``--deploy`` argument to the Heat-Translator. You can provide desired stack name by providing it as ``--stack-name <name>``
- argument. If you do not provide ``--stack-name``, an unique name will be created and used.
- Below is an example command to deploy translated template with a desired stack name::
- heat-translator --template-file translator/tests/data/tosca_helloworld.yaml --stack-name mystack --deploy
-* The Heat-Translator supports translation of TOSCA templates to Heat Senlin
- resources (e.g. ``OS::Senlin::Cluster``) but that requires to use a specific
- TOSCA node type called ``tosca.policies.Scaling.Cluster``.
- The ``tosca.policies.Scaling.Cluster`` is a custom type that derives from
- ``tosca.policies.Scaling``. For example usage, refer to the
- ``tosca_cluster_autoscaling.yaml`` and ``hot_cluster_autoscaling.yaml``
- provided under the ``translator/tests/data/autoscaling`` and
- ``translator/tests/data/hot_output/autoscaling`` directories respectively in
- the heat-translator project (``https://github.com/openstack/heat-translator``).
- When you use ``tosca.policies.Scaling`` normative node type, the
- Heat-Translator will translate it to ``OS::Heat::AutoScalingGroup`` Heat
- resource. Related example templates, ``tosca_autoscaling.yaml`` and
- ``hot_autoscaling.yaml`` can be found for reference purposes under the same
- directory structure mentioned above.
-* With the version 0.7.0 of Heat-Translator, output of multiple template files
- (for example, nested templates in autoscaling) can be accessed via newly
- introduced API called ``translate_to_yaml_files_dict(<output_filename>)``
- where ``<output_filename>`` is the name of file where you want to store parent
- HOT template. The return value of this API call will be a dictionary in HOT
- YAML with one or multiple file names as keys and translated content as values.
- In order to use this on the command line, simply invoke Heat-Translator with
- ``--output-file`` argument. Here, the parent template will be stored in the
- value specified to the ``--output-file``. Whereas, child templates, if any,
- will be saved at the same location of the parent template.
-
- Below is an example of how to call the API in your code, where
- ``translator`` is an instance of Heat-Translator::
-
- yaml_files = translator.translate_to_yaml_files_dict(filename)
-
- Below is an example of how to use this on the command line::
-
- heat-translator --template-file translator/tests/data/autoscaling/tosca_autoscaling.yaml --output-file /tmp/hot.yaml \ No newline at end of file