[WIP] docs: Add (updated old) learn section to envoy docs

[phlax]

Signed-off-by: Ryan Northey ryan@synca.io

Commit Message: docs: Add (updated old) learn section to envoy docs
Additional Description:
The learn section was removed from the website as it was beginning to suffer bitrot and lacked a maintainer

This PR will readd those docs into the main Envoy docs, and add some testing/validation to ensure the docs stay up to date

(atm this PR is very WIP, and is just bringing the docs into the repo tree)

Risk Level: low
Testing: yep
Docs Changes: yep
Release Notes:
[Optional Runtime guard:]
[Optional Fixes #Issue] Fix #9662
[Optional Deprecated:]

[phlax]

the old learn site (unthemed) can be seen here:

https://phlax.github.io/learn.envoy/

[phlax]

the current build of the new tutorial docs can be seen here:

https://387354-65214191-gh.circle-artifacts.com/0/generated/docs/tutorial/index.html

it will rebuild as i make changes, so check latest if there are changes (ie click through circleci for latest url).

atm the most useful thing to focus on is the pages, titles, descriptions and headings - ie the structure

i was tempted to add just these without any copy, but decided against - but just to stress i have not read or formatted (beyond ci requirements) any copy yet, and probably wont until we are happy with the structure

there are some "missing pages" - titles in the original suggestive of where pages should be (eg observability section) - i will probs just add these empty shortly

[mattklein123]

@phlax can you let me know what type of review you want on this change right now? I'm not clear on the current state of the PR.

/wait-any

[phlax]

can you let me know what type of review you want on this change right now?

let me update with the skeleton pages and ill post again tomorrow

I'm not clear on the current state of the PR.

very WIP, but im thinking that ~now is the best time to think about what it should contain - esp if im going to add in some new pages and/or update old ones to better fit with other docs or current ideas

[mattklein123]

OK sounds good just ping me back when this is updated and you want me to take a first pass.

/wait

[phlax]

@mattklein123 i have added the skeleton pages - so the structure - if you browse to the index page, should now resemble the old learn site. i will be updating bits through today, but current build is here https://388458-65214191-gh.circle-artifacts.com/0/generated/docs/tutorial/index.html .

its quite useful moving to rst as the toc shows all the pages and headings in one place - its this we need to focus on atm.

ill breakdown what i think we need to think about now, but things can evolve as we proceed so nothing need be set in stone.

place in docs

i added the learn section as "Envoy tutorial" at the top level of the doc tree, but open to suggestions on that.

We might want to jiggle some things around (intro/tutorial/install, perhaps sandboxes) and/or include the tutorial in one of the other sections. (also see #13408)

structure of tutorial docs

basically the pages and headings, as shown in the toc

one example that im wondering about is whether we need to move "deployment on kubernetes" to it own page

de/duplication

there will inevitably be some duplication in the docs - especially i think in a tutorial section that walks through the other parts of the docs.

there may be some things that are just direct dupes (i need to read through more thoroughly) - eg there is a "lifecycle of a request" page already, and one in the tutorial - likewise some of the sandbox material is very similar to material in the tutorial.

i think duplication doesnt matter too much - if the "voice" and progression through is different, but we want to avoid directly duped material, or pages with the same name.

additional/updated content

the "skeleton" pages are kinda obvious in the toc as they have no subsections.

if we are happy with those pages as being ones that need to be created, agreeing some rough subsections would be good.

eg - for the observability - specifying what techniques and/or extensions are important to showcase in "metrics aggregation"

another eg - maybe we need a page on a specific observability extension. etc

likewise, if you read through the other (non-skeleton) pages and think some pages or sections need to be added/removed/renamed - lmk

---

i think thats if for now. im gonna start working on the copy, fixing links and similar.

[mattklein123]

Thanks @phlax for working on this. VERY excited to see this content coming back to us in a more sustainable way. Here are my high level thoughts:

1. IMO we should merge "Getting started", "Building and installation", and "Envoy Tutorial" into a single section that replaces "Getting started" called "Getting started & tutorial" (or something like that). I think it will make a lot more sense if we take all of the content we have and try to make it read in a more sequential way that builds on itself, dropping duplication where necessary. What do you think? Does it make more sense to just start down this path? I think it will honestly be less work than trying to fix up the old content and then merge it later since so much updating has to happen?
2. one example that im wondering about is whether we need to move "deployment on kubernetes" to it own page: personally, I would rather not mention K8s at all anywhere in our docs. I think it just confuses the issue. IMO the only thing we should depend on here is at most docker / docker compose for any examples. As an aside, I know that @kelseyhightower is working on "service mesh the hard way" which in some ways is very similar to what we are trying to do here so I've asked him offline if he would eventually like to merge/collaborate on any of this.
3. In terms of sections to add/remove, honestly this looks great to start out with. My suggestion is to just figure out the basic content and the merge with the other sections and then we can add more later?

Thank you!!!

[phlax]

we should merge "Getting started", "Building and installation", and "Envoy Tutorial" into a single section that replaces "Getting started" called "Getting started & tutorial" (or something like that). I think it will make a lot more sense if we take all of the content we have and try to make it read in a more sequential way that builds on itself, dropping duplication where necessary. What do you think? Does it make more sense to just start down this path?

yep, agree - with the caveat that eg the sandboxes are more like a reference implementation, so i feel it may be legitimate to walk through similar steps in a tutorial, while keeping the ref docs.

the only thing we should depend on here is at most docker / docker compose for any examples

my guess is that reasoning here is that kubernetes adds too many layers of complexity, and if the key docker concepts are well presented they should be transposable to kubernetes.

Broadly i think i agree

my only concern - i wouldnt want to excise all kubernetes docs/examples altogether. Particularly setting up kubernetes as an edge proxy outside of istio etc, it can be very useful to have an example like this one #13408 (comment)

[mattklein123]

my only concern - i wouldnt want to excise all kubernetes docs/examples altogether. Particularly setting up kubernetes as an edge proxy outside of istio etc, it can be very useful to have an example like this one

I think what I'm mainly suggesting is let's completely ignore K8s for right now and just focus on improving everything else. If we burn through the rest of our doc debt and there is still interest in some level of K8s docs we can discuss then?

[phlax]

If we burn through the rest of our doc debt and there is still interest in some level of K8s docs we can discuss then?

yep, cool

[phlax]

thanks @moderation

ive removed (almost all) of the references - when i start working on the copy, ill have to figure out an equivalent image and set of steps to use as an example of dynamic configuration

[phlax]

@mattklein123 im reviewing this PR again now that we have reorganized/updated existing install

im wondering how best to distinguish the tutorial from sandboxes. One idea i have is to make the tutorial more like a step by step create your own sandbox

the tutorial/getting-started (https://storage.googleapis.com/envoy-pr/13386/docs/start/tutorial/index.html#getting-started) has quite a bit of duplicate and useful info.

Probably im thinking to carve the info on these pages out to other sections, and make it more like getting-started creating an environment for the tutorial (not using any existing sandboxes)

pretty much the same with the "dynamic configuration" section https://storage.googleapis.com/envoy-pr/13386/docs/start/tutorial/index.html#dynamic-configuration

i think there is some really useful info there, that could probs be more useful in relevant sections, and we can make this more like a step by step setting up an envoy with dynamic config

on a related note ive been harbouring ideas about creating a "Dynamic configuration" sandbox. This is an area that i think could be better documented for users wanting dynamic config outside of istio etc.

[phlax]

@mattklein123 just to update with my current plan on this

my feeling was that there was some pretty big gaps in the initial user journey - ie before they got to the stage of working through a tutorial.

With the dynamic sandboxes, and updates to quick-start etc im hoping we will have mostly plugged those gaps. I think if we had not tackled that first, the temptation would have been to use the tutorial to do that.

i have a pretty good idea now (in my head) of how i would like to structure the tutorial, and will update in the next day or two

[mattklein123]

Great in general sounds like a plan. Looking forward to seeing the draft!

/wait

[phlax]

so my current thinking on this is to build a step-by-step microcosmic service mesh

very roughly, the steps im currently thinking about

• start with the default container
• add a composition
• make config (fs) dynamic
• add upstream service/s with load balancing
• add csrf
• add caching
• add custom wasm filter
• and mtls
• add sds
• add websocket/service
• add proxy to upstream persistence (eg postgres)
• add observability and tracing
• inject faults and observe
• add blue/green deployment

i will re/use any techniques and concepts in the orig where relevant

[mattklein123]

@phlax at a high level ^ makes sense to me. Is that the order that you thinking about? As I think that some of the things later in the list are more important concept wise than earlier in the list.

[phlax]

Is that the order that you thinking about?

by no means set in stone, but very roughly perhaps

im not thinking to dwell too much on the basics, and now we have the quick-start guide updated we can point to that, but the plan i have in mind is to kinda go from zero to hero, so it will need to start with some basics

im wondering about progression and testing - which ultiimately could resolve each other in a sense.

by progression, im meaning that if you cut in at (eg) lesson 5, but havent done previous parts you will need a ~copy of the env so far

one way im thinking to resolve this is that each page/lesson begins with the resultant config/env of the previous lesson which can be downloaded or perhaps cded to like with the sandboxes

this would make it easier to test the steps too

[github-actions]

This pull request has been automatically marked as stale because it has not had activity in the last 30 days. It will be closed in 7 days if no further activity occurs. Please feel free to give a status update now, ping for review, or re-open when it's ready. Thank you for your contributions!

[github-actions]

This pull request has been automatically closed because it has not had activity in the last 37 days. Please feel free to give a status update now, ping for review, or re-open when it's ready. Thank you for your contributions!