API Reference
This document provides a technical reference of the Custom Resources used by DxOperator. It includes an exhaustive list of all configuration options available.
DxSqlAg
A DxSqlAg represents one deployment of a Microsoft SQL Server Availability Group cluster.
| Group | Version | Kind |
|---|---|---|
| dh2i.com | v1 | DxSqlAg |
| Field | Description |
|---|---|
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info |
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info |
metadata ObjectMeta | Standard object's metadata. More info |
spec SqlAgSpec | spec defines the desired characteristics of the DxSqlAg cluster. |
BasicMetadata
Appears in:
- ServiceTemplateSpec
- SqlAgPodSpec
- SqlAgStatefulSetSpec
- VolumeClaimConfiguration
- PerServiceCustomizationSpec
| Field | Description |
|---|---|
annotations object | Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info |
labels object | Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info |
DxEnterpriseContainerSpec
Appears in:
| Field | Description |
|---|---|
acceptEula boolean | Whether or not the user accepts the DxEnterprise EULA |
clusterSecret string | "The secret containing a DX_PASSKEY, DX_LICENSE, and optional DX_OTPK environment variable(s). |
env EnvVar array | List of environment variables to set in the container. Cannot be updated. |
envFrom EnvFromSource array | List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. |
image string | The DxEnterprise container image. Default: docker.io/dh2i/dxe:latest |
imagePullPolicy string | Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info |
joinTarget TargetConfiguration | A configuration for the external target cluster each pod will join to. |
otpkExpiration string | The date and/or time the OTPK will expire. Default: 1 hour |
readinessProbe Probe | Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info |
resources ResourceRequirements | Compute Resources required by this container. Cannot be updated. More info |
securityContext SecurityContext | SecurityContext defines the security options the container should be run with. If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext. More info |
vhostName string | The name of the DxEnterprise Vhost. Default: VHOST1 |
volumeClaimConfiguration VolumeClaimConfiguration | Configuration options for the required volume claim for DxEnterprise. |
volumeMounts VolumeMount array | Additional pod volumes to mount into the container's filesystem. |
MssqlServerContainerSpec
Appears in:
| Field | Description |
|---|---|
acceptEula boolean | Whether or not the user accepts the SQL Server EULA. |
env EnvVar array | List of environment variables to set in the container. Cannot be updated. |
envFrom EnvFromSource array | List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. |
image string | The SQL Server container image. Default: mcr.microsoft.com/mssql/server:latest |
imagePullPolicy string | Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info |
mssqlConfigMap string | The name of the ConfigMap that contains configuration info for the mssql.conf file. |
mssqlPID string | The product ID (edition) the SQL Server container will run with, or a license key. |
mssqlSecret string | The secret containing the MSSQL_SA_PASSWORD environment variable. |
mssqlTcpPort integer | The listening port for MSSQL. Default: 1433 |
readinessProbe Probe | Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info |
resources ResourceRequirements | Compute Resources required by this container. Cannot be updated. More info |
securityContext SecurityContext | The security context for the SQL Server container. The NET_BIND_SERVICE capability is added by default in OpenShift clusters. |
volumeClaimConfiguration VolumeClaimConfiguration | Configuration options for the required volume claim for SQL Server. |
volumeMounts VolumeMount array | Additional pod volumes to mount into the container's filesystem. |
PerServiceCustomizationSpec
Appears in:
| Field | Description |
|---|---|
clusterIP string | clusterIP is the IP address of the service and is usually assigned randomly. If an address is specified manually, is in-range (as per system configuration), and is not in use, it will be allocated to the service; otherwise creation of the service will fail. This field may not be changed through updates unless the type field is also being changed to ExternalName (which requires this field to be blank) or the type field is being changed from ExternalName (in which case this field may optionally be specified, as describe above). Valid values are "None", empty string (""), or a valid IP address. Setting this to "None" makes a "headless service" (no virtual IP), which is useful when direct endpoint connections are preferred and proxying is not required. Only applies to types ClusterIP, NodePort, and LoadBalancer. If this field is specified when creating a Service of type ExternalName, creation will fail. This field will be wiped when updating a Service to type ExternalName. More info |
clusterIPs string array | ClusterIPs is a list of IP addresses assigned to this service, and are usually assigned randomly. If an address is specified manually, is in-range (as per system configuration), and is not in use, it will be allocated to the service; otherwise creation of the service will fail. This field may not be changed through updates unless the type field is also being changed to ExternalName (which requires this field to be empty) or the type field is being changed from ExternalName (in which case this field may optionally be specified, as describe above). Valid values are "None", empty string (""), or a valid IP address. Setting this to "None" makes a "headless service" (no virtual IP), which is useful when direct endpoint connections are preferred and proxying is not required. Only applies to types ClusterIP, NodePort, and LoadBalancer. If this field is specified when creating a Service of type ExternalName, creation will fail. This field will be wiped when updating a Service to type ExternalName. If this field is not specified, it will be initialized from the clusterIP field. If this field is specified, clients must ensure that clusterIPs[0] and clusterIP have the same value. This field may hold a maximum of two entries (dual-stack IPs, in either order). These IPs must correspond to the values of the ipFamilies field. Both clusterIPs and ipFamilies are governed by the ipFamilyPolicy field. More info |
externalIPs string array | externalIPs is a list of IP addresses for which nodes in the cluster will also accept traffic for this service. These IPs are not managed by Kubernetes. The user is responsible for ensuring that traffic arrives at a node with this IP. A common example is external load-balancers that are not part of the Kubernetes system. |
externalName string | externalName is the external reference that discovery mechanisms will return as an alias for this service (e.g. a DNS CNAME record). No proxying will be involved. Must be a lowercase RFC-1123 hostname and requires type to be "ExternalName". |
healthCheckNodePort integer | healthCheckNodePort specifies the healthcheck nodePort for the service. This only applies when type is set to LoadBalancer and externalTrafficPolicy is set to Local. If a value is specified, is in-range, and is not in use, it will be used. If not specified, a value will be automatically allocated. External systems (e.g. load-balancers) can use this port to determine if a given node holds endpoints for this service or not. If this field is specified when creating a Service which does not need it, creation will fail. This field will be wiped when updating a Service to no longer need it (e.g. changing type). This field cannot be updated once set. |
loadBalancerIP integer | Only applies to Service Type: LoadBalancer. This feature depends on whether the underlying cloud-provider supports specifying the loadBalancerIP when a load balancer is created. This field will be ignored if the cloud-provider does not support the feature. Deprecated: This field was under-specified and its meaning varies across implementations. Using it is non-portable and it may not support dual-stack. Users are encouraged to use implementation-specific annotations when available. |
loadBalancerSourceRanges string array | If specified and supported by the platform, this will restrict traffic through the cloud-provider load-balancer will be restricted to the specified client IPs. This field will be ignored if the cloud-provider does not support the feature." More info |
metadata BasicMetadata | Annotations and labels for the object metadata. |
name string | The full name of the service (templateName-podName, e.g. 'lb-dxsqlag-0'). |
ports ServicePort array | The list of ports that are exposed by this service. These port entries take precedence over the parent ServiceTemplateSpec. Duplicates are overwritten. More info |
ServiceTemplateSpec
Appears in:
| Field | Description |
|---|---|
allocateLoadBalancerNodePorts boolean | allocateLoadBalancerNodePorts defines if NodePorts will be automatically allocated for services with type LoadBalancer. Default is "true". It may be set to "false" if the cluster load-balancer does not rely on NodePorts. If the caller requests specific NodePorts (by specifying a value), those requests will be respected, regardless of this field. This field may only be set for services with type LoadBalancer and will be cleared if the type is changed to any other type. |
externalTrafficPolicy string | externalTrafficPolicy describes how nodes distribute service traffic they receive on one of the Service's "externally-facing" addresses (NodePorts, ExternalIPs, and LoadBalancer IPs). If set to "Local", the proxy will configure the service in a way that assumes that external load balancers will take care of balancing the service traffic between nodes, and so each node will deliver traffic only to the node-local endpoints of the service, without masquerading the client source IP. (Traffic mistakenly sent to a node with no endpoints will be dropped.) The default value, "Cluster", uses the standard behavior of routing to all endpoints evenly (possibly modified by topology and other features). Note that traffic sent to an External IP or LoadBalancer IP from within the cluster will always get "Cluster" semantics, but clients sending to a NodePort from within the cluster may need to take traffic policy into account when picking a node. |
internalTrafficPolicy string | InternalTrafficPolicy describes how nodes distribute service traffic they receive on the ClusterIP. If set to "Local", the proxy will assume that pods only want to talk to endpoints of the service on the same node as the pod, dropping the traffic if there are no local endpoints. The default value, "Cluster", uses the standard behavior of routing to all endpoints evenly (possibly modified by topology and other features). |
ipFamilies string array | IPFamilies is a list of IP families (e.g. IPv4, IPv6) assigned to this service. This field is usually assigned automatically based on cluster configuration and the ipFamilyPolicy field. If this field is specified manually, the requested family is available in the cluster, and ipFamilyPolicy allows it, it will be used; otherwise creation of the service will fail. This field is conditionally mutable: it allows for adding or removing a secondary IP family, but it does not allow changing the primary IP family of the Service. Valid values are "IPv4" and "IPv6". This field only applies to Services of types ClusterIP, NodePort, and LoadBalancer, and does apply to "headless" services. This field will be wiped when updating a Service to type ExternalName. This field may hold a maximum of two entries (dual-stack families, in either order). These families must correspond to the values of the clusterIPs field, if specified. Both clusterIPs and ipFamilies are governed by the ipFamilyPolicy field. |
ipFamilyPolicy string | IPFamilyPolicy represents the dual-stack-ness requested or required by this Service. If there is no value provided, then this field will be set to SingleStack. Services can be "SingleStack" (a single IP family), "PreferDualStack" (two IP families on dual-stack configured clusters or a single IP family on single-stack clusters), or "RequireDualStack" (two IP families on dual-stack configured clusters, otherwise fail). The ipFamilies and clusterIPs fields depend on the value of this field. This field will be wiped when updating a service to type ExternalName. |
loadBalancerClass string | loadBalancerClass is the class of the load balancer implementation this Service belongs to. If specified, the value of this field must be a label-style identifier, with an optional prefix, e.g. "internal-vip" or "example.com/internal-vip". Unprefixed names are reserved for end-users. This field can only be set when the Service type is 'LoadBalancer'. If not set, the default load balancer implementation is used, today this is typically done through the cloud provider integration, but should apply for any default implementation. If set, it is assumed that a load balancer implementation is watching for Services with a matching class. Any default load balancer implementation (e.g. cloud providers) should ignore Services that set this field. This field can only be set when creating or updating a Service to type 'LoadBalancer'. Once set, it can not be changed. This field will be wiped when a service is updated to a non 'LoadBalancer' type. |
metadata BasicMetadata | Annotations and labels for the object metadata. |
name string | The name of the service template. For each pod in the cluster, the service template name is joined with the pod name to create a load balancer name. |
perServiceCustomizations PerServiceCustomizationSpec array | An array of per-service configuration overrides. Used when a service created by a serviceTemplate needs specific customizations. Keyed by 'name' - the full name of the service, e.g. 'templateName-podName' |
ports ServicePort array | The list of ports that are exposed by this service. More info |
publishNotReadyAddresses boolean | publishNotReadyAddresses indicates that any agent which deals with endpoints for this Service should disregard any indications of ready/not-ready. The primary use case for setting this field is for a StatefulSet's Headless Service to propagate SRV DNS records for its Pods for the purpose of peer discovery. The Kubernetes controllers that generate Endpoints and EndpointSlice resources for Services interpret this to mean that all endpoints are considered "ready" even if the Pods themselves are not. Agents which consume only Kubernetes generated endpoints through the Endpoints or EndpointSlice resources can safely assume this behavior. |
selector object | Route service traffic to pods with label keys and values matching this selector. Only applies to types ClusterIP, NodePort, and LoadBalancer. Ignored if type is ExternalName. More info |
sessionAffinity string | Supports "ClientIP" and "None". Used to maintain session affinity. Enable client IP based session affinity. Must be ClientIP or None. Defaults to None. More info |
sessionAffinityConfig SessionAffinityConfig | sessionAffinityConfig contains the configurations of session affinity. |
type string | type determines how the Service is exposed. Defaults to ClusterIP. Valid options are ExternalName, ClusterIP, NodePort, and LoadBalancer. "ClusterIP" allocates a cluster-internal IP address for load-balancing to endpoints. Endpoints are determined by the selector or if that is not specified, by manual construction of an Endpoints object or EndpointSlice objects. If clusterIP is "None", no virtual IP is allocated and the endpoints are published as a set of endpoints rather than a virtual IP. "NodePort" builds on ClusterIP and allocates a port on every node which routes to the same endpoints as the clusterIP. "LoadBalancer" builds on NodePort and creates an external load-balancer (if supported in the current cloud) which routes to the same endpoints as the clusterIP. "ExternalName" aliases this service to the specified externalName. Several other fields do not apply to ExternalName services. More info |
SqlAgConfiguration
Appears in:
| Field | Description |
|---|---|
asynchronousReplicas integer | The number of asynchronous replicas to create in the SQL Server Availability Group cluster. Valid values are 0-9. The total number of synchronous + asynchronous + configuration-only replicas cannot exceed 9. |
availabilityGroupClusterType string | The CLUSTER_TYPE value to set when creating the SQL Server Availability Group. Defaults to EXTERNAL. Set this value to NONE to create a Read-Scale Cluster. |
availabilityGroupListenerPort integer | The port number to use to create a SQL Server Availability Group Listener. Must be a valid TCP port number (1-65535) if set. |
availabilityGroupName string | The name of the SQL Server Availability Group, within SQL Server. This is different from the cluster name. Defaults to AG1 |
availabilityGroupOptions string | Extra options to set when creating the SQL Server Availability Group. With SQL Server 2022 and newer, one useful extra option is CONTAINED. See Microsoft's Documentation. |
configurationOnlyReplicas integer | The number of configuration-only (witness) replicas to create in the SQL Server Availability Group cluster. Valid values are 0-1. The total number of synchronous + asynchronous + configuration-only replicas cannot exceed 9. |
createLoadBalancers boolean | Whether or not to create load balancers for external access to the Kubernetes pods. Defaults to false. |
disableModeSwitching boolean | Disables automatic availability mode switching when scaling the synchronous + asynchronous StatefulSet. |
disableTunnels boolean | Disables creating tunnels for the AG database mirroring endpoints. |
synchronousReplicas integer | The number of synchronous replicas to create in the SQL Server Availability Group cluster. Valid values are 0-9. The total number of synchronous + asynchronous + configuration-only replicas cannot exceed 9. |
SqlAgPodSpec
Appears in:
| Field | Description |
|---|---|
affinity Affinity | If specified, the pod's scheduling constraints |
containers Container array | Additional list of containers belonging to the pod. Containers cannot currently be added or removed. Cannot be updated. |
dnsConfig PodDNSConfig | Specifies the DNS parameters of a pod. Parameters specified here will be merged to the generated DNS configuration based on DNSPolicy. |
dnsPolicy string | Set DNS policy for the pod. Defaults to "ClusterFirst". Valid values are 'ClusterFirstWithHostNet', 'ClusterFirst', 'Default' or 'None'. DNS parameters given in DNSConfig will be merged with the policy selected with DNSPolicy. To have DNS options set along with hostNetwork, you have to specify DNS policy explicitly to 'ClusterFirstWithHostNet'. |
dxEnterpriseContainer DxEnterpriseContainerSpec | The configuration for the DxEnterprise container. |
hostAliases HostAlias array | HostAliases is an optional list of hosts and IPs that will be injected into the pod's hosts file if specified. |
imagePullSecrets LocalObjectReference array | ImagePullSecrets is an optional list of references to secrets in the same namespace to use for pulling any of the images used by this PodSpec. If specified, these secrets will be passed to individual puller implementations for them to use. More info |
initContainers Container array | List of initialization containers belonging to the pod. Init containers are executed in order prior to containers being started. If any init container fails, the pod is considered to have failed and is handled according to its restartPolicy. The name for an init container or normal container must be unique among all containers. Init containers may not have Lifecycle actions, Readiness probes, Liveness probes, or Startup probes. The resourceRequirements of an init container are taken into account during scheduling by finding the highest request/limit for each resource type, and then using the max of of that value or the sum of the normal containers. Limits are applied to init containers in a similar fashion. Init containers cannot currently be added or removed. Cannot be updated. More info |
metadata BasicMetadata | Annotations and labels for the object metadata. |
mssqlServerContainer MssqlServerContainerSpec | The configuration for the Microsoft SQL Server container. |
nodeName string | NodeName is a request to schedule this pod onto a specific node. If it is non-empty, the scheduler simply schedules this pod onto that node, assuming that it fits resource requirements. |
nodeSelector object | NodeSelector is a selector which must be true for the pod to fit on a node. Selector which must match a node's labels for the pod to be scheduled on that node. More info |
securityContext PodSecurityContext | The pod's security context. FsGroup must be set to 10001 for SQL Server. Default (Kubernetes): fsGroup: 10001; Default (OpenShift): fsGroupChangePolicy: OnRootMismatch |
terminationGracePeriodSeconds integer | Optional duration in seconds the pod needs to terminate gracefully. May be decreased in delete request. Value must be non-negative integer. The value zero indicates stop immediately via the kill signal (no opportunity to shut down). If this value is nil, the default grace period will be used instead. The grace period is the duration in seconds after the processes running in the pod are sent a termination signal and the time when the processes are forcibly halted with a kill signal. Set this value longer than the expected cleanup time for your process. Defaults to 30 seconds. |
tolerations Toleration array | If specified, the pod's tolerations. |
topologySpreadConstraints TopologySpreadConstraint array | TopologySpreadConstraints describes how a group of pods ought to spread across topology domains. Scheduler will schedule pods in a way which abides by the constraints. All topologySpreadConstraints are ANDed. |
volumes volume array | List of volumes that can be mounted by containers belonging to the pod. More info |
SqlAgSpec
Appears in:
| Field | Description |
|---|---|
serviceTemplates ServiceTemplateSpec array | An array of service templates keyed by name. |
sqlAgConfiguration SqlAgConfiguration | Configuration options for the SQL Server Availability Group. |
statefulSetSpec *SqlAgStatefulSetSpec | The configuration for the DxSqlAg StatefulSet. |
SqlAgStatefulSetSpec
Appears in:
| Field | Description |
|---|---|
metadata BasicMetadata | Annotations and labels for the object metadata. |
persistentVolumeClaimRetentionPolicy StatefulSetPersistentVolumeClaimRetentionPolicy | persistentVolumeClaimRetentionPolicy describes the lifecycle of persistent volume claims created from volumeClaimTemplates. By default, all persistent volume claims are created as needed and retained until manually deleted. This policy allows the lifecycle to be altered, for example by deleting persistent volume claims when their stateful set is deleted, or when their pod is scaled down. |
podManagementPolicy string | podManagementPolicy controls how pods are created during initial scale up, when replacing pods on nodes, or when scaling down. The default policy is OrderedReady, where pods are created in increasing order (pod-0, then pod-1, etc) and the controller will wait until each pod is ready before continuing. When scaling down, the pods are removed in the opposite order. The alternative policy is Parallel which will create pods in parallel to match the desired scale without waiting, and on scale down will delete all pods at once. |
podSpec *SqlAgPodSpec | The spec for the DxSqlAg pods. |
revisionHistoryLimit integer | revisionHistoryLimit is the maximum number of revisions that will be maintained in the StatefulSet's revision history. The revision history consists of all revisions not represented by a currently applied StatefulSetSpec version. The default value is 10. |
selector LabelSelector | selector is a label query over pods that should match the replica count. It must match the pod template's labels. If this property isn't provided, DxOperator will fill it. More info |
updateStrategy StatefulSetUpdateStrategy | updateStrategy indicates the StatefulSetUpdateStrategy that will be employed to update Pods in the StatefulSet when a revision is made to Template. |
volumeClaimTemplates PersistentVolumeClaim array | volumeClaimTemplates is a list of claims that pods are allowed to reference. The StatefulSet controller is responsible for mapping network identities to claims in a way that maintains the identity of a pod. Every claim in this list must have at least one matching (by name) volumeMount in one container in the template. A claim in this list takes precedence over any volumes in the template, with the same name. |
TargetConfiguration
Appears in:
| Field | Description |
|---|---|
target string | The target hostname, IP, or FQDN for the join process. |
useNat bool | Whether or not the target is a NAT match-making service. |
VolumeClaimConfiguration
Appears in:
| Field | Description |
|---|---|
accessModes string array | accessModes contains all ways the volume can be mounted. More info |
metadata BasicMetadata | Annotations and labels for the object metadata. |
storageClassName string | storageClassName is the name of the StorageClass required by the claim. More info |
resources ResourceRequirements | resources represents the minimum resources the volume should have. If RecoverVolumeExpansionFailure feature is enabled users are allowed to specify resource requirements that are lower than previous value but must still be higher than capacity recorded in the status field of the claim. More info |