EDB Postgres Containers and Integration with OpenShift. Version 1.0

Transcription

1 EDB Postgres Containers and Integration with OpenShift Version 1.0 November 21, 2017

2 EDB Postgres Containers and Integration with OpenShift, Version 1.0 by EnterpriseDB Corporation Copyright 2017 EnterpriseDB Corporation. All rights reserved. EnterpriseDB Corporation, 34 Crosby Drive, Suite 100, Bedford, MA 01730, USA T F E info@enterprisedb.com Copyright 2017 EnterpriseDB Corporation. All rights reserved. 2

3 Table of Contents 1 Introduction Typographical Conventions Used in this Guide Installing an Advanced Server Container Deployment Creating a Project Creating an OpenShift Project Configuring Volume Resources for the Container Creating a Project Template Removing a Project Retaining a Project with No Pods Using the OpenShift Console Scaling an Advanced Server Deployment Connecting with the psql Client File Locations Creating a Custom Configuration within a Pod Performing a Rolling Update Managing a Container at the Command Line Creating a Container at the Docker Command Line Using Docker to Connect to an Advanced Server Container Managing an Advanced Server Container at the Atomic Command Line Using the Atomic Command Line to Stop or Uninstall a Container Supported LABELS - Reference Copyright 2017 EnterpriseDB Corporation. All rights reserved.

4 1 Introduction EDB Postgres Platform for Containers allows you to use a Docker-formatted container to deploy and manage EDB Postgres Advanced Server (Advanced Server) in a Red Hat OpenShift environment. OpenShift automation provides an environment in which you can easily: Deploy or disable Advanced Server instances as needed. Automatically scale an Advanced Server instance to meet application requirements. Easily ensure Failover Manager protection for your data. Utilize load balancing to distribute read/write requests across available servers. Manage Advanced Server instances with custom configurations in a container environment. The EDB Postgres Platform for Containers automates the deployment of containers that include Advanced Server and the following supporting components: EDB Failover Manager pgpool (connection pooling for Postgres databases) The EDB Postgres Platform for Containers also automates the deployment of Docker containers that install the EDB Postgres Backup and Recovery Tool (BART). BART provides simplified backup and recovery management for Advanced Server. For detailed information and documentation for each component, please visit the EnterpriseDB website at: Copyright 2017 EnterpriseDB Corporation. All rights reserved. 2

5 1.1 Typographical Conventions Used in this Guide Certain typographical conventions are used in this manual to clarify the meaning and usage of various commands, statements, programs, examples, etc. This section provides a summary of these conventions. In the following descriptions a term refers to any word or group of words that are language keywords, user-supplied values, literals, etc. A term s exact meaning depends upon the context in which it is used. Italic font introduces a new term, typically, in the sentence that defines it for the first time. Fixed-width (mono-spaced) font is used for terms that must be given literally such as SQL commands, specific table and column names used in the examples, programming language keywords, etc. For example, SELECT * FROM emp; Italic fixed-width font is used for terms for which the user must substitute values in actual usage. For example, DELETE FROM table_name; A vertical pipe denotes a choice between the terms on either side of the pipe. A vertical pipe is used to separate two or more alternative terms within square brackets (optional choices) or braces (one mandatory choice). Square brackets [ ] denote that one or none of the enclosed term(s) may be substituted. For example, [ a b ], means choose one of a or b or neither of the two. Braces {} denote that exactly one of the enclosed alternatives must be specified. For example, { a b }, means exactly one of a or b must be specified. Ellipses... denote that the proceeding term may be repeated. For example, [ a b ]... means that you may have the sequence, b a a b a. Copyright 2017 EnterpriseDB Corporation. All rights reserved. 3

6 2 Installing an Advanced Server Container Deployment Advanced Server containers are supported on OpenShift Origin version 3.0 or later. For information about obtaining and installing OpenShift, please visit: You can use images from the EnterpriseDB or Docker repository or a local repository when deploying an Advanced Server or Backup and Recovery Tool container. Deploying a Container from the EnterpriseDB or RedHat Repository Use the docker login command to log in to either the EnterpriseDB repository (containers.enterprisedb.com) or the RedHat repository (registry.connect.redhat.com). Use the following command to log in: Where: docker login registry_address [ u username] [ p password] registry_address is the address of the registry you wish to use. username is the user name you use to log in to the registry. password is the password associated with the user account. Please note: If you do not provide a user name and password, you will be prompted for credentials when you log in. For connection credentials to the EnterpriseDB repository, please contact EnterpriseDB at: After logging in to the docker registry, pull a copy of the image that you will be using from the repository. For Advanced Server, use the commands: docker pull containers.enterprisedb.com/edb/edb-as:9.5 docker tag containers.enterprisedb.com/edb/edb-as:9.5 edbas:9.5 For BART, use the command: Copyright 2017 EnterpriseDB Corporation. All rights reserved. 4

7 docker pull containers.enterprisedb.com/edb/edb-bart:1 docker tag containers.enterprisedb.com/edb/edb-bart:1 edbbart:1 To make management easier, you may want to use the docker tag command to create shortcuts that represent each of your containers. For example, use the following command to create a shortcut for the Advanced Server container: docker tag containers.enterprisedb.com/edb/edb-as:9.5 edb-as:9.5 After invoking the command, you can refer to the Advanced Server container at the command line as edb-as:9.5. Creating a Local Repository To create a local repository that contains EDB Postgres images, you must create a local Docker registry. For example, the following command create and start a registry on localhost:5000 docker run -d -p 5000: restart=always --name registry registry:2 The following commands will push the Advanced Server image from the EnterpriseDB repository to a local repository (localhost:5000): docker pull containers.enterprisedb.com/edb/edb-as:9.5 docker tag containers.enterprisedb.com/edb/edb-as:9.5 localhost:5000/edb/edb-as:9.5 docker push localhost:5000/edb/edb-as:9.5 For information about creating a local Docker registry, please see the Docker documentation at: Copyright 2017 EnterpriseDB Corporation. All rights reserved. 5

8 2.1 Creating a Project Before deploying an EDB Postgres Advanced Server (EPAS) or EDB Postgres Backup and Recovery Tool (BART) container, you must: 1. Create an OpenShift project that will describe the resource allocations and template information for the container. 2. Configure the volume resources that the container will use. 3. Create a template file that describes the container that you will be deploying. The examples that follow use the OpenShift command line; log in to the OpenShift command line with sufficient privileges to create an OpenShift project: oc login -u admin -p admin For detailed information about using the OpenShift command line, see the project documentation at: Creating an OpenShift Project Use the following command to create a new OpenShift project for the Advanced Server container: oc new-project project_name Where project_name is the name of the OpenShift project that will describe resources available for the container and the container templates. After creating the project, assume sufficient privileges to create the.yaml files: oc login -u system:admin Configuring Volume Resources for the Container Before configuring the volume resources, an administrative user must identify an NFS mount point (with read/write access) that will be used to store the data files, log files, and supporting files for your deployments. The mount point must be provided in the persistent-volume.yaml file. Copyright 2017 EnterpriseDB Corporation. All rights reserved. 6

9 The persistent-volume.yaml and persistent-volume-claim.yaml files contain information that will be passed to the OpenShift PersistentVolume API and the OpenShift PersistentVolumeClaim API when deploying your project. The persistent-volume.yaml File Customize the following example of a persistent-volume.yaml file, providing details that are specific to your container host. apiversion: v1 kind: PersistentVolume metadata: name: ppas-pv spec: capacity: storage: 10Gi accessmodes: - ReadWriteOnce nfs: path: /volumes/edb-95 server: persistentvolumereclaimpolicy: Retain The persistent-volume-claim.yaml File Customize the following example of a persistent-volume-claim.yaml file, providing details that are specific to the container host. apiversion: v1 kind: PersistentVolumeClaim metadata: name: ppas-pvc spec: accessmodes: - ReadWriteOnce resources: requests: storage: 5Gi After creating the files that define the volume and the volume claim, navigate into the directory in which the files reside, and invoke the following commands: oc create -f persistent-volume.yaml oc create -f persistent-volume-claim.yaml Copyright 2017 EnterpriseDB Corporation. All rights reserved. 7

10 For more information about OpenShift volumes, please see the OpenShift documentation at: Creating a Project Template After creating the volume and volume claim, create a template that describes the content of your container: A ppas95-persistent.yaml file creates an EDB Postgres Advanced Server 9.5 container. A edb-bart.yaml file creates a container that hosts the EDB Backup and Recovery Tool. After creating the.yaml file that describes your container, use the following commands to create the template. To create a template for an Advanced Server container, invoke the command: oc create -f ppas95-persistent.yaml To create a template for a container that hosts the EDB Backup and Recovery Tool, use the command: oc create -f edb-bart.yaml The following examples create templates for Advanced Server 9.5 and BART 2.0. The ppas95-persistent.yaml File The following ppas95-persistent.yaml file example creates a template for Advanced Server 9.5; after creating the template, you can use the OpenShift console to provide installation details. Customize the following example, providing details that are specific to your installation. apiversion: v1 kind: Template metadata: name: ppas95-persistent annotations: description: "Standard EDB Postgres Advanced Server 9.5 Deployment Config" Copyright 2017 EnterpriseDB Corporation. All rights reserved. 8

11 tags: "database,ppas,postgres,postgresql" iconclass: "icon-postgresql" labels: template: ppas95-persistent objects: - apiversion: v1 kind: Service metadata: name: ${DATABASE_NAME}-service spec: ports: - name: db port: name: lb port: 9999 selector: db: ${DATABASE_NAME} sessionaffinity: None type: LoadBalancer - apiversion: v1 kind: DeploymentConfig metadata: name: ${DATABASE_NAME} spec: replicas: 4 selector: db: ${DATABASE_NAME} strategy: resources: {} rollingparams: intervalseconds: 1 maxsurge: 25% maxunavailable: 25% timeoutseconds: 600 updateperiodseconds: 1 type: Rolling template: metadata: creationtimestamp: null labels: db: ${DATABASE_NAME} spec: containers: - env: - name: DATABASE_NAME value: ${DATABASE_NAME} - name: DATABASE_USER value: ${DATABASE_USER} - name: DATABASE_USER_PASSWORD value: ${DATABASE_USER_PASSWORD} - name: ENTERPRISEDB_PASSWORD value: ${ENTERPRISEDB_PASSWORD} Copyright 2017 EnterpriseDB Corporation. All rights reserved. 9

12 - name: REPL_USER value: ${REPL_USER} - name: REPL_PASSWORD value: ${REPL_PASSWORD} - name: PGPORT value: "5444" - name: MASTER_HOST value: ${DATABASE_NAME}-service - name: MASTER_PORT value: "9999" - name: RESTORE_FILE value: /edbvolume/backup/${database_name}/pgbackup/ppas-95/latest.tar - name: LOCALEPARAMETER value: ${LOCALEPARAMETER} - name: CLEANUP_SCHEDULE value: ${CLEANUP_SCHEDULE} - name: YUM_URL value: ${YUM_URL} - name: EFM_ value: ${EFM_ } - name: EFM_PRODUCT_KEY value: ${EFM_PRODUCT_KEY} - name: NAMESERVER value: ${NAMESERVER} image: edb-as:9.5 imagepullpolicy: IfNotPresent name: ${DATABASE_NAME} ports: - containerport: 5444 protocol: TCP - containerport: 9999 protocol: TCP readinessprobe: exec: command: - /var/lib/ppas/testisrunning.sh initialdelayseconds: 60 timeoutseconds: 5 resources: {} terminationmessagepath: /dev/termination-log volumemounts: - name: ${PERSISTENT_VOLUME} mountpath: /edbvolume dnspolicy: ClusterFirst restartpolicy: Always securitycontext: {} terminationgraceperiodseconds: 0 volumes: - name: ${PERSISTENT_VOLUME} persistentvolumeclaim: claimname: ${PERSISTENT_VOLUME_CLAIM} Copyright 2017 EnterpriseDB Corporation. All rights reserved. 10

13 triggers: - type: ConfigChange parameters: - name: DATABASE_NAME displayname: Database Name description: Name of Postgres database (leave edb for default) value: 'edb' - name: DATABASE_USER displayname: Default database user (leave enterprisedb for default) description: Default database user value: 'enterprisedb' - name: DATABASE_USER_PASSWORD displayname: Password for default database user description: Password for default db user (other than enterprisedb) required: true - name: ENTERPRISEDB_PASSWORD displayname: EnterpriseDB Password description: Password for enterprisedb database user required: true - name: REPL_USER displayname: Repl user description: repl database user value: 'repl' - name: REPL_PASSWORD displayname: Repl Password description: Password for repl db user required: true - name: LOCALEPARAMETER displayname: Locale description: Locale of database value: 'en_us.utf-8' - name: CLEANUP_SCHEDULE displayname: Host Cleanup Schedule description: Standard cron schedule - min (0-59), hour (0-23), day of month (1-31), month (1-12), day of week (0-6) (0 to 6 are Sunday to Saturday, or use names; 7 is Sunday, the same as 0). Leave it empty if you dont want to cleanup. value: '0:0:*:*:*' - name: YUM_URL displayname: Yum Repository URL description: Yum repository URL with username and password value: ' - name: EFM_ displayname: description: for EFM value: 'name@ .com' - name: EFM_PRODUCT_KEY displayname: EFM Product Key description: EFM Product Key value: 'product_key' Copyright 2017 EnterpriseDB Corporation. All rights reserved. 11

14 - name: NAMESERVER displayname: Name Server for description: Name Server for value: 'nameserver' - name: PERSISTENT_VOLUME displayname: Persistent Volume description: Persistent volume name value: '' required: true - name: PERSISTENT_VOLUME_CLAIM displayname: Persistent Volume Claim description: Persistent volume claim name value: '' required: true The edb-bart.yaml File The following edb-bart.yaml file example creates a template for BART 2.0; after creating the template, you can use the OpenShift console to provide installation details. Customize the following example, providing details that are specific to your installation. apiversion: v1 kind: Template metadata: name: edb-bart annotations: description: "Standard EDB Backup And Recovery Tool Deployment Config" tags: "database,ppas,postgres,postgresql" iconclass: "icon-postgresql" labels: template: edb-bart objects: - apiversion: v1 kind: DeploymentConfig metadata: name: ${DATABASE_NAME}-bart spec: replicas: 1 selector: name: ${DATABASE_NAME}-bart strategy: resources: {} rollingparams: intervalseconds: 1 maxsurge: 25% maxunavailable: 25% timeoutseconds: 600 Copyright 2017 EnterpriseDB Corporation. All rights reserved. 12

15 updateperiodseconds: 1 type: Rolling template: metadata: labels: name: ${DATABASE_NAME}-bart spec: containers: - env: - name: BART_HOST_ADDRESS value: ${BART_HOST_ADDRESS} - name: DB_SERVER_NAME value: ${DB_SERVER_NAME} - name: PGHOST value: "${DATABASE_NAME}-service" - name: PGPORT value: ${PGPORT} - name: DATABASE_NAME value: ${DATABASE_NAME} - name: REPL_USER value: ${REPL_USER} - name: REPL_PASSWORD value: ${REPL_PASSWORD} - name: BART_BACKUP_SCHEDULE value: "${BART_BACKUP_SCHEDULE}" - name: BART_NUM_BACKUPS_TO_KEEP value: "${BART_NUM_BACKUPS_TO_KEEP}" - name: YUM_URL value: "${YUM_URL}" image: edb-bart:1 imagepullpolicy: IfNotPresent name: edb-bart volumemounts: - name: ${PERSISTENT_VOLUME} mountpath: /edbvolume volumes: - name: ${PERSISTENT_VOLUME} persistentvolumeclaim: claimname: ${PERSISTENT_VOLUME_CLAIM} triggers: - type: ConfigChange parameters: - name: BART_HOST_ADDRESS displayname: BART Host Address description: BART host address (leave localhost for default) value: 'localhost' required: true - name: DB_SERVER_NAME displayname: Database Server Name description: Database server name (leave ppas-95 for default) value: 'ppas-95' required: true Copyright 2017 EnterpriseDB Corporation. All rights reserved. 13

16 - name: DATABASE_NAME displayname: Database Name description: Name of Postgres database (leave edb for default) value: 'edb' required: true - name: PGHOST displayname: Database Host description: Database Host (leave ${DATABASE_NAME}-service for default) value: ${DATABASE_NAME}-service required: true - name: PGPORT displayname: Database Port description: Database Port (leave 5444 for default) value: '5444' required: true - name: REPL_USER displayname: Repl user description: repl database user value: 'repl' - name: REPL_PASSWORD displayname: Repl Password description: Password for repl db user required: true - name: YUM_URL displayname: Yum Repository URL description: Yum repository URL with username and password value: ' - name: PERSISTENT_VOLUME displayname: Persistent Volume description: Persistent volume name value: '' required: true - name: PERSISTENT_VOLUME_CLAIM displayname: Persistent Volume Claim description: Persistent volume claim name value: '' required: true - name: BART_BACKUP_SCHEDULE displayname: BART Backup Schedule description: Standard cron schedule - min (0-59), hour (0-23), day of month (1-31), month (1-12), day of week (0-6) (0 to 6 are Sunday to Saturday, or use names; 7 is Sunday, the same as 0) value: '0:0:*:*:*' required: true - name: BART_NUM_BACKUPS_TO_KEEP displayname: BART Number of Backups to Keep description: How many backups to keep, older backups will be removed as newer backups are added value: '2' required: true Copyright 2017 EnterpriseDB Corporation. All rights reserved. 14

17 2.2 Removing a Project Use the following set of commands to remove a project: oc project project-name oc delete template template-name oc delete dc database-name oc delete service service-name For example, to remove the example project ppas-95 created earlier where edb was used as the database name and edb-service as the service name: oc project ppas-95 oc delete template ppas95-persistent oc delete dc edb oc delete service edb-service When using the OpenShift command line (the oc delete command) to remove a project, you must manually remove the /volumes/edb/project_name/.db_namemaster file before launching another pod with the same component and version Retaining a Project with No Pods If you scale a cluster down to 0 pods, but retain the project for later use, you must manually remove the /volumes/edb/project_name/.db_name-master file before adding a pod to the cluster. Copyright 2017 EnterpriseDB Corporation. All rights reserved. 15

18 3 Using the OpenShift Console After creating a template, you can use the OpenShift console to create and manage Advanced Server projects. To create a project, open your web browser, and navigate to the connection address of your OpenShift console (by default, Provide your OpenShift connection credentials and click the Log In button to connect. When you've successfully authenticated with OpenShift, the console displays the Projects page (see Figure 3.1). Figure 3.1 The OpenShift console Projects page. Select your project (or ppas-95) from the Projects list; the OpenShift console will navigate to the project management page (see Figure 3.2). Figure 3.2 The OpenShift console project management page. Copyright 2017 EnterpriseDB Corporation. All rights reserved. 16

19 Click the Add to Project button to open the Select Image or Template page (see Figure 3.3). Figure 3.3 The OpenShift console Select Image or Template page. Select the button that is labeled with the name of the Advanced Server template. The OpenShift console opens a page that allows you to specify details for your Advanced Server deployment (see Figure 3.4). Copyright 2017 EnterpriseDB Corporation. All rights reserved. 17

20 Figure 3.4 The OpenShift project Parameters page. Copyright 2017 EnterpriseDB Corporation. All rights reserved. 18

21 Use the fields displayed under the Parameter heading to provide installation details for the deployment. The details provided will be used during pod initialization; it is important to note that password changes are not allowed after a pod has been initialized. Use the Database Name field to provide the name of the database that will be created when the database cluster is initialized. Use the Default database user field to specify the name of a database superuser that will be created when the database is initialized; by default, the database superuser is named enterprisedb. If you accept the default (enterprisedb), the user will be associated with the password provided in the EnterpriseDB Password field. If you specify an alternate name for the database superuser, the user will be associated with the password provided in the Password for default database user field. Use the Password for default database user field to specify the password associated with the database superuser named in the Default database user field if you specify a user name other than enterprisedb. Please note that this password should not be changed after the pod is initialized. During the installation process, the container creates a database superuser named enterprisedb. Use the EnterpriseDB Password field to provide the password associated with the default database superuser (enterprisedb). Please note that this password should not be changed after the pod is initialized. Use the Repl user field to specify the name of the replication user; the default name is repl. Use the Repl Password field to specify a password for the replication user; if you do not provide a password, a password will be generated by the server. Use the Locale field to specify the locale that will be used by the cluster; by default, the locale used is the system locale. Use the Host Cleanup Schedule to specify the execution schedule for a cleanup script. The cleanup script will review the data directories, and mark any directory for deletion that has not been used in the last 24 hours. If you do not provide a value in this field, the cleanup script will not execute. Copyright 2017 EnterpriseDB Corporation. All rights reserved. 19

22 Use the Yum Repository URL field to specify the connection properties for the EnterpriseDB yum repository. Replace <username> with the name of a user with connection privileges to the repository. Replace <password> with the password associated with the user name. Use the field to provide the address that will receive any notifications sent by Failover Manager. For detailed information about Failover Manager event notifications, please see the EDB Postgres Failover Manager Guide, available at: Use the EFM Product Key field to provide the Failover Manager product key. For more information about Failover Manager licenses, visit the project website at: Use the Name Server for parameter to provide the identity of a name server that will be used for notifications from Failover Manager. Use the Persistent Volume field to specify the name of the persistent volume definition file. Use the Persistent Volume Claim to specify the name of the persistent volume claim definition file. When you've completed the Parameters dialog, click the Create button to deploy an Advanced Server project. Copyright 2017 EnterpriseDB Corporation. All rights reserved. 20

23 Figure 3.5 Continue to the project overview. When the OpenShift console acknowledges that the application has been created; click the Continue to overview banner (see Figure 3.5). Figure 3.6 The template objects have been created successfully. OpenShift confirms that all of the items described in the template have been created before deploying Advanced Server pods (see Figure 3.6). By default, an Advanced Server deployment will consist of four pods, with EDB Failover Manager protection enabled. If you wish to disable failover protection and spin up a pod with a single replica, you can modify the xpas95-persistent.yaml file, setting the value for replicas to 1. Copyright 2017 EnterpriseDB Corporation. All rights reserved. 21

24 Figure 3.7 The pods are being deployed. As OpenShift spins up the pod, the progress indicator displayed on the Overview will change from light blue to darker blue (see Figure 3.7). Figure 3.8 The cluster is ready for use. When the progress indicator is solid blue and indicates that 4 pods have been created, Advanced Server is ready for use (see Figure 3.8). Failover Manager will send notifications to the address specified when you configured your project, keeping you informed of the state of your pods (see Figure 3.9). Copyright 2017 EnterpriseDB Corporation. All rights reserved. 22

25 Figure 3.9 notifications from Failover Manager. You can use Failover Manager notifications to easily identify the Master node of your replication scenario. The Subject line identifies each node in the cluster as a Master or Standby. Locate the Master agent, and then compare the address shown in the From column of your to the names in the Pods list (accessed via the Browse menu) in the OpenShift console to identify the Master node (see Figure 3.10). Figure 3.10 A list of pods, displaying the pod names. Copyright 2017 EnterpriseDB Corporation. All rights reserved. 23

26 3.1 Scaling an Advanced Server Deployment The default configuration of EDB Postgres Advanced Server for OpenShift uses EDB Postgres Failover Manager to ensure high-availability for your deployment. If a pod fails, Failover Manager detects the failure, and replaces the pod with a running node. If the failed node is the master in your replication scenario, Failover Manager promotes a standby node to the role of master before adding a replacement standby to the scenario. For detailed information about Failover Manager, please visit the EnterpriseDB website at: To prevent disruptions in Failover Manager monitoring, an Advanced Server deployment must have at least four pods; by default, each new Advanced Server project will have four pods. Figure 3.11 Use the arrows to the right of the blue circle to scale a deployment. Please note: by default, the container environment will support up to 9 pods; to support 10 or more pods, you must modify the server configuration. For detailed information, see Section 3.3, Creating a Custom Configuration within a Pod. Copyright 2017 EnterpriseDB Corporation. All rights reserved. 24

27 Manually Scaling a Pod You can use the up arrow (to the right of the blue circle) to add new pods to your deployment when processing requirements are higher, or use the down arrow to remove unneeded pods from the deployment when processing requirements are light (see Figure 3.11). Please note that when removing a pod from your deployment, OpenShift may remove the master node in your replication scenario. If Failover Manager is enabled, and the master node is removed during scaling, a standby node will be promoted to the role of master. If you plan to remove multiple pods from a deployment, you should allow time for each pod to be completely removed before removing each additional pod to avoid interfering with Failover Manager protection. Copyright 2017 EnterpriseDB Corporation. All rights reserved. 25

28 3.2 Connecting with the psql Client Connections to Advanced Server and supporting components are managed by OpenShift; for more information about managing and connecting to an OpenShift pod, refer to the OpenShift documentation at: OpenShift documentation is also easily accessed through the Documentation link in the upper-right corner of the OpenShift console. You can use the OpenShift console Terminal to open a psql client to connect to Advanced Server and query the server directly. To connect with psql, select Pods from the Browse menu. Figure 3.12 The list of available pods. When the Pods dialog opens (see Figure 3.12), click the name of a pod to access detailed information about the selected pod. Copyright 2017 EnterpriseDB Corporation. All rights reserved. 26

29 Figure 3.13 Detailed information about a pod To open the psql client, select the Terminal tab (see Figure 3.13). Copyright 2017 EnterpriseDB Corporation. All rights reserved. 27

30 Figure 3.14 Connecting with the psql client on the Terminal tab When the Terminal tab opens (as shown in Figure 3.14), use the psql command to open the client. A psql command takes the following form: Where: psql d database_name U user_name database_name specifies the name of the database to which you wish to connect. user_name specifies the name of the connecting user. For detailed information about using the psql client, see the PostgreSQL online documentation at: Copyright 2017 EnterpriseDB Corporation. All rights reserved. 28

31 3.3.2 File Locations By default, Advanced Server files are located in the directories listed in the table below: EDBAS Component Data directory postgresql.conf file pg_hba.conf file Executables Libraries Contrib Path to Installation Directory /edbvolume/9.x/pgdata/hostname /edbvolume/9.x/conf/edb/postgresql.conf /edbvolume/9.x/conf/edb/pg_hba.conf /usr/ppas-9.x/bin /usr/ppas-9.x/lib64 /usr/ppas9.x/share/contrib Copyright 2017 EnterpriseDB Corporation. All rights reserved. 29

32 3.3 Creating a Custom Configuration within a Pod Configuration files on an Advanced Server installation determine user authentication methods and server preferences for that server. You can customize your installation by modifying those files, and then replacing the instances within your project with new pods that use the modified configuration files. Parameter changes made at the command line will not be replicated to standby servers; you must save modifications to the configuration file of the master node of the replication scenario. By default, Advanced Server files are located in the directories listed in the table below: EDBAS Component postgresql.conf file pg_hba.conf file Path to Installation Directory /edbvolume/9.x/conf/edb/postgresql.conf /edbvolume/9.x/conf/edb/pg_hba.conf To create a custom Advanced Server pod: 1. Use a standard template to create an Advanced Server pod. 2. Use your choice of editor to modify the appropriate configuration files. By default, configuration files are located in edbvolume/9.x/conf/db_name. 3. Use the OpenShift console to add new pods to the cluster; as each new pod is added, the new pod will use the customized configuration file. 4. Remove pods that were instantiated with old configuration files (including the original master node of the replication scenario). Please note: To preserve the integrity of your Failover Manager scenario, you should not let the total pod count of the deployment drop below four when replacing those clusters with an old configuration with clusters with the new configuration files. The default setting for the max_wal_sender parameter (in the postgresql.conf file) is 10; this allows you to deploy up to 9 pods. If you would like to create more than 9 pods, you must adjust the value of max_wal_sender to at least 1 greater than the number of pods you would like to create. Please note that the value of max_connections must be greater than the max_wal_sender value. For detailed information about customizing the postgresql.conf file, please refer to the Postgres core documentation, available at: CONFIGURATION-FILE Copyright 2017 EnterpriseDB Corporation. All rights reserved. 30

33 For detailed information about customizing the pg_hba.conf file, please refer to the Postgres core documentation, available at: Performing a Rolling Update When an updated version of Advanced Server becomes available, you can use a rolling update technique to upgrade your cluster. EnterpriseDB's Docker repository will always make available the most recent version of the server; to update the server version used in your deployment, you can simply: 1. When an updated version of Advanced Server becomes available, use the OpenShift console to add new pods to the cluster; as each new pod is added, the new pod will use the updated server version. 2. Remove pods that were instantiated using the old server version (including the original master node of the replication scenario). Please note: To preserve the integrity of your Failover Manager scenario, you should not let the total pod count of the deployment drop below four when performing a rolling update. Copyright 2017 EnterpriseDB Corporation. All rights reserved. 31

34 4 Managing a Container at the Command Line You can use the Docker or Atomic command line client to deploy, manage, and use an Advanced Server container. We recommend including the following docker command options when using the command line: -d The d option forces docker to run as a daemon. This option is mandatory when invoking an atomic command, but optional for docker commands. --privileged The --privileged option may be required if local security settings do not permit mounting a local volume with read-write options. As an alternative, we recommend allowing your security settings to permit the container to have readwrite access to the mounted volume. If applicable, adjust your SELinux settings to allow access. --restart=always This option configures your container to automatically restart. For more information about docker commands and command options, please see the documentation at: Copyright 2017 EnterpriseDB Corporation. All rights reserved. 32

35 4.1 Creating a Container at the Docker Command Line To use the Docker command line to create a container deployment of Advanced Server that enables Failover Manager, you must invoke the docker run command four times, creating a master node, and three standby nodes. The first docker run command will create a master node. Each subsequent docker run command will create a standby node. You can specify environment variables at the command line (when invoking the docker run command), or in a file located in the network mountpoint for the container. Consult the docker documentation for a complete list of command options: The following command uses the docker command line client to create a container: Where: docker run --restart option --name node_name -v network_mountpoint -e DATABASE_NAME="database_name" -e PGPORT="as_listener_port" -e DATABASE_USER="db_user_name" -e DATABASE_USER_PASSWORD=" db_user_password" -e ENTERPRISEDB_PASSWORD=" user_password " -e REPL_USER="repl_user_name" -e REPL_PASSWORD="repl_user_password" -e LOCALEPARAMETER="locale" -e MASTER_HOST= "none `docker inspect -f {{.NetworkSettings.IPAddress}} master`" -e RESTORE_FILE="path_to_restore_file" ${db_name}/latest.tar" -e NAMESERVER="nameserver " -e CLEANUP_SCHEDULE="0:0:*:*:*" -e EFM_ =" @address.com" -d edb-as:95 Include the docker run --restart option environment variable to specify your restart preferences for the container. Please refer to the docker documentation for details about the supported options. Include the --name node_name option to specify the name of the replication cluster node. For example, master, replica1, replica2, and replica3 might identify the nodes of a cluster. Copyright 2017 EnterpriseDB Corporation. All rights reserved. 33

36 Include the -v network_mountpoint option to specify the volume in which the container will reside. Use the DATABASE_NAME="database_name" environment variable to specify the name of the Advanced Server database. Use the PGPORT="as_listener_port" environment variable to specify the listener port of the Advanced Server database (by default, 5444). Use the DATABASE_USER="db_user_name" environment variable to specify the name of a database superuser that will be created when the database is initialized; by default, the database superuser is named enterprisedb. If you specify the default (enterprisedb), the user will be associated with the password provided in the EnterpriseDB Password field. If you specify an alternate name for the database superuser, the user will be associated with the password provided in the Password for default database user field. Use the DATABASE_USER_PASSWORD=" db_user_password" environment variable to specify the password associated with the database superuser if you specify a db_user_name other than enterprisedb. Please note that this password should not be changed after the pod is initialized. Use the ENTERPRISEDB_PASSWORD=" user_password" environment variable to specify the password associated with the default database superuser (enterprisedb). During the installation process, the container creates a database superuser named enterprisedb. Please note that this password should not be changed after the pod is initialized. Use the REPL_USER="repl_user_name" environment variable to specify the name of the Postgres streaming replication user. Use the REPL_PASSWORD="repl_user_password" environment variable to specify the password associated with the replication user. Use the LOCALEPARAMETER="locale" environment variable to specify the locale that will be used by the container. Use the MASTER_HOST environment variable to indicate if the node is a master or a standby. Specify none if the node is the master node within the replication cluster. Copyright 2017 EnterpriseDB Corporation. All rights reserved. 34

37 Specify MASTER_HOST=`docker inspect -f {{.NetworkSettings.IPAddress}} master' if the node is a standby node within the replication cluster. The clause uses a call to docker inspect to retrieve the address of the master node of the cluster. Please note: by default, the container environment will support up to 9 pods; to support 10 or more pods, you must modify the server configuration. For detailed information, see Section 3.3, Creating a Custom Configuration within a Pod. Use the RESTORE_FILE="path_to_restore_file" environment variable to specify the complete path to the restore file for the cluster. Use the NAMESERVER="nameserver " environment variable to specify the identity of a name server that will be used for notifications from Failover Manager. Use the CLEANUP_SCHEDULE="0:0:*:*:*" environment variable to provide an execution schedule for a cleanup script. The cleanup script will review the data directories, and mark any directory for deletion that has not been used in the last 24 hours. Specify the value in a cron format; if you do not provide a value, the cleanup script will not execute. Use the EFM_ =" @address.com" environment variable to specify the address that will receive any notifications sent by Failover Manager. For detailed information about Failover Manager event notifications, please see the EDB Postgres Failover Manager Guide, available at: Copyright 2017 EnterpriseDB Corporation. All rights reserved. 35

38 4.1.1 Using Docker to Connect to an Advanced Server Container After creating a container, you can use the docker exec command to connect to the master node of the cluster: docker exec node Where node is the name of the node to which you are connecting (master, replica1, replica2, or replica3). The shell will start in the /usr/ppas-95/bin directory. After connecting, you can use the psql command line client to access the database:./psql -U database_user_name -d database_name For example, to connect to a database named edb, as the user enterprisedb, use the command:./psql -U enterprisedb -d edb Copyright 2017 EnterpriseDB Corporation. All rights reserved. 36

39 4.2 Managing an Advanced Server Container at the Atomic Command Line You can use the Atomic command line client to deploy or manage an Advanced Server Docker container. The Atomic command line is restricted to three arguments: OPT1 contains optional docker switches to be passed. OPT2 is the name of the cluster node that you are creating. OPT3 is the NFS mount directory. Use an environment file to specify additional container properties. You can use either the atomic install or atomic run command to create an EnterpriseDB Advanced Server container. For example: atomic install --opt1='--restart always' --opt2=master -- opt3=/volumes/edb-ppas ppas95 atomic run --opt1='--restart always' --opt2=master -- opt3=/volumes/edb-ppas ppas Using the Atomic Command Line to Stop or Uninstall a Container You can use the atomic command line to stop or uninstall your container. To stop a container, invoke the following command: Where: atomic stop --opt1=node_name container_name node_name is the name of the node (within the replication cluster that you wish to stop. container_name is the name of the container that you wish to stop. Use the following command to stop a container, and then unload the image from your local repository: Where: atomic uninstall --opt1= node_name container_name Copyright 2017 EnterpriseDB Corporation. All rights reserved. 37

40 node_name is the name of the node (within the replication cluster that you wish to stop. container_name is the name of the container that you wish to stop Supported LABELS - Reference Docker makes some values available for use by atomic commands through the use of LABEL instructions. The Advanced Server container supports the labels that are described below. Within each label: OPT1 can be any valid option for a Docker command used within the label. For a complete list of the Docker options for a specific command, please use the docker --help command: docker command --help Where command is the docker command invoked by the label. OPT2 is the name of the cluster node that you are managing. OPT3 is the network mountpoint of the volume (or local directory) that hosts the configuration files and/or the data directory. You must be a superuser to invoke an atomic command. RUN The RUN label sends an atomic run ppas command to the container host, running the container. The syntax is: INSTALL LABEL RUN=docker run ${OPT1} --name ${OPT2} -v ${OPT3}:/edbvolume:z -d ppas:latest The INSTALL label invokes the atomic install ppas command, installing and running the container. The syntax is: STOP LABEL INSTALL=docker run ${OPT1} --name ${OPT2} -v ${OPT3}:/edbvolume:z -d ppas:latest Copyright 2017 EnterpriseDB Corporation. All rights reserved. 38

41 The STOP label invokes the atomic stop ppas command, stopping the container. The syntax is: LABEL STOP=`docker stop ${OPT1}` UNINSTALL The UNINSTALL label invokes the atomic uninstall ppas command, uninstalling the container. Please note that the container image will persist on the host. The syntax is: LABEL UNINSTALL=`docker stop ${OPT1}` Please note: The following label values are subject to change; for the content that is applicable to your container, please see the atomic info file: atomic info container_type Where container_type is ppas or edb-bart. Name The name of the container image. For example, for Advanced Server: Name=ppas or, for BART: Name=edb-bart Version The version number of Advanced Server. For example, for Advanced Server: Version= or, for BART: Version= Release The release number of the container. For example: Copyright 2017 EnterpriseDB Corporation. All rights reserved. 39

42 Release=1 Vendor The name of the container vendor. For example: Vendor=EnterpriseDB Architecture The architecture of operation sysem. For example: Architecture=x86_64 Build-date The build date and time of the Advanced Server container. For example: Build-date=build-date: Description The description of the EDB Postgres Advanced Server container. For example: Description= EDB Postgres Advanced Server 9.5. This container includes EDB Failover Manager for High Availability and pgpool for automatic load balancing of read requests across cluster members. Summary Summary information describing the Advanced Server container. For example: Summary= The EDB Postgres Advanced Server 9.5 container will install all required packages via yum and offers the ability to scale the number of nodes in the cluster while automatically updating the load balancer to route requests to the appropriate master or replica node. It also handles high availability by automatically promoting one of the replicas to become a master if the original master node fails. Copyright Copyright information for the EDB Postgres Advanced Server container. For example: Copyright=2017 Copyright 2017 EnterpriseDB Corporation. All rights reserved. 40