Creating and Deleting MySQL Instances

This topic describes how to create and delete MySQL instances.

Prerequisites

Before you can create or delete MySQL instances, you must have:

The Kubernetes Command Line Interface (kubectl) installed. For more information, see the Kubernetes documentation.
Full admin access to all Kubernetes resources in your developer namespace.

For information about Roles and RoleBindings that your Kubernetes cluster admin needs to create, see the Kubernetes documentation.
The URL and credentials to access the registry that stores the VMware MySQL Operator images. This can be the VMware Tanzu Network registry or the private registry configured for your environment. If you do not have access to the registry credentials, contact your Kubernetes admin to have these set up for you in your namespace.
The VMware SQL with MySQL for Kubernetes deployment templates. See Download the Deployment Templates.
Ensure that your storage class can provision persistent volumes. Check for existing storage classes by running:
```
kubectl get storageclass
```
If you don't have one, create or request one accordingly, based on your underlying infrastructure. For details on storage classes, refer to Kubernetes documentation.

Download the Deployment Templates

Download the deployment templates from Tanzu Network, and use them to customize the VMware SQL with MySQL for Kubernetes resources that you will deploy.

To access the templates:

Log in to VMware Tanzu Network and visit the VMware MySQL Operator product page.
Select VMware SQL with MySQL for Kubernetes v1.8.0 and download the .tgz archive file to your local machine.

Note: You do not need to download the Artifact References from the VMware SQL with MySQL for Kubernetes product page.
Expand the downloaded .tgz file. Open the directory mysql-for-kubernetes-1.8.0. The templates are located in the samples subdirectory.

The templates include the following:

backup.yaml (for the MySQLBackup resource)
backuplocation.yaml (for the MySQLBackupLocation resource)
backupschedule.yaml (for the MySQLBackupSchedule resource)
mysql.yaml (for the MySQL resource; this template is used to create MySQL instances)
restore.yaml (for the MySQLRestore resource)
tls-secret.yaml (for a TLS Secret)

Use these templates as a starting point for the instance creation, and backup/restore.

Create a MySQL Instance

Note: On OpenShift clusters, MySQL Instances cannot run on the "default" namespace because OpenShift does not assign SCC (Security Context Constraints) to pods in this namespace. See Managing security context constraints in the RedHat OpenShift documentation.

When you create a MySQL instance, the MySQL Operator also creates PVCs. The PVCs are attached to the instance and contain the data for the MySQL database. Single-node instances have one PVC, and high-availability (HA) instances have three. The PVC name contains the instance name and the MySQL Pod number. The PVC name is of the form mysql-data-INSTANCE-NAME-N, for example mysql-data-mysql-sample-0.

Selecting the VMware MySQL Version

The VMware MySQL Operator by default deploys the latest supported MySQL database version. The VMware MySQL Operator supports four versions: mysql-8.0.27, mysql-8.0.28, mysql-8.0.29, and mysql-8.0.31. To view your Operator's available VMware MySQL versions, run the command:

kubectl get mysqlversions

The command displays:

NAME           DB VERSION
mysql-8.0.28   8.0.28
mysql-8.0.29   8.0.29
mysql-8.0.31   8.0.31
mysql-8.0.32   8.0.32
mysql-latest   8.0.32

where:

NAME denotes the VMware MySQL version. The special VMware MySQL version named mysql-latest runs the latest Operator-supported MySQL version (for example, in 1.8.0 that is 8.0.32). It also configures the instance to automatically upgrade its MySQL version whenever any future Operator upgrades add support for newer MySQL versions. For more details see Property Reference for MySQL Resource.
DB VERSION displays the Percona MySQL version an instance runs when that VMware MySQL version is named in the instance's spec.

Note which value in the DB VERSION column you wish to deploy with your instance, if different than the default.

Deploying an Instance

To create a MySQL instance:

Target the namespace where you want to create the MySQL instance:
```
kubectl config set-context --current --namespace=DEVELOPMENT-NAMESPACE
```
Where DEVELOPMENT-NAMESPACE is the namespace in which you want to create the instance. For example:
```
kubectl config set-context --current --namespace=my-namespace
```

From your namespace, Kubernetes must be able to access the registry that stores the VMware MySQL Operator images. To allow this, create an imagePullSecret by running:

kubectl create secret --namespace=DEVELOPMENT-NAMESPACE \
    docker-registry tanzu-image-registry \
    --docker-server=REGISTRY-SERVER-URL \
    --docker-username=DOCKER-USERNAME \
    --docker-password=DOCKER-PASSWORD

Where:

DEVELOPMENT-NAMESPACE is the namespace in which you want to create the instance
REGISTRY-SERVER-URL is the VMware Tanzu Network registry or the private registry configured for your environment
DOCKER-USERNAME and DOCKER-PASSWORD are the credentials used to pull images from the registry.

For example:

kubectl create secret --namespace=my-namespace \
    docker-registry tanzu-image-registry  \
    --docker-server=https://registry.tanzu.vmware.com/ \
    --docker-username=sample-username  \
    --docker-password=sample-password

secret/tanzu-image-registry created

Locate the mysql.yaml deployment template in the TGZ file you downloaded from VMware Tanzu Network. For details on downloading deployment template, see Download the Deployment Templates.

Create a copy of the mysql.yaml file and give it a unique name. For example:

cp ~/Downloads/mysql-for-kubernetes-1.8.0/samples/mysql.yaml testdb.yaml

Edit the file and customize the instance according to your requirements.

To customize the VMware MySQL instance version, use one of the values under the column NAME displayed at the output of the command kubectl get mysqlversions, and specify the mysql.spec.mysqlVersion.name field in the MySQL instance manifest:
```
...
metadata:
  name: mysql-sample
spec:

#### Specify the MySQL Version
  mysqlVersion:
    name: mysql-8.0.31
...
```
IMPORTANT: Specify mysql-latest as your instances version if you can tolerate occasional unscheduled database outages triggered by future Operator ugprades. Upgraded Operators immediately upgrade all mysql-latest instances to run any newer "latest" supported MySQL version, and the upgrade is disruptive. To avoid future Operator-induced unscheduled outages, select the highest-numbered NAME value, e.g. mysql-8.0.28.

You may also customize your VMware MySQL instance resources, instance storage class, storage size, high availability, node affinity and tolerations, PVC retention policy, service type (ClusterIP or LoadBalancer), and TLS secret. For details on the properties that you can set for the MySQL resource, see Property Reference for the MySQL Resource.

Deploy a MySQL instance to Kubernetes by running:

kubectl -n DEVELOPMENT-NAMESPACE apply -f FILENAME

Where FILENAME is the name of the configuration file you created. For example:

kubectl -n my-namespace apply -f testdb.yaml

mysql.with.sql.tanzu.vmware.com/mysql-sample created

Verify that the instance was created successfully by running:

kubectl -n DEVELOPMENT-NAMESPACE get mysql INSTANCE-NAME

Where INSTANCE-NAME is the value that you configured for metadata.name in your file. For example:

kubectl -n my-namespace get mysql mysql-sample

NAME           READY   STATUS    AGE    OPERATOR VERSION   DB VERSION   UPDATE STATUS       USER ACTION
mysql-sample   true    Running   162m   1.7.1              8.0.31       NoUpdateRequired

Review Configuring TLS for MySQL Instances if you need to configure a custom ClusterIssuer. By default, the MySQL instances created by VMware MySQL Operator 1.2.0 (and later) use TLS certificates provided by the cert-manager ClusterIssuer, using a self-signed certificate authority (CA).

Delete a VMware MySQL Instance

This section provides some conceptual information about deleting an instance, and the procedure for how to delete an instance.

There are two steps to deleting an instance. The first step is to delete the instance itself, and the second step is to delete the PVCs.

There are situations where you want to delete the instance but not delete the PVC. For example, in a test environment, you might delete the instance to save costs but keep the PVC storing the data. If you later create a new instance with the same name as the deleted instance, the old PVCs automatically reattach to the new instance and you have access to your data again.

Note: If you delete the Pod or the StatefulSet associated with the MySQL resource, the Operator re-creates it for you. To permanently delete the instance, you need to delete the MySQL resource, as described in step 1 below.

Procedure

To delete a MySQL instance:

Delete the MySQL instance by running:
```
kubectl -n DEVELOPMENT-NAMESPACE delete mysql INSTANCE-NAME
```
Where:
- DEVELOPMENT-NAMESPACE is the namespace where you created the instance.
- INSTANCE-NAME is the name of the instance you want to delete.
For example:
```
kubectl -n my-namespace delete mysql mysql-sample
```
```
my-namespace "mysql-sample" deleted
```
(Optional) Delete the PVCs by running:

Warning: This command is destructive. When you destroy your PVCs, you delete all data associated with your VMware MySQL Operator database.
```
kubectl delete pvc -l app.kubernetes.io/instance=INSTANCE-NAME
```
Where INSTANCE-NAME is the name of the MySQL instance that you deleted above.

For example:
```
kubectl delete pvc -l app.kubernetes.io/instance=mysql-sample
```
```
persistentvolumeclaim "mysql-data-mysql-sample-0" deleted
```
Note: For HA MySQL instances, the command deletes all three PVCs associated with the MySQL instance.