Quickstart walkthrough #690
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
| title: Quickstart Walkthrough | ||
| id: quickstart-walkthrough | ||
| --- | ||
| The following will walk you through the manual process of creating an overlay network with your own PKI. These steps are the same steps that take place behind the scenes when running the OpenZiti Quickstart’s `expressInstall` function. |
There was a problem hiding this comment.
The following will
feels like it's missing "document", or "page", or "article" or "something"?
the manual process of creating an overlay network
Maybe change this paragraph to:
This page is intended to explain the steps that happen automatically when the
expressInstallfunction is executed. The [Local - No Docker](add link), [Local - With Docker](add link), [Local - Docker Compose](add link), and [Host OpenZiti Anywhere] quickstarts all run theexpressInstallfunction. Each version varies slightly. This page will focus on the Host OpenZiti Anywhere quickstart.
There was a problem hiding this comment.
It's probably best to 'outline' what happens here too.
- make directory
- establish env vars
- create config for controller
- init ziti controller
- create router config
- create router in controller
- enroll router
- add default policies (erp/serp)
That basically gives you the rest of the outline to then fill in where you can add things like what each env var is, and which ones are important, what the pki looks like, why it looks like it does (aka 'complex' vs 'as simple as necessary') etc.
|
|
||
| ### Declare Variables | ||
|
|
||
| Some global variables used throughout the overlay setup. |
There was a problem hiding this comment.
I don't always say this, but it feels like this needs more words for clarity:
The first thing
expressInstallwill do is establish numerous environment variables used throughout the script. Some important variables are listed below.
docusaurus/docs/learn/quickstarts/network/help/quickstart-walkthrough.md
Outdated
Show resolved
Hide resolved
|
|
||
| ### Create Environment | ||
|
|
||
| Create a directory where you will store your network files. |
There was a problem hiding this comment.
I'd change the 'you/your' here. Feels out of place. Try to be critical about using 'you/your' and remove it when possible.
Also more words, maybe with the outline this will feel more natural. Would be good to explain how the ZITI_HOME is set if the user doesn't set it.
|
|
||
| ### Obtain Ziti Binary | ||
|
|
||
| The ziti binary is required to setup the network. The exact URL will differ depending on your operating system and architecture. Visit the [releases](https://github.com/openziti/ziti/releases) page to get the appropriate URL. |
There was a problem hiding this comment.
You should explain that getZiti is used for this purpose and explain what/how it works. It detects your OS, it solicits github for the latest released version and crafts the proper url to download the binary (and then extract it to the ZITI_BIN_DIR). Also, this would be a good place to add a:
:::note
you don't have to always run expressInstall when running the quickstart. you can source the ziti-cli-function.sh file and run getZiti to get the latest version of ziti installed quickly and easily
:::
|
|
||
| ## Create PKI | ||
|
|
||
| You may use an existing PKI if you prefer, however, as part of the `expressInstall` a PKI is generated for you. The following will run through the process of generating your own PKI. |
There was a problem hiding this comment.
You may use an existing PKI if you prefer
There's no option to do this? This page is explaining the steps that the quickstart DOES. it most definitely makes a new pki every time so it's not a preference, right?
|
|
||
| ### Setup | ||
|
|
||
| Set some initial environment variables for setting up the PKI. The `CA_NAME` values can be any name of your choosing. |
There was a problem hiding this comment.
These are all optional. After reading this far, I don't think we should get into the depths of the options the quickstart provides OTHER than what we show people on the host it anywhere page. I think it would be worthwhile to add more doc around the quickstart and all these variables that allow people to customize the quickstart install, but not here
There was a problem hiding this comment.
What do you mean these are optional? Is this walkthrough just explaining what quickstart does? I thought we were providing the steps to mimic expressInstall "manually".
There was a problem hiding this comment.
i was learning towards an explainer of the quickstart and the "five" or so things people actually change (usually)
export EXTERNAL_IP="$(curl -s eth0.me)"
export ZITI_CTRL_EDGE_IP_OVERRIDE="${EXTERNAL_IP}"
export ZITI_ROUTER_IP_OVERRIDE="${EXTERNAL_IP}"
export ZITI_CTRL_EDGE_ADVERTISED_ADDRESS="${EXTERNAL_DNS:-${EXTERNAL_IP}}"
export ZITI_ROUTER_ADVERTISED_ADDRESS="${EXTERNAL_DNS:-${EXTERNAL_IP}}"
export ZITI_CTRL_ADVERTISED_PORT=8440
export ZITI_CTRL_EDGE_ADVERTISED_PORT=8441
export ZITI_ROUTER_PORT=8442
these mostly. we can go on to explain that the express install makes a pki for control plane, data plane and api but not how to customize it. that's more detaill than i wanted in this particular guide. i want them to understand what it does, not how to customize it.
then, having all these type of variables doc'ed in some reference doc telling them how to tweak them all makes sense to me.
that help?
There was a problem hiding this comment.
Okay, so this is more of an explanation rather than a "this is how you can mimic the quickstart manually"? So, rather than the env vars, should I put hard-coded values for the PKI creation?
docusaurus/docs/learn/quickstarts/network/help/quickstart-walkthrough.md
Outdated
Show resolved
Hide resolved
|
|
||
| ### Create Server and Client Certs for the Control Plane | ||
|
|
||
| Set up some initial values for the server and client certificates. |
There was a problem hiding this comment.
remove and condense into just one "pki-related" section.
|
|
||
| ### Update the CA Bundle | ||
|
|
||
| Add the CAs to the CA bundle and make a copy for the HTTP API CA bundle. |
There was a problem hiding this comment.
explain 'why' this is done. it's important to understand the motivation behind doing this
|
|
||
| ### Setup | ||
|
|
||
| Declare some environment variables used to generate the controller config file. Some environment variables used were already set previously. |
There was a problem hiding this comment.
mmmm. i guess i need to walk back a little bit here. these are all vitally important to the quickstart. explain what each of these variables does in more detail. the short description just isn't enough. i can see a bunch of this doc being reusable in a more "quickstart reference" tpye doc too so don't just throw it all away when you remove it. consider adding it to some kind of page that talks about all the various env vars that can be set and what they do
|
|
||
| ### Initialize the Controller | ||
|
|
||
| Initializing the controller sets up database files and some of the configuration values. |
There was a problem hiding this comment.
This uses the config file to initialize the database and nothing else.
|
|
||
| ### Wait for the Controller | ||
|
|
||
| We want to ensure the controller is ready before creating a router, this mini loop |
There was a problem hiding this comment.
Definitely don't use 'we' or "we'll" in the doc. You don't need to explain the loop, just that it's important for the controller to be online before proceeding
There was a problem hiding this comment.
you should explain WHY the controller needs to be online though.
|
|
||
| ``` | ||
| # We have to log in first | ||
| "${ZITI_BIN_DIR}/ziti" edge login ${ZITI_CTRL_ADVERTISED_ADDRESS}:${ZITI_CTRL_EDGE_ADVERTISED_PORT} -u admin -p $ZITI_PWD -y |
|
|
||
| ### Create the Router Config File | ||
|
|
||
| Just as with the controller, we need to create a router config file. The router config also uses values set in environment variables up to this point. |
There was a problem hiding this comment.
i would use words and explain where the config files go, what they look like and how they are named by default. It's fine to show all these commands but I think it might be useful to put them behind a
|
|
||
| ## Confirm the Network is Up | ||
|
|
||
| Log in and run a command to list the edge routers and we should see a single edge router showing `ONLINE`. |
There was a problem hiding this comment.
the quickstat does not leave the network in a state that this can be done, so technically this is inaccurate. you'd have to startController and startRouter but the quickstart doesn't do that. I'd say the ending is when the 'success' banner is printed
|
@gberl002 numerous comments added. I think it needs to be reworked a bit |
No description provided.