Publish Content to clouddocs.f5.com¶

What?¶

clouddocs.f5.com is a static website hosted in an Amazon Web Services S3 bucket and fronted with AWS CloudFront. It contains User Guides and product documentation for multiple F5 products. `go/clouddocs`_ for more information.

Why?¶

The clouddocs.f5.com website launched in tandem with the initial release of the Container Connectors. The website addressed a need to publish documentation that is developed like code and follows a continuous delivery model.

How?¶

All projects that publish to CloudDocs do so via a CI/CD pipeline. On commits to a project’s release branch, the docs build and tests run; if the tests pass, the content automatically deploys to the website, which is hosted in an AWS S3 bucket.

Contact¶

Join the CloudDocs Team on Microsoft Teams.

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

Provision AWS Access ID and Key for the project (via request in the Support channel on CloudDocs Team).
Set up the project’s CI tool to run the test and deployment scripts. [1]

gitlab-ci¶

Add the AWS access ID and key to the project’s CI settings as secure environment variables.
Add stages to .gitlab.yaml:
```
stages:
- build_docs
- deploy
```

Add jobs to .gitlab.yaml:

build docs:
image: quay.f5net.com/doc-ops/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: quay.pdsea.f5net.com/doc-ops/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: quay.pdsea.f5net.com/doc-ops/containthedocs:master
stage: deploy
tags:
 - docker
only:
 - 1.0-stable@velcro/k8s-bigip-ctlr
dependencies:
 - build docs
script:
 - publish-product-docs-to-prod k8s-bigip-ctlr v1.0

travis-ci¶

Use the template below as a basis for setting up the test, staging, and deployment jobs in a GitHub repo using Travis-CI.

You will need to add all of the variables shown in the example to the Travis-CI settings for the repo.

language: python
python:
- '2.7'
sudo: required
services:
- docker
before_install:
- docker pull f5devcentral/containthedocs:latest
install:
- pip install awscli --upgrade
script:
- ./scripts/docker-docs.sh ./scripts/test-docs.sh
deploy:
# DEPLOY TO STAGING
- provider: s3
  skip_cleanup: true
  access_key_id: $AWS_ACCESS_KEY_ID
  secret_access_key: $AWS_SECRET_ACCESS_KEY
  bucket: $AWS_S3_STAGING
  local_dir: docs/_build/html
  upload_dir: /path/to/content/in/s3
  on:
    branch: master
    repo: F5Networks/<repo-name>
# DEPLOY TO PRODUCTION
- provider: s3
  skip_cleanup: true
  access_key_id: $AWS_ACCESS_KEY_ID
  secret_access_key: $AWS_SECRET_ACCESS_KEY
  bucket: $AWS_S3_BUCKET
  local_dir: docs/_build/html
  upload_dir: /path/to/content/in/s3
  on:
    branch: v2
    repo: F5Networks/<repo-name>

after_deploy:
  - aws cloudfront create-invalidation --distribution-id $AWS_DIST_ID --paths /path/to/content/in/s3/

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]	There is a public staging site at https://clouddocs.f5networks.net. An effort to stand up an internal staging site for Blue is underway.

Previous Next