Change to user/admin/developer

docs/user.md

@@ -0,0 +1,183 @@
+# How to create a new db cluster
+
+## Create a manifest for a new db cluster
+
+As an example you can take this
+[minimal example](manifests/minimal-postgres-manifest.yaml):
+
+```yaml
+apiVersion: "acid.zalan.do/v1"
+kind: postgresql
+metadata:
+  name: acid-minimal-cluster
+spec:
+  teamId: "ACID"
+  volume:
+    size: 1Gi
+  numberOfInstances: 2
+  users:
+    # database owner
+    zalando:
+    - superuser
+    - createdb
+
+    # role for application foo
+    foo_user:
+
+  #databases: name->owner
+  databases:
+    foo: zalando
+  postgresql:
+    version: "10"
+```
+
+## Create a new Spilo cluster
+
+```bash
+    $ kubectl create -f manifests/minimal-postgres-manifest.yaml
+```
+
+## Watch pods being created
+
+```bash
+    $ kubectl get pods -w --show-labels
+```
+
+## Connect to PostgreSQL
+
+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
+```
+
+# Defining database roles in the operator
+
+Postgres operator allows defining roles to be created in the resulting database
+cluster. It covers three use-cases:
+
+* create application roles specific to the cluster described in the manifest:
+  `manifest roles`.
+* create application roles that should be automatically created on every
+  cluster managed by the operator: `infrastructure roles`.
+* automatically create users for every member of the team owning the database
+  cluster: `teams API roles`.
+
+In the next sections, we will cover those use cases in more details.
+
+## Manifest roles
+
+Manifest roles are defined directly in the cluster manifest. See
+[minimal postgres manifest](https://github.com/zalando-incubator/postgres-operator/blob/master/manifests/minimal-postgres-manifest.yaml)
+for an example of `zalando` role, defined with `superuser` and `createdb`
+flags.
+
+Manifest roles are defined as a dictionary, with a role name as a key and a
+list of role options as a value. For a role without any options supply an empty
+list.
+
+The operator accepts the following options:  `superuser`, `inherit`, `login`,
+`nologin`, `createrole`, `createdb`, `replication`, `bypassrls`.
+
+By default, manifest roles are login roles (aka users), unless `nologin` is
+specified explicitly.
+
+The operator automatically generates a password for each manifest role and
+places it in the secret named
+`{username}.{team}-{clustername}.credentials.postgresql.acid.zalan.do` in the
+same namespace as the cluster. This way, the application running in the
+Kubernetes cluster and working with the database can obtain the password right
+from the secret, without ever sharing it outside of the cluster.
+
+At the moment it is not possible to define membership of the manifest role in
+other roles.
+
+## Infrastructure roles
+
+An infrastructure role is a role that should be present on every PostgreSQL
+cluster managed by the operator. An example of such a role is a monitoring
+user. There are two ways to define them:
+
+* Exclusively via the infrastructure roles secret (specified by the
+  `infrastructure_roles_secret_name` parameter).
+
+The role definition looks like this (values are base64 encoded):
+
+```yaml
+    user1: ZGJ1c2Vy
+    password1: c2VjcmV0
+    inrole1: b3BlcmF0b3I=
+```
+
+A block above describes the infrastructure role 'dbuser' with the password
+'secret' that is the member of the 'operator' role. For the following
+definitions one must increase the index, i.e. the next role will be defined as
+'user2' and so on. Note that there is no way to specify role options (like
+superuser or nologin) this way, and the resulting role will automatically be a
+login role.
+
+*  Via both the infrastructure roles secret and the infrastructure role
+   configmap (with the same name as the infrastructure roles secret).
+
+The infrastructure roles secret should contain an entry with 'rolename:
+rolepassword' for each role, and the role description should be specified in
+the configmap. Below is the example:
+
+```yaml
+    dbuser: c2VjcmV0
+```
+
+and the configmap definition for that user:
+
+```yaml
+    data:
+      dbuser: |
+        inrole: [operator, admin]  # following roles will be assigned to the new user
+        user_flags:
+          - createdb
+        db_parameters:  # db parameters, applied for this particular user
+          log_statement: all
+```
+
+Note that the definition above allows for more details than the one that relies
+solely on the infrastructure role secret. In particular, one can allow
+membership in multiple roles via the `inrole` array parameter, define role
+flags via the `user_flags` list and supply per-role options through the
+`db_parameters` dictionary. All those parameters are optional.
+
+The definitions that solely use the infrastructure roles secret are more
+limited and considered legacy ones; one should use the new style that specifies
+infrastructure roles using both the secret and the configmap. You can mix both
+in the infrastructure role secret, as long as your new-style definition can be
+clearly distinguished from the old-style one (for instance, do not name
+new-style roles`userN`).
+
+Since an infrastructure role is created uniformly on all clusters managed by
+the operator, it makes no sense to define it without the password. Such
+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
+
+To ensure Postgres pods are running on nodes without any other application
+pods, you can use
+[taints and tolerations](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)
+and configure the required toleration in the manifest.
+
+```
+apiVersion: "acid.zalan.do/v1"
+kind: postgresql
+metadata:
+  name: acid-minimal-cluster
+spec:
+  teamId: "ACID"
+  tolerations:
+  - key: postgres
+    operator: Exists
+    effect: NoSchedule
+```