This chapter explains how to use direct mode applications and Client/Server drivers to access and to use your TimesTen databases that reside in your Kubernetes cluster.
Topics:
You can run direct mode applications inside of the Pods in your TimesTenClassic deployment. When configured, each Pod in your active standby pair runs two or more containers. One container runs TimesTen and the TimesTen agent and the other container(s) run whatever applications you choose. These applications that are running in your containers can then use TimesTen in direct mode. For information on direct mode applications, see "Managing TimesTen Databases" in the Oracle TimesTen In-Memory Database Operations Guide.
TimesTen Pods are created with the Kubernetes shareProcessNamespace option. This option allows direct mode applications running in other containers within the same Pod to function.
Note:
The standard security issues that surround direct mode apply in this environment as in a non-Kubernetes environment. Segregating your applications into separate containers from TimesTen is intended for ease of management and ease of upgrade. It is not intended as a security barrier and provides no additional security.The .spec.template.spec.containers attribute of your TimesTenClassic object can be specified to cause one or more containers to be created within each Pod in your active standby pair. These containers are created in addition to the tt container that runs TimesTen. The containers run the specified command in the container image.
This example illustrates how to include the .spec.template.spec.containers attribute in your TimesTenClassic object (represented in bold):
apiVersion: timesten.oracle.com/v1 kind: TimesTenClassic metadata: name: directmode spec: ttspec: storageClassName: oci storageSize: 250G image: phx.ocir.io/youraccount/tt1814110:3 imagePullSecret: sekret dbConfigMap: - directmode template: spec: containers: - name: yourapp image: phx.ocir.io/youraccount/yourapplication:1 command: ["/bin/yourapp"] - name: anotherapp image: phx.ocir.io/youraccount/anotherapplication:1 command: ["/bin/anotherapp"]
You can specify any other Kubernetes configuration for these containers just as you could in the .spec.template.spec.containers attribute of the Kubernetes StatefulSet object. For example, you could use the resources attribute to set CPU and memory limits for your containers. See "Resources specification for the tt and the daemonlog containers" for information on the resources attribute. The Operator automatically adds appropriate mounts to the containers you specify. This enables your containers to access TimesTen.
To use TimesTen in direct mode, your application containers must know how TimesTen is configured in the tt container. You must configure your application containers similarly. See "Understanding how the Operator functions" for information on TimesTen containers and specifically the tt container.
In particular:
The name of the TimesTen users group is oracle with a group ID (GID) of 333. For more information on the TimesTen users group, see "Understanding the TimesTen users group" in the Oracle TimesTen In-Memory Database Installation, Migration, and Upgrade Guide.
TimesTen runs as the oracle operating system user (with UID of 333). This oracle user is a member of the TimesTen group.
You must configure your application containers to run your applications as a member of the TimesTen group with GID of 333. Only members of this group can run TimesTen in direct mode.
You can run your direct mode applications as a user with UID of 333. However, this grants the application instance administrator permissions on the TimesTen instance. Alternatively, you can create a group with GID of 333 and then create a user whose primary or secondary group is that group, but with a UID that is not 333. In the latter case, you can run your application as this user and you can use TimesTen in direct mode. You can then grant such a user privileges up to and including the ADMIN privilege. For more information on primary and secondary groups, see "Creating an installation on Linux/UNIX" in the Oracle TimesTen In-Memory Database Installation, Migration, and Upgrade Guide. For information on TimesTen privileges, see "System privileges" and "Object privileges" in the Oracle TimesTen In-Memory Database SQL Reference.
The direct mode application must use the TimesTen instance that is configured at /tt/home/oracle/instances/instance1. The scripts to configure the TimesTen environment variables are located at /tt/home/oracle/instances/instance1/bin/ttenv.*.
You must not modify any file that is located in the TimesTen instance. In addition, ensure you do not create any new files in the $TIMESTEN_HOME directory tree of the instance.
There are two DSNs that have been configured. They are located in the /tt/home/oracle/instances/instance1/conf/sys.odbc.ini file. One DSN has the name of the TimesTenClassic object. The second is called tt. You can use either one. They are equivalent.
You must not add entries to the /tt/home/oracle/instances/instance1/conf/sys.odbc.ini file. These files can be overwritten by the Operator. However, you can store your own DSN entries in the $HOME/.odbc.ini file located in your application container.
You must not create additional TimesTen databases.
Kubernetes, not the Operator, is responsible for monitoring and managing the life cycle of the direct mode containers. In particular:
Applications are started by Kubernetes regardless of the state of TimesTen (located in its own container). Kubernetes manages the life cycle of containers individually. It does not sequence. Your application must know how to wait for TimesTen to become available.
A direct mode application runs in the Pod containing the active TimesTen database and in the Pod containing the standby TimesTen database. The application may need to use the ttRepStateGet built-in procedure to determine whether it is running on the active or on the standby and perhaps quiesce itself on the standby. For more information on the ttRepStateGet built-in procedure, see "ttRepStateGet" in the Oracle TimesTen In-Memory Database Reference.
Kubernetes may start the application before the TimesTen database exists or before it is loaded into memory and ready for use. It is the responsibility of the direct mode application to verify the state of the TimesTen database in its Pod and to use it appropriately.
If your application exits, the container terminates, and Kubernetes spawns another container. This does not impact TimesTen that is running in the tt container.
Applications that are running in other Pods in your Kubernetes cluster can use your TimesTen database by using the standard TimesTen Client/Server drivers. You must configure your application containers with a TimesTen client instance. That instance must contain a configured $TIMESTEN_HOME/conf/sys.odbc.ini file, or your application must use an appropriate Client/Server connection string.
For example, if you chose to configure a sys.odbc.ini file, the contents of sys.odbc.ini would contain a client DSN definition that references the Pods that are running your TimesTen databases.
This example creates the sample DSN and references the sample TimesTenClassic object in the default namespace.
% vi $TIMESTEN_HOME/conf/sys.odbc.ini [sample] TTC_SERVER_DSN=sample TTC_SERVER1=sample-0.sample.mynamespace.svc.cluster.local TTC_SERVER2=sample-1.sample.mynamespace.svc.cluster.local
Applications connect to the TimesTen database using this DSN. In the active standby pair configuration, TimesTen automatically routes application connections to the active database. (sample-0 and sample-1 are used for example purposes.)
Client/Server applications must connect to the database using a defined username and password. The Operator can create such a user with ADMIN privileges. You can then connect to the database, as that user, to create other users and grant these users the CREATE SESSION privilege. See "Understanding the configuration metadata and the Kubernetes facilities" for information on how to have the Operator create an initial user with ADMIN privileges.
In this example, use a connection string to connect to the sample database as the scott user. (If you use a connection string that requires all the required connection attributes, you do not need to define them in the sys.odbc.ini file.) The scott user was created by the Operator and already exists in the sample database. After connecting, you can verify that the scott.emp table exists. (The Operator also previously created this table. See "schema.sql file" for information on how the Operator created this table.)
% ttIsqlCS -connstr "TTC_SERVER1=sample-0.sample.mynamespace.svc.cluster.local; TTC_SERVER2=sample-1.sample.mynamespace.svc.cluster.local; TTC_SERVER_DSN=sample;UID=scott;PWD=tiger"; Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved. Type ? or "help" for help, type "exit" to quit ttIsql. connect "TTC_SERVER1=sample-0.sample.mynamespace.svc.cluster.local; TTC_SERVER_DSN=sample;uid=scott;pwd=********"; Connection successful: DSN=;TTC_SERVER=sample-0.sample.mynamespace.svc.cluster.local; TTC_SERVER_DSN=sample;UID=scott;DATASTORE=/tt/home/oracle/datastore/sample; DATABASECHARACTERSET=AL32UTF8;CONNECTIONCHARACTERSET=US7ASCII;PERMSIZE=200; DDLREPLICATIONLEVEL=3; (Default setting AutoCommit=1) Command> tables; SCOTT.EMP 1 table found.