more refinement, rearranging etc. word changes that seem to need to change

This commit is contained in:
dovholuknf 2023-01-29 17:22:53 -05:00
parent 75f90aa1ef
commit 725d4046cb
No known key found for this signature in database
GPG Key ID: 0EE08251136D3480
12 changed files with 31 additions and 35 deletions

View File

@ -1,6 +1,6 @@
![zrok](docs/images/zrok.png)
`zrok` is a next-generation sharing platform built on top of [Ziti](https://docs.openziti.io), a programmable zero-trust network overlay. `zrok` is a _Ziti Native Application_.
`zrok` is a next-generation sharing platform built on top of [OpenZiti](https://docs.openziti.io), a programmable zero-trust network overlay. `zrok` is an _OpenZiti Native Application_.
`zrok` facilitates sharing resources both publicly and privately, exposing them to an audience you can easily control.
@ -32,9 +32,9 @@ See the [Concepts and Getting Started Guide](docs/getting-started/v0.3_getting_s
`zrok` is also designed to scale down to support extremely small deployments. Run an OpenZiti network with `zrok` layered on top of it on a Raspberry Pi!
The single `zrok` binary contains everything you need to operate `zrok` environments and also host your own service instances. Just add a Ziti network and you're up and running.
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 [Quick Start](docs/v0.3_quickstart.md) for details on getting your own `zrok` service instance running. This builds on top of the [Ziti Quick Start](https://docs.openziti.io/docs/learn/quickstarts/network/) to have you running a `zrok` service instance in minutes.
See the [Quick Start](docs/v0.3_quickstart.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 you running a `zrok` service instance in minutes.
## Building

View File

@ -1,8 +1,7 @@
{
"label": "Core Concepts",
"label": "Sharing",
"position": 10,
"link": {
"type": "generated-index",
"title": "Tutorial overview"
}
}

View File

@ -1,10 +1,10 @@
# Reserved Services
The `v0.3` series introduces a concept of "reserving" services. The intention is that the `zrok` control plane will support limits on the number of reserved services (and eventually `frontend`instances) that an account is allowed to utilize. Service reservations could also be time-limited, or possibly even bandwidth-limited (the reservation expires after a bandwidth threshold is crossed).
With v0.3, `zrok` introduced a concept of "reserving" services. The intention is that the `zrok` control plane will support limits on the number of reserved services (and eventually `frontend`instances) that an account is allowed to utilize. Service reservations could also be time-limited, or possibly even bandwidth-limited (the reservation expires after a bandwidth threshold is crossed).
## Reserved Services Example
`v0.3` introduces the `zrok reserve` command:
With v0.3 `zrok` introduced the `zrok reserve` command:
```
$ zrok reserve private http://localhost:9090

View File

@ -1,6 +1,6 @@
# Public/Private Sharing
The `v0.3` series introduces new sharing modes, and new types of built-in services.
In `v0.3` new sharing modes and new types of built-in services were introduced.
## Share Modes
@ -10,7 +10,7 @@ _Note: We're going to continue using `frontend` and `backend` as concepts, even
### Public Sharing
In `v0.2`, `zrok` only offered a "public" sharing mode. The public sharing mode will allow any configured `frontend` instances to send traffic to any `backend`. The policy and permission model was very simple and flat. A `v0.2` deployment considers any available `frontend` instance to be allowed to send traffic to configured services. The access for `frontend` instances is controlled by identity provisioning within the underlying Ziti network.
In `v0.2`, `zrok` only offered a "public" sharing mode. The public sharing mode will allow any configured `frontend` instances to send traffic to any `backend`. The policy and permission model was very simple and flat. A `v0.2` deployment considers any available `frontend` instance to be allowed to send traffic to configured services. The access for `frontend` instances is controlled by identity provisioning within the underlying OpenZiti network.
In `v0.3`, `zrok` will offer both a "public" and a "private" sharing mode. When `v0.3` configures the policies for a service, a publicly-shared service will have policies created that allow whichever selected public `frontend` instances to access the shared `backend`. A `v0.3` deployment will have a collection of multi-tenant, high-capacity `frontend` instances available to be selected from. The `zrok` CLI will default to selecting the `public` `frontend` instances.
@ -18,7 +18,7 @@ The `frontend` selection approach also gives us a clean implementation for picki
### Private Sharing
`v0.3` introduces a "private" sharing mode. When provisioning a service for private sharing, `zrok` will not create any policies for the service, until a request for a `frontend` binding is created for the service (through the `v0.3` `zrok access` command).
`v0.3` introduced "private" sharing mode. When provisioning a service for private sharing, `zrok` will not create any policies for the service, until a request for a `frontend` binding is created for the service (through the `v0.3` `zrok access` command).
The `v0.3` `zrok` API will support creating `frontend` instances for both identified users (where the `zrok` user has a provisioned `environment`), as well as ephemeral users (the `zrok` controller will create a single-use "ephemeral environment" for these `frontend` instances).
@ -42,7 +42,7 @@ This allows users to create read/write repositories of files that can be shared
## Entities (SQL)
`v0.3` introduces a new `frontends` table to allow the `zrok` controller to track the frontend instances that are available to any account or environment.
`zrok` v0.3 introduced a new `frontends` table to allow the `zrok` controller to track the frontend instances that are available to any account or environment.
The following illustration shows the possibilities available.

View File

@ -3,6 +3,5 @@
"position": 20,
"link": {
"type": "generated-index",
"title": "Tutorial overview"
}
}

View File

@ -1,6 +1,6 @@
# zrok quickstart
## ziti quickstart
## OpenZiti quickstart
```
$ source /dev/stdin <<< "$(wget -qO- https://raw.githubusercontent.com/openziti/ziti/release-next/quickstart/docker/image/ziti-cli-functions.sh)"; expressInstall

View File

@ -1,6 +1,6 @@
# Getting Started with zrok v0.3
`zrok` is a next-generation sharing platform built on top of [Ziti][openziti], a programmable zero trust network overlay. `zrok` is a _Ziti Native Application_.
`zrok` is a next-generation sharing platform built on top of [OpenZiti][https://github.com/openziti/ziti/stargazers], a programmable zero trust network overlay. `zrok` is an _OpenZiti Native Application_.
`zrok` facilitates sharing resources publicly and privately with an audience of your choosing.
@ -156,7 +156,7 @@ Congratulations! Your `zrok` account is ready to go!
When your `zrok` account was created, the service generated a _secret token_ that identifies and authenticates in a single step. Protect your secret token as if it were a password, or an important account number; it's a _secret_, protect it.
When we left off you had downloaded, extracted, and configured your `zrok` environment. In order to use that environment with your account, you'll need to `enable` it. Enabling an environment generates a secure identity and the necessary underlying security policies with the Ziti network hosting the `zrok` service.
When we left off you had downloaded, extracted, and configured your `zrok` environment. In order to use that environment with your account, you'll need to `enable` it. Enabling an environment generates a secure identity and the necessary underlying security policies with the OpenZiti network hosting the `zrok` service.
From the web console, click on your email address in the upper right corner of the header. That drop down menu contains an `Enable Your Environment` link. Click that link and a modal dialog will be shown like this:
@ -271,7 +271,7 @@ The `zrok` service will respond with the following:
access your share with: zrok access private wvszln4dyz9q
```
Rather than allowing access to your service through a public frontend, a _private_ share is only exposed to the underlying Ziti network, and can only be accessed using the `zrok access` command.
Rather than allowing access to your service through a public frontend, a _private_ share is only exposed to the underlying OpenZiti network, and can only be accessed using the `zrok access` command.
The `zrok access private wvszln4dyz9q` command can be run by any `zrok` user, allowing them to create and bind a local HTTP listener, that allows for private access to your shared resources.

View File

@ -3,6 +3,5 @@
"position": 30,
"link": {
"type": "generated-index",
"title": "Tutorial overview"
}
}

View File

@ -1,6 +1,6 @@
# Self-Hosting Guide
## Ziti Quickstart
## OpenZiti Quickstart
https://openziti.github.io/docs/quickstarts/network/
@ -56,7 +56,7 @@ The `endpoint` section defines where your `zrok` controller will listen.
The `store` section defines the local `sqlite3` database used by the controller.
The `ziti` section defines how the `zrok` controller should communicate with your Ziti installation. When using the Ziti quickstart, an administrative password will be generated; the `password` in the `ziti` stanza should reflect this password.
The `ziti` section defines how the `zrok` controller should communicate with your OpenZiti installation. When using the OpenZiti quickstart, an administrative password will be generated; the `password` in the `ziti` stanza should reflect this password.
## Environment Variables
@ -70,9 +70,9 @@ In my case, I've set:
$ export ZROK_API_ENDPOINT=http://localhost:18080
```
## Bootstrap Ziti for zrok
## Bootstrap OpenZiti for zrok
With your Ziti network running and your configuration saved to a local file (I refer to mine as `etc/ctrl.yml` in these examples), you're ready to bootstrap the Ziti network.
With your OpenZiti network running and your configuration saved to a local file (I refer to mine as `etc/ctrl.yml` in these examples), you're ready to bootstrap the Ziti network.
Use the `zrok admin bootstrap` command to bootstrap like this:
@ -105,7 +105,7 @@ $ zrok admin bootstrap etc/ctrl.yml
[ 0.140] INFO main.(*adminBootstrap).run: bootstrap complete!
```
The `zrok admin bootstrap` command configures the `zrok` database, the necessary Ziti identities, and all of the Ziti policies required to run a `zrok` service.
The `zrok admin bootstrap` command configures the `zrok` database, the necessary OpenZiti identities, and all of the OpenZiti policies required to run a `zrok` service.
Notice this warning:

View File

@ -3,6 +3,5 @@
"position": 60,
"link": {
"type": "generated-index",
"title": "Tutorial overview"
}
}

View File

@ -11,7 +11,7 @@ The super-power of `zrok` is providing a single-step solution to creating epheme
`zrok` is also a service (which can be self-hosted) and runs on top of any OpenZiti network. The service provides one or more listening endpoints (typically on the public internet), that are designed to dynamically expose endpoints (HTTP(S)-only, as of v0.1.x), as requested by the end-user `zrok` tooling.
`zrok` listening endpoints, and `zrok` terminating endpoints are typically used together to create the streamlined, ephemeral connectivity solution for dark services. But listening endpoints and the terminating endpoints can be used orthogonally, interoperating with other Ziti SDK clients.
`zrok` listening endpoints, and `zrok` terminating endpoints are typically used together to create the streamlined, ephemeral connectivity solution for dark services. But listening endpoints and the terminating endpoints can be used orthogonally, interoperating with other OpenZiti SDK clients.
### The Primary Use Case
@ -35,7 +35,7 @@ $ zrok http http://localhost:3000
http://d9121e7cdfd2dd2f.zrok.io/
```
This URL can be shared with anyone, anywhere, allowing access to the developer's application as long as the developer is running the `zrok http` command. Simply ending that process will destroy all of the public access, and clean up the associated resources in the underlying Ziti environment.
This URL can be shared with anyone, anywhere, allowing access to the developer's application as long as the developer is running the `zrok http` command. Simply ending that process will destroy all of the public access, and clean up the associated resources in the underlying OpenZiti environment.
## How Does `zrok` Work?
@ -53,11 +53,11 @@ When a new `zrok` user signs up for an account, they are issued a "secret token"
When the user runs `zrok enable` from their shell, here's what happens:
1. The `zrok enable` client reaches out with an enable request to the `zrok` controller.
2. The `zrok` controller creates a new Ziti identity for the environment and enrolls it.
3. The `zrok` controller creates an edge router policy associating the new Ziti identity with `#all` edge routers.
2. The `zrok` controller creates a new OpenZiti identity for the environment and enrolls it.
3. The `zrok` controller creates an edge router policy associating the new OpenZiti identity with `#all` edge routers.
4. The `zrok` controller returns the entire SDK configuration back to the `zrok enable` client.
5. The `zrok enable` client then stores the Ziti identity along with a few other housekeeping details in the user's `~/.zrok` folder (we refer to this as `zrokdir`, conceptually in the code).
6. With the Ziti identity and configuration details stored in the user's `zrokdir`, the user is then able to create any number of binding endpoints using the `zrok http` command.
5. The `zrok enable` client then stores the OpenZiti identity along with a few other housekeeping details in the user's `~/.zrok` folder (we refer to this as `zrokdir`, conceptually in the code).
6. With the OpenZiti identity and configuration details stored in the user's `zrokdir`, the user is then able to create any number of binding endpoints using the `zrok http` command.
### The `zrok http` Flow
@ -69,13 +69,13 @@ When a `zrok` user issues a `zrok http` command for an endpoint, here's what hap
3. The `zrok` controller allocates a new "service name" for the binding.
4. The `zrok` controller creates a `zrok.proxy.v1` configuration describing the user's requested authentication details (currently: `none` or `basic`).
5. The `zrok` controller creates a new service, associating the service with the configuration.
6. The `zrok` controller creates a bind service policy for the user's environment identity and the newly created Ziti service.
6. The `zrok` controller creates a bind service policy for the user's environment identity and the newly created OpenZiti service.
7. The `zrok` controller creates a dial service policy allowing the configured listening endpoints (ingress proxies) to dial the newly created service.
8. The `zrok` controller creates a service edge router policy associating the newly created service with `#all` edge routers.
9. The URL for the new `zrok` service is constructed and returned to the `zrok http` client.
10. The `zrok http` client then binds the Ziti service with an SDK client, and begins reverse-proxying traffic received from Ziti across to the dark service.
10. The `zrok http` client then binds the OpenZiti service with an SDK client, and begins reverse-proxying traffic received from OpenZiti across to the dark service.
When the user terminates the `zrok http` client, these resources are removed from the Ziti network.
When the user terminates the `zrok http` client, these resources are removed from the OpenZiti network.
### `zrok proxy` and HTTP Clients
@ -87,6 +87,6 @@ When an HTTP request arrives as the `zrok proxy` listener, this happens:
1. The `zrok proxy` parses the `Host` header provided by the client, extracting the `zrok` service name from the URL.
2. The service is refreshed (if necessary) and retrieved. The `zrok.proxy.v1` configuration details are retrieved.
3. The `zrok.proxy.v1` configuration is used to do authentication processing. If authentication is required, such a response is returned to the client.
4. The `zrok proxy` then dials the Ziti service, and the dialed service is used to reverse proxy the request from the end user across Ziti to the binding endpoint, and then dark service.
4. The `zrok proxy` then dials the OpenZiti service, and the dialed service is used to reverse proxy the request from the end user across OpenZiti to the binding endpoint, and then dark service.
The `zrok proxy` does not require any communication with the `zrok` controller, and is stateless. They can be pooled behind a load balancer. It is currently a goal is to maintain this lightweight nature.

View File

@ -40,7 +40,7 @@
--ifm-color-primary-lightest: #99ff00;
--docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
--code-background-color: rgba(76, 55, 123, 0.53);
--code-font-color: rgb(197, 160, 247);
--code-font-color: rgb(205, 180, 247);
--selection-color: #0f023b;
}
@ -160,7 +160,7 @@ h6 {
}
a code {
color: rgb(167, 130, 217);
color: var(--code-font-color);
}
::-moz-selection { /* Code for Firefox */
color: var(--selection-font-color);