extern/zrok
1
1
Fork 0
mirror of https://github.com/openziti/zrok.git synced 2025-01-10 16:08:20 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #209 from openziti/qrkourier-patch-3

Browse Source 
use ziti quickstart with external DNS
This commit is contained in:
Ken Bingham 2023-02-02 18:13:48 -05:00 committed by GitHub
commit 6a532b40c5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 36 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/guides/v0.3_self_hosting_guide.md
View File

@ -1,16 +1,17 @@
# 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/
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 "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:
@ -19,6 +20,12 @@ 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/learn/quickstarts/network/hosted)
## Install zrok
Download [the latest release](https://github.com/openziti/zrok/releases/latest) 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.
@ -30,7 +37,7 @@ Create a controller configuration file in `etc/ctrl.yml`. The controller does no
# /___|_| \___/|_|\_\
# controller configuration
v: 1
v: 2
admin:
secrets:
@ -62,12 +69,12 @@ 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:
```bash
$ export ZROK_API_ENDPOINT=http://localhost:18080
export ZROK_API_ENDPOINT=http://localhost:18080
```
## Bootstrap OpenZiti for zrok
@ -113,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:
@ -133,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
@ -140,7 +151,20 @@ $ 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
# list Ziti identities created by the quickstart and bootstrap
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