From ca9fc209c16cf2b930b58490caef7719ce4cc976 Mon Sep 17 00:00:00 2001 From: Neaj Morshad Date: Wed, 16 Oct 2024 16:09:40 +0600 Subject: [PATCH 1/5] Add MSSQLServer TLS/SSL Encryption doc Signed-off-by: Neaj Morshad --- .../mssqlserver/tls/clusterissuer.yaml | 7 + docs/examples/mssqlserver/tls/issuer.yaml | 8 + .../mssqlserver/tls/rd-cluster-ssl.yaml | 23 ++ .../examples/mssqlserver/tls/rd-sentinel.yaml | 24 ++ .../mssqlserver/tls/rd-standalone-ssl.yaml | 19 ++ .../mssqlserver/tls/sentinel-ssl.yaml | 20 ++ docs/guides/mssqlserver/tls/_Index.md | 10 + docs/guides/mssqlserver/tls/ag_cluster.md | 286 ++++++++++++++++++ docs/guides/mssqlserver/tls/overview.md | 73 +++++ docs/guides/mssqlserver/tls/standalone.md | 198 ++++++++++++ 10 files changed, 668 insertions(+) create mode 100644 docs/examples/mssqlserver/tls/clusterissuer.yaml create mode 100644 docs/examples/mssqlserver/tls/issuer.yaml create mode 100644 docs/examples/mssqlserver/tls/rd-cluster-ssl.yaml create mode 100644 docs/examples/mssqlserver/tls/rd-sentinel.yaml create mode 100644 docs/examples/mssqlserver/tls/rd-standalone-ssl.yaml create mode 100644 docs/examples/mssqlserver/tls/sentinel-ssl.yaml create mode 100644 docs/guides/mssqlserver/tls/_Index.md create mode 100644 docs/guides/mssqlserver/tls/ag_cluster.md create mode 100644 docs/guides/mssqlserver/tls/overview.md create mode 100644 docs/guides/mssqlserver/tls/standalone.md diff --git a/docs/examples/mssqlserver/tls/clusterissuer.yaml b/docs/examples/mssqlserver/tls/clusterissuer.yaml new file mode 100644 index 0000000000..f18ef6ca85 --- /dev/null +++ b/docs/examples/mssqlserver/tls/clusterissuer.yaml @@ -0,0 +1,7 @@ +apiVersion: cert-manager.io/v1 +kind: ClusterIssuer +metadata: + name: redis-ca-issuer +spec: + ca: + secretName: redis-ca diff --git a/docs/examples/mssqlserver/tls/issuer.yaml b/docs/examples/mssqlserver/tls/issuer.yaml new file mode 100644 index 0000000000..c812454645 --- /dev/null +++ b/docs/examples/mssqlserver/tls/issuer.yaml @@ -0,0 +1,8 @@ +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: redis-ca-issuer + namespace: demo +spec: + ca: + secretName: redis-ca diff --git a/docs/examples/mssqlserver/tls/rd-cluster-ssl.yaml b/docs/examples/mssqlserver/tls/rd-cluster-ssl.yaml new file mode 100644 index 0000000000..5da87a0846 --- /dev/null +++ b/docs/examples/mssqlserver/tls/rd-cluster-ssl.yaml @@ -0,0 +1,23 @@ +apiVersion: kubedb.com/v1 +kind: Redis +metadata: + name: rd-tls + namespace: demo +spec: + version: "6.2.14" + mode: Cluster + cluster: + shards: 3 + replicas: 1 + tls: + issuerRef: + apiGroup: "cert-manager.io" + kind: Issuer + name: redis-ca-issuer + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi diff --git a/docs/examples/mssqlserver/tls/rd-sentinel.yaml b/docs/examples/mssqlserver/tls/rd-sentinel.yaml new file mode 100644 index 0000000000..360e5ed13a --- /dev/null +++ b/docs/examples/mssqlserver/tls/rd-sentinel.yaml @@ -0,0 +1,24 @@ +apiVersion: kubedb.com/v1 +kind: Redis +metadata: + name: rd-tls + namespace: demo +spec: + version: "6.2.14" + mode: Sentinel + replicas: 3 + sentinelRef: + name: sen-tls + namespace: demo + tls: + issuerRef: + apiGroup: "cert-manager.io" + kind: ClusterIssuer + name: redis-ca-issuer + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi diff --git a/docs/examples/mssqlserver/tls/rd-standalone-ssl.yaml b/docs/examples/mssqlserver/tls/rd-standalone-ssl.yaml new file mode 100644 index 0000000000..28398aa2f7 --- /dev/null +++ b/docs/examples/mssqlserver/tls/rd-standalone-ssl.yaml @@ -0,0 +1,19 @@ +apiVersion: kubedb.com/v1 +kind: Redis +metadata: + name: rd-tls + namespace: demo +spec: + version: "6.2.14" + tls: + issuerRef: + apiGroup: "cert-manager.io" + kind: Issuer + name: redis-ca-issuer + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi diff --git a/docs/examples/mssqlserver/tls/sentinel-ssl.yaml b/docs/examples/mssqlserver/tls/sentinel-ssl.yaml new file mode 100644 index 0000000000..24cc52e63a --- /dev/null +++ b/docs/examples/mssqlserver/tls/sentinel-ssl.yaml @@ -0,0 +1,20 @@ +apiVersion: kubedb.com/v1 +kind: RedisSentinel +metadata: + name: sen-tls + namespace: demo +spec: + replicas: 3 + version: "6.2.14" + tls: + issuerRef: + apiGroup: "cert-manager.io" + kind: ClusterIssuer + name: redis-ca-issuer + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi \ No newline at end of file diff --git a/docs/guides/mssqlserver/tls/_Index.md b/docs/guides/mssqlserver/tls/_Index.md new file mode 100644 index 0000000000..bf62d65dd1 --- /dev/null +++ b/docs/guides/mssqlserver/tls/_Index.md @@ -0,0 +1,10 @@ +--- +title: Run Microsoft SQL Server with TLS +menu: + docs_{{ .version }}: + identifier: ms-tls + name: TLS/SSL Encryption + parent: guides-mssqlserver + weight: 45 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/mssqlserver/tls/ag_cluster.md b/docs/guides/mssqlserver/tls/ag_cluster.md new file mode 100644 index 0000000000..005ad3bf59 --- /dev/null +++ b/docs/guides/mssqlserver/tls/ag_cluster.md @@ -0,0 +1,286 @@ +--- +title: MSSQLServer Sentinel TLS/SSL Encryption +menu: + docs_{{ .version }}: + identifier: ms-tls-sentinel + name: Sentinel + parent: ms-tls + weight: 20 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Run SQL Server with TLS/SSL Encryption + +KubeDB supports providing TLS/SSL encryption for MSSQLServer. This tutorial will show you how to use KubeDB to run a MSSQLServer database with TLS/SSL encryption. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Install [`cert-manger`](https://cert-manager.io/docs/installation/) v1.0.0 or later to your cluster to manage your SSL/TLS certificates. + +- Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). + +- To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + + ```bash + $ kubectl create ns demo + namespace/demo created + ``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/mssqlserver](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/mssqlserver) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Overview + +KubeDB uses following crd fields to enable SSL/TLS encryption in MSSQLServer and MSSQLServerSentinel. + +- `spec:` + - `tls:` + - `issuerRef` + - `certificate` + +There are two basic things to keep in mind when securing MSSQLServer using TLS in Sentinel Mode. + +- Either Sentinel instance and MSSQLServer database both should have TLS enabled or both have TLS disabled. + +- If TLS enabled, both Sentinel instance and MSSQLServer database should use the same `Issuer`. If they are in different namespace, in order to use same issuer, the certificates should be signed using `ClusterIssuer` + +Read about the fields in details in [mssqlserver concept](/docs/guides/mssqlserver/concepts/mssqlserver.md) and [mssqlserversentinel concept](/docs/guides/mssqlserver/concepts/mssqlserversentinel.md) + +## Create Issuer/ ClusterIssuer + +We are going to create an example `ClusterIssuer` that will be used throughout the duration of this tutorial to enable SSL/TLS in MSSQLServer. Alternatively, you can follow this [cert-manager tutorial](https://cert-manager.io/docs/configuration/ca/) to create your own `ClusterIssuer`. + +- Start off by generating you can certificate using openssl. + +```bash +openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ca.key -out ./ca.crt -subj "/CN=mssqlserver/O=kubedb" +``` + +- Now create a ca-secret using the certificate files you have just generated. The secret should be created in `cert-manager` namespace to create the `ClusterIssuer`. + +```bash +$ kubectl create secret tls mssqlserver-ca \ + --cert=ca.crt \ + --key=ca.key \ + --namespace=cert-manager +``` + +Now, create an `ClusterIssuer` using the `ca-secret` you have just created. The `YAML` file looks like this: + +```yaml +apiVersion: cert-manager.io/v1 +kind: ClusterIssuer +metadata: + name: mssqlserver-ca-issuer +spec: + ca: + secretName: mssqlserver-ca +``` + +Apply the `YAML` file: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mssqlserver/tls/clusterissuer.yaml +clusterissuer.cert-manager.io/mssqlserver-ca-issuer created +``` + +## TLS/SSL encryption in Sentinel + +Below is the YAML for MSSQLServer in Sentinel Mode. +```yaml +apiVersion: kubedb.com/v1 +kind: MSSQLServerSentinel +metadata: + name: sen-tls + namespace: demo +spec: + replicas: 3 + version: "6.2.14" + tls: + issuerRef: + apiGroup: "cert-manager.io" + kind: ClusterIssuer + name: mssqlserver-ca-issuer + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi +``` + +### Deploy MSSQLServer in Sentinel Mode + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mssqlserver/tls/sentinel-ssl.yaml +mssqlserversentinel.kubedb.com/sen-tls created +``` + +Now, wait until `sen-tls` has status `Ready`. i.e, + +```bash +$ watch kubectl get mssqlserversentinel -n demo +Every 2.0s: kubectl get mssqlserver -n demo +NAME VERSION STATUS AGE +sen-tls 6.2.14 Ready 111s +``` + +### Verify TLS/SSL in MSSQLServer in Sentinel Mode + +Now, connect to this database by exec into a pod and verify if `tls` has been set up as intended. + +```bash +$ kubectl describe secret -n demo sen-tls-client-cert +Name: sen-tls-client-cert +Namespace: demo +Labels: app.kubernetes.io/component=database + app.kubernetes.io/instance=sen-tls + app.kubernetes.io/managed-by=kubedb.com + app.kubernetes.io/name=mssqlserversentinels.kubedb.com +Annotations: cert-manager.io/alt-names: + cert-manager.io/certificate-name: sen-tls-client-cert + cert-manager.io/common-name: default + cert-manager.io/ip-sans: + cert-manager.io/issuer-group: cert-manager.io + cert-manager.io/issuer-kind: ClusterIssuer + cert-manager.io/issuer-name: mssqlserver-ca-issuer + cert-manager.io/uri-sans: + +Type: kubernetes.io/tls + +Data +==== +ca.crt: 1147 bytes +tls.crt: 1127 bytes +tls.key: 1675 bytes +``` + +## TLS/SSL encryption in MSSQLServer in Sentinel Mode + +Below is the YAML for MSSQLServer in Sentinel Mode. +```yaml +apiVersion: kubedb.com/v1 +kind: MSSQLServer +metadata: + name: ms-tls + namespace: demo +spec: + version: "6.2.14" + mode: Sentinel + replicas: 3 + sentinelRef: + name: sen-tls + namespace: demo + tls: + issuerRef: + apiGroup: "cert-manager.io" + kind: ClusterIssuer + name: mssqlserver-ca-issuer + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi +``` + +### Deploy MSSQLServer in Sentinel Mode + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mssqlserver/tls/ms-sentinel.yaml +mssqlserver.kubedb.com/ms-tls created +``` + +Now, wait until `ms-tls` has status `Ready`. i.e, + +```bash +$ watch kubectl get ms -n demo +Every 2.0s: kubectl get mssqlserver -n demo +NAME VERSION STATUS AGE +ms-tls 6.2.14 Ready 2m14s +``` + +### Verify TLS/SSL in MSSQLServer in Sentinel Mode + +Now, connect to this database by exec into a pod and verify if `tls` has been set up as intended. + +```bash +$ kubectl describe secret -n demo ms-tls-client-cert +Name: ms-tls-client-cert +Namespace: demo +Labels: app.kubernetes.io/component=database + app.kubernetes.io/instance=ms-tls + app.kubernetes.io/managed-by=kubedb.com + app.kubernetes.io/name=mssqlserveres.kubedb.com +Annotations: cert-manager.io/alt-names: + cert-manager.io/certificate-name: ms-tls-client-cert + cert-manager.io/common-name: default + cert-manager.io/ip-sans: + cert-manager.io/issuer-group: cert-manager.io + cert-manager.io/issuer-kind: ClusterIssuer + cert-manager.io/issuer-name: mssqlserver-ca-issuer + cert-manager.io/uri-sans: + +Type: kubernetes.io/tls + +Data +==== +tls.key: 1679 bytes +ca.crt: 1147 bytes +tls.crt: 1127 bytes +``` + + +Now, we can connect using tls-certs connect to the mssqlserver and write some data + +```bash +$ kubectl exec -it -n demo ms-tls-0 -c mssqlserver -- bash + +# Trying to connect without tls certificates +root@ms-tls-0:/data# mssqlserver-cli +127.0.0.1:6379> +127.0.0.1:6379> set hello world +# Can not write data +Error: Connection reset by peer + +# Trying to connect with tls certificates +root@ms-tls-0:/data# mssqlserver-cli --tls --cert "/certs/client.crt" --key "/certs/client.key" --cacert "/certs/ca.crt" +127.0.0.1:6379> +127.0.0.1:6379> set hello world +OK +127.0.0.1:6379> exit +``` + +## Cleaning up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +$ kubectl patch -n demo mssqlserver/ms-tls -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +mssqlserver.kubedb.com/ms-tls patched + +$ kubectl delete -n demo mssqlserver ms-tls +mssqlserver.kubedb.com "ms-tls" deleted + +$ kubectl patch -n demo mssqlserversentinel/sen-tls -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +mssqlserversentinel.kubedb.com/sen-tls patched + +$ kubectl delete -n demo mssqlserversentinel sen-tls +mssqlserversentinel.kubedb.com "sen-tls" deleted + +$ kubectl delete clusterissuer mssqlserver-ca-issuer +clusterissuer.cert-manager.io "mssqlserver-ca-issuer" deleted +``` + +## Next Steps + +- Detail concepts of [MSSQLServer object](/docs/guides/mssqlserver/concepts/mssqlserver.md). +- [Backup and Restore](/docs/guides/mssqlserver/backup/kubestash/overview/index.md) MSSQLServer databases using KubeStash. . +- Monitor your MSSQLServer database with KubeDB using [out-of-the-box Prometheus operator](/docs/guides/mssqlserver/monitoring/using-prometheus-operator.md). +- Monitor your MSSQLServer database with KubeDB using [out-of-the-box builtin-Prometheus](/docs/guides/mssqlserver/monitoring/using-builtin-prometheus.md). diff --git a/docs/guides/mssqlserver/tls/overview.md b/docs/guides/mssqlserver/tls/overview.md new file mode 100644 index 0000000000..f9d5d5a74e --- /dev/null +++ b/docs/guides/mssqlserver/tls/overview.md @@ -0,0 +1,73 @@ +--- +title: MSSQLServer TLS/SSL Encryption Overview +menu: + docs_{{ .version }}: + identifier: ms-tls-overview + name: Overview + parent: ms-tls + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# MSSQLServer TLS/SSL Encryption + +**Prerequisite :** To configure TLS/SSL in `MSSQLServer`, `KubeDB` uses `cert-manager` to issue certificates. So first you have to make sure that the cluster has `cert-manager` installed. Install `cert-manager` in your cluster following steps [here](https://cert-manager.io/docs/installation/). + +To issue a certificate, the following crd of `cert-manager` is used: + +- `Issuer/ClusterIssuer`: Issuers, and ClusterIssuers represent certificate authorities (CAs) that are able to generate signed certificates by honoring certificate signing requests. All cert-manager certificates require a referenced issuer that is in a ready condition to attempt to honor the request. You can learn more details [here](https://cert-manager.io/docs/concepts/issuer/). + +- `Certificate`: `cert-manager` has the concept of Certificates that define a desired x509 certificate which will be renewed and kept up to date. You can learn more details [here](https://cert-manager.io/docs/concepts/certificate/). + +**MSSQLServer CRD Specification :** + +KubeDB uses following crd fields to enable SSL/TLS encryption in `MSSQLServer`. + +- `spec:` + - `tls:` + - `issuerRef` + - `certificates` + - `clientTLS` + +Read about the fields in details from [MSSQLServer Concepts](/docs/guides/mssqlserver/concepts/mssqlserver.md), + +`KubeDB` uses the `Issuer` or `ClusterIssuer` referenced in the `tls.issuerRef` field, and the certificate specs provided in `tls.certificate` to generate certificate secrets using `Issuer/ClusterIssuers` specification. These certificates secrets including `ca.crt`, `server.crt` and `server.key` etc. are used to configure `MSSQLServer` server, exporter etc. respectively. + + +# TODO...................... + +## How TLS/SSL configures in MSSQLServer + +The following figure shows how `KubeDB` enterprise used to configure TLS/SSL in MSSQLServer. Open the image in a new tab to see the enlarged version. + +
+Deploy MSSQLServer with TLS/SSL +
Fig: Deploy MSSQLServer with TLS/SSL
+
+ +Deploying MSSQLServer with TLS/SSL configuration process consists of the following steps: + +1. At first, a user creates a `Issuer/ClusterIssuer` cr. + +2. Then the user creates a `MSSQLServer` cr which refers to the `Issuer/ClusterIssuer` cr that the user created in the previous step. + +3. `KubeDB` Provisioner operator watches for the `MSSQLServer` cr. + +4. When it finds one, it creates `Secret`, `Service`, etc. for the `MSSQLServer` database. + +5. `KubeDB` Ops-manager operator watches for `MSSQLServer`(5c), `Issuer/ClusterIssuer`(5b), `Secret` and `Service`(5a). + +6. When it finds all the resources(`MSSQLServer`, `Issuer/ClusterIssuer`, `Secret`, `Service`), it creates `Certificates` by using `tls.issuerRef` and `tls.certificates` field specification from `MSSQLServer` cr. + +7. `cert-manager` watches for certificates. + +8. When it finds one, it creates certificate secrets `tls-secrets`(server, client, exporter secrets etc.) that holds the actual certificate signed by the CA. + +9. `KubeDB` Provisioner operator watches for the Certificate secrets `tls-secrets`. + +10. When it finds all the tls-secret, it creates the related `PetSets` so that MSSQLServer database can be configured with TLS/SSL. + +In the next doc, we are going to show a step-by-step guide on how to configure a `MSSQLServer` database with TLS/SSL. \ No newline at end of file diff --git a/docs/guides/mssqlserver/tls/standalone.md b/docs/guides/mssqlserver/tls/standalone.md new file mode 100644 index 0000000000..4775855a88 --- /dev/null +++ b/docs/guides/mssqlserver/tls/standalone.md @@ -0,0 +1,198 @@ +--- +title: MSSQLServer Standalone TLS/SSL Encryption +menu: + docs_{{ .version }}: + identifier: ms-tls-standalone + name: Standalone + parent: ms-tls + weight: 20 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Run MSSQLServer with TLS/SSL (Transport Encryption) + +KubeDB supports providing TLS/SSL encryption for MSSQLServer. This tutorial will show you how to use KubeDB to run a MSSQLServer database with TLS/SSL encryption. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Install [`cert-manger`](https://cert-manager.io/docs/installation/) v1.0.0 or later to your cluster to manage your SSL/TLS certificates. + +- Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). + +- To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + + ```bash + $ kubectl create ns demo + namespace/demo created + ``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/mssqlserver](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/mssqlserver) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Overview + +KubeDB uses following crd fields to enable SSL/TLS encryption in MSSQLServer. + +- `spec:` + - `tls:` + - `issuerRef` + - `certificate` + +Read about the fields in details in [mssqlserver concept](/docs/guides/mssqlserver/concepts/mssqlserver.md), + +## Create Issuer/ ClusterIssuer + +We are going to create an example `Issuer` that will be used throughout the duration of this tutorial to enable SSL/TLS in MSSQLServer. Alternatively, you can follow this [cert-manager tutorial](https://cert-manager.io/docs/configuration/ca/) to create your own `Issuer`. + +- Start off by generating you ca certificates using openssl. + +```bash +openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ca.key -out ./ca.crt -subj "/CN=mssqlserver/O=kubedb" +``` + +- Now create a ca-secret using the certificate files you have just generated. + +```bash +kubectl create secret tls mssqlserver-ca \ + --cert=ca.crt \ + --key=ca.key \ + --namespace=demo +``` + +Now, create an `Issuer` using the `ca-secret` you have just created. The `YAML` file looks like this: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: mssqlserver-ca-issuer + namespace: demo +spec: + ca: + secretName: mssqlserver-ca +``` + +Apply the `YAML` file: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mssqlserver/tls/issuer.yaml +issuer.cert-manager.io/mssqlserver-ca-issuer created +``` + +## TLS/SSL encryption in MSSQLServer Standalone + +Below is the YAML for MSSQLServer Standalone. + +```yaml +apiVersion: kubedb.com/v1 +kind: MSSQLServer +metadata: + name: ms-tls + namespace: demo +spec: + version: "6.2.14" + tls: + issuerRef: + apiGroup: "cert-manager.io" + kind: Issuer + name: mssqlserver-ca-issuer + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi +``` + +### Deploy MSSQLServer Standalone + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mssqlserver/tls/ms-standalone-ssl.yaml +mssqlserver.kubedb.com/ms-tls created +``` + +Now, wait until `ms-tls` has status `Ready`. i.e, + +```bash +$ watch kubectl get ms -n demo +Every 2.0s: kubectl get mssqlserver -n demo +NAME VERSION STATUS AGE +ms-tls 6.2.14 Ready 14s +``` + +### Verify TLS/SSL in MSSQLServer Standalone + +Now, connect to this database by exec into a pod and verify if `tls` has been set up as intended. + +```bash +$ kubectl describe secret -n demo ms-tls-client-cert +Name: ms-tls-client-cert +Namespace: demo +Labels: app.kubernetes.io/component=database + app.kubernetes.io/instance=ms-tls + app.kubernetes.io/managed-by=kubedb.com + app.kubernetes.io/name=mssqlserveres.kubedb.com +Annotations: cert-manager.io/alt-names: + cert-manager.io/certificate-name: ms-tls-client-cert + cert-manager.io/common-name: default + cert-manager.io/ip-sans: + cert-manager.io/issuer-group: cert-manager.io + cert-manager.io/issuer-kind: Issuer + cert-manager.io/issuer-name: mssqlserver-ca-issuer + cert-manager.io/uri-sans: + +Type: kubernetes.io/tls + +Data +==== +ca.crt: 1147 bytes +tls.crt: 1127 bytes +tls.key: 1675 bytes +``` + +Now, we can connect using tls certs to connect to the mssqlserver and write some data + +```bash +$ kubectl exec -it -n demo ms-tls-0 -c mssqlserver -- bash + +# Trying to connect without tls certificates +root@ms-tls-0:/data# mssqlserver-cli +127.0.0.1:6379> +127.0.0.1:6379> set hello world +# Can not write data +Error: Connection reset by peer + +# Trying to connect with tls certificates +root@ms-tls-0:/data# mssqlserver-cli --tls --cert "/certs/client.crt" --key "/certs/client.key" --cacert "/certs/ca.crt" +127.0.0.1:6379> +127.0.0.1:6379> set hello world +OK +127.0.0.1:6379> exit +``` + +## Cleaning up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +$ kubectl patch -n demo mssqlserver/ms-tls -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +mssqlserver.kubedb.com/ms-tls patched + +$ kubectl delete -n demo mssqlserver ms-tls +mssqlserver.kubedb.com "ms-tls" deleted + +$ kubectl delete issuer -n demo mssqlserver-ca-issuer +issuer.cert-manager.io "mssqlserver-ca-issuer" deleted +``` + +## Next Steps + +- Detail concepts of [MSSQLServer object](/docs/guides/mssqlserver/concepts/mssqlserver.md). +- [Backup and Restore](/docs/guides/mssqlserver/backup/kubestash/overview/index.md) MSSQLServer databases using KubeStash. . +- Monitor your MSSQLServer database with KubeDB using [out-of-the-box Prometheus operator](/docs/guides/mssqlserver/monitoring/using-prometheus-operator.md). +- Monitor your MSSQLServer database with KubeDB using [out-of-the-box builtin-Prometheus](/docs/guides/mssqlserver/monitoring/using-builtin-prometheus.md). From 068c7c428dd79f1167194609bb4fe9914512ae81 Mon Sep 17 00:00:00 2001 From: Neaj Morshad Date: Thu, 17 Oct 2024 16:57:42 +0600 Subject: [PATCH 2/5] Fix overview Signed-off-by: Neaj Morshad --- .../mssqlserver/configuration/using-config-file.md | 2 +- docs/guides/mssqlserver/tls/ag_cluster.md | 4 +--- docs/guides/mssqlserver/tls/overview.md | 14 ++++++-------- docs/guides/mssqlserver/tls/standalone.md | 4 +--- docs/images/day-2-operation/mssqlserver/ms-tls.svg | 4 ++++ 5 files changed, 13 insertions(+), 15 deletions(-) create mode 100644 docs/images/day-2-operation/mssqlserver/ms-tls.svg diff --git a/docs/guides/mssqlserver/configuration/using-config-file.md b/docs/guides/mssqlserver/configuration/using-config-file.md index 4cd2580716..42e5b58327 100644 --- a/docs/guides/mssqlserver/configuration/using-config-file.md +++ b/docs/guides/mssqlserver/configuration/using-config-file.md @@ -41,7 +41,7 @@ SQL Server allows configuring database via configuration file. The default confi At first, you have to create a config file named `mssql.conf` with your desired configuration. Then you have to create a [secret](https://kubernetes.io/docs/concepts/configuration/secret/) using this file. Then specify this secret name in `spec.configSecret.name` section while creating MSSQLServer CR. -KubeDB will create a secret named `{mssqlserver-name}-config` with configuration file contents as the value of the key `mssql.conf` and mount this secret into `/var/opt/mssql/` directory of the database pod. the secret named `{mssqlserver-name}-config` will contain your desired configurations with some default configurations. +KubeDB will create a secret named `{mssqlserver-name}-config` with configuration file contents as the value of the key `mssql.conf` and mount this secret into `/var/opt/mssql/` directory of the database pod. The secret named `{mssqlserver-name}-config` will contain your desired configurations with some default configurations. In this tutorial, we will configure sql server via a custom config file. diff --git a/docs/guides/mssqlserver/tls/ag_cluster.md b/docs/guides/mssqlserver/tls/ag_cluster.md index 005ad3bf59..01acb288cf 100644 --- a/docs/guides/mssqlserver/tls/ag_cluster.md +++ b/docs/guides/mssqlserver/tls/ag_cluster.md @@ -281,6 +281,4 @@ clusterissuer.cert-manager.io "mssqlserver-ca-issuer" deleted ## Next Steps - Detail concepts of [MSSQLServer object](/docs/guides/mssqlserver/concepts/mssqlserver.md). -- [Backup and Restore](/docs/guides/mssqlserver/backup/kubestash/overview/index.md) MSSQLServer databases using KubeStash. . -- Monitor your MSSQLServer database with KubeDB using [out-of-the-box Prometheus operator](/docs/guides/mssqlserver/monitoring/using-prometheus-operator.md). -- Monitor your MSSQLServer database with KubeDB using [out-of-the-box builtin-Prometheus](/docs/guides/mssqlserver/monitoring/using-builtin-prometheus.md). +- [Backup and Restore](/docs/guides/mssqlserver/backup/overview/index.md) MSSQLServer databases using KubeStash. . diff --git a/docs/guides/mssqlserver/tls/overview.md b/docs/guides/mssqlserver/tls/overview.md index f9d5d5a74e..d0e020060e 100644 --- a/docs/guides/mssqlserver/tls/overview.md +++ b/docs/guides/mssqlserver/tls/overview.md @@ -37,11 +37,9 @@ Read about the fields in details from [MSSQLServer Concepts](/docs/guides/mssqls `KubeDB` uses the `Issuer` or `ClusterIssuer` referenced in the `tls.issuerRef` field, and the certificate specs provided in `tls.certificate` to generate certificate secrets using `Issuer/ClusterIssuers` specification. These certificates secrets including `ca.crt`, `server.crt` and `server.key` etc. are used to configure `MSSQLServer` server, exporter etc. respectively. -# TODO...................... - ## How TLS/SSL configures in MSSQLServer -The following figure shows how `KubeDB` enterprise used to configure TLS/SSL in MSSQLServer. Open the image in a new tab to see the enlarged version. +The following figure shows how `KubeDB` used to configure TLS/SSL in MSSQLServer. Open the image in a new tab to see the enlarged version.
Deploy MSSQLServer with TLS/SSL @@ -50,17 +48,17 @@ The following figure shows how `KubeDB` enterprise used to configure TLS/SSL in Deploying MSSQLServer with TLS/SSL configuration process consists of the following steps: -1. At first, a user creates a `Issuer/ClusterIssuer` cr. +1. At first, a user creates a `Issuer/ClusterIssuer` CR. -2. Then the user creates a `MSSQLServer` cr which refers to the `Issuer/ClusterIssuer` cr that the user created in the previous step. +2. Then the user creates a `MSSQLServer` CR which refers to the `Issuer/ClusterIssuer` CR that the user created in the previous step. -3. `KubeDB` Provisioner operator watches for the `MSSQLServer` cr. +3. `KubeDB` Provisioner operator watches for the `MSSQLServer` CR. -4. When it finds one, it creates `Secret`, `Service`, etc. for the `MSSQLServer` database. +4. When it finds one, it creates `Secret`, `Service`, etc. for the `MSSQLServer`. 5. `KubeDB` Ops-manager operator watches for `MSSQLServer`(5c), `Issuer/ClusterIssuer`(5b), `Secret` and `Service`(5a). -6. When it finds all the resources(`MSSQLServer`, `Issuer/ClusterIssuer`, `Secret`, `Service`), it creates `Certificates` by using `tls.issuerRef` and `tls.certificates` field specification from `MSSQLServer` cr. +6. When it finds all the resources(`MSSQLServer`, `Issuer/ClusterIssuer`, `Secret`, `Service`), it creates `Certificates` by using `tls.issuerRef` and `tls.certificates` field specification from `MSSQLServer` CR. 7. `cert-manager` watches for certificates. diff --git a/docs/guides/mssqlserver/tls/standalone.md b/docs/guides/mssqlserver/tls/standalone.md index 4775855a88..4fa6658eee 100644 --- a/docs/guides/mssqlserver/tls/standalone.md +++ b/docs/guides/mssqlserver/tls/standalone.md @@ -193,6 +193,4 @@ issuer.cert-manager.io "mssqlserver-ca-issuer" deleted ## Next Steps - Detail concepts of [MSSQLServer object](/docs/guides/mssqlserver/concepts/mssqlserver.md). -- [Backup and Restore](/docs/guides/mssqlserver/backup/kubestash/overview/index.md) MSSQLServer databases using KubeStash. . -- Monitor your MSSQLServer database with KubeDB using [out-of-the-box Prometheus operator](/docs/guides/mssqlserver/monitoring/using-prometheus-operator.md). -- Monitor your MSSQLServer database with KubeDB using [out-of-the-box builtin-Prometheus](/docs/guides/mssqlserver/monitoring/using-builtin-prometheus.md). +- [Backup and Restore](/docs/guides/mssqlserver/backup/overview/index.md) MSSQLServer databases using KubeStash. . \ No newline at end of file diff --git a/docs/images/day-2-operation/mssqlserver/ms-tls.svg b/docs/images/day-2-operation/mssqlserver/ms-tls.svg new file mode 100644 index 0000000000..819643f928 --- /dev/null +++ b/docs/images/day-2-operation/mssqlserver/ms-tls.svg @@ -0,0 +1,4 @@ + + + +            Enterprise            Operator              Community            Operator
service
se...
secret
se...
tls-secret
tls-secret
Cert- manager
Cert- ma...
StatefulSet
Statef...
Issuer/Cluster Issuer
Issuer...
Kafka
Kafka
Certificates
Certif...
User
User
2.Create
2.Create
1.Create
1.Create
5a.Watch
5a.Watch
3.Watch
3.Watch
4.Create
4.Create
5c.Watch
5c.Watch
6.Create
6.Create
7.Watch
7.Watch
uses
uses
8.Create
8.Create
9.Watch
9.Watch
10.Create
10.Create
5b.Watch
5b.Watch
refers to
refers toText is not SVG - cannot display \ No newline at end of file From aea54a9fba3176caf8cc299c93a0dcbf164efb11 Mon Sep 17 00:00:00 2001 From: Neaj Morshad Date: Mon, 21 Oct 2024 12:23:31 +0600 Subject: [PATCH 3/5] finish ag tls Signed-off-by: Neaj Morshad --- docs/examples/mssqlserver/tls/issuer.yaml | 4 +- .../mssqlserver/tls/mssql-ag-tls.yaml | 35 +++ ...ter-ssl.yaml => mssql-standalone-tls.yaml} | 20 +- .../examples/mssqlserver/tls/rd-sentinel.yaml | 24 -- .../mssqlserver/tls/rd-standalone-ssl.yaml | 19 -- .../mssqlserver/tls/sentinel-ssl.yaml | 20 -- docs/guides/mssqlserver/tls/ag_cluster.md | 274 ++++++++---------- docs/guides/mssqlserver/tls/standalone.md | 143 ++++++--- 8 files changed, 270 insertions(+), 269 deletions(-) create mode 100644 docs/examples/mssqlserver/tls/mssql-ag-tls.yaml rename docs/examples/mssqlserver/tls/{rd-cluster-ssl.yaml => mssql-standalone-tls.yaml} (52%) delete mode 100644 docs/examples/mssqlserver/tls/rd-sentinel.yaml delete mode 100644 docs/examples/mssqlserver/tls/rd-standalone-ssl.yaml delete mode 100644 docs/examples/mssqlserver/tls/sentinel-ssl.yaml diff --git a/docs/examples/mssqlserver/tls/issuer.yaml b/docs/examples/mssqlserver/tls/issuer.yaml index c812454645..7a00e196d9 100644 --- a/docs/examples/mssqlserver/tls/issuer.yaml +++ b/docs/examples/mssqlserver/tls/issuer.yaml @@ -1,8 +1,8 @@ apiVersion: cert-manager.io/v1 kind: Issuer metadata: - name: redis-ca-issuer + name: mssqlserver-ca-issuer namespace: demo spec: ca: - secretName: redis-ca + secretName: mssqlserver-ca \ No newline at end of file diff --git a/docs/examples/mssqlserver/tls/mssql-ag-tls.yaml b/docs/examples/mssqlserver/tls/mssql-ag-tls.yaml new file mode 100644 index 0000000000..013eb80a30 --- /dev/null +++ b/docs/examples/mssqlserver/tls/mssql-ag-tls.yaml @@ -0,0 +1,35 @@ +apiVersion: kubedb.com/v1alpha2 +kind: MSSQLServer +metadata: + name: mssql-ag-tls + namespace: demo +spec: + version: "2022-cu12" + replicas: 3 + topology: + mode: AvailabilityGroup + availabilityGroup: + databases: + - agdb1 + - agdb2 + internalAuth: + endpointCert: + issuerRef: + apiGroup: cert-manager.io + name: mssqlserver-ca-issuer + kind: Issuer + tls: + issuerRef: + name: mssqlserver-ca-issuer + kind: Issuer + apiGroup: "cert-manager.io" + clientTLS: true + storageType: Durable + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut \ No newline at end of file diff --git a/docs/examples/mssqlserver/tls/rd-cluster-ssl.yaml b/docs/examples/mssqlserver/tls/mssql-standalone-tls.yaml similarity index 52% rename from docs/examples/mssqlserver/tls/rd-cluster-ssl.yaml rename to docs/examples/mssqlserver/tls/mssql-standalone-tls.yaml index 5da87a0846..50bf7f7b2a 100644 --- a/docs/examples/mssqlserver/tls/rd-cluster-ssl.yaml +++ b/docs/examples/mssqlserver/tls/mssql-standalone-tls.yaml @@ -1,19 +1,18 @@ -apiVersion: kubedb.com/v1 -kind: Redis +apiVersion: kubedb.com/v1alpha2 +kind: MSSQLServer metadata: - name: rd-tls + name: mssql-standalone-tls namespace: demo spec: - version: "6.2.14" - mode: Cluster - cluster: - shards: 3 - replicas: 1 + version: "2022-cu12" + replicas: 1 + storageType: Durable tls: issuerRef: - apiGroup: "cert-manager.io" + name: mssqlserver-ca-issuer kind: Issuer - name: redis-ca-issuer + apiGroup: "cert-manager.io" + clientTLS: true storage: storageClassName: "standard" accessModes: @@ -21,3 +20,4 @@ spec: resources: requests: storage: 1Gi + deletionPolicy: WipeOut \ No newline at end of file diff --git a/docs/examples/mssqlserver/tls/rd-sentinel.yaml b/docs/examples/mssqlserver/tls/rd-sentinel.yaml deleted file mode 100644 index 360e5ed13a..0000000000 --- a/docs/examples/mssqlserver/tls/rd-sentinel.yaml +++ /dev/null @@ -1,24 +0,0 @@ -apiVersion: kubedb.com/v1 -kind: Redis -metadata: - name: rd-tls - namespace: demo -spec: - version: "6.2.14" - mode: Sentinel - replicas: 3 - sentinelRef: - name: sen-tls - namespace: demo - tls: - issuerRef: - apiGroup: "cert-manager.io" - kind: ClusterIssuer - name: redis-ca-issuer - storage: - storageClassName: "standard" - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 1Gi diff --git a/docs/examples/mssqlserver/tls/rd-standalone-ssl.yaml b/docs/examples/mssqlserver/tls/rd-standalone-ssl.yaml deleted file mode 100644 index 28398aa2f7..0000000000 --- a/docs/examples/mssqlserver/tls/rd-standalone-ssl.yaml +++ /dev/null @@ -1,19 +0,0 @@ -apiVersion: kubedb.com/v1 -kind: Redis -metadata: - name: rd-tls - namespace: demo -spec: - version: "6.2.14" - tls: - issuerRef: - apiGroup: "cert-manager.io" - kind: Issuer - name: redis-ca-issuer - storage: - storageClassName: "standard" - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 1Gi diff --git a/docs/examples/mssqlserver/tls/sentinel-ssl.yaml b/docs/examples/mssqlserver/tls/sentinel-ssl.yaml deleted file mode 100644 index 24cc52e63a..0000000000 --- a/docs/examples/mssqlserver/tls/sentinel-ssl.yaml +++ /dev/null @@ -1,20 +0,0 @@ -apiVersion: kubedb.com/v1 -kind: RedisSentinel -metadata: - name: sen-tls - namespace: demo -spec: - replicas: 3 - version: "6.2.14" - tls: - issuerRef: - apiGroup: "cert-manager.io" - kind: ClusterIssuer - name: redis-ca-issuer - storage: - storageClassName: "standard" - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 1Gi \ No newline at end of file diff --git a/docs/guides/mssqlserver/tls/ag_cluster.md b/docs/guides/mssqlserver/tls/ag_cluster.md index 01acb288cf..9a689d92ff 100644 --- a/docs/guides/mssqlserver/tls/ag_cluster.md +++ b/docs/guides/mssqlserver/tls/ag_cluster.md @@ -1,20 +1,20 @@ --- -title: MSSQLServer Sentinel TLS/SSL Encryption +title: SQL Server Availability Group TLS/SSL Encryption menu: docs_{{ .version }}: - identifier: ms-tls-sentinel - name: Sentinel - parent: ms-tls - weight: 20 + identifier: mssql-ag-tls-availability-group + name: Availability Group (HA Cluster) + parent: mssql-ag-tls + weight: 30 menu_name: docs_{{ .version }} section_menu_id: guides --- > New to KubeDB? Please start [here](/docs/README.md). -# Run SQL Server with TLS/SSL Encryption +# Run SQL Server Availability Group with TLS/SSL Encryption -KubeDB supports providing TLS/SSL encryption for MSSQLServer. This tutorial will show you how to use KubeDB to run a MSSQLServer database with TLS/SSL encryption. +KubeDB supports providing TLS/SSL encryption for MSSQLServer. This tutorial will show you how to use KubeDB to run a MSSQLServer with TLS/SSL encryption. ## Before You Begin @@ -24,6 +24,8 @@ KubeDB supports providing TLS/SSL encryption for MSSQLServer. This tutorial will - Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). +- Install [csi-driver-cacerts](https://github.com/kubeops/csi-driver-cacerts) which will be used to add self-signed ca certificates to the OS trusted certificate store (eg, /etc/ssl/certs/ca-certificates.crt) + - To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. ```bash @@ -31,51 +33,61 @@ KubeDB supports providing TLS/SSL encryption for MSSQLServer. This tutorial will namespace/demo created ``` -> Note: YAML files used in this tutorial are stored in [docs/examples/mssqlserver](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/mssqlserver) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). +> Note: YAML files used in this tutorial are stored in [docs/examples/mssqlserver/tls](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/mssqlserver/tls) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). ## Overview -KubeDB uses following crd fields to enable SSL/TLS encryption in MSSQLServer and MSSQLServerSentinel. +KubeDB uses following crd fields to enable SSL/TLS encryption in MSSQLServer. - `spec:` - `tls:` - `issuerRef` - - `certificate` + - `certificates` + - `clientTLS` + + +- `issuerRef` is a reference to the `Issuer` or `ClusterIssuer` CR of [cert-manager](https://cert-manager.io/docs/concepts/issuer/) that will be used by `KubeDB` to generate necessary certificates. + + - `apiGroup` is the group name of the resource that is being referenced. Currently, the only supported value is `cert-manager.io`. + - `kind` is the type of resource that is being referenced. KubeDB supports both `Issuer` and `ClusterIssuer` as values for this field. + - `name` is the name of the resource (`Issuer` or `ClusterIssuer`) being referenced. -There are two basic things to keep in mind when securing MSSQLServer using TLS in Sentinel Mode. +- `clientTLS` This setting determines whether TLS (Transport Layer Security) is enabled for the MS SQL Server. + - If set to `true`, the sql server will be provisioned with `TLS`, and you will need to install the [csi-driver-cacerts](https://github.com/kubeops/csi-driver-cacerts) which will be used to add self-signed ca certificates to the OS trusted certificate store (/etc/ssl/certs/ca-certificates.crt). + - If set to `false`, TLS will not be enabled for SQL Server. However, the Issuer will still be used to configure a TLS-enabled WAL-G proxy server, which is necessary for performing SQL Server backup operations. -- Either Sentinel instance and MSSQLServer database both should have TLS enabled or both have TLS disabled. +- `certificates` (optional) are a list of certificates used to configure the server and/or client certificate. -- If TLS enabled, both Sentinel instance and MSSQLServer database should use the same `Issuer`. If they are in different namespace, in order to use same issuer, the certificates should be signed using `ClusterIssuer` +Read about the fields in details in [mssqlserver concept](/docs/guides/mssqlserver/concepts/mssqlserver.md). -Read about the fields in details in [mssqlserver concept](/docs/guides/mssqlserver/concepts/mssqlserver.md) and [mssqlserversentinel concept](/docs/guides/mssqlserver/concepts/mssqlserversentinel.md) ## Create Issuer/ ClusterIssuer -We are going to create an example `ClusterIssuer` that will be used throughout the duration of this tutorial to enable SSL/TLS in MSSQLServer. Alternatively, you can follow this [cert-manager tutorial](https://cert-manager.io/docs/configuration/ca/) to create your own `ClusterIssuer`. +We are going to create an example `Issuer` that will be used throughout the duration of this tutorial to enable SSL/TLS in MSSQLServer. Alternatively, you can follow this [cert-manager tutorial](https://cert-manager.io/docs/configuration/ca/) to create your own `Issuer`. -- Start off by generating you can certificate using openssl. +- Start off by generating you CA certificates using openssl. ```bash openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ca.key -out ./ca.crt -subj "/CN=mssqlserver/O=kubedb" ``` -- Now create a ca-secret using the certificate files you have just generated. The secret should be created in `cert-manager` namespace to create the `ClusterIssuer`. +- Now create a ca-secret using the certificate files you have just generated. ```bash -$ kubectl create secret tls mssqlserver-ca \ +kubectl create secret tls mssqlserver-ca \ --cert=ca.crt \ --key=ca.key \ - --namespace=cert-manager + --namespace=demo ``` -Now, create an `ClusterIssuer` using the `ca-secret` you have just created. The `YAML` file looks like this: +Now, create an `Issuer` using the `ca-secret` you have just created. The `YAML` file looks like this: ```yaml apiVersion: cert-manager.io/v1 -kind: ClusterIssuer +kind: Issuer metadata: name: mssqlserver-ca-issuer + namespace: demo spec: ca: secretName: mssqlserver-ca @@ -84,27 +96,41 @@ spec: Apply the `YAML` file: ```bash -$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mssqlserver/tls/clusterissuer.yaml -clusterissuer.cert-manager.io/mssqlserver-ca-issuer created +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mssqlserver/tls/issuer.yaml +issuer.cert-manager.io/mssqlserver-ca-issuer created ``` -## TLS/SSL encryption in Sentinel +## TLS/SSL encryption in SQL Server Availability Group -Below is the YAML for MSSQLServer in Sentinel Mode. +Below is the YAML for MSSQLServer in Availability Group Mode. ```yaml -apiVersion: kubedb.com/v1 -kind: MSSQLServerSentinel +apiVersion: kubedb.com/v1alpha2 +kind: MSSQLServer metadata: - name: sen-tls + name: mssql-ag-tls namespace: demo spec: + version: "2022-cu12" replicas: 3 - version: "6.2.14" + topology: + mode: AvailabilityGroup + availabilityGroup: + databases: + - agdb1 + - agdb2 + internalAuth: + endpointCert: + issuerRef: + apiGroup: cert-manager.io + name: mssqlserver-ca-issuer + kind: Issuer tls: issuerRef: - apiGroup: "cert-manager.io" - kind: ClusterIssuer name: mssqlserver-ca-issuer + kind: Issuer + apiGroup: "cert-manager.io" + clientTLS: true + storageType: Durable storage: storageClassName: "standard" accessModes: @@ -112,149 +138,109 @@ spec: resources: requests: storage: 1Gi + deletionPolicy: WipeOut ``` -### Deploy MSSQLServer in Sentinel Mode +### Deploy MSSQLServer in Availability Group Mode ```bash -$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mssqlserver/tls/sentinel-ssl.yaml -mssqlserversentinel.kubedb.com/sen-tls created +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mssqlserver/tls/mssql-ag-tls.yaml +ms.kubedb.com/mssql-ag-tls created ``` -Now, wait until `sen-tls` has status `Ready`. i.e, +Now, wait until `mssql-ag-tls` has status `Ready`. i.e, ```bash -$ watch kubectl get mssqlserversentinel -n demo -Every 2.0s: kubectl get mssqlserver -n demo -NAME VERSION STATUS AGE -sen-tls 6.2.14 Ready 111s +$ watch kubectl get ms -n demo +Every 2.0s: kubectl get ms -n demo +NAME VERSION STATUS AGE +mssql-ag-tls 2022-cu12 Ready 4m26s ``` -### Verify TLS/SSL in MSSQLServer in Sentinel Mode + +### Verify TLS/SSL in MSSQLServer in Availability Group Mode Now, connect to this database by exec into a pod and verify if `tls` has been set up as intended. ```bash -$ kubectl describe secret -n demo sen-tls-client-cert -Name: sen-tls-client-cert +$ kubectl describe secret -n demo mssql-ag-tls-client-cert +Name: mssql-ag-tls-client-cert Namespace: demo Labels: app.kubernetes.io/component=database - app.kubernetes.io/instance=sen-tls + app.kubernetes.io/instance=mssql-ag-tls app.kubernetes.io/managed-by=kubedb.com - app.kubernetes.io/name=mssqlserversentinels.kubedb.com + app.kubernetes.io/name=mssqlservers.kubedb.com + controller.cert-manager.io/fao=true Annotations: cert-manager.io/alt-names: - cert-manager.io/certificate-name: sen-tls-client-cert - cert-manager.io/common-name: default + cert-manager.io/certificate-name: mssql-ag-tls-client-cert + cert-manager.io/common-name: mssql cert-manager.io/ip-sans: cert-manager.io/issuer-group: cert-manager.io - cert-manager.io/issuer-kind: ClusterIssuer + cert-manager.io/issuer-kind: Issuer cert-manager.io/issuer-name: mssqlserver-ca-issuer + cert-manager.io/subject-organizationalunits: client + cert-manager.io/subject-organizations: kubedb cert-manager.io/uri-sans: Type: kubernetes.io/tls Data ==== -ca.crt: 1147 bytes -tls.crt: 1127 bytes +tls.crt: 1180 bytes tls.key: 1675 bytes +ca.crt: 1164 bytes ``` -## TLS/SSL encryption in MSSQLServer in Sentinel Mode -Below is the YAML for MSSQLServer in Sentinel Mode. -```yaml -apiVersion: kubedb.com/v1 -kind: MSSQLServer -metadata: - name: ms-tls - namespace: demo -spec: - version: "6.2.14" - mode: Sentinel - replicas: 3 - sentinelRef: - name: sen-tls - namespace: demo - tls: - issuerRef: - apiGroup: "cert-manager.io" - kind: ClusterIssuer - name: mssqlserver-ca-issuer - storage: - storageClassName: "standard" - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 1Gi -``` - -### Deploy MSSQLServer in Sentinel Mode +Now, we can connect with tls to the mssqlserver and write some data ```bash -$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mssqlserver/tls/ms-sentinel.yaml -mssqlserver.kubedb.com/ms-tls created -``` +$ kubectl get secret -n demo mssql-ag-tls-auth -o jsonpath='{.data.\username}' | base64 -d +sa -Now, wait until `ms-tls` has status `Ready`. i.e, - -```bash -$ watch kubectl get ms -n demo -Every 2.0s: kubectl get mssqlserver -n demo -NAME VERSION STATUS AGE -ms-tls 6.2.14 Ready 2m14s +$ kubectl get secret -n demo mssql-ag-tls-auth -o jsonpath='{.data.\password}' | base64 -d +Ng1DaJSNjZkgXXFX ``` -### Verify TLS/SSL in MSSQLServer in Sentinel Mode - -Now, connect to this database by exec into a pod and verify if `tls` has been set up as intended. - ```bash -$ kubectl describe secret -n demo ms-tls-client-cert -Name: ms-tls-client-cert -Namespace: demo -Labels: app.kubernetes.io/component=database - app.kubernetes.io/instance=ms-tls - app.kubernetes.io/managed-by=kubedb.com - app.kubernetes.io/name=mssqlserveres.kubedb.com -Annotations: cert-manager.io/alt-names: - cert-manager.io/certificate-name: ms-tls-client-cert - cert-manager.io/common-name: default - cert-manager.io/ip-sans: - cert-manager.io/issuer-group: cert-manager.io - cert-manager.io/issuer-kind: ClusterIssuer - cert-manager.io/issuer-name: mssqlserver-ca-issuer - cert-manager.io/uri-sans: - -Type: kubernetes.io/tls +$ kubectl exec -it -n demo mssql-ag-tls-0 -c mssql -- bash +1> select name from sys.databases +2> go +name +---------------------------------------------------------------------------------- +master +tempdb +model +msdb +agdb1 +agdb2 +kubedb_system + +(5 rows affected) +1> SELECT name FROM sys.availability_groups +2> go +name +---------------------------------------------------------------------------- +mssqlagtls + +(1 rows affected) +1> select replica_server_name from sys.availability_replicas; +2> go +replica_server_name +------------------------------------------------------------------------------------------- +mssql-ag-tls-0 +mssql-ag-tls-1 +mssql-ag-tls-2 +(3 rows affected) +1> select database_name from sys.availability_databases_cluster; +2> go +database_name +------------------------------------------------------------------------------------------ +agdb1 +agdb2 + +(2 rows affected) -Data -==== -tls.key: 1679 bytes -ca.crt: 1147 bytes -tls.crt: 1127 bytes -``` - - -Now, we can connect using tls-certs connect to the mssqlserver and write some data - -```bash -$ kubectl exec -it -n demo ms-tls-0 -c mssqlserver -- bash - -# Trying to connect without tls certificates -root@ms-tls-0:/data# mssqlserver-cli -127.0.0.1:6379> -127.0.0.1:6379> set hello world -# Can not write data -Error: Connection reset by peer - -# Trying to connect with tls certificates -root@ms-tls-0:/data# mssqlserver-cli --tls --cert "/certs/client.crt" --key "/certs/client.key" --cacert "/certs/ca.crt" -127.0.0.1:6379> -127.0.0.1:6379> set hello world -OK -127.0.0.1:6379> exit ``` ## Cleaning up @@ -262,19 +248,13 @@ OK To clean up the Kubernetes resources created by this tutorial, run: ```bash -$ kubectl patch -n demo mssqlserver/ms-tls -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" -mssqlserver.kubedb.com/ms-tls patched - -$ kubectl delete -n demo mssqlserver ms-tls -mssqlserver.kubedb.com "ms-tls" deleted - -$ kubectl patch -n demo mssqlserversentinel/sen-tls -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" -mssqlserversentinel.kubedb.com/sen-tls patched +$ kubectl patch -n demo mssqlserver/mssql-ag-tls -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +mssqlserver.kubedb.com/mssql-ag-tls patched -$ kubectl delete -n demo mssqlserversentinel sen-tls -mssqlserversentinel.kubedb.com "sen-tls" deleted +$ kubectl delete -n demo mssqlserver mssql-ag-tls +mssqlserver.kubedb.com "mssql-ag-tls" deleted -$ kubectl delete clusterissuer mssqlserver-ca-issuer +$ kubectl delete issuer mssqlserver-ca-issuer clusterissuer.cert-manager.io "mssqlserver-ca-issuer" deleted ``` diff --git a/docs/guides/mssqlserver/tls/standalone.md b/docs/guides/mssqlserver/tls/standalone.md index 4fa6658eee..234364d9ec 100644 --- a/docs/guides/mssqlserver/tls/standalone.md +++ b/docs/guides/mssqlserver/tls/standalone.md @@ -12,9 +12,9 @@ section_menu_id: guides > New to KubeDB? Please start [here](/docs/README.md). -# Run MSSQLServer with TLS/SSL (Transport Encryption) +# Run SQL Server Standalone with TLS/SSL (Transport Encryption) -KubeDB supports providing TLS/SSL encryption for MSSQLServer. This tutorial will show you how to use KubeDB to run a MSSQLServer database with TLS/SSL encryption. +KubeDB supports providing TLS/SSL encryption for MSSQLServer. This tutorial will show you how to use KubeDB to run a MSSQLServer with TLS/SSL encryption. ## Before You Begin @@ -24,6 +24,8 @@ KubeDB supports providing TLS/SSL encryption for MSSQLServer. This tutorial will - Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). +- Install [csi-driver-cacerts](https://github.com/kubeops/csi-driver-cacerts) which will be used to add self-signed ca certificates to the OS trusted certificate store (eg, /etc/ssl/certs/ca-certificates.crt) + - To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. ```bash @@ -31,7 +33,7 @@ KubeDB supports providing TLS/SSL encryption for MSSQLServer. This tutorial will namespace/demo created ``` -> Note: YAML files used in this tutorial are stored in [docs/examples/mssqlserver](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/mssqlserver) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). +> Note: YAML files used in this tutorial are stored in [docs/examples/mssqlserver/tls](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/mssqlserver/tls) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). ## Overview @@ -40,15 +42,30 @@ KubeDB uses following crd fields to enable SSL/TLS encryption in MSSQLServer. - `spec:` - `tls:` - `issuerRef` - - `certificate` + - `certificates` + - `clientTLS` + + +- `issuerRef` is a reference to the `Issuer` or `ClusterIssuer` CR of [cert-manager](https://cert-manager.io/docs/concepts/issuer/) that will be used by `KubeDB` to generate necessary certificates. + + - `apiGroup` is the group name of the resource that is being referenced. Currently, the only supported value is `cert-manager.io`. + - `kind` is the type of resource that is being referenced. KubeDB supports both `Issuer` and `ClusterIssuer` as values for this field. + - `name` is the name of the resource (`Issuer` or `ClusterIssuer`) being referenced. + +- `clientTLS` This setting determines whether TLS (Transport Layer Security) is enabled for the MS SQL Server. + - If set to `true`, the sql server will be provisioned with `TLS`, and you will need to install the [csi-driver-cacerts](https://github.com/kubeops/csi-driver-cacerts) which will be used to add self-signed ca certificates to the OS trusted certificate store (/etc/ssl/certs/ca-certificates.crt). + - If set to `false`, TLS will not be enabled for SQL Server. However, the Issuer will still be used to configure a TLS-enabled WAL-G proxy server, which is necessary for performing SQL Server backup operations. + +- `certificates` (optional) are a list of certificates used to configure the server and/or client certificate. + +Read about the fields in details in [mssqlserver concept](/docs/guides/mssqlserver/concepts/mssqlserver.md). -Read about the fields in details in [mssqlserver concept](/docs/guides/mssqlserver/concepts/mssqlserver.md), ## Create Issuer/ ClusterIssuer We are going to create an example `Issuer` that will be used throughout the duration of this tutorial to enable SSL/TLS in MSSQLServer. Alternatively, you can follow this [cert-manager tutorial](https://cert-manager.io/docs/configuration/ca/) to create your own `Issuer`. -- Start off by generating you ca certificates using openssl. +- Start off by generating you CA certificates using openssl. ```bash openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ca.key -out ./ca.crt -subj "/CN=mssqlserver/O=kubedb" @@ -88,18 +105,21 @@ issuer.cert-manager.io/mssqlserver-ca-issuer created Below is the YAML for MSSQLServer Standalone. ```yaml -apiVersion: kubedb.com/v1 +apiVersion: kubedb.com/v1alpha2 kind: MSSQLServer metadata: - name: ms-tls + name: mssql-standalone-tls namespace: demo spec: - version: "6.2.14" + version: "2022-cu12" + replicas: 1 + storageType: Durable tls: issuerRef: - apiGroup: "cert-manager.io" - kind: Issuer name: mssqlserver-ca-issuer + kind: Issuer + apiGroup: "cert-manager.io" + clientTLS: true storage: storageClassName: "standard" accessModes: @@ -107,22 +127,24 @@ spec: resources: requests: storage: 1Gi + deletionPolicy: WipeOut ``` ### Deploy MSSQLServer Standalone ```bash -$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mssqlserver/tls/ms-standalone-ssl.yaml -mssqlserver.kubedb.com/ms-tls created +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mssqlserver/tls/mssql-standalone-tls.yaml +mssqlserver.kubedb.com/mssql-standalone-tls created ``` -Now, wait until `ms-tls` has status `Ready`. i.e, +Now, wait until `mssql-standalone-tls` has status `Ready`. i.e, ```bash $ watch kubectl get ms -n demo -Every 2.0s: kubectl get mssqlserver -n demo -NAME VERSION STATUS AGE -ms-tls 6.2.14 Ready 14s +Every 2.0s: kubectl get ms -n demo + +NAME VERSION STATUS AGE +mssql-standalone-tls 2022-cu12 Ready 3m30s ``` ### Verify TLS/SSL in MSSQLServer Standalone @@ -130,49 +152,76 @@ ms-tls 6.2.14 Ready 14s Now, connect to this database by exec into a pod and verify if `tls` has been set up as intended. ```bash -$ kubectl describe secret -n demo ms-tls-client-cert -Name: ms-tls-client-cert +$ kubectl describe secret -n demo mssql-standalone-tls-client-cert +Name: mssql-standalone-tls-client-cert Namespace: demo Labels: app.kubernetes.io/component=database - app.kubernetes.io/instance=ms-tls + app.kubernetes.io/instance=mssql-standalone-tls app.kubernetes.io/managed-by=kubedb.com - app.kubernetes.io/name=mssqlserveres.kubedb.com + app.kubernetes.io/name=mssqlservers.kubedb.com + controller.cert-manager.io/fao=true Annotations: cert-manager.io/alt-names: - cert-manager.io/certificate-name: ms-tls-client-cert - cert-manager.io/common-name: default + cert-manager.io/certificate-name: mssql-standalone-tls-client-cert + cert-manager.io/common-name: mssql cert-manager.io/ip-sans: cert-manager.io/issuer-group: cert-manager.io cert-manager.io/issuer-kind: Issuer cert-manager.io/issuer-name: mssqlserver-ca-issuer + cert-manager.io/subject-organizationalunits: client + cert-manager.io/subject-organizations: kubedb cert-manager.io/uri-sans: Type: kubernetes.io/tls Data ==== -ca.crt: 1147 bytes -tls.crt: 1127 bytes -tls.key: 1675 bytes +ca.crt: 1164 bytes +tls.crt: 1180 bytes +tls.key: 1679 bytes ``` -Now, we can connect using tls certs to connect to the mssqlserver and write some data +Now, we can connect with tls to the mssqlserver and write some data + +```bash +$ kubectl get secret -n demo mssql-standalone-tls-auth -o jsonpath='{.data.\username}' | base64 -d +sa + +$ kubectl get secret -n demo mssql-standalone-tls-auth -o jsonpath='{.data.\password}' | base64 -d +C2vU3HOCWY0hQHaj +``` ```bash -$ kubectl exec -it -n demo ms-tls-0 -c mssqlserver -- bash - -# Trying to connect without tls certificates -root@ms-tls-0:/data# mssqlserver-cli -127.0.0.1:6379> -127.0.0.1:6379> set hello world -# Can not write data -Error: Connection reset by peer - -# Trying to connect with tls certificates -root@ms-tls-0:/data# mssqlserver-cli --tls --cert "/certs/client.crt" --key "/certs/client.key" --cacert "/certs/ca.crt" -127.0.0.1:6379> -127.0.0.1:6379> set hello world -OK -127.0.0.1:6379> exit +$ kubectl exec -it -n demo mssql-standalone-tls-0 -c mssql -- bash +mssql@mssql-standalone-tls-0:/$ /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P "C2vU3HOCWY0hQHaj" -N +1> select name from sys.databases +2> go +name +-------------------------------------------------------------------------------------------------------------------------------- +master +tempdb +model +msdb +kubedb_system + +(5 rows affected) +1> create database tls_test +2> go +1> use tls_test +2> go +Changed database context to 'tls_test'. +1> CREATE TABLE Data (ID INT, NAME NVARCHAR(255), AGE INT); +2> go +1> INSERT INTO Data(ID, Name, Age) VALUES (1, 'John Doe', 25), (2, 'Jane Smith', 30); +2> go +(2 rows affected) +1> select * from data +2> go +ID NAME AGE +----------- -------------------------------------------- +1 John Doe 25 +2 Jane Smith 30 +(2 rows affected) +1> ``` ## Cleaning up @@ -180,11 +229,11 @@ OK To clean up the Kubernetes resources created by this tutorial, run: ```bash -$ kubectl patch -n demo mssqlserver/ms-tls -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" -mssqlserver.kubedb.com/ms-tls patched +$ kubectl patch -n demo mssqlserver/mssql-standalone-tls -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +mssqlserver.kubedb.com/mssql-standalone-tls patched -$ kubectl delete -n demo mssqlserver ms-tls -mssqlserver.kubedb.com "ms-tls" deleted +$ kubectl delete -n demo mssqlserver mssql-standalone-tls +mssqlserver.kubedb.com "mssql-standalone-tls" deleted $ kubectl delete issuer -n demo mssqlserver-ca-issuer issuer.cert-manager.io "mssqlserver-ca-issuer" deleted @@ -193,4 +242,4 @@ issuer.cert-manager.io "mssqlserver-ca-issuer" deleted ## Next Steps - Detail concepts of [MSSQLServer object](/docs/guides/mssqlserver/concepts/mssqlserver.md). -- [Backup and Restore](/docs/guides/mssqlserver/backup/overview/index.md) MSSQLServer databases using KubeStash. . \ No newline at end of file +- [Backup and Restore](/docs/guides/mssqlserver/backup/overview/index.md) MSSQLServer databases using KubeStash. \ No newline at end of file From c748492fb3692c3416d2e94763ba3b479346398d Mon Sep 17 00:00:00 2001 From: Tamal Saha Date: Tue, 22 Oct 2024 10:59:51 -0700 Subject: [PATCH 4/5] Update ag_cluster.md Signed-off-by: Tamal Saha --- docs/guides/mssqlserver/tls/ag_cluster.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/mssqlserver/tls/ag_cluster.md b/docs/guides/mssqlserver/tls/ag_cluster.md index 9a689d92ff..f419b5ef49 100644 --- a/docs/guides/mssqlserver/tls/ag_cluster.md +++ b/docs/guides/mssqlserver/tls/ag_cluster.md @@ -4,7 +4,7 @@ menu: docs_{{ .version }}: identifier: mssql-ag-tls-availability-group name: Availability Group (HA Cluster) - parent: mssql-ag-tls + parent: ms-tls weight: 30 menu_name: docs_{{ .version }} section_menu_id: guides From 129e740e98c17e35bda877350020f7468dba4aa1 Mon Sep 17 00:00:00 2001 From: Neaj Morshad Date: Thu, 24 Oct 2024 19:21:01 +0600 Subject: [PATCH 5/5] remove Signed-off-by: Neaj Morshad --- docs/examples/mssqlserver/tls/clusterissuer.yaml | 7 ------- 1 file changed, 7 deletions(-) delete mode 100644 docs/examples/mssqlserver/tls/clusterissuer.yaml diff --git a/docs/examples/mssqlserver/tls/clusterissuer.yaml b/docs/examples/mssqlserver/tls/clusterissuer.yaml deleted file mode 100644 index f18ef6ca85..0000000000 --- a/docs/examples/mssqlserver/tls/clusterissuer.yaml +++ /dev/null @@ -1,7 +0,0 @@ -apiVersion: cert-manager.io/v1 -kind: ClusterIssuer -metadata: - name: redis-ca-issuer -spec: - ca: - secretName: redis-ca