Run any Skill in Manus with one click

$pwd:

engine-hints-mssql

Name: Engine Hints Mssql
Author: apecloud

// 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.

Run Skill in Manus

$ git log --oneline --stat

stars:0

forks:0

updated:May 6, 2026 at 04:41

SKILL.md

readonly

package.json

"author": "apecloud"

"repository": "apecloud/kubeblocks-addon-docs"

View GitHub Repository

$ install --globalskills.sh

$ download --local

Run Skill in Manus

[HINT] Download the complete skill directory including SKILL.md and all related files

Run any Skill with one click

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 Hints: MSSQL

Engine name in KubeBlocks: mssql

Versions

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

Topology

Only one topology: cluster (default). Uses the mssql component with regex ^mssql-\d+.

Component Resource Minimums

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

Instance Creation Examples

Helm install (recommended)

# 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

Raw YAML — MSSQL 2022 cluster (3 replicas)

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"

Raw YAML — MSSQL 2019 cluster (2 replicas)

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"

Restore from Backup

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 restore command

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\"}}"'

Certificate handling during restore

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/
The entrypoint create_certificate() uses backup certificates (with backup password) if present, otherwise falls back to the Helm-generated certificate from the mounted volume

This 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.

Important notes

Release name must be 15 characters or fewer (enforced by the cluster chart)
storage must be >= source cluster PVC size (Kubernetes cannot shrink volumes)
The restoreFrom value must use --set-json (not --set) because it contains JSON braces
Cleanup: helm uninstall <restore-name>

Cluster-specific volumes

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.

Helm Values Reference

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

Remote standby settings

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)

Connect

# 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"

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.