Install & configure NRDOT for Oracle monitoring with Helm

You can install and configure Oracle Database monitoring on Kubernetes using the oracle-otel Helm chart. Optionally, the chart can also run a setup job that creates the monitoring database user for you.

Prerequisites

A valid New Relic license key.
Helm 3.0 or later, and kubectl configured to access your Kubernetes cluster.
Network connectivity from your Kubernetes cluster to the Oracle Database host and listener port.
Either a monitoring database user you've already created, or Oracle Database admin credentials (RDS master user, SYS, or ADMIN) so the chart's setup job can create one for you. See Configure monitoring credentials below.

Create the namespace

Create the namespace you'll install into. It must exist before you create any secrets in the next step, since helm install --create-namespace only creates the namespace during the final install step:

bash

$kubectl create namespace newrelic

Tip

Set it as the default namespace for your current kubectl context so you don't need to pass -n on every command below:

bash

$kubectl config set-context --current --namespace=newrelic

Configure monitoring credentials

Decide whether you want the chart's setup job to create the Oracle Database monitoring user for you, and if not, how you'll supply its credentials:

With this method there's also no setup job. Create the monitoring user yourself first, exactly as in the plain-credentials method above. The only difference is where its credentials live: instead of plaintext in values.yaml, store them in a Kubernetes secret:

bash

$kubectl create secret generic oracle-monitor-creds \
>  --from-literal=username=<MONITORING_USERNAME> \
>  --from-literal=password='<MONITORING_PASSWORD>' \
>  -n newrelic

With this method, the chart's setup job creates the monitoring user for you using database admin credentials. Both the monitoring and admin credentials must be provided as Kubernetes secrets: the setup job never accepts plaintext admin credentials, and enabling it requires secret-based monitoring credentials too.

Create a secret with the monitoring username and password. This is the identity the setup job creates and the collector connects with:

bash

$kubectl create secret generic oracle-monitor-creds \
>  --from-literal=username=<MONITORING_USERNAME> \
>  --from-literal=password='<MONITORING_PASSWORD>' \
>  -n newrelic

The setup job only accepts admin credentials via a Kubernetes secret (no plaintext username/password in values.yaml). Since this credential can create users and grant broad database access, create it as its own secret:
bash
```
$kubectl create secret generic oracle-admin-creds \
>  --from-literal=username=<ADMIN_USERNAME> \
>  --from-literal=password='<ADMIN_PASSWORD>' \
>  -n newrelic
```

Configure the Helm values

Set oracle.topology to match your environment:

Value	Description
`cdb`	On-host, multitenant CDB. All PDBs under this CDB are monitored.
`pdb`	On-host, single PDB.
`rds`	Oracle Database on AWS RDS.
`adb`	Oracle Autonomous Database.

Use the values.yaml that matches the credential method you chose in the previous step:

licenseKey: <YOUR_LICENSE_KEY>
otlpEndpoint: otlp.nr-data.net:4317

oracle:
  topology: <cdb|pdb|rds|adb>
  endpoint: <YOUR_DB_HOST>:<YOUR_DB_PORT>
  service: <YOUR_SERVICE_NAME>
  username: <YOUR_MONITORING_USERNAME>
  password: <YOUR_MONITORING_PASSWORD>

# No setup job runs, so create the monitoring user yourself
# before installing the chart.
setupJob:
  enabled: false

licenseKey: <YOUR_LICENSE_KEY>
otlpEndpoint: otlp.nr-data.net:4317

oracle:
  topology: <cdb|pdb|rds|adb>
  endpoint: <YOUR_DB_HOST>:<YOUR_DB_PORT>
  service: <YOUR_SERVICE_NAME>
  existingSecret: oracle-monitor-creds

# No setup job runs, so the monitoring user referenced by
# this secret must already exist - create it yourself
# before installing the chart.
setupJob:
  enabled: false

licenseKey: <YOUR_LICENSE_KEY>
otlpEndpoint: otlp.nr-data.net:4317

oracle:
  topology: <cdb|pdb|rds|adb>
  endpoint: <YOUR_DB_HOST>:<YOUR_DB_PORT>
  service: <YOUR_SERVICE_NAME>
  existingSecret: oracle-monitor-creds

setupJob:
  enabled: true
  image:
    # -- Oracle Instant Client + sqlplus image. No default: pulling from container-registry.oracle.com requires accepting Oracle's license terms first. See README.
    repository: ""
    tag: ""
    pullPolicy: IfNotPresent
  oracleAdmin:
    existingSecret: oracle-admin-creds

Parameter	Description
`licenseKey`	Your New Relic license key.
`otlpEndpoint`	Your region's OTLP/gRPC endpoint, as a bare `host:port` with no scheme: `otlp.nr-data.net:4317` (US) or `otlp.eu01.nr-data.net:4317` (EU). For more information, refer to New Relic OTLP endpoints documentation.
`oracle.endpoint`	Your Oracle Database host (or RDS endpoint) and listener port, reachable from the cluster.
`oracle.service`	Your CDB, PDB, RDS, or ADB service name for the collector connection.
`setupJob.image.repository` / `setupJob.image.tag`	An Oracle Instant Client + `sqlplus` image used by the setup job. There's no default: pulling from `container-registry.oracle.com` requires accepting Oracle's license terms first, so you must supply your own image. Only required for secret-based credentials, where the setup job is enabled.

Tip

See the chart's values.yaml for all available configuration options.

(Optional) Monitor multiple instances from one release

Instead of oracle.*, set oracleMulti.enabled: true to monitor several Oracle Database instances from a single collector pod in one release. The two modes are mutually exclusive: don't set oracle.endpoint and oracleMulti.enabled: true in the same release. Every instance in a release must share the same oracleMulti.topology (cdb, pdb, rds, or adb): mixing topologies, for example an RDS instance and a self-hosted CDB, isn't supported in one release; use a separate release for each topology instead.

Multi-instance mode has no plain-username/password path: every instance needs its own Kubernetes secret with monitoring credentials. Decide whether you also want the setup job to create each monitoring user for you:

Create each instance's monitoring-user secret yourself before installing (repeat per instance, matching the name you give it in values.yaml):

bash

$kubectl create secret generic db1-monitor-creds \
>  --from-literal=username=<MONITORING_USERNAME> \
>  --from-literal=password='<MONITORING_PASSWORD>' \
>  -n newrelic
$# Repeat for every instance (db2-monitor-creds, ...)

licenseKey: <YOUR_LICENSE_KEY>
otlpEndpoint: otlp.nr-data.net:4317

# EDIT the two example entries below (or add more) to match
# your real instances - each `name` must be unique within
# this release and match the Secret you created for it.
oracleMulti:
  enabled: true
  topology: <cdb|pdb|rds|adb>
  collectionInterval: 15s
  databases:
    - name: db1
      endpoint: <YOUR_DB_1_HOST>:<YOUR_DB_1_PORT>
      service: <YOUR_DB_1_SERVICE_NAME>
      existingSecret: db1-monitor-creds
    - name: db2
      endpoint: <YOUR_DB_2_HOST>:<YOUR_DB_2_PORT>
      service: <YOUR_DB_2_SERVICE_NAME>
      existingSecret: db2-monitor-creds

# No admin credential is configured here since the setup
# job is disabled - create each instance's monitoring user
# yourself first.
setupJob:
  enabled: false

Each instance needs both its own monitoring-user secret and its own admin-credentials secret (repeat per instance):

bash

$kubectl create secret generic db1-monitor-creds \
>  --from-literal=username=<MONITORING_USERNAME> \
>  --from-literal=password='<MONITORING_PASSWORD>' \
>  -n newrelic
>kubectl create secret generic db1-admin-creds \
>  --from-literal=username=<ADMIN_USERNAME> \
>  --from-literal=password='<ADMIN_PASSWORD>' \
>  -n newrelic
$# Repeat for every instance (db2-monitor-creds, db2-admin-creds, ...)

licenseKey: <YOUR_LICENSE_KEY>
otlpEndpoint: otlp.nr-data.net:4317

# EDIT the two example entries below (or add more) to match
# your real instances - each `name` must be unique within
# this release and match the Secrets you created for it.
oracleMulti:
  enabled: true
  topology: <cdb|pdb|rds|adb>
  collectionInterval: 15s
  databases:
    - name: db1
      endpoint: <YOUR_DB_1_HOST>:<YOUR_DB_1_PORT>
      service: <YOUR_DB_1_SERVICE_NAME>
      existingSecret: db1-monitor-creds
      oracleAdmin:
        existingSecret: db1-admin-creds
    - name: db2
      endpoint: <YOUR_DB_2_HOST>:<YOUR_DB_2_PORT>
      service: <YOUR_DB_2_SERVICE_NAME>
      existingSecret: db2-monitor-creds
      oracleAdmin:
        existingSecret: db2-admin-creds

setupJob:
  enabled: true
  image:
    repository: ""
    tag: ""

Parameter	Description
`oracleMulti.enabled`	Set to `true` to monitor multiple instances from one release instead of `oracle.*`. Defaults to `false`.
`oracleMulti.topology`	`cdb`, `pdb`, `rds`, or `adb` (same meaning as `oracle.topology`), shared by every instance in this release.
`oracleMulti.collectionInterval`	Default scrape interval for every entry. Defaults to `15s`. Override it for a specific instance with that entry's own `collectionInterval`.
`oracleMulti.databases`	List of instances to monitor. Each entry requires a unique `name`, `endpoint` (`host:port`), `service`, and `existingSecret`; add `oracleAdmin.existingSecret` per entry only when `setupJob.enabled` is `true`.

Tip

Unlike the other NRDOT Helm charts, Oracle lets you override collectionInterval per instance. Every other scrape setting still applies identically to every instance. Use additionalReceiverConfig for anything else that needs to differ. The setup job runs once per instance (<release>-setup-<name>) rather than once per release.

Install the Helm chart

Add the New Relic Helm repository:

bash

$helm repo add newrelic https://helm-charts.newrelic.com
$helm repo update

Install the chart using your values.yaml file:

bash

$helm upgrade --install oracle-otel newrelic/oracle-otel \
>  -n newrelic \
>  --create-namespace \
>  -f values.yaml

Verify the installation

Check that the setup job completed and the collector pod is running:
bash
```
$kubectl get jobs,pods -n newrelic --watch
```

Run this query in the query builder to confirm data is arriving:

SELECT count(*) FROM Metric
WHERE metricName LIKE 'oracledb.%'
AND instrumentation.provider = 'opentelemetry'
SINCE 10 minutes ago

To find your Oracle Database entity in New Relic, see Find and use your data.

Install & configure NRDOT for Oracle monitoring with Helm

Prerequisites

Create the namespace

Tip

Configure monitoring credentials

No setup job: plain username and password

No setup job: secret-based credentials

Automated setup job

Configure the Helm values

No setup job: plain username and password

No setup job: secret-based credentials

Automated setup job

Tip

(Optional) Monitor multiple instances from one release

No setup job

Automated setup job

Tip

Install the Helm chart

Verify the installation

Install & configure NRDOT for Oracle monitoring with Helm

Prerequisites .css-21sua1{background:none;border:none;width:0;padding:0;}

Create the namespace

Tip

Configure monitoring credentials

No setup job: secret-based credentials

Automated setup job

Configure the Helm values

No setup job: plain username and password

No setup job: secret-based credentials

Automated setup job

Tip

(Optional) Monitor multiple instances from one release

No setup job

Automated setup job

Tip

Install the Helm chart

Verify the installation

Prerequisites