Cluster UI Components
This library contains components used by the CockroachDB Console and CockroachCloud Console to display cluster-level information.
Overview of how this package interacts with CRDB and CockroachCloud
The diagram below describes how this package is published and imported in the two application codebases it's used in:
To look one level of abstraction below the diagram above, the
components used in CockroachCloud and CRDB from this package differ
due to the way that the component state management code integrates
with the different applications. In CRDB, we import the React page component
and connect it to existing Redux code that manages state whereas
in CockroachCloud, we import a "Connected component" which is already
coupled to the Redux code that retrieves and manages its data. In
CockroachCloud we link the
cluster-ui redux store to the global
app store which lets our Connected component store and retrieve data.
Version alignment with CRDB releases
cluster-ui is dependent on the API of CRDB through a dependency on a protobuf client.
Since the API can change in incompatible ways between major versions of the database,
versions of cluster-ui are published following the version scheme of CockroachDB.
|CRDB Version||Cluster UI Version||development branch|
Note, that the patch versions of the CRDB version and the Cluster UI version will not align. The versioning schemes between CRDB and Cluster UI may vary slightly, but the goal is to provide guidance about compatibility.
Development Workflow with CRDB
The build processes for Cluster UI have been integrated into the
/pkg/ui. The intention is that the development workflow between DB Console
and Cluster UI components be seamless. If you would like to build cluster-ui
independently, you can run the following commands,
> make pkg/ui/yarn.protobuf.installed -B; # to build protobufs cluster-ui depends on > make pkg/ui/yarn.cluster-ui.installed -B; # to build cluster-ui
Development Workflow with CockroachCloud
In CockroachCloud Console, we install multiple aliased versions of cluster-ui.
This, in addition to certain peer dependencies, prevent us from using a traditional
yarn link for local development of cluster-ui. Instead, you must pack the dependency
and install it from a local tarball. To view a local change to cluster-ui in CockroachCloud,
# after making your code change, # in the root of cockroachdb/cockroach $ make pkg/ui/yarn.protobuf.installed -B $ make pkg/ui/yarn.cluster-ui.installed -B # in pkg/ui/workspaces/cluster-ui $ yarn run build $ yarn pack --prod
And then install the package in
$ cd /console $ yarn cache clean # yarn add --force [cluster-ui package alias]@[full path to tarball], # here's an example $ yarn add --force @cockroachlabs/cluster-ui-21-1@/path/to/cockroachlabs-cluster-ui.tgz
Test your changes by running CockroachCloud locally, but please be careful to not
commit the changes to
package.json or to
Learn more about Storybook here: https://storybook.js.org/
You can run storybook for this project using:
$ yarn run storybook
And opening http://localhost:6006/ in your browser.
The use of storybook in this project is to provide a controlled environment where components can be rendered or showcased for testing and sharing purposes outside of the entire DB Console or CockroachCloud app.
Often we build a component that behaves or looks differently in different scenarios with different inputs. Storybook lets us render the component in all the "interesting configurations" we define so that we can quickly get visual feedback on our work and ensure that we're not breaking functionality when editing code. Otherwise we waste lots of time getting our app in the "right state" to try and see if some random feature works or not.
Components and page developers are encouraged to use Storybook to showcase components and pages in many common states to be able to quickly review their work visually and to aid others in understanding what the various states pages and components we want to support.
Storybook stories should use the CSF format as described here: https://storybook.js.org/docs/react/api/csf in order to facilitate writing unit tests with the storybook components.
Publishing Cluster UI package to npm
Publishing Cluster UI pre-release versions from the master branch to npm is done
by a Github Action workflow called "Publish Cluster UI Pre-release". This workflow
will publish to npm anytime a version of Cluster UI is merged to master that is
unpublished (by comparing the version in the
package.json to versions of
@cockroachlabs/cluster-ui on npm). To change the version of Cluster UI, you can
run the command
yarn bump from
To publish a version from a release branch, a manual publish is still required. The steps below can be followed to manually publish to npm. Github Workflows are being worked on for release branches, and this README will be updated when they are available.
1. Change the version in package.json
CockroachDB uses a form of calver versioning where the major part
is a Short Year and the minor part is an iterative number.The micro part (in
semver, this is called the "patch" part) is also an iterative number. The first
two numbers comprise a major version of CockroachDB, and the third denotes a minor
release of that major version. For example,
21.1.6 is a version released in 2021,
is part of the first major release of that year, and the seventh release in that
21.1.0 being the first).
npm package versions must be parseable by semantic versioning. To denote what versions of the cluster-ui package are intended for use with specific major version of CockroachDB, cluster-ui mimics the version of CockroachDB. For example
firstname.lastname@example.org is a version of cluster-ui compatible with the API of CockroachDB version
21.1 and is the fourth release in this major version. It's important to note that
email@example.com is not directly published from CockroachDB version
21.1.4. Only that
firstname.lastname@example.org was published from CockroachDB branch
So when incrementing (or "bumping") the version of cluster-ui the only number that should change will be the "patch"
version (the third number). For example, if you're working on master and find the version to be
21.2.1 you would
change the version to be
21.2.2. The version change should accompany the pull-request with the changes to the code, and should be merged with them.
2. Create a git tag
Once a pull-request has been merged into respective branch, a git tag should be made against the commit that contains
the changes to cluster-ui and the version change. The form of the tag should be
[version] is the version found in the
package.json. After creating a tag, push the tag to a remote referencing
$ git tag [tag name] [SHA] # SHA can be omitted if desired commit is HEAD $ git push [remote] [tag name]
3. Build Cluster UI prerequisites (protobufs, etc)
To build the prerequisites for cluster-ui run the following commands from the root directory of CockroachDB.
$ make ui-maintainer-clean $ make ui-generate -B
If you have not done so already, request publishing permissions from the Cluster
UI team at Cockroach Labs. You will be required to create an account on npm
and configure two factor authentication. You will then be added to the
npm organization and given permission to publish the
Setup your npm registry login details
Before publishing, ensure that you have authenticated with the npm registry by running the following command,
$ yarn login
To log in, you will be prompted for your credentials.
$ yarn login yarn login v1.22.10 question npm username: ********* question npm email: **************@*****.*** ✨ Done in 11.56s.
If you were logged in already, you will see the current authenticated user
$ yarn login yarn login v1.XX.XX info npm username: xxxxxxxxxxx info npm email: email@example.com ✨ Done in 0.05s.
Once you have authenticated, you are ready to publish to npm.
Publish package to npm
Go into the
pkg/ui/cluster-ui subfolder, as you'll be publishing the package
as specified by that
Note: If you've already updated
package.json to reflect the new version,
you'll need to temporarily change this back to the older version (i.e. the version
that's currently listed on npm). After running the command below, the script will then
automatically reverted back to the newer version.
To publish the package, run the publish command,
$ yarn publish --access public
During a publish you can expect to see some prepublish steps before the package
is delivered to the registry.
clean will delete the contents of the
build will compile TypeScript and bundle the code using Webpack.
The publish will create a tarball and send it to the registry.
5. Add a distribution tag
We use distribution tags to organize the versions of
cluster-ui. By default
the most recent published version will be tagged as
latest. Depending on the
version you are publishing, you will most likely need to add distribution tags to
the version you published. Our current distribution tags are,
|dist tag name||example version||purpose|
|latest||21.1.2||latest version of major stable version of CRDB|
|release-21.1||21.1.2||latest version from version 21.1 of CRDB|
|release-20.2||20.2.3||latest version from version 20.2 of CRDB|
|next||21.2.0-prerelease-1||latest version of development version of CRDB|
At the time of writing, June 2021, CockroachDB v21.1 is the latest stable version so cluster
ui versions from this release branch should be tagged as both
CockroachDB v21.2 is currently under development and so versions published from
master should be tagged as
next and are expected to have a prerelease identifiers
(a portion of the version appended by a
-, for example
This is to designate that a
.0 version of
21.2 should be reserved until CockroachDB v21.2
is released publicly.
Distribution tags are easily modified and so there should be little concern about adding or removing them as needed. To add (or modify) a distribution tag, run the following command,
$ npm dist-tag add @cockroachlabs/cluster-ui@[version] [dist tag name]; # for example, # npm dist-tag add @firstname.lastname@example.org release-21.1 # npm dist-tag add @email@example.com next # npm dist-tag add @firstname.lastname@example.org latest
If a mistake is made, simply add again the correct version/tag pair or remove the tag with the following command,
$ npm dist-tag rm @cockroachlabs/cluster-ui [dist tag name];
To see what the current distribution tags for cluster-ui, run
$ npm dist-tag ls @cockroachlabs/cluster-ui # example output: # latest: 21.1.1 # next: 21.2.0-prerelease-1 # release-20.2: 20.2.0 # release-21.1: 21.1.1