Requirements for tools and documentation

• Open source tooling
• Editable with vim, emacs, etc
• Suitable for version control
• Suitable for scripting

Types of documentation

Component diagrams

Preferred tool : PlantUML

Note PlantUML requires graphviz to be installed to generate component diagrams.

1
2
3

# Command line
PLANTUML=~/Downloads/plantuml.jar
java -jar $PLANTUML -v -tpng src/k8s-runtime.uml -o ../out/

@startuml

title Kubernetes
skinparam componentStyle uml2

package "Development" {
  component Developer
  component [Code\nVCS] as VCS
  component CI
  component CD
}

package "External Services" {
  component MQ
  component DB
}

package "Kubernetes Cluster" {
  component "Nodes/Pods/Containers" as Service
  component [Controller] as Controller
}

package Artifacts {
  component [Container Registry] as Registry
  component [Config VCS] as Config
}

package "External Network" {
  component [User] as WebBrowser
}

Developer -l-> VCS : commit
VCS -d-> CI : test & build
CI -r-> CD
CI -d-> Registry : upload image
CD -r-> Controller : deploy

WebBrowser -u-> Service

Service -u-> MQ
Service -u-> DB

Controller -r-> Registry : fetch
Controller -d-> Config : fetch

Controller -l-> Service : deploy

@enduml

Useful parameters for Component Diagrams

skinparam componentType uml2

skinparam linetype splines
skinparam linetype ortho
skinparam linetype polyline

Sequence diagrams

Preferred tool : PlantUML

Note: PlantUML can generate sequence diagrams using only the plantuml.jar file.

@startuml

title Data flow

entity "Data Source" as DataSource

box "Integration" #lightblue
  entity "fluent-bit" as fluentbit
  entity "envoy" as envoy
end box

box "Monitoring"
  entity "Prometheus" as Prometheus
  entity "Grafana" as Grafana
end box

box "Splunk Platform" #lightblue
  entity "Splunk\nHeavy Forwarder" as HF
  database "Splunk Index" as IDX
  entity "Splunk SHC" as SHC
end box

actor "User" as User

== Events ==

DataSource -> fluentbit
fluentbit -> envoy : HTTP-Proxy/HEC
envoy -> HF : HTTP/HEC
HF -> IDX : TCP/Splunk forward

== Metrics ==

envoy -> Prometheus : metrics
fluentbit -> Prometheus : Metrics over HTTP

== Reporting ==

Prometheus -> Grafana
Grafana -> User : HTTP
IDX -> SHC
SHC -> User : HTTP

@enduml

Timing diagrams

Preferred tool : PlantUML

@startuml

robust "CPU0" as CPU0
robust "CPU1" as CPU1
concise "Task Progress" as TaskProgress
concise "Task Breakdown" as TaskBreakdown

@0
TaskProgress is Idle
TaskBreakdown is None
CPU1 is Idle
CPU0 is Idle

@100
TaskProgress is Running
TaskBreakdown is Serial
CPU0 is PreparingTask
CPU1 is Idle : Idle

CPU0@100 <-> @200 : 100 ms

@200
TaskBreakdown is Parallel
CPU0 is NumberCrunching
CPU0 -> CPU1 : Distribute task
CPU1 is NumberCrunching

@700
TaskProgress is Idle
TaskBreakdown is None
CPU1 -> CPU0 : Complete task
CPU0 is Idle
CPU1 is Idle

@1200
CPU0 is Idle
CPU1 is Idle
@enduml

Graph visualization

Preferred tool : Graphviz

1

 ~$ neato src/graph-cohesion.dot -Tpng -o out/graph-cohesion.png

digraph G {

  {node [label="Developer" style=filled color=skyblue] d1 d2 d3 d4 d5 }

  d1 -> d2 [len=2];
  d1 -> d3 [len=2];
  d1 -> d4 [len=2];
  d1 -> d5 [len=2];

  d2 -> d1 [len=2];
  d2 -> d3 [len=2];
  d2 -> d4 [len=2];
  d2 -> d5 [len=2];

  d3 -> d1 [len=2];
  d3 -> d2 [len=2];
  d3 -> d4 [len=2];
  d3 -> d5 [len=2];

  d4 -> d1 [len=2];
  d4 -> d2 [len=2];
  d4 -> d3 [len=2];
  d4 -> d5 [len=2];

  d5 -> d1 [len=2];
  d5 -> d2 [len=2];
  d5 -> d3 [len=2];
  d5 -> d4 [len=2];

}

Flow charts

Preferred tool : PlantUML

@startuml

scale 4

:Perform task;
note right
E.g. Manually resize a volume
end note
-> 
if (OK?) then
  -[#blue]-> p=**0.97**;
  :Task complete;
  -[#blue]-> Info;
  #Lightblue:Success1 = 0.97;
  -[#blue]->
else
  -[#red]-> p=**0.03**;
  :Emergency with plan;
  note right: Follow rollback procedure
  -[#red]->
  if (Recover?) then
    -[#green]-> p=**0.90**;
    #Lightgreen:Abort1 = (0.03 * 0.90);
    -[#green]->
    stop
  else
    -[#red]-> p=**0.10**;
    :Emergency without plan;
    -[#red]->
    if (Recover?) then
      -[#green]-> p=**0.70**;
      #Lightgreen: Abort2 = (0.03 * 0.10 * 0.70);
      -[#green]->
      stop
    else
      -[#red]-> p=**0.30**;
      #Pink: Failure1 = (0.03 * 0.10 * 0.30);
      -[#red]->
      stop
    endif
  endif
endif
-[#blue]->;
stop

@enduml

Plotting

Preferred tool : gnuplot

1

 ~$ gnuplot src/plot-usl-001.gnuplot

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

set terminal pngcairo size 1000,800 enhanced font 'Verdana,14'
set output 'out/plot-usl-001.png'
set border linewidth 1.5
set title "Scalability - Full USL"

set ylabel 'Work'
set xlabel 'Scale'

# Axes
set style line 11 lc rgb '#808080' lt 1
set border 3 back ls 11
set tics nomirror out scale 0.75

# Grid
set style line 12 lc rgb'#808080' lt 0 lw 1
set grid back ls 12

set style fill noborder
set style function filledcurves y1=0
set clip two

n = 1
s = 0.1 # serialization
k = 0.01 # crosstalk

USL(x, s, k) = (x * n) / (1 + s * (x - 1) + k*(x*(x-1)) )

f1(x) = USL(x, 0, 0)
f2(x) = USL(x, s, 0)
f3(x) = USL(x, s, k)
f4(x) = USL(x, 0, k)

set yrange [1:10]
set xrange [1:40]

unset colorbox
set key opaque
set key title "(xn) / (1 + s(x-1) + k(x(x-1)) )"
set key top right Left reverse samplen 1

set label "Linear scalability" at 10,9.2 front
set arrow from 7,6 to 10,9

set label "Serialization constrained" at 25, 5.5 front textcolor rgbcolor "#ffffff"
set label "Coordination constrained" at 6, 4 front textcolor rgbcolor "#ffffff"
set label "Serialization and coordination constrained" at 8, 2 front textcolor rgbcolor "#ffffff"

set lmargin 6
plot f1(x) fs transparent solid 0.30 lc rgb "light-green" title 'n=1   s=0     k=0', \
     f2(x) fs transparent solid 0.50 lc rgb "blue" title 'n=1   s=0.1  k=0', \
     f4(x) fs transparent solid 0.50 lc rgb "light-red" title 'n=1   s=0     k=0.01', \
     f3(x) fs transparent solid 0.70 lc rgb "red" title 'n=1   s=0.1  k=0.01'

Presentations

Preferred tool : pandoc

1
2
3
4
5

pandoc src/presentation.md \
--mathml  \
-t beamer \
--highlight-style espresso \
-o out/presentation.pdf

Reports

Preferred tool : pandoc

1
2
3
4
5
6

pandoc src/report.md \
 -V geometry:margin=1in \
--latex-engine=pdflatex \
--mathml  \
--highlight-style espresso \
-o out/report.pdf

Other tools

• inkscape
• ditaa
• mermaid