Merge pull request #120 from xenophenes/master

jmccormick2001 · web-flow · commit 4e63d517e5a0 · 2018-02-28T17:04:09.000-06:00
misc. minor documentation changes
diff --git a/docs/operator-docs.asciidoc b/docs/operator-docs.asciidoc
@@ -1,4 +1,4 @@
-= PostgreSQL Operator Documentation 
+= PostgreSQL Operator Documentation
 :toc:
 v2.5, {docdate}
 
@@ -14,14 +14,14 @@ from source, you can download them from the following:
 Further details can be found in the link:design.asciidoc[PostgreSQL Operator Design] document on
 how the operator is built and how it operates.
 
-For most users of the Operator who simply want to deploy 
-it on a running Kube cluster will find the Quickstart
-script useful https://github.com/CrunchyData/postgres-operator/blob/master/examples/quickstart.sh
+For most users of the Operator who simply want to deploy
+it on a running Kubernetes cluster will find the link:https://github.com/CrunchyData/postgres-operator/blob/master/examples/quickstart.sh[Quickstart]
+script useful.
 
 Executing that script will deploy the Operator to your Kube
 cluster and also set up your local user environment with the
 *pgo* client in about 10 seconds.  More details on the Quickstart
-is at the end of this document <<Quickstart>>.
+script is located in the <<Quickstart>> section in this document.
 
 
 == Requirements
@@ -35,7 +35,7 @@ these versions.
 * *OpenShift Origin 1.7.0+*
 
 The operator is developed with the Golang versions great than or equal to version 1.8  See
-link:https://golang.org/dl/[Golang website] for details on installing golang. 
+link:https://golang.org/dl/[Golang website] for details on installing golang.
 
 Pre-compiled versions of the Operator *pgo* client are provided for the x86_64, Mac OSX, and Windows hosts.
 
@@ -88,6 +88,13 @@ export PGO_CLIENT_CERT=$COROOT/conf/apiserver/server.crt
 export PGO_CLIENT_KEY=$COROOT/conf/apiserver/server.key
 ....
 
+It will be necessary to refresh your .bashrc file in order for the changes to take
+effect.
+
+....
+source ~/.bashrc
+....
+
 The value of CO_IMAGE_PREFIX is used to prefix the Operator
 Docker images.  For example, set this environment variable
 to where you have your Operator images loaded either locally (crunchydata)
@@ -155,7 +162,7 @@ tar xvzf ./postgres-operator.2.5.tar.gz
 
 Lastly, add the *pgo* client into your PATH.
 
-You are now ready to Deploy the operator to your Kube system.
+You are now ready to Deploy the operator to your Kubernetes system.
 
 === Build from Source
 
@@ -195,7 +202,7 @@ kubectl config use-context demo
 kubectl config current-context
 ....
 
-Permissions are granted to the Operator by means of a 
+Permissions are granted to the Operator by means of a
 Service Account called *postgres-operator*.  That service
 account is added to the Operator deployment.
 
@@ -233,14 +240,14 @@ To run the Operator on Openshift Container Platform note the following:
 === Configure Persistent Storage
 
 The default Operator configuration is defined to use a HostPath
-persistence configuration.  
+persistence configuration.
 
 There are example scripts provided that will create PV and PVC resources
-that can be used in your testing. 
+that can be used in your testing.
 
-These example scripts can create sample HostPath and NFS volumes. 
+These example scripts can create sample HostPath and NFS volumes.
 
-To create sample HostPath Persistent Volumes and CLaims use the following scripts:
+To create sample HostPath Persistent Volumes and Claims use the following scripts:
 ....
 cd $COROOT/pv
 ./create-pv.sh
@@ -274,7 +281,7 @@ username:password
 testuser:testpass
 ....
 
-Modify these values to be unique to your environment.  
+Modify these values to be unique to your environment.
 
 If the username and password passed by clients to the *apiserver* do
 not match, the REST call will fail and a log message will be produced
@@ -332,16 +339,17 @@ this value is set to *false* if you do not specify a value.
 PostgreSQL passwords are defined in Secrets starting with release
 2.5.  When the *pgo-apiserver* starts, it will read the passwords
 to be used for PostgresSQL clusters from the following Kube Secrets:
+
  * pgo-postgres-user-pass
  * pgo-primary-user-pass
  * pgo-testuser-user-pass
 
 The defaults for these Secrets are set in the *create-secrets.sh* script
-which is executed during the postgres-operator deployment. 
+which is executed during the postgres-operator deployment.
 
 === Configuration
 
-The *apiserver* uses the following  configuration files found in $COROOT/conf/apiserver to determine how the Operator will provision PostgreSQL containers:
+The *apiserver* uses the following configuration files found in $COROOT/conf/apiserver to determine how the Operator will provision PostgreSQL containers:
 ....
 $COROOT/conf/apiserver/pgo.yaml
 $COROOT/conf/apiserver/pgo.lspvc-template.json
@@ -351,11 +359,8 @@ $COROOT/conf/apiserver/pgo.load-template.json
 Note that the default *pgo.yaml* file assumes you are going to use *HostPath* Persistent Volumes for
 your storage configuration.  Adjust this file for NFS or other storage configurations.
 
-Note that the *pgo.yaml* configuration file assumes your Kubernetes configuration file is located in */etc/kubernetes/admin.conf*.  Update this kubeconfig
-path to match your local Kubernetes configuration file location. 
-
 The version of PostgreSQL container the Operator will deploy is determined
-by the *CCPImageTag* setting in the *$COROOT/conf/apiserver/pgo.yaml* 
+by the *CCPImageTag* setting in the *$COROOT/conf/apiserver/pgo.yaml*
 configuration file.  By default, this value is set to the latest
 release of the Crunchy Container Suite.
 
@@ -402,9 +407,9 @@ Strategies for deploying the operator can be found in the link:design.asciidoc[P
 
 === Verify Installation
 
-When you first run the operator, it will look for the presence of the 
-predefined custom resource definitions, and create them if not found. 
-The best way to verify a successful deployment of the Operator is by 
+When you first run the operator, it will look for the presence of the
+predefined custom resource definitions, and create them if not found.
+The best way to verify a successful deployment of the Operator is by
 viewing these custom resource definitions:
 
 ....
@@ -425,7 +430,7 @@ name of the *postgres-operator* service or to the IP address of the
 export CO_APISERVER_URL=https://10.105.56.167:8443
 ....
 
-or if you have DNS configured on your client host:
+Or if you have DNS configured on your client host:
 ....
 export CO_APISERVER_URL=https://postgres-operator.demo.svc.cluster.local:8443
 ....
@@ -478,10 +483,10 @@ The following table describes the Makefile targets:
 |all        | compile all binaries and build all images
 |setup        | fetch the dependent packages required to build with
 |deployoperator        | deploy the Operator (apiserver and postgers-operator) to Kubernetes
-|main        | compile the postgres-operator 
+|main        | compile the postgres-operator
 |runmain        | locally execute the postgres-operator
 |pgo        | build the pgo binary
-|runpgo        | run the pgo binary 
+|runpgo        | run the pgo binary
 |runapiserver        | run the apiserver binary outside of Kube
 |clean        | remove binaries and compiled packages, restore dependencies
 |operatorimage        | compile and build the postgres-operator Docker image
@@ -566,9 +571,9 @@ Values in the pgo configuration file have the following meaning:
 |Cluster.Strategy        | sets the deployment strategy to be used for deploying a cluster, currently there is only strategy *1*
 |Cluster.Replicas        | the number of cluster replicas to create for newly created clusters
 |Cluster.Policies        | optional, list of policies to apply to a newly created cluster, comma separated, must be valid policies in the catalog
-|Cluster.PasswordAgeDays        | optional, if set, will set the VALID UNTIL date on passwords to this many days in the future when creating users or setting passwords, defaults to 365 days
+|Cluster.PasswordAgeDays        | optional, if set, will set the VALID UNTIL date on passwords to this many days in the future when creating users or setting passwords, defaults to 60 days
 |Cluster.PasswordLength        | optional, if set, will determine the password length used when creating passwords, defaults to 8
-|PrimaryStorage    |required, the value of the storage configuration to use for the primary PostgreSQL deployment 
+|PrimaryStorage    |required, the value of the storage configuration to use for the primary PostgreSQL deployment
 |BackupStorage    |required, the value of the storage configuration to use for backups
 |ReplicaStorage    |required, the value of the storage configuration to use for the replica PostgreSQL deployments
 |Storage.storage1.StorageClass        |for a dynamic storage type, you can specify the storage class used for storage provisioning(e.g. standard, gold, fast)
@@ -626,22 +631,22 @@ pgo create cluster testcluster2 --storage-config=fastdisk --replica-storage-conf
 
 That example will create a cluster and specify a storage configuration
 of *fastdisk* to be used for the primary database storage, the replica
-storage will use the storage configuration *slowdisk*.  
+storage will use the storage configuration *slowdisk*.
 
 ....
 pgo backup testcluster --storage-config=offsitestorage
 ....
 
-That example will create a backup and use the *offsitestorage* 
+That example will create a backup and use the *offsitestorage*
 storage configuration for persisting the backup.
 
 === Disaster Recovery Using Storage Configurations
 
 A simple support for disaster recovery can be obtained
-by leveraging network storage, Kube storage classes, and
+by leveraging network storage, Kubernetes storage classes, and
 the storage configuration options within the Operator.
 
-For example, if you define a Kube storage class that refers
+For example, if you define a Kubernetes storage class that refers
 to a storage backend that is running within your disaster recovery
 site, and then use that storage class as a storage configuration
 for your backups, you essentially have moved your backup files
@@ -765,6 +770,20 @@ database using the service IP address:
 psql -h 10.105.121.12 -U postgres postgres
 ....
 
+More details are available on user management below, however, you may wish to take note
+that user credentials are created in the file $COROOT/deploy/create-secrets.sh upon
+deployment of the Operator. The following user accounts and passwords are created by
+default for connecting to the PostgreSQL clusters:
+
+*username*: postgres
+*password*: password
+
+*username*: primaryuser
+*password*: password
+
+*username*: testuser
+*password*: password
+
 You can view *all* databases using the special keyword *all*:
 ....
 pgo show cluster all
@@ -806,28 +825,16 @@ You can view the backup:
 pgo show backup mycluster
 ....
 
-You can view the backup along with a PVC listing:
-....
-pgo show backup mycluster --show-pvc=true
-....
+View the PVC folder and the backups contained therein:
 
-The output of the backup will list the backup snapshots
-found in the backup PVC, for example:
 ....
-backup job pods for cluster mycluster...
-└── backup-mycluster-63fw1
-└── mydatabase
-
-database pod mycluster is found
-
-├── mycluster-backups/2017-03-27-13-54-33
-├── mycluster-backups/2017-03-27-13-56-49
-└── mycluster-backups/2017-03-27-14-02-38
+pgo show pvc mycluster-backup-pvc
+pgo show pvc mycluster-backup-pvc --pvc-root=mycluster-backups
 ....
 
-This output is important in that it can let you copy/paste
-a backup snapshot path and use it for restoring a database or
-essentially cloning a database with an existing backup archive.
+The output from this command is important in that it can let you
+copy/paste a backup snapshot path and use it for restoring a database
+or essentially cloning a database with an existing backup archive.
 
 For example, to restore a database from a backup archive:
 ....
@@ -861,15 +868,15 @@ pgo delete cluster restoredb
 ....
 
 Note, that this command will not remove the PVC associated with
-this cluster. 
+this cluster.
 
 Selectors also apply to the delete command as follows:
 ....
 pgo delete cluster  --selector=project=xray
 ....
 
 This command will cause any cluster matching the selector
-to be removed. 
+to be removed.
 
 You can remove a cluster and it's data files by running:
 ....
@@ -897,13 +904,13 @@ Deployment is set to a replica count of 1, it can not scale beyond 1.
 The replica Deployment is set to an initial value of 0, you will
 see there are 0 replica databases running.  Those replica databases
 are in read-only mode, but you can scale up the number of replicas
-beyond 0 if you need higher read scaling.  To set the number of 
+beyond 0 if you need higher read scaling.  To set the number of
 replicas issue the following command:
 ....
 pgo scale mycluster --replica-count=1
 ....
 
-There are 2 service connections available to the postgres cluster, one is
+There are 2 service connections available to the PostgreSQL cluster. One is
 to the master database which allows read-write SQL processing, and
 the other is to the set of read-only replica databases.  The replica
 service performs round-robin load balancing to the replica databases.
@@ -954,7 +961,7 @@ container image specified in your pgo configuration file.
 
 The database data files are converted to the new major Postgres
 version as specified by the current Postgres image version
-in your pgo configuration file.  
+in your pgo configuration file.
 
 In this scenario, the upgrade is performed by the Postgres
 pg_upgrade utility which is containerized in the *crunchydata/crunchy-upgrade*
@@ -1034,16 +1041,16 @@ pgo create policy policy1 --url=https://someurl/policy1.sql
 
 When you execute this command, it will create a policy named *policy1*
 using the input file */tmp/policy1.sql* as input.  It will create
-on the server a PgPolicy CRD with the name *policy1* that you can 
+on the server a PgPolicy CRD with the name *policy1* that you can
 examine as follows:
 
 ....
 kubectl get pgpolicies policy1 -o json
 ....
 
-Policies get automatically applied to any cluster you create if 
+Policies get automatically applied to any cluster you create if
 you define in your *pgo.yaml* configuration a CLUSTER.POLICIES
-value.  Policy SQL is executed as the *postgres* user.  
+value.  Policy SQL is executed as the *postgres* user.
 
 To view policies:
 ....
@@ -1087,7 +1094,7 @@ pgo user --delete-user=sally --selector=name=mycluster
 
 To delete that user in all clusters:
 ....
-pgo user --delete-user=sally 
+pgo user --delete-user=sally
 ....
 
 To change the password for a user in the *mycluster* cluster:
@@ -1169,7 +1176,7 @@ The loading is based on a load definition found in the *sample-load-config.json*
 If you include the *--policies* flag, any specified policies will be applied prior to the data being loaded.  For
 example:
 ....
-pgo load --policies="rlspolicy,xrayapp" --load-config=$COROOT/examples/sample-load-config.json --selector=name=mycluster 
+pgo load --policies="rlspolicy,xrayapp" --load-config=$COROOT/examples/sample-load-config.json --selector=name=mycluster
 ....
 
 Likewise you can load a sample json file into a database as follows:
@@ -1197,15 +1204,16 @@ The load configuration file has the following YAML attributes:
 == bash Completion
 
 There is a bash completion file that is included for users to try, this
-is located in the repo at *example/pgo-bash-completion*.  To use it, copy
-that file to /etc/bash_completion.d/pgo, and log out and back into your
-bash shell to try it out.   
-
+is located in the repository at *example/pgo-bash-completion*. To use it:
+....
+cp $COROOT/example/pgo-bash-completion /etc/bash_completion.d/pgo
+su - $USER
+....
 
 == Quickstart
 
-The *quickstart.sh* script will allow users to set up a Postgres Operator quickly.
-This script is tested on GKE but can be used for other Kube environments as
+The *quickstart.sh* script will allow users to set up the Postgres Operator quickly.
+This script is tested on GKE but can be modified for use with other Kubernetes environments as
 well.
 
 The script requires a few things in order to work:
@@ -1214,7 +1222,7 @@ The script requires a few things in order to work:
  * kubectl utility installed
 
 Executing the script will give you a default Operator deployment
-that assumes *dynamic* storage and a storage class named *standard*, 
+that assumes *dynamic* storage and a storage class named *standard*,
 things that GKE provides.
 
 The script performs the following:
@@ -1225,5 +1233,5 @@ The script performs the following:
  * sets your .bashrc to include the Operator environment variables
  * sets your $HOME/.bash_completion file to be the *pgo* bash_completion file
 
-Our plans are to provide other more customized versions of the Quickstart script
+Our plans are to provide other customized versions of the Quickstart script
 over time, as well as support Mac and Windows versions of the script.
