diff options
Diffstat (limited to 'docs/sections/blueprints/PGaaS.rst')
| -rw-r--r-- | docs/sections/blueprints/PGaaS.rst | 106 |
1 files changed, 104 insertions, 2 deletions
diff --git a/docs/sections/blueprints/PGaaS.rst b/docs/sections/blueprints/PGaaS.rst index 39d309f1..47e234e0 100644 --- a/docs/sections/blueprints/PGaaS.rst +++ b/docs/sections/blueprints/PGaaS.rst @@ -23,9 +23,12 @@ lifetime. When the application is undeployed, the associated database should be deployed too. OR, the database should have a lifetime beyond the scope of the applications that are writing to it or reading from it. -The Blueprints for PG Services and Cinder +Blueprint Files ------------ +The Blueprints for PG Services and Cinder +^^^^^^^^^^^ + The all-in-one blueprint PGaaS.yaml assumes that the PG servers and Cinder volumes can be allocated and deallocated together. This PGaaS.yaml blueprint creates a cluster named "pstg" by default. @@ -35,7 +38,7 @@ PGaaS-disk.yaml, and then use PGaaS-cluster.yaml to create the cluster. The PG c redeployed without affecting the data on the Cinder volumes. The Blueprints for Databases ------------- +^^^^^^^^^^^ The PGaaS-database.yaml blueprint shows how a database can be created separately from any application that uses it. That database will remain present until the PGaaS-database.yaml blueprint is @@ -45,3 +48,102 @@ needed to access a given database on a given PostgreSQL cluster. If the lifetime of your database is tied to the lifetime of your application, use a block similar to what is in PGaaS-database.yaml to allocate the database, and use the attributes as shown in PGaaS-getdbinfo.yaml to access the credentials. + + +What is Created by the Blueprints +^^^^^^^^^^^^ + +Each PostgreSQL cluster has a name, represented below as ``${CLUSTER}`` or ``CLNAME``. Each cluster is created +with two VMs, one VM used for the writable master and the other as a cascaded read-only secondary. + + +There are two DNS A records added, ``${LOCATIONPREFIX}${CLUSTER}00.${LOCATIONDOMAIN}`` and +``${LOCATIONPREFIX}${CLUSTER}01.${LOCATIONDOMAIN}``. In addition, +there are two CNAME entries added: +``${LOCATIONPREFIX}-${CLUSTER}-write.${LOCATIONDOMAIN} `` +and +``${LOCATIONPREFIX}-${CLUSTER}.${LOCATIONDOMAIN}``. The CNAME +``${LOCATIONPREFIX}-${CLUSTER}-write.${LOCATIONDOMAIN}`` will be used by further +blueprints to create and attach to databases. + + +Parameters +------------ + +The blueprints are designed to run using the standard inputs file used for all of the blueprints, +plus several additional parameters that are given reasonable defaults. + +How to Run +------------ + + + +To install the PostgreSQL as a Service +^^^^^^^^^^^^ + +Installing the all-in-one blueprint is straightforward: + +:: + + cfy install -p pgaas.yaml -i inputs.yaml + +By default, the all-in-one blueprint creates a cluster by the name ``pstg``. + +You can override that name using another ``-i`` option. +(When overriding the defaults, it is also best to explicitly +set the -b and -d names.) + +:: + cfy install -p pgaas.yaml -b pgaas-CLNAME -d pgaas-CLNAME -i inputs.yaml -i pgaas_cluster_name=CLNAME + + +Separating out the disk allocation from the service creation requires using two blueprints: + +:: + cfy install -p pgaas-disk.yaml -i inputs.yaml + cfy install -p pgaas-cluster.yaml -i inputs.yaml + +By default, these blueprints create a cluster named ``pgcl``, which can be overridden the same +way as shown above: + +:: + cfy install -p pgaas-disk.yaml -b pgaas-disk-CLNAME -d pgaas-disk-CLNAME -i inputs.yaml -i pgaas_cluster_name=CLNAME + cfy install -p pgaas-cluster.yaml -b pgaas-disk-CLNAME -d pgaas-disk-CLNAME -i inputs.yaml -i pgaas_cluster_name=CLNAME + + +You must use the same pgaas_cluster_name for the two blueprints to work together. + +For the disk, you can also specify a ``cinder_volume_size``, as in ``-i cinder_volume_size=1000`` +for 1TiB volume. (There is no need to override the ``-b`` and ``-d`` names when changing the +volume size.) + + +You can verify that the cluster is up and running by connecting to the PostgreSQL service +on port 5432: + +:: + telnet ${LOCATIONPREFIX}-${CLUSTER}-write.${LOCATIONDOMAIN} 5432 + +Once you have the cluster created, you can then allocate databases. An application that +wants a persistent database not tied to the lifetime of the application blueprint can +use the ``pgaas-database.yaml`` blueprint to create the database; + +:: + cfy install -p pgaas-database.yaml -i inputs.yaml + +By default, the ``pgaas-database.yaml`` blueprint creates a database with the name ``sample``, which +can be overridden using ``database_name``. + + +:: + cfy install -p pgaas-database.yaml -b pgaas-database-DBNAME -d pgaas-database-DBNAME -i inputs.yaml -i database_name=DBNAME + cfy install -p pgaas-database.yaml -b pgaas-database-CLNAME-DBNAME -d pgaas-database-CLNAME-DBNAME -i inputs.yaml -i pgaas_cluster_name=CLNAME -i database_name=DBNAME + + +The ``pgaas-getdbinfo.yaml`` blueprint shows how an application can attach to an existing +database and access its attributes: + +:: + cfy install -p pgaas-getdbinfo.yaml -d pgaas-getdbinfo -b pgaas-getdbinfo -i inputs.yaml + cfy deployments outputs -d pgaas-getdbinfo + cfy uninstall -d pgaas-getdbinfo |