Category Archives: Docker

Upgrade Oracle Kubernetes Engine on the the Oracle Cloud

Your Oracle Container Cluster is not automatically upgraded to new versions as the come out.  Automatically upgrading your cluster could cause problems if you’re running an application that would fail on a newer version.

However, the process to upgrade your Oracle Container Cluster is fairly straight forward.

Warning

Before you upgrade your Container Cluster, make sure all of your deployed apps will work with the version you intend to upgrade to.

Prerequisites

Open the Cluster details page

From your Oracle Cloud Dashboard

  1. Click the menu icon in the upper left.
  2. Find “Developer Services”.
  3. Click Container Services (OKE).
  4. Select the cluster you want to upgrade.

If there’s an upgrade available you’ll find a button next to the delete button on the details page.  Unfortunately, I had upgraded my cluster before I took a screenshot.  But, I used my amazing image editing skills to add a button to the picture below.

Push the upgrade button and you will see a list of the versions that are available.  You can upgrade 1 version at a time until you get to the current version.   If you’re upgrading across multiple versions, I recommend testing your deployed apps after each upgrade.

Worker Nodes

Worker nodes will not automatically upgrade with the master node.  If you have worker nodes that are more that 2 versions behind the master you will receive an error when you attempt to upgrade the cluster beyond that point.

I’m sure you could upgrade the worker nodes in your node pools manually, but I decided to take the easy route and…

Migrate to New Worker Nodes
  1. In your cluster details page, under resources, click “Node Pools”.
  2. Open your node pool details page.
  3. Under resources click nodes.
  4. For each node, collect the private IP and any custom settings, save them for later.  You could also keep this page open in a separate window.
  5. Go back to your cluster details page, and click the “Add Node Pool” button.
  6. Create a new pool using the same settings for the current pool and its nodes.
  7. Wait until all Nodes are “Ready”.
  8. In a terminal use kubectrl to drain the existing pool.
    Once the current pool is drained, Kubernetes should automatically move all of the pods from the drained pool into nodes in in the new pool.
    If you’ve manually assigned your pods to a specific node, you will need to move the pod manually. (Not covered here.)
  9. Open the Kubernetes API, make sure all of the pods are running on the new pool’s nodes.
  10. Go back to the Oracle Container Cluster details page, under resources, Open the drained node pool.
  11. Click “Delete Node Pool”.
  12. If you have multiple Node Pools, repeat these steps for each pool.

If your cluster was more than 2 versions behind you may have to repeat this process until you’re on the current version.

How To Connect your Node.js app in Docker to your Oracle Database

In this post I’ll cover how to make a connection from a Node.js application in a Docker container to your Oracle Database in three different scenarios.

  • Typical Database connection.
  • Database inside a different Docker container.
  • Oracle Autonomous Transaction Processing Cloud Database.

Simple Test App

When attempting something new, I find it’s best to make sure all of the pieces that are not part of the new thing, are as simple as possible.

For my examples I will be using a small Node.js application that:

  • Connects to the Oracle Database.
  • Runs a simple query.
  • Prints the results to the console.

Create a new file named dbConfig.js to set the database connection information.

Create a new file named server.js used to test the connection.

Install the node-oracledb driver. (If you have any questions about the node-oracledb driver, you can find the answers here.)

Create environment variables for the connection information.  (Replace my values with yours)

Test the Node.js application.  You should see something similar to the following.

Create a Docker Container for the Node.js app

Create a Dockerfile

Build the image

Now that you have an image you’ll run a container and to connect it to:

Typical Oracle Database
The container will run, execute the query and stop.  You should see something similar to this output.
An Oracle Database inside a Docker Container

In a previous post I walked through how to setup both an ORDS instance and an Oracle XE instance in Docker Containers.  Follow through the section showing how to create an Oracle XE Database in a Docker container.

When you followed the steps in that post you should have also created a Docker Network.

You’ll use that same network to connect from the Node.js container to the Oracle XE container.

First, change your NODE_ORACLEDB_CONNECTIONSTRING environment variable to use the Oracle XE container name.

Now when you run a new docker container you will attach it to the same Docker Network as the Oracle XE container.

The container will run, execute the query and stop.  You should see something similar to this output.

Since both containers are using the same Docker network, you do not need to open the port when you run the Oracle XE container.  This is useful if you’d like to keep your database private inside the Docker environment.

Oracle Autonomous Transaction Processing Cloud Database

After you create an Oracle ATP Cloud Database you’ll need to download the credentials file and extract it into a secure location.

For this database, you will be using an entry in the tnsnames.ora file to make the database connection.  Change the NODE_ORACLEDB_CONNECTIONSTRING environment variable to use the tnsnames entry:

Before you run the container, you need to modify the sqlnet.ora file found in the credentials directory.  Change the wallet location to the value that will be mapped inside the Docker container.

When you run the new container for the node app you will map a volume from the directory where you extracted your credentials file to the internal container directory.  Mapping a volume makes sure that there is not a copy of the credential files inside the Docker container.

Finally, when you run the new container, you will add an additional environment variable defining where the tns admin information is located.

The full command looks like this:

The container will run, execute the query and stop.  You should see something similar to this output.

I used the same docker image for all of the examples

You may have noticed that you only built the Docker image once at the beginning of the post.  The application in the Docker image uses environment variables to connect to the database.  This allows you to run the same application in one or more containers and each container can connect to different Oracle Databases without having to rebuild the image.

Quick and Easy Setup – Oracle Xe and ORDS Using Docker

In this post I’ll show you how to stand up a couple of Docker containers running Oracle Database Xe and Oracle REST Data Services.

I will assume you are familiar with using Docker.  If not checkout this getting started guide.

Required Downloads

Oracle docker-images repository

Oracle provides a GitHub repository with a log of great examples.  Clone repository into the directory where you want to work.

Oracle Xe

You can find more information about Oracle Xe at https://www.oracle.com/rest.

Download the installer and place it in the docker-images/OracleDatabase/SingleInstance/dockerfiles/18.4.0 directory.

I’ll be using oracle-database-xe-18c-1.0-1.x86_64.rpm .

Oracle Rest Data Services (ORDS)

You can find more information about ORDS at https://www.oracle.com/rest.

Download the installer and place it in the docker-images/OracleRestDataServices/dockerfiles directory.

I’ll be using ords-19.1.0.092.1545.zip .

ORDS runs in Java, so you’ll need a Java JRE.  Download the Server JRE and place it in the docker-images/OracleJava/java-8 directory.

I’ll be using server-jre-8u211-linux-x64.tar.gz .

Docker Network

We’ll be running the database and ORDS in separate docker containers.  Define a docker network that they will use to communicate.

Oracle Database Xe

Change into the docker-images/OracleDatabase/SingleInstance/dockerfiles/18.4.0 directory.  Make sure the Oracle Xe install file (oracle-database-xe-18c-1.0-1.x86_64.rpm)  is in this directory.

This directory contains a Dockerfile.xe ready for us to use.  Take a minute and read through the file to see what it is going to do.

Build the Oracle Database Docker Image

The repository includes a shell script (buildDockerImage.sh) that you can use to build the docker image for Xe and other Oracle Databases.

It can be found in the docker-images/OracleDatabase/SingleInstance/dockerfiles directory.  Instructions for using this script can be found here.

I won’t be using the shell script.

The shell script will generate and run something similar to the following command that I will use:
*Notice the dot at the end, this is not a typo.

You can find an explanation of the Docker Build parameters here.

If this command doesn’t work for you, try using the shell script.

Verify that your image was created:

You should see something like this:

Once you have created the docker image it’s time to

Create a Docker Container

The following command is similar to the command you’ll find on the GitHub repository, but I’ve added a ‘-d’ to run the container in detached mode and I’m not defining any data volumes so my data will not persist when I delete the container.

You can find more information on the docker run command parameters here.

This will take a few minutes.

You can watch the progress and troubleshoot any issues with with this command:
(You can use the container name or id.)

When the last line of the log looks like this, you are ready to proceed.

Verify that your container was created and is up:

You should see something like this:

Now try to connect to your new Oracle Xe Database.

To connect with SQLcl:

Oracle REST Data Services

Before we create the ORDS container, we need to create a Docker image with Oracle Linux 7 and a Java JRE installed.  We will use this as a base image to build on top of.

Oracle Linux 7 and Java JRE Base Image

Change into the docker-images/OracleJava/java-8 directory.  In there you will find a Dockerfile and the server-jre-8uXXX-linux-x64.tar.gz file you downloaded earlier.

Take a minute and read through the Dockerfile to see what it is going to do.

Run the following to build the image:
*Notice the dot at the end, this is not a typo.

We do not need to create a Docker container from this image.  We will only need the image as a base for the ORDS image.

Verify that your image was created:

You should see something like this:

Now we can create the ORDS image.

ORDS

Change into the docker-images/OracleRestDataServices/dockerfiles directory.  In there you will find a Dockerfile and the ords-19.1.0.092.1545.zip file you downloaded earlier.

Take a minute and read through the Dockerfile to see what it is going to do.

Pre-Checks

Verify that the docker network we created earlier is ready:

You should see something like this.

Make sure your Xe database is running with the docker ps  command above.

If the Xe database container is not started, start it with the following command:

Build the ORDS Docker Image

The repository includes a shell script (buildDockerImage.sh) that you can use to build the ORDS docker image.

It can be found in the docker-images/OracleRestDataServices/dockerfiles directory.  Instructions for using this script can be found here.

If you choose to run the shell script instead of the below command, and there is not a Checksum file included for the version of ORDS you are installing, use the -i 1 command line argument to ignore the check.

The shell script will generate and run something similar to the following:
*Notice the dot at the end, this is not a typo.

Verify that your image was created:

You should see something like this:

Now we can create the ORDS container.

Create an ORDS Docker Container

The following command is similar to the command you’ll find on the GitHub repository, but I’ve added a ‘-d’ to run the container in detached mode and I’m not defining any data volumes so my data will not persist when I delete the container.

Make sure that you set  -e ORACLE_HOST=oracleXe to the name you used for the Oracle Xe Database container you created above.  ORDS will not find your database if you use localhost.  The containers are basically separate servers running on the same network --network=OrdsXeNet .

The parameter -e ORACLE_PWD="Password1_One" is the SYS/SYSTEM password you used when you created the Oracle Xe Database above.

The parameter -e ORDS_PWD="ORDS_Password1"  will be used as the ORDS admin password.  It does not need to be the same as the database password.

Verify that your container was created and is up:

You should see something like this:

You should now have an Oracle Xe database up and running in one container and an ORDS instance running in the other.

Connect to your database and test that ORDS is properly installed and configured.  A quick way to tell using Oracle SQL Developer is:

  1. Create a new database user.
  2. Connect as that user.
  3. Right click on the connection.
  4. Look towards the bottom of the menu for “REST Services”.

Have fun creating your new REST modules!