Introduction

Oracle TimesTen In-Memory Database (TimesTen) is a full-featured relational database that resides entirely in physical memory and is persistent and recoverable. It provides fast response times and high throughput to applications. TimesTen supports SQL, standard APIs, complete ACID properties, and replication for high availability. TimesTen is fully supported in Kubernetes environments and provides a richly functional operator. The TimesTen Kubernetes Operator (TimesTen Operator) lets you deploy, manage, and monitor active standby pairs of TimesTen Classic databases in your Kubernetes cluster. It also supports TimesTen's built-in cache functionality, allowing you to use TimesTen databases as a read-only or read-write cache for your Oracle database to improve response times for SQL queries.

An active standby pair replication scheme in TimesTen consists of two TimesTen databases. One database is the active, and the second database is the standby. Applications update the active database. The standby database is read-only and receives replicated updates from the active database. Only one of the two databases functions as the active database at any one time. If the active database fails, the standby database is promoted to be the active. After the failed (active) database is recovered, it becomes the standby database.


Active Standby Pair of TimesTen Databases

Oracle TimesTen In-Memory Database for Kubernetes - BYOL in Oracle Cloud Marketplace consists of a container image that contains TimesTen, its software prerequisites, and everything you need to run TimesTen in a containerized environment. The container image also includes the YAML manifest files and Helm charts needed to deploy the TimesTen Operator and create TimesTen databases.

This guide walks you through the steps to export the TimesTen container image and get access to the TimesTen container image by logging in to Container Registry and creating a Kubernetes Secret with the credentials needed for your Kubernetes cluster to access the container image in Oracle Cloud Infrastructure (OCI). It also provides references to the TimesTen documentation on extracting the manifest files, deploying the TimesTen Operator, and creating the TimesTen databases in your Kubernetes cluster.

Objectives

  • Export a TimesTen container image into a repository in Oracle Cloud Infrastructure Registry (Container Registry).

  • Log in to Container Registry on your development host and create a Kubernetes Secret to store the credentials that your Kubernetes cluster needs to access Container Registry.

Before You Begin

Before you begin using Marketplace, you should be familiar with Oracle Cloud. Also, ensure you have the following:

  • Access to an Oracle Cloud Infrastructure (OCI) tenancy. The tenancy must be subscribed to one or more of the regions in which Container Registry is available. See Availability by Region.

    Note:

    To log in to Container Registry, you will need the Object Storage namespace name of the tenancy. It can be found in the Tenancy Details page.

  • An OCI user that belongs to a group that can read and use Marketplace listings and manage repositories in Container Registry.

    Note:

    If your tenancy uses identity domains, you will need the name of the identity domain to log in to Container Registry. You are required to select the name of the identity domain associated with your user upon login to the OCI Console if your tenancy uses identity domains.

    The following Identity and Access Management (IAM) policies enable the specified group to read and use listings and manage repositories in the specified compartment:

    Allow group <group_name> to inspect all-resources in tenancy
Allow group <group_name> to manage app-catalog-listings in compartment <compartment_name>
Allow group <group_name> to use marketplace-listings in compartment <compartment_name>
Allow group <group_name> to read marketplace-workrequests in compartment <compartment_name>
Allow group <group_name> to manage repos in compartment <compartment_name>

    See Required IAM Policy.

  • An auth token for the OCI user. If you forgot your auth token or have yet to create one for your OCI user, see Getting an Auth Token.

  • A working Kubernetes cluster. If your cluster was not set up using Oracle Cloud Infrastructure Container Engine for Kubernetes (OKE), ensure that:

    • The cluster provides a StorageClass that can be used to request persistent volumes.

    • The nodes have their clocks synchronized through NTP or equivalent.

    See Creating Kubernetes Clusters Using Console Workflows.

  • A development host to access the Kubernetes cluster. The host can be a virtual machine (VM) instance in the same tenancy as your cluster. Ensure that:

    • The host resides outside the Kubernetes cluster.

    • The host is able to access and control the Kubernetes cluster. For this, ensure that the docker (or podman) and kubectl command line tools are installed on the host. See the Docker and kubectl documentation.

      If you decide to use the Helm charts provided by the container image, ensure that the helm command line tool is also installed. See the Helm documentation.

    See Setting Up Cluster Access.

Task 1: Export the TimesTen Container Image

To export the TimesTen container image from Marketplace:
  1. Sign in to your tenancy in Oracle Cloud Console (Console).
  2. In the top-left corner of the Console, expand the Navigation menu and click Marketplace. Then, click All Applications.
  3. Click the Oracle TimesTen In-Memory Database for Kubernetes - BYOL listing.

    To find the listing, you may use the filters and search bar as follows:

    • In Filters, in the Type drop-down list, select Container.

    • In the Publisher drop-down list, select Oracle.

    • In the Price drop-down list, select BYOL.

    • To narrow your search even further, in the search bar, type TimesTen.

  4. Click Export Package.
  5. Select a compartment with the appropriate IAM policies.
  6. Either select an existing repository or create a new one.

    If you decide to create a new repository:

    1. Provide a name for the repository.
    2. In Access, select either Private or Public.

      If you make the repository private, you (along with users belonging to the Administrators group of the tenancy) can perform any operation on the repository.

      If you make the repository public, any user with internet access and knowledge of the appropriate URL can pull images from the repository.

  7. Select the latest package version available.

    The version number corresponds to a release version of TimesTen.

  8. Review and accept the Partner terms and conditions.
  9. Click Export.

    The Export Package dialog closes and a pop-up window announces that a work request has been submitted. Follow the link provided by the pop-up window or the following step to verify that the work request completed successfully.

    Wait a couple of minutes for the work request to complete.

  10. Verify that the work request completed successfully.
    1. In the top-left corner of the Console, expand the Navigation menu and click Marketplace. Then, click Work Request.
    2. If successful, you should find a work request listed with the following:

      • Listing name: Oracle TimesTen In-Memory Database.

      • Package version: The package version selected in Step 7.

      • State: Succeeded.

      • Start time: Time matching the export request.

  11. Once the work request is complete, identify the tag and full path of the container image in the repository.

    You will need the tag and full path of the container image to deploy the TimesTen Operator. To identify them:

    1. In the top-left corner of the Console, expand the Navigation menu and click Developer Services. Then, under Containers and Artifacts, click Container Registry.
    2. In List scope, select the compartment associated with the repository.
    3. In Repositories and images, select the TimesTen container image under the name of the repository you selected (or created).

      Note:

      The list of images included in each repository may not load at first try. Try selecting the repository and once the details panel for the repository is loaded, you should be able to select the TimesTen container image from the drop-down list.

      The container image should be listed in the following format: 

      <repository_name>:<image_tag>

      where <image_tag> is composited as follows: 

      <unique_ID>-timesten-<package_version>

      For example, if you created a private repository named samplerepository with a container image of package version 22.1.1.23.0, then the container image should be listed as: 

      [-] samplerepository (Private) [1 image]
        samplerepository:<unique_ID>-timesten-22.1.1.23.0

      The full path of the image is under Image information. The path should be listed in the following format: 

      <tenancy_namespace>/<repository_name>:<image_tag>

      For example, if the samplerepository repository is associated with a tenancy named sampletenancy, then the full path of the image should be: 

      sampletenancy/samplerepository:<unique_ID>-timesten-22.1.1.23.0
You successfully exported the TimesTen container image.

Task 2: Get Access to the TimesTen Container Image

A Kubernetes Secret is an object that contains a small amount of sensitive data. Your Kubernetes cluster needs a secret containing your OCI user name and auth token to access the TimesTen container image in Container Registry.

To get access to the TimesTen container image on your development host and Kubernetes cluster:

  1. In a terminal window on your development host, log in to Container Registry.

    When you log in to Container Registry, your credentials are stored in your Docker configuration file: $HOME/.docker/config.json. 

    docker login <region_key>.ocir.io

    where <region_key> corresponds to the key for the region you are using for the repository. See Availability by Region.

    For example, to log in to Container Registry in the US West (Phoenix) region:

    docker login phx.ocir.io
    1. When prompted for a user name, enter your OCI user name in the following format:
      <tenancy_namespace>/<identity_domain>/<user_name>

      where:

      • <tenancy_namespace> is the Object Storage namespace name of the tenancy that owns the repository (as shown on the Tenancy Details page).

      • <identity_domain> is the name of the identity domain associated with your user. If your tenancy does not use identity domains and your user is federated with Oracle Identity Cloud Service, use OracleIdentityCloudService as identity domain.

      • <user_name> is your OCI user name for the tenancy.

      For example:

      sampletenancy/Default/john.smith@example.com

      If your identity domain is the Default, you can simply use:

      sampletenancy/john.smith@example.com
    2. When prompted for a password, enter the auth token for your OCI user.
  2. Create a Kubernetes Secret with the credentials stored in your Docker configuration file.
    kubectl create secret generic <secret_name> --from-file=.dockerconfigjson=$HOME/.docker/config.json \
        --type=kubernetes.io/dockerconfigjson

    Replace <secret_name> with a name of your choosing. For example, to create a Kubernetes Secret named sekret: 

    kubectl create secret generic sekret --from-file=.dockerconfigjson=$HOME/.docker/config.json \
        --type=kubernetes.io/dockerconfigjson

    Note:

    Consider writing down the name of the Kubernetes Secret. You need it to deploy the TimesTen Operator and create TimesTen databases.
You now have access to the TimesTen container image on your development host and Kubernetes cluster.

Next Steps

Now that you have a TimesTen container image in a repository in Container Registry and a Kubernetes Secret in your Kubernetes cluster to access Container Registry, you have all you need to deploy the TimesTen Operator and create TimesTen databases. You can either use the YAML manifest files or Helm charts included in the TimesTen container image to perform those tasks.

  1. Obtain the YAML manifest files and Helm charts for the TimesTen Operator, see Obtain TimesTen YAML Manifest Files and Helm Charts.

    While following the examples, where you create a new container, remember to replace the IMAGE argument in the examples with the region endpoint plus the full path of the container image. 

    docker create --name ttoper <region_key>.ocir.io/<tenancy_namespace>/<repository_name>:<image_tag>

    For example, for the samplerepository repository in the sampletenancy tenancy in the US West (Phoenix) region with a container image of package version 22.1.1.23.0, the command to create a new container should look like this: 

    docker create --name ttoper phx.ocir.io/sampletenancy/samplerepository:<unique_ID>-timesten-22.1.1.23.0

  2. Install the TimesTen Custom Resource Definitions (CRDs), see Install TimesTen CRDs.

  3. Deploy the TimesTen Operator, see Install the TimesTen Operator.

    Note:

    You can skip this step if you intend to use Helm to deploy the TimesTen Operator.

    While following the examples, where you customize the TimesTen Operator, remember to replace the value for name in imagePullSecrets with the name of the Kubernetes Secret you just created and the value for image in containers with the region endpoint plus the full path of the container image. 

    imagePullSecrets:
- name: <secret_name>
  containers:
    - name: timesten-operator
      image: <region_key>.ocir.io/<tenancy_namespace>/<repository_name>:<image_tag>

    For example, for the samplerepository repository in the sampletenancy tenancy in the US West (Phoenix) region with a container image of package version 22.1.1.23.0 and the sekret Kubernetes Secret, the operator.yaml file should include these values: 

    imagePullSecrets:
- name: sekret
  containers:
    - name: timesten-operator
      image: phx.ocir.io/sampletenancy/samplerepository:<unique_ID>-timesten-22.1.1.23.0

  4. Create TimesTen databases with the TimesTen Operator, see Create TimesTen Classic Databases.

    Note:

    You can skip this step if you intend to use Helm to create the TimesTen databases.

    While following the examples, where you create the YAML file to define the TimesTenClassic object, remember to replace the values for image and imagePullSecret in ttspec with the region endpoint plus the full path of the container image and the name of your Kubernetes Secret, respectively. 

    ttspec:
  image: <region_key>.ocir.io/<tenancy_namespace>/<repository_name>:<image_tag>
  imagePullSecret: <secret_name>

    For example, for the samplerepository repository in the sampletenancy tenancy in the US West (Phoenix) region with a container image of package version 22.1.1.23.0 and the sekret Kubernetes Secret, the YAML file should include these values: 

    ttspec:
  image: phx.ocir.io/sampletenancy/samplerepository:<unique_ID>-timesten-22.1.1.23.0
  imagePullSecret: sekret

  5. Alternatively, you can use Helm to deploy the TimesTen Operator and create the TimesTen databases, see Use Helm in Your TimesTen Kubernetes Operator Environment.

    Note:

    You can skip this step if you intend to use the YAML manifest files to deploy the TimesTen Operator and create the TimesTen databases.

    While following the examples, where you create the YAML files to define the configuration of the TimesTen Operator and TimesTen databases, remember to replace the values for repository and tag in image with the region endpoint plus the full path of the container image and the value for name in imagePullSecrets with the name of your Kubernetes Secret. 

    image:
  repository: <region_key>.ocir.io/<tenancy_namespace>/<repository_name>
  tag: <image_tag>
imagePullSecrets:
  - name: <secret_name>

    For example, for the samplerepository repository in the sampletenancy tenancy in the US West (Phoenix) region with a container image of package version 22.1.1.23.0 and the sekret Kubernetes Secret, the YAML files should include these values: 

    image:
  repository: phx.ocir.io/sampletenancy/samplerepository
  tag: <unique_ID>-timesten-22.1.1.23.0
imagePullSecrets:
  - name: sekret

Related Links

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customer access to and use of Oracle support services will be pursuant to the terms and conditions specified in their Oracle order for the applicable services.