Oracle Database Operator for Kubernetes makes it easy to deploy Oracle Globally Distributed AI Database 26ai using standard Kubernetes workflows. Instead of building the environment manually, you define the deployment through Kubernetes resources and let the operator handle the database lifecycle.

In this post, we walk through a quick deployment path using Oracle Kubernetes Engine (OKE), Oracle Database Operator, Oracle Database 26ai Free Edition container images, and a sharded GDD manifest. We use OKE Quick Create as the starting point, but the same operator-driven approach applies across other supported Kubernetes environments.

By the end, you will have a small GDD environment running on Kubernetes, including a shard catalog, Global Service Manager (GSM) pods, and shard pods.

What You Need

  • A Kubernetes cluster with a working storage class that supports persistent storage. 
  • kubectl configured to access the target cluster with permissions to create namespaces, Custom Resource Definitions (CRDs), RBAC resources, secrets, services, and pods. 
  • Git and OpenSSL installed on the workstation used for deployment. 
  • Oracle Container Registry credentials with access to the required Oracle Database container images. 
  • The Oracle Database Operator repository cloned locally. 
Security note: The commands below use local environment variables and Kubernetes Secrets for a reproducible lab workflow. For production environments, prefer OCI Vault or an approved external vault and avoid placing passwords directly in shell history.

Deployment Steps

Step 1: Prepare the Kubernetes Environment

Start with a working Kubernetes cluster and kubectl access from your workstation. For the quickest path, OKE Quick Create is a good fit because it creates a managed Kubernetes cluster with the core network resources and worker-node setup already handled. That lets you move quickly to the database for deployment instead of spending time building the cluster foundation.

Oracle Database Operator is not limited to OKE. Oracle Database Operator v2.1.0 is tested on the following Kubernetes environments:

  • Oracle Kubernetes Engine (OKE)
  • Red Hat OpenShift 4.19+
  • Oracle Linux Cloud Native Environment (OLCNE) 1.9+
  • Google Kubernetes Engine (GKE)
  • Azure Kubernetes Service (AKS)
  • Amazon Elastic Kubernetes Service (EKS)
  • Red Hat OKD
  • Minikube v1.29.0, for development and local testing

For this walkthrough, OKE is the simplest path. Once the cluster is available, validate access before continuing.

Step 2: Authenticate with Oracle Container Registry

The deployment pulls Oracle Database container images from Oracle Container Registry. Before creating the image pull secret, sign in to Oracle Container Registry, accept the required license terms for the database image, and confirm that your credentials can access the image used by the manifest.

Oracle Container Registry is available at https://container-registry.oracle.com/

Keep the username and password available. You will use them in Step 6 to create the Kubernetes image pull secret.

Step 3: Clone the Oracle Database Operator Repository

Clone the Oracle Database Operator repository and move into the repository root:

$ git clone https://github.com/oracle/oracle-database-operator
$ cd oracle-database-operator

The remaining commands assume that you are running from this repository root unless a step explicitly changes directories.

Step 4: Apply cert-manager and Role Bindings

Oracle Database Operator uses admission webhooks, which require TLS certificates. Install cert-manager first, then apply the role bindings for the default cluster-scoped operator deployment. The node RBAC file is needed when the deployment uses NodePort services.

# Install cert-manager.
$ kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml  

# Apply cluster-scoped role bindings from the operator repository root.
$ kubectl apply -f rbac/cluster-role-binding.yaml
$ kubectl apply -f rbac/node-rbac.yaml

Validate that cert-manager is running before installing the database operator:

$ kubectl get pods -n cert-manager

Step 5: Install Oracle Database Operator for Kubernetes

Create a namespace for the GDD environment, install the operator, and verify that the operator pods are running. This example uses the namespace shns.

# Create the namespace for the sharded database environment.
$ kubectl create namespace shns
$ kubectl get namespace shns  

# Install Oracle Database Operator.
$ kubectl apply -f oracle-database-operator.yaml  

# Validate the operator deployment.
$ kubectl get pods -n oracle-database-operator-system
Deployment mode: These steps use the default cluster-scoped deployment, where the operator can monitor namespaces across the cluster. Namespace-scoped deployment is also available when you want the operator restricted to selected namespaces.

Step 6: Create Kubernetes Secrets

The GDD manifest needs a database password secret and an image pull secret for Oracle Container Registry. Replace the example placeholder values below before running the commands.

NAMESPACE=”shns”
SECRET_NAME=”db-user-pass-rsa”
RSADIR=”/tmp/.secrets”  

DB_PASSWORD=”<database-admin-password>”
DOCK_USER=”<oracle-account-email>”
DOCK_PWD=”<oracle-container-registry-password-or-auth-token>”
DOCK_EMAIL=”${DOCK_USER}”  

PRIVKEY=”${RSADIR}/key.pem”
PUBKEY=”${RSADIR}/key.pub”
PWDFILE=”${RSADIR}/pwdfile.txt”
PWDFILE_ENC=”${RSADIR}/pwdfile.enc”  

# After setting variables above, generate db keys
mkdir -p “${RSADIR}”
openssl genrsa -out “${PRIVKEY}”
openssl rsa -in “${PRIVKEY}” -out “${PUBKEY}” -pubout
printf ‘%s’ “${DB_PASSWORD}” > “${PWDFILE}”
openssl pkeyutl -in “${PWDFILE}” -out “${PWDFILE_ENC}” -pubin -inkey “${PUBKEY}” -encrypt
rm -f “${PWDFILE}”  

kubectl delete secret “${SECRET_NAME}” -n “${NAMESPACE}” –ignore-not-found
kubectl create secret generic “${SECRET_NAME}” \  
–from-file=”${PWDFILE_ENC}” \  
–from-file=”${PRIVKEY}” \  
-n “${NAMESPACE}”  

# Generate Container keys kubectl delete secret ocr-reg-cred -n “${NAMESPACE}” –ignore-not-found
kubectl create secret docker-registry ocr-reg-cred \  
–docker-server=container-registry.oracle.com \   
–docker-username=”${DOCK_USER}” \  
–docker-password=”${DOCK_PWD}” \  
–docker-email=”${DOCK_EMAIL}” \  
-n “${NAMESPACE}”

Confirm that both secrets exist in the GDD namespace:

$ kubectl get secrets -n shns   

NAME               TYPE                             DATA   AGE 
db-user-pass-rsa   Opaque                           2      11m 
ocr-reg-cred       kubernetes.io/dockerconfigjson   1      10m   

Step 7: Apply the GDD Deployment Manifest

After the operator and secrets are in place, apply the sharding deployment manifest. The example below uses the Oracle Database 26ai Free image manifest from the sharding examples.

Before applying the manifest, review the namespace, image, image pull secret, storage, and resource settings for your cluster.

Apply the manifest from the sharding examples directory:

$ cd docs/sharding/provisioning/free 
$ kubectl apply -f sharding provisioning_with_free_images.yaml

A small running environment should include a shard catalog, two GSM pods, and three shard pods. Pod startup can take several minutes while images are pulled, persistent volumes are attached, and the database containers initialize.

$ kubectl get pods -n shns
 
# Expected pod names include:
catalog-0
gsm1-0
gsm2-0
shard1-0
shard2-0
shard3-0

Post Deployment Validation

Here are some steps to validate that the Distributed Database environment has been deployed successfully:

Ensure the pods are in ‘Running’ State

$ kubectl get pods -n shns
NAME                         READY   STATUS    RESTARTS   AGE
catalog-0                    1/1     Running   0         6h43m
gsm1-0                       1/1     Running   0          6h43m
gsm2-0                       1/1     Running   0          6h43m
shard1-0                     1/1     Running   0           6h37m
shard2-0                     1/1      Running   0          6h35m
shard3-0                     1/1     Running   0          6h35m

The Status for all the pods should be ‘Running’. If this is not the case then a ‘$ kubectl describe pod -podname-‘ command can be issued to investigate the problem. One common problem is that the authentication information was not correct.

Log on to GSM and check the status of the Shards

$ kubectl exec -n shns gsm1-0  -it — /bin/sh
sh-4.4$ source ./.bashrc
[oracle@gsm1-0 ~]$
[oracle@gsm1-0 ~]$ gdsctl
GDSCTL: Version 23.26.1.0.0 – Production on Mon Jul 06 19:04:37 UTC 2026
 
Copyright (c) 2011, 2026, Oracle.  All rights reserved.
 
Welcome to GDSCTL, type “help” for information.
 
Current GSM is set to SHARDDIRECTORGSM1
GDSCTL> config shard
Catalog connection is established
Name                Shard Group         Status    State       Region    Availability
—-                 ———–         ——    —–       ——    ————
shard1_shard1pdb    shardgroup1         Ok        Deployed   primary   ONLINE
shard2_shard2pdb    shardgroup1         Ok        Deployed   primary   ONLINE
shard3_shard3pdb    shardgroup1         Ok        Deployed   primary   ONLINE

The state for all of the shards should be ‘Deployed’. If a Shard does not appear or shows as not ONLINE, it is best to wait a few minutes and check ‘config shard’ again. The scripts which prepare the environment may take up to 10 or 15 minutes to complete.

Begin creating a Sharded Database

Connect to the Catalog database and begin creating a Sharded schema as outlined in the Globally Distributed Database documentation.

$ kubectl exec -n shns catalog-0  -it — /bin/sh
sh-4.4$ sqlplus / as sysdba
 
SQL*Plus: Release 23.26.1.0.0 – Production on Mon Jul 6 19:09:33 2026
Version 23.26.1.0.0
 
Copyright (c) 1982, 2025, Oracle.  All rights reserved.

Connected to:
Oracle AI Database 26ai Enterprise Edition Release 23.26.1.0.0 – Production
Version 23.26.1.0.0
 
SQL> show pdbs
 
    CON_ID CON_NAME                  OPEN MODE  RESTRICTED
———- —————————— ———- ———-
        2 PDB$SEED                   READ ONLY  NO
        3 CATALOGPDB                 READ WRITE NO
SQL> alter session set container=catalogpdb;
 
Session altered.
 
SQL> alter session enable shard ddl;
 

Other Options and References

The path above is intentionally simple: clone the repository, install the operator, create secrets, and apply the GDD manifest. Depending on your environment, you can use other supported options:

  • Use OKE Quick Create when you want the fastest managed Kubernetes starting point in OCI.
  • Use OperatorHub.io or the Red Hat OpenShift catalog when your platform standardizes on Operator Lifecycle Manager.
  • Use namespace-scoped operator deployment when the operator should watch only specific namespaces.
  • Use the sharding documentation and sample manifests to adapt the topology, image, storage, namespace, replication, and service settings for your target environment.
  • Move secrets into OCI Vault or another approved vault for production-style deployments.

Conclusion

Oracle Database Operator turns a GDD deployment on Kubernetes into a repeatable workflow built from standard Kubernetes resources. For a lab, OKE Quick Create and Oracle Database 26ai Free Edition provide a fast path to a working sharded environment. For broader use, the same operator model can be adapted to other supported Kubernetes platforms, installation methods, and database configurations.

Once the pods are running and the custom resource reports healthy status, the environment is ready for workload setup, resiliency testing, or further tuning.

Sources