Operator's Guide
How to configure and run VTAdmin
Get Started #
This guide describes how to configure and build the VTAdmin API server (vtadmin
) and front-end (vtadmin-web
).
If you intend to use the Vitess operator to deploy VTAdmin please refer to Running in VTop.
The simplest VTAdmin deployment involves a single Vitess cluster. You can look
at the local example for a
minimal invocation of the vtadmin
and vtadmin-web
binaries.
Prerequisites #
- Building
vtadmin-web
requires node at the version given in the package.json file.
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 tovtadmin
with the--cluster-config
build flag - Set the
--cluster
and/or--cluster-defaults
flags when runningvtadmin
, 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.
2. Configure vtadmin
#
Configure the flags for the vtadmin
process. The full list of flags is given in the vtadmin
reference documentation.
The following is from the 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.
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.
3. Configure and build vtadmin-web
#
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.
The following is from the local example showing a minimal set of environment variables. $web_dir
, in this case, refers to the vtadmin-web
source directory but could equally apply to the web/vtadmin/
directory copied into a Docker container, for example. REACT_APP_VTADMIN_API_ADDRESS
uses the same hostname as the --addr
flag passed to vtadmin
in the previous step.
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
If you want to overwrite or set environment variables after the build you can use the $web_dir/build/config/config.js
file.
For example:
window.env = {
'REACT_APP_VTADMIN_API_ADDRESS': "https://vtadmin-api.example.com:14200",
'REACT_APP_FETCH_CREDENTIALS': "omit",
'REACT_APP_ENABLE_EXPERIMENTAL_TABLET_DEBUG_VARS': true,
'REACT_APP_BUGSNAG_API_KEY': "",
'REACT_APP_DOCUMENT_TITLE': "",
'REACT_APP_READONLY_MODE': false,
};
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 or npm's serve package. Each filename inside of $web_dir/build/static
will contain a unique hash of the file contents. This hash in the file name enables long term caching techniques.