diff --git a/.gitignore b/.gitignore
index ad08aa383691ace26179c6fcff09757937fbe9ea..e09b6644b0baf9a247708ccbf41f9b119a517c87 100644
--- a/.gitignore
+++ b/.gitignore
@@ -30,3 +30,7 @@ _testmain.go
.idea
scm-source.json
+
+# diagrams
+*.aux
+*.log
diff --git a/README.md b/README.md
index 403d63e7f3ac76c60331dafdb97440cd317b6a8a..9ea0291831cfe196885145496f02e893c159e0cd 100644
--- a/README.md
+++ b/README.md
@@ -33,8 +33,16 @@ new Postgres cluster CRD was submitted:
-There is a browser-friendly version of this documentation at
-[postgres-operator.readthedocs.io](https://postgres-operator.readthedocs.io)
+This picture is not complete without an overview of what is inside a pod, so
+let's zoom in:
+
+
+
+These two diagrams should help you to understand the basics of what kind of
+functionality the operator provides. Below we discuss all everything in more
+details.
+
+There is a browser-friendly version of this documentation at [postgres-operator.readthedocs.io](https://postgres-operator.readthedocs.io)
## Table of contents
diff --git a/docs/diagrams/Makefile b/docs/diagrams/Makefile
new file mode 100644
index 0000000000000000000000000000000000000000..0c0c7c918b76551a03d9e8f7bca0acc6c7107305
--- /dev/null
+++ b/docs/diagrams/Makefile
@@ -0,0 +1,11 @@
+OBJ=$(patsubst %.tex, %.png, $(wildcard *.tex))
+
+.PHONY: all
+
+all: $(OBJ)
+
+%.pdf: %.tex
+ lualatex $< -shell-escape $@
+
+%.png: %.pdf
+ convert -flatten -density 300 $< -quality 90 $@
diff --git a/docs/diagrams/operator.png b/docs/diagrams/operator.png
index af51bbf08102a6e304fa2340e47c561b80ec97ba..5e1cbfe8379966e9494aa9180c1989fc0dfc75d3 100644
Binary files a/docs/diagrams/operator.png and b/docs/diagrams/operator.png differ
diff --git a/docs/diagrams/operator.tex b/docs/diagrams/operator.tex
new file mode 100644
index 0000000000000000000000000000000000000000..a8ee0a05f9426ff38b823273c230cf414cb4e689
--- /dev/null
+++ b/docs/diagrams/operator.tex
@@ -0,0 +1,101 @@
+\documentclass{article}
+\usepackage{tikz}
+\usepackage[graphics,tightpage,active]{preview}
+\usetikzlibrary{arrows, shadows.blur, positioning, fit, calc, backgrounds}
+\usepackage{lscape}
+
+\pagenumbering{gobble}
+
+\PreviewEnvironment{tikzpicture}
+\PreviewEnvironment{equation}
+\PreviewEnvironment{equation*}
+\newlength{\imagewidth}
+\newlength{\imagescale}
+\pagestyle{empty}
+\thispagestyle{empty}
+
+\begin{document}
+\begin{center}
+\begin{tikzpicture}[
+ scale=0.5,transform shape,
+ font=\sffamily,
+ every matrix/.style={ampersand replacement=\&,column sep=2cm,row sep=2cm},
+ operator/.style={draw,solid,thick,circle,fill=red!20,inner sep=.3cm, blur shadow={shadow blur steps=5,shadow blur extra rounding=1.3pt}},
+ component/.style={draw,solid,thick,rounded corners,fill=yellow!20,inner sep=.3cm, blur shadow={shadow blur steps=5,shadow blur extra rounding=1.3pt}},
+ border/.style={draw,dashed,rounded corners,fill=gray!20,inner sep=.3cm, blur shadow={shadow blur steps=5,shadow blur extra rounding=1.3pt}},
+ pod/.style={draw,solid,thick,rounded corners,fill=blue!20, inner sep=.3cm, blur shadow={shadow blur steps=5,shadow blur extra rounding=1.3pt}},
+ service/.style={draw,solid,thick,rounded corners,fill=blue!20, inner sep=.3cm, blur shadow={shadow blur steps=5,shadow blur extra rounding=1.3pt}},
+ endpoint/.style={draw,solid,thick,rounded corners,fill=blue!20, blur shadow={shadow blur steps=5,shadow blur extra rounding=1.3pt}},
+ secret/.style={draw,solid,thick,rounded corners,fill=blue!20, blur shadow={shadow blur steps=5,shadow blur extra rounding=1.3pt}},
+ pvc/.style={draw,solid,thick,rounded corners,fill=blue!20, inner sep=.3cm, blur shadow={shadow blur steps=5,shadow blur extra rounding=1.3pt}},
+ label/.style={rectangle,inner sep=0,outer sep=0},
+ to/.style={->,>=stealth',shorten >=1pt,semithick,font=\sffamily\footnotesize},
+ every node/.style={align=center}]
+
+ % Position the nodes using a matrix layout
+
+ \matrix{
+ \& \node[component] (crd) {CRD}; \\
+ \& \node[operator] (operator) {Operator}; \\
+ \path
+ node[service] (service-master) {Master}
+ node[label, right of=service-master] (service-middle) {}
+ node[label, below of=service-middle] (services-label) {Services}
+ node[service, right=.5cm of service-master] (service-replica) {Replica}
+ node[border, behind path,
+ fit=(service-master)(service-replica)(services-label)
+ ] (services) {};
+ \&
+ \node[component] (sts) {Statefulset}; \& \node[component] (pdb) {Pod Disruption Budget}; \\
+ \path
+ node[service] (master-endpoint) {Master}
+ node[service, right=.5cm of master-endpoint] (replica-endpoint) {Replica}
+ node[label, right of=master-endpoint] (endpoint-middle) {}
+ node[label, below of=endpoint-middle] (endpoint-label) {Endpoints}
+ node[border, behind path,
+ fit=(master-endpoint)(replica-endpoint)(endpoint-label)
+ ] (endpoints) {}; \&
+ \node[component] (pod-template) {Pod Template}; \&
+ \node[border] (secrets) {
+ \begin{tikzpicture}[]
+ \node[secret] (users-secret) at (0, 0) {Users};
+ \node[secret] (robots-secret) at (2, 0) {Robots};
+ \node[secret] (standby-secret) at (4, 0) {Standby};
+ \end{tikzpicture} \\
+ Secrets
+ }; \\ \&
+ \path
+ node[pod] (replica1-pod) {Replica}
+ node[pod, left=.5cm of replica1-pod] (master-pod) {Master}
+ node[pod, right=.5cm of replica1-pod] (replica2-pod) {Replica}
+ node[label, below of=replica1-pod] (pod-label) {Pods}
+ node[border, behind path,
+ fit=(master-pod)(replica1-pod)(replica2-pod)(pod-label)
+ ] (pods) {}; \\ \&
+ \path
+ node[pvc] (replica1-pvc) {Replica}
+ node[pvc, left=.5cm of replica1-pvc] (master-pvc) {Master}
+ node[pvc, right=.5cm of replica1-pvc] (replica2-pvc) {Replica}
+ node[label, below of=replica1-pvc] (pvc-label) {Persistent Volume Claims}
+ node[border, behind path,
+ fit=(master-pvc)(replica1-pvc)(replica2-pvc)(pvc-label)
+ ] (pvcs) {}; \&
+ \\ \& \\
+ };
+
+ % Draw the arrows between the nodes and label them.
+ \draw[to] (crd) -- node[midway,above] {} node[midway,below] {} (operator);
+ \draw[to] (operator) -- node[midway,above] {} node[midway,below] {} (sts);
+ \draw[to] (operator) -- node[midway,above] {} node[midway,below] {} (secrets);
+ \draw[to] (operator) -| node[midway,above] {} node[midway,below] {} (pdb);
+ \draw[to] (service-master) -- node[midway,above] {} node[midway,below] {} (master-endpoint);
+ \draw[to] (service-replica) -- node[midway,above] {} node[midway,below] {} (replica-endpoint);
+ \draw[to] (master-pod) -- node[midway,above] {} node[midway,below] {} (master-pvc);
+ \draw[to] (replica1-pod) -- node[midway,above] {} node[midway,below] {} (replica1-pvc);
+ \draw[to] (replica2-pod) -- node[midway,above] {} node[midway,below] {} (replica2-pvc);
+ \draw[to] (operator) -| node[midway,above] {} node[midway,below] {} (services);
+ \draw[to] (sts) -- node[midway,above] {} node[midway,below] {} (pod-template);
+ \draw[to] (pod-template) -- node[midway,above] {} node[midway,below] {} (pods);
+\end{tikzpicture}
+\end{center}
+\end{document}
diff --git a/docs/diagrams/pod.png b/docs/diagrams/pod.png
new file mode 100644
index 0000000000000000000000000000000000000000..f54d1a2bdd684fd3c77242ca332e6278ea35ca1e
Binary files /dev/null and b/docs/diagrams/pod.png differ
diff --git a/docs/diagrams/pod.tex b/docs/diagrams/pod.tex
new file mode 100644
index 0000000000000000000000000000000000000000..f4451399a5cd7cfa4f6df4f9f621213a551740ba
--- /dev/null
+++ b/docs/diagrams/pod.tex
@@ -0,0 +1,92 @@
+\documentclass{article}
+\usepackage{tikz}
+\usepackage[graphics,tightpage,active]{preview}
+\usetikzlibrary{arrows, shadows.blur, positioning, fit, calc, backgrounds}
+\usepackage{lscape}
+
+\pagenumbering{gobble}
+
+\PreviewEnvironment{tikzpicture}
+\PreviewEnvironment{equation}
+\PreviewEnvironment{equation*}
+\newlength{\imagewidth}
+\newlength{\imagescale}
+\pagestyle{empty}
+\thispagestyle{empty}
+
+\begin{document}
+\begin{center}
+\begin{tikzpicture}[
+ scale=0.5,transform shape,
+ font=\sffamily,
+ every matrix/.style={ampersand replacement=\&,column sep=2cm,row sep=2cm},
+ pod/.style={draw,solid,thick,circle,fill=red!20,inner sep=.3cm, blur shadow={shadow blur steps=5,shadow blur extra rounding=1.3pt}},
+ component/.style={draw,solid,thick,rounded corners,fill=yellow!20,inner sep=.3cm, blur shadow={shadow blur steps=5,shadow blur extra rounding=1.3pt}},
+ border/.style={draw,dashed,rounded corners,fill=gray!20,inner sep=.3cm, blur shadow={shadow blur steps=5,shadow blur extra rounding=1.3pt}},
+ volume/.style={draw,solid,thick,rounded corners,fill=blue!20, inner sep=.3cm, blur shadow={shadow blur steps=5,shadow blur extra rounding=1.3pt}},
+ sidecar/.style={draw,solid,thick,rounded corners,fill=blue!20, inner sep=.3cm, blur shadow={shadow blur steps=5,shadow blur extra rounding=1.3pt}},
+ k8s-label/.style={draw,solid,thick,rounded corners,fill=blue!20, minimum width=1.5cm, inner sep=.3cm, blur shadow={shadow blur steps=5,shadow blur extra rounding=1.3pt}},
+ affinity/.style={draw,solid,thick,rounded corners,fill=blue!20, minimum width=2cm, inner sep=.3cm, blur shadow={shadow blur steps=5,shadow blur extra rounding=1.3pt}},
+ label/.style={rectangle,inner sep=0,outer sep=0},
+ to/.style={->,>=stealth',shorten >=1pt,semithick,font=\sffamily\footnotesize},
+ every node/.style={align=center}]
+
+ % Position the nodes using a matrix layout
+
+ \matrix{
+ \path
+ node[k8s-label] (app-label) {App}
+ node[k8s-label, right=.25cm of app-label] (role-label) {Role}
+ node[k8s-label, right=.25cm of role-label] (custom-label) {Custom}
+ node[label, below of=role-label] (k8s-label-label) {K8S Labels}
+ node[border, behind path,
+ fit=(app-label)(role-label)(custom-label)(k8s-label-label)
+ ] (k8s-labels) {}; \& \&
+ \path
+ node[affinity] (affinity) {Affinity}
+ node[label, right=.25cm of affinity] (affinity-middle) {}
+ node[affinity, right=.25cm of affinity-middle] (anti-affinity) {Anti-affinity}
+ node[label, below of=affinity-middle] (affinity-label) {Assigning to nodes}
+ node[border, behind path,
+ fit=(affinity)(anti-affinity)(affinity-label)
+ ] (affinity) {}; \\
+ \& \node[pod] (pod) {Pod}; \& \\
+ \path
+ node[volume, minimum width={width("shm-volume")}] (data-volume) {Data}
+ node[volume, right=.25cm of data-volume, minimum width={width("shm-volume")}] (tokens-volume) {Tokens}
+ node[volume, right=.25cm of tokens-volume] (shm-volume) {/dev/shm}
+ node[label, below of=tokens-volume] (volumes-label) {Volumes}
+ node[border, behind path,
+ fit=(data-volume)(shm-volume)(tokens-volume)(volumes-label)
+ ] (volumes) {}; \&
+ \node[component] (spilo) {Spilo}; \&
+ \node[sidecar] (scalyr) {Scalyr}; \& \\ \&
+ \path
+ node[component] (patroni) {Patroni}
+ node[component, below=.25cm of patroni] (postgres) {PostgreSQL}
+ node[border, behind path,
+ fit=(postgres)(patroni)
+ ] (spilo-components) {}; \&
+ \path
+ node[sidecar] (custom-sidecar1) {User defined}
+ node[label, right=.25cm of custom-sidecar1] (sidecars-middle) {}
+ node[sidecar, right=.25cm of sidecars-middle] (custom-sidecar2) {User defined}
+ node[label, below of=sidecars-middle] (sidecars-label) {Custom sidecars}
+ node[border, behind path,
+ fit=(custom-sidecar1)(custom-sidecar2)(sidecars-label)
+ ] (sidecars) {};
+ \\ \& \\
+ };
+
+ % Draw the arrows between the nodes and label them.
+ \draw[to] (pod) to [bend left=25] (volumes);
+ \draw[to] (pod) to [bend left=25] (k8s-labels);
+ \draw[to] (pod) to [bend right=25] (affinity);
+ \draw[to] (pod) to [bend right=25] (scalyr);
+ \draw[to] (pod) to [bend right=25] (sidecars);
+ \draw[to] (pod) -- node[midway,above] {} node[midway,below] {} (spilo);
+ \draw[to] (spilo) -- node[midway,above] {} node[midway,below] {} (spilo-components);
+
+\end{tikzpicture}
+\end{center}
+\end{document}