Skip to main content
Version: v1.0.63.0

DxOperator Quick Start Guide

DxOperator is a software extension to Kubernetes that uses custom resource definitions to automate the deployment of DxEnterprise clusters. DxEnterprise then provides all of the instrumentation to create, configure, manage and provide automatic failover for Microsoft SQL Server availability group workloads in Kubernetes.

For a free developer license to test DxOperator - Request a free license.

Prerequisites

  • A Kubernetes cluster installed with at least 4GB of RAM.

  • An internet connection.

Install DxOperator

  1. Download the DxOperator YAML.

    wget https://dxoperator.dh2i.com/dxesqlag/files/v1.yaml
  2. Apply the DxOperator YAML.

    kubectl apply -f v1.yaml

Create a DxEnterpriseSqlAg

tip

To deploy DxOperator with non-default SQL Server ports, please see the DxOperator with Non-default Ports for SQL Server

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

    kubectl create secret generic dxe --from-literal=DX_PASSKEY=<pass> --from-literal=DX_LICENSE=<license_key>
    kubectl create secret generic mssql --from-literal=MSSQL_SA_PASSWORD=<pass>
  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
  1. Copy the example DxEnterpriseSqlAg.yaml file below or download the file.

    info

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

    DxEnterpriseSqlAg.yaml
    apiVersion: dh2i.com/v1
    kind: DxEnterpriseSqlAg
    metadata:
    name: dxesqlag
    spec:
    synchronousReplicas: 3
    asynchronousReplicas: 0
    # ConfigurationOnlyReplicas are only allowed with availabilityGroupClusterType set to EXTERNAL
    configurationOnlyReplicas: 0
    availabilityGroupName: AG1
    # Listener port for the availability group (uncomment to apply)
    #availabilityGroupListenerPort: 14033
    # For a contained availability group, add the option CONTAINED
    availabilityGroupOptions: null
    # Valid options are EXTERNAL (automatic failover) and NONE (no automatic failover)
    availabilityGroupClusterType: EXTERNAL
    createLoadBalancers: true
    template:
    metadata:
    labels:
    label: example
    annotations:
    annotation: example
    spec:
    dxEnterpriseContainer:
    image: "docker.io/dh2i/dxe:latest"
    imagePullPolicy: Always
    acceptEula: true
    clusterSecret: dxe
    vhostName: VHOST1
    joinExistingCluster: false
    # QoS – guaranteed (uncomment to apply)
    #resources:
    #limits:
    #memory: 1Gi
    #cpu: '1'
    # Configuration options for the required persistent volume claim for DxEnterprise
    volumeClaimConfiguration:
    storageClassName: null
    resources:
    requests:
    storage: 1Gi
    mssqlServerContainer:
    image: "mcr.microsoft.com/mssql/server:latest"
    imagePullPolicy: Always
    mssqlSecret: mssql
    acceptEula: true
    mssqlPID: Developer
    # Only set this to a value if you created a ConfigMap
    mssqlConfigMap: null
    # QoS – guaranteed (uncomment to apply)
    #resources:
    #limits:
    #memory: 2Gi
    #cpu: '2'
    # Configuration options for the required persistent volume claim for SQL Server
    volumeClaimConfiguration:
    storageClassName: null
    resources:
    requests:
    storage: 2Gi
    # Additional side-car containers, such as mssql-tools (uncomment to apply)
    #containers:
    #- name: mssql-tools
    #image: "mcr.microsoft.com/mssql-tools"
    #command: [ "/bin/sh" ]
    #args: [ "-c", "tail -f /dev/null" ]
    caution

    If you applied a ConfigMap in the previous optional step, you need to modify the highlighted spec.mssqlServerContainer.mssqlConfigMap value, otherwise the ConfigMap will not be applied:

    mssqlConfigMap: mssql-config
  2. Apply the DxEnterpriseSqlAg custom resource YAML.

    kubectl apply -f DxEnterpriseSqlAg.yaml
  3. Verify the deployment.

    kubectl get pods
  4. Verify load balancer assignments.

    kubectl get services

Creating an Availability Group Listener

  1. In the DxEnterpriseSqlAg spec, add a new entry for the AG Listener.

    DxEnterpriseSqlAg.yaml
    spec:
    availabilityGroupListenerPort: 14033
  2. Apply the below service YAML to add a load balancer for the listener.

    info

    Make sure to set the selector to dh2i.com/entity: <DxEnterpriseSqlAg_name>, using the name that was applied in the DxEnterpriseSqlAg.yaml above.

    Example Load Balancer Service
    apiVersion: v1
    kind: Service
    metadata:
    name: dxemssql-cluster-lb
    spec:
    type: LoadBalancer
    selector:
    dh2i.com/entity: dxesqlag
    ports:
    - name: sql
    protocol: TCP
    port: 1433
    targetPort: 1433
    - name: listener
    protocol: TCP
    port: 14033
    targetPort: 14033
    - name: dxe
    protocol: TCP
    port: 7979
    targetPort: 7979
  3. Verify the load balancer assignments.

    kubectl get services

Removing Custom Resources and DxOperator

The below steps will allow you to delete the custom resources and PVCs to redeploy with the same operator (steps 1 & 2). Or you can optionally also delete DxOperator completely (step 3).

  1. Delete the DxEnterpriseSqlAg custom resource YAML.

    kubectl delete -f DxEnterpriseSqlAg.yaml
  2. Delete the persistent volume claims (PVC).

    kubectl delete pvc --all
  3. Delete the DxOperator YAML.

    danger

    Running this command will delete the DxEnterpriseSqlAg CRD. If any DxEnterpriseSqlAg custom resources remain in the Kubernetes cluster, Kubernetes will destroy them as part of the deletion process. Only run this command if you intend on removing every DxEnterpiseSqlAg too!

    To list all DxEnterpriseSqlAgs, run 'kubectl get dxesqlag'.

    kubectl delete -f v1.yaml