From 82bf5984ac8988db47cab7b3f9a78aa6d2f7022f Mon Sep 17 00:00:00 2001 From: Matt Oswalt Date: Tue, 23 Oct 2018 12:04:41 -0700 Subject: [PATCH 1/9] Bulk of docs restructing and additions Signed-off-by: Matt Oswalt --- docs/antidote-web/antidote-web.rst | 6 -- docs/{architecture => }/architecture.rst | 23 ++--- docs/architecture/infrastructure.rst | 92 ------------------ docs/community.rst | 6 -- docs/conf.py | 4 +- docs/contributing/contributing.rst | 31 ------ docs/contributing/curriculum.rst | 97 +++++++++++++++++++ docs/contributing/general.rst | 52 ---------- docs/contributing/index.rst | 24 +++++ docs/contributing/lessondetails.rst | 23 ----- docs/contributing/platform.rst | 8 ++ docs/index.rst | 60 +++++++++--- docs/intro.rst | 45 --------- docs/nrelabs.rst | 9 +- docs/platform/antidote-web/antidote-web.rst | 6 ++ docs/platform/index.rst | 11 +++ .../lessonnetworking.rst | 0 .../syringe}/lessonscheduling.rst | 0 docs/{ => platform}/syringe/syringe.rst | 1 + docs/{ => platform}/syringe/syringefile.rst | 0 docs/resources.rst | 14 +++ 21 files changed, 223 insertions(+), 289 deletions(-) delete mode 100644 docs/antidote-web/antidote-web.rst rename docs/{architecture => }/architecture.rst (85%) delete mode 100644 docs/architecture/infrastructure.rst delete mode 100644 docs/community.rst delete mode 100644 docs/contributing/contributing.rst create mode 100644 docs/contributing/curriculum.rst delete mode 100644 docs/contributing/general.rst create mode 100644 docs/contributing/index.rst delete mode 100644 docs/contributing/lessondetails.rst create mode 100644 docs/contributing/platform.rst delete mode 100644 docs/intro.rst create mode 100644 docs/platform/antidote-web/antidote-web.rst create mode 100644 docs/platform/index.rst rename docs/{architecture => platform}/lessonnetworking.rst (100%) rename docs/{architecture => platform/syringe}/lessonscheduling.rst (100%) rename docs/{ => platform}/syringe/syringe.rst (93%) rename docs/{ => platform}/syringe/syringefile.rst (100%) create mode 100644 docs/resources.rst diff --git a/docs/antidote-web/antidote-web.rst b/docs/antidote-web/antidote-web.rst deleted file mode 100644 index 3b59d1eb..00000000 --- a/docs/antidote-web/antidote-web.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. antidoteweb: - -Antidote-Web -================================ - -TBD diff --git a/docs/architecture/architecture.rst b/docs/architecture.rst similarity index 85% rename from docs/architecture/architecture.rst rename to docs/architecture.rst index de34c799..776762dc 100644 --- a/docs/architecture/architecture.rst +++ b/docs/architecture.rst @@ -1,25 +1,14 @@ .. architecture: -Antidote Architecture +Architecture ================================ -.. toctree:: - :maxdepth: 1 - - infrastructure.rst - lessonnetworking.rst - lessonscheduling.rst - - Antidote has multiple layers that build up a cluster, and multiple tools that run or setup each layer. -In general, the Antidote cluster can be thought of like a Kubernetes cluster running many services. This cluster is designed to run atop any cloud IaaS with very few services outside of the cluster (e.g. ingress load balancing). Because we're not using hosted Kubernetes (e.g. GKE), we need to setup the group of virtual machines on which to install Kubernetes before we can even begin. To automate this task and make it multicloud portable, we are using general infrastructure-as-code tooling. - -The NRE Labs runtime of Antidote runs on Google Cloud Platform, so we'll use this as a example to illustrate the cluster and stack at a glance. - .. image:: /images/infralayers.png -Now let's overview the tiers that make up Antidote: +Now let's overview the tiers that make up Antidote. The NRE Labs runtime of Antidote runs on Google Cloud Platform, +so we'll use this as a example to illustrate the cluster and stack at a glance. +----------------------+--------------+--------------------------------------------------------------------------+ | Infrastructure Tier | Tool Used | Explanation | @@ -55,7 +44,11 @@ Now let's overview the tiers that make up Antidote: | | | the lab exercise steps. | +----------------------+--------------+--------------------------------------------------------------------------+ -Antidote provisions and manages Kubernetes as opposed to using a hosted, managed solution like GKE because: +The first three layers are Antidote's "infrastructure". This means we are using existing tools and software to +get to a working Kubernetes cluster. The final two components make up the :ref:`Antidote Platform `, which +is the bulk of the custom software developed for the Antidote project. + +Antidote's infrastructure scripts provision and manages Kubernetes as opposed to using a hosted, managed solution like GKE because: - It needs a custom CNI plugin (multus). GKE doesn't support CNI except for very tightly controlled deployments. This means that we can't have multiple interfaces per pod. We tried our best to think of alternatives but the diff --git a/docs/architecture/infrastructure.rst b/docs/architecture/infrastructure.rst deleted file mode 100644 index a47cc065..00000000 --- a/docs/architecture/infrastructure.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. infrastructure: - -Infrastructure -================================ - - -# Load Balancer - -Irules and iapps f5, traffic scripts in steelapp. - -Lua script inside nginx config. See if you can run other code too. - -You really just need the load balancer to make sessions sticky. The end application like xterm or guac should update kubernetes. Need to use cookies on load balancer, and probably still do source-ip rate limiting - - - - -# Scheduling - -Right now, I'm taking charge of curating kubernetes defintions and other config files for a lab. Long-term, it would be best to limit the configuration to a bare minimum. Select -what images you want, connected in which ways, and which jupyter notebooks to include. - -To do this, we need a tool that not only accepts these minimal parameters and deploys them to k8s,but also takes care of scheduling pre-provisioned lab instances. - -Needs health checks to know when the lab is provisioned (being able to successfully SSH for instance) - -Need to watch both the K8S API, as well as the load balancer logs. Will also need to configure the load balancer probably. - - - -# Postgres - -Guacamole needs this - - -# Isolation - -kubectl create namespace my-namespace - -https://kubernetes.io/docs/concepts/services-networking/network-policies/ -https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -# Networking - -http://dougbtv.com/nfvpe/2017/02/22/multus-cni/ - -## Weave - -Why Weave? - -Weave Net supports an overlay network that can span different cloud networking configurations, simplifying running legacy workloads on Kubernetes. For example, Weave supports multicast, even when the underlying network doesn’t. Weave can configure the underlying VPC networking and bypass the overlay when running on AWS. This provider forms a mesh network of hosts that are partitionable and eventually consistent, meaning that the setup is almost zero-config, and it doesn’t need to rely on an Etcd. Weave supports encryption and Kubernetes network policy ensuring that there is security at the network level. - -weave also supports network policy - -https://github.com/weaveworks/weave/blob/master/site/kubernetes.md -https://www.weave.works/docs/net/latest/kubernetes/kube-addon/ -https://sourcegraph.com/github.com/weaveworks/weave@58eaf19026e6ac540c6f89c0dd2bb18bc80c5d59/-/blob/plugin/net/cni.go#L36:3 -https://www.weave.works/blog/linux-namespaces-and-go-don-t-mix -https://www.weave.works/docs/net/latest/building/ - -Some labs may need a single shared network, and this should be the default. They can optionally specify their own bridge per link, in which case the multiple interfaces would sit on different defined network definitions. In both cases, you'll likely want to do some kind of network policy - - -# Updating DNS - -Patching the coredns deployment with the appropriate network is all you need to do: - -kubectl -n kube-system patch deployment coredns -p '{"spec":{"template":{"metadata":{"annotations":{"networks": "[{ \"name\": \"guac-net\" }]"}}}}}' - - -# Load balancing - -https://cloud.google.com/kubernetes-engine/docs/tutorials/http-balancer - -Also nginx ingress. - -Labs don't get load balanced. Syringe schedules one service per lab pod, and each service is used individually from the antidote-web app - -# Antidote-web - -[Install with Docker](https://guacamole.apache.org/doc/gug/guacamole-docker.html) -[Extend Guacamole](https://guacamole.apache.org/doc/gug/guacamole-ext.html) - -Also get the build your own docs, since you did this - -# Monitoring - -- NGINX -- The nodes themselves -- gcp LB logs? -- web logs? -- syringe logs \ No newline at end of file diff --git a/docs/community.rst b/docs/community.rst deleted file mode 100644 index 8ad64704..00000000 --- a/docs/community.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _community: - -Community -================================ - -`Join the community on our Slack space and channel #nre_labs `_ diff --git a/docs/conf.py b/docs/conf.py index 1b7980ea..f2c6a1c3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,8 +20,8 @@ # -- Project information ----------------------------------------------------- project = 'antidote' -copyright = '2018, Matt Oswalt' -author = 'Matt Oswalt' +copyright = '2018, Juniper Networks' +author = 'Juniper Networks' # exclude_patterns = ['*DESCRIPTION.rst'] # The short X.Y version diff --git a/docs/contributing/contributing.rst b/docs/contributing/contributing.rst deleted file mode 100644 index 67873639..00000000 --- a/docs/contributing/contributing.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _contrib: - -Contributing to Antidote -================================ - -.. toctree:: - :maxdepth: 1 - - general.rst - lessondetails.rst - -In general, there are two area in which to contribute: Antidote infrastructure -and into the curriculum of Lessons. Lessons contributions are expected to be -the most common, and the community is striving to abstract the infrastructure -well enough that no software or platform engineering complexities are -involved in creating lessons. - -:ref:`Skip to code contribution ` guidelines, if you're not -contributing to the learning curriculum. - -Before setting off contributing, you should have used NRE Labs and have an idea -about the user experience desired if you wish to have your work considered to -be published there. Furthermore, you should read about the -project's curriculum :ref:`taxonomy `. And in order to test your -contributions before submitting a pull request to the project, it is helpful to -run an instance of Antidote yourself and test your changes. - -This document is meant to convey the spirit of the ideal contribution to Antidote. -Please read on, as it will make the review process much easier. When you're ready -to begin working on a lesson, go on to :ref:`Contributing a Lesson ` -for the technical details. \ No newline at end of file diff --git a/docs/contributing/curriculum.rst b/docs/contributing/curriculum.rst new file mode 100644 index 00000000..27dcb24d --- /dev/null +++ b/docs/contributing/curriculum.rst @@ -0,0 +1,97 @@ +.. _contrib-curriculum: + +Contributing to the Curriculum +============================== + +Thanks for contributing to the Antidote curriculum. Before starting, please read this document in its entirety, +so your work has the maximum impact and your time is best spent. + +Look at existing or in-progress content +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. Read this document in its entirety + +After you have used NRE Labs, know the spirit of it’s break down of workflows as lessons with many quick stages/labs +to progress through, and after you’ve read the quick contributing guide above, then it’s time to dirty your hands. + +4. Make a contribution goal for yourself (or anyone else) to fulfill by opening up a new issue with the “curriculum” +label. Make sure you don’t conflict with an existing issue that is open and in progress. If you do conflict, then +simply consider working together. Here are those existing issues: https://github.com/nre-learning/antidote/issues?q=is%3Aopen+is%3Aissue+label%3Acurriculum +Also make sure you don’t conflict with an existing lesson here: https://github.com/nre-learning/antidote/tree/master/lessons (also look +here to see example of how other lessons are implmented until docs are better) +5. Set off working. + + + + + +Lessons Should Demonstrate Something Useful +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Lessons in NRE Labs should demonstrate something useful to a network engineer. +For instance, the first lesson is a simple NAPALM based python tool that +collects system information about a target device. + +If a user can easily replicate what is shown in the lab so that it can help +them in production, then this would be even better. + +Planning Lessons +^^^^^^^^^^^^^^^^^^^^^^ + +**One-off** + +There are multiple ways to build lessons in NRElabs. The simplest method is +to have single one-off lessons that do not have any direct relationship to +other lessons. + +**Repeat** + +Some lessons can be repeated 2 or 3 times. For instance, in addition to the +NAPALM lesson, you could show the user how to collect system information using +an alternate method. You should explain why a network engineer would want to +choose one method over another. In the case of the first lesson, NAPALM is a +somewhat limited tool. If the user needs additional information, they would +need to do something different. They could use PyEZ, for instance. + +**Workflow** + +Some lessons could be a group of inter-related tasks. A troubleshooting +workflow that helps a network engineer locate a device in the network, or the +path between two devices, could be broken up into a set of distinct tasks. +Not every task has to be automated, but some could be, and the lessons could +reflect this. + +**Considerations** + +There are a number of languages, tools, and libraries/packages that could be +leveraged to build a lesson. Consider using open-source tools for the lessons, +or tools that are at least free. This helps ensure that a user could more +easily replicate what is shown in the lesson. + + + + + +Lesson Details +================================= + +The best way to get started building lessons is to get an instance of Antidote +running on your own laptop. Ironing out all of the bugs before you submit a pull +request makes the review process much smoother. For more info, see the +:ref:`local build ` documentation. + +You'll also want to get familiar with the :ref:`syringe file ` documentation. + +**Required lab components** + +syringe file +readme for the lab +html layout +Default configs + +tabs will be determined via syringefile and rendered from jinja2 template at +build time. + +The :ref:`Syringe YAML file ` is the main descriptor of a lesson. It is here +that a lesson is defined, it's properties and stages declared, and resources like configs, +scripts, and playbooks referenced. \ No newline at end of file diff --git a/docs/contributing/general.rst b/docs/contributing/general.rst deleted file mode 100644 index 2448c4d5..00000000 --- a/docs/contributing/general.rst +++ /dev/null @@ -1,52 +0,0 @@ -The Spirit of Antidote -================================ - -Lessons Should Demonstrate Something Useful -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Lessons in NRE Labs should demonstrate something useful to a network engineer. -For instance, the first lesson is a simple NAPALM based python tool that -collects system information about a target device. - -If a user can easily replicate what is shown in the lab so that it can help -them in production, then this would be even better. - -Planning Lessons -^^^^^^^^^^^^^^^^^^^^^^ - -**One-off** - -There are multiple ways to build lessons in NRElabs. The simplest method is -to have single one-off lessons that do not have any direct relationship to -other lessons. - -**Repeat** - -Some lessons can be repeated 2 or 3 times. For instance, in addition to the -NAPALM lesson, you could show the user how to collect system information using -an alternate method. You should explain why a network engineer would want to -choose one method over another. In the case of the first lesson, NAPALM is a -somewhat limited tool. If the user needs additional information, they would -need to do something different. They could use PyEZ, for instance. - -**Workflow** - -Some lessons could be a group of inter-related tasks. A troubleshooting -workflow that helps a network engineer locate a device in the network, or the -path between two devices, could be broken up into a set of distinct tasks. -Not every task has to be automated, but some could be, and the lessons could -reflect this. - -**Considerations** - -There are a number of languages, tools, and libraries/packages that could be -leveraged to build a lesson. Consider using open-source tools for the lessons, -or tools that are at least free. This helps ensure that a user could more -easily replicate what is shown in the lesson. - -.. _contrib-code: - -If you want to propose a change to Antidote, Syringe, Antidote-web, or any other member project, -contributions are welcome! Just be patient, as these components are still not considered quite stable, so you -should reach out to the maintainers before getting too deep into the weeds on a change, so you don't waste your time. - diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst new file mode 100644 index 00000000..66d88939 --- /dev/null +++ b/docs/contributing/index.rst @@ -0,0 +1,24 @@ +.. _contrib: + +Contributing to Antidote +================================ + +.. toctree:: + :maxdepth: 1 + + curriculum.rst + platform.rst + +In general, there are two area in which to contribute to Antidote: + +- The Lesson Curriculum - this is the most popular place to contribute to + Antidote. Here, you can change or add new lessons that describe automation + workflows. Before getting started, please read the + :ref:`lesson contribution guide `. +- The Antidote Platform - there are a number of software projects that power + Antidote, and these are also open source. Please visit the + :ref:`platform contribution guide ` before looking to + contribute here. + +Before starting work on a contribution, please read the relevant contribution guide; +they contain vital information to ensure your time is well-spent. diff --git a/docs/contributing/lessondetails.rst b/docs/contributing/lessondetails.rst deleted file mode 100644 index 91019607..00000000 --- a/docs/contributing/lessondetails.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _contriblesson: - - -Lesson Details -================================= - -The best way to get started building lessons is to get an instance of Antidote -running on your own laptop. Ironing out all of the bugs before you submit a pull -request makes the review process much smoother. For more info, see the -:ref:`local build ` documentation. - -You'll also want to get familiar with the :ref:`syringe file ` documentation. - -**Required lab components** - -syringe file -readme for the lab -html layout -Default configs - -tabs will be determined via syringefile and rendered from jinja2 template at -build time. - diff --git a/docs/contributing/platform.rst b/docs/contributing/platform.rst new file mode 100644 index 00000000..eec16e99 --- /dev/null +++ b/docs/contributing/platform.rst @@ -0,0 +1,8 @@ +.. _contrib-platform: + +Contributing to the Antidote Platform +===================================== + +If you want to propose a change to Antidote, Syringe, Antidote-web, or any other member project, +contributions are welcome! Just be patient, as these components are still not considered quite stable, so you +should reach out to the maintainers before getting too deep into the weeds on a change, so you don't waste your time. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 104726b1..d96b7c54 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,25 +1,57 @@ .. antidote documentation master file -Welcome to Antidote's documentation! -==================================== +Introduction to Antidote +======================== .. toctree:: - :maxdepth: 3 + :maxdepth: 1 :caption: Contents: - intro.rst - architecture/architecture.rst + architecture.rst + platform/index.rst building/building.rst - syringe/syringe.rst - antidote-web/antidote-web.rst - contributing/contributing.rst + contributing/index.rst roadmap.rst nrelabs.rst - community.rst + resources.rst -Indices and tables -================== +Welcome to Antidote! + +Antidote is an open-source project aimed at making automated network operations +more accessible with fast, easy and fun learning. It teaches from-scratch +network automation skills for network reliability engineers (NREs) and other +NetOps pros or amateurs. + +Antidote isn't just one application, but rather, a set of smaller applications +that work together to provide this learning experience. +The `antidote-selfmedicate `_ repository is the simplest way to get this going, as it's, +designed to allow you to run everything on your laptop, using `minikube`. This is very useful if you're looking to develop some lessons +and need an easy way to test them out without a lot of setup. See the :ref:`build local ` instructions for more info on that. + +In case you're looking to run Antidote in more of a public-facing, production capacity, the main `Antidote +repository `_ contains terraform configurations, kubernetes manifests, +and scripts necessary for running all of Antidote's components in the cloud. More information for spinning this up can be found in the :ref:`production ` guide. + +In fact, the reference runtime and use case for Antidote is +:ref:`NRE Labs ` and Antidote is the project behind it. NRE Labs is +a free site and training service on the web sponsored by Juniper Networks, but +anyone interested can run their own copy of Antidote. + +Often the first step to learning about network automation is the hardest: +you need to setup complex virtual environments, labs, or worse risk +experimenting in production. NRE Labs was built to teach skills right in your +web browser and let you deal with real tools, code and network devices. + +What's more is that often at the outset of the network automation journey, +when one thinks about what to automate, the answer is “the network!” But +specifics about workflows are prerequisite to automating them. That's why the +community here has created lessons and labs with real-life NetOps workflows. +And everything you see and use is applicable and open for you to use back in +your own environments. + +:ref:`Contributions ` are welcome. + +*Please note that NRE Labs is currently in limited tech preview.* + +`Join the community on our Slack space and channel #nre_labs `_ -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/intro.rst b/docs/intro.rst deleted file mode 100644 index bd1739dc..00000000 --- a/docs/intro.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _intro: - -Introduction -================================ - -Welcome to Antidote! - -Antidote is an open-source project aimed at making automated network operations -more accessible with fast, easy and fun learning. It teaches from-scratch -network automation skills for network reliability engineers (NREs) and other -NetOps pros or amateurs. - -Antidote isn't just one application, but rather, a set of smaller applications -that work together to provide this learning experience. -The `antidote-selfmedicate `_ repository is the simplest way to get this going, as it's, -designed to allow you to run everything on your laptop, using `minikube`. This is very useful if you're looking to develop some lessons -and need an easy way to test them out without a lot of setup. See the :ref:`build local ` instructions for more info on that. - -In case you're looking to run Antidote in more of a public-facing, production capacity, the main `Antidote -repository `_ contains terraform configurations, kubernetes manifests, -and scripts necessary for running all of Antidote's components in the cloud. More information for spinning this up can be found in the :ref:`production ` guide. - -In fact, the reference runtime and use case for Antidote is -:ref:`NRE Labs ` and Antidote is the project behind it. NRE Labs is -a free site and training service on the web sponsored by Juniper Networks, but -anyone interested can run their own copy of Antidote by learning about its -:ref:`infrastructure ` and :ref:`operations `. - -Often the first step to learning about network automation is the hardest: -you need to setup complex virtual environments, labs, or worse risk -experimenting in production. NRE Labs was built to teach skills right in your -web browser and let you deal with real tools, code and network devices. - -What's more is that often at the outset of the network automation journey, -when one thinks about what to automate, the answer is “the network!” But -specifics about workflows are prerequisite to automating them. That's why the -community here has created lessons and labs with real-life NetOps workflows. -And everything you see and use is applicable and open for you to use back in -your own environments. - -:ref:`Contributions ` are welcome. - -*Please note that NRE Labs is currently in limited tech preview.* - -`Join the community on our Slack space and channel #nre_labs `_ diff --git a/docs/nrelabs.rst b/docs/nrelabs.rst index 10a6758b..f3348f91 100644 --- a/docs/nrelabs.rst +++ b/docs/nrelabs.rst @@ -4,9 +4,12 @@ NRE Labs ================================ -NRE Labs is the flagship and reference deployment of Antidote. +`NRE Labs `_ is the flagship +and reference deployment of Antidote. .. image:: images/NRELabs-Large-onBlack.png + :scale: 20 % + :align: center While NRE Labs aims to be intuitive to use without documentation, lab contributors and Antidote developers should familiarize themselves with @@ -15,7 +18,7 @@ concepts of the learning curriculum and in the future, gamification. Taxonomy --------------- -In the NRE Labs curriculum there are many courses. A course is a theme and +In the NRE Labs curriculum there are several courses. A course is a theme and grouping of many related lessons. A lesson is a common task or workflow of many small steps. A lab is one small step or several that can be explained easily so that a user can understand and accomplish the labs in a matter of @@ -27,7 +30,7 @@ Here is the hierarchy overview: * Course: Like a category or topic of study * Lessons: A set of exercises that make sense together to teach something with a common set of resources. Usually a NetOps task. -* Labs - A set of related steps forming a workflow in a Lesson +* Labs (also known as stages): A set of related steps forming a workflow in a Lesson Lesson and Lab Relationship ------------------------------ diff --git a/docs/platform/antidote-web/antidote-web.rst b/docs/platform/antidote-web/antidote-web.rst new file mode 100644 index 00000000..5cec553f --- /dev/null +++ b/docs/platform/antidote-web/antidote-web.rst @@ -0,0 +1,6 @@ +.. antidoteweb: + +Antidote-Web - Antidote's Front-End +=================================== + +TBD diff --git a/docs/platform/index.rst b/docs/platform/index.rst new file mode 100644 index 00000000..10f238ae --- /dev/null +++ b/docs/platform/index.rst @@ -0,0 +1,11 @@ +.. _platform: + +Antidote Platform +================= + +.. toctree:: + :maxdepth: 1 + + syringe/syringe.rst + antidote-web/antidote-web.rst + lessonnetworking.rst diff --git a/docs/architecture/lessonnetworking.rst b/docs/platform/lessonnetworking.rst similarity index 100% rename from docs/architecture/lessonnetworking.rst rename to docs/platform/lessonnetworking.rst diff --git a/docs/architecture/lessonscheduling.rst b/docs/platform/syringe/lessonscheduling.rst similarity index 100% rename from docs/architecture/lessonscheduling.rst rename to docs/platform/syringe/lessonscheduling.rst diff --git a/docs/syringe/syringe.rst b/docs/platform/syringe/syringe.rst similarity index 93% rename from docs/syringe/syringe.rst rename to docs/platform/syringe/syringe.rst index 00fc66e1..970ae01c 100644 --- a/docs/syringe/syringe.rst +++ b/docs/platform/syringe/syringe.rst @@ -7,6 +7,7 @@ Syringe - Antidote's "Brains" :maxdepth: 1 syringefile.rst + lessonscheduling.rst Syringe is where the real work gets done in the Antidote project. It's responsible for taking in lesson definitions via :ref:`a YAML file `, and any configs, scripts, etc used in the lesson, and providing them to the \ No newline at end of file diff --git a/docs/syringe/syringefile.rst b/docs/platform/syringe/syringefile.rst similarity index 100% rename from docs/syringe/syringefile.rst rename to docs/platform/syringe/syringefile.rst diff --git a/docs/resources.rst b/docs/resources.rst new file mode 100644 index 00000000..a46045ec --- /dev/null +++ b/docs/resources.rst @@ -0,0 +1,14 @@ +.. _resources: + +Resources +================================ + +- Join our `Slack space and use the channel #nre_labs `_ for questions or ideas. +- Follow `@NRELabs `_ on twitter for periodic updates on NRE Labs and the underlying platform. + +Introduction to NRE Labs + +.. raw:: html + +
+ From 0f6c30f89086cbce96166514ff5f1d9d2afb68b9 Mon Sep 17 00:00:00 2001 From: Matt Oswalt Date: Tue, 23 Oct 2018 15:21:47 -0700 Subject: [PATCH 2/9] Minor fixes Signed-off-by: Matt Oswalt --- docs/platform/syringe/configuration.rst | 6 ++++++ docs/platform/syringe/syringe.rst | 4 +++- 2 files changed, 9 insertions(+), 1 deletion(-) create mode 100644 docs/platform/syringe/configuration.rst diff --git a/docs/platform/syringe/configuration.rst b/docs/platform/syringe/configuration.rst new file mode 100644 index 00000000..35ccbff7 --- /dev/null +++ b/docs/platform/syringe/configuration.rst @@ -0,0 +1,6 @@ +Configuring Syringe +================================ + +Syringe is configured with environment variables. Here is a list. + +TBD diff --git a/docs/platform/syringe/syringe.rst b/docs/platform/syringe/syringe.rst index 970ae01c..aec4285b 100644 --- a/docs/platform/syringe/syringe.rst +++ b/docs/platform/syringe/syringe.rst @@ -6,8 +6,10 @@ Syringe - Antidote's "Brains" .. toctree:: :maxdepth: 1 + configuration.rst syringefile.rst lessonscheduling.rst Syringe is where the real work gets done in the Antidote project. It's responsible for taking in lesson definitions -via :ref:`a YAML file `, and any configs, scripts, etc used in the lesson, and providing them to the \ No newline at end of file +via :ref:`a YAML file `, and any configs, scripts, etc used in the lesson, and providing them to the +front-end via its API. \ No newline at end of file From 767d9653a0c8a007fc237b5a6d834cd637dec734 Mon Sep 17 00:00:00 2001 From: Matt Oswalt Date: Wed, 24 Oct 2018 01:25:29 -0700 Subject: [PATCH 3/9] fix header Signed-off-by: Matt Oswalt --- docs/contributing/curriculum.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/curriculum.rst b/docs/contributing/curriculum.rst index 27dcb24d..0d908471 100644 --- a/docs/contributing/curriculum.rst +++ b/docs/contributing/curriculum.rst @@ -73,7 +73,7 @@ easily replicate what is shown in the lesson. Lesson Details -================================= +^^^^^^^^^^^^^^^^^^^^^^ The best way to get started building lessons is to get an instance of Antidote running on your own laptop. Ironing out all of the bugs before you submit a pull From 43806b5ec340d2ed5b3ae145af8291a260bf54cc Mon Sep 17 00:00:00 2001 From: Matt Oswalt Date: Wed, 24 Oct 2018 01:37:48 -0700 Subject: [PATCH 4/9] Changelog updates Signed-off-by: Matt Oswalt --- CHANGELOG.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a421576b..94ca55b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,15 @@ # CHANGELOG ## In development -- TBD + +### Curriculum + +- Fixed typos in YAML lesson (change) - [#109](https://github.com/nre-learning/antidote/pull/109) (contributed by pklimai) + +### Other + +- Significant restructuring of docs, and large improvements to contribution pages [#108](https://github.com/nre-learning/antidote/pull/108) ## v0.1.0 + - Initial release, announced and made public at NXTWORK 2018 in Las Vegas From b7fa7ac2a1c875ecae53c228d3568506254fc03b Mon Sep 17 00:00:00 2001 From: Matt Oswalt Date: Wed, 24 Oct 2018 10:09:23 -0700 Subject: [PATCH 5/9] Add fetch to changelog script Signed-off-by: Matt Oswalt --- check-changelog.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/check-changelog.sh b/check-changelog.sh index 308c5629..b0198035 100755 --- a/check-changelog.sh +++ b/check-changelog.sh @@ -1,3 +1,4 @@ +git fetch origin master if echo $(git diff --name-only master) | grep -w CHANGELOG.md > /dev/null; then echo "Thanks for making a CHANGELOG update!" exit 0 From fd18fc172118f79d80880cc1f2471131524ffba5 Mon Sep 17 00:00:00 2001 From: Matt Oswalt Date: Wed, 24 Oct 2018 10:09:23 -0700 Subject: [PATCH 6/9] Add fetch to changelog script Signed-off-by: Matt Oswalt --- check-changelog.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/check-changelog.sh b/check-changelog.sh index 308c5629..b0198035 100755 --- a/check-changelog.sh +++ b/check-changelog.sh @@ -1,3 +1,4 @@ +git fetch origin master if echo $(git diff --name-only master) | grep -w CHANGELOG.md > /dev/null; then echo "Thanks for making a CHANGELOG update!" exit 0 From 73427ec959ea3f7188384662d0b3617bed125c23 Mon Sep 17 00:00:00 2001 From: Matt Oswalt Date: Wed, 24 Oct 2018 14:39:07 -0700 Subject: [PATCH 7/9] Finished the curriculum contribution guide for now Signed-off-by: Matt Oswalt --- docs/contributing/curriculum.rst | 86 +++++++++++++++++++------------- 1 file changed, 50 insertions(+), 36 deletions(-) diff --git a/docs/contributing/curriculum.rst b/docs/contributing/curriculum.rst index 0d908471..1490afed 100644 --- a/docs/contributing/curriculum.rst +++ b/docs/contributing/curriculum.rst @@ -3,27 +3,25 @@ Contributing to the Curriculum ============================== -Thanks for contributing to the Antidote curriculum. Before starting, please read this document in its entirety, -so your work has the maximum impact and your time is best spent. +Thanks for contributing to the Antidote curriculum. Before starting your work, please read this +document in its entirety, so your work has the maximum impact and your time is best spent. -Look at existing or in-progress content +Step 1 - Ask Around! ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -1. Read this document in its entirety - -After you have used NRE Labs, know the spirit of it’s break down of workflows as lessons with many quick stages/labs -to progress through, and after you’ve read the quick contributing guide above, then it’s time to dirty your hands. - -4. Make a contribution goal for yourself (or anyone else) to fulfill by opening up a new issue with the “curriculum” -label. Make sure you don’t conflict with an existing issue that is open and in progress. If you do conflict, then -simply consider working together. Here are those existing issues: https://github.com/nre-learning/antidote/issues?q=is%3Aopen+is%3Aissue+label%3Acurriculum -Also make sure you don’t conflict with an existing lesson here: https://github.com/nre-learning/antidote/tree/master/lessons (also look -here to see example of how other lessons are implmented until docs are better) -5. Set off working. - - +Antidote is still in tech preview, so there is a lot of work going on all the time. Before you get +started, make sure you don’t conflict with any existing or current work! +The first step is to peruse the `existing curriculum +issues `_. +If someone's already working on something related to the curriculum, there's a good chance that +there will be an issue there. If not, please first `open an issue `_ +so the community can have a chance to provide feedback on your idea before you spend time building it. There's a chance +that something already exists, or maybe someone else is planning to work on it, and evangelizing your idea first +gives you an opportunity to combine forces with these existing efforts if they exist. +Once you feel like you've gotten good feedback, and you have a good plan in place, read the following section for some +guidelines on how to write a really awesome lesson. Lessons Should Demonstrate Something Useful ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -69,29 +67,45 @@ or tools that are at least free. This helps ensure that a user could more easily replicate what is shown in the lesson. - - - Lesson Details ^^^^^^^^^^^^^^^^^^^^^^ -The best way to get started building lessons is to get an instance of Antidote -running on your own laptop. Ironing out all of the bugs before you submit a pull +Okay. You've determined that you have a good idea for a lesson, and no one else is working on it. +Let's get you started! + +The best ally to have when buliding lessons is a local instance of Antidote +running on your own laptop. Ironing out all of the bugs locally before you submit a pull request makes the review process much smoother. For more info, see the :ref:`local build ` documentation. -You'll also want to get familiar with the :ref:`syringe file ` documentation. - -**Required lab components** - -syringe file -readme for the lab -html layout -Default configs - -tabs will be determined via syringefile and rendered from jinja2 template at -build time. - -The :ref:`Syringe YAML file ` is the main descriptor of a lesson. It is here -that a lesson is defined, it's properties and stages declared, and resources like configs, -scripts, and playbooks referenced. \ No newline at end of file +Once you're ready to start building a lesson, you'll need to create a :ref:`syringe.yaml file`. +This is the primary metadata file for a lesson, and it's here where we declare the attributes (such as the +name of the lesson and what course it belongs to), what resources the lesson needs, and how they connect to +each other (if applicable). + +.. note:: + It's very important to get the ``syringe.yaml`` file right, because it's so central to the + definition of a lesson. Please refer to the :ref:`syringe.yaml docs ` for detailed + documentation on this file. + +This is really the only "required" file for a lesson, but in order to be useful, the ``syringe.yaml`` file will +need to refer to other files like configs, markdown files, and more, in order to be useful. +Take a look at the `existing lessons `_ and see +how those lessons are laid out. What you'll need in your lesson directory will vary wildly, depending on the +contents of your ``syringe.yaml`` file. + +Once you've got your changes together, and pushed to a branch of your own (i.e. in a fork of the Antidote repo), +open a pull request. + +For Reviewers +^^^^^^^^^^^^^ + +Here are a few things that reviewers should be on the lookout for when reviewing new contributions to the +curriculum, either for new or existing lessons: + +- Does the new or changed lesson adhere to the spirit of Antidote lessons laid out in this document? +- For new lessons, does the lesson guide (or jupyter notebook if applicable) look nice? Does the author attribute themselves? +- Is the lesson guide(s) easy to follow? +- Are any documentation updates also needed? +- Is the CHANGELOG updated properly? +- Can we show this in NRE labs? Usage rights? From 388f2a0f32cfc27da86b853268d3e806a3f1bad4 Mon Sep 17 00:00:00 2001 From: Matt Oswalt Date: Wed, 24 Oct 2018 14:42:20 -0700 Subject: [PATCH 8/9] Add note to syringe file doc Signed-off-by: Matt Oswalt --- docs/platform/syringe/syringefile.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/platform/syringe/syringefile.rst b/docs/platform/syringe/syringefile.rst index 913a3f99..73d31057 100644 --- a/docs/platform/syringe/syringefile.rst +++ b/docs/platform/syringe/syringefile.rst @@ -7,6 +7,10 @@ Syringe uses a totally file-driven approach to lesson definitions. This allows u within a Git repository, rather than maintain a database of lesson state all the time. When syringe starts, it looks for lesson definitions within a directory, loads them into memory, and serves them directly via its API. +.. note:: + The way that ``syringe.yaml`` files are put together is still a work-in-progress. Be prepared for changes to + the below information, as we improve Syringe and make it (hopefully) easier to put these lesson files together. + These lesson definitions are written in YAML. A very simple example is shown below. This file describes a very simple lesson in two parts, with a single linux container for interactivity: From 0aa4ecc7bb6836e617ea6637048e0c37ad108b94 Mon Sep 17 00:00:00 2001 From: Matt Oswalt Date: Wed, 24 Oct 2018 14:48:36 -0700 Subject: [PATCH 9/9] Some header changes to curriculum guide Signed-off-by: Matt Oswalt --- docs/contributing/curriculum.rst | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/docs/contributing/curriculum.rst b/docs/contributing/curriculum.rst index 1490afed..3f62afdc 100644 --- a/docs/contributing/curriculum.rst +++ b/docs/contributing/curriculum.rst @@ -23,7 +23,7 @@ gives you an opportunity to combine forces with these existing efforts if they e Once you feel like you've gotten good feedback, and you have a good plan in place, read the following section for some guidelines on how to write a really awesome lesson. -Lessons Should Demonstrate Something Useful +Step 2 - Plan It Out ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Lessons in NRE Labs should demonstrate something useful to a network engineer. @@ -33,13 +33,11 @@ collects system information about a target device. If a user can easily replicate what is shown in the lab so that it can help them in production, then this would be even better. -Planning Lessons -^^^^^^^^^^^^^^^^^^^^^^ +There are multiple ways to build lessons in Antidote. **One-off** -There are multiple ways to build lessons in NRElabs. The simplest method is -to have single one-off lessons that do not have any direct relationship to +The simplest method is to have single one-off lessons that do not have any direct relationship to other lessons. **Repeat** @@ -66,9 +64,8 @@ leveraged to build a lesson. Consider using open-source tools for the lessons, or tools that are at least free. This helps ensure that a user could more easily replicate what is shown in the lesson. - -Lesson Details -^^^^^^^^^^^^^^^^^^^^^^ +Step 3 - Put It Together +^^^^^^^^^^^^^^^^^^^^^^^^ Okay. You've determined that you have a good idea for a lesson, and no one else is working on it. Let's get you started! @@ -94,14 +91,15 @@ Take a look at the `existing lessons `_. Here are a few things that reviewers should be on the lookout for when reviewing new contributions to the -curriculum, either for new or existing lessons: +curriculum, either for new or existing lessons. If you're contributing to the curriculum, you should be aware +of these guidelines, to make the review process much smoother. - Does the new or changed lesson adhere to the spirit of Antidote lessons laid out in this document? - For new lessons, does the lesson guide (or jupyter notebook if applicable) look nice? Does the author attribute themselves?