tungstenfabric / docs Goto Github PK
View Code? Open in Web Editor NEWDocumentation for the Tungsten Fabric SDN
Home Page: https://docs.tungsten.io
License: Creative Commons Attribution 4.0 International
Documentation for the Tungsten Fabric SDN
Home Page: https://docs.tungsten.io
License: Creative Commons Attribution 4.0 International
Re-jigger tungsten.io to move docs currently under 'website' repo 'docs' repo
Here are notes I took while setting up git-review and sending my first patch (for https://jira.tungsten.io/browse/TFB-1412 ) They need to be cleaned up, converted to .rst, and added to the Contributors directory.
gerrit version 2.16.8
or highercommit -s
so you’ll get the signed-off-by, which is required by git reviewgit commit --amend -s -c <SHA>
on itgit review
to get the patch into Gerrit
Success looks something like this:
`Θυια:docs vmb$ git review
remote:
remote: Processing changes: }}{{new: 1 ()
remote: Processing changes: new: 1 (|)
remote: Processing changes: new: 1
remote: Processing changes: new: 1
remote: Processing changes: new: 1 ()
remote: Processing changes: refs: 1, new: 1 ()
remote: Processing changes: refs: 1, new: 1, done
remote:
remote: SUCCESS
remote:
remote: New Changes:
remote: https://gerrit.tungsten.io/r/c/docs/+/24 Reorg docs directories
To ssh://gerrit.tungsten.io:29418/docs
We now have the automated CLA stuff integrated into gerrit.tungsten.io.
The docs team will be the first using this Gerrit, which will give us a good opportunity to test out the CLA stuff and ensure it's documented, making contributions easier for others once their repos transition to the TF Gerrit.
A potentially helpful reference will be the LF CLA documentation: https://docs.linuxfoundation.org/display/DOCS/Contributor+License+Agreement+User+Guide
Migrated from GitHub Issue: #26
I'm creating a summary of this for someone who asked, so I may as well add it into the repo to help everyone.
The summary will:
Add a quick start guide for using Tungsten Fabric using TF-Devstack and upgrades for Contrail Ansible deployer - k8 and Openstack.
Migrated from GitHub Issue: #31
From #dev on Slack (on/around 2019-02-20):
05:10 Hello everyone. Can somebody help me with updating schemas? My question is what packages needed to be reinstalled after schema updating. For example, if i want to update this file - https://github.com/Juniper/contrail-controller/blob/R4.0/src/schema/loadbalancer.xsd
And another example - if i want to make changes in schema - do i need to change something in other files?
Migrated from GitHub Issue: #32
From the #users channel on Slack (on/around 2019-02-21):
11:41 Hi all,
11:41 quick question
11:41 on which smart NICs is vRouter offload supported?
11:41 https://tungstenfabric.github.io/website/Tungsten-Fabric-Architecture.html#smartnic-vrouter
12:04 mellanox and neutronome I suppose. both companies worked on supporting theier products. but i don't know exact version where it works
Many contributors (tech writers, programmers, others) wont be familiar with rST. We should provide basic guidance for how to use it.
Migrated from GitHub Issue: #30
According to a conversation in #dev on Slack, the CI process right now is tribal knowledge. This makes it very difficult for contributors to troubleshoot issues or even to know how things are going.
We should start documentation of this process, written from the perspective of the end user (contributor).
The Slack conversation from on/around 2019-01-30:
17:58 vsinitsyn Is everything okay with the CI? 2 minutes for green unit tests doesn't sound real, especially if building centos packages fails: https://review.opencontrail.org/#/c/48958/ (edited)
18:03 VM (Vicky) Brasseur @vsinitsyn A Codilime dev is doing some work on the Gerrit/repos. Maybe that's affecting it?
18:04 VM (Vicky) Brasseur I've emailed him to ask, and also asked him to join the Slack.
18:04 VM (Vicky) Brasseur His name is Jarek, so keep an eye out for him joining.
18:09 vsinitsyn Thanks Vicky will do
18:22 andrey-mp @vsinitsyn CI doesn't re-run UT job if it was successful for this patchset
18:25 VM (Vicky) Brasseur Is there a doc somewhere that covers this stuff? Or is it tribal knowledge?
18:25 vsinitsyn @Andrey-mp good news, thanks
18:28 andrey-mp I've checked job log and made such conclusion
18:30 jluk False alarm
18:30 jluk Pure tribal knowledge.
18:33 VM (Vicky) Brasseur Hrm. That's not gonna scale.
18:34 — VM (Vicky) Brasseur opens a doc issue…
A checklist of things we have to do after a TSC election. Please update this list accordingly here until the doc exists:
Right now this doc is accidentally in the root directory. It should be under administration. Also, it's not showing in RTD at all. This may be a result of the prior sync issues, but more likely it needs to be added to an index.rst or some such?
This spreadsheet lists all of the TF services and the ports that they listen on and talk to: https://docs.google.com/spreadsheets/d/14IGWcfZLJhG0nz6iSZGpRqKz4PajqHohH6HG__vVsnA/edit?usp=sharing We should convert this into an rST doc.
We don't really have an entry point/landing page for contributing.
There's some stuff on the website, and some stuff in the repo, and some stuff scattered around elsewhere (see the Docs Census: https://wiki.tungsten.io/display/TUN/Docs+Census
We need to create a single, easy to find and use landing page in RTD for all of this information.
Gerrit uses 'gates' (tests) to determine whether a patch can be merged. As of today (2019-05-09), the gates are as follows:
Finally debugged the issue and now commits are blocked by requiring an "Issue-ID: " in the commit body
Eventually the gates may be different for each project, but this is a good start and we should start documenting this now.
Current gates that exist in Gerrit:
TF must obey the same CoC that applies to all LF projects: https://lfprojects.org/policies/code-of-conduct/ We should make sure that this CoC is linked everywhere (docs repo, all other repos, websites, wiki, slack).
There's a link to the Community Governance Document on the Governance page (http://docs.tungsten.io/en/latest/governance/index.html) http://docs.tungsten.io/en/latest/governance/index.html This link is broken and goes to the RTD 404 page.
Currently, the Jira workflows and Blueprint submission process for developers are documented in Google Docs.
https://docs.google.com/document/d/1UWIzZZOzTR8zZeTUOpV5pPzq1EcCPrS-F2GkYysOpR8/edit?usp=sharing
https://docs.google.com/document/d/1hYhaPmQEN4V4ZeLxruloIshnQ6yd05vNkcKqhRqCnIw/edit#heading=h.h3vxu6qloos
For consistency and to allow new developers to easily find this required documentation, the purpose of this task is to move these documents to the required format in the docs repository in the Contributor folder.
Tungsten Fabric requires release notes for the r5.1 release. This ticket is for the submission of the r5.1 release notes into the appropriate ReadTheDocs (RTD) format.
With our limited resources, we need to focus our resources on the minimal viable product (MVP) for docs. In the 2020-01-09 docs meeting: https://wiki.tungsten.io/display/TUN/2020-01-09+Docs+Project+Meeting we came up with a first pass at a list of things we'll need for that MVP.
Please note a few things:
We're focusing on the point of view of a contributor.
Because the docs repo is the only one that's fully moved to the git/gerrit/jira workflow, we'll use it as the target for all of our work.
Because of that, then, we'll be writing for a tech writer audience. Specifically, the Juniper Networks tech writers, since they have the most information about and experience with the product. These people are intelligent and accomplished but don\u0027t use git or reStructuredText for their jobs.
So, our audience are tech writers who don't know git, gerrit, or rST. The documents we create therefore will be a bit lower level than if we were targeting only developers, but even developers will benefit from them. For instance, this level of documentation would have been invaluable for our Google Summer of Code interns in 2019.
Our goal is to have these docs done by mid-2020 (if not sooner) so we can host a training/doc-a-thon in the Juniper offices in June or July.
Create a document introducing how to use Gerrit for people who've never seen Gerrit before. Assume a tech writer audience.
For now this will only list the core committers (+2/merge) folks for the Docs project and repo, but eventually we'll add the others in there as well after they move to the TF gerrit.
Instead, maybe document the merge requirements then link to a wiki page listing the current core committers for each project?
The read the docs site has the manual CLA steps for the original OpenContrail Gerrit. https://tungsten-fabric-documentation.readthedocs.io/en/latest/manual-cla-admin.html It appears we need to document the automated CLA process. Although it's straight forward, it would be helpful to have clear steps in read the docs. Wills Docs Census has a description. https://wiki.tungsten.io/display/TUN/Docs+Census It should just require a conversion to RST and to the contributor docs.
page: https://tungstenfabric.github.io/website/Tungsten-Fabric-Ubuntu-one-line-install-on-k8s.html
Section:
What just happened ?
Hurray! Welcome to Tungsten Fabric.
You installed Tungsten Fabric CNI in your Kubernetes node. If new compute nodes are added to your Kubernetes cluster, Tungsten Fabric CNI will be propogated to them auto-magically as it is backed by a Kubernetes DaemaonSet.
An extra sentence should be added to clarify what happens to compute nodes which have already been added prior to this command.
Reading that sentence it kind of sounds like the CNI will only apply from now on, but based on my understanding of daemonsets I would expect that it is already applied to those.
Should I not have added my compute nodes yet when setting up my cluster?
A bit of disambiguation would be good.
Will assembled the Docs Census, collecting the diaspora of TF documentation in one spot (well links to the docs, anyway):
https://wiki.tungsten.io/display/TUN/Docs+Census
We should review this census to see whether there are any items in there that can be used for the MVP.
Add a quick start guide for using Tungsten Fabric as a container network interface for Kubernetes deployments https://jira.tungsten.io/browse/TFB-1465 GSoC TF as a CNI for K8s guide
The index.rst for Governance reads:
Elections
The Election Mechanics wiki page supplements the Charter and Governance Document with specific details such as tools, timelines and exact process details. Changes to this page must be approved by the TSC, but should not contradict anything in either the Charter or Governance Document.
Because it needs to be approved by the TSC, and because it's an important part of governance, it should be in the repo along with the rest of the governance docs.
Many tech writers arent very familiar with git. We should create a basic doc for this so they have the resources they need to get started.
We can rely on existing resources out there in the world for some of this. For instance, recently (past few years) the Write The Docs conference held a git for tech writers workshop. If those materials are available we may be able to repurpose them (depending upon their licensing).
Creative Commons has come out with a styleguide and it's (no surprise) licensed CC BY: https://creativecommons.org/wp-content/uploads/2019/10/Creative-Commons-Style-Guide-2019.pdf" Maybe this is something we could fork as modify to become our first styleguide?
Migrated from GitHub Issue: #20
From #users on Slack today (2019-01-10):
12:12 Hello All, can someone let me know if @tf can be used as a SD-WAN solution similar to Viptela or Velo Cloud for enterprise branch connectivity – any links to documentation to such implementation if any would be very helpful, Thanks in advance
Documentation to capture the release verison info of DPDK (from upstream), which is expected to work with Tungsten Fabric. Compilation instructions to use upstream DPDK libraries.
Once CI is in place, we should be requiring docs be updated when code changes. This ticket can be a placeholder for discussion around such an issue.
Add Configuration API Guide to cover the followings.:
;Right now the docs have a Public Meetings page: http://docs.tungsten.io/en/latest/index.html#public-meetings It duplicates info available in the wiki or would, if it weren't already out of date. Instead of duplicating the info here, instead link to the appropriate places on the wiki.
Migrated from GitHub Issue: #21
From #docs on Slack today (2019-01-11):
00:13 I would like to install tungsten fabric with openstack queens manually.
00:13 But I can't find any documents about that.
And also in #users:
07:29 I would like to integrate tungsten fabirc with openstack (queens, rocky) . But I don't see any documents for manual install.
07:32 @Sapd I don't know about any docs that describes how to configure installed OpenStack with new deployed TF
07:34 Today I have installed TF on Kubernetes. But I would like to manual install to clear understand about architecture and all components
08:11 you need to provide keystone auth params to TF of existing OpenStack
08:13 in OpenStack you need to run compute/neutron/heat containers to bring required binaries/modules and then you need to configure neutron/heat
08:15 I will check contrail-heat
Someone updated review.opencontrail.org to the latest Gerrit. That means that you can't find the access groups under People anymore, since that link doesn't exist. Instead, go to Browse & Groups. The docs need to be updated to reflect this change.
From this thread on dev@:
I think it is important for the resource requirements to be documented somewhere.
In my testing (using CentOS 7.4 and 7.6) I have found the minimum requirements to be as follows. Not sure this is official, but I was running into resource constraints with anything lower than this amount of resources.
Kernel: 3.10.0-862.14.4
CPU: 8 vCPU
RAM: 32GB
Root Drive: 60GB
We should document this somewhere (or multiple somewheres).
Right now there's no way to see who's a member of which working group. We should add these to the docs.
Instead of documenting the members themselves (since membership can change a lot), instead doc what the standing WGs are and link to the wiki pages for them.
Once the Deprecation Policy is approved, we'll be moving this to the docs repo: https://wiki.tungsten.io/pages/viewpage.action?pageId=10060530
When reviewing the current structure of the documentation, I didn't see a good place to put proposals. Where should this governance proposal live?Should we review and comment in Confluence / JIRA
I proposed the following documentation:
https://wiki.tungsten.io/x/YQALAQ
We should be open about this sort of information, if only so community members know where to go if there are problems.
See this thread for information on dev ML moderators.
Who are the moderators for the other lists?
We should document tha basic CI/CD workflow for TF. For now we can start with the workflow for the Docs repo. We can information about other repos as it materialises.
The TSC has spoken: The tf-docs repo will act as a prototype for transitioning all TF repos from Gerrit to GitHub. This issue is for tracking the work related to this transition for tf-docs.
Work we'd like to tackle during the 2019 DDF at KubeCon in San Diego
This spreadsheet lists all of the TF services and the ports that they listen on and talk to: https://docs.google.com/spreadsheets/d/14IGWcfZLJhG0nz6iSZGpRqKz4PajqHohH6HG__vVsnA/edit?usp=sharing We should convert this into an rST doc.
We should be open about this sort of information, if only so community members know where to go if there are problems.
We've received a ppt file full of TF diagrams. We need to save these things for posterity and try to get them incorporated into the docs somehow. The file is larger than Jira will allow me to attach, so here's a Dropbox link to it: https://www.dropbox.com/s/btasyx7thaunbqd/TF%20Diagrams%202.pptx?dl=0
It's s a Jira ticket about creating Jira tickets. It's a meta-Jira-ticket! Anyway, we're going to have opinions on how people do this, so we need to document them. This should be linked in a few places (contributor guide, website at the very least).
Items to cover:
Dmitri at Juniper is working on a Carbide Evaluation Guide (aka CEG) for TF. It';s target audience is people who are familiar with Kubernetes and its goal is to make it easier for k8s folks to get up to speed with TF. Right now the document is in a Google Doc: https://docs.google.com/document/d/1RDwLfcZkZfP_b2MDrxIyl3zsy0UrQEErZAStI_Mvv08/edit Once the initial work is complete, the CEG will have to move to the https://gerrit.tungsten.io/r/admin/repos/docs It should go into the User/GettingStarted directory. It must be in http://docutils.sourceforge.net/rst.html
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.