From 98f9b120fb493e6749b727ab6c5d67efb48aa134 Mon Sep 17 00:00:00 2001 From: Marios Andreou Date: Thu, 4 Apr 2019 15:11:45 +0300 Subject: [PATCH] Adds python-tripleoclient/tripleo-common primer developer docs Adds a primer for python-tripleoclient - where and how tripleo commands are defined. Change-Id: Ic5623ca18a6ea6710c660d7eb96c4e036acfb2c1 Related-Bug: 1804642 --- doc/source/developer/index.rst | 1 + doc/source/developer/tripleoclient_primer.rst | 136 ++++++++++++++++++ 2 files changed, 137 insertions(+) create mode 100644 doc/source/developer/tripleoclient_primer.rst diff --git a/doc/source/developer/index.rst b/doc/source/developer/index.rst index 9687d825..f2a32e51 100644 --- a/doc/source/developer/index.rst +++ b/doc/source/developer/index.rst @@ -8,5 +8,6 @@ Documentation of developer-specific options in |project|. tht_walkthrough/tht_walkthrough release + tripleoclient_primer mistral_workflows/00-index ../upgrade/developer/upgrades/upgrades diff --git a/doc/source/developer/tripleoclient_primer.rst b/doc/source/developer/tripleoclient_primer.rst new file mode 100644 index 00000000..3e931c5e --- /dev/null +++ b/doc/source/developer/tripleoclient_primer.rst @@ -0,0 +1,136 @@ +Primer python-tripleoclient and tripleo-common +============================================== + +This document gives an overview of how python-tripleoclient_ provides the +cli interface for TripleO. In particular it focuses on two key aspects of +TripleO commands: where they are defined and how they (very basically) work. + +Whilst python-tripleoclient provides the CLI for TripleO, it is in +tripleo-common_ that the logic behind a given command resides. So interfacing +with OpenStack services such as Heat, Nova or Mistral typically happens in +tripleo-common. + +For this primer we will use a specific example command but the same applies to +any TripleO cli command to be found in the TripleO documentation or in any +local deployment (or even in TripleO CI) logfiles. + +The example used here is:: + + openstack overcloud container image build + +This command is used to build the container images listed in the +tripleo-common file overcloud_containers.yaml_ using Kolla_. See :doc:`Building +Containers` for more information on +how to use this command as an operator. + +One of the TipleO CI jobs that executes this command is the +tripleo-build-containers-centos-7_ job. This job invokes the overcloud container +image build command in the build.sh.j2_ template:: + + openstack overcloud container image build \ + --config-file $TRIPLEO_COMMON_PATH/container-images/overcloud_containers.yaml \ + --kolla-config-file {{ workspace }}/kolla-build.conf \ + +The relevance of showing this is simply to serve as an example in the following +sections. First we see how to identify *where* in the tripleoclient code a given +command is defined, and then *how* the command works, highlighting a recurring +pattern common to all TripleO commands. + +.. _python-tripleoclient: https://git.openstack.org/cgit/openstack/python-tripleoclient/ +.. _tripleo-common: https://git.openstack.org/cgit/openstack/tripleo-common/ +.. _overcloud_containers.yaml: https://git.openstack.org/cgit/openstack/tripleo-common/tree/container-images/overcloud_containers.yaml?id=827af753884e15326863ff2207b2ac95d4ad595b#n1 +.. _Kolla: https://git.openstack.org/cgit/openstack/kolla +.. _tripleo-build-containers-centos-7: http://zuul.openstack.org/builds?job_name=tripleo-build-containers-centos-7 +.. _build.sh.j2: https://git.openstack.org/cgit/openstack-infra/tripleo-ci/tree/playbooks/tripleo-buildcontainers/templates/build.sh.j2?id=69212e1cd8726396c232b493f1aec79480459666#n5 +.. _setup.cfg: https://git.openstack.org/cgit/openstack/python-tripleoclient/tree/setup.cfg?id=73cc43898cfcc8b99ce736f734fc5b514f5bc6e9#n46 + + +TripleO commands: *where* +------------------------- + +Luckily the location of all TripleO commands is given in the list of +``entry_points`` in the python-tripleoclient_ setup.cfg_ file. Each *key=value* +pair has a key derived from the TripleO command. Taking the command, omit +the initial *openstack* and link subcommands with underscore instead of +whitespace. That is, for the +**openstack overcloud container image build** command the equivalent entry is +**overcloud_container_image_build**:: + + [entry_points] + openstack.cli.extension = + tripleoclient = tripleoclient.plugin + + openstack.tripleoclient.v1 = + ... + overcloud_container_image_build = tripleoclient.v1.container_image:BuildImage + +The value in each *key=value* pair provides us with the file and class name +used in the tripleoclient namespace for this comand. For **overcloud_container_image_build** we have +**tripleoclient.v1.container_image:BuildImage**, which means this command is +defined in a class called **BuildImage** inside the `tripleoclient/v1/container_image.py`_ +file. + +.. _`tripleoclient/v1/container_image.py`: https://git.openstack.org/cgit/openstack/python-tripleoclient/tree/tripleoclient/v1/container_image.py?id=0132e7d08240d8a9d5839cc4345574d44ec2b278#n100 + +TripleO commands: *how* +----------------------- + +Obviously each TripleO command 'works' differently in that they are doing +different things - deploy vs upgrade the undercloud vs overcloud etc. +However there **is** at least one commonality which we highlight in this section. +Each TripleO command class defines a get_parser_ function and a take_action_ +function. + +The get_parser_ is where all command line arguments are defined and +take_action_ is where tripleo-common is invoked to perform the task at hand, +building container images in this case. + +Looking inside the **BuildImage** class we find:: + + def get_parser(self, prog_name): + ... + parser.add_argument( + "--config-file", + dest="config_files", + metavar='', + default=[], + action="append", + help=_("YAML config file specifying the images to build. May be " + "specified multiple times. Order is preserved, and later " + "files will override some options in previous files. " + "Other options will append. If not specified, the default " + "set of containers will be built."), + ) + parser.add_argument( + "--kolla-config-file", + +Here we can see where the two arguments shown in the introduction above are +defined: **--config-file** and **--kolla-config-file**. You can see the default +values and all other attributes for each of the command parameters there. + +Finally we can look for the take_action_ function to learn more about how the +command actually 'works'. Typically the take_action function will have some +validation of the provided arguments before calling out to tripleo-common to +actually 'do' the work (build container images in this case):: + + from tripleo_common.image import kolla_builder + ... + def take_action(self, parsed_args): + ... + try: + builder = kolla_builder.KollaImageBuilder(parsed_args.config_files) + result = builder.build_images(kolla_config_files, + +Here we can see the actual image build is done by the **kolla_builder.KollaImageBuilder** +class **build_images** function. Looking in tripleo-common we can follow that +python namespace to find the definition of **build_images** in the +`tripleo_common/image/kolla_builder.py`_ file:: + + def build_images(self, kolla_config_files=None, excludes=[], + template_only=False, kolla_tmp_dir=None): + cmd = ['kolla-build'] + ... + +.. _get_parser: https://git.openstack.org/cgit/openstack/python-tripleoclient/tree/tripleoclient/v1/container_image.py?id=0132e7d08240d8a9d5839cc4345574d44ec2b278#n119 +.. _take_action: https://git.openstack.org/cgit/openstack/python-tripleoclient/tree/tripleoclient/v1/container_image.py?id=0132e7d08240d8a9d5839cc4345574d44ec2b278#n184 +.. _`tripleo_common/image/kolla_builder.py`: https://git.openstack.org/cgit/openstack/tripleo-common/tree/tripleo_common/image/kolla_builder.py?id=3db41939a370ef3bbd2c6b60ca24e6e8e4b6e30a#n441