Add diagrams (#90)

This adds diagrams for what the operator does when scaling up and updating a CassandraDatacenter. It also adds a mage task to generate these diagrams using mermaid-js.

docs/developer/diagrams/scale-up-diagram.mmd

@@ -0,0 +1,37 @@
+sequenceDiagram
+  participant user as User
+  participant operator as Cass Operator
+  participant dc as dc1<br/>CassandraDatacenter
+  participant sts as cluster1-dc1-r1-sts<br/>StatefulSet
+  participant sts_ctrl as StatefulSet<br/>Controller
+  participant pod1 as cluster1-dc1-r1-sts-1<br/>Pod
+  participant pod2 as cluster1-dc1-r1-sts-2<br/>Pod
+	user->>dc: update size by 2
+  dc->>operator: update event
+  operator->>dc: set ScalingUp condition to True
+  operator->>sts: increment replicas by 2
+  sts->>sts_ctrl: update event
+  par create pods in parallel
+    sts_ctrl->>pod1: create
+  and
+    sts_ctrl->>pod2: create
+  end
+  loop requeue reconcile event until Node Management API running
+    operator->>pod1: check Node Management API running
+    operator->>pod2: check Node Management API running
+  end
+  Note over operator,pod1: Assuming Node Management API starts running on cluster1-dc1-r1-sts-1 first
+  operator->>pod1: start cassandra
+  Note over sts_ctrl,pod1: pod ready when cassandra<br/>finished starting
+  pod1->>sts_ctrl: update event (pod ready)
+  sts_ctrl->>sts: increment ready replicas
+  sts->>operator: update event
+  loop requeue reconcile event until Node Management API running
+    operator->>pod2: check Node Management API running
+  end
+  operator->>pod2: start cassandra
+  Note over sts_ctrl,pod2: pod ready when cassandra finished starting
+  pod2->>sts_ctrl: update event (pod ready)
+  sts_ctrl->>sts: increment ready replicas
+  sts->>operator: update event
+  operator->>dc: set ScalingUp condition to False

docs/developer/diagrams/update-diagram.mmd

@@ -0,0 +1,64 @@
+sequenceDiagram
+  participant user as User
+  participant operator as Cass Operator
+  participant dc as dc1<br/>CassandraDatacenter
+  participant sts1 as cluster1-dc1-r1-sts<br/>StatefulSet
+  participant sts2 as cluster1-dc1-r2-sts<br/>StatefulSet
+  participant sts_ctrl as StatefulSet<br/>Controller
+  participant pod1 as cluster1-dc1-r1-sts-0<br/>Pod
+  participant pod2 as cluster1-dc1-r1-sts-1<br/>Pod
+  participant pod3 as cluster1-dc1-r2-sts-0<br/>Pod
+  participant pod4 as cluster1-dc1-r2-sts-1<br/>Pod
+	user->>dc: update config
+  dc->>operator: update event
+  operator->>dc: set Updating condition to True
+  operator->>sts1: update pod template
+  sts1->>sts_ctrl: update event
+  sts_ctrl->>pod2: delete and recreate
+  sts_ctrl->>sts1: decrement ready replicas
+  sts1->>operator: update event
+  loop requeue reconcile event until Node Management API running
+    operator->>pod2: check Node Management API running
+  end
+  operator->>pod2: start cassandra
+  Note over sts_ctrl,pod2: pod ready when cassandra<br/>finished starting
+  pod2->>sts_ctrl: update event (pod ready)
+  sts_ctrl->>sts1: increment ready replicas
+  sts1->>operator: update event
+  sts_ctrl->>pod1: delete and recreate
+  sts_ctrl->>sts1: decrement ready replicas
+  sts1->>operator: update event
+  loop requeue reconcile event until Node Management API running
+    operator->>pod1: check Node Management API running
+  end
+  operator->>pod1: start cassandra
+  Note over sts_ctrl,pod1: pod ready when cassandra<br/>finished starting
+  pod1->>sts_ctrl: update event (pod ready)
+  sts_ctrl->>sts1: increment ready replicas
+  sts1->>operator: update event
+
+  operator->>sts2: update pod template
+  sts2->>sts_ctrl: update event
+  sts_ctrl->>pod4: delete and recreate
+  sts_ctrl->>sts2: decrement ready replicas
+  sts2->>operator: update event
+  loop requeue reconcile event until Node Management API running
+    operator->>pod4: check Node Management API running
+  end
+  operator->>pod4: start cassandra
+  Note over sts_ctrl,pod4: pod ready when cassandra finished starting
+  pod4->>sts_ctrl: update event (pod ready)
+  sts_ctrl->>sts2: increment ready replicas
+  sts2->>operator: update event
+  sts_ctrl->>pod3: delete and recreate
+  sts_ctrl->>sts2: decrement ready replicas
+  sts1->>operator: update event
+  loop requeue reconcile event until Node Management API running
+    operator->>pod3: check Node Management API running
+  end
+  operator->>pod3: start cassandra
+  Note over sts_ctrl,pod3: pod ready when cassandra finished starting
+  pod3->>sts_ctrl: update event (pod ready)
+  sts_ctrl->>sts2: increment ready replicas
+  sts2->>operator: update event
+  operator->>dc: set Updating condition to False

docs/developer/workflow_details.md

@@ -0,0 +1,37 @@
+## How the operator scales up a datacenter
+
+Given `CassandraDatacenter` like the following:
+
+```yaml
+apiVersion: cassandra.datastax.com/v1beta1
+kind: CassandraDatacenter
+metadata:
+  name: dc1
+spec:
+  clusterName: cluster1
+  serverType: cassandra
+  serverVersion: "3.11.6"
+  managementApiAuth:
+    insecure: {}
+  size: 1
+  storageConfig:
+    cassandraDataVolumeClaimSpec:
+      storageClassName: server-storage
+      accessModes:
+        - ReadWriteOnce
+      resources:
+        requests:
+          storage: 1Gi
+  racks:
+    - name: r1
+```
+
+When a user scales up the datacenter, for example, by doing the following:
+
+```
+kubectl patch cassandradatacenter/dc1 --patch '{"spec":{"size":3}}' --type merge
+```
+
+This is what the Cass Operator will do:
+
+![scale-up sequence diagram](./diagrams/scale-up-diagram.svg)

mage/operator/lib.go

@@ -25,9 +25,11 @@ import (
 const (
 	rootBuildDir               = "./build"
 	sdkBuildDir                = "operator/build"
+	diagramsDir                = "./docs/developer/diagrams"
 	operatorSdkImage           = "operator-sdk-binary"
 	testSdkImage               = "operator-sdk-binary-tester"
 	genClientImage             = "operator-gen-client"
+	mermaidJsImage             = "operator-mermaid-js"
 	generatedDseDataCentersCrd = "operator/deploy/crds/cassandra.datastax.com_cassandradatacenters_crd.yaml"
 	packagePath                = "github.com/datastax/cass-operator/operator"
 	envGitBranch               = "MO_BRANCH"
@@ -416,6 +418,37 @@ func BuildDocker() {
 	writeBuildFile("tagsToPush.txt", outputText)
 }
 
+func buildMermaidJsDockerImage() {
+	dockerutil.Build("./tools/mermaid-js", "", "./tools/mermaid-js/Dockerfile",
+		[]string{mermaidJsImage}, []string{}).ExecVPanic()
+}
+
+func generateDocDiagram(in string, out string) {
+	runArgs := []string{}
+	execArgs := []string{
+		"-i", in,
+		"-o", out,
+	}
+	diagramsDirAbs, err := filepath.Abs(diagramsDir)
+	mageutil.PanicOnError(err)
+	volumes := []string{fmt.Sprintf("%s:%s", diagramsDirAbs, "/data")}
+	dockerutil.Run(mermaidJsImage, volumes, nil, nil, runArgs, execArgs).ExecVPanic()
+}
+
+func doGenerateDocDiagrams() {
+	diagramSrcExt := ".mmd"
+	svgExt := ".svg"
+	files, err := ioutil.ReadDir(diagramsDir)
+	mageutil.PanicOnError(err)
+	for _, file := range files {
+		if strings.HasSuffix(file.Name(), diagramSrcExt) {
+			base := strings.TrimSuffix(file.Name(), diagramSrcExt)
+			svg := fmt.Sprintf("%s%s", base, svgExt)
+			generateDocDiagram(file.Name(), svg)
+		}
+	}
+}
+
 func buildCodeGeneratorDockerImage() {
 	// Use the version of code-generator that we are pinned to
 	// in operator/go.mod.
@@ -450,6 +483,12 @@ func doGenerateClient() {
 	dockerutil.Run(genClientImage, volumes, nil, nil, runArgs, execArgs).ExecVPanic()
 }
 
+// Generate diagrams for docs.
+func GenerateDiagrams() {
+	buildMermaidJsDockerImage()
+	doGenerateDocDiagrams()
+}
+
 // Gen operator client code.
 //
 // Uses k8s code-generator to generate client code that

tools/mermaid-js/Dockerfile

@@ -0,0 +1,15 @@
+# based on https://github.com/mermaid-js/mermaid.cli/blob/33a8334293308af13d307d5c3754841636e46da8/Dockerfile
+FROM node:14.2.0-stretch
+
+WORKDIR /mermaid-js
+
+RUN apt-get update && \
+    apt-get install -y gconf-service libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxss1 libxtst6 libappindicator1 libnss3 libasound2 libatk1.0-0 libc6 ca-certificates fonts-liberation lsb-release xdg-utils wget &&\
+    npm install @mermaid-js/[email protected]
+
+ADD puppeteer-config.json ./puppeteer-config.json
+
+WORKDIR /data
+
+ENTRYPOINT ["/mermaid-js/node_modules/.bin/mmdc", "-p", "/mermaid-js/puppeteer-config.json"]
+CMD [ "--help" ]

tools/mermaid-js/puppeteer-config.json

@@ -0,0 +1,6 @@
+
+{
+    "args": [
+        "--no-sandbox"
+    ]
+}