--- title: Install & configure NRDOT for Oracle monitoring with Helm source: https://docs.newrelic.com/docs/opentelemetry/db360/oracle/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 [#prerequisites] - A valid New Relic [license key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#ingest-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](#credentials) below. ## Create the namespace [#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 [#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: **No setup job: plain username and password** With this method there's no setup job, so nothing here creates the monitoring user for you. Before installing the chart, create it yourself: follow the **Configure database user** and **Grant monitoring privileges** steps in [On-host CDB](https://docs.newrelic.com/docs/opentelemetry/db360/oracle/host-cdb) or [On-host PDB](https://docs.newrelic.com/docs/opentelemetry/db360/oracle/host-pdb), depending on your environment. You'll set the monitoring username and password directly in `values.yaml` in the next step. **No setup job: secret-based 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= \ --from-literal=password='' \ -n newrelic ``` **Automated setup job** 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. 1. 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= \ --from-literal=password='' \ -n newrelic ``` 2. 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= \ --from-literal=password='' \ -n newrelic ``` ## Configure the Helm values [#configure] 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: **No setup job: plain username and password** ```yaml licenseKey: otlpEndpoint: otlp.nr-data.net:4317 oracle: topology: endpoint: : service: username: password: # No setup job runs, so create the monitoring user yourself # before installing the chart. setupJob: enabled: false ``` **No setup job: secret-based credentials** ```yaml licenseKey: otlpEndpoint: otlp.nr-data.net:4317 oracle: topology: endpoint: : service: 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 ``` **Automated setup job** ```yaml licenseKey: otlpEndpoint: otlp.nr-data.net:4317 oracle: topology: endpoint: : service: 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](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/). | | `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](https://github.com/newrelic/helm-charts/blob/master/charts/oracle-otel/values.yaml) for all available configuration options. ## (Optional) Monitor multiple instances from one release [#multi] 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: **No setup job** 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= \ --from-literal=password='' \ -n newrelic # Repeat for every instance (db2-monitor-creds, ...) ``` ```yaml licenseKey: 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: collectionInterval: 15s databases: - name: db1 endpoint: : service: existingSecret: db1-monitor-creds - name: db2 endpoint: : service: 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 ``` **Automated setup job** 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= \ --from-literal=password='' \ -n newrelic kubectl create secret generic db1-admin-creds \ --from-literal=username= \ --from-literal=password='' \ -n newrelic # Repeat for every instance (db2-monitor-creds, db2-admin-creds, ...) ``` ```yaml licenseKey: 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: collectionInterval: 15s databases: - name: db1 endpoint: : service: existingSecret: db1-monitor-creds oracleAdmin: existingSecret: db1-admin-creds - name: db2 endpoint: : service: 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 (`-setup-`) rather than once per release. ## Install the Helm chart [#install] 1. Add the New Relic Helm repository: ```bash helm repo add newrelic https://helm-charts.newrelic.com helm repo update ``` 2. 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 [#verify] 1. Check that the setup job completed and the collector pod is running: ```bash kubectl get jobs,pods -n newrelic --watch ``` 2. Run this query in the [query builder](https://docs.newrelic.com/docs/query-your-data/explore-query-data/query-builder/introduction-query-builder/) to confirm data is arriving: ```sql 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](https://docs.newrelic.com/docs/opentelemetry/db360/oracle/introduction/#find).