Menu Close

Quick Start Guide

Red Hat OpenShift Database Access 1

Service Preview Release

Red Hat Data Services Documentation Team

Abstract

This quick start guides administrators and developers through how to configure, and connect to an external MongoDB Atlas, Crunchy Data Bridge, or CockroachDB database instance using OpenShift Database Access.
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright's message

Preface

Important

The Red Hat OpenShift Database Access is a Service Preview release add-on that enables:

  • Easy consumption of database-as-a-service (DBaaS) offerings from partners including MongoDB Atlas, Crunchy Bridge, and CockroachDB directly from managed OpenShift clusters.
  • Easy management, monitoring and control by administrators of cloud-hosted DBaaS including consumption, usage, and status.

Red Hat OpenShift Database Access (OpenShift Database Access) is a Service Preview release. A Service Preview release contains features that are early in development. Service Preview releases are not production ready and might have features and functionality that are not fully tested. You are advised not to use OpenShift Database Access for production or business-critical workloads.

To provide feedback or inform our engineering team of any technical issues with OpenShift Database Access, please use dbaas-alpha-support@redhat.com.

Chapter 1. Installing the Red Hat OpenShift Database Access add-on

The Red Hat OpenShift Database Access add-on allows you to configure a connection to cloud-database providers, create new database instances, and connect database instances to applications for developers to use.

Procedure

  1. Log into the Red Hat Hybrid Cloud Console with your credentials.

    Red Hat Hybrid Cloud Console login page

  2. Click OpenShift from the navigation menu.

    Selecting OpenShift from the navigation menu
  3. Click Clusters to display a list of your clusters. Select a cluster name from the list to add database access to.

  4. Click Add-ons, and select the Red Hat OpenShift Database Access tile.

    Selecting the Red Hat OpenShift Database Access tile

  5. Click Install.

    The Red Hat OpenShift Database Access installation button

  6. Wait for the installation process to finish. Once the add-on installation completes successfully, a green checkmark appears on the tile.

    Green checkmark showing that the add-on installation has completed successfully

Chapter 2. Accessing the database access menu for configuring and monitoring

You can access the Red Hat OpenShift Database Access page from the OpenShift console navigation menu to select the correct project namespace for importing a cloud-database provider account.

Important

If using MongoDB Atlas as a cloud-database provider, then you must add the IP address of the application pod to MongoDB Atlas' IP Access List. If the IP address is not in the IP Access List, then a 504 gateway timeout error occurs. Visit the MongoDB Atlas website for more details on adding an IP address to your database project.

Prerequisites

Procedure

  1. Log into the OpenShift console.

  2. To select the correct project namespace follow these sub-steps.

    Single page screenshot of the administrator’s entry point
    1. Select the Administrator perspective First callout .

    2. Expand the Data Services navigation menu, and click Database Access Second callout .

      Note

      You might need to scroll down the navigation menu.

    3. Click the Project dropdown menu and then enable the Show default projects switch Third callout .
    4. Type dbaas in the search field.

    5. Select redhat-dbaas-operator or openshift-dbaas-operator project namespace Fourth callout .

      From the database inventory page you can monitor the database environment, import cloud-hosted database provider accounts, or create new database instances.

      Database inventory landing page

Chapter 3. Accessing the developer workspace and adding a database instance

You can access the developer workspace in the OpenShift console to manage connectivity between database instances and applications.

Prerequisites

  • Installation of the OpenShift Database Access add-on.
  • Import at least one cloud-database provider account.

Procedure

  1. Log into the OpenShift console.

  2. Access the developer workspace, and select or create your project, then select a cloud-hosted database provider to add to your project:

    Single page screenshot of the developer’s entry point
    1. Select the Developer perspective First callout .
    2. Click +Add Second callout .
    3. Click the Project dropdown menu Third callout .
    4. Create a new project or search for your application’s project Fourth callout .
    5. Select the Cloud-Hosted Databases tile to connect to a cloud-database provider Fifth callout .
  3. Select your cloud-hosted database provider tile.
  4. Click Add to Topology.
  5. Select a previously configured Provider Account for this database instance from the dropdown menu.
  6. Select the database instance ID you want to use, and then click Add to Topology.
  7. Click Continue. Upon a successful connection, you are taken to the Topology page.

Chapter 4. Connecting an application to a database instance using the topology view

You can add a database to an application by making a connection to the database instance from the cloud-database provider. On the Topology page, you see the application, along with the new database instance.

Procedure

  1. Click and drag the arrow from the application to the new database instance to create a binding connector.

    The topology view of the application and the database with a dotted line arrow indicating database binding in the process of being dragged from the database to the application

  2. On the pop-up dialog, click Create. Once the binding is created, the application pod restarts. After the application pod restarts, your application now has database connectivity.

    The topology view of the application and the database with a solid line arrow indicating database binding to the application is complete

    This binding visually represents the injection of database connection information and credentials into the application pod.

  3. Use a service binding library based on your application’s framework to consume the service binding information and credentials.

Additional Resources

Appendix A. Find your MongoDB Atlas account credentials

You need the Organization ID, the Organization Public Key, and the Organization Private Key to create a provider account resource for MongoDB Atlas.

Important

If using MongoDB Atlas as a cloud-database provider, then you must add the IP address of the application pod to MongoDB Atlas' IP Access List. If the IP address is not in the IP Access List, then a 504 gateway timeout error occurs. Visit the MongoDB Atlas website for more details on adding an IP address to your database project.

Procedure

  1. From the MongoDB Atlas home page, Sign In to your account.

  2. From your account home page:

    Single screenshot for finding your Organization ID value
    1. Select Organization from the dropdown menu First callout .
    2. Click Settings from the Organization navigation menu Second callout .

    3. Copy the Organization ID value Third callout .

      Note

      In some cases your organization ID may be hidden by default.

  3. Next, from the account home page:

    Single screenshot for finding your API keys
    1. Click Access Manager from the Organization navigation menu First callout .
    2. Click API Keys Second callout .
    3. If you have existing API keys, you can find them listed here. Copy the API public and private keys for the import provider account fields. Also, verify that your API keys have the Organization Owner and Organization Member permissions Third callout Fourth callout .
  4. If you need new API keys, click Create API Key, and proceed to the next step.
  5. On the Create API Key page, enter a Description, and under the Organization Permissions dropdown box select the Organization Owner and Organization Member permissions. Click Next.
  6. Copy the API public and private keys for the import provider account fields.

Appendix B. Find your Crunchy Data Bridge account credentials

You need the Public API Key, and the Private API Secret to create a provider account resource for Crunchy Data Bridge.

Procedure

  1. From the Crunch Data Bridge Log in page, sign in to your account.

  2. From your personal account home page, click Settings, and then click Settings from the navigation menu.

    Crunchy Data Bridge settings on the navigation menu

  3. Copy the Application ID and Application Secret values for the import provider account fields.

    Crunchy Data Bridge API key and secret values

Appendix C. Find your CockroachDB account credentials

You need the API Key to create a provider account resource for CockroachDB.

Prerequisites

Currently, access to the Service Accounts tab on the Access Management page is enabled by invite only from CockroachDB. To expose the Service Accounts tab on the Access Management page, you can request that this feature be enabled. Contact CockroachDB support and ask for the Cloud API to be enabled in the CockroachDB Cloud Console for your user account.

Additionally, you can view this quick video tutorial from Cockroach Labs on creating an account.

Procedure

  1. From the CockroachDB service account page, log in to your account.
  2. From your service account home page, select Access from the navigation menu.
  3. Click Service Accounts from the Access Management page.
  4. Click Create Service Account.

  5. Enter an Account name, select the Permissions, and click Create.

    Step 1 for creating a service account

  6. Enter an API key name, and click Create.

    Step 2 for creating a service account

  7. Copy the Secret key for the import provider account field, and click Done.

    Step 3 for creating a service account

Appendix D. Deleting a database provider account

Instead of directly editing your cloud-hosted database provider account information, Red Hat recommends you delete the provider account, and recreate a new one.

Procedure

  1. Log into the OpenShift console.
  2. Select the Administrator perspective from the navigation menu.
  3. Expand the Operators navigation menu, and click Installed Operators.
  4. Click OpenShift Database Access Operator from the list of installed operators.
  5. Select Provider Account.
  6. Click the vertical ellipsis for the database provider account you want to delete, and click on Delete DBaaSInventory.
  7. A dialog box appears to confirm the deletion, click Delete.
  8. After deleting the database provider account, you can recreate the database provider account by clicking Create DBaaSInventory.

Appendix E. Service binding libraries

The Kubernetes service binding feature was introduced to bring consistency to the way secrets are shared for connecting applications to external services, such as REST APIs, databases, and many other services. OpenShift Database Access leverages the service binding feature to bring a low-touch administrative experience to provisioning, and managing access to external database services. The service binding feature enables developers to connect their applications to database services with a consistent, and predictable experience. Specifically, a service binding creates a volume on the application pod, and organizes the information to make a connection to the database in a directory structure. The volume mount point is exposed as an environment variable. Developer frameworks, such as Quarkus, are service binding aware, and can automatically connect to a database using this exposed workload information without needing to embed database connection information in the application source code.

Here are some application examples on how to use a service binding library:

Additional resources

Legal Notice

Copyright © 2022 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.