Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Breakdown Architecture into Guide pages #11

Open
wants to merge 83 commits into
base: andyet/docs-v4.1
Choose a base branch
from

Conversation

one000mph
Copy link

@one000mph one000mph commented Oct 10, 2019

Overview of Changes

  • Updates TOC/sidebar to reflect new Outline (Issue Docs Outline #2)
  • Condensed Architecture Guide
    • Design Principles
    • Detailed Connection Walkthrough
  • Auth Service
    • Authn vs Authz
    • Purpose of Certificates
    • Issuing & Using Certificates
    • Certificate Rotation
    • Auth Server API
    • Auth State
  • Teleport Basic Concepts
    • Simplify Service Description, move bulk of discussion to other Concept pages
  • Node Service
  • Proxy Service
  • Users Service
  • A few typo corrections in code comments (let me know if you prefer that I don't correct these)

Motivation
This PR introduces a new section called "Concepts". This change attempts to address a couple of issue I saw in the previous docs version.

  1. Many of the chapters were quite long (2000+ words). Even with the sidebar TOC to help users jump to sections within pages, some pages felt difficult to navigate and digest.
  2. The same idea (e.g. Auth Service) was explained in multiple places, but there was not one source definition or description to point users to.

In this PR I attempted to pull out the key concepts of Teleport and write explainer docs on each of them. I also attempted to eliminate the need for repetitive explanations of concepts in the step-by-step guide. Guides can now focus on practical tasks and provide minimal inline definitions. They will reference users to concept docs for detailed explanations of terms and ideas.

Possible Problems
As I was writing I found that it was hard to describe each concept alone without duplicating some information between docs. For example the Proxy Service relies heavily on the Auth Service so you can't really discuss one without the other. As these are refined it will be challenging to describe each concept clearly while minimizing duplicate information.

Graphics
I still need to create or revise graphics for most of these pages. This can be done in a later PR so non-blocking. It would be nice to use some of the existing graphical elements to preserve a consistent feel, but if that's not possible I can start from scratch on lucidchart.

klizhentas and others added 25 commits October 1, 2019 10:25
This commit fixes goroutine leak - whenever
a leaf cluster disconnects from the root cluster,
the caching access point cache update loop has to be closed
as well.
Fixed anti-pattern use of /var/run as the PID dir
* First draft updating Trusted Cluster
…nal#2956)

* Info for backup and Restore
* Include information about path in storage.
* Add Dynamo stream configuration
* Update to NEW_IMAGE as per docs
* PV template to use Values.persistence.accessMode

* use apps/v1

* expose replica count for modification
@one000mph one000mph marked this pull request as ready for review October 10, 2019 19:09
@one000mph
Copy link
Author

Added diagrams and got this to a place where the Architecture Section (formerly known as Concepts) replaces the previous Architecture Guide.

@one000mph one000mph changed the title Adds Concept Guides Breakdown Architecture into Guide pages Oct 16, 2019
Copy link

@webvictim webvictim left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if this is officially "ready for review" yet but I was browsing through and thought I'd add some comments. Looks great overall.

docs/4.1/architecture/auth.md Outdated Show resolved Hide resolved
docs/4.1/architecture/auth.md Outdated Show resolved Hide resolved
docs/4.1/architecture/auth.md Outdated Show resolved Hide resolved
docs/4.1/architecture/auth.md Outdated Show resolved Hide resolved
docs/4.1/architecture/auth.md Outdated Show resolved Hide resolved
docs/4.1/architecture/proxy.md Outdated Show resolved Hide resolved
docs/4.1/architecture/users.md Outdated Show resolved Hide resolved
docs/4.1/architecture/users.md Outdated Show resolved Hide resolved
docs/4.1/architecture/users.md Show resolved Hide resolved
docs/4.1/architecture/users.md Outdated Show resolved Hide resolved
@one000mph
Copy link
Author

Not sure if this is officially "ready for review" yet but I was browsing through and thought I'd add some comments. Looks great overall.

@webvictim thanks for the review and catching some typos!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

10 participants