From d712d5eeebefcdefc2d9ea4f110b7e93e1303270 Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Wed, 5 Apr 2023 20:20:31 -0400 Subject: [PATCH 1/4] bump controller config version to 3 --- README.md | 2 +- docs/core-features/hosting.md | 2 +- docs/getting-started.md | 2 +- .../{v0.3_nginx_tls_guide.md => nginx_tls_guide.md} | 2 +- .../{v0.3_self_hosting_guide.md => self_hosting_guide.md} | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) rename docs/guides/self-hosting/{v0.3_nginx_tls_guide.md => nginx_tls_guide.md} (97%) rename docs/guides/self-hosting/{v0.3_self_hosting_guide.md => self_hosting_guide.md} (99%) diff --git a/README.md b/README.md index 84a7a2a0..072dbbdf 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ See the [Concepts and Getting Started Guide](docs/getting-started.md) for a full The single `zrok` binary contains everything you need to operate `zrok` environments and also host your own service instances. Just add an OpenZiti network and you're up and running. -See the [Self-Hosting Guide](docs/guides/v0.3_self_hosting_guide.md) for details on getting your own `zrok` service instance running. This builds on top of the [OpenZiti Quick Start](https://docs.openziti.io/docs/learn/quickstarts/network/) to have a running `zrok` service instance in minutes. +See the [Self-Hosting Guide](docs/guides/self_hosting_guide.md) for details on getting your own `zrok` service instance running. This builds on top of the [OpenZiti Quick Start](https://docs.openziti.io/docs/learn/quickstarts/network/) to have a running `zrok` service instance in minutes. ## Building diff --git a/docs/core-features/hosting.md b/docs/core-features/hosting.md index 59523345..20e44264 100644 --- a/docs/core-features/hosting.md +++ b/docs/core-features/hosting.md @@ -5,7 +5,7 @@ sidebar_position: 200 ## Self-Hosted -`zrok` is not limited to a managed offering. You can [host your own](../guides/self-hosting/v0.3_self_hosting_guide.md) instance of `zrok` as well. `zrok` is +`zrok` is not limited to a managed offering. You can [host your own](../guides/self-hosting/self_hosting_guide.md) instance of `zrok` as well. `zrok` is also freely available as open source software hosted by GitHub under a very permissive Apache v2 license. ## Managed Service diff --git a/docs/getting-started.md b/docs/getting-started.md index d2d81b50..ff8d83c1 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -430,7 +430,7 @@ You use the `zrok reserve` command to create _reserved shares_. Reserved shares ## Self-Hosting a Service Instance -Interested in self-hosting your own `zrok` service instance? See the [self-hosting guide](./guides/self-hosting/v0.3_self_hosting_guide.md) for details. +Interested in self-hosting your own `zrok` service instance? See the [self-hosting guide](./guides/self-hosting/self_hosting_guide.md) for details. [openziti]: https://docs.openziti.io/docs/learn/introduction/ "OpenZiti" [ zrok-download]: https://zrok.io "Zrok Download" diff --git a/docs/guides/self-hosting/v0.3_nginx_tls_guide.md b/docs/guides/self-hosting/nginx_tls_guide.md similarity index 97% rename from docs/guides/self-hosting/v0.3_nginx_tls_guide.md rename to docs/guides/self-hosting/nginx_tls_guide.md index 438d1164..183a471a 100644 --- a/docs/guides/self-hosting/v0.3_nginx_tls_guide.md +++ b/docs/guides/self-hosting/nginx_tls_guide.md @@ -11,7 +11,7 @@ sidebar_label: Nginx TLS ## Before You Begin -I'll assume you have a running zrok controller and public frontend and wish to front both with Nginx providing server TLS. Go back to [Self-Hosting Guide](./v0.3_self_hosting_guide.md) if you still need to spin those up. +I'll assume you have a running zrok controller and public frontend and wish to front both with Nginx providing server TLS. Go back to [Self-Hosting Guide](./self_hosting_guide.md) if you still need to spin those up. ## Choose a Reverse Proxy Address diff --git a/docs/guides/self-hosting/v0.3_self_hosting_guide.md b/docs/guides/self-hosting/self_hosting_guide.md similarity index 99% rename from docs/guides/self-hosting/v0.3_self_hosting_guide.md rename to docs/guides/self-hosting/self_hosting_guide.md index 54031813..2f6d7dfe 100644 --- a/docs/guides/self-hosting/v0.3_self_hosting_guide.md +++ b/docs/guides/self-hosting/self_hosting_guide.md @@ -47,7 +47,7 @@ Create a controller configuration file in `etc/ctrl.yml`. The controller does no # /___|_| \___/|_|\_\ # controller configuration -v: 2 +v: 3 admin: secrets: From db8d2e55a3d8c78e27976224ebe9a3b446fe7a5e Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Thu, 6 Apr 2023 13:38:48 -0400 Subject: [PATCH 2/4] tweak self-hosting guide --- docs/guides/self-hosting/self_hosting_guide.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/guides/self-hosting/self_hosting_guide.md b/docs/guides/self-hosting/self_hosting_guide.md index 2f6d7dfe..84dec517 100644 --- a/docs/guides/self-hosting/self_hosting_guide.md +++ b/docs/guides/self-hosting/self_hosting_guide.md @@ -179,7 +179,9 @@ Nice work! The `zrok` controller is fully configured now that you have created t ## Configure the Public Frontend -Create `etc/http-frontend.yml`. You must reiterate the pattern you expressed in the public frontend URL template as a `host_match` pattern, and you may change the default address where the frontend will listen for public access requests. The frontend does not provide server TLS, but you may front the server with a reverse proxy. It is essential the reverse proxy forwards the `Host` header supplied by the viewer. This example will expose the non-TLS listener for the frontend. +Create `etc/http-frontend.yml`. This frontend config file has a `host_match` pattern that represents the DNS zone you're using with this instance of zrok. Incoming HTTP requests with a matching `Host` header will be handled by this frontend. You may also specify the interface address where the frontend will listen for public access requests. + +The frontend does not provide server TLS, but you may front the server with a reverse proxy. It is essential the reverse proxy forwards the `Host` header supplied by the viewer. This example will expose the non-TLS listener for the frontend. ```yaml host_match: zrok.quigley.com From 650e1c131bd9f9e3fb3bc3ff87b6ac387faa4dbb Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Fri, 7 Apr 2023 15:18:14 -0400 Subject: [PATCH 3/4] hint the minimum Ziti version --- docs/guides/v0.4_metrics.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 docs/guides/v0.4_metrics.md diff --git a/docs/guides/v0.4_metrics.md b/docs/guides/v0.4_metrics.md new file mode 100644 index 00000000..48fd1ffd --- /dev/null +++ b/docs/guides/v0.4_metrics.md @@ -0,0 +1,31 @@ +`v0.4` includes a new metrics infrastructure based on OpenZiti usage, which provides `zrok` with telemetry used to power end-user intelligence about shares, and also to power usage-based limits. + +# Configuration + +This requires a version of OpenZiti with a `fabric` dependency of `v0.22.52` or newer, which is satisfed by the `v0.27.6` release of OpenZiti Controller. + +## controller configuration + +```yaml +network: + intervalAgeThreshold: 5s + metricsReportInterval: 5s + +events: + jsonLogger: + subscriptions: + - type: fabric.usage + version: 3 + handler: + type: file + format: json + path: /tmp/fabric-usage.log +``` + +## router configuration + +```yaml +metrics: + reportInterval: 5s + intervalAgeThreshold: 5s +``` From 75758b5ab16ee890fcbca66ff54b1c8d3bad60cb Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Mon, 10 Apr 2023 09:27:32 -0400 Subject: [PATCH 4/4] mention that InfluxDB bucket, org must be created in advance --- .../metrics-and-limits/configuring-metrics.md | 6 ++-- docs/guides/v0.4_metrics.md | 31 ------------------- 2 files changed, 3 insertions(+), 34 deletions(-) delete mode 100644 docs/guides/v0.4_metrics.md diff --git a/docs/guides/metrics-and-limits/configuring-metrics.md b/docs/guides/metrics-and-limits/configuring-metrics.md index 5d58cfc7..b0072f43 100644 --- a/docs/guides/metrics-and-limits/configuring-metrics.md +++ b/docs/guides/metrics-and-limits/configuring-metrics.md @@ -92,12 +92,12 @@ metrics: queue_name: events influx: url: "http://127.0.0.1:8086" - bucket: zrok - org: zrok + bucket: zrok # the bucket and org must be + org: zrok # created in advance in InfluxDB token: "" ``` -This configures the `zrok` controller to consume usage events from the AMQP queue, and configures the InfluxDB metrics store. +This configures the `zrok` controller to consume usage events from the AMQP queue, and configures the InfluxDB metrics store. The InfluxDB organization and bucket must be created in advance. The `zrok` controller will not create these for you. ## Testing Metrics diff --git a/docs/guides/v0.4_metrics.md b/docs/guides/v0.4_metrics.md deleted file mode 100644 index 48fd1ffd..00000000 --- a/docs/guides/v0.4_metrics.md +++ /dev/null @@ -1,31 +0,0 @@ -`v0.4` includes a new metrics infrastructure based on OpenZiti usage, which provides `zrok` with telemetry used to power end-user intelligence about shares, and also to power usage-based limits. - -# Configuration - -This requires a version of OpenZiti with a `fabric` dependency of `v0.22.52` or newer, which is satisfed by the `v0.27.6` release of OpenZiti Controller. - -## controller configuration - -```yaml -network: - intervalAgeThreshold: 5s - metricsReportInterval: 5s - -events: - jsonLogger: - subscriptions: - - type: fabric.usage - version: 3 - handler: - type: file - format: json - path: /tmp/fabric-usage.log -``` - -## router configuration - -```yaml -metrics: - reportInterval: 5s - intervalAgeThreshold: 5s -```