This is an automated email from the ASF dual-hosted git repository. granthenke pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/kudu.git
commit c46efd29b78ddf3461886f3479d18e76a109c9b8 Author: Grant Henke <[email protected]> AuthorDate: Wed Jun 26 22:08:56 2019 -0700 [docs] Add new Docker based quickstart page This patch adds back the quickstart page now using the published Docker images and `docker-compose`. Follow up improvments can add more substantial demos including ones that use other services and Docker images. Change-Id: I2162922ba409578c59277398c47e7362e8a9775e Reviewed-on: http://gerrit.cloudera.org:8080/13747 Tested-by: Grant Henke <[email protected]> Reviewed-by: Andrew Wong <[email protected]> --- docker/quickstart.yml | 201 ++++++++++++++++++++++++ docs/configuration.adoc | 1 + docs/index.adoc | 1 + docs/quickstart.adoc | 190 ++++++++++++++++++++++ docs/release_notes.adoc | 1 + docs/support/jekyll-templates/document.html.erb | 1 + 6 files changed, 395 insertions(+) diff --git a/docker/quickstart.yml b/docker/quickstart.yml new file mode 100644 index 0000000..ec7d0e1 --- /dev/null +++ b/docker/quickstart.yml @@ -0,0 +1,201 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +version: "3" +services: + kudu-master-1: + image: apache/kudu:${KUDU_QUICKSTART_VERSION:-latest} + ports: + - "7051:7051" + - "8051:8051" + command: ["master"] + volumes: + - kudu-master-1:/var/lib/kudu + environment: + - KUDU_MASTERS=kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251 + # TODO: Use `host.docker.internal` instead of KUDU_QUICKSTART_IP when it + # works on Linux (https://github.com/docker/for-linux/issues/264) + - > + MASTER_ARGS=--fs_wal_dir=/var/lib/kudu/master + --rpc_bind_addresses=0.0.0.0:7051 + --rpc_advertised_addresses=${KUDU_QUICKSTART_IP:?Please set KUDU_QUICKSTART_IP environment variable}:7051 + --webserver_port=8051 + --webserver_advertised_addresses=${KUDU_QUICKSTART_IP}:8051 + --webserver_doc_root=/opt/kudu/www + --logtostderr + --use_hybrid_clock=false + kudu-master-2: + image: apache/kudu:${KUDU_QUICKSTART_VERSION:-latest} + ports: + - "7151:7151" + - "8151:8151" + command: ["master"] + volumes: + - kudu-master-2:/var/lib/kudu + environment: + - KUDU_MASTERS=kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251 + - > + MASTER_ARGS=--fs_wal_dir=/var/lib/kudu/master + --rpc_bind_addresses=0.0.0.0:7151 + --rpc_advertised_addresses=${KUDU_QUICKSTART_IP}:7151 + --webserver_port=8151 + --webserver_advertised_addresses=${KUDU_QUICKSTART_IP}:8151 + --webserver_doc_root=/opt/kudu/www + --logtostderr + --use_hybrid_clock=false + kudu-master-3: + image: apache/kudu:${KUDU_QUICKSTART_VERSION:-latest} + ports: + - "7251:7251" + - "8251:8251" + command: ["master"] + volumes: + - kudu-master-3:/var/lib/kudu + environment: + - KUDU_MASTERS=kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251 + - > + MASTER_ARGS=--fs_wal_dir=/var/lib/kudu/master + --rpc_bind_addresses=0.0.0.0:7251 + --rpc_advertised_addresses=${KUDU_QUICKSTART_IP}:7251 + --webserver_port=8251 + --webserver_advertised_addresses=${KUDU_QUICKSTART_IP}:8251 + --webserver_doc_root=/opt/kudu/www + --logtostderr + --use_hybrid_clock=false + kudu-tserver-1: + image: apache/kudu:${KUDU_QUICKSTART_VERSION:-latest} + depends_on: + - kudu-master-1 + - kudu-master-2 + - kudu-master-3 + ports: + - "7050:7050" + - "8050:8050" + command: ["tserver"] + volumes: + - kudu-tserver-1:/var/lib/kudu + environment: + - KUDU_MASTERS=kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251 + - > + TSERVER_ARGS=--fs_wal_dir=/var/lib/kudu/tserver + --rpc_bind_addresses=0.0.0.0:7050 + --rpc_advertised_addresses=${KUDU_QUICKSTART_IP}:7050 + --webserver_port=8050 + --webserver_advertised_addresses=${KUDU_QUICKSTART_IP}:8050 + --webserver_doc_root=/opt/kudu/www + --logtostderr + --use_hybrid_clock=false + kudu-tserver-2: + image: apache/kudu:${KUDU_QUICKSTART_VERSION:-latest} + depends_on: + - kudu-master-1 + - kudu-master-2 + - kudu-master-3 + ports: + - "7150:7150" + - "8150:8150" + command: ["tserver"] + volumes: + - kudu-tserver-2:/var/lib/kudu + environment: + - KUDU_MASTERS=kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251 + - > + TSERVER_ARGS=--fs_wal_dir=/var/lib/kudu/tserver + --rpc_bind_addresses=0.0.0.0:7150 + --rpc_advertised_addresses=${KUDU_QUICKSTART_IP}:7150 + --webserver_port=8150 + --webserver_advertised_addresses=${KUDU_QUICKSTART_IP}:8150 + --webserver_doc_root=/opt/kudu/www + --logtostderr + --use_hybrid_clock=false + kudu-tserver-3: + image: apache/kudu:${KUDU_QUICKSTART_VERSION:-latest} + depends_on: + - kudu-master-1 + - kudu-master-2 + - kudu-master-3 + ports: + - "7250:7250" + - "8250:8250" + command: ["tserver"] + volumes: + - kudu-tserver-3:/var/lib/kudu + environment: + - KUDU_MASTERS=kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251 + - > + TSERVER_ARGS=--fs_wal_dir=/var/lib/kudu/tserver + --rpc_bind_addresses=0.0.0.0:7250 + --rpc_advertised_addresses=${KUDU_QUICKSTART_IP}:7250 + --webserver_port=8250 + --webserver_advertised_addresses=${KUDU_QUICKSTART_IP}:8250 + --webserver_doc_root=/opt/kudu/www + --logtostderr + --use_hybrid_clock=false + kudu-tserver-4: + image: apache/kudu:${KUDU_QUICKSTART_VERSION:-latest} + depends_on: + - kudu-master-1 + - kudu-master-2 + - kudu-master-3 + ports: + - "7350:7350" + - "8350:8350" + command: ["tserver"] + volumes: + - kudu-tserver-4:/var/lib/kudu + environment: + - KUDU_MASTERS=kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251 + - > + TSERVER_ARGS=--fs_wal_dir=/var/lib/kudu/tserver + --rpc_bind_addresses=0.0.0.0:7350 + --rpc_advertised_addresses=${KUDU_QUICKSTART_IP}:7350 + --webserver_port=8350 + --webserver_advertised_addresses=${KUDU_QUICKSTART_IP}:8350 + --webserver_doc_root=/opt/kudu/www + --logtostderr + --use_hybrid_clock=false + kudu-tserver-5: + image: apache/kudu:${KUDU_QUICKSTART_VERSION:-latest} + depends_on: + - kudu-master-1 + - kudu-master-2 + - kudu-master-3 + ports: + - "7450:7450" + - "8450:8450" + command: ["tserver"] + volumes: + - kudu-tserver-5:/var/lib/kudu + environment: + - KUDU_MASTERS=kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251 + - > + TSERVER_ARGS=--fs_wal_dir=/var/lib/kudu/tserver + --rpc_bind_addresses=0.0.0.0:7450 + --rpc_advertised_addresses=${KUDU_QUICKSTART_IP}:7450 + --webserver_port=8450 + --webserver_advertised_addresses=${KUDU_QUICKSTART_IP}:8450 + --webserver_doc_root=/opt/kudu/www + --logtostderr + --use_hybrid_clock=false +volumes: + kudu-master-1: + kudu-master-2: + kudu-master-3: + kudu-tserver-1: + kudu-tserver-2: + kudu-tserver-3: + kudu-tserver-4: + kudu-tserver-5: \ No newline at end of file diff --git a/docs/configuration.adoc b/docs/configuration.adoc index 16f5630..e9bb291 100644 --- a/docs/configuration.adoc +++ b/docs/configuration.adoc @@ -152,4 +152,5 @@ line tool. |=== == Next Steps +- link:quickstart.html[Get Started With Kudu] - link:developing.html[Developing Applications With Kudu] diff --git a/docs/index.adoc b/docs/index.adoc index 196e3e0..7a301ec 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -262,4 +262,5 @@ RDBMS, and some in files in HDFS. You can access and query all of these sources formats using Impala, without the need to change your legacy systems. == Next Steps +- link:quickstart.html[Get Started With Kudu] - link:installation.html[Installing Kudu] diff --git a/docs/quickstart.adoc b/docs/quickstart.adoc new file mode 100644 index 0000000..9ccaafd --- /dev/null +++ b/docs/quickstart.adoc @@ -0,0 +1,190 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +[[quickstart]] += Apache Kudu Quickstart +:author: Kudu Team +:imagesdir: ./images +:icons: font +:toc: left +:toclevels: 2 +:doctype: book +:backend: html5 +:sectlinks: +:experimental: + +Follow these instructions to set up and run a local Kudu Cluster using Docker, +and get started using Apache Kudu in minutes. + +Note: This is intended for demonstration purposes only and shouldn't +be used for production or performance/scale testing. + +[[quickstart_vm]] + +== Install Docker + +Follow the Docker link:https://docs.docker.com/install/[install documentation] +to install docker in your Linux, Mac, or Windows environment. + +You may also want to read through the Docker getting started guide, but that isn't a requirement. + +== Clone the Repository + +Clone the Apache Kudu repository using Git and change to the `kudu` directory: + +[source,bash] +---- +$ git clone https://github.com/apache/kudu +$ cd kudu +---- + +== Start the Quickstart Cluster + +=== Set KUDU_QUICKSTART_IP + +Set the `KUDU_QUICKSTART_IP` environment variable to your ip address: + +[source,bash] +---- +$ export KUDU_QUICKSTART_IP=$(ifconfig | grep "inet " | grep -Fv 127.0.0.1 | cut -d" " -f2 | tail -1) +---- + +=== Bring up the Cluster + +Then use `docker-compose` to start a cluster with 3 master servers and 5 tablet servers. +When inside the docker network/containers the master addresses will be +`kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251` and when on the host machine +you can specify the master addresses with `localhost:7051,localhost:7151,localhost:7251`. + +[source,bash] +---- +docker-compose -f docker/quickstart.yml up +---- + +Note: You can include the `-d` flag to run the cluster in the background. + +=== View the Web-UI + +Once the cluster is started you can view the master web-ui by visiting link:localhost:8050[localhost:8050]. + +=== Check the cluster health + +Use the command below to get a bash shell in the `kudu-master-1` container: + +[source,bash] +---- +docker exec -it $(docker ps -aqf "name=kudu-master-1") /bin/bash +---- + +You can now run the Kudu `ksck` tool to verify the cluster is healthy: + +[source,bash] +---- +kudu cluster ksck kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251 +---- + +Alternatively, if you have a kudu binary available on your host machine, +you can run `ksck` there via: + +[source,bash] +---- +export KUDU_USER_NAME=kudu +kudu cluster ksck localhost:7051,localhost:7151,localhost:7251 +---- + +Note: Setting `KUDU_USER_NAME=kudu` simplifies using Kudu from various user +accounts in a non-secure environment. + +== Running an Example + +Now that a kudu cluster is up and running, examples and integrations can be +run against the cluster. The commands below run the `java-example` against +the quickstart cluster: + +[source,bash] +---- +export KUDU_USER_NAME=kudu +cd examples/java/java-example +mvn package +java -DkuduMasters=localhost:7051,localhost:7151,localhost:7251 -jar target/kudu-java-example-1.0-SNAPSHOT.jar +---- + +== Destroying the Cluster + +Once you are done with the quickstart cluster you can shutdown in a couple of ways. +If you ran `docker-compose` without the `-d` flag, you can use `ctrl + c` to +stop the cluster. + +If you ran `docker-compose` with the `-d` flag, you can use the following to +gracefully shutdown the cluster: + +[source,bash] +---- +docker-compose -f docker/quickstart.yml down +---- + +Another alternative is to stop all of the Kudu containers via: + +[source,bash] +---- +docker stop $(docker ps -aqf "name=kudu") +---- + +If you want to remove the cluster state you can also remove the docker +containers and volumes via: + +[source,bash] +---- +docker rm $(docker ps -aqf "name=kudu") +docker volume rm $(docker volume ls --filter name=kudu -q) +---- + +== Troubleshooting + +=== Viewing the logs + +To view the logs you can use the `docker logs` command. Below is an example +that will show the logs one of the tablet servers: + +[source,bash] +---- +docker logs $(docker ps -aqf "name=kudu-tserver-1") +---- + +=== Changing the Kudu version + +To change the version of Kudu Docker images used you can override the default value +of `latest` by setting the `KUDU_QUICKSTART_VERSION` environment variable. + +[source,bash] +---- +export KUDU_QUICKSTART_VERSION="1.9.0" +---- + +=== Changing the Kudu configuration + +To change the configuration flags passed to the master and tablet servers you +can edit the `docker/quickstart.yml` file before starting the cluster. + +=== Killing a Kudu master + +Due to link:https://issues.apache.org/jira/browse/KUDU-1620[KUDU-1620] master hosts +are always expected to be reachable. + +== Next Steps +- link:installation.html[Installing Kudu] +- link:configuration.html[Configuring Kudu] diff --git a/docs/release_notes.adoc b/docs/release_notes.adoc index 495d3e3..0c362fe 100644 --- a/docs/release_notes.adoc +++ b/docs/release_notes.adoc @@ -125,6 +125,7 @@ documentation. For full installation details, see link:installation.html[Kudu Installation]. == Next Steps +- link:quickstart.html[Kudu Quickstart] - link:installation.html[Installing Kudu] - link:configuration.html[Configuring Kudu] diff --git a/docs/support/jekyll-templates/document.html.erb b/docs/support/jekyll-templates/document.html.erb index 5125a7f..41f1aa2 100644 --- a/docs/support/jekyll-templates/document.html.erb +++ b/docs/support/jekyll-templates/document.html.erb @@ -86,6 +86,7 @@ end %> toplevels = [ :index, "Introducing Kudu", :release_notes, "Kudu Release Notes", + :quickstart, "Getting Started with Kudu", :installation, "Installation Guide", :configuration, "Configuring Kudu", :kudu_impala_integration, "Using Impala with Kudu",
