Publish Content to clouddocs.f5.com

What?

clouddocs.f5.com is a static website hosted in an Amazon Web Services S3 bucket. It contains solution and product documentation for multiple cloud-related F5 products.

Why?

The clouddocs.f5.com website launched in tandem with the initial (Crestone) release of the Container Connectors. The website addressed a need to publish documentation from multiple project repositories using a continuous delivery model.

How?

All solution and product docs use continuous deployment (also called ‘continuous delivery’). On commits to a project’s release branch, the doc tests run and (if the tests pass) the content automatically deploys to the AWS S3 bucket.

How do I set up my project to publish to clouddocs.f5.com?

  1. Add the project path to clouddocs project in GitLab.

  2. Provision AWS Access ID and Key for the project.

  3. Add the scripts directory from the training repo in GitLab to your project. [1]

    Note

    GitLab projects don’t need the “deploy-docs” script.

  4. Set up the project’s CI tool to run the test and deployment scripts. [2]

    The containthedocs Docker image includes a set of deployment scripts. Use the table below to identify the script you need to use for your project, based on where it will live in clouddocs.

    Script Path Example
    publish-cloud-docs-to-prod /cloud/${cloud_path}/${version} /cloud/openstack/v1
    publish-container-docs-to-prod /${solution_path}/${version} /containers/v1
    publish-product-docs-to-prod /products/${product_path}/${version} /products/connectors/k8s-bigip-ctlr/v1.2

gitlab-ci

  1. Add the AWS access ID and key to the project as secure environment variables.

  2. Add stages to .gitlab.yaml:

    stages:
- build_docs
- deploy

  3. Add jobs to .gitlab.yaml:

    build docs:
image: docker-registry.pdbld.f5net.com/tools/containthedocs:master
script:
  - ./path-to/test-docs.sh
tags:
  - docker
stage: build_docs
artifacts:
  paths:
    - docs/_build/html

    Publish docs to internet:
# Publish ONLY release branch to the internet.
image: docker-registry.pdbld.f5net.com/tools/containthedocs:master
stage: deploy
tags:
  - docker
only:
  - <release-branch>@<project-repo> \\ not a fork
dependencies:
  - build docs
script:
  - <containthedocs-script> <clouddocs-path> <version>

    Example:

    Publish docs to internet:
# Publish ONLY 1.0-stable to the internet.
image: docker-registry.pdbld.f5net.com/tools/containthedocs:master
stage: deploy
tags:
 - docker
only:
 - 1.0-stable@velcro/asp
dependencies:
 - build docs
script:
 - publish-product-docs-to-prod asp v1.0

travis-ci

  1. Add the AWS access ID and key to the project as secure environment variables.

  2. Add the script section to .travis.yaml:

    script:
- ./path-to/docker-docs.sh ./path-to/test-docs.sh

  3. Add the deploy section to .travis.yaml:

     deploy:
 - provider: script
skip_cleanup: true
on:
  branch: v1
  repo: F5Networks/f5-ci-docs
script:
- ./path-to/deploy-docs.sh <containthedocs-script> <clouddocs-path> <version>

    Example:

    deploy:
- provider: script
skip_cleanup: true
on:
 branch: v1
 repo: F5Networks/f5-ci-docs
script:
- ./path-to/deploy-docs.sh publish-container-docs-to-prod containers v1

Note

This is not intended to be a one-size-fits-all solution. We can (and do) make modifications to accommodate the needs of individual projects.

Footnotes

[1]Email Jodie Putrino if you need access to the project in GitLab.
[2]There will be a staging bucket as well; WIP.