with one click
engine-hints-mssql
// Use when developing, reviewing, or testing SQL Server or MSSQL KubeBlocks addon behavior and needing engine-specific topology, lifecycle, readiness, storage, security, or HA constraints.
// Use when developing, reviewing, or testing SQL Server or MSSQL KubeBlocks addon behavior and needing engine-specific topology, lifecycle, readiness, storage, security, or HA constraints.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | engine-hints-mssql |
| description | Use when developing, reviewing, or testing SQL Server or MSSQL KubeBlocks addon behavior and needing engine-specific topology, lifecycle, readiness, storage, security, or HA constraints. |
Reference resolution: when this source-derived skill mentions docs/..., resolve it from the shared support package beside the installed user skills: ~/.codex/skills/kubeblocks-addon-source-docs/docs/... for Codex or ~/.claude/skills/kubeblocks-addon-source-docs/docs/... for Claude Code. In the shared kubeblocks-addon-docs checkout, the same files live under skills/kubeblocks-addon-source-docs/docs/.... When it mentions scripts/..., resolve it from the same support package under scripts/.... If you are working inside a checkout of the original apecloud/kubeblocks-addon-skills, repo-relative paths are also valid.
Engine name in KubeBlocks: mssql
| Major | ComponentDef prefix | Service versions | Default |
|---|---|---|---|
| 2022 | mssql-2022 | 2022.19.0, 2022.14.0 | 2022.19.0 |
| 2019 | mssql-2019 | 2019.30.0, 2019.29.0 | 2019.30.0 |
Only one topology: cluster (default). Uses the mssql component with regex ^mssql-\d+.
MSSQL requires at least 2Gi memory. SQL Server will not start below this threshold.
| Component | Version | Minimum CPU | Minimum memory limit | Reason |
|---|---|---|---|---|
| mssql | any | 1 | 2Gi | SQL Server minimum requirement; OOMKill or startup failure below 2Gi |
# MSSQL 2022 — 3 replicas (default)
helm install mssql-2022-test addons-cluster/mssql \
--set version=2022.19.0 \
--set replicas=3 \
--set cpu=1 \
--set memory=2 \
--set storage=20 \
--set extra.terminationPolicy=Delete
# MSSQL 2019 — 2 replicas
helm install mssql-2019-test addons-cluster/mssql \
--set version=2019.30.0 \
--set replicas=2 \
--set cpu=1 \
--set memory=2 \
--set storage=20 \
--set extra.terminationPolicy=Delete
apiVersion: v1
kind: Secret
metadata:
name: mssql-2022-test-certificates
data:
# Auto-generated self-signed cert; replace with custom cert if needed
dbm_certificate.crt: <base64-encoded-cert>
dbm_certificate.key: <base64-encoded-key>
private_key_password: <base64-encoded-password>
---
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
name: mssql-2022-test
annotations:
kubeblocks.io/extra-env: '{"MSSQL_PID":"Developer","MSSQL_COLLATION":"SQL_Latin1_General_CP1_CI_AS"}'
spec:
terminationPolicy: Delete
clusterDef: mssql
topology: cluster
componentSpecs:
- name: mssql
serviceVersion: "2022.19.0"
replicas: 3
resources:
limits:
cpu: "1"
memory: "2Gi"
requests:
cpu: "1"
memory: "2Gi"
volumeClaimTemplates:
- name: data
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 20Gi
volumes:
- name: certificates
secret:
secretName: mssql-2022-test-certificates
optional: true
env:
- name: MSSQL_PRIVATE_ENCRYPTION_PASSWORD
valueFrom:
secretKeyRef:
name: mssql-2022-test-certificates
key: private_key_password
- name: HOST_NETWORK
value: "false"
- name: DEFAULT_DB_NAME
value: "db1"
- name: IS_REMOTE_STANDBY
value: "false"
- name: REMOTE_SESSION_TIMEOUT_SECONDS
value: "30"
apiVersion: v1
kind: Secret
metadata:
name: mssql-2019-test-certificates
data:
dbm_certificate.crt: <base64-encoded-cert>
dbm_certificate.key: <base64-encoded-key>
private_key_password: <base64-encoded-password>
---
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
name: mssql-2019-test
annotations:
kubeblocks.io/extra-env: '{"MSSQL_PID":"Developer","MSSQL_COLLATION":"SQL_Latin1_General_CP1_CI_AS"}'
spec:
terminationPolicy: Delete
clusterDef: mssql
topology: cluster
componentSpecs:
- name: mssql
serviceVersion: "2019.30.0"
replicas: 2
resources:
limits:
cpu: "1"
memory: "2Gi"
requests:
cpu: "1"
memory: "2Gi"
volumeClaimTemplates:
- name: data
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 20Gi
volumes:
- name: certificates
secret:
secretName: mssql-2019-test-certificates
optional: true
env:
- name: MSSQL_PRIVATE_ENCRYPTION_PASSWORD
valueFrom:
secretKeyRef:
name: mssql-2019-test-certificates
key: private_key_password
- name: HOST_NETWORK
value: "false"
- name: DEFAULT_DB_NAME
value: "db1"
- name: IS_REMOTE_STANDBY
value: "false"
- name: REMOTE_SESSION_TIMEOUT_SECONDS
value: "30"
MSSQL requires Helm-based restore to maintain structural homogeneity (certificate Secret + volume + env vars). Do NOT use raw YAML for MSSQL restore — the cluster chart auto-generates the certificate Secret and all required mounts.
helm install <restore-name> addons-cluster/mssql \
--set version=<service-version> \
--set replicas=<N> \
--set cpu=<cpu> --set memory=<memory> --set storage=<storage> \
--set extra.terminationPolicy=Delete \
--set-json 'restoreFrom="{\"mssql\":{\"name\":\"<backup-name>\",\"namespace\":\"<namespace>\",\"volumeRestorePolicy\":\"Parallel\"}}"'
Example (restore from full backup, 3 replicas, MSSQL 2019):
helm install mssql19-rst addons-cluster/mssql \
--set version=2019.30.0 \
--set replicas=3 \
--set cpu=1 --set memory=2 --set storage=21 \
--set extra.terminationPolicy=Delete \
--set-json 'restoreFrom="{\"mssql\":{\"name\":\"backup-full-1776254454\",\"namespace\":\"default\",\"volumeRestorePolicy\":\"Parallel\"}}"'
The backup ActionSet saves the original cluster's certificate (PFX or CER+PVK) and password to backup storage. During restore:
prepareData downloads backup certificates to ${BACKUP_DIR}/INIT_BACKUPS/certificates/create_certificate() uses backup certificates (with backup password) if present, otherwise falls back to the Helm-generated certificate from the mounted volumeThis ensures the restore cluster uses the same certificate as the source cluster (thumbprint match), which is critical for TDE or any certificate-based data encryption.
storage must be >= source cluster PVC size (Kubernetes cannot shrink volumes)restoreFrom value must use --set-json (not --set) because it contains JSON braceshelm uninstall <restore-name>The certificates volume is declared in the Cluster spec (not in the ComponentDefinition). The cluster chart generates a self-signed certificate Secret named <cluster-name>-certificates and mounts it via spec.componentSpecs[].volumes. This allows each cluster instance to have its own certificate, and supports custom certificates via Helm values.
| Parameter | Default | Description |
|---|---|---|
version | 2022.19.0 | Service version |
replicas | 3 | Number of MSSQL replicas |
cpu | 1 | CPU limit (cores) |
memory | 2 | Memory limit (Gi) |
storage | 20 | PVC size (Gi) |
productEdition | Developer | MSSQL edition: Developer, Express, Standard, Enterprise, etc. |
productKey | "" | Product key (overrides productEdition if set) |
collation | SQL_Latin1_General_CP1_CI_AS | Default collation |
hostNetworkEnabled | false | Enable host network for cross-host AG access |
defaultDBName | "" | Default database name (defaults to db1 if empty) |
extra.terminationPolicy | (from kblib) | Delete or DoNotTerminate |
certificates.custom | false | Use custom certificates instead of auto-generated |
certificates.cert | "" | Base64 X.509 certificate (when custom=true) |
certificates.privateKey | "" | Base64 PVK private key (when custom=true) |
certificates.password | "" | Raw decryption password for PVK/PFX |
| Parameter | Default | Description |
|---|---|---|
remoteSetting.isStandby | false | Create as a disaster-recovery standby |
remoteSetting.sessionTimeoutSeconds | 30 | Remote session timeout |
remoteSetting.primaryHost | "" | Primary instance host (standby mode) |
remoteSetting.primaryPort | "" | Primary instance port (standby mode) |
remoteSetting.primaryAgName | ag1 | Primary AG name (standby mode) |
remoteSetting.primaryCertificateSecret.name | "" | Secret with primary's certificates (standby mode) |
# Get SA credentials
SA_USER=$(kubectl get secret ${CLUSTER_NAME}-mssql-account-sa \
-o jsonpath='{.data.username}' | base64 -d)
SA_PASS=$(kubectl get secret ${CLUSTER_NAME}-mssql-account-sa \
-o jsonpath='{.data.password}' | base64 -d)
# Connect via sqlcmd inside the pod
kubectl exec -it ${CLUSTER_NAME}-mssql-0 -c mssql -- \
/opt/mssql-tools/bin/sqlcmd -S localhost -U "$SA_USER" -P "$SA_PASS" -Q "SELECT @@VERSION"