tosca2heat/heat-translator/doc/source/usage.rst

   1 =====
   2 Usage
   3 =====
   4
   5 Use Heat-Translator with OpenStackClient (OSC)
   6 ----------------------------------------------
   7 Assuming that OpenStackClient (OSC) is available in your environment, you can easily install Heat-Translator to use with OSC by following three steps::
   8
   9     git clone https://github.com/openstack/heat-translator
  10     cd heat-translator
  11     sudo python setup.py install
  12
  13 Alternatively, you can install a particular release of Heat-Translator as available at https://pypi.python.org/pypi/heat-translator.
  14
  15 Once installation is complete, Heat-Translator is ready to use. Currently you can use it in following three ways.
  16
  17 Translate and get output on command line. For example: ::
  18
  19     openstack translate template --template-file /home/openstack/heat-translator/translator/tests/data/tosca_helloworld.yaml --template-type tosca
  20
  21 Translate and save output of translated file to a desired destination. For example: ::
  22
  23     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
  24
  25 Do not translate but only validate template file. For example: ::
  26
  27     openstack translate template --template-file /home/openstack/heat-translator/translator/tests/data/tosca_helloworld.yaml --template-type tosca --validate-only=true
  28
  29 You can learn more about available options by running following help command::
  30
  31     openstack help translate template
  32
  33
  34 Use Heat-Translator on its own
  35 ------------------------------
  36 Heat-Translator can be used without any specific OpenStack environment set up as below::
  37
  38     git clone https://github.com/openstack/heat-translator
  39     python heat_translator.py --template-file==<path to the YAML template> --template-type=<type of template e.g. tosca> --parameters="purpose=test"
  40
  41 The heat_translator.py test program is at the root level of the project. The program has currently tested with TOSCA templates.
  42 It requires two arguments::
  43
  44 1. 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
  45 system or via URL.
  46 2. Type of translation (e.g. tosca)
  47
  48 For example, a TOSCA hello world template can be translated by running the following command from the project location::
  49
  50     python heat_translator.py --template-file=translator/tests/data/tosca_helloworld.yaml --template-type=tosca
  51
  52 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>.
  53 For example: ::
  54
  55     python heat_translator.py --template-file=translator/tests/data/tosca_helloworld.yaml --template-type=tosca --output-file=/tmp/hot_helloworld.yaml
  56
  57 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
  58 optional argument. The command below shows an example usage::
  59
  60     python heat_translator.py --template-file==<path to the YAML template> --template-type=<type of template e.g. tosca> --validate-only=true
  61
  62 Alternatively, you can install a particular release of Heat-Translator as available at https://pypi.python.org/pypi/heat-translator.
  63 In this case, you can simply run translation via CLI entry point::
  64     heat-translator --template-file=translator/tests/data/tosca_helloworld.yaml --template-type=tosca
  65
  66 Things To Consider
  67 ------------------
  68 * When use Heat-Translator in an OpenStack environment, please ensure that you have one or more preferred flavors and images available in your OpenStack
  69   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,
  70   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.
  71   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)
  72   with the best possible match to the constraints defined in the TOSCA template.
  73 * 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
  74   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.
  75 * Since properties of TOSCA Compute OS and HOST capabilities are optional, the user should make sure that either they set these properties correctly
  76   in the TOSCA template or provide them via CLI parameters in order to find best match of flavor and image.
  77 * The ``flavor`` and ``image`` properties of ``OS::Nova::Server`` resource is irrelevant to the TOSCA specification and can not be used in the TOSCA
  78   template as such. Heat-Translator sets these properties in the translated template based on constraints defined per TOSCA Compute OS and HOST
  79   capabilities. However, user may required to use these properties in template in certain circumstances, so in that case, TOSCA Compute can be extended
  80   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
  81   template.
  82