This chapter describes the process for setting up the TimesTen Operator.
Note that it is possible to use the Operator in an environment where nothing is allowed to run as root. If this is your desired environment, see Appendix C, "Run Containers as Non-Root" for the procedures to set up such an environment. You do not need to perform the procedures in this chapter if you choose to do the procedures in the Appendix.
Topics:
Complete these prerequisites before installing the TimesTen Operator:
Ensure you have a working Kubernetes cluster.
The Operator and the CRD are developed using the Oracle Cloud Infrastructure Container Engine for Kubernetes (referred to as OKE) with clusters provisioned using Quick Create. (OKE release 1.14 or later). See "Introducing the TimesTen Operator" for information on the Operator and the CRD.)
Your cluster must provide a StorageClass that can be used to request PersistentVolumes. Each Pod that runs TimesTen uses a PersistentVolume to store the TimesTen database that it manages. You must know the name of this storage class. For example, in OKE, you can use the oci storage class. For more information on Storage Classes, see:
https://kubernetes.io/docs/concepts/storage/storage-classes/
The nodes in your cluster must have their clocks synchronized through NTP or other means.
Ensure you have a Linux development host to access the Kubernetes cluster. This development host must reside outside the Kubernetes cluster, and you must be able to access and to control the Kubernetes cluster from this host. On it, you must install:
The kubectl command line tool: You use the kubectl command line tool to control and mange the Kubernetes cluster.
The docker command line tool: You use the docker command line tool to create images and to push the images to the image registry.
Ensure you have access to an image registry.
You need an image registry to run containers in a Kubernetes cluster. You use this registry to store container images that will then be run by Kubernetes. For example, when you use a Kubernetes cluster in OKE, you may consider using the Oracle Container Image Registry (OCIR). You can use other image registries, as well.
The development host needs to be able to push images to the registry using the docker push command.
The Kubernetes cluster needs to be able to pull images from the registry using an image pull secret.
You must be able to pull base operating system images from image registries.
You must download the TimesTen full distribution on Linux-64 bit in order to use the TimesTen Operator.
Perform these steps to download the full distribution of TimesTen and then unpack the TimesTen Operator distribution that is embedded within it. Perform all steps from your Linux development host.
From the directory of your choice:
Create one subdirectory into which you will download the TimesTen full distribution. For example, create the installation_dir subdirectory. (The installation_dir directory is used in the remainder of this book.)
Create a second subdirectory into which you will unpack the TimesTen Operator distribution. For example, create the kube_files subdirectory. (This kube_files directory is used in the remainder of this book.)
% mkdir -p installation_dir % mkdir -p kube_files
You are now ready to download and unpack the TimesTen full distribution.
Navigate to installation_dir.
% cd installation_dir
Download the TimesTen full distribution into this directory. As an example, download the timesten1814110.server.linux8664.zip file, (the 18.1.4.11.0 full distribution for Linux 64-bit).
From the installation_dir, use the ZIP utility to unpack the TimesTen distribution.
% unzip timesten1814110.server.linux8664.zip Archive: /timesten/installation/timesten1814110.server.linux8664.zip creating: tt18.1.4.11.0/ creating: tt18.1.4.11.0/ttoracle_home/ ... creating: tt18.1.4.11.0/kubernetes/ ...
You successfully unpacked the TimesTen full distribution.
Note that the installation_dir/tt18.1.4.11.0/kubernetes directory is created. The operator.zip file is located in this directory. For example, this is a sample directory structure after unpacking the distribution:
% pwd
installation_dir/tt18.1.4.11.0
% dir
3rdparty include lib oraclescripts README.html ttoracle_home
bin info network PERL startup
grid kubernetes nls plsql support
Navigate to the kube_files directory and unpack the operator.zip file into it. In this example, unpack the installation_dir/tt18.1.4.11.0/kubernetes/operator.zip file.
% cd kube_files % unzip installation_dir/tt18.1.4.11.0/kubernetes/operator.zip [...UNZIP OUTPUT...]
You successfully unpacked the installation_dir/tt18.1.4.11.0/kubernetes/operator.zip file into the kube_files directory.
Review the directory structure. Later in this chapter, you will modify some of the files in these subdirectories. This example shows the most important subdirectories and files, which can change from release to release.
README.md deploy/crd.yaml deploy/operator.yaml deploy/service_account.yaml operator/Dockerfile operator/timestenclassic-operator ttimage/agent2 ttimage/.bashrc ttimage/create1.sql ttimage/create2.sql ttimage/Dockerfile ttimage/get1.sql ttimage/pausecq.sql ttimage/repcreate.sql ttimage/repduplicate.sql ttimage/runsql,sql ttimage/starthost.pl ttimage/.ttdotversion ttimage/.ttdrop
Note:
This directory tree must persist through the lifetime of the TimesTen Operator.In addition, do not delete the TimesTen full distribution file (timesten1814110.server.linux8664.zip, in this example). You need to copy this file into the:
/operator directory to build the Operator image and push the image to the image registry. See "Building the Operator image" for details.
/ttimage directory to build the TimesTen image and push the image to the image registry. See "Building the TimesTen image" for details.
You successfully downloaded and unpacked the TimesTen Operator distribution.
The Operator runs by using a Kubernetes service account. This service account needs permissions and privileges in your namespace. These permissions and privileges are granted through a role. The service_account.yaml file adds the service account and the role to your namespace, and grants the service account the privileges that are specified in the role. The service_account.yaml file is provided in the operator.zip file you previously unpacked.
Perform these steps:
Navigate to the kube_files/deploy directory.
% cd kube_files/deploy
Create the service account.
% kubectl create -f service_account.yaml role.rbac.authorization.k8s.io/timestenclassic-operator created serviceaccount/timestenclassic-operator created rolebinding.rbac.authorization.k8s.io/timestenclassic-operator created
The service_account.yaml file created the timestenclassic-operator service account and the timestenclassic-operator role in your namespace, and granted the service account the privileges specified in the role.
Kubernetes supports objects, such as Pods and StatefulSets. The Kubernetes API can be extended to create customized object types. This step adds a new object type, called TimesTenClassic, to your cluster.
Navigate to the kube_files/deploy directory, and then use the kubectl create command to create the TimesTenClassic customized resource definition (CRD) in your Kubernetes cluster.
% cd kube_files/deploy
% kubectl create -f crd.yaml
customresourcedefinition.apiextensions.k8s.io/
timestenclassics.timesten.oracle.com created
You successfully added the TimesTenClassic object type to your Kubernetes cluster.
Kubernetes Operators are Pods that run a customized image. Before you can run the Operator, you must build this image and push it to your image registry.
The files needed to create the image are provided in the kube_files/operator directory (part of the ZIP file you previously unpacked). In the kube_files/operator directory are the Dockerfile and the binaries needed to create the Operator image.
To build the Operator image and push it to your registry, perform these steps:
Navigate to the kube_files/operator directory, and copy the TimesTen distribution into it. This example assumes you downloaded the timesten1814110.server.linux8664.zip distribution into the installation_dir directory. See "Downloading TimesTen and the TimesTen Operator" for information. Then, verify the timesten1814110.server.linux8664.zip file is in the kube_files/operator directory.
% cd kube_files/operator % cp installation_dir/timesten1814110.server.linux8664.zip . % ls -a Dockerfile timesten1814110.server.linux8664.zip timestenclassic-operator
Navigate to the kube_files/operator directory (if not already in this directory) and use the docker command to build the Operator image. You can choose any name for ttclassic-operator:3 (represented in bold in this example). Note that the output may change from release to release.
% cd kube_files/operator % docker build -t ttclassic-operator:3 . Sending build context to Docker daemon 478.6MB Step 1/7 : FROM container-registry.oracle.com/os/oraclelinux:7 ---> d788eca028a0 Step 2/7 : ARG TT_DISTRO=timesten1814110.server.linux8664.zip ---> Using cache ---> a259a93fe906 Step 3/7 : RUN yum -y install openssl unzip && /usr/sbin/useradd -d /tt-operator -m -u 1001 -s /bin/nologin -U tt-operator ---> Using cache ---> e3f1427246ab Step 4/7 : COPY --chown=tt-operator:tt-operator timestenclassic-operator /usr/local/bin/timestenclassic-operator ---> Using cache ---> 6ccad53230f0 Step 5/7 : COPY --chown=tt-operator:tt-operator $TT_DISTRO /tt-operator/ $TT_DISTRO ---> 5cd31705485a Step 6/7 : USER tt-operator ---> Running in 6a773ddac5dd Removing intermediate container 6a773ddac5dd ---> 875ee38ebc75 Step 7/7 : ENTRYPOINT ["/usr/local/bin/timestenclassic-operator"] ---> Running in fed0f6c94c2f Removing intermediate container fed0f6c94c2f ---> 10dde79e1617 Successfully built 10dde79e1617 Successfully tagged ttclassic-operator:3
Use the docker command to tag the Operator image.
Replace phx.ocir.io/youraccount with the location of your image registry. (phx.ocir.io/youraccount is represented in bold in this example.)
Replace ttclassic-operator:3 with the name you chose in the previous step. (ttclassic-operator:3 is represented in bold in this example.)
% docker tag ttclassic-operator:3 phx.ocir.io/youraccount/ttclassic-operator:3
Use the docker command to push the Operator image to your registry.
Replace phx.ocir.io/youraccount with the location of your image registry. (phx.ocir.io/youraccount is represented in bold in this example.)
Replace ttclassic-operator:3 with the name you chose in the previous steps. (ttclassic-operator:3 is represented in bold in this example.)
% docker push phx.ocir.io/youraccount/ttclassic-operator:3 The push refers to repository [phx.ocir.io/youraccount/ttclassic-operator] 46458e9fc890: Pushed 471a399f0540: Pushed 9e51a2b82af3: Pushed 2f915858a916: Layer already exists 3: digest: sha256:9b941f12e3d52298b9b38f7766ddcdfb1d011857a990ff01a8adafd32f3d3e8d size: 1166
You successfully built the Operator image and pushed it to your image registry.
This section covers the steps to customize, and then deploy the Operator. It also provides the commands to verify that the Operator is running.
To customize the Operator for your namespace, navigate to the kube_files/deploy directory, and edit the operator.yaml file. This file is provided in the distribution that you previously unpacked. See "Downloading TimesTen and the TimesTen Operator" for details.
Modify these fields represented in bold (in the operator.yaml file below):
replicas: 1
Replace 1 with the number of copies of the Operator that you would like to run. 1 is acceptable for development and testing. However, you can run more than one replica for high availability purposes.
Replace sekret with the name of the image pull secret that Kubernetes uses to pull images from your registry.
Replace phx.ocir.io/youraccount with the location of your image registry.
Replace ttclassic-operator:3 with the name you chose in the previous steps.
% cd kube_files/deploy % vi operator.yaml apiVersion: apps/v1 kind: Deployment metadata: name: timestenclassic-operator spec: replicas: 1 selector: matchLabels: name: timestenclassic-operator template: metadata: labels: name: timestenclassic-operator spec: serviceAccountName: timestenclassic-operator imagePullSecrets: - name: sekret containers: - name: timestenclassic-operator image: phx.ocir.io/youraccount/ttclassic-operator:3 command: - timestenclassic-operator imagePullPolicy: Always env: - name: WATCH_NAMESPACE valueFrom: fieldRef: fieldPath: metadata.namespace - name: POD_NAME valueFrom: fieldRef: fieldPath: metadata.name - name: OPERATOR_NAME value: "timestenclassic-operator" - name: GODEBUG value: "x509ignoreCN=0"
Use the kubectl create command to define the Operator to your namespace and to start the Operator.
% kubectl create -f operator.yaml deployment.apps/timestenclassic-operator created
You deployed the Operator. The Operator should now be running.
Before you can start TimesTen in your Kubernetes cluster, you must first package TimesTen as a container image and then push the image to your image registry. The files that you need to do this are provided in the kube_files directory tree. See "Downloading TimesTen and the TimesTen Operator" for information.
To build the TimesTen container image, perform these steps:
Navigate to the kube_files/ttimage directory, and copy the TimesTen distribution into it. This example assumes you downloaded the timesten1814110.server.linux8664.zip distribution into the installation_dir directory. See "Downloading TimesTen and the TimesTen Operator" for information. Then, verify the timesten1814110.server.linux8664.zip file is in the kube_files/ttimage directory.
% cd kube_files/ttimage % cp installation_dir/timesten1814110.server.linux8664.zip . % ls *.zip timesten1814110.server.linux8664.zip
Navigate to the kube_files/ttimage directory (if not already in this directory). Edit the Dockerfile, replacing timesten1814110.server.linux8664.zip with the name of your TimesTen full distribution. If your TimesTen distribution is timesten1814110.server.linux8664.zip, no modification is necessary. If not, the modification you need to make is represented in bold. Note: The TimesTen full distribution must be 18.1.4.11.0 or later.
% cd kube_files/ttimage % vi Dockerfile # Copyright (c) 2019, 2021, Oracle and/or its affiliates. FROM container-registry.oracle.com/os/oraclelinux:7 ARG TT_DISTRO=timesten1814110.server.linux8664.zip RUN yum -y install tar gzip vim curl unzip libaio util-linux RUN groupadd -g 333 oracle RUN useradd -M -d /tt/home/oracle -s /bin/bash -u 333 -g oracle oracle RUN install -d -m 0750 -o oracle -g oracle /home/oracle COPY --chown=oracle:oracle $TT_DISTRO /home/oracle/ COPY --chown=oracle:oracle .bashrc starthost.pl .ttdrop .ttdotversion agent2 create1.sql create2.sql get1.sql repcreate.sql repduplicate.sql runsql.sql pausecg.sql /home/oracle/ # Uncomment the following line if you are using the optional non-root installation procedure. # USER 333 ENTRYPOINT "/home/oracle/starthost.pl"
Use the docker command to build the TimesTen container image. Replace tt1814110:3 with a name of your choosing (represented in bold, in the docker build command below). Note that the output may change from release to release.
% docker build -t tt1814110:3 . Sending build context to Docker daemon 445.8MB Step 1/9 : FROM container-registry.oracle.com/os/oraclelinux:7 ---> d788eca028a0 Step 2/9 : ARG TT_DISTRO=timesten1814110.server.linux8664.zip ---> Using cache ---> a259a93fe906 Step 3/9 : RUN yum -y install tar gzip vim curl unzip libaio util-linux ---> Using cache ---> ac676b5376f3 Step 4/9 : RUN groupadd -g 333 oracle ---> Using cache ---> ce16920f085c Step 5/9 : RUN useradd -M -d /tt/home/oracle -s /bin/bash -u 333 -g oracle oracle ---> Using cache ---> 0319814aca1c Step 6/9 : RUN install -d -m 0750 -o oracle -g oracle /home/oracle ---> Using cache ---> c8612b53398a Step 7/9 : COPY --chown=oracle:oracle $TT_DISTRO /home/oracle/ ---> 31cae98b71fd Step 8/9 : COPY --chown=oracle:oracle .bashrc starthost.pl .ttdrop .ttdotversion agent2 create1.sql create2.sql get1.sql repcreate.sql repduplicate.sql runsql.sql pausecg.sql /home/oracle/ ---> e50eb99c9b54 Step 9/9 : ENTRYPOINT "/home/oracle/starthost.pl" ---> Running in 0b41efd38837 Removing intermediate container 0b41efd38837 ---> 171245e546d5 Successfully built 171245e546d5 Successfully tagged tt1814110:3
Use the docker command to tag the TimesTen container image. Replace the following, represented in bold, in the docker tag command below.
tt1814110:3 with the name you chose in the previous step.
phx.ocir.io/youraccount with the location of your image registry.
% docker tag tt1814110:3 phx.ocir.io/youraccount/tt1814110:3
Use the docker command to push the TimesTen container image to your registry. Replace the following, represented in bold, in the docker push command below.
phx.ocir.io/youraccount with the location of your image registry.
tt1814110:3 with the name you chose previously.
% docker push phx.ocir.io/youraccount/tt1814110:3 The push refers to repository [phx.ocir.io/youraccount/tt1814110] 97a0f250b2fe: Pushed 650b003a3ad4: Pushed b8de51528854: Pushed 62192d26e325: Pushed 7dfe13e9b5a4: Pushed d8570fce965c: Pushed 2f915858a916: Layer already exists 3: digest: sha256:a6ac313394229eb2256d4a56fbcd8e2eda50ea2cc21991fa76f11701f2299710 size: 1788
You successfully built the TimesTen container image. It is pushed to your image registry.