--- title: Install & configure NRDOT for MSSQL monitoring with Helm source: https://docs.newrelic.com/docs/opentelemetry/db360/mssql/helm --- You can install and configure SQL Server monitoring on Kubernetes using the `mssql-otel` Helm chart. Optionally, the chart can also run a setup job that creates the monitoring login for you. > #### ⚠️ IMPORTANT > > This chart only supports SQL Server Authentication (username/password). It does not support Windows Authentication, Windows Domain Authentication, or gMSA. The collector always reaches SQL Server remotely over the network, whether it runs on Linux or Windows, self-hosted or on RDS, so SQL authentication works identically in every case. It also reports SQL Server metrics only (no host/infrastructure metrics), since the collector runs as a Kubernetes Deployment rather than on the SQL Server host itself. ## Prerequisites [#helm-prerequisites] - 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 SQL Server host (or RDS endpoint) and port: - Self-hosted: a routed path to the SQL Server host (VPN, peering, or shared network), and the SQL Server-side firewall must allow the connection's source IP. - AWS RDS: VPC peering, a transit gateway, or shared-VPC placement with the RDS instance, and the RDS security group must allow the SQL Server port (`1433` by default) from the cluster's egress source. - Either a monitoring login you've already created, or SQL Server admin credentials (a `sysadmin`-role login, such as `sa` or the RDS master user) so the chart's setup job can create one for you. See [Configure monitoring credentials](#helm-credentials) below. ## Create the namespace [#helm-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 [#helm-credentials] Decide whether you want the chart's setup job to create the SQL Server monitoring login 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 login for you. This chart only supports SQL Server Authentication, so before installing it, create the monitoring login yourself using the SQL Server Authentication **Create monitoring user** step from [Linux self-hosted](https://docs.newrelic.com/docs/opentelemetry/db360/mssql/linux-hosted/#user), [Windows self-hosted](https://docs.newrelic.com/docs/opentelemetry/db360/mssql/windows-hosted-sql/#user-sql), [Linux RDS](https://docs.newrelic.com/docs/opentelemetry/db360/mssql/linux-rds/#user), or [Windows RDS](https://docs.newrelic.com/docs/opentelemetry/db360/mssql/windows-rds-sql/#user-sql), 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 login 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 mssql-monitor-creds \ --from-literal=username= \ --from-literal=password='' \ -n newrelic ``` **Automated setup job** With this method, the chart's setup job creates the monitoring login for you using SQL Server 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 mssql-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 logins and grant broad `VIEW` access, create it as its own secret. Use a login in the `sysadmin` role (or equivalent) for self-hosted SQL Server, or the RDS master user for SQL Server on AWS RDS: ```bash kubectl create secret generic mssql-admin-creds \ --from-literal=username= \ --from-literal=password='' \ -n newrelic ``` ## Configure the Helm values [#helm-configure] Set `mssql.topology` to match your environment: | Value | Description | | ------------- | ------------------------------------------------------------------------- | | `self-hosted` | Self-hosted SQL Server, reached over the network (Linux or Windows host). | | `rds` | SQL Server on AWS RDS. | 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: https://otlp.nr-data.net:4318 mssql: topology: server: port: username: password: # No setup job runs, so create the monitoring login yourself # before installing the chart. setupJob: enabled: false ``` **No setup job: secret-based credentials** ```yaml licenseKey: otlpEndpoint: https://otlp.nr-data.net:4318 mssql: topology: server: port: existingSecret: mssql-monitor-creds # No setup job runs, so the monitoring login referenced by # this secret must already exist - create it yourself # before installing the chart. setupJob: enabled: false ``` **Automated setup job** ```yaml licenseKey: otlpEndpoint: https://otlp.nr-data.net:4318 mssql: topology: server: port: existingSecret: mssql-monitor-creds setupJob: enabled: true image: # -- sqlcmd image. No default: see the chart's README for why # (mcr.microsoft.com/mssql-tools:latest is freely pullable but # stale and unmaintained). repository: "" tag: "" pullPolicy: IfNotPresent sqlAdmin: existingSecret: mssql-admin-creds ``` | Parameter | Description | | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `licenseKey` | Your New Relic license key. | | `otlpEndpoint` | Your region's OTLP/HTTP endpoint, as a full URL with scheme: `https://otlp.nr-data.net:4318` (US) or `https://otlp.eu01.nr-data.net:4318` (EU). For more information, refer to [New Relic OTLP endpoints documentation](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/). | | `mssql.server` / `mssql.port` | Your SQL Server host (or RDS endpoint) and port, reachable from the cluster. | | `mssql.tls.enabled` / `mssql.tls.trustServerCertificate` | Optional. Set `enabled: true` to encrypt the connection to SQL Server, and `trustServerCertificate: true` to skip certificate validation (useful for self-signed certs in test environments). | | `setupJob.image.repository` / `setupJob.image.tag` | A `sqlcmd`-capable image used by the setup job. There's no default: Microsoft's freely pullable `mcr.microsoft.com/mssql-tools:latest` is dated 2017 and unmaintained, so confirm you're comfortable with its age (including unpatched CVEs) before using it, or build a current image yourself from Microsoft's `mssql-tools18` apt packages. 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/mssql-otel/values.yaml) for all available configuration options, including `mssql.collectionInterval`, `mssql.maxConcurrentQueries`, and the `additionalReceiverConfig` escape hatch. ## (Optional) Monitor multiple instances from one release [#helm-multi] Instead of `mssql.*`, set `mssqlMulti.enabled: true` to monitor several SQL Server instances (self-hosted or RDS) from a single collector pod in one release. The two modes are mutually exclusive: don't set `mssql.server` and `mssqlMulti.enabled: true` in the same release. 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 login for you: **No setup job** Create each instance's monitoring-login 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: https://otlp.nr-data.net:4318 # 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. mssqlMulti: enabled: true topology: databases: - name: db1 server: existingSecret: db1-monitor-creds - name: db2 server: existingSecret: db2-monitor-creds # No admin credential is configured here since the setup # job is disabled - create each instance's monitoring login # yourself first. setupJob: enabled: false ``` **Automated setup job** Each instance needs both its own monitoring-login 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: https://otlp.nr-data.net:4318 # 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. mssqlMulti: enabled: true topology: databases: - name: db1 server: existingSecret: db1-monitor-creds sqlAdmin: existingSecret: db1-admin-creds - name: db2 server: existingSecret: db2-monitor-creds sqlAdmin: existingSecret: db2-admin-creds setupJob: enabled: true image: repository: "" tag: "" ``` | Parameter | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mssqlMulti.enabled` | Set to `true` to monitor multiple instances from one release instead of `mssql.*`. Defaults to `false`. | | `mssqlMulti.topology` | `self-hosted` or `rds`, same meaning as `mssql.topology`, shared by every instance in this release. | | `mssqlMulti.databases` | List of instances to monitor. Each entry requires a unique `name`, `server` (`port` defaults to `1433`), and `existingSecret`; add `sqlAdmin.existingSecret` per entry only when `setupJob.enabled` is `true`. | > #### 💡 TIP > > Scrape settings (collection interval, TLS, metrics) apply identically to every instance in `mssqlMulti.databases`. There's no per-instance override. Use `additionalReceiverConfig` for anything that needs to differ. The setup job runs once per instance (`-setup-`) rather than once per release. ## Install the Helm chart [#helm-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 mssql-otel newrelic/mssql-otel \ -n newrelic \ --create-namespace \ -f values.yaml ``` ## Verify the installation [#helm-verify] 1. Check that the setup job completed (if enabled) 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 'sqlserver.%' AND instrumentation.provider = 'opentelemetry' SINCE 10 minutes ago ``` ## Find and use your data [#find] Once your data is being collected, you can access comprehensive SQL Server database monitoring through the New Relic UI. To find your SQL Server database entity in New Relic: 1. Go to **[one.newrelic.com](https://one.newrelic.com) > All capabilities > Databases**. 2. From the **Entity type** dropdown, select **MSSQL instance**, then click **Apply**. 3. Select your SQL Server database from the list of entities. After setting up SQL Server monitoring with NRDOT, you can: - [Create custom dashboards](https://docs.newrelic.com/docs/query-your-data/explore-query-data/dashboards/introduction-dashboards/) to visualize your database metrics - [Set up alerts](https://docs.newrelic.com/docs/alerts/create-alert/create-alert-condition/alert-conditions/) for critical database performance thresholds - [Explore your data](https://docs.newrelic.com/docs/query-your-data/explore-query-data/browse-data/introduction-data-explorer/) using New Relic query capabilities ## Related documentation [#related-docs] [Metrics reference](https://docs.newrelic.com/docs/opentelemetry/db360/mssql/metrics-reference) Learn about the available metrics collected by the NRDOT Collector. [Troubleshooting](https://docs.newrelic.com/docs/opentelemetry/db360/mssql/troubleshooting) Learn how to troubleshoot your MSSQL monitoring setup in New Relic. [Set up APM-database correlation](https://docs.newrelic.com/docs/opentelemetry/db360/capabilities/db-apm) Learn how to correlate your application performance with database operations in New Relic.