f5networks / f5-ci-docs Goto Github PK
View Code? Open in Web Editor NEWDocumentation for F5's Container Ingress Services
Home Page: http://clouddocs.f5.com/containers/v2
License: Apache License 2.0
Documentation for F5's Container Ingress Services
Home Page: http://clouddocs.f5.com/containers/v2
License: Apache License 2.0
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.
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
1.0.0
We do not currently have instructions for pulling images from private registries when deploying Apps in Marathon.
For ISC release -- K8s PoC and Mesos GA -- we need to do the following in the f5-ci-docs repo:
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.
N/A
provide all of the drafts of the PoC/Beta release documentation
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".
We need to provide the appropriate acknowledgments and copyright notices.
Contents:
The lightewight-proxy README contains F5 developer instructions including
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.
See BDO-306 for details.
Setup intersphinx mapping for the site based on expected URLs.
The general idea is to rely on refs wherever possible instead of hard-coded URLs.
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.
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.
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)
We need to develop automated docs test and integrate them with a CI system.
Beta
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:
This was reported by Nicolas Menant.
v0.1.0
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/
marathon beta v0.1
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)
DoD:
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.
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]
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.
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
Mesos/Marathon solution
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'
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.
Contents:
Investigate customizing the template / using f5 css file to match branding.
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.
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.
docs v0.2.0 (ISC Mesos Early Release / k8s Beta)
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.
@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).
See BDO-307.
There are many sphinx config options that may be useful to us that should be investigated/trialed.
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.
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.
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.
See the product docs for k8s-bigip-ctrl and marathon-bigip-ctlr for examples and usage
0.1
I have created a Dockerfile that will create a sphinx build environment in a Docker container. Next steps:
_build/html
and _build/latex/*.pdf
into a new directoryBonus points:
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
See BDO-305 for details.
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/
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
Most important that this works usefully in the HTML version of the docs. I think it'll work for the PDF version too.
all
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?)
v1.0.0
The installation instructions provided in docs/kubernetes/asp-k8s-deploy-f5kubeproxy.rst only apply to CoreOS. We should add instructions for other environments.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.