[docs] Add starter docs; upgrade helm chart (#66)

Adds very basic docs with an introduction to the operator and
instructions to install it. Auto-generates API docs.

Also ensures that `bundle.yaml` is up-to-date via CI, which necessitates
installing helm in our CI image.

Preparing for initial release!!

.buildkite/Dockerfile-ci

@@ -0,0 +1,8 @@
+FROM golang:1.10.4-stretch
+
+RUN mkdir /helm && \
+  cd /helm && \
+  wget -q -O helm.tgz https://storage.googleapis.com/kubernetes-helm/helm-v2.11.0-linux-amd64.tar.gz && \
+  tar xzvf helm.tgz && \
+  mv linux-amd64/helm /bin && \
+  rm -rf /helm

.buildkite/docker-compose.yml

@@ -1,18 +1,22 @@
-app:
-  image: golang:1.10.4-stretch
-  volumes:
-    - ../:/go/src/github.com/m3db/m3db-operator
-  environment:
-    - CI
-    - BUILDKITE
-    - BUILDKITE_AGENT_ACCESS_TOKEN
-    - BUILDKITE_JOB_ID
-    - BUILDKITE_BUILD_ID
-    - BUILDKITE_BUILD_NUMBER
-    - BUILDKITE_BRANCH
-    - BUILDKITE_BUILD_URL
-    - BUILDKITE_PROJECT_SLUG
-    - BUILDKITE_COMMIT
-    - BUILDKITE_PULL_REQUEST
-    - BUILDKITE_TAG
-    - CODECOV_TOKEN
+version: '3'
+services:
+  app:
+    build:
+      context: ./
+      dockerfile: Dockerfile-ci
+    volumes:
+      - ../:/go/src/github.com/m3db/m3db-operator
+    environment:
+      - CI
+      - BUILDKITE
+      - BUILDKITE_AGENT_ACCESS_TOKEN
+      - BUILDKITE_JOB_ID
+      - BUILDKITE_BUILD_ID
+      - BUILDKITE_BUILD_NUMBER
+      - BUILDKITE_BRANCH
+      - BUILDKITE_BUILD_URL
+      - BUILDKITE_PROJECT_SLUG
+      - BUILDKITE_COMMIT
+      - BUILDKITE_PULL_REQUEST
+      - BUILDKITE_TAG
+      - CODECOV_TOKEN

.buildkite/test.sh

@@ -7,4 +7,4 @@ export PACKAGE=github.com/m3db/m3db-operator
 echo "--- :git: Updating git submodules"
 git submodule update --init --recursive
 echo "--- Running unit tests"
-make clean-all test-ci-unit lint metalint test-all-gen build-bin
+make clean-all test-ci-unit lint metalint bins test-all-gen

.gitignore

@@ -21,6 +21,7 @@ vendor/
 
 # Ignore build artifacts
 out/**/*
+site/
 
 # ci artifacts
 .ci/
@@ -29,3 +30,6 @@ profile.cov
 
 # helm binaries
 linux-amd64/
+
+# Helm packages
+helm/**/*.tgz

CONTRIBUTING.md

@@ -0,0 +1,32 @@
+Contributing
+============
+
+We'd love your help building the M3DB Operator!
+
+## Getting Started
+
+M3DB Operator uses `dep` to manage dependencies. To get started:
+
+```bash
+git submodule update --init --recursive
+make dep-ensure
+```
+
+## Making A Change
+
+* Before making any significant changes, please [open an issue](https://github.com/m3db/m3db-operator/issues)
+
+* Discussing your proposed changes ahead of time will make the contribution process smooth for everyone.
+
+Once we've discussed your changes and you've got your code ready, make sure that tests are passing:
+
+```bash
+make test-all
+```
+
+Your pull request is most likely to be accepted if it:
+
+* Includes tests for new functionality.
+* Follows the guidelines in [Effective Go](https://golang.org/doc/effective_go.html) and the [Go team's common code
+  review comments](https://github.com/golang/go/wiki/CodeReviewComments).
+* Has a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).

Dockerfile

@@ -20,7 +20,7 @@ ADD . /go/src/github.com/m3db/m3db-operator
 RUN cd /go/src/github.com/m3db/m3db-operator/ && \
     git submodule update --init      && \
     dep ensure && \
-    make build-bin
+    make m3db-operator
 
 # stage 2: lightweight "release"
 FROM alpine:latest

Makefile

@@ -1,7 +1,6 @@
 PROJECT_NAME := m3db-operator
-REPO_PATH    := github.com/m3db/m3db-operator
-BUILD_PATH   := $(REPO_PATH)/cmd/$(PROJECT_NAME)
 OUTPUT_DIR   := out
+DOCS_OUT_DIR := site
 DEP_VERSION  := v0.5.0
 BUILD_SETTINGS := GOOS=linux GOARCH=amd64 CGO_ENABLED=0
 ifeq ($(shell uname), Darwin)
@@ -62,6 +61,32 @@ GOMETALINT_VERSION   := v2.0.5
 
 LINUX_AMD64_ENV := GOOS=linux GOARCH=amd64 CGO_ENABLED=0
 
+CMDS :=        		\
+	docgen       		\
+	m3db-operator 	\
+
+## Binary rules
+
+out:
+	@mkdir -p $$(pwd)/$(OUTPUT_DIR)
+
+define CMD_RULES
+
+.PHONY: $(CMD)
+$(CMD)-no-deps:
+	@echo "--- $(CMD)"
+	$(BUILD_SETTINGS) go build -o $(OUTPUT_DIR)/$(CMD) ./cmd/$(CMD)
+
+$(CMD): dep-ensure $(CMD)-no-deps
+
+endef
+
+$(foreach CMD,$(CMDS),$(eval $(CMD_RULES)))
+
+.PHONY: bins bins-no-deps
+bins: $(CMDS)
+bins-no-deps: $(foreach CMD,$(CMDS),$(CMD)-no-deps)
+
 .PHONY: lint
 lint: install-codegen-tools
 	@echo "--- $@"
@@ -80,6 +105,10 @@ test-xml: test-base
 	@$(convert-test-data) $(coverage_xml)
 	@rm $(coverfile) &> /dev/null
 
+.PHONY: test-all
+test-all: clean-all install-ci-tools verify-gen lint metalint test-all-gen bins test
+	@echo "--- $@"
+
 .PHONY: test
 test: test-base
 	@echo "--- $@"
@@ -163,7 +192,7 @@ asset-gen:
 	PATH=$(retool_bin_path):$(PATH) statik -src $(SELF_DIR)/assets -dest $(SELF_DIR)/pkg/ -p assets -f -m -c "$$LICENSE_HEADER"
 
 .PHONY: all-gen
-all-gen: mock-gen kubernetes-gen license-gen asset-gen
+all-gen: mock-gen kubernetes-gen license-gen asset-gen helm-bundle docs-api-gen
 
 # Ensure base commit had up-to-date generated artifacts
 .PHONY: test-all-gen
@@ -186,7 +215,7 @@ clean-all: clean ## Clean-all cleans all build dependencies.
 	@rm -rf _tools/
 
 .PHONY: all
-all: clean-all kubernetes-gen lint metalint test-ci-unit
+all: clean-all kubernetes-gen lint metalint test-ci-unit bins
 	@echo "$@ successfully finished"
 
 .PHONY: dep-ensure
@@ -203,25 +232,43 @@ kubernetes-gen: dep-ensure ## Generate boilerplate code for kubernetes packages
 verify-gen: dep-ensure ## Ensure all codegen is up to date
 	@./hack/verify-generated.sh
 
-.PHONY: build-bin
-build-bin: out dep-ensure build-bin-no-deps
-	@echo "--- $@"
-
-.PHONY: build-bin-no-deps
-build-bin-no-deps: ## Build m3db-operator binary
-	@echo "--- $@"
-	@echo "building $(PROJECT_NAME)..."
-	$(BUILD_SETTINGS) go build -o $(OUTPUT_DIR)/$(PROJECT_NAME) $(BUILD_PATH)
-
 .PHONY: build-docker
 build-docker: ## Build m3db-operator docker image with go binary
 	@echo "--- $@"
 	@./build/build-docker.sh
 
+.PHONE: helm-bundle
+helm-bundle:
+	@echo "--- $@"
+	@helm template helm/m3db-operator > bundle.yaml
+
 .PHONY: publish-helm-charts
 publish-helm-charts: ## pushes a new version of the helm chart
 	@echo "+ $@"
 	./build/package-helm-charts.sh
 
-out:
-	@mkdir -p $$(pwd)/$(OUTPUT_DIR)
+## Documentation
+
+.PHONY: docs-clean
+docs-clean:
+	mkdir -p $(DOCS_OUT_DIR)
+	rm -rf $(DOCS_OUT_DIR)/*
+
+.PHONY: docs-container
+docs-container:
+	docker build -t m3db-docs -f docs/Dockerfile docs
+
+.PHONY: docs-build
+docs-build: docs-clean docs-container
+	docker run -v $(PWD):/m3db --rm m3db-docs "mkdocs build -e docs/theme -t material"
+
+.PHONY: docs-serve
+docs-serve: docs-clean docs-container
+	docker run -v $(PWD):/m3db -p 8000:8000 -it --rm m3db-docs "mkdocs serve -e docs/theme -t material -a 0.0.0.0:8000"
+
+.PHONY: docs-api-gen-no-deps
+docs-api-gen-no-deps:
+	$(SELF_DIR)/out/docgen api pkg/apis/m3dboperator/v1alpha1/cluster.go pkg/apis/m3dboperator/v1alpha1/namespace.go pkg/apis/m3dboperator/v1alpha1/pod_identity.go > $(SELF_DIR)/docs/api.md
+
+.PHONY: docs-api-gen
+docs-api-gen: docgen docs-api-gen-no-deps

NOTICE.txt

@@ -0,0 +1,20 @@
+M3DB Operator includes derived work from Prometheus Operator
+(https://github.com/coreos/prometheus-operator) under the Apache License 2.0:
+
+  Copyright 2016 The prometheus-operator Authors
+
+  Licensed 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.
+
+The derived work can be found in the files:
+- cmd/docgen/main.go
+- cmd/docgen/api.go

README.md

@@ -10,39 +10,35 @@ The M3DB Operator is a project dedicated to setting up M3DB on Kubernetes. It ai
 * Shrinking clusters (removing instances)
 * Replacing failed instances
 
+More information:
+
+- [Documentation][docs]
+- [Gitter room](https://gitter.im/m3db/kubernetes)
+- [M3DB Google Group](https://groups.google.com/forum/#!forum/m3db)
 
 ## Getting Started
 
-The following instructions serve as a quickstart to get an M3DB cluster up and running in your Kubernetes cluster.
+The following instructions serve as a quickstart to get an M3DB cluster up and running in your Kubernetes cluster. This
+setup is not for production use, as there's no persistent storage. More information on production-grade clusters can be
+found in our [docs][docs].
 
 ### Kubernetes Cluster Prerequisites
 
-## Cloud (GKE) Prerequisites
-When running on GKE, the user applying the manifests will need the ability to
-allow `cluster-admin-binding` during the installation. Use the following
-`ClusterRoleBinding` with the user name provided by gcloud:
+The M3DB operator targets Kubernetes **1.10** and **1.11**. We generally aim to target the latest two minor versions
+supported by GKE but welcome community contributions to support more versions!
 
-```
-kubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user=<[email protected]>
-```
+The M3DB operator is intended for creating highly available clusters across distinct failure domains. For this reason we
+currently only support Kubernetes clusters with nodes in at least 3 zones, but [support][zonal] for zonal clusters is
+coming soon.
 
-Apply the persistent disk storage resource:
+When running on GKE, the user applying the manifests will need the ability to allow `cluster-admin-binding` during the
+installation. Use the following `ClusterRoleBinding` with the user name provided by gcloud:
 
 ```
-kubectl apply -f example/storage-fast-gcp.yaml
-```
-
-## etcd Cluster
-
-M3DB stores its topology in etcd, so it is necessary to deploy an etcd cluster for a healthy deployment of M3DB.  
-
-Apply the `etcd` cluster:
-
-```
-kubectl apply -f example/etcd.yaml
+kubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user=<[email protected]>
 ```
 
-## Installing the M3DB Operator 
+### Installing the M3DB Operator
 
 With Helm:
 
@@ -53,20 +49,21 @@ helm install m3db/m3db-operator --namespace m3db-operator
 
 With `kubectl`:
 
-`kubectl apply -f https://raw.githubusercontent.com/m3db/m3db-operator/master/bundle.yaml`
-
+```
+kubectl apply -f https://raw.githubusercontent.com/m3db/m3db-operator/v0.1.0/bundle.yaml
+```
 
 ## Managing Clusters
 
 ### Creating a Cluster
 
-Apply the `m3db` cluster:
+Create a simple etcd cluster to store M3DB's topology:
 
 ```
-kubectl apply -f https://github.com/m3db/m3db-operator/tree/master/example/etcd/etcd-basic.yaml
+kubectl apply -f https://raw.githubusercontent.com/m3db/m3db-operator/v0.1.0/example/etcd/etcd-basic.yaml
 ```
 
-Apply manifest with your zones specified for isolation groups: 
+Apply manifest with your zones specified for isolation groups:
 
 ```
 apiVersion: operator.m3db.io/v1alpha1
@@ -92,20 +89,28 @@ spec:
       preset: 10s:2d
 ```
 
-### Help
-```
->make help
+### Resizing a Cluster
+
+To resize a cluster, specify the new number of instances you want in each zone either by reapplying your manifest or
+using `kubectl edit`. The operator will safely scale up or scale down your cluster.
 
-  Usage:
-    make            <target>
+### Deleting a Cluster
 
-  Targets:
-    build-bin       Build m3db-operator binary
-    build-docker    Build m3db-operator docker image with go binary
-    code-gen        Generate boilerplate code for kubernetes packages
-    dep-ensure      Run dep ensure to generate vendor directory
-    dep-install     Ensure dep is installed
+Delete a cluster using `kubectl delete`. You will to remove the etcd data as well, or wipe the data generated by the
+operator if you intend to reuse the etcd cluster for another M3DB cluster:
+
+```
+kubectl exec etcd-0 -- env ETCDCTL_API=3 etcdctl del --keys-only --prefix ""
 ```
 
-### License
-This project is licensed under the Apache license -- see the [LICENSE](https://github.com/m3db/m3db-operator/blob/master/LICENSE) file for details. 
+## Contributing
+
+We welcome community contributions to to the M3DB operator! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for more
+information. Please note that on creating a pull request you will be asked to agree to the Uber CLA before we can accept
+your contribution.
+
+## License
+This project is licensed under the Apache license -- see the [LICENSE](https://github.com/m3db/m3db-operator/blob/master/LICENSE) file for details.
+
+[docs]: https://operator.m3db.io/
+[zonal]: https://github.com/m3db/m3db-operator/issues/68