From 1ec24666ffe9c78011d2548831712d59759f8e2b Mon Sep 17 00:00:00 2001 From: Ken Bingham Date: Wed, 1 Feb 2023 16:46:14 -0500 Subject: [PATCH 1/8] use the ziti quickstart that uses external DNS It's important for the ziti controller to advertise a global domain name for a self-hosted zrok to be useful Signed-off-by: Ken Bingham --- docs/guides/v0.3_self_hosting_guide.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/guides/v0.3_self_hosting_guide.md b/docs/guides/v0.3_self_hosting_guide.md index 94171981..8448aab6 100644 --- a/docs/guides/v0.3_self_hosting_guide.md +++ b/docs/guides/v0.3_self_hosting_guide.md @@ -2,15 +2,9 @@ ## OpenZiti Quickstart -https://openziti.github.io/docs/quickstarts/network/ +[https://openziti.github.io/docs/quickstarts/network/](https://docs.openziti.io/docs/learn/quickstarts/network/hosted) -I specifically used the "no docker" variant: - -```bash -$ source /dev/stdin <<< "$(wget -qO- https://get.openziti.io/quick/ziti-cli-functions.sh)"; expressInstall -$ startController -$ startRouter -``` +I specifically used the "Host OpenZiti Anywhere" variant because it provides a public controller. We'll need that to use zrok with multiple devices across different networks. Keep track of the generated admin password when running the `expressInstall` script. The script will prompt you like this: From e7e9f6b26148792bdbbf2e9eb36f00c488e8587f Mon Sep 17 00:00:00 2001 From: Ken Bingham Date: Wed, 1 Feb 2023 16:55:44 -0500 Subject: [PATCH 2/8] correct the controller config version Signed-off-by: Ken Bingham --- docs/guides/v0.3_self_hosting_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/v0.3_self_hosting_guide.md b/docs/guides/v0.3_self_hosting_guide.md index 8448aab6..636e174b 100644 --- a/docs/guides/v0.3_self_hosting_guide.md +++ b/docs/guides/v0.3_self_hosting_guide.md @@ -24,7 +24,7 @@ Create a controller configuration file in `etc/ctrl.yml`. The controller does no # /___|_| \___/|_|\_\ # controller configuration -v: 1 +v: 2 admin: secrets: From a0c86f06f721279e5b94e345b5841a502cd2e083 Mon Sep 17 00:00:00 2001 From: Ken Bingham Date: Wed, 1 Feb 2023 17:09:30 -0500 Subject: [PATCH 3/8] Update v0.3_self_hosting_guide.md Signed-off-by: Ken Bingham --- docs/guides/v0.3_self_hosting_guide.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/guides/v0.3_self_hosting_guide.md b/docs/guides/v0.3_self_hosting_guide.md index 636e174b..3666349a 100644 --- a/docs/guides/v0.3_self_hosting_guide.md +++ b/docs/guides/v0.3_self_hosting_guide.md @@ -13,6 +13,10 @@ Do you want to keep the generated admin password 'XO0xHp75uuyeireO2xmmVlK91T7B9f ``` You'll need that generated password (`XO0xHp75uuyeireO2xmmVlK91T7B9fpD`) when building your `zrok` controller configuration. +## Install zrok + +Download [the latest release](https://github.com/openziti/zrok/releases/tag/v0.3.0-rc5) from GitHub. + ## Configure the Controller Create a controller configuration file in `etc/ctrl.yml`. The controller does not provide server TLS, but you may front the server with a reverse proxy. This example will expose the non-TLS listener for the controller. @@ -56,7 +60,7 @@ The `ziti` section defines how the `zrok` controller should communicate with you The `zrok` binaries are configured to work with the global `zrok.io` service, and default to using `api.zrok.io` as the endpoint for communicating with the service. -To work with a local `zrok` deployment, you'll need to set the `ZROK_API_ENDPOINT` environment variable to point to the address where your `zrok` controller will be listening, according to `endpoint` in the configuration file above. +To work with a self-hosted `zrok` deployment, you'll need to set the `ZROK_API_ENDPOINT` environment variable to point to the address where your `zrok` controller will be listening, according to `endpoint` in the configuration file above. In my case, I've set: From 214129635fdb2cdf2e3315ed05f370ecdc51584f Mon Sep 17 00:00:00 2001 From: Ken Bingham Date: Wed, 1 Feb 2023 22:24:16 -0500 Subject: [PATCH 4/8] Update v0.3_self_hosting_guide.md Signed-off-by: Ken Bingham --- docs/guides/v0.3_self_hosting_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/v0.3_self_hosting_guide.md b/docs/guides/v0.3_self_hosting_guide.md index 3666349a..789a47b4 100644 --- a/docs/guides/v0.3_self_hosting_guide.md +++ b/docs/guides/v0.3_self_hosting_guide.md @@ -15,7 +15,7 @@ You'll need that generated password (`XO0xHp75uuyeireO2xmmVlK91T7B9fpD`) when bu ## Install zrok -Download [the latest release](https://github.com/openziti/zrok/releases/tag/v0.3.0-rc5) from GitHub. +Download [the latest release](https://github.com/openziti/zrok/releases/latest) from GitHub. ## Configure the Controller From d240652118bb4a9debb0ea0eba175d3183faad9c Mon Sep 17 00:00:00 2001 From: Ken Bingham Date: Wed, 1 Feb 2023 22:31:30 -0500 Subject: [PATCH 5/8] add "Before you Begin" Signed-off-by: Ken Bingham --- docs/guides/v0.3_self_hosting_guide.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/guides/v0.3_self_hosting_guide.md b/docs/guides/v0.3_self_hosting_guide.md index 789a47b4..69b88720 100644 --- a/docs/guides/v0.3_self_hosting_guide.md +++ b/docs/guides/v0.3_self_hosting_guide.md @@ -1,8 +1,15 @@ # Self-Hosting Guide +## Before you Begin + +This will get you up and running with a self-hosted instance of zrok. I'll assume you have the following: + +* a Linux server with a public IP +* a wildcard DNS record like `*.zrok.quigley.com` that resolves to the server IP + ## OpenZiti Quickstart -[https://openziti.github.io/docs/quickstarts/network/](https://docs.openziti.io/docs/learn/quickstarts/network/hosted) +The first step is to log in to your Linux server and run the OpenZiti quickstart. This will install a Ziti controller and Ziti router as systemd services. I specifically used the "Host OpenZiti Anywhere" variant because it provides a public controller. We'll need that to use zrok with multiple devices across different networks. @@ -13,6 +20,8 @@ Do you want to keep the generated admin password 'XO0xHp75uuyeireO2xmmVlK91T7B9f ``` You'll need that generated password (`XO0xHp75uuyeireO2xmmVlK91T7B9fpD`) when building your `zrok` controller configuration. +BEGIN: [Run the OpenZiti Quickstart](https://docs.openziti.io/docs/quickstarts/network/) + ## Install zrok Download [the latest release](https://github.com/openziti/zrok/releases/latest) from GitHub. From addd4156322c225048781bf43c73c69ec121fe5f Mon Sep 17 00:00:00 2001 From: Ken Bingham Date: Wed, 1 Feb 2023 22:32:37 -0500 Subject: [PATCH 6/8] link to hosted quickstart Signed-off-by: Ken Bingham --- docs/guides/v0.3_self_hosting_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/v0.3_self_hosting_guide.md b/docs/guides/v0.3_self_hosting_guide.md index 69b88720..1898f680 100644 --- a/docs/guides/v0.3_self_hosting_guide.md +++ b/docs/guides/v0.3_self_hosting_guide.md @@ -20,7 +20,7 @@ Do you want to keep the generated admin password 'XO0xHp75uuyeireO2xmmVlK91T7B9f ``` You'll need that generated password (`XO0xHp75uuyeireO2xmmVlK91T7B9fpD`) when building your `zrok` controller configuration. -BEGIN: [Run the OpenZiti Quickstart](https://docs.openziti.io/docs/quickstarts/network/) +BEGIN: [Run the OpenZiti Quickstart](https://docs.openziti.io/docs/learn/quickstarts/network/hosted) ## Install zrok From a9c056ca8d7669486f37fe4939d2872ed009911b Mon Sep 17 00:00:00 2001 From: Ken Bingham Date: Thu, 2 Feb 2023 14:19:00 -0500 Subject: [PATCH 7/8] add headings to emphasize the steps in the procedure Signed-off-by: Ken Bingham --- docs/guides/v0.3_self_hosting_guide.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/guides/v0.3_self_hosting_guide.md b/docs/guides/v0.3_self_hosting_guide.md index 1898f680..7e14b599 100644 --- a/docs/guides/v0.3_self_hosting_guide.md +++ b/docs/guides/v0.3_self_hosting_guide.md @@ -74,7 +74,7 @@ To work with a self-hosted `zrok` deployment, you'll need to set the `ZROK_API_E In my case, I've set: ```bash -$ export ZROK_API_ENDPOINT=http://localhost:18080 +export ZROK_API_ENDPOINT=http://localhost:18080 ``` ## Bootstrap OpenZiti for zrok @@ -120,6 +120,8 @@ Notice this warning: [ 0.120] WARNING zrok/controller.Bootstrap: missing public frontend for ziti id 'sqJRAINSiB'; please use 'zrok admin create frontend sqJRAINSiB public https://{token}.your.dns.name' to create a frontend instance ``` +## Run zrok Controller + The `zrok` bootstrap process wants us to create a "public frontend" for our service. `zrok` uses public frontends to allow users to specify where they would like public traffic to ingress from. The `zrok admin create frontend` command requires a running `zrok` controller, so let's start that up first: @@ -140,6 +142,8 @@ $ zrok controller etc/ctrl.yml [ 0.085] INFO zrok/controller.(*metricsAgent).listen: started ``` +## Create zrok Frontend + With our `ZROK_ADMIN_TOKEN` and `ZROK_API_ENDPOINT` environment variables set, we can create our public frontend like this: ```bash @@ -147,7 +151,19 @@ $ zrok admin create frontend sqJRAINSiB public http://{token}.zrok.quigley.com:8 [ 0.037] INFO main.(*adminCreateFrontendCommand).run: created global public frontend 'WEirJNHVlcW9' ``` -Now our `zrok` controller is fully configured. +The id of the frontend was emitted earlier in by the zrok controller when we ran the bootstrap command. If you don't have that log message the you can find the id again with the `ziti` CLI like this: + +```bash +# initialize the Ziti quickstart env +source ~/.ziti/quickstart/$(hostname -s)/$(hostname -s).env +# login as admin +zitiLogin +# ziti edge list identities +``` + +The id is shown for the "frontend" identity. + +Nice work! The `zrok` controller is fully configured now that you have created the zrok frontend. ## Configure the Public Frontend From f2a32c39913d9ec07926d009f2c17539e23b30c4 Mon Sep 17 00:00:00 2001 From: Ken Bingham Date: Thu, 2 Feb 2023 14:20:50 -0500 Subject: [PATCH 8/8] fix a typo Signed-off-by: Ken Bingham --- docs/guides/v0.3_self_hosting_guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guides/v0.3_self_hosting_guide.md b/docs/guides/v0.3_self_hosting_guide.md index 7e14b599..b9df9475 100644 --- a/docs/guides/v0.3_self_hosting_guide.md +++ b/docs/guides/v0.3_self_hosting_guide.md @@ -158,7 +158,8 @@ The id of the frontend was emitted earlier in by the zrok controller when we ran source ~/.ziti/quickstart/$(hostname -s)/$(hostname -s).env # login as admin zitiLogin -# ziti edge list identities +# list Ziti identities created by the quickstart and bootstrap +ziti edge list identities ``` The id is shown for the "frontend" identity.