3.2 Installing EDB Ark for OpenStack

The installation instructions that follow describe the Ark console installation process on Red Hat Enterprise Linux OpenStack. OpenStack Administrative privileges are required during the installation process:

•	You must be an OpenStack administrative user with sufficient privileges to upload a public image to import the EDB Ark image.

•	When creating a security group and launching EDB Ark, you must use an OpenStack account with sufficient privileges in the tenant that will host the Ark console.

To install EDB Ark on an OpenStack host, you must:

1.	Import the EDB Ark Image. For more information, see Section 3.2.1.

2.	Create the EDB Ark Security Group. For more information, see Section 3.2.2.

3.	Launch the Ark console instance. For more information, see Section 3.2.3.

4.	Assign a floating IP address to the instance. For more information, see Section 3.2.4.

5.	Modify the ppcd.properties file to configure the Ark console. For more information, see Section 3.2.5.

6.	Deploy the Ark console. For more information, see Section 3.2.6.

7.	Configure OpenStack user accounts. For more information, see Section 3.2.7.

8.	Connect to the Ark console. For more information, see Section 3.2.8.

3.2.1 Importing the EDB Ark Image on an OpenStack Host

You can use either the OpenStack dashboard GUI or the OpenStack Glance command line to import the EDB Ark image.

Using the OpenStack Dashboard to Import the EDB Ark Image

Use the following steps in the OpenStack Dashboard to import the EDB Ark image:

1.	Log into the OpenStack dashboard as an administrative user.

2.	Navigate to the Admin menu, and then select the Images menu selection.

3.	Click the + Create Image button to open the Create An Image dialog (shown in Figure 3.17).

Figure 3.17 – The Create an Image dialog.

Use fields on the Create An Image dialog to define the EDB Ark image:

•	Use the Name field to provide a name for the image.

•	Use the Description field to provide a description of the image.

•	Use the Image Source drop-down listbox to specify that the source will be an Image File.

•	Use the Image Location field to specify the location of the EDB Ark image file on your computer

•	Use the Format drop-down listbox to select QCOW2 - QEMU Emulator.

•	Enter x86_64 in the Architecture field.

•	Enter 16 in the Minimum Disk (GB) field.

•	Enter 4096 in the Min RAM (MB) field.

•	Check the box next to Copy Data.

•	Check the box next to Public.

•	Check the box next to Protected.

After completing the dialog, click the Create Image button to create the EDB Ark image. Please note that the process of creating an image may take a while depending on your network conditions. While the image is being created you should not exit the OpenStack dashboard or close your browser tab as it will stop the file transfer.

Using the Glance Command Line to Import the EDB Ark Image

You can also use the Glance command line tool to import the EDB Ark image. Please consult your platform-specific documentation for Glance installation instructions. After installing Glance, connect to the server as an administrator, and invoke the following command:

glance \
--os-username administrative_user \
--os-password password \
--os-tenant-name tenant_name \
--os-auth-url http://identity_service_name:35357/v2.1
image-create \
--name 'image_name' \
--disk-format qcow2 \
--container-format bare \
--is-public True \
--is-protected True \
--min-disk 16 \
--min-ram 4096 \
--property 'description=image_details' \
--progress \
--property os_type=linux
/path_to_image_file

Where:

administrative_user is the name of an OpenStack administrative user with sufficient privileges to import the image.

password is the password associated with the administrative user account.

tenant_name is the name of a tenant that the --os-username belongs to; it will be used as part of the OpenStack authentication process.

identity_service_name is the URL of the node hosting the OpenStack keystone authentication service. When importing an image, you should specify port 35357 to ensure that the required operations are available.

image_name is a descriptive name of the EDB Ark image.

image_details is a user-friendly description of the EDB Ark image that you are importing. For example, you might want to specify that you are importing: EDB Ark 2.1 Console on CentOS 6.6 x86_64 Default user: centos

path_to_image_file specifies the location and file name of the EDB Ark image file.

For more information about the other options supported by Glance, please consult the Glance documentation, available at:

http://docs.openstack.org/developer/glance/

3.2.2 Creating the EDB Ark Security Group

The security group for the Ark console must allow communication between the nodes of the cluster. To define the security group rules:

1.	Log into the OpenStack dashboard as an administrator

2.	Navigate into the tenant that is hosting the Ark console.

3.	Navigate to the Project page, and select select Access & Security.

4.	Select the Security Group tab, and click the + Create Security Group button to open the Create Security Group dialog (shown in Figure 3.18).

Figure 3.18 – The Create Security Group dialog.

Use fields on the dialog to create a security group for the image:

•	Use the Name field to provide a name for the security group.

•	Use the Description field to provide a description of the security group.

Click the Create Security Group button to create the security group and continue.

Figure 3.19 – The new group, displayed in the Security Groups list.

To add rules to the new security group, click the Manage Rules button that is located to the right of the security group name (see Figure 3.19). When the list of security group rules opens (see Figure 3.20), click the + Add Rule button to access a dialog that allows you to add a new rule.

Figure 3.20 – The Security Group rules for the new security group.

Before using EDB Ark, you should add rules that allow communication between the nodes of the cluster. Use the Add Rule dialog to define the rules listed below:

Rule Type	Direction	Port	Remote	CIDR Address
All ICMP	Ingress		CIDR	0.0.0.0/0
SSH			CIDR	0.0.0.0/0
HTTP			CIDR	0.0.0.0/0
HTTPS			CIDR	0.0.0.0/0
Custom TCP	Ingress	6666	CIDR	0.0.0.0/0
Custom TCP	Ingress	port range from 7800 to 7999	CIDR	0.0.0.0/0

3.2.3 Launching the EDB Ark Console Instance

After importing the image and defining the security group, you are ready to launch the Ark console instance. Log into the Openstack dashboard as an Administrative user, and navigate into the tenant that is hosting the installation. Then, navigate through the Project tab to open the Compute menu, and select Instances. On the Instances dialog, click the Launch Instance button to open the Launch Instance dialog (shown in Figure 3.21).

Figure 3.21 – The Launch Instance dialog.

Use fields on the Launch Instance dialog to describe the EDB Ark instance; on the Project & User tab:

•	Use the Project drop-down listbox to select a tenant for the instance.

•	Use the User drop-down listbox to the name of the user that will own the instance.

On the Details tab:

•	Use the Availability Zone drop-down listbox to specify an availability zone.

•	Use the Instance Name field to provide a name for the instance.

•	Use the Flavor drop-down listbox to specify the size of the cluster. Please note that the cluster must be size m1.medium or larger.

•	Set the Instance Count field to 1.

•	Use the drop-down listbox in the Instance Boot Source field to select Boot from image.

•	Use the drop-down listbox in the Image Name field to select the name of the image that you imported in Step One.

On the Access & Security tab:

•	Use the Key Pair drop-down listbox to select the keypair you will use to access the instance.

•	Check the box next to the name of the security group you created in step 2

On the Networking tab

•	Select a network from the list of available networks.

No changes are required on the Post-Creation and Advanced Options tabs.

Click the Launch button to launch the console instance.

3.2.4 Assign a Floating IP Address

When the instance launch completes, the new instance will be displayed on the Instances panel (as shown in Figure 3.22).

Figure 3.22– The Instances dialog.

To assign a floating IP address to the new instance, select Associate Floating IP from the drop-down listbox in the Actions column. When the Manage Floating IP Associations dialog opens (see Figure 3.23), use the IP Address drop-down listbox to select an IP address, or click the + button to allocate a new IP address.

Figure 3.23– The Manage Floating IP Associations dialog.

3.2.5 Configuring the Installation

Once the console instance has fully launched, you should review the instance log. To review the instance log, log into the OpenStack dashboard as an administrator and navigate into the tenant that is hosting the Ark console. Click the Project tab, and then select the Instances menu option. Use the drop-down listbox in the Actions column) to select View Log.

After displaying startup information and SSH authentication details, the log will confirm that the Postgres service and the GlassFish application server have started:

Starting postgresql-9.4 service: [ OK ]
Waiting for domain1 to start .......
Successfully started the domain : domain1
domain
Location: /opt/glassfish3/glassfish/domains/domain1
Log File: /opt/glassfish3/glassfish/domains/domain1/logs/server.log
Admin Port: 4848
Command start-domain executed successfully.

After confirming that the service is running, you should use your SSH keypair to SSH to the IP address assigned in Step Four as the user centos:

ssh -i /path_to_your_private_key centos@ip_address

Where:

path_to_your_private_key specifies the complete path to the key on your local system. This must be the same key used when launching the console instance (see Section 3).

ip_address specifies the floating IP address of the Ark console.

Setting the Console Time Zone

After connecting with SSH, assume root privileges, and use the following commands to set the console time zone.

# rm /etc/localtime
# ln -s /usr/share/zoneinfo/time_zone /etc/localtime
# rm –f /etc/timezone
# ln –s /usr/share/zoneinfo/time_zone /etc/timezone

Where time_zone specifies the time zone identifier that the console will use. To discover the available time zones for your system, you can use the command:

ls -l /usr/share/zoneinfo/

Then, restart the console's Postgres server, and then the GlassFish server:

# /etc/init.d/postgresql-9.6 restart
# su – ppcd
$ asadmin restart-domain

Then, use your choice of editor to modify the ppcd.properties file.

3.2.5.1 Configuring the ppcd.properties File on an OpenStack Host

You must supply configuration information in the ppcd.properties file before deploying the Ark console. Modify the ppcd.properties file (located in /var/ppcd/), specifying the system-specific information detailed below.

Please note that parameter names that start with the word openstack have a corresponding value that was declared during the OpenStack installation. The value specified during the OpenStack configuration must match the value specified in the ppcd.properties file for EDB Ark to function properly.

Likewise, parameters that are prefaced with aws have values that correspond to values specified on the Amazon AWS management console. The value specified on the Amazon AWS Management console must match the value specified in the ppcd.properties file for EDB Ark to function properly.

PPCD Console DB Backup properties

Use the parameters in the PPCD Console DB Backup properties section to specify backup instructions for the Ark console. By default, the backup properties are commented out; if you uncomment them, the backup service will start when the console application is deployed.

# To enable Console DB Backups, uncomment these properties.

# You must specify console.db.backup.dir and modify the others

# as needed.

# DB user name

# console.db.user=postgres

# DB user password

# console.db.password= 0f42d1934a1a19f3d25d6288f2a3272c6143fc5d

# DB name to connect to

# console.db.name=postgres

EDB Ark provides a backup script. For console backups to function properly, the console (GlassFish) must be running as the ppcd user. Ark creates the .pgpass file in the ppcd user’s home directory (by default, /var/ppcd).

By default, the console.db.backup.script parameter specifies the name and location of the script provided with EDB Ark. If you choose to provide your own backup script, use the parameter to specify the name and location. Please note that you must ensure that the script can be read and executed by the Ark user account (ppcd).

# name of backup script (set to the default script
# shipped with EDB Ark)

# console.db.backup.script=/var/ppcd/.edb/backup-postgresql.sh

Use the console.db.backup.dir parameter to specify the directory to which console backups will be written. The Ark user account (ppcd) must have sufficient privileges to write to the specified directory. For information about recovering from a console failure, please see Section 7.

# directory to store the backups

# this must be a location that is writeable by the ppcd OS user

# console.db.backup.dir=backup_dir

On an Amazon hosted console, you can use the console.db.backup.container and console.db.backup.folder parameters to specify the name of an Amazon S3 bucket to which console backups will be copied, and a console-specific folder name. If no value is specified for console.db.backup.folder, the value will default to default.

# Optional bucket name in which to store console backups

# console.db.backup.container=

# Unique name for the console backup folder that identifies this

# console, i.e. 'dev.console'. Default name is 'default'

# console.db.backup.folder=

Please note: Your AWS S3 backup container name must be unique when compared to the names of all other AWS containers. Including account specific information in the bucket identifier may help you create a unique name; for example:

account-name.console.db.backup.container

For more information about forming a bucket name, please consult the Amazon documentation at:

http://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html

Please note: backups are first created in the location specified in console.db.backup.dir before being copied to the container specified in console.db.backup.container. You must provide values for both parameters.

Email Configuration properties

Use the contact.email.address parameter to specify the email address included in the body of cluster status notification emails.

# The contact email address that is displayed to the user. This

# is used in cases where the user may need to contact someone

# for more information, e.g. if a user's account is disabled.

contact.email.address=email_address

Use the email.from.address parameter to specify the return email address specified on cluster status notification emails.

# Return address for all generated emails. This can be

# separate from the mailto links that are included in

# the email bodies.

email.from.address=email_address

Use the notification.email parameter to specify the email address to which email notifications about the status of the Ark console will be sent.

# the email address that will receive administrative emails from

# the EDB Ark console

notification.email=email_address

General properties

The wal.archive.container parameter specifies the name of the object storage container where WAL archives (used for point-in-time recovery) are stored. You must provide a value for this property. Once this property is set, this property must not be changed.

# the name of the Object Storage (swift) container used by
# Point-In-Time Recovery(this should never change after
# the initial deployment of EDB Ark).

wal.archive.container=container_name

Please note: If you are using an AWS S3 bucket, your bucket name must be unique when compared to the names of all other AWS buckets. Including account specific information in the bucket identifier may help you create a unique name; for example:

account-name.wal.archive.container

For more information about forming a bucket name, please consult the Amazon documentation at:

http://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html

The api.timeout parameter specifies the number of minutes that an authorization token will be valid for use with the API.

# the lifetime in minutes of an authorization token used in the API

api.timeout=10

OpenStack specific properties

Use the openstack.region parameter to specify the region in which the Ark console resides. This parameter must match the region specified during OpenStack installation.

# the OpenStack region hosting your PPCD console
openstack.region=region_name

Use the openstack.admin.role parameter to specify the name of the OpenStack administrative role. The OpenStack role is created during the OpenStack installation; when a user that is a member of this role connects to the Ark console, the console will display the Admin and DBA tabs.

# the name of the OpenStack admin role
openstack.admin.role=admin_name

Use the openstack.identity.service.endpoint parameter to specify the URL of the OpenStack Keystone Identity Service.

# the URL for the API endpoint for the Identity Service
openstack.identity.service.endpoint=http://identity_service_url

Use the service.account.id parameter to specify the name of the OpenStack user account that EDB Ark will use when managing clusters. The account must be a member of and be assigned the admin role (as specified in the openstack.admin.role property) for all tenants that are allowed to run EDB Ark clusters.

Use the service.account.password parameter to specify the password associated with the service account.

# the account name and password for the EDB Ark service user
# (used internally by EDB Ark)

service.account.id=edbArk_service_user

service.account.password=password

Amazon AWS specific properties

The parameters listed in the OpenStack specific properties section will not apply to those consoles that are installed on an OpenStack host.

# the IAM role for the AWS service account
aws.service.account.rolearn=iam_role_arn

Use the aws.service.account.externalid parameter to specify the Amazon external ID that should be used by the Ark service user (ppcd).

# the external ID for the IAM role for the AWS service account
aws.service.account.externalid=iam_role_externalId

Use the aws.region parameter to specify the Amazon region in which Ark clusters will reside.

# the AWS region hosting your EDB Ark console (i.e. us-east-1)
aws.region=region_name

Use the aws.cross.account.accesskey parameter to specify the Amazon AWS_ACCESS_KEY_ID associated with the AWS role used for account administration.

# the AWS IAM cross account access key
aws.cross.account.accesskey=accesskeyid

Use the aws.cross.account.secretkey parameter to specify the Amazon AWS_SECRET_ACCESS_KEY associated with the AWS role used for account administration.

# the AWS IAM cross account secret key
aws.cross.account.secretkey=secretkeyid

If your console uses an Amazon AWS backing host, you can use the self.registration.enabled parameter to instruct the Ark console to enable or disable self-registration for Ark users.

If self.registration.enabled is set to false, an administrative user must register each Ark console user in the Ark administrative console.

If self.registration.enabled is set to true, the Ark console login dialog will display a Register button. An unregistered console user can use the Register button to access a dialog that allows them to register their own user account, and access the console. To successfully register, the user must know a valid Amazon Role ARN that will be associated with their identity.

# Self registration enabled
self.registration.enabled=false

Display properties

Use the console.dashboard.docs and console.dashboard.hot.topics parameters to specify the source of the content that will be displayed on the Dashboard tab of the Ark console:

•	If your cluster resides on a network with Internet access, set the parameters to DEFAULT to display content (alerts and documentation) from EnterpriseDB.

•	If you would like the Dashboard tab to display alternate content, use the parameters to provide the URL of the content.

•	If your cluster has limited access to the Internet, or if you wish to not display content on the Dashboard tab, leave the parameter values empty.

# these properties allow you to control the dashboard content.
# Legal values:
# DEFAULT = load the default pages from enterprisedb.com
# <unset> = don't load anything
# <url> = load alternate content at specified url
console.dashboard.docs=DEFAULT
console.dashboard.hot.topics=DEFAULT

3.2.6 Deploying the Console

After modifying the ppcd.properties file, assume root privileges, and use the following command to deploy the Ark console:

# /var/ppcd/postInstall.sh
Have you modified the ppcd.properties file according to your requirements?
Are you sure you want to continue? <y/N> y
Deploying EDB Ark Application...
Application deployed with name PPCDConsole.
Command deploy executed successfully.
Done!

The postInstall.sh script will remind you to edit /var/ppcd/ppcd.properties and prompt you to continue before allowing you to complete installation.

Then, you are ready to log into the Ark console; when connecting to the console, use your OpenStack user name and password and an SSL encrypted browser connection (https://). When connecting as an OpenStack Administrative user, EDB Ark Administrative options will be displayed on the Ark console.

In preparation for non-administrative user to connect, an OpenStack Administrator should:

3.	Use the Ark console to define a server image for each OpenStack server image that will host a database cluster. For detailed information about using the Ark console to create server images, see Section 4.1.2.

4.	Use the Ark console to create database engine definitions. For detailed information about defining a database engine, see Section 4.1.3.

After deploying the console, OpenStack users that are configured with access permissions may log in; for information about granting access to an OpenStack user, see Section 3.2.7.

3.2.7 Configuring a User to Log In

After deploying the Ark console, the console will be available for connections from enabled OpenStack user accounts. Use the OpenStack console to grant access to an OpenStack user account. Please note that the EDB Ark service account must have administrative privileges in the tenant or project in which you are granting access.

To enable an existing OpenStack user account, connect to the OpenStack console as an Administrative user and select Identity. Click the Manage Members button in the Actions column to the right of the project name.

Figure 3.24 – The Edit Project dialog.

The Edit Project dialog opens, displaying the Project Members tab (see Figure 3.24).

•	To allow a user to access the project, click the + button to the right of a user's name in the left column. The user will be moved to the right column

•	To remove a user's access to a project, click the - button to the right of a user's name in the right column. The user will be moved to the left column.

When you're finished adding users to a project, click Save to save your changes and exit the dialog.

Creating an OpenStack User with EDB Ark Console Access

To create an OpenStack user account with access to the Ark console for a specific project, connect to the OpenStack console as a user with Administrative privileges and select Identity. Open the Users tab, and click the Create User button to open the Create User dialog (see Figure 3.25).

Figure 3.25 – The Create User dialog.

Complete the Create User dialog, providing information for the new user:

•	Specify the name of the user in the User Name field.

•	Specify the email address of the user in the Email field.

•	Specify the password associated with the user account in the Password field.

•	Re-enter the password in the Confirm Password field.

•	Use the drop-down listbox in the Primary Project field to select the project that will be displayed when the user connects. Please note that the Ark service account must have administrative privileges in the selected project.

•	Use the drop-down listbox in the Role field to specify if the new role is a _member_ or an admin user. Please note that _member_ roles will have sufficient privileges to access the Ark console.

When you've completed the dialog, click the Create User button to create the user and exit the dialog. The new user should now be able to access the Ark console

3.2.8 Connecting to the Administrative Console on an OpenStack Host

When you navigate to the URL of the installed Ark console that uses OpenStack to host clusters, the console will display a login dialog (see Figure 3.26).

Figure 3.26 - The Login dialog.

Enter the name of an administrative user in the User Name field, and the associated password in the Password field, and click Login to connect to the Ark console. If the user name and password provided are members of an OpenStack administrative role, the Ark console will include the DBA tab and the Admin tab (as shown in Figure 3.27).

Figure 3.27 - The EDB Ark Administrator’s console.

After connecting to the Ark console, you should:

•	Update the User tab, providing a Notification Email. For more information about the User tab, see the EDB Ark Getting Started Guide.

•	Use the Admin tab to create the server images and database engines that will be used by non-administrative users. For more information about using the Admin tab, see Section 4.1.