[Starlingx-discuss] Review stx docs zuul implementation

Jeremy Stanley fungi at yuggoth.org
Mon Aug 22 16:05:58 UTC 2022


On 2022-08-22 16:02:02 +0000 (+0000), Stone, Ronald wrote:
> My company is researching Zuul for internal StarlingX docs builds.

That's awesome news! I hope you'll find it as invaluable as I do.

> Can someone point out where we could find the config files for
> StarlingX docs on opendev.org? We're hoping to use them as a
> jumping off point for an internal implementation.

If you're talking about the starlingx/docs repo specifically, you'll
see there's already a Zuul configuration file in it, though that's
really just serving as an entry point for populating some project
pipelines with jobs defined in other repos:

https://opendev.org/starlingx/docs/src/branch/master/.zuul.yaml

In particular, you're adding the openstack-tox-docs job to the check
and gate pipelines along with the promote-stx-tox-docs-site job to
the promote pipeline. It's also applying the stx-api-ref-jobs
template which comes from here:

https://opendev.org/starlingx/zuul-jobs/src/branch/master/zuul.d/project-templates.yaml

In that project-template entry you can see it's adding variants of
build-openstack-api-ref and promote-stx-api-ref jobs to some
pipelines as well. Some of these jobs are reused from OpenStack's
definitions, as you can tell from their names, though the couple
with "stx" in their names are defined in this trusted config repo
because they need access to shared credentials in order to be able
to write to the publication site:

https://opendev.org/openstack/project-config/src/branch/master/zuul.d/starlingx-jobs.yaml

The reused OpenStack jobs on the other hand are being consumed from
definitions here:

https://opendev.org/openstack/openstack-zuul-jobs/src/branch/master/zuul.d/jobs.yaml

Zuul jobs also rely on inheritance, so you'll see for example the
build-openstack-api-ref job inherits from the openstack-tox-docs job
but overrides some specific variables and limits its scope to only
triggering on master branches (because in OpenStack, APIs are
versioned independently of the software which provides them). Then
openstack-tox-docs in turn inherits from opendev-tox-docs with a
variety of things overridden. You can find the opendev-tox-docs
definition here:

https://opendev.org/opendev/base-jobs/src/branch/master/zuul.d/jobs.yaml

So I can already hear you asking, "how do I find and keep all these
different sources/locations straight?" Zuul actually has a
browseable configuration in its WebUI. You can see the project entry
here shows all the jobs defined to run for various pipelines:

https://zuul.opendev.org/t/openstack/project/opendev.org/starlingx/docs

If you click on the build-openstack-api-ref entry, for example, it
will take you to details about that job including the project and
file which contains its definition along with a hyperlinked parent
entry, which you can follow to get a similar view of the inherited
job (continuing until you hit bedrock at the job named "base").

If you get stuck, all of those repositories can also be searched
here:

https://codesearch.opendev.org/

So anyway, that covers the basics of job definitions and how they're
selected, but what do they actually run? For that you'll want to
look for the "run" (often also "pre-run" and "post-run") playbooks.
Those are paths to Ansible playbook files in the repositories where
the job definitions reside. In the case of openstack-tox-docs for
example, you'll see its run phase uses this playbook:

https://opendev.org/openstack/openstack-zuul-jobs/src/branch/master/playbooks/tox-docs/run.yaml

The roles in there are reusable sets of tasks (instructions
basically), which can usually either be found in a "roles" top-level
directory of the same project, or in a project expressly listed as
providing additional roles in that job's definition or that of one
of its ancestors. In this case you'll see Zuul's standard library
(included by the "base" job definition) provides those revoke-sudo
and tox roles, while build-pdf-docs comes from
openstack/openstack-zuul-jobs where the job definition resides:

https://opendev.org/zuul/zuul-jobs/src/branch/master/roles
https://opendev.org/openstack/openstack-zuul-jobs/src/branch/master/roles

As for what goes in roles and playbooks, well, that's the point at
which you should consult the Ansible documentation, but I'm going to
assume this is at least enough to get you started.
-- 
Jeremy Stanley
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: not available
URL: <https://lists.starlingx.io/pipermail/starlingx-discuss/attachments/20220822/5a64583d/attachment.sig>


More information about the Starlingx-discuss mailing list