Rework docs jobs to be consumable by tenants

This refactors the docs publication/promote jobs so that there
are base versions which can be consumed by tenants who will supply
their own AFS secrets, as well as versions for use in this tenant
(which consume the base versions in exactly the way another tenant
would).

The documentation policies for the tenant are encoded in the secret,
so each tenant can choose the publication locations and scheme once
and allow all projects within that tenant to use these jobs.

Change-Id: I8f201c0351d4d532ddcbcf1f22f9297dece04fff
This commit is contained in:
James E. Blair 2019-04-01 11:04:01 -07:00
parent 910bf4fd0c
commit edab04d5ef
3 changed files with 148 additions and 24 deletions

View File

@ -1,10 +1,14 @@
- hosts: localhost
tasks:
- name: Check execution context
when: "zuul.branch is not defined"
fail:
msg: "This playbook must be run in a branch-based pipeline (e.g., 'promote')."
- name: Download docs archive
include_role:
name: download-artifact
vars:
download_artifact_job: opendev-tox-docs
# download_artifact_job: provided by zuul job
download_artifact_api: "https://zuul.opendev.org/api/tenant/{{ zuul.tenant }}"
download_artifact_name: docs_archive
download_artifact_pipeline: gate
@ -16,35 +20,36 @@
unarchive:
src: "{{ zuul.executor.work_root }}/docs-html.tar.bz2"
dest: "{{ zuul.executor.work_root }}/docs"
- name: Write branch marker text
copy:
dest: "{{ zuul.executor.work_root }}/docs/.root-marker"
content: "Project: {{ zuul.project.name }} Branch: {{ zuul.branch }} Build: {{ zuul.build }} Revision: {{ zuul.ref }}"
- name: Set publication directory to latest
- include_role:
name: write-root-marker
vars:
root_marker_dir: "{{ zuul.executor.work_root }}/docs"
- name: Set target directory
when: "zuul.branch == 'master'"
set_fact:
publication_dir: latest
- name: Set publication directory to branch
target_dir: "{{ afs.docs_master_path }}"
- name: Set target directory
when: "zuul.branch != 'master'"
set_fact:
publication_dir: "{{ zuul.branch }}"
target_dir: "{{ afs.docs_branch_path }}"
- name: Get an AFS token
include_role:
name: create-afs-token
- name: Create publication directory
file:
path: "/afs/.openstack.org/project/opendev.org/docs/{{ zuul.project.name }}/"
path: "{{ target_dir }}"
state: directory
- name: Create redirect htaccess file
when: "afs.docs_redirect_path is defined and zuul.branch == 'master'"
copy:
dest: "/afs/.openstack.org/project/opendev.org/docs/{{ zuul.project.name }}/.htaccess"
content: "Redirect 302 /{{ zuul.project.name }} /{{ zuul.project.name }}/latest"
dest: "{{ afs.docs_redirect_path }}"
content: "{{ afs.docs_redirect_content }}"
- name: Upload to AFS
include_role:
name: upload-afs
vars:
afs_source: "{{ zuul.executor.work_root }}/docs/"
afs_target: "/afs/.openstack.org/project/opendev.org/docs/{{ zuul.project.name }}/{{ publication_dir }}"
afs_target: "{{ target_dir }}"
- name: Destroy AFS token
include_role:
name: destroy-afs-token

View File

@ -1,26 +1,29 @@
- hosts: localhost
tasks:
- name: Write branch marker text
copy:
dest: "{{ zuul.executor.log_root }}/docs/.root-marker"
content: "Project: {{ zuul.project.name }} Branch: {{ zuul.branch }} Build: {{ zuul.build }} Revision: {{ zuul.ref }}"
- name: Set publication directory to tag
when: "zuul.tag is defined"
- name: Check execution context
when: "zuul.tag is not defined"
fail:
msg: "This playbook must be run in a tag-based pipeline (e.g., 'release')."
- include_role:
name: write-root-marker
vars:
root_marker_dir: "{{ zuul.executor.log_root }}/docs"
- name: Set target directory
set_fact:
publication_dir: "{{ zuul.tag }}"
target_dir: "{{ afs.docs_tag_path }}"
- name: Get an AFS token
include_role:
name: create-afs-token
- name: Create publication directory
file:
path: "/afs/.openstack.org/project/opendev.org/docs/{{ zuul.project.name }}/"
path: "{{ target_dir }}"
state: directory
- name: Upload to AFS
include_role:
name: upload-afs
vars:
afs_source: "{{ zuul.executor.log_root }}/docs/"
afs_target: "/afs/.openstack.org/project/opendev.org/docs/{{ zuul.project.name }}/{{ publication_dir }}"
afs_target: "{{ target_dir }}"
- name: Destroy AFS token
include_role:
name: destroy-afs-token

120
zuul.yaml
View File

@ -87,6 +87,11 @@
Jpyp6oXA+W+qefPPqQlxa9EbP3emwVf/HWUdCjlCw+GjDz730P94Xd8ie6KiGq3ywYtFn
EuJvheVCAYjlq4lwshfNIysNA8WePvAze9T5DpVl1MayR7b1KC+R/7wM6xUCbw=
service_name: service/opendev-zuul@OPENSTACK.ORG
docs_master_path: "/afs/.openstack.org/project/opendev.org/docs/{{ zuul.project.name }}/latest"
docs_branch_path: "/afs/.openstack.org/project/opendev.org/docs/{{ zuul.project.name }}/{{ zuul.branch }}"
docs_tag_path: "/afs/.openstack.org/project/opendev.org/docs/{{ zuul.project.name }}/{{ zuul.tag }}"
docs_redirect_path: "/afs/.openstack.org/project/opendev.org/docs/{{ zuul.project.name }}/.htaccess"
docs_redirect_content: "Redirect 302 /{{ zuul.project.name }} /{{ zuul.project.name }}/latest"
- job:
name: base
@ -253,9 +258,59 @@
post-run: playbooks/tox-docs/post.yaml
success-url: docs/
- job:
name: opendev-publish-tox-docs-base
# This is not parented to opendev-tox-docs because the post
# playbook differs.
description: |
Publish a ref-based documentation build.
Use this in the tag or release pipelines to publish a build
based on a newly-created tag.
This is an abstract job intended to be inherited from in an
OpenDev tenant and an appropriate secret added.
.. zuul:jobvar:: afs
:type: dict
This is expected to be a Zuul Secret with these keys:
.. zuul:jobvar:: keytab
The AFS keytab for the service principal.
.. zuul:jobvar:: service_name
The name of the service princpal.
.. zuul:jobvar:: docs_master_path
The full docs publication path to use if the job is run on
the master branch.
.. zuul:jobvar:: docs_branch_path
The full docs publication path to use if the job is run on
any other branch.
.. zuul:jobvar:: docs_tag_path
The full docs publication path to use if the job is run on
a tag.
abstract: True
vars:
tox_envlist: docs
bindep_profile: compile doc
pre-run: playbooks/tox-docs/pre.yaml
run: playbooks/tox-docs/run.yaml
post-run:
- playbooks/tox-docs/post.yaml
- playbooks/tox-docs/publish.yaml
- job:
name: opendev-publish-tox-docs
parent: opendev-tox-docs
parent: opendev-publish-tox-docs-base
description: |
Publish a ref-based documentation build.
@ -265,20 +320,81 @@
secrets:
- secret: opendev-zuul-docs
name: afs
pass-to-parent: true
- job:
name: opendev-promote-docs
name: opendev-promote-docs-base
description: |
Publish a previously built branch-tip documentation tarball.
Use this in the promote pipeline to publish a branch tip tarball
built in the gate pipeline.
This is an abstract job intended to be inherited from in an
OpenDev tenant and an appropriate secret added.
.. zuul:jobvar:: afs
:type: dict
This is expected to be a Zuul Secret with these keys:
.. zuul:jobvar:: keytab
The AFS keytab for the service principal.
.. zuul:jobvar:: service_name
The name of the service princpal.
.. zuul:jobvar:: docs_master_path
The full docs publication path to use if the job is run on
the master branch.
.. zuul:jobvar:: docs_branch_path
The full docs publication path to use if the job is run on
any other branch.
.. zuul:jobvar:: docs_tag_path
The full docs publication path to use if the job is run on
a tag.
.. zuul:jobvar:: docs_redirect_path
If this variable is present, a .htaccess redirect will be
created at this path when the job is run on the master
branch. For example, it can be used to redirect "project/"
to "project/latest".
.. zuul:jobvar:: docs_redirect_content
The contents of the .htaccess file in docs_redirect_path.
.. zuul:jobvar:: download_artifact_job
The name of the job which built the docs artifact which this
job should download and promote.
abstract: True
run: playbooks/docs/promote.yaml
nodeset:
nodes: []
- job:
name: opendev-promote-docs
parent: opendev-promote-docs-base
description: |
Publish a previously built branch-tip documentation tarball.
Use this in the promote pipeline to publish a branch tip tarball
built in the gate pipeline.
vars:
download_artifact_job: opendev-tox-docs
secrets:
- secret: opendev-zuul-docs
name: afs
pass-to-parent: true
- project:
check: