From 07d9dff847ae662418be2e0676f8e230ea60725b Mon Sep 17 00:00:00 2001
From: erthalion <9erthalion6@gmail.com>
Date: Fri, 1 Jun 2018 16:15:42 +0200
Subject: [PATCH 1/6] Add an example of clone feature

---
 docs/user.md | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/docs/user.md b/docs/user.md
index 71ff0901a..5beb4d31e 100644
--- a/docs/user.md
+++ b/docs/user.md
@@ -162,7 +162,7 @@ definitions will be ignored with a prior warning.
 See [infrastructure roles secret](https://github.com/zalando-incubator/postgres-operator/blob/master/manifests/infrastructure-roles.yaml)
 and [infrastructure roles configmap](https://github.com/zalando-incubator/postgres-operator/blob/master/manifests/infrastructure-roles-configmap.yaml) for the examples.
 
-#### Use taints and tolerations for dedicated PostgreSQL nodes
+## Use taints and tolerations for dedicated PostgreSQL nodes
 
 To ensure Postgres pods are running on nodes without any other application
 pods, you can use
@@ -181,3 +181,27 @@ spec:
     operator: Exists
     effect: NoSchedule
 ```
+
+## How to clone an existing PostgreSQL cluster
+
+To spin up a new cluster as a clone of the existing one, you need to provide a
+clone section in the spec:
+
+```
+apiVersion: "acid.zalan.do/v1"
+kind: postgresql
+
+metadata:
+  name: acid-test-cluster
+spec:
+  clone:
+    cluster: "acid-batman"
+    timestamp: "2017-12-19T12:40:33+01:00"
+```
+
+Here `cluster` is a name of a target cluster that is going to be cloned. If
+`timestamp` is not empty, then a new cluster will be cloned from an S3 bucket
+using the latest backup before the `timestamp`. If `timestamp` is empty or
+absent, a new cluster will be cloned from an existing alive cluster using
+pg_basebackup. Note that timezone required for `timestamp` (offset relative to
+UTC, see RFC 3339 section 5.6)

From b82faf66bbb504762fab39e7f677d32a1d68be10 Mon Sep 17 00:00:00 2001
From: erthalion <9erthalion6@gmail.com>
Date: Fri, 1 Jun 2018 16:21:37 +0200
Subject: [PATCH 2/6] Unrelated chaotic good adjustments of snippets

---
 docs/user.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/user.md b/docs/user.md
index 5beb4d31e..144b3b806 100644
--- a/docs/user.md
+++ b/docs/user.md
@@ -34,13 +34,13 @@ spec:
 ## Create a new Spilo cluster
 
 ```bash
-    $ kubectl create -f manifests/minimal-postgres-manifest.yaml
+$ kubectl create -f manifests/minimal-postgres-manifest.yaml
 ```
 
 ## Watch pods being created
 
 ```bash
-    $ kubectl get pods -w --show-labels
+$ kubectl get pods -w --show-labels
 ```
 
 ## Connect to PostgreSQL
@@ -48,10 +48,10 @@ spec:
 We can use the generated secret of the `postgres` robot user to connect to our `acid-minimal-cluster` master running in Minikube:
 
 ```bash
-    $ export PGHOST=db_host
-    $ export PGPORT=db_port
-    $ export PGPASSWORD=$(kubectl get secret postgres.acid-minimal-cluster.credentials -o 'jsonpath={.data.password}' | base64 -d)
-    $ psql -U postgres
+$ export PGHOST=db_host
+$ export PGPORT=db_port
+$ export PGPASSWORD=$(kubectl get secret postgres.acid-minimal-cluster.credentials -o 'jsonpath={.data.password}' | base64 -d)
+$ psql -U postgres
 ```
 
 # Defining database roles in the operator
@@ -169,7 +169,7 @@ pods, you can use
 [taints and tolerations](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)
 and configure the required toleration in the manifest.
 
-```
+```yaml
 apiVersion: "acid.zalan.do/v1"
 kind: postgresql
 metadata:
@@ -187,7 +187,7 @@ spec:
 To spin up a new cluster as a clone of the existing one, you need to provide a
 clone section in the spec:
 
-```
+```yaml
 apiVersion: "acid.zalan.do/v1"
 kind: postgresql
 

From e661ea1ea7094f83ebb2759f9535a61d49f4eed3 Mon Sep 17 00:00:00 2001
From: erthalion <9erthalion6@gmail.com>
Date: Fri, 1 Jun 2018 16:44:57 +0200
Subject: [PATCH 3/6] Mention `uid` field

---
 docs/user.md                              | 23 ++++++++++++++++++-----
 manifests/complete-postgres-manifest.yaml |  1 +
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/docs/user.md b/docs/user.md
index 144b3b806..6f35628d6 100644
--- a/docs/user.md
+++ b/docs/user.md
@@ -195,13 +195,26 @@ metadata:
   name: acid-test-cluster
 spec:
   clone:
+    uid: "efd12e58-5786-11e8-b5a7-06148230260c"
     cluster: "acid-batman"
     timestamp: "2017-12-19T12:40:33+01:00"
 ```
 
 Here `cluster` is a name of a target cluster that is going to be cloned. If
-`timestamp` is not empty, then a new cluster will be cloned from an S3 bucket
-using the latest backup before the `timestamp`. If `timestamp` is empty or
-absent, a new cluster will be cloned from an existing alive cluster using
-pg_basebackup. Note that timezone required for `timestamp` (offset relative to
-UTC, see RFC 3339 section 5.6)
+`timestamp` is not empty, then a new cluster will be cloned from an S3 bucket,
+that was created by operator,
+using the latest backup before the `timestamp`. In this case `uid` field is
+also mandatory - operator will use it to find an S3 bucket. You can find this
+field from metadata of a target cluster:
+
+```yaml
+apiVersion: acid.zalan.do/v1
+kind: postgresql
+metadata:
+  name: acid-test-cluster
+  uid: efd12e58-5786-11e8-b5a7-06148230260c
+```
+
+If `timestamp` is empty or absent, a new cluster will be cloned from an
+existing alive cluster using pg_basebackup. Note that timezone required for
+`timestamp` (offset relative to UTC, see RFC 3339 section 5.6)
diff --git a/manifests/complete-postgres-manifest.yaml b/manifests/complete-postgres-manifest.yaml
index 2f929bc2c..9ac2d1ec5 100644
--- a/manifests/complete-postgres-manifest.yaml
+++ b/manifests/complete-postgres-manifest.yaml
@@ -48,6 +48,7 @@ spec:
   # with a non-empty timestamp, clone from an S3 bucket using the latest backup before the timestamp
   # with an empty/absent timestamp, clone from an existing alive cluster using pg_basebackup
   # clone:
+  #  uid: "efd12e58-5786-11e8-b5a7-06148230260c"
   #  cluster: "acid-batman"
   #  timestamp: "2017-12-19T12:40:33+01:00" # timezone required (offset relative to UTC, see RFC 3339 section 5.6)
   maintenanceWindows:

From 5151b43c82d702cf97656b44791fc172d9b885bc Mon Sep 17 00:00:00 2001
From: erthalion <9erthalion6@gmail.com>
Date: Mon, 4 Jun 2018 13:41:18 +0200
Subject: [PATCH 4/6] Split into two parts and reformulate a bit

---
 docs/user.md | 43 ++++++++++++++++++++++++++++++++-----------
 1 file changed, 32 insertions(+), 11 deletions(-)

diff --git a/docs/user.md b/docs/user.md
index 6f35628d6..108780d56 100644
--- a/docs/user.md
+++ b/docs/user.md
@@ -184,8 +184,31 @@ spec:
 
 ## How to clone an existing PostgreSQL cluster
 
-To spin up a new cluster as a clone of the existing one, you need to provide a
-clone section in the spec:
+You can spin up a new cluster as a clone of the existing one, using a clone
+section in the spec. There are two options here:
+
+* Clone directly from a source cluster using `pg_basebackup`
+
+* Clone from an S3 bucket
+
+### Clone directly
+
+```yaml
+apiVersion: "acid.zalan.do/v1"
+kind: postgresql
+
+metadata:
+  name: acid-test-cluster
+spec:
+  clone:
+    cluster: "acid-batman"
+```
+
+Here `cluster` is a name of a source cluster that is going to be cloned. The
+cluster to clone is assumed to be running and the clone procedure invokes
+`pg_basebackup` from it.
+
+### Clone from S3
 
 ```yaml
 apiVersion: "acid.zalan.do/v1"
@@ -200,12 +223,11 @@ spec:
     timestamp: "2017-12-19T12:40:33+01:00"
 ```
 
-Here `cluster` is a name of a target cluster that is going to be cloned. If
-`timestamp` is not empty, then a new cluster will be cloned from an S3 bucket,
-that was created by operator,
-using the latest backup before the `timestamp`. In this case `uid` field is
-also mandatory - operator will use it to find an S3 bucket. You can find this
-field from metadata of a target cluster:
+Here `cluster` is a name of a source cluster that is going to be cloned. A new
+cluster will be cloned from an S3, using the latest backup before the
+`timestamp`. In this case, `uid` field is also mandatory - operator will use it
+to find a correct key inside an S3 bucket. You can find this field from
+metadata of a source cluster:
 
 ```yaml
 apiVersion: acid.zalan.do/v1
@@ -215,6 +237,5 @@ metadata:
   uid: efd12e58-5786-11e8-b5a7-06148230260c
 ```
 
-If `timestamp` is empty or absent, a new cluster will be cloned from an
-existing alive cluster using pg_basebackup. Note that timezone required for
-`timestamp` (offset relative to UTC, see RFC 3339 section 5.6)
+Note that timezone required for `timestamp` (offset relative to UTC, see RFC
+3339 section 5.6)

From d0e69326415f3b16271f8fb2626e476d679ce293 Mon Sep 17 00:00:00 2001
From: erthalion <9erthalion6@gmail.com>
Date: Mon, 4 Jun 2018 15:36:17 +0200
Subject: [PATCH 5/6] Adjustments for clone section

---
 docs/user.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/docs/user.md b/docs/user.md
index 108780d56..3e5919d29 100644
--- a/docs/user.md
+++ b/docs/user.md
@@ -189,7 +189,7 @@ section in the spec. There are two options here:
 
 * Clone directly from a source cluster using `pg_basebackup`
 
-* Clone from an S3 bucket
+* Clone from S3 bucket
 
 ### Clone directly
 
@@ -206,7 +206,10 @@ spec:
 
 Here `cluster` is a name of a source cluster that is going to be cloned. The
 cluster to clone is assumed to be running and the clone procedure invokes
-`pg_basebackup` from it.
+`pg_basebackup` from it. The operator will connect to the service by name (if
+the cluster is called test, then the connection string will look like host=test
+port=5432), which means that you can clone only from clusters running in the
+default namespace.
 
 ### Clone from S3
 
@@ -224,7 +227,7 @@ spec:
 ```
 
 Here `cluster` is a name of a source cluster that is going to be cloned. A new
-cluster will be cloned from an S3, using the latest backup before the
+cluster will be cloned from S3, using the latest backup before the
 `timestamp`. In this case, `uid` field is also mandatory - operator will use it
 to find a correct key inside an S3 bucket. You can find this field from
 metadata of a source cluster:

From 2a05179f63cff8268987e5266f10009cb05b79b5 Mon Sep 17 00:00:00 2001
From: erthalion <9erthalion6@gmail.com>
Date: Mon, 4 Jun 2018 16:17:48 +0200
Subject: [PATCH 6/6] Adjust article for title

---
 docs/user.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/user.md b/docs/user.md
index 3e5919d29..d0ebcc1b0 100644
--- a/docs/user.md
+++ b/docs/user.md
@@ -189,7 +189,7 @@ section in the spec. There are two options here:
 
 * Clone directly from a source cluster using `pg_basebackup`
 
-* Clone from S3 bucket
+* Clone from an S3 bucket
 
 ### Clone directly