diff --git a/docs/modules/hbase/pages/getting_started/first_steps.adoc b/docs/modules/hbase/pages/getting_started/first_steps.adoc index b2e153f6..15c237dd 100644 --- a/docs/modules/hbase/pages/getting_started/first_steps.adoc +++ b/docs/modules/hbase/pages/getting_started/first_steps.adoc @@ -2,8 +2,8 @@ :description: Deploy and verify an HBase cluster using ZooKeeper, HDFS, and HBase configurations. Test with REST API and Apache Phoenix for table creation and data querying. :phoenix: https://phoenix.apache.org/index.html -Once you have followed the steps in the xref:getting_started/installation.adoc[] section to install the operator and its dependencies, you will now deploy an HBase cluster and its dependencies. -Afterwards you can <<_verify_that_it_works, verify that it works>> by creating tables and data in HBase using the REST API and Apache Phoenix (an SQL layer used to interact with HBase). +Once you have followed the steps in the xref:getting_started/installation.adoc[] section to install the operator and its dependencies, you deploy an HBase cluster and its dependencies. +Afterward you can <<_verify_that_it_works, verify that it works>> by creating tables and data in HBase using the REST API and Apache Phoenix (an SQL layer used to interact with HBase). == Setup @@ -14,7 +14,7 @@ To deploy a ZooKeeper cluster create one file called `zk.yaml`: [source,yaml] include::example$getting_started/zk.yaml[] -We also need to define a ZNode that will be used by the HDFS and HBase clusters to reference ZooKeeper. +We also need to define a ZNode that is used by the HDFS and HBase clusters to reference ZooKeeper. Create another file called `znode.yaml` and define a separate ZNode for each service: [source,yaml] @@ -73,8 +73,8 @@ include::example$getting_started/hbase.yaml[] == Verify that it works -To test the cluster you will use the REST API to check its version and status, and to create and inspect a new table. -You will also use Phoenix to create, populate and query a second new table, before listing all non-system tables in HBase. +To test the cluster, use the REST API to check its version and status, and to create and inspect a new table. +Use Phoenix to create, populate and query a second new table, before listing all non-system tables in HBase. These actions wil be carried out from one of the HBase components, the REST server. First, check the cluster version with this callout: @@ -82,7 +82,7 @@ First, check the cluster version with this callout: [source] include::example$getting_started/getting_started.sh[tag=cluster-version] -This will return the version that was specified in the HBase cluster definition: +This returns the version that was specified in the HBase cluster definition: [source,json] {"Version":"2.4.18"} @@ -92,7 +92,7 @@ The cluster status can be checked and formatted like this: [source] include::example$getting_started/getting_started.sh[tag=cluster-status] -which will display cluster metadata that looks like this (only the first region is included for the sake of readability): +which displays cluster metadata that looks like this (only the first region is included for the sake of readability): [source,json] { @@ -134,7 +134,7 @@ You can now create a table like this: [source] include::example$getting_started/getting_started.sh[tag=create-table] -This will create a table `users` with a single column family `cf`. +This creates a table `users` with a single column family `cf`. Its creation can be verified by listing it: [source] @@ -155,7 +155,7 @@ Use the Python utility `psql.py` (found in /stackable/phoenix/bin) to create, po [source] include::example$getting_started/getting_started.sh[tag=phoenix-table] -The final command will display some grouped data like this: +The final command displays some grouped data like this: [source] HO TOTAL_ACTIVE_VISITORS diff --git a/docs/modules/hbase/pages/getting_started/index.adoc b/docs/modules/hbase/pages/getting_started/index.adoc index 6cbdc32e..bab5bc4b 100644 --- a/docs/modules/hbase/pages/getting_started/index.adoc +++ b/docs/modules/hbase/pages/getting_started/index.adoc @@ -1,6 +1,6 @@ = Getting started -This guide will get you started with HBase using the Stackable operator. +This guide gets you started with HBase using the Stackable operator. It guides you through the installation of the operator and its dependencies, setting up your first HBase cluster and verifying its operation. == Prerequisites diff --git a/docs/modules/hbase/pages/getting_started/installation.adoc b/docs/modules/hbase/pages/getting_started/installation.adoc index fca0cffa..68eafc41 100644 --- a/docs/modules/hbase/pages/getting_started/installation.adoc +++ b/docs/modules/hbase/pages/getting_started/installation.adoc @@ -2,17 +2,17 @@ :description: Install Stackable HBase and required operators using stackablectl or Helm on Kubernetes. Follow setup and verification steps for a complete installation. :kind: https://kind.sigs.k8s.io/ -On this page you will install the Stackable HBase operator and its dependencies, the ZooKeeper and HDFS operators, as well as the commons, secret and listener operators which are required by all Stackable operators. +Install the Stackable HBase operator and its dependencies, the ZooKeeper and HDFS operators, as well as the commons, secret and listener operators which are required by all Stackable operators. -== Stackable Operators - -There are 2 ways to run Stackable operators - -. Using xref:management:stackablectl:index.adoc[] -. Using Helm - -=== stackablectl +There are multiple ways to install the Stackable Operator for Apache Zookeeper. +xref:management:stackablectl:index.adoc[] is the preferred way, but Helm is also supported. +OpenShift users may prefer installing the operator from the RedHat Certified Operator catalog using the OpenShift web console. +[tabs] +==== +stackablectl:: ++ +-- `stackablectl` is the command line tool to interact with Stackable operators and our recommended way to install operators. Follow the xref:management:stackablectl:installation.adoc[installation steps] for your platform. @@ -23,7 +23,7 @@ After you have installed stackablectl run the following command to install all o include::example$getting_started/getting_started.sh[tag=stackablectl-install-operators] ---- -The tool will show +The tool shows [source] include::example$getting_started/install_output.txt[] @@ -31,24 +31,26 @@ include::example$getting_started/install_output.txt[] TIP: Consult the xref:management:stackablectl:quickstart.adoc[] to learn more about how to use `stackablectl`. For example, you can use the `--cluster kind` flag to create a Kubernetes cluster with {kind}[kind]. +-- -=== Helm - -You can also use Helm to install the operators. +Helm:: ++ +-- Add the Stackable Helm repository: [source,bash] ---- include::example$getting_started/getting_started.sh[tag=helm-add-repo] ---- -Then install the Stackable Operators: +Install the Stackable operators: [source,bash] ---- include::example$getting_started/getting_started.sh[tag=helm-install-operators] ---- -Helm will deploy the operators in a Kubernetes Deployment and apply the CRDs for the HBase cluster (as well as the CRDs for the required operators). -You are now ready to deploy HBase in Kubernetes. +Helm deploys the operators in a Kubernetes Deployment and apply the CRDs for the HBase cluster (as well as the CRDs for the required operators). +-- +==== == What's next diff --git a/docs/modules/hbase/pages/index.adoc b/docs/modules/hbase/pages/index.adoc index 4a15ac44..23ea1ae2 100644 --- a/docs/modules/hbase/pages/index.adoc +++ b/docs/modules/hbase/pages/index.adoc @@ -18,7 +18,7 @@ Apache HBase is an open-source, distributed, non-relational database that runs o == Getting started Follow the xref:getting_started/index.adoc[] guide to learn how to xref:getting_started/installation.adoc[install] the Stackable operator for Apache HBase as well as the dependencies. -The guide will also show you how to xref:getting_started/first_steps.adoc[interact] with HBase running on Kubernetes by creating tables and some data using the REST API or Apache Phoenix. +The guide shows you how to xref:getting_started/first_steps.adoc[interact] with HBase running on Kubernetes by creating tables and some data using the REST API or Apache Phoenix. The xref:usage-guide/index.adoc[] contains more information on xref:usage-guide/phoenix.adoc[] as well as other topics such as xref:usage-guide/resource-requests.adoc[CPU and memory configuration], xref:usage-guide/monitoring.adoc[] and @@ -55,7 +55,7 @@ The xref:demos:hbase-hdfs-load-cycling-data.adoc[] demo shows how you can use HB == Supported versions The Stackable operator for Apache HBase currently supports the HBase versions listed below. -To use a specific HBase version in your HBaseCluster, you have to specify an image - this is explained in the xref:concepts:product-image-selection.adoc[] documentation. +To use a specific HBase version in your HBaseCluster, you have to specify an image -- this is explained in the xref:concepts:product-image-selection.adoc[] documentation. The operator also supports running images from a custom registry or running entirely customized images; both of these cases are explained under xref:concepts:product-image-selection.adoc[] as well. include::partial$supported-versions.adoc[] diff --git a/docs/modules/hbase/pages/reference/commandline-parameters.adoc b/docs/modules/hbase/pages/reference/commandline-parameters.adoc index 055b9cc0..8f28dd89 100644 --- a/docs/modules/hbase/pages/reference/commandline-parameters.adoc +++ b/docs/modules/hbase/pages/reference/commandline-parameters.adoc @@ -23,7 +23,7 @@ stackable-hbase-operator run --product-config /foo/bar/properties.yaml *Multiple values:* false -The operator will **only** watch for resources in the provided namespace `test`: +The operator **only** watches for resources in the provided namespace `test`: [source] ---- diff --git a/docs/modules/hbase/pages/reference/environment-variables.adoc b/docs/modules/hbase/pages/reference/environment-variables.adoc index 8efdc889..cf76fc7f 100644 --- a/docs/modules/hbase/pages/reference/environment-variables.adoc +++ b/docs/modules/hbase/pages/reference/environment-variables.adoc @@ -36,7 +36,7 @@ docker run \ *Multiple values:* false -The operator will **only** watch for resources in the provided namespace `test`: +The operator **only** watches for resources in the provided namespace `test`: [source] ---- diff --git a/docs/modules/hbase/pages/usage-guide/operations/graceful-shutdown.adoc b/docs/modules/hbase/pages/usage-guide/operations/graceful-shutdown.adoc index 3ed465e8..3eb85373 100644 --- a/docs/modules/hbase/pages/usage-guide/operations/graceful-shutdown.adoc +++ b/docs/modules/hbase/pages/usage-guide/operations/graceful-shutdown.adoc @@ -6,8 +6,8 @@ You can configure the graceful shutdown as described in xref:concepts:operations As a default, masters have `20 minutes` to shut down gracefully. -The HBase master process will receive a `SIGTERM` signal when Kubernetes wants to terminate the Pod. -After the graceful shutdown timeout runs out, and the process still didn't exit, Kubernetes will issue a `SIGKILL` signal. +The HBase master process receives a `SIGTERM` signal when Kubernetes wants to terminate the Pod. +After the graceful shutdown timeout runs out, and the process is still running, Kubernetes issues a `SIGKILL` signal. This is equivalent to executing the `bin/hbase-daemon.sh stop master` command, which internally executes `kill ` (https://github.com/apache/hbase/blob/8382f55b15be6ae190f8d202a5e6a40af177ec76/bin/hbase-daemon.sh#L338[code]), waits for a configurable period of time (defaults to 20 minutes), and finally executes `kill -9 ` to `SIGKILL` the master (https://github.com/apache/hbase/blob/8382f55b15be6ae190f8d202a5e6a40af177ec76/bin/hbase-common.sh#L20-L41[code]). diff --git a/docs/modules/hbase/pages/usage-guide/operations/pod-placement.adoc b/docs/modules/hbase/pages/usage-guide/operations/pod-placement.adoc index 4adaa1da..3401afa1 100644 --- a/docs/modules/hbase/pages/usage-guide/operations/pod-placement.adoc +++ b/docs/modules/hbase/pages/usage-guide/operations/pod-placement.adoc @@ -106,7 +106,7 @@ In the examples above `cluster-name` is the name of the HBase custom resource th The `hdfs-cluster-name` is the name of the HDFS cluster that was configured in the `hdfsConfigMapName` property. NOTE: It is important that the `hdfsConfigMapName` property contains the name the HDFS cluster. -You could instead configure ConfigMaps of specific name or data roles, but for the purpose of pod placement, this will lead to faulty behavior. +You could instead configure ConfigMaps of specific name or data roles, but for the purpose of Pod placement, this leads to faulty behavior. == Use custom pod placement For general configuration of Pod placement, see the xref:concepts:operations/pod_placement.adoc[Pod placement concepts] page. @@ -131,4 +131,4 @@ spec: replicas: 2 ---- -WARNING: Please note that the Pods will be stuck in `Pending`, when your Kubernetes cluster does not have any node without a masters already running on it and sufficient compute resources. +WARNING: The Pods remain in the `Pending` phase until the masters are up and running and there are sufficient compute resources available. diff --git a/docs/modules/hbase/pages/usage-guide/overrides.adoc b/docs/modules/hbase/pages/usage-guide/overrides.adoc index b39fccb9..346c1100 100644 --- a/docs/modules/hbase/pages/usage-guide/overrides.adoc +++ b/docs/modules/hbase/pages/usage-guide/overrides.adoc @@ -4,15 +4,15 @@ The HBase xref:concepts:stacklet.adoc[Stacklet] definition also supports overriding configuration properties, environment variables and Pod specs, either per role or per role group, where the more specific override (role group) has precedence over the less specific one (role). -IMPORTANT: Overriding certain properties which are set by operator can interfere with the operator and can lead to problems. +IMPORTANT: Overriding operator-set properties can interfere with the operator and can lead to problems. == Configuration properties For a role or role group, at the same level of `config`, you can specify: `configOverrides` for the following files: -- `hbase-site.xml` -- `hbase-env.sh` -- `security.properties` +* `hbase-site.xml` +* `hbase-env.sh` +* `security.properties` NOTE: `hdfs-site.xml` is not listed here, the file is always taken from the referenced HDFS cluster. If you want to modify it, take a look at xref:hdfs:usage-guide/configuration-environment-overrides.adoc[HDFS configuration overrides]. @@ -33,7 +33,7 @@ restServers: replicas: 1 ---- -Just as for the `config`, it is possible to specify this at role level as well: +Just as for the `config`, you can specify this at role level as well: [source,yaml] ---- @@ -50,7 +50,7 @@ restServers: ---- All override property values must be strings. -The properties will be formatted and escaped correctly into the XML file, respectively inserted as is into the `hbase-env.sh` file. +The properties are formatted and escaped correctly into the XML file, respectively inserted as is into the `hbase-env.sh` file. For a full list of configuration options we refer to the HBase https://hbase.apache.org/book.html#config.files[configuration documentation]. diff --git a/docs/modules/hbase/pages/usage-guide/phoenix.adoc b/docs/modules/hbase/pages/usage-guide/phoenix.adoc index ba86a3f7..03205656 100644 --- a/docs/modules/hbase/pages/usage-guide/phoenix.adoc +++ b/docs/modules/hbase/pages/usage-guide/phoenix.adoc @@ -4,7 +4,7 @@ :sqlline-github: https://github.com/julianhyde/sqlline Apache Phoenix allows you to interact with HBase using a familiar SQL-syntax via a JDBC driver. -The Phoenix dependencies are bundled with the Stackable HBase image and do not need to be installed separately (client components will need to ensure that they have the correct client-side libraries available). +The Phoenix dependencies are bundled with the Stackable HBase image and do not need to be installed separately (client components need to ensure that they have the correct client-side libraries available). Information about client-side installation can be found {phoenix-installation}[here]. Apache Phoenix comes bundled with a few simple scripts to verify a correct server-side installation. diff --git a/docs/modules/hbase/pages/usage-guide/security.adoc b/docs/modules/hbase/pages/usage-guide/security.adoc index 6353ac26..a6c65e15 100644 --- a/docs/modules/hbase/pages/usage-guide/security.adoc +++ b/docs/modules/hbase/pages/usage-guide/security.adoc @@ -104,8 +104,8 @@ include::example$usage-guide/hbase-regorules.yaml[] ---- This rego rule is intended for demonstration purposes and allows every operation. -For a production setup you will probably need to have something much more granular. -We provide a more representative rego rule in our integration tests and in the aforementioned coprocessor repository. +For a production setup you probably need to have something much more granular. +A more representative rego rule can be found in our integration tests and in the aforementioned coprocessor repository. Details can be found below in the <> section. === How it works @@ -114,7 +114,7 @@ WARNING: This implementation takes an approach to HBase authorization that is fu The current rego rules ignore file ownership and permissions, and ACLs are persisted neither in ZooKeeper nor internal HBase tables. Keeping this state in HDFS/HBase clashes with the infrastructure-as-code approach (IaC). -Instead, HBase will send a request detailing who (e.g. `alice/test-hbase-permissions.default.svc.cluster.local@CLUSTER.LOCAL`) is trying to execute what type of action (e.g. `READ`, `WRITE`, `CREATE` or `ADMIN`) on what namespace or table (e.g. `developers:`, `developers/table1`) to OPA. +Instead, HBase sends a request detailing who (e.g. `alice/test-hbase-permissions.default.svc.cluster.local@CLUSTER.LOCAL`) is trying to execute what type of action (e.g. `READ`, `WRITE`, `CREATE` or `ADMIN`) on what namespace or table (e.g. `developers:`, `developers/table1`) to OPA. OPA then makes a decision whether this action is allowed or not. Instead of using the HBase shell to grant or revoke rights to users, you can create rules for OPA using the Rego language to define what a specific user is allowed or not allowed to do to.