Skip to main content
Version: v2.0-RC

Configure SQL Server's Listening Port

This guide explains how to set the TCP port that SQL Server listens on inside the DxSqlAg SQL Server container, and how the operator decides which value to use.

The goal is that you always know which port SQL Server is using, and that you can see it directly on the DxSqlAg custom resource.

Prerequisites​

Default SQL Server Behavior​

If you don’t configure anything, SQL Server listens on the default port:

  • Default TCP port: 1433

The operator treats 1433 as "no custom port was requested" unless you explicitly set a different value.

SECURITY CAUTION: Avoid Default Listening Port for SQL Server

For security best practices, do not use the default SQL Server port (1433) when configuring SQL Server instances in production environments. Using the default port can expose your instance to automated scanning and brute-force attacks. In production environments, it is strongly recommended to configure a non-standard port to reduce the attack surface and improve security posture.

Where the Port can be Configured​

There are three places you can (indirectly or directly) set the SQL Server TCP port:

  1. A field on the DxSqlAg spec:
    • spec.statefulSetSpec.podSpec.mssqlServerContainer.mssqlTcpPort
  2. An environment variable on the SQL Server container:
    • MSSQL_TCP_PORT
  3. The SQL Server configuration file (mssql.conf) stored in a ConfigMap:
    • network.tcpport in mssql.conf

When the operator processes a new DxSqlAg, it picks a port using this precedence order:

  1. mssqlTcpPort field in the CR (if not 1433)
  2. MSSQL_TCP_PORT environment variable (if present and valid)
  3. network.tcpport in mssql.conf from the ConfigMap referenced by mssqlConfigMap
  4. Fallback: 1433 (default)

Whichever value wins is then written back into the DxSqlAg CR:

spec.statefulSetSpec.podSpec.mssqlServerContainer.mssqlTcpPort

So the CR’s mssqlTcpPort field always reflects the effective port.

caution

The SQL Server TCP port can only be set during the DxSqlAg creation - you must delete the DxSqlAg to change the port!

The simplest and most "operator-native" way is to set the port directly on the DxSqlAg spec. The operator will:

  • Use that value as the source of truth.
  • Ensure the container is configured to use that port (including setting the MSSQL_TCP_PORT env var for you when needed).

Example: Set SQL Server to Listen on Port 11433​

apiVersion: dh2i.com/v1
kind: DxSqlAg
metadata:
  name: dxsqlag
spec:
  statefulSetSpec:
    podSpec:
      mssqlServerContainer:
        mssqlTcpPort: 11433
        # Optional: if you have other env vars, keep them here
        # env:
        #   - name: SOME_OTHER_FOO
        #     value: "bar"
tips
  • You don’t need to manually set MSSQL_TCP_PORT if you configure mssqlTcpPort. The operator will create or update that env var when appropriate.
  • Avoid setting a conflicting port in mssql.conf at the same time. Pick one place to define the port and keep it consistent.

Option 2: Use the MSSQL_TCP_PORT Environment Variable​

You can also set the port via the SQL Server container environment, as long as:

  • mssqlTcpPort is left at its default (1433), and
  • you configure MSSQL_TCP_PORT to the desired port.

The operator will:

  • Read MSSQL_TCP_PORT,
  • Use that as the effective port, and
  • Update mssqlTcpPort on the CR to match.

Example: Set Port using MSSQL_TCP_PORT​

apiVersion: dh2i.com/v1
kind: DxSqlAg
metadata:
  name: example-sqlag
spec:
  statefulSetSpec:
    podSpec:
      mssqlServerContainer:
        mssqlTcpPort: 1433   # Leave at default or omit entirely so env var takes precedence
        env:
          - name: MSSQL_TCP_PORT
            value: "11433"

Option 3: Use mssql.conf via a ConfigMap​

If you already manage SQL Server settings via mssql.conf, you can specify the TCP port there and point the container at that ConfigMap.

In that case, the operator will:

  • Look up the ConfigMap referenced in mssqlConfigMap,
  • Read the mssql.conf entry,
  • Parse the network.tcpport value,
  • Use that as the effective port, and
  • Update mssqlTcpPort in the CR accordingly.

Example: Set Port using mssql.conf​

  1. Create a ConfigMap.

    configmap.yaml
    kind: ConfigMap 
    apiVersion: v1 
    metadata:
      name: my-mssql-config
    data:
      mssql.conf: |
        [network]
        tcpport = 11433

  2. Reference the ConfigMap in the DxSqlAg

    apiVersion: dh2i.com/v1
    kind: DxSqlAg
    metadata:
      name: dxsqlag
    spec:
      statefulSetSpec:
        podSpec:
          mssqlServerContainer:
            mssqlTcpPort: 1433    # Leave at default or omit entirely
            mssqlConfigMap: my-mssql-config
info
  • If network.tcpport is missing or empty in mssql.conf, SQL Server is treated as using the default port (1433).
  • In this "ConfigMap-driven" mode, the operator reads the value but does not force a MSSQL_TCP_PORT env var for it. The important part is that the CR's mssqlTcpPort field is updated to match what’s in mssql.conf.

Keeping Things Consistent​

To avoid confusion, pick one primary configuration method (spec field, env var, or ConfigMap) and keep the others either unset or aligned.

The operator always tries to keep the CR’s mssqlTcpPort field in sync with the actual port, based on the rules described above.

Verifying the Configured Port​

After you change the port, check the CR:

kubectl get dxsqlag dxsqlag -o yaml | grep mssqlTcpPort

Confirm that mssqlTcpPort shows the value you expect.

Optionally, you can also check inside SQL Server. Connect to the instance and run:

SELECT local_tcp_port
FROM sys.dm_exec_connections
WHERE session_id = @@SPID;

This will show the actual port that your session is using.

Configure External Load Balancers​

This step is only required if per-pod external access is needed. If per-pod external access is required, custom LoadBalancer services can be created using service templates.

More Information​