Skip to main content
Version: v2.0-RC

Create a SQL Server AG using kubectl

This guide shows you how to create a SQL Server Availability Group with kubectl by writing a DxSqlAg manifest and applying it.

Prerequisites​

  • A Kubernetes cluster with DxOperator v2 installed. See the DxOperator Manual Installation Guide for more information.
  • A valid DxEnterprise license with availability group management features and tunnels enabled. A fully featured Developer Edition is available free for non-production use. To purchase DxEnterprise software for production workloads, please contact us.

Create a SQL Server AG​

  1. Create secrets for the DxEnterprise passkey and license key, and the SQL Server SA account.

    kubectl create secret generic dxe --from-literal=DX_PASSKEY=<password> --from-literal=DX_LICENSE=<license_key>
    kubectl create secret generic mssql --from-literal=MSSQL_SA_PASSWORD=<password>

  2. (OPTIONAL) Apply a ConfigMap YAML for the mssql.conf file.

    info

    See the Microsoft documentation for all supported variables for MSSQL.

    configmap.yaml
    kind: ConfigMap 
    apiVersion: v1 
    metadata:
      name: mssql-config
    data:
      mssql.conf: |

        [sqlagent]
        enabled = true
    kubectl apply -f configmap.yaml

  3. Copy the example DxSqlAg.yaml file below.

    info

    There are many configuration options for the DxSqlAg custom resource beyond those that are shown in this example. View the DxSqlAg API Reference for more information.

    apiVersion: dh2i.com/v1
    kind:  DxSqlAg
    metadata:
      name: dxsqlag
    spec:
      sqlAgConfiguration:
        synchronousReplicas: 3
        asynchronousReplicas: 0
        # ConfigurationOnlyReplicas are only allowed with availabilityGroupClusterType set to EXTERNAL
        configurationOnlyReplicas: 0      
        availabilityGroupName: AG1
        # Adds auto-generated load balancers to serviceTemplates for easy cluster access
        # For more customization, use the serviceTemplates section below
        #createLoadBalancers: true
        # Listener port for the availability group (uncomment to apply)
        #availabilityGroupListenerPort: 14033
        # For a contained availability group, add the option CONTAINED
        #availabilityGroupOptions: CONTAINED
        # Disables automatic availability mode switching when scaling down
        #disableModeSwitching: true
      # Service templates are used to create a service for each pod in the cluster
      serviceTemplates:
      - name: custom-service
        type: LoadBalancer
        ports:
        - name: dxe-admin
          port: 7979
          protocol: TCP
        # Per-service customizations are used to specify values specific to a service
        perServiceCustomizations:
        - name: custom-service-dxsqlag-0
          metadata:
            annotations:
              cloud-provider: "10.0.0.100"
        - name: custom-service-dxsqlag-1
          metadata:
            annotations:
              cloud-provider: "10.0.0.101"
      statefulSetSpec:
        podSpec:
          dxEnterpriseContainer:
            image: "docker.io/dh2i/dxe:latest"
            imagePullPolicy: Always
            acceptEula: true
            clusterSecret: dxe
            vhostName: VHOST1
            # Configuration options for the required persistent volume claim for DxEnterprise
            #volumeClaimConfiguration:
              # Set custom storage class for DxE PVC
              #storageClassName: example-class
          mssqlServerContainer:
            image: "mcr.microsoft.com/mssql/server:2025-latest"
            imagePullPolicy: Always
            mssqlSecret: mssql
            acceptEula: true
            mssqlPID: Developer
            # Set a non-default SQL Server port. DxOperator will auto-detect
            # the port from other sources too, such as mssqlConfigMap
            #mssqlTcpPort: 51433
            # The MSSQL configMap (mssql.conf file)
            #mssqlConfigMap: mssql-config
            # Configuration options for the required persistent volume claim for SQL Server
            #volumeClaimConfiguration:
            #  resources:
            #    requests:
            #      storage: 2Gi
          # Additional pod containers, such as mssql-tools
          #containers:
          #- name: mssql-tools
            #image: "mcr.microsoft.com/mssql-tools"
            #command: [ "/bin/sh" ]
            #args: [ "-c", "tail -f /dev/null" ]
    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. For more information on configuring SQL Server to use a non-default port, see: Configure SQL Server's Listening Port

    Also note: If you applied a ConfigMap in the previous optional step, you must explicitly set spec.mssqlServerContainer.mssqlConfigMap to ensure it is used:

    mssqlConfigMap: mssql-config

  4. Apply the DxSqlAg custom resource YAML.

    kubectl apply -f DxSqlAg.yaml

  5. Verify the StatefulSet has been created.

    kubectl get sts dxsqlag

That's it! DxOperator will begin spinning up a new SQL Server Availability Group in Kubernetes and should - depending on cluster resources - finish within a few minutes. You can check on the progress using kubectl exec -itc dxe dxsqlag-0 -- dxcli get-ags-detail <vhost_name> <ag_name>.

Delete a DxSqlAg​

To delete a DxSqlAg, simply run:

warning

Deleting a DxSqlAg custom resource will also remove the StatefulSet managing the pods, meaning the cluster will become inoperable.

kubectl delete -f DxSqlAg.yaml

Next Steps​

Additional Information​