f5networks / f5-ci-docs Goto Github PK

See BDO-305 for details.

Mesos/Marathon does not have to run on DC/OS (we run it on openstack for example). Parts of the examples specific to the environment could be more clearly contextualized.

A communication that "This example is presented with Mesos/Marathon running on DC/OS. Sections of the example config below specific to DC/OS may have requirements based how your Mesos/Marathon cluster is deployed."

Or perhaps

    // Mesos DC/OS Open oath authentication
    "F5_CC_DCOS_AUTH_TOKEN": "<authentication-token>"

becomes

    // Mesos DC/OS Open oath authentication
    // or corresponding authentication if required
    "F5_CC_DCOS_AUTH_TOKEN": "<authentication-token>"

see f5-ci-docs/docs/_build/html/marathon/mctlr-authenticate-dcos.html#mesos-authentication

DoD:

• Private Read the Docs site is up and docs are built
• RTD webhook is active

Description

There are placeholder links with "tbd" as the target used throughout the documentation. These need to be replaced with actual links or refs, as appropriate, before official docs release.

There are many sphinx config options that may be useful to us that should be investigated/trialed.

• ifconfig
• doctest
• html_sidebars
• primary_domain
• default_role
• using rst_prolog to identify development drafts?
• integrating comments via the Disqus extension

Title: A short but descriptive summary of the issue, whether it be a bug or enhancement.
Details: For bugs, use the below template.
Do not include requests for development or report issues with code or products here. This repository contains documentation only.

Version

docs v0.2.0 (ISC Mesos Early Release / k8s Beta)

Description

The UX of the documentation can be improved by standardizing how content is presented across the repos and making the process of finding content more intuitive.

The "Releases and Versioning" page should include BIG-IP v13.0 and/or indicate v12.1 and forward.

In general, it's not clear from the way we have indicated versions if it's only just that specific version of a product or is it that version and later. As an example, we indicated Kubernetes 1.3.7 which, as a customer, would lead me to believe ONLY 1.3.7 is supported but that's not the case as we support v1.4 and v1.5 as well.

UPDATE: After talking with Sean Duggan, the PM perspective is that it's best to list the specific version of a given platform rather than using the "+" symbol. For example, with Kubernetes, we would list version 1.3.7, 1.4 and 1.5. However, within a specific version we can use an "x" to denote support maintenance releases as in "1.5.x".

• Edit readmes to ensure consistent voice and format across projects (lightweight-proxy, lwp-controller, and f5-marathon-lb).
• Push changes back up to fork for respective projects and open PRs against upstream repos.

provide all of the drafts of the PoC/Beta release documentation

Upon successful builds for release tags, or on commits to any branch that are not made by a pull request, we should deploy the built documentation to the correct directory in the AWS s3 bucket for the docs website.

S3 Access id, keys, and bucket name must not be visible in the build logs, travis.yaml, or anywhere else where it could be compromisable.

The lightewight-proxy README contains F5 developer instructions including

• git clone bldr-git....
• vagrant build instructions
• Docker build instructions

The docker run instructions should be modified to replace the f5/lwp-proxy image name with a placeholder, and any "run from the command line" instructions removed.

These developer-only parts of the README should be moved into the a developer-only README that doesn't get included in these user docs.

Setup intersphinx mapping for the site based on expected URLs.

• Cross-project refs and links must be version-consistent (i.e., if I'm looking at v1.0.3 and click a link, the content I am directed to must also be for v1.0.3).

The general idea is to rely on refs wherever possible instead of hard-coded URLs.

Version

marathon beta v0.1

Description

Beta refers to f5-marathon-lb v0.1.1 but it should now refer to v0.1.2 so that users get a fix for f5-marathon-lb issue 62 (Node creation may fail if mesos hostname is not an IP address)

Provide information on how the virtual server name will appear on the BIGIP. This varies depending on the orchestration environment.
K8s: [namespace][configmap-name]
MM: [appId][bindadrr or iapp]_[servicePort]

The ASP has a new config option -- bind_port -- that allows the user to configure a single ingress socket. Proper use of this config option needs to be documented in the Kubernetes solution docs.

Contents:

• Installation instructions for all projects/tools involved
• splunk integration instructions (e.g., go get splunk, then do this with it)
• Support / Compatibility Matrix (include tested versions of mesos/mesosphere, marathon, BIG-IP, Ubuntu)
• Troubleshooting tips
• FAQs

See BDO-307.

Version

v1.0.0

Description

The installation instructions provided in docs/kubernetes/asp-k8s-deploy-f5kubeproxy.rst only apply to CoreOS. We should add instructions for other environments.

In scripts/test-docs.sh, we use write-good to check grammar. Currently, this is only checking the files in the top-level docs/ directory because it will throw errors on the code blocks in all of the other documentation.

We should investigate the level of effort involved in contributing to the write-good project to get it to ignore sphinx code blocks.

Investigate customizing the template / using f5 css file to match branding.

In a variety of locations in the documentation, there are still references to the old names of "Lightweight Proxy" and "LWP" as well as variations of them.

Please change references from "LWP" to "ASP" and from "Lightweight Proxy" to "Application Services Proxy". This applies to all variations of these names.

kctlr-user-bigip-openshift.rst:
note:
We assigned the existing ?? user and group permissions to the |kctlr|.

In our lab we used the namespace 'management-infra' with a serviceAccountName of 'management-admin'

Sphinx needs to be told what it should add to the index. See http://www.sphinx-doc.org/en/1.5.1/markup/misc.html#directive-index.

Version

1.0.0

Description

We do not currently have instructions for pulling images from private registries when deploying Apps in Marathon.

Set up integration with gitlab-ci to eliminate the (current) use of submodules. The goal is to have changes automatically pushed here when builds are triggered in the source repos.
Need to refactor docs in repo once gitlab integration is set up. Only cross-project documentation should actually be sourced from this repo.

All beta customers have been notified that there is no supported path for upgrade from beta release to Crestone release. We should have a notice somewhere to this effect that instructs customers to contact F5 support rep with questions, etc.

Description

The documentation (especially the usage guide) contains several example JSON blobs for configuring applications in Marathon. Currently, users have to copy and paste into a shell or editor. It would be nice if these snippets were also downloadable (and included in the git clone).

Ideally, there's a way to include the contents of a file inside the docs as a code snippet. Then, for instance, we could have a file like "examples/f5-marathon-lb.json" that contains the JSON, and the HTML rendering would contain the contents of examples/f5-marathon-lb.json inline (as it already does), but also a link to download examples/f5-marathon-lb.json

Environment

Most important that this works usefully in the HTML version of the docs. I think it'll work for the PDF version too.

Description

See BDO-306 for details.

The documentation in this repository will be refactored into 'solution' documentation. This consists of goal-oriented guides that help users accomplish specific goals.

Documentation should utilize EPPO best practices (i.e., linking, not reuse).

DoD

• K8s solution

  • how to launch bigip-controller in k8s
  • how to launch asp in k8s
  • how to use big-ip-controller / asp with OpenShift VxLAN
  • how to verify everything is running
  • service deployment examples (manual and iApps)

• Mesos/Marathon solution

  • how to launch bigip-controller in Marathon
  • how to launch asp-controller in Marathon
  • how to verify everything is running
  • service deployment examples (manual and iApps)

• Title: A short but descriptive summary of the issue, whether it be a bug or enhancement.
• Details: For bugs, use the below template.
• Do not include requests for development or report issues with code or products here. This repository contains documentation only.>

Description

There are three todos that actually appear in the published docs. We should do them or remove/hide the todo.

$ grep todo $(find ./ -name "*.rst")
.//docs/guides/includes/topic_f5-mesos-lwp-install.rst:    .. todo:: add instructions here
.//docs/guides/lwp_lwp-controller_guide.rst:.. todo:: additional explanation?
.//usage-marathon-poc.rst:.. todo:: enter email address

Contents:

• use cases / test plans for customers to work through (TBD)

index.rst:

Expound on node health.
When the |kctlr-long| runs with pool-member-type set to cluster -- which integrates the BIG-IP into the cluster network -- the |kctlr| watches the NodeList in the Kubernetes API server; the BIG-IP FDB (Forwarding DataBase) entries are created/updated according to that list. This ensures the k8s-bigip-ctlr will only make VxLAN requests to reported nodes; furthermore, if a node does become unhealthy (yet remains in the reported list) as a property of VxLAN the BIG-IP will still only continue to communicate with the remaining healthy nodes that respond.

We need to develop automated docs test and integrate them with a CI system.

• sphinx syntax
• rST syntax
• external links
• internal refs & toctrees (i.e., make sure that no docs are missing or broken)

Description

@bmarshall13 has a makefile that lets him build from the top-level project (this one) when writing docs for a subproject (lightweight-proxy).
We need to leverage this to identify and correct issues that would not occur when building docs locally from a subproject (e.g., not finding the _static directory or knowing where to find included files).

• investigate variablizing paths to make it easier to specify where files can be found

1. For Mesos, BIG-IP 11.6+ is supported and it would be the same for k8s... (needs to be corrected in f5-ci-docs/docs/releases-and-support)
2. Table display is a problem, given that a lot of key information is cut out. This requires changes to the rtd template / css.

developer-centric docs need to be removed (should only be in project repos)
guides need to be populated with content (i.e., no content re-use)

Version

all

Description

• apply the new official project names across all project repos
• update the directory names and all other references to the project names here.

F5 Container Service Integrator
F5 FlowPoint™ Proxy
F5 FlowPoint™ Proxy Controller
F5 BIG-IP Controller <env_name>
(F5 BIG-IP Marathon Controller? or F5 BIG-IP Controller - Marathon?)

Version

Beta

Description

The Marathon docs provide examples that specify service ports like 11099. In many installations of Marathon and DC/OS, the default configuration doesn't allow binding on those ports, only in ranges like 31000-32000.

The first time we provide an ASP example with a service port (this was in _build/f5-lwpc/minimaps/map_csim-lwp-deployment.html#install-the-lwpc, may have moved), we should:

• Say "The service port must be an available Mesos port. Consult the Mesos "ports" resource to see what ports are available in your cluster." (link to http://mesos.apache.org/documentation/latest/attributes-resources/ ).
• Say "If the associated Service Port cannot be allocated (due to it being in use, out of range, or some other condition, the ASP will not deploy. You will see tasks in the Marathon queue that cannot deploy due to "InsufficientPorts""

This was reported by Nicolas Menant.

• The iApp example in the CC docs need updating

See the product docs for k8s-bigip-ctrl and marathon-bigip-ctlr for examples and usage

We should define a plan for version management in the documentation so the sidebar doesn't get too cluttered from release to release. I'd like to do something like the node.js docs; they only include the latest versions in the side bar and provide links to the older doc sets in a toc tree on the home page.
https://nodejs.org/en/docs/

Version

v0.1.0

Description

AWS S3 integration for docs is required for customer access. These need to be pushed to S3 from Travis-CI for tagged versions and if it is the latest major version also copied into the latest directory.

The target path in the bucket is:
s3:///containers/

Version

0.1

Description

I have created a Dockerfile that will create a sphinx build environment in a Docker container. Next steps:

• build the docs (html and pdf) in the container
• copy _build/html and _build/latex/*.pdf into a new directory
• tar the new directory
• export the .tgz file

Bonus points:

• create a release in GitHub and upload the .tgz if the build image is tagged with a version number

We need to provide the appropriate acknowledgments and copyright notices.

For ISC release -- K8s PoC and Mesos GA -- we need to do the following in the f5-ci-docs repo:

• update the project list (and include refs to the projects' docs/README pages) on index.rst
• update toctree on index.rst

This epic encompasses sphinx development / customizations that would be nice to have or are required to make docs function they way we need them to.

Description

The beta docs are now on their own branch. Working from development, I need to refactor the docs directory so it can receive docs from the individual project repos. This includes moving content that is project-specific into the appropriate directory from the docs/_includes directory.

Environment

N/A