docker: Move Dockerfile files for "base" image from the root of the r…

…epository to docker/base. This unifies the locations of most of our Docker configurations and reduces complexity. In the past, we probably had to put the Dockerfile for the "base" image in the root for the automated build feature of Docker Hub. But now they support custom paths for the Dockerfile and we should no longer have to do this. Since the automated build looks for a README.md in the same file as the Dockerfile I created a new one in docker/base/. For the most part it is copied from the root directory, but I removed the badges at the top and the reference to Gitter. Additionally, I've created docker/README.md which lists our different Docker images and describes how they are used in detail.
wlx5575 · Apr 13, 2017 · 3b17529 · 3b17529
1 parent 4c87f97
commit 3b17529
Show file tree

Hide file tree

Showing 8 changed files with 100 additions and 8 deletions.
diff --git a/Makefile b/Makefile
@@ -148,6 +148,9 @@ php_proto:
 	docker cp vitess_php-proto:/vt/src/github.com/youtube/vitess/php/src/Vitess/Proto/. php/src/Vitess/Proto/
 	docker rm vitess_php-proto
 
+# Helper targets for building Docker images.
+# Please read docker/README.md to understand the different available images.
+
 # This rule builds the bootstrap images for all flavors.
 DOCKER_IMAGES_FOR_TEST = mariadb mysql56 mysql57 percona percona57
 DOCKER_IMAGES = common $(DOCKER_IMAGES_FOR_TEST)
@@ -164,29 +167,26 @@ docker_bootstrap_push:
 docker_bootstrap_pull:
 	for i in $(DOCKER_IMAGES); do echo "pulling bootstrap image: $$i"; docker pull vitess/bootstrap:$$i || exit 1; done
 
-# Note: The default base and lite images (tag "latest") use MySQL 5.7.
-# Images with other MySQL/MariaDB versions get their own tag e.g. "mariadb".
-# We never push the non-"latest" tags though and only provide them for convenience for users who want to run something else than MySQL 5.7.
 docker_base:
 	# Fix permissions before copying files, to avoid AUFS bug.
 	chmod -R o=g *
-	docker build -t vitess/base .
+	docker build -f docker/base/Dockerfile -t vitess/base .
 
 docker_base_mysql56:
 	chmod -R o=g *
-	docker build -f Dockerfile.mysql56 -t vitess/base:mysql56 .
+	docker build -f docker/base/Dockerfile.mysql56 -t vitess/base:mysql56 .
 
 docker_base_mariadb:
 	chmod -R o=g *
-	docker build -f Dockerfile.mariadb -t vitess/base:mariadb .
+	docker build -f docker/base/Dockerfile.mariadb -t vitess/base:mariadb .
 
 docker_base_percona:
 	chmod -R o=g *
-	docker build -f Dockerfile.percona -t vitess/base:percona .
+	docker build -f docker/base/Dockerfile.percona -t vitess/base:percona .
 
 docker_base_percona57:
 	chmod -R o=g *
-	docker build -f Dockerfile.percona57 -t vitess/base:percona57 .
+	docker build -f docker/base/Dockerfile.percona57 -t vitess/base:percona57 .
 
 docker_lite: docker_base
 	cd docker/lite && ./build.sh

diff --git a/docker/README.md b/docker/README.md
@@ -0,0 +1,62 @@
+# Vitess Docker Images
+
+The Vitess Project publishes several Docker images in the [Docker Hub "vitess" repository](https://hub.docker.com/u/vitess/).
+This file describes the purpose of the different images.
+
+**TL;DR:** Use the [vitess/lite](https://hub.docker.com/r/vitess/lite/) image for running Vitess.
+Our Kubernetes Tutorial uses it as well.
+Instead of using the `latest` tag, you can pin it to a known stable version e.g. `v2.0`.
+
+## Principles
+
+The structure of this directory and our Dockerfile files is guided by the following principles:
+
+* The configuration of each Vitess image is in the directory `docker/<image>/`.
+* Configurations for other images e.g. our internal tool Keytar (see below), can be in a different location.
+* Images with more complex build steps have a `build.sh` script e.g. see [lite/build.sh](https://github.com/youtube/vitess/blob/master/docker/lite/build.sh).
+* Tags are used to provide (stable) versions e.g. see tag `v2.0` for the image [vitess/lite](https://hub.docker.com/r/vitess/lite/tags).
+* Where applicable, we provide a `latest` tag to reference the latest build of an image.
+
+## Images
+
+Our list of images can be grouped into:
+
+* published Vitess code
+* dependencies for our Kubernetes tutorial
+* internally used tools
+
+### Vitess
+
+| Image | How (When) Updated | Description |
+| --- | --- | --- |
+| **bootstrap** | manual (after incompatible changes are made to [bootstrap.sh](https://github.com/youtube/vitess/blob/master/bootstrap.sh) or [vendor/vendor.json](https://github.com/youtube/vitess/blob/master/vendor/vendor.json) | Basis for all Vitess images. It is a snapshot of the checked out repository after running `./bootstrap.sh`. Used to cache dependencies. Avoids lengthy recompilation of dependencies if they did not change. Our internal test runner [`test.go`](https://github.com/youtube/vitess/blob/master/test.go) uses it to test the code against different MySQL versions. |
+| **base** | automatic (after every GitHub push to the master branch) | Contains all Vitess server binaries. Snapshot after running `make build`. |
+| **root** | automatic (after every GitHub push to the master branch) | Same as **base** but with the default user set to "root". Required for Kubernetes. |
+| **lite** | manual (updated with every Vitess release) | Stripped down version of **base** e.g. source code and build dependencies are removed. Default image in our Kubernetes templates for minimized startup time. |
+
+All these Vitess images include a specific MySQL/MariaDB version ("flavor").
+
+  * We provide Dockerfile files for multiple flavors (`Dockerfile.<flavor>`).
+  * As of April 2017, the following flavors are supported: `mariadb`, `mysql56`, `mysql57`, `percona`(56), `percona57`
+  * On Docker Hub we publish only images with MySQL 5.7 to minimize maintenance overhead and avoid confusion.
+  * If you need an image for a different flavor, it is very easy to build it yourself. See the [Custom Docker Build instructions](http://vitess.io/getting-started/docker-build.html).
+
+If you are looking for a stable version of Vitess, use the **lite** image with a fixed version. If you are looking for the latest Vitess code in binary form, use the "latest" tag of the **base** image.
+
+### Kubernetes Tutorial Dependencies
+
+| Image | How (When) Updated | Description |
+| --- | --- | --- |
+| **etcd-lite** | manual | Our Kubernetes tutorial uses etcd as Vitess topology backing store and runs this image. It is a stripped version of the **etcd** image for faster Kubernetes startup times. Published as `vitess/etcd:<version>-lite` e.g. [v2.0.13-lite](https://hub.docker.com/r/vitess/etcd/tags/). |
+| **etcd** | manual | Basis for **etcd-lite**. |
+| **guestbook** | manual (updated with every Vitess release) | Vitess adaption of the Kubernetes guestbook example. Used to showcase sharding in Vitess. Dockerfile is located in [`examples/kubernetes/guestbook/`](https://github.com/youtube/vitess/tree/master/examples/kubernetes/guestbook). |
+| **orchestrator** | manual | Binaries for [Orchestrator](https://github.com/github/orchestrator). It can be used with Vitess for automatic failovers. Currently not part of the Kubernetes Tutorial and only used in tests. |
+
+### Internal Tools
+
+These images are used by the Vitess project for internal workflows and testing infrastructure and can be ignored by users.
+
+| Image | How (When) Updated | Description |
+| --- | --- | --- |
+| **publish-site** | manual | Contains [Jekyll](https://jekyllrb.com/) which we use to generate our [vitess.io](http://vitess.io) website from the Markdown files located in [doc/](https://github.com/youtube/vitess/tree/master/doc). |
+| **keytar** | manual | Keytar is a Vitess testing framework to run our Kubernetes cluster tests. Dockerfile is located in [`test/cluster/keytar/`](https://github.com/youtube/vitess/tree/master/test/cluster/keytar). |
diff --git a/Dockerfile → docker/base/Dockerfile b/Dockerfile → docker/base/Dockerfile
diff --git a/Dockerfile.mariadb → docker/base/Dockerfile.mariadb b/Dockerfile.mariadb → docker/base/Dockerfile.mariadb
diff --git a/Dockerfile.mysql56 → docker/base/Dockerfile.mysql56 b/Dockerfile.mysql56 → docker/base/Dockerfile.mysql56
diff --git a/Dockerfile.percona → docker/base/Dockerfile.percona b/Dockerfile.percona → docker/base/Dockerfile.percona
diff --git a/Dockerfile.percona57 → docker/base/Dockerfile.percona57 b/Dockerfile.percona57 → docker/base/Dockerfile.percona57
diff --git a/docker/base/README.md b/docker/base/README.md
@@ -0,0 +1,30 @@
+# Vitess 
+
+Vitess is a database clustering system for horizontal scaling of MySQL
+through generalized sharding.
+
+By encapsulating shard-routing logic, Vitess allows application code and
+database queries to remain agnostic to the distribution of data onto
+multiple shards. With Vitess, you can even split and merge shards as your needs
+grow, with an atomic cutover step that takes only a few seconds.
+
+Vitess has been a core component of YouTube's database infrastructure
+since 2011, and has grown to encompass tens of thousands of MySQL nodes.
+
+For more about Vitess, please visit [vitess.io](http://vitess.io).
+
+## Contact
+
+Ask questions in the
+[vitess@googlegroups.com](https://groups.google.com/forum/#!forum/vitess)
+discussion forum.
+
+Subscribe to
+[vitess-announce@googlegroups.com](https://groups.google.com/forum/#!forum/vitess-announce)
+or the [Vitess Blog](http://blog.vitess.io/)
+for low-frequency updates like new features and releases.
+
+## License
+
+Unless otherwise noted, the Vitess source files are distributed
+under the BSD-style license found in the LICENSE file.