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
This commit is contained in:
parent
43842ececf
commit
98f9b120fb
|
@ -8,5 +8,6 @@ Documentation of developer-specific options in |project|.
|
||||||
|
|
||||||
tht_walkthrough/tht_walkthrough
|
tht_walkthrough/tht_walkthrough
|
||||||
release
|
release
|
||||||
|
tripleoclient_primer
|
||||||
mistral_workflows/00-index
|
mistral_workflows/00-index
|
||||||
../upgrade/developer/upgrades/upgrades
|
../upgrade/developer/upgrades/upgrades
|
||||||
|
|
|
@ -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</install/containers_deployment/3rd_party>` 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='<yaml config file>',
|
||||||
|
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
|
Loading…
Reference in New Issue