Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add Update Version doc
Browse files Browse the repository at this point in the history
Signed-off-by: Neaj Morshad <[email protected]>
Neaj-Morshad-101 committed Nov 14, 2024

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
1 parent 33646e8 commit 8b86a72
Showing 10 changed files with 1,898 additions and 24 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
apiVersion: ops.kubedb.com/v1alpha1
kind: MSSQLServerOpsRequest
metadata:
name: msops-update-ag-cluster
namespace: demo
spec:
type: UpdateVersion
databaseRef:
name: mssql-ag-cluster
updateVersion:
targetVersion: 2022-cu14
timeout: 5m
apply: IfReady
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
apiVersion: ops.kubedb.com/v1alpha1
kind: MSSQLServerOpsRequest
metadata:
name: msops-update-standalone
namespace: demo
spec:
type: UpdateVersion
databaseRef:
name: mssql-standalone
updateVersion:
targetVersion: 2022-cu14
timeout: 5m
apply: IfReady
44 changes: 44 additions & 0 deletions docs/examples/mssqlserver/update-version/mssql-ag-cluster.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
apiVersion: kubedb.com/v1alpha2
kind: MSSQLServer
metadata:
name: mssql-ag-cluster
namespace: demo
spec:
version: "2022-cu12"
replicas: 3
topology:
mode: AvailabilityGroup
availabilityGroup:
databases:
- agdb1
- agdb2
tls:
issuerRef:
name: mssqlserver-ca-issuer
kind: Issuer
apiGroup: "cert-manager.io"
clientTLS: false
podTemplate:
spec:
containers:
- name: mssql
env:
- name: ACCEPT_EULA
value: "Y"
- name: MSSQL_PID
value: Evaluation
resources:
requests:
cpu: "500m"
memory: "1.5Gi"
limits:
memory: "2Gi"
storageType: Durable
storage:
storageClassName: "standard"
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
deletionPolicy: WipeOut
32 changes: 32 additions & 0 deletions docs/examples/mssqlserver/update-version/mssql-standalone.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
apiVersion: kubedb.com/v1alpha2
kind: MSSQLServer
metadata:
name: mssql-standalone
namespace: demo
spec:
version: "2022-cu12"
replicas: 1
storageType: Durable
tls:
issuerRef:
name: mssqlserver-ca-issuer
kind: Issuer
apiGroup: "cert-manager.io"
clientTLS: false
podTemplate:
spec:
containers:
- name: mssql
env:
- name: ACCEPT_EULA
value: "Y"
- name: MSSQL_PID
value: Evaluation
storage:
storageClassName: "standard"
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
deletionPolicy: WipeOut
48 changes: 24 additions & 24 deletions docs/guides/mssqlserver/README.md
Original file line number Diff line number Diff line change
@@ -20,30 +20,30 @@ Microsoft SQL Server is one of the most popular relational database management s

## Supported Microsoft SQL Server Features

| Features | Availability |
|---------------------------------------------------------------------|:------------:|
| Standalone and Availability Group Cluster (HA configuration) | &#10003; |
| Synchronous Replication | &#10003; |
| Automatic Failover | &#10003; |
| Custom Configuration | &#10003; |
| Authentication & Authorization | &#10003; |
| Externally manageable Auth Secret | &#10003; |
| Instant and Scheduled Backup ([KubeStash](https://kubestash.com/)) | &#10003; |
| Continuous Archiving using `wal-g` | &#10003; |
| Initialization from WAL archive | &#10003; |
| Initializing from Snapshot ([KubeStash](https://kubestash.com/)) | &#10003; |
| Reconfigurable Health Checker | &#10003; |
| Persistent volume | &#10003; |
| Builtin Prometheus Discovery | &#10003; |
| Using Prometheus operator | &#10003; |
| Automated Version Update | &#10003; |
| Automated Vertical Scaling, Volume Expansion | &#10003; |
| Automated Horizontal Scaling | &#10003; |
| Autoscaler for Compute and Storage Resources | &#10003; |
| Reconfiguration | &#10003; |
| TLS | &#10003; |
| Grafana Dashboards | &#10003; |
| Autoscaling (vertically) | &#10003; |
| Features | Availability |
|--------------------------------------------------------------------|:------------:|
| Standalone and Availability Group Cluster (HA configuration) | &#10003; |
| Synchronous Replication | &#10003; |
| Automatic Failover | &#10003; |
| Custom Configuration | &#10003; |
| Authentication & Authorization | &#10003; |
| Externally manageable Auth Secret | &#10003; |
| Instant and Scheduled Backup ([KubeStash](https://kubestash.com/)) | &#10003; |
| Continuous Archiving using `wal-g` | &#10003; |
| Initialization from WAL archive | &#10003; |
| Initializing from Snapshot ([KubeStash](https://kubestash.com/)) | &#10003; |
| Reconfigurable Health Checker | &#10003; |
| Persistent Volume | &#10003; |
| Builtin Prometheus Discovery | &#10003; |
| Using Prometheus operator | &#10003; |
| Automated Version Update | &#10003; |
| Automated Vertical Scaling, Volume Expansion | &#10003; |
| Automated Horizontal Scaling | &#10003; |
| Autoscaling Compute and Storage Resources | &#10003; |
| Reconfiguration | &#10003; |
| TLS | &#10003; |
| Reconfigure TLS | &#10003; |
| Grafana Dashboards | &#10003; |


## Supported Microsoft SQL Server Versions
54 changes: 54 additions & 0 deletions docs/guides/mssqlserver/reconfigure-tls/overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
---
title: Reconfiguring TLS of MSSQLServer Database
menu:
docs_{{ .version }}:
identifier: mg-reconfigure-tls-overview
name: Overview
parent: mg-reconfigure-tls
weight: 10
menu_name: docs_{{ .version }}
section_menu_id: guides
---

> New to KubeDB? Please start [here](/docs/README.md).
# Reconfiguring TLS of MSSQLServer Database

This guide will give an overview on how KubeDB Ops-manager operator reconfigures TLS configuration i.e. add TLS, remove TLS, update issuer/cluster issuer or Certificates and rotate the certificates of a `MSSQLServer` database.

## Before You Begin

- You should be familiar with the following `KubeDB` concepts:
- [MSSQLServer](/docs/guides/mssqlserver/concepts/mssqlserver.md)
- [MSSQLServerOpsRequest](/docs/guides/mssqlserver/concepts/opsrequest.md)

## How Reconfiguring MSSQLServer TLS Configuration Process Works

The following diagram shows how KubeDB Ops-manager operator reconfigures TLS of a `MSSQLServer` database. Open the image in a new tab to see the enlarged version.

<figure align="center">
  <img alt="Reconfiguring TLS process of MSSQLServer" src="/docs/images/day-2-operation/mssqlserver/mg-reconfigure-tls.svg">
<figcaption align="center">Fig: Reconfiguring TLS process of MSSQLServer</figcaption>
</figure>

The Reconfiguring MSSQLServer TLS process consists of the following steps:

1. At first, a user creates a `MSSQLServer` Custom Resource Object (CRO).

2. `KubeDB` Provisioner operator watches the `MSSQLServer` CRO.

3. When the operator finds a `MSSQLServer` CR, it creates required number of `PetSets` and related necessary stuff like secrets, services, etc.

4. Then, in order to reconfigure the TLS configuration of the `MSSQLServer` database the user creates a `MSSQLServerOpsRequest` CR with desired information.

5. `KubeDB` Ops-manager operator watches the `MSSQLServerOpsRequest` CR.

6. When it finds a `MSSQLServerOpsRequest` CR, it pauses the `MSSQLServer` object which is referred from the `MSSQLServerOpsRequest`. So, the `KubeDB` Provisioner operator doesn't perform any operations on the `MSSQLServer` object during the reconfiguring TLS process.

7. Then the `KubeDB` Ops-manager operator will add, remove, update or rotate TLS configuration based on the Ops Request yaml.

8. Then the `KubeDB` Ops-manager operator will restart all the Pods of the database so that they restart with the new TLS configuration defined in the `MSSQLServerOpsRequest` CR.

9. After the successful reconfiguring of the `MSSQLServer` TLS, the `KubeDB` Ops-manager operator resumes the `MSSQLServer` object so that the `KubeDB` Provisioner operator resumes its usual operations.

In the next docs, we are going to show a step by step guide on reconfiguring TLS configuration of a MSSQLServer database using `MSSQLServerOpsRequest` CRD.
1,006 changes: 1,006 additions & 0 deletions docs/guides/mssqlserver/reconfigure-tls/reconfigure-tls.md

Large diffs are not rendered by default.

352 changes: 352 additions & 0 deletions docs/guides/mssqlserver/update-version/ag_cluster.md

Large diffs are not rendered by default.

54 changes: 54 additions & 0 deletions docs/guides/mssqlserver/update-version/overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
---
title: Updating MSSQLServer Overview
menu:
docs_{{ .version }}:
identifier: ms-updating-overview
name: Overview
parent: mssql-updating
weight: 10
menu_name: docs_{{ .version }}
section_menu_id: guides
---

> New to KubeDB? Please start [here](/docs/README.md).
# Updating MSSQLServer version Overview

This guide will give you an overview on how KubeDB Ops-manager operator update the version of `MSSQLServer` database.

## Before You Begin

- You should be familiar with the following `KubeDB` concepts:
- [MSSQLServer](/docs/guides/mssqlserver/concepts/mssqlserver.md)
- [MSSQLServerOpsRequest](/docs/guides/mssqlserver/concepts/opsrequest.md)

## How update version Process Works

The following diagram shows how KubeDB Ops-manager operator update the version of `MSSQLServer`. Open the image in a new tab to see the enlarged version.

<figure align="center">
  <img alt="updating Process of MSSQLServer" src="/docs/images/day-2-operation/mssqlserver/ms-update-version.png">
<figcaption align="center">Fig: Updating Process of MSSQLServer</figcaption>
</figure>

The updating process consists of the following steps:

1. At first, a user creates a `MSSQLServer` Custom Resource (CR).

2. `KubeDB` Provisioner operator watches the `MSSQLServer` CR.

3. When the operator finds a `MSSQLServer` CR, it creates `PetSets` and related necessary resources like secrets, services, etc.

4. Then, in order to update the version of the `MSSQLServer` the user creates a `MSSQLServerOpsRequest` CR with the desired version.

5. `KubeDB` Ops-manager operator watches the `MSSQLServerOpsRequest` CR.

6. When it finds a `MSSQLServerOpsRequest` CR, it halts the `MSSQLServer` object which is referred from the `MSSQLServerOpsRequest`. So, the `KubeDB` Provisioner operator doesn't perform any operations on the `MSSQLServer` object during the updating process.

7. By looking at the target version from `MSSQLServerOpsRequest` CR, `KubeDB` Ops-manager operator updates the images of the `PetSet`.

8. After successfully updating the `PetSet` and their `Pods` images, the `KubeDB` Ops-manager operator updates the image of the `MSSQLServer` object to reflect the updated state of the database.

9. After successfully updating of `MSSQLServer` object, the `KubeDB` Ops-manager operator resumes the `MSSQLServer` object so that the `KubeDB` Provisioner operator can resume its usual operations.

In the next doc, we are going to show a step-by-step guide on updating of a MSSQLServer using UpdateVersion operation.
306 changes: 306 additions & 0 deletions docs/guides/mssqlserver/update-version/standalone.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,306 @@
---
title: Updating MSSQLServer Standalone
menu:
docs_{{ .version }}:
identifier: ms-updating-standalone
name: Standalone
parent: mssql-updating
weight: 20
menu_name: docs_{{ .version }}
section_menu_id: guides
---

> New to KubeDB? Please start [here](/docs/README.md).
# Update Version of MSSQLServer Standalone

This guide will show you how to use `KubeDB` Ops-manager operator to update the version of `MSSQLServer` standalone.

## Before You Begin

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

- Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). Make sure install with helm command including `--set global.featureGates.MSSQLServer=true` to ensure MSSQLServer CRD installation.

- 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. To install `cert-manager` in your cluster following steps [here](https://cert-manager.io/docs/installation/kubernetes/).

- You should be familiar with the following `KubeDB` concepts:
- [MSSQLServer](/docs/guides/mssqlserver/concepts/mssqlserver.md)
- [MSSQLServerOpsRequest](/docs/guides/mssqlserver/concepts/opsrequest.md)
- [Updating Overview](/docs/guides/mssqlserver/update-version/overview.md)

To keep everything isolated, we are going to use 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](/docs/examples/mssqlserver/update-version) directory of [kubedb/docs](https://github.com/kube/docs) repository.
### Prepare MSSQLServer Standalone Database

Now, we are going to deploy a `MSSQLServer` standalone database with version `2022-cu12`.

### Deploy MSSQLServer Standalone

In this section, we are going to deploy a MSSQLServer standalone database. Then, in the next section we will update the version of the database using `MSSQLServerOpsRequest` CR.

At first, we need to create an Issuer/ClusterIssuer which will be used to generate the certificate used for TLS configurations.

### Create Issuer/ClusterIssuer

Now, we are going to create an example `Issuer` that will be used throughout the duration of this tutorial. Alternatively, you can follow this [cert-manager tutorial](https://cert-manager.io/docs/configuration/ca/) to create your own `Issuer`. By following the below steps, we are going to create our desired issuer,

- Start off by generating our 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"
```
-
- Create a secret using the certificate files we have just generated,
```bash
$ kubectl create secret tls mssqlserver-ca --cert=ca.crt --key=ca.key --namespace=demo
secret/mssqlserver-ca created
```
Now, we are going to create an `Issuer` using the `mssqlserver-ca` secret that contains the ca-certificate we have just created. Below is the YAML of the `Issuer` CR that we are going to create,

```yaml
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: mssqlserver-ca-issuer
namespace: demo
spec:
ca:
secretName: mssqlserver-ca
```
Let’s create the `Issuer` CR we have shown above,
```bash
$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mssqlserver/standalone/mssqlserver-ca-issuer.yaml
issuer.cert-manager.io/mssqlserver-ca-issuer created
```


### Create MSSSQLServer

Below is the YAML of the `MSSQLServer` CR that we are going to create,

```yaml
apiVersion: kubedb.com/v1alpha2
kind: MSSQLServer
metadata:
name: mssql-standalone
namespace: demo
spec:
version: "2022-cu12"
replicas: 1
storageType: Durable
tls:
issuerRef:
name: mssqlserver-ca-issuer
kind: Issuer
apiGroup: "cert-manager.io"
clientTLS: false
podTemplate:
spec:
containers:
- name: mssql
env:
- name: ACCEPT_EULA
value: "Y"
- name: MSSQL_PID
value: Evaluation
storage:
storageClassName: "standard"
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
deletionPolicy: WipeOut
```

Let's create the `MSSQLServer` CR we have shown above,

```bash
$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mssqlserver/update-version/mssql-standalone.yaml
mssqlserver.kubedb.com/mssql-standalone created
```

Now, wait until `mssql-standalone` created has status `Ready`. i.e,

```bash
$ kubectl get ms -n demo
NAME VERSION STATUS AGE
mssql-standalone 2022-cu12 Ready 3m8s
```

We are now ready to apply the `MSSQLServerOpsRequest` CR to update this database.

### Update MSSQLServer Version

Here, we are going to update `MSSQLServer` standalone from `2022-cu12` to `2022-cu14`.

#### Create MSSQLServerOpsRequest:

In order to update the standalone database, we have to create a `MSSQLServerOpsRequest` CR with our desired version that is supported by `KubeDB`. Below is the YAML of the `MSSQLServerOpsRequest` CR that we are going to create,

```yaml
apiVersion: ops.kubedb.com/v1alpha1
kind: MSSQLServerOpsRequest
metadata:
name: msops-update-standalone
namespace: demo
spec:
type: UpdateVersion
databaseRef:
name: mssql-standalone
updateVersion:
targetVersion: 2022-cu14
timeout: 5m
apply: IfReady
```

Here,

- `spec.databaseRef.name` specifies that we are performing operation on `mssql-standalone` database.
- `spec.type` specifies that we are going to perform `UpdateVersion` on our database.
- `spec.updateVersion.targetVersion` specifies the expected version of the database `2022-cu14`.
- Have a look [here](/docs/guides/mssqlserver/concepts/opsrequest.md#spectimeout) on the respective sections to understand the `timeout` & `apply` fields.


Let's create the `MSSQLServerOpsRequest` CR we have shown above,

```bash
$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mssqlserver/update-version/msops-update-standalone.yaml
mssqlserveropsrequest.ops.kubedb.com/msops-update-standalone created
```

#### Verify MSSQLServer version updated successfully :

If everything goes well, `KubeDB` Ops-manager operator will update the image of `MSSQLServer` object and related `PetSets` and `Pods`.

Let's wait for `MSSQLServerOpsRequest` to be `Successful`. Run the following command to watch `MSSQLServerOpsRequest` CR,

```bash
$ watch kubectl get mssqlserveropsrequest -n demo
Every 2.0s: kubectl get mssqlserveropsrequest -n demo
NAME TYPE STATUS AGE
msops-update-standalone UpdateVersion Successful 2m28s
```

We can see from the above output that the `MSSQLServerOpsRequest` has succeeded. If we describe the `MSSQLServerOpsRequest` we will get an overview of the steps that were followed to update the database.

```bash
$ kubectl describe mssqlserveropsrequest -n demo msops-update-standalone
Name: msops-update-standalone
Namespace: demo
Labels: <none>
Annotations: <none>
API Version: ops.kubedb.com/v1alpha1
Kind: MSSQLServerOpsRequest
Metadata:
Creation Timestamp: 2024-11-12T12:46:07Z
Generation: 1
Resource Version: 328223
UID: 7038611f-8ebe-4fb9-8f79-1d73e9669445
Spec:
Apply: IfReady
Database Ref:
Name: mssql-standalone
Timeout: 5m
Type: UpdateVersion
Update Version:
Target Version: 2022-cu14
Status:
Conditions:
Last Transition Time: 2024-11-12T12:46:07Z
Message: MSSQLServer ops-request has started to update version
Observed Generation: 1
Reason: UpdateVersion
Status: True
Type: UpdateVersion
Last Transition Time: 2024-11-12T12:46:16Z
Message: successfully reconciled the MSSQLServer with updated version
Observed Generation: 1
Reason: UpdatePetSets
Status: True
Type: UpdatePetSets
Last Transition Time: 2024-11-12T12:46:21Z
Message: get pod; ConditionStatus:True; PodName:mssql-standalone-0
Observed Generation: 1
Status: True
Type: GetPod--mssql-standalone-0
Last Transition Time: 2024-11-12T12:46:21Z
Message: evict pod; ConditionStatus:True; PodName:mssql-standalone-0
Observed Generation: 1
Status: True
Type: EvictPod--mssql-standalone-0
Last Transition Time: 2024-11-12T12:48:16Z
Message: check pod running; ConditionStatus:True; PodName:mssql-standalone-0
Observed Generation: 1
Status: True
Type: CheckPodRunning--mssql-standalone-0
Last Transition Time: 2024-11-12T12:48:21Z
Message: Successfully Restarted MSSQLServer pods
Observed Generation: 1
Reason: RestartPods
Status: True
Type: RestartPods
Last Transition Time: 2024-11-12T12:48:21Z
Message: Successfully updated MSSQLServer
Observed Generation: 1
Reason: UpdateDatabase
Status: True
Type: UpdateDatabase
Last Transition Time: 2024-11-12T12:48:21Z
Message: Successfully updated MSSQLServer version
Observed Generation: 1
Reason: Successful
Status: True
Type: Successful
Observed Generation: 1
Phase: Successful
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Starting 2m42s KubeDB Ops-manager Operator Start processing for MSSQLServerOpsRequest: demo/msops-update-standalone
Normal Starting 2m42s KubeDB Ops-manager Operator Pausing MSSQLServer database: demo/mssql-standalone
Normal Successful 2m42s KubeDB Ops-manager Operator Successfully paused MSSQLServer database: demo/mssql-standalone for MSSQLServerOpsRequest: msops-update-standalone
Normal UpdatePetSets 2m33s KubeDB Ops-manager Operator successfully reconciled the MSSQLServer with updated version
Warning get pod; ConditionStatus:True; PodName:mssql-standalone-0 2m28s KubeDB Ops-manager Operator get pod; ConditionStatus:True; PodName:mssql-standalone-0
Warning evict pod; ConditionStatus:True; PodName:mssql-standalone-0 2m28s KubeDB Ops-manager Operator evict pod; ConditionStatus:True; PodName:mssql-standalone-0
Warning check pod running; ConditionStatus:False; PodName:mssql-standalone-0 2m23s KubeDB Ops-manager Operator check pod running; ConditionStatus:False; PodName:mssql-standalone-0
Warning check pod running; ConditionStatus:True; PodName:mssql-standalone-0 33s KubeDB Ops-manager Operator check pod running; ConditionStatus:True; PodName:mssql-standalone-0
Normal RestartPods 28s KubeDB Ops-manager Operator Successfully Restarted MSSQLServer pods
Normal Starting 28s KubeDB Ops-manager Operator Resuming MSSQLServer database: demo/mssql-standalone
Normal Successful 28s KubeDB Ops-manager Operator Successfully resumed MSSQLServer database: demo/mssql-standalone for MSSQLServerOpsRequest: msops-update-standalone
```

Now, we are going to verify whether the `MSSQLServer` and the related `PetSets` their `Pods` have the new version image. Let's check,

```bash
$ kubectl get ms -n demo mssql-standalone -o=jsonpath='{.spec.version}{"\n"}'
2022-cu14
$ kubectl get petset -n demo mssql-standalone -o=jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'
mcr.microsoft.com/mssql/server:2022-CU14-ubuntu-22.04@sha256:c1aa8afe9b06eab64c9774a4802dcd032205d1be785b1fd51e1c0151e7586b74
$ kubectl get pods -n demo mssql-standalone-0 -o=jsonpath='{.spec.containers[0].image}{"\n"}'
mcr.microsoft.com/mssql/server:2022-CU14-ubuntu-22.04
```

You can see from above, our `MSSQLServer` standalone database has been updated with the new version. So, the update process is successfully completed.

## Cleaning Up

To clean up the Kubernetes resources created by this tutorial, run:

```bash
kubectl delete ms -n demo mssql-standalone
kubectl delete msops -n demo msops-update-standalone
kubectl delete issuer -n demo mssqlserver-ca-issuer
kubectl delete secret -n demo mssqlserver-ca
kubectl delete ns demo
```

0 comments on commit 8b86a72

Please sign in to comment.