Update developer guide

Change-Id: I91cc70f100a86d2d4916833384c6bf73867d8e39

Dockerfile

@@ -1,4 +1,4 @@
-# Build the manager binary
+# Build the Flink Operator binary
 FROM golang:1.12.5 as builder
 
 WORKDIR /workspace
@@ -15,11 +15,11 @@ COPY api/ api/
 COPY controllers/ controllers/
 
 # Build
-RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 GO111MODULE=on go build -a -o manager main.go
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 GO111MODULE=on go build -a -o flink-operator main.go
 
-# Use distroless as minimal base image to package the manager binary
+# Use distroless as minimal base image to package the Flink Operator binary
 # Refer to https://github.com/GoogleContainerTools/distroless for more details
 FROM gcr.io/distroless/static:latest
 WORKDIR /
-COPY --from=builder /workspace/manager .
-ENTRYPOINT ["/manager"]
+COPY --from=builder /workspace/flink-operator .
+ENTRYPOINT ["/flink-operator"]

Makefile

@@ -1,18 +1,18 @@
 
 # Image URL to use all building/pushing image targets
-IMG ?= controller:latest
+IMG ?= flink-operator:latest
 # Produce CRDs that work back to Kubernetes 1.11 (no version conversion)
 CRD_OPTIONS ?= "crd:trivialVersions=true"
 
-all: manager
+all: flink-operator
 
 # Run tests
 test: generate fmt vet manifests
 	go test ./api/... ./controllers/... -coverprofile cover.out
 
-# Build manager binary
-manager: generate fmt vet
-	go build -o bin/manager main.go
+# Build flink-operator binary
+flink-operator: generate fmt vet
+	go build -o bin/flink-operator main.go
 
 # Run against the configured Kubernetes cluster in ~/.kube/config
 run: generate fmt vet
@@ -22,11 +22,18 @@ run: generate fmt vet
 install: manifests
 	kubectl apply -f config/crd/bases
 
-# Deploy controller in the configured Kubernetes cluster in ~/.kube/config
+# Deploy the operator in the configured Kubernetes cluster in ~/.kube/config
 deploy: manifests
 	kubectl apply -f config/crd/bases
 	kustomize build config/default | kubectl apply -f -
 
+undeploy:
+	kustomize build config/default | kubectl delete -f - || true
+
+# Deploy the sample Flink clusters in the Kubernetes cluster
+samples:
+	kubectl apply -f config/samples/
+
 # Generate manifests e.g. CRD, RBAC etc.
 manifests: controller-gen
 	$(CONTROLLER_GEN) $(CRD_OPTIONS) rbac:roleName=manager-role webhook paths="./..." output:crd:artifacts:config=config/crd/bases
@@ -46,7 +53,7 @@ generate: controller-gen
 # Build the docker image
 docker-build: test
 	docker build . -t ${IMG}
-	@echo "updating kustomize image patch file for manager resource"
+	@echo "updating kustomize image patch file for Flink Operator resource"
 	sed -i'' -e 's@image: .*@image: '"${IMG}"'@' ./config/default/manager_image_patch.yaml
 
 # Push the docker image

config/default/manager_auth_proxy_patch.yaml

@@ -19,6 +19,6 @@ spec:
         ports:
         - containerPort: 8443
           name: https
-      - name: manager
+      - name: flink-operator
         args:
         - "--metrics-addr=127.0.0.1:8080"

config/default/manager_image_patch.yaml

@@ -7,6 +7,6 @@ spec:
   template:
     spec:
       containers:
-      # Change the value of image field below to your controller image URL
+      # Change the value of image field below to your operator image URL
       - image: IMAGE_URL
-        name: manager
+        name: flink-operator

config/default/manager_prometheus_metrics_patch.yaml

@@ -1,4 +1,4 @@
-# This patch enables Prometheus scraping for the manager pod.
+# This patch enables Prometheus scraping for the flink-operator pod.
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -12,7 +12,7 @@ spec:
     spec:
       containers:
       # Expose the prometheus metrics on default port
-      - name: manager
+      - name: flink-operator
         ports:
         - containerPort: 8080
           name: metrics

config/default/manager_webhook_patch.yaml

@@ -7,7 +7,7 @@ spec:
   template:
     spec:
       containers:
-      - name: manager
+      - name: flink-operator
         ports:
         - containerPort: 443
           name: webhook-server

config/manager/manager.yaml

@@ -12,23 +12,26 @@ metadata:
   namespace: system
   labels:
     control-plane: controller-manager
+    app: flink-operator
 spec:
   selector:
     matchLabels:
       control-plane: controller-manager
+      app: flink-operator
   replicas: 1
   template:
     metadata:
       labels:
         control-plane: controller-manager
+        app: flink-operator
     spec:
       containers:
-      - command:
-        - /manager
+      - name: flink-operator
+        image: flink-operator:latest
+        command:      
+        - /flink-operator
         args:
         - --enable-leader-election
-        image: controller:latest
-        name: manager
         resources:
           limits:
             cpu: 100m

docs/developer-guide.md

@@ -1,16 +1,123 @@
 # Developer Guide
 
-## Build with Docker
+## Project overview
 
-The [Dockerfile](../docker/Dockerfile) specifies the dependencies and steps to build the operator from the source code. Run the following command from the root of the repo to start building a Docker image for the operator:
+The Flink Operator is built on top of the Kubernetes [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime)
+library, and the project structure and boilerplate files are generated with [Kubebuilder](https://github.com/kubernetes-sigs/kubebuilder).
+Knowledge of controller-runtime and Kubebuilder is required to better understand this project.
+
+The Flink custom resources are defined in Go structs, e.g. [FlinkSessionCluster](../api/v1alpha1/flinksessioncluster_types.go),
+then Kubebuild generates related other Go files and YAML files, e.g.
+[flinksessionclusters.yaml](../config/crd/bases/flinkoperator.k8s.io_flinksessionclusters.yaml).
+The custom logic for reconciling a Flink custom resource is inside of the [controllers](../controllers) directory, e.g.,
+[flinksessioncluster_controller.go](../controllers/flinksessioncluster_controller.go).
+
+The [Dockerfile](../Dockerfile) defines the steps of building the Flink Operator image.
+
+The [Makefile](../Makefile) includes various actions you can take to generate code, build the Flink Operator binary, run
+unit tests, build and push docker image, deploy the Flink Operator to a Kubernetes cluster.
+
+## Local build and test
+
+Run
+
+```bash
+make flink-operator
+```
+
+or simply
+
+```bash
+make
+```
+
+to build the Flink Operator binary locally. This is useful to detect compliation errors after you change the source
+code. ```make flink-operator``` automatically runs ```make generate``` which generates Go source code and YAML files
+with KubeBuilder.
+
+Run unit tests with
+
+```bash
+make test
+```
+
+## Build and push docker image
+
+Build a Docker image for the Flink Operator and then push it to an image
+registry with
+
+```bash
+make docker-build docker-push IMG=<tag>
+```
+
+Depending on which image registry you want to use, choose a tag accordingly, e.g., if you are using [Google Container Registry](https://cloud.google.com/container-registry/docs/) you want to use a tag like `gcr.io/<project>/flink-operator:latest`.
+
+## Deploy the operator to a running Kubernetes cluster
+
+Assume you have built and pushed the Flink Operator image, then you need to have a running Kubernetes cluster. Verify
+the cluster info with
+
+```bash
+kubectl cluster-info
+```
+
+Deploy the Flink Custom Resource Definitions and the Flink Operator to the cluster with
+
+```bash
+make deploy
+```
+
+After that, you can verify CRDs are created with
+
+```bash
+kubectl get crds | grep flink
+```
+
+The operator runs as a Kubernetes Deployment, you can find out the deployment with
+
+```bash
+kubectl get deployments -n flink-operator-system
+```
+
+or verify the operator pod is up and running.
+
+```bash
+kubectl get pods -n flink-operator-system
+```
+
+You can also check the operator logs with
 
 ```bash
-$ docker build -t <image-tag> -f docker/Dockerfile .
+kubectl logs -n flink-operator-system -l app=flink-operator --all-containers
 ```
 
-The operator image is based on [alpine image](https://hub.docker.com/_/alpine) by default, but you can use your own base image (e.g., an image with some custom dependencies) by specifying the argument `BASE_IMAGE`:
+## Create a sample Flink cluster
+
+After deploying the Flink CRDs and the Flink Operator to a Kubernetes cluster, the operator serves as a control plane for Flink. In other words, previously the cluster only understands the language of Kubernetes, now it understands the language of Flink. You can then create custom resources representing Flink session clusters or job clusters, the operator will detect the custom resources automatically, then create the actual clusters optionally run jobs, and update status in the custom resources.
+
+Deploy the sample Flink clusters with the following command
+
+```bash
+make samples
+```
+
+After that you can check the operator logs with
 
 ```bash
-$ docker build --build-arg BASE_IMAGE=<base-image> \
-    -t <image-tag> -f docker/Dockerfile .
+kubectl logs -n flink-operator-system -l app=flink-operator --all-containers -f --tail=1000
+```
+
+or check the custom resources with
+
+```bash
+kubectl describe flinksessionclusters
+kubectl describe flinkjobclusters
+```
+
+## Undeploy the operator
+
+Undeploy the operator from the Kubernetes cluster with
+
+```
+make undeploy
 ```