Add VTAdmin Operator's Guide

content/en/docs/14.0/reference/programs/vtadmin-web.md

@@ -0,0 +1,30 @@
+---
+title: vtadmin-web
+---
+
+## Environment Variables
+
+These environment variables configure VTAdmin, most commonly when creating a `vtadmin-web` production build as described in the [VTAdmin Operator's Guide][operators_guide]. These environment variables also enumerated in [web/vtadmin/src/react-app-env.d.ts][vtadmin_env_ref].
+
+Under the hood, `vtadmin-web` uses [create-react-app][cra], which requires all environment variables to be prefixed with `REACT_APP` to avoid accidentally including secrets in the static build. For more on custom environment variables with create-react-app, see ["Adding Custom Environment Variables"][cra_env_ref].
+
+These environment variables can be passed inline to the `npm run build` command or [added to a .env file][cra_env_file_ref].
+
+
+| Name | Required | Type | Default | Definition |
+| -------- | --------- | --------- | --------- |--------- |
+| `REACT_APP_VTADMIN_API_ADDRESS` | **Required** | string | - | The full address of vtadmin-api's HTTP(S) interface. Example: "https://vtadmin.example.com:12345" | 
+| `REACT_APP_BUGSNAG_API_KEY` | Optional | string | - | An API key for https://bugsnag.com. If defined, the @bugsnag/js client will be initialized. Your Bugsnag API key can be found in your Bugsnag Project Settings. | 
+| `REACT_APP_BUILD_BRANCH` | Optional | string | - | The branch vtadmin-web was built with. Used only for debugging; will appear on the (secret) /settings route in the UI. |
+| `REACT_APP_BUILD_SHA` | Optional | string | - | The SHA vtadmin-web was built with. Used only for debugging; will appear on the (secret) /settings route in the UI. |
+| `REACT_APP_DOCUMENT_TITLE` | Optional | string | "VTAdmin" | Used for the document.title property. Overriding this can be useful to differentiate between multiple VTAdmin deployments, e.g., "VTAdmin (staging)". |
+| `REACT_APP_ENABLE_EXPERIMENTAL_TABLET_DEBUG_VARS` | Optional | string | - | Optional, but recommended. When `"true"`, enables front-end components that query vtadmin-api's /api/experimental/tablet/{tablet}/debug/vars endpoint. | 
+| `REACT_APP_FETCH_CREDENTIALS` | Optional | string | - | Configures the `credentials` property for fetch requests  made against vtadmin-api. If unspecified, uses fetch defaults. See https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#sending_a_request_with_credentials_included |
+| `REACT_APP_READONLY_MODE` | Optional | string | "false" | If "true", UI controls that correspond to write actions (PUT, POST, DELETE) will be hidden. Note that this *only* affects the UI. If write actions are a concern, Vitess operators are encouraged to also [configure vtadmin-api for role-based access control (RBAC)][rbac] if needed. | 
+
+[cra]: https://create-react-app.dev/
+[cra_env_ref]: https://create-react-app.dev/docs/adding-custom-environment-variables/
+[cra_env_file_ref]: https://create-react-app.dev/docs/adding-custom-environment-variables/#adding-development-environment-variables-in-env
+[operators_guide]: ../../vtadmin/operators_guide
+[rbac]: ../../vtadmin/role-based-access-control
+[vtadmin_env_ref]: https://github.com/vitessio/vitess/blob/main/web/vtadmin/src/react-app-env.d.ts

content/en/docs/14.0/reference/vtadmin/operators_guide.md

@@ -0,0 +1,85 @@
+---
+title: Operator's Guide
+description: How to configure and run VTAdmin
+---
+
+{{< info >}}
+If you run into issues or have questions, we recommend posting in our [#feat-vtadmin Slack channel](https://vitess.slack.com). Click the Slack icon in the top right to join. This is a very active community forum and a great place to interact with other users.
+{{< /info >}}
+
+## Get Started
+
+This guide describes how to configure and build the VTAdmin API server (`vtadmin`) and front-end (`vtadmin-web`).
+
+The simplest VTAdmin deployment involves a single Vitess cluster. You can look
+at the [local example][local_example] for a
+minimal invocation of the `vtadmin-api` and `vtadmin-web` binaries.
+
+## Prerequisites
+
+- Building `vtadmin-web` requires [node](https://nodejs.org/en/) >= v16.13.0.
+
+## 1. Define the cluster configuration
+
+VTAdmin is mapped to one or more Vitess clusters two ways:
+
+- Add a `clusters.yaml` file and pass its path to `vtadmin-api` with the `--cluster-config` build flag
+- Set the `--cluster` and/or `--cluster-defaults` flags when running `vtadmin-api`, described in the next section.
+
+When both command-line cluster configs and a config file are provided, any options for a given cluster on the command-line take precedence over options for that cluster in the config file. 
+
+For a well-commented example enumerating the cluster configuration options, see [clusters.example.yaml](https://github.com/vitessio/vitess/blob/main/doc/vtadmin/clusters.yaml).
+
+
+## 2. Configure `vtadmin-api`
+
+Configure the flags for the `vtadmin`process. The full list of flags is given in the [vtadmin reference documentation][vtadmin_flag_ref].
+
+The following is from the [local example][local_example] showing a minimal set of flags. Here, we define the cluster configuration with the `--cluster` flag and use static (file-based) discovery configured in the [local example's `discovery.json` file][discovery_json]. 
+
+```
+vtadmin \
+  --addr ":14200" \
+  --http-origin "https://vtadmin.example.com:14201" \
+  --http-tablet-url-tmpl "http://{{ .Tablet.Hostname }}:15{{ .Tablet.Alias.Uid }}" \
+  --tracer "opentracing-jaeger" \
+  --grpc-tracing \
+  --http-tracing \
+  --logtostderr \
+  --alsologtostderr \
+  --no-rbac \
+  --cluster "id=local,name=local,discovery=staticfile,discovery-staticfile-path=./vtadmin/discovery.json,tablet-fqdn-tmpl={{ .Tablet.Hostname }}:15{{ .Tablet.Alias.Uid }}" 
+```
+
+To optionally configure role-based access control (RBAC), refer to the [RBAC documentation][rbac_docs].
+
+## 3. Configure and build `vtadmin-web`
+
+{{< info >}}
+Unlike other Vitess components, `vtadmin-web` is not distributed as a binary. This is because environment variables specific to a Vitess environment (such as the hostname for `vtadmin-api`) are embedded during build time. Since `vtadmin-web` produces a static HTML/CSS/JS build, it's not possible to read these values at run-time.
+{{< /info >}}
+
+Environment variables can be defined in a `.env` file or passed inline to the `npm run build` command. The full list of flags is given in the [vtadmin-web reference documentation][vtadmin_web_env_ref].
+
+The following is from the [local example][local_example] showing a minimal set of environment variables. `$web_dir`, in this case, refers to the [vtadmin-web source directory][vtadmin_web_src] but could equally apply to the `web/vtadmin/` directory copied into a Docker container, for example. `REACT_APP_VTADMIN_API_ADDRESS` uses 
+
+```
+npm --prefix $web_dir --silent install
+
+REACT_APP_VTADMIN_API_ADDRESS="https://vtadmin-api.example.com:14200" \
+  REACT_APP_ENABLE_EXPERIMENTAL_TABLET_DEBUG_VARS="true" \
+  npm run --prefix $web_dir build
+```
+
+After running `build` command, the production build of the front-end assets will be in the `$web_dir/build` directory. They can be served as any other static content; for example, [Go's embed package][go_embed] or npm's [serve package][npm_serve]. Each filename inside of build/static will contain a unique hash of the file contents. This hash in the file name enables [long term caching techniques][web_caching].
+
+
+[discovery_json]: https://github.com/vitessio/vitess/blob/main/examples/local/vtadmin/discovery.json
+[go_embed]:https://pkg.go.dev/embed
+[local_example]: https://github.com/vitessio/vitess/blob/main/examples/local/scripts/vtadmin-up.sh
+[npm_serve]: https://www.npmjs.com/package/serve
+[rbac_docs]: ../role-based-access-control
+[vtadmin_flag_ref]: ../../programs/vtadmin
+[vtadmin_web_env_ref]: ../../programs/vtadmin-web
+[vtadmin_web_src]: https://github.com/vitessio/vitess/tree/main/web/vtadmin
+[web_caching]: https://create-react-app.dev/docs/production-build/#static-file-caching

content/en/docs/15.0/reference/programs/vtadmin-web.md

@@ -0,0 +1,30 @@
+---
+title: vtadmin-web
+---
+
+## Environment Variables
+
+These environment variables configure VTAdmin, most commonly when creating a `vtadmin-web` production build as described in the [VTAdmin Operator's Guide][operators_guide]. These environment variables also enumerated in [web/vtadmin/src/react-app-env.d.ts][vtadmin_env_ref].
+
+Under the hood, `vtadmin-web` uses [create-react-app][cra], which requires all environment variables to be prefixed with `REACT_APP` to avoid accidentally including secrets in the static build. For more on custom environment variables with create-react-app, see ["Adding Custom Environment Variables"][cra_env_ref].
+
+These environment variables can be passed inline to the `npm run build` command or [added to a .env file][cra_env_file_ref].
+
+
+| Name | Required | Type | Default | Definition |
+| -------- | --------- | --------- | --------- |--------- |
+| `REACT_APP_VTADMIN_API_ADDRESS` | **Required** | string | - | The full address of vtadmin-api's HTTP(S) interface. Example: "https://vtadmin.example.com:12345" | 
+| `REACT_APP_BUGSNAG_API_KEY` | Optional | string | - | An API key for https://bugsnag.com. If defined, the @bugsnag/js client will be initialized. Your Bugsnag API key can be found in your Bugsnag Project Settings. | 
+| `REACT_APP_BUILD_BRANCH` | Optional | string | - | The branch vtadmin-web was built with. Used only for debugging; will appear on the (secret) /settings route in the UI. |
+| `REACT_APP_BUILD_SHA` | Optional | string | - | The SHA vtadmin-web was built with. Used only for debugging; will appear on the (secret) /settings route in the UI. |
+| `REACT_APP_DOCUMENT_TITLE` | Optional | string | "VTAdmin" | Used for the document.title property. Overriding this can be useful to differentiate between multiple VTAdmin deployments, e.g., "VTAdmin (staging)". |
+| `REACT_APP_ENABLE_EXPERIMENTAL_TABLET_DEBUG_VARS` | Optional | string | - | Optional, but recommended. When `"true"`, enables front-end components that query vtadmin-api's /api/experimental/tablet/{tablet}/debug/vars endpoint. | 
+| `REACT_APP_FETCH_CREDENTIALS` | Optional | string | - | Configures the `credentials` property for fetch requests  made against vtadmin-api. If unspecified, uses fetch defaults. See https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#sending_a_request_with_credentials_included |
+| `REACT_APP_READONLY_MODE` | Optional | string | "false" | If "true", UI controls that correspond to write actions (PUT, POST, DELETE) will be hidden. Note that this *only* affects the UI. If write actions are a concern, Vitess operators are encouraged to also [configure vtadmin-api for role-based access control (RBAC)][rbac] if needed. | 
+
+[cra]: https://create-react-app.dev/
+[cra_env_ref]: https://create-react-app.dev/docs/adding-custom-environment-variables/
+[cra_env_file_ref]: https://create-react-app.dev/docs/adding-custom-environment-variables/#adding-development-environment-variables-in-env
+[operators_guide]: ../../vtadmin/operators_guide
+[rbac]: ../../vtadmin/role-based-access-control
+[vtadmin_env_ref]: https://github.com/vitessio/vitess/blob/main/web/vtadmin/src/react-app-env.d.ts

content/en/docs/15.0/reference/vtadmin/operators_guide.md

@@ -0,0 +1,85 @@
+---
+title: Operator's Guide
+description: How to configure and run VTAdmin
+---
+
+{{< info >}}
+If you run into issues or have questions, we recommend posting in our [#feat-vtadmin Slack channel](https://vitess.slack.com). Click the Slack icon in the top right to join. This is a very active community forum and a great place to interact with other users.
+{{< /info >}}
+
+## Get Started
+
+This guide describes how to configure and build the VTAdmin API server (`vtadmin`) and front-end (`vtadmin-web`).
+
+The simplest VTAdmin deployment involves a single Vitess cluster. You can look
+at the [local example][local_example] for a
+minimal invocation of the `vtadmin-api` and `vtadmin-web` binaries.
+
+## Prerequisites
+
+- Building `vtadmin-web` requires [node](https://nodejs.org/en/) >= v16.13.0.
+
+## 1. Define the cluster configuration
+
+VTAdmin is mapped to one or more Vitess clusters two ways:
+
+- Add a `clusters.yaml` file and pass its path to `vtadmin-api` with the `--cluster-config` build flag
+- Set the `--cluster` and/or `--cluster-defaults` flags when running `vtadmin-api`, described in the next section.
+
+When both command-line cluster configs and a config file are provided, any options for a given cluster on the command-line take precedence over options for that cluster in the config file. 
+
+For a well-commented example enumerating the cluster configuration options, see [clusters.example.yaml](https://github.com/vitessio/vitess/blob/main/doc/vtadmin/clusters.yaml).
+
+
+## 2. Configure `vtadmin-api`
+
+Configure the flags for the `vtadmin`process. The full list of flags is given in the [vtadmin reference documentation][vtadmin_flag_ref].
+
+The following is from the [local example][local_example] showing a minimal set of flags. Here, we define the cluster configuration with the `--cluster` flag and use static (file-based) discovery configured in the [local example's `discovery.json` file][discovery_json]. 
+
+```
+vtadmin \
+  --addr ":14200" \
+  --http-origin "https://vtadmin.example.com:14201" \
+  --http-tablet-url-tmpl "http://{{ .Tablet.Hostname }}:15{{ .Tablet.Alias.Uid }}" \
+  --tracer "opentracing-jaeger" \
+  --grpc-tracing \
+  --http-tracing \
+  --logtostderr \
+  --alsologtostderr \
+  --no-rbac \
+  --cluster "id=local,name=local,discovery=staticfile,discovery-staticfile-path=./vtadmin/discovery.json,tablet-fqdn-tmpl={{ .Tablet.Hostname }}:15{{ .Tablet.Alias.Uid }}" 
+```
+
+To optionally configure role-based access control (RBAC), refer to the [RBAC documentation][rbac_docs].
+
+## 3. Configure and build `vtadmin-web`
+
+{{< info >}}
+Unlike other Vitess components, `vtadmin-web` is not distributed as a binary. This is because environment variables specific to a Vitess environment (such as the hostname for `vtadmin-api`) are embedded during build time. Since `vtadmin-web` produces a static HTML/CSS/JS build, it's not possible to read these values at run-time.
+{{< /info >}}
+
+Environment variables can be defined in a `.env` file or passed inline to the `npm run build` command. The full list of flags is given in the [vtadmin-web reference documentation][vtadmin_web_env_ref].
+
+The following is from the [local example][local_example] showing a minimal set of environment variables. `$web_dir`, in this case, refers to the [vtadmin-web source directory][vtadmin_web_src] but could equally apply to the `web/vtadmin/` directory copied into a Docker container, for example. `REACT_APP_VTADMIN_API_ADDRESS` uses 
+
+```
+npm --prefix $web_dir --silent install
+
+REACT_APP_VTADMIN_API_ADDRESS="https://vtadmin-api.example.com:14200" \
+  REACT_APP_ENABLE_EXPERIMENTAL_TABLET_DEBUG_VARS="true" \
+  npm run --prefix $web_dir build
+```
+
+After running `build` command, the production build of the front-end assets will be in the `$web_dir/build` directory. They can be served as any other static content; for example, [Go's embed package][go_embed] or npm's [serve package][npm_serve]. Each filename inside of build/static will contain a unique hash of the file contents. This hash in the file name enables [long term caching techniques][web_caching].
+
+
+[discovery_json]: https://github.com/vitessio/vitess/blob/main/examples/local/vtadmin/discovery.json
+[go_embed]:https://pkg.go.dev/embed
+[local_example]: https://github.com/vitessio/vitess/blob/main/examples/local/scripts/vtadmin-up.sh
+[npm_serve]: https://www.npmjs.com/package/serve
+[rbac_docs]: ../role-based-access-control
+[vtadmin_flag_ref]: ../../programs/vtadmin
+[vtadmin_web_env_ref]: ../../programs/vtadmin-web
+[vtadmin_web_src]: https://github.com/vitessio/vitess/tree/main/web/vtadmin
+[web_caching]: https://create-react-app.dev/docs/production-build/#static-file-caching