Installing the VMware SQL with MySQL for Kubernetes Operator

This topic describes how to install the VMware MySQL Operator.

The primary method for installing VMware MySQL Operator is via Helm, using the Tanzu Network Registry or a downloadable file. For details, refer to Installing using Helm.

For Tanzu Application Platform (TAP) customers, the VMware MySQL Operator can be installed using the Tanzu CLI. For more details, refer to Installing using the Tanzu CLI.

Installing using Helm

Prerequisites

Before you deploy the VMware MySQL Operator, you need:

Access to Tanzu Network and Tanzu Network Registry. You can use the same credentials for both sites.
Docker running and configured on your local computer, to access the Kubernetes cluster and Docker registry.
A running Kubernetes cluster.
The kubectl command-line tool, configured and authenticated to communicate with your Kubernetes cluster.
The Helm CLI version 3.8.0 or newer. For more information, see Installing Helm from the Helm documentation.
cluster-admin ClusterRole access to the Kubernetes cluster. For more information, see the Kubernetes documentation.
Review the Network Policies Configuration topic if you have any network plugins (for example Network Plugin) in your Kubernetes cluster.

Cert Manager installed on the Kubernetes cluster.

To verify the cert manager installation run:

kubectl api-resources --api-group=cert-manager.io

You should see an output similar to:

NAME                  SHORTNAMES   APIVERSION           NAMESPACED   KIND
certificaterequests   cr,crs       cert-manager.io/v1   true         CertificateRequest
certificates          cert,certs   cert-manager.io/v1   true         Certificate
clusterissuers                     cert-manager.io/v1   false        ClusterIssuer
issuers                            cert-manager.io/v1   true         Issuer

To install cert-manager, if it is not already installed, refer to installation options in the cert-manager documentation.

To setup TLS security, refer to Configuring TLS for MySQL Instances.

Access the Resources

You can access and install using two different methods:

Use Setup the VMware MySQL Operator via Tanzu Network Registry for a faster installation process, and if your server hosts have access to the internet.
Use Setup the VMware MySQL Operator via Downloadable Archive File if your server hosts do not have access to the internet, or if you want to install from a private registry.

Setup the VMware MySQL Operator via the Tanzu Network Registry

Use Helm to log in to the Tanzu Network Registry by running:
```
helm registry login registry.tanzu.vmware.com
```
Follow the prompts to enter the email address and password for your VMware Tanzu Network account.

Download the Helm chart from the Tanzu Distribution Registry, and export into a local /tmp/ directory:

helm pull oci://registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/vmware-sql-with-mysql-operator --version 1.10.0 --untar --untardir /tmp

Setup the VMware MySQL Operator via a Downloaded Archive File

Download the VMware MySQL Operator distribution from VMware Tanzu Network. The download filename has the format: mysql-for-kubernetes-<version>.tgz.
Unpack the downloaded software:
```
cd ~/Downloads
tar xzf mysql-for-kubernetes-<version>.tgz
```
This command unpacks the distribution into a new directory named mysql-for-kubernetes-<version>, for example mysql-for-kubernetes-1.10.0.
Change to the new mysql-for-kubernetes-<version> directory. For example:
```
cd ./mysql-for-kubernetes-<version>
```
where is the release you selected.

Load the MySQL instance images to the Docker registry:

docker load -i ./images/mysql-instance-8.0.29
docker load -i ./images/mysql-instance-8.0.31
docker load -i ./images/mysql-instance-8.0.32
docker load -i ./images/mysql-instance-8.0.34

Load the MySQL Operator image to the Docker registry:
```
docker load -i ./images/mysql-operator
```

Verify that the five Docker images are now available.

docker images

REPOSITORY                                                             TAG                     IMAGE ID       CREATED        SIZE
registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/mysql-instance    1.10.0-mysql-8.0.29     3j2h83j93msl   2 weeks ago    1.15GB
registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/mysql-instance    1.10.0-mysql-8.0.31     a5cb44250541   2 weeks ago    1.26GB
registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/mysql-instance    1.10.0-mysql-8.0.32     24b4526b5393   2 weeks ago    1.63GB
registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/mysql-instance    1.10.0-mysql-8.0.34     fe89680a1d36   2 weeks ago    1.78GB
registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/mysql-operator    1.10.0                  8b46a4d26aa0   2 weeks ago    99.8MB

Push the VMware MySQL Docker images to the container registry of your choice. Set each image’s project and image repo name, tag the images, and then push them using the Docker command docker push.

This example tags and pushes the images to the Google Cloud Registry, using the default (core) project name for the example Google Cloud account.

gcloud auth configure-docker

PROJECT=$(gcloud config list core/project --format='value(core.project)')
REGISTRY="gcr.io/${PROJECT}"

INSTANCE_IMAGE_NAME="${REGISTRY}/mysql-instance:$(cat ./images/mysql-instance-8.0.29-tag)"
docker tag $(cat ./images/mysql-instance-8.0.29-id) ${INSTANCE_IMAGE_NAME}
docker push ${INSTANCE_IMAGE_NAME}

INSTANCE_IMAGE_NAME="${REGISTRY}/mysql-instance:$(cat ./images/mysql-instance-8.0.31-tag)"
docker tag $(cat ./images/mysql-instance-8.0.31-id) ${INSTANCE_IMAGE_NAME}
docker push ${INSTANCE_IMAGE_NAME}

INSTANCE_IMAGE_NAME="${REGISTRY}/mysql-instance:$(cat ./images/mysql-instance-8.0.32-tag)"
docker tag $(cat ./images/mysql-instance-8.0.32-id) ${INSTANCE_IMAGE_NAME}
docker push ${INSTANCE_IMAGE_NAME}

INSTANCE_IMAGE_NAME="${REGISTRY}/mysql-instance:$(cat ./images/mysql-instance-8.0.34-tag)"
docker tag $(cat ./images/mysql-instance-8.0.34-id) ${INSTANCE_IMAGE_NAME}
docker push ${INSTANCE_IMAGE_NAME}

OPERATOR_IMAGE_NAME="${REGISTRY}/mysql-operator:$(cat ./images/mysql-operator-tag)"
docker tag $(cat ./images/mysql-operator-id) ${OPERATOR_IMAGE_NAME}
docker push ${OPERATOR_IMAGE_NAME}

Install the Operator

Create Operator Namespace and Secrets

Create the Operator namespace:
```
kubectl create namespace NAMESPACE
```
where NAMESPACE is the name of a namespace where the following steps will create a docker-registry secret and install the operator.

For example:
```
kubectl create namespace vmware-mysql-for-kubernetes-system
```
Create a docker-registry type secret to allow the Kubernetes cluster to authenticate with a private image registry, or the Tanzu Registry, so it can pull images.

IMPORTANT: Re-run the commands below to create identical or equivalent secrets in every namespace in which users will create VMware MySQL instances, and replace the Operator namespace vmware-mysql-for-kubernetes-system by the instance namespace (e.g. default).
If these secrets are not created in the instance namespace, the users will receive "ImagePullBackOff" errors when creating instances, as their MySQL pods fail to pull instance images from the image registry.
```
kubectl create secret docker-registry <SECRET-NAME> \
    --docker-server=<DOCKER-SERVER> \
    --docker-username=<DOCKER-USERNAME> \
    --docker-password=<DOCKER-PASSWORD> \
    --namespace=<OPERATOR-NAMESPACE>
```
where: - SECRET-NAME is the name of the secret. Choose tanzu-image-registry to match the default secret name used by the operator - DOCKER-SERVER is the name of the server location for the registry - DOCKER-USERNAME is the username for registry authentication - DOCKER-PASSWORD is the password for registry authentication

For example:
```
kubectl create secret docker-registry tanzu-image-registry \
  --docker-server=registry.tanzu.vmware.com \
  --docker-username=my-username \
  --docker-password=my-password \
  --namespace=vmware-mysql-for-kubernetes-system
```

Review the Operator Values

The below Operator configuration files are in the helm chart directory vmware-sql-with-mysql-operator.

If you setup the VMware MySQL Operator via Tanzu Network Registry, vmware-sql-with-mysql-operator should be in the untardir directory specified in the helm pull ... command.
If you setup the VMware MySQL Operator via a downloaded archive file, go to the directory of helm charts within the unpacked archive file:
```
cd mysql-for-kubernetes-*/charts
```
(or cd charts from within that unpacked archive file).

List the contents of the Operator helm chart directory vmware-sql-with-mysql-operator:

ls -F vmware-sql-with-mysql-operator

You should see that the chart directory contains config files and subdirectories:

Chart.yaml      crds/      templates/      values.schema.json      values.yaml

In most situations, the default values supplied in the Operator configuration file values.yaml do not need to be changed.

However, you will need to create an Operator Values Override file to replace those values with your own if any of the following are true:

You relocated the VMware SQL with MySQL for Kubernetes images to a custom private registry.
You named the registry secret something other than the default tanzu-image-registry in Create Operator Namespace and Secrets above.
You want to allocate specific CPU or memory resources for your Operator.
You want to specify your ClusterIssuer for generating TLS credentials for the databases.
You want to disable the security context on pods.

Create an Operator Values Override file:

The file values.yaml specifies the location of the MySQL Operator and instance images. By default it contains the following values:

---
imagePullSecretName: tanzu-image-registry
operatorImage: registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/mysql-operator:1.10.0
registry: "registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/"
resources: {}
certManagerClusterIssuerName: ""
enableSecurityContext: true

Create a copy of values.yaml and name the new file operator-values-overrides.yaml. Save this file in the same directory as the values.yaml file. In this file, you can specify the custom container registry and secret. For manual changes, you may also set individual parameters using the --set flag on the command line.

See Helm Values Files in the Helm documentation for more information.

Note: When installing the Operator on OpenShift, set enableSecurityContext to false.

This step is optional for customers not using Openshift.

If you are using a single node Minikube environment, it is not necessary to override the operator/values.yaml file because Minikube pulls the images from its local Docker registry.

Determine which values in the values.yaml file need to be changed for your environment. Use the table below as a guide.

Key	Value Type	Description
`imagePullSecret`	String	Name of image pull secret. This value must match the name of the Kubernetes docker-registry type secret you created in Create Operator Namespace and Secrets.
`operatorImage`	URI	Reference to the VMware MySQL Operator image. If you uploaded the Operator image to a private registry, you must change this reference to pull the Operator image from your registry.
`registry`	URI	The registry from which to download VMware MySQL images.
`resources`	List	Limits and requests for CPU and memory for the VMware MySQL Operator. You can change these values to scale your resources.
`certManagerClusterIssuerName`	String	Name of any custom TLS issuer in Cert Manager, if you created one while configuring Cert Manager in the above Prerequisites. Details are in [Configuring a Custom TLS Issuer](configure-tls.html#configuring-a-custom-tls-issuer).
`enableSecurityContext`	boolean	Enable security context for the MySQL Operator deployment and the managed instances, typically deactivated (set to false) on OpenShift clusters.

Edit the values that you want to change.
Delete the sections of the file that you do not change.
Save the operator-values-overrides.yaml file in a location of your choice or the same directory as the values.yaml file. You will reference this file during upcoming deployment steps.

Deploy the Operator

By default, the VMware MySQL Operator configures a ClusterIssuer for issuing MySQL instance TLS certificates. Customers requiring a custom Certificate Authority for TLS, follow the Operator install steps in Configuring a Custom TLS Issuer in the Configuring TLS for MySQL Instances page.

Use Helm to install the MySQL Operator in your Kubernetes cluster:

Without an override file:
```
helm install <RELEASE-NAME> <CHART-DIR> \
  -n <OPERATOR-NAMESPACE> \
  --wait
```
If you need to specify an override file:
```
helm install <RELEASE-NAME> <CHART-DIR> \
  -f <OVERRIDE-FILE> \
  -n <OPERATOR-NAMESPACE> \
  --wait
```
where: - RELEASE-NAME is the custom name you provide for your MySQL Operator - CHART-DIR is the location of the MySQL Operator helm chart - OPERATOR-NAMESPACE is the Operator namespace you created in Create Operator Namespace and Secrets - OVERRIDE-FILE is the override file with your custom values, as per Review the Operator Values

For example:
```
helm install my-mysql-operator /tmp/vmware-sql-with-mysql-operator \
  -n vmware-mysql-for-kubernetes-system \
  --wait
```
Or another example where the chart reference is an OCI registry name instead of a downloaded directory:
```
helm install my-mysql-operator oci://registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/vmware-sql-with-mysql-operator --version 1.10.0 \
  -n vmware-mysql-for-kubernetes-system \
  --wait
```
The command displays a message similar to:
```
NAME: my-mysql-operator
LAST DEPLOYED: Wed Jun 16 13:28:05 2022
NAMESPACE: vmware-mysql-for-kubernetes-system
STATUS: deployed
REVISION: 1
TEST SUITE: None
```
Note: Install the Operator in the same namespace as the secrets, as described in Create Operator Namespace and Secrets.
If you used an Operator values override file, save it for future Operator upgrades reference. By default, Helm will re-apply those override values when you later use helm upgrade, unless you perform the upgrade with a different override file or with the --reset-values flag. For more details on Helm upgrades, see Helm Upgrade in the Helm documentation.

Use watch kubectl get all to monitor the progress of the deployment. The deployment is complete when the MySQL Operator pod status changes to Running.

watch kubectl get all -n <OPERATOR-NAMESPACE>

where OPERATOR-NAMESPACE is the namespace where the operator is installed.

For example:

watch kubectl get all -n vmware-mysql-for-kubernetes-system

The output would be similar to:

NAME                                    READY   STATUS    RESTARTS   AGE
pod/my-mysql-operator-d8545b9c6-pwbxd   1/1     Running   0          20s

NAME                               TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
service/my-mysql-webhook-service   ClusterIP   10.8.2.19    <none>        443/TCP   22s

NAME                                READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/my-mysql-operator   1/1     1            1           22s

NAME                                          DESIRED   CURRENT   READY   AGE
replicaset.apps/my-mysql-operator-d8545b9c6   1         1         1       22s

You may also check the logs to confirm the Operator is running properly:

kubectl logs -n <OPERATOR-NAMESPACE> -l app.kubernetes.io/name=tanzu-sql-with-mysql-operator

where OPERATOR-NAMESPACE is the namespace where the operator is installed.

Clean up the downloaded chart if it is no longer needed:
```
rm -rf <CHART-DIR>
```
where CHART-DIR is the directory of the downloaded helm chart.

For example:
```
rm -rf /tmp/vmware-sql-with-mysql-operator
```

Installing using the Tanzu CLI

Prerequisites

A Tanzu Network account to access images from the VMware Tanzu Network registry.
A private registry, to relocate images from VMware Tanzu Network registry.
Before using the Tanzu CLI, certain prerequisites (kapp-controller and secretgen-controller) must be installed on the Kubernetes cluster. For details on these requirements review Cluster Essentials for VMware Tanzu.
Tanzu CLI installed on your local environment.
Cert Manager installed on the Kubernetes cluster.

(Optional) Relocate Images to a Private Registry

The VMware Tanzu Network registry does not offer uptime guarantees for installations. Skipping image relocation should only occur when configuring an evaluation, testing, or proof-of-concept environment.

To relocate images from the VMware Tanzu Network registry to a private registry:

Log in to your image registry by running:
```
docker login <MY-REGISTRY>
```
where:
- MY-REGISTRY is your own image registry
Log in to the VMware Tanzu Network registry with your VMware Tanzu Network credentials by running:
```
docker login registry.tanzu.vmware.com
```
Install imgpkg from carvel.dev.
Relocate the images to a private registry.
```
imgpkg copy -b registry.tanzu.vmware.com/packages-for-vmware-tanzu-data-services/tds-packages:<TDS-VERSION> \
     --to-repo <MY-REGISTRY>/<TARGET-REPOSITORY>/tds-packages
```
where: - MY-REGISTRY is your own image registry - TARGET-REPOSITORY is your target repository - TDS-VERSION is the tag for the image bundle (e.g. 1.12.0). Each VMware MySQL Operator release corresponds to a TDS package version. For instance, MySQL Operator version 1.10.0 is part of TDS version 1.12.0. Insert the correct version for your VMware MySQL Operator release.

For example:
```
imgpkg copy -b registry.tanzu.vmware.com/packages-for-vmware-tanzu-data-services/tds-packages:1.12.0 \
     --to-repo gcr.io/my-project/tds-packages
```

Create a Kubernetes Secret

First, verify the existing secrets in your environment.

tanzu secret registry list

The output would look similar to:

NAME                   REGISTRY                       EXPORTED           AGE
test-registry          my-registry                    to all namespaces  47h
tanzu-registry         registry.tanzu.vmware.com      to all namespaces  47h

Verify there is an exported secret for your custom image registry. If there is no associated secret, create a secret and export the secret to all namespaces:

tanzu secret registry add <SECRET-NAME> \
    --username <MY-REGISTRY-USERNAME> \
    --password <MY-REGISTRY-PASSWORD> \
    --server <MY-REGISTRY> \
    --export-to-all-namespaces --yes

where: - SECRET-NAME: is the name of the Kubernetes secret that will be created - MY-REGISTRY is your own image registry, or registry.tanzu.vmware.com to install directly from TanzuNet - MY-REGISTRY-USERNAME is the username for your own container registry - MY-REGISTRY-PASSWORD is the password for your own container registry

For example:

tanzu secret registry add tanzu-registry \
    --username [email protected] \
    --password my-password \
    --server registry.tanzu.vmware.com \
    --export-to-all-namespaces --yes

Create or select a namespace

Select a namespace to install the MySQL operator into, and create it if it does not exist. It is recommended to install the operator into its own namespace, or in a namespace shared with VMware SQL with Postgres for Kubernetes.

kubectl create namespace <NAMESPACE>

For example:

kubectl create namespace data-services-operators

Add the Package Repository

Add the package repository for VMware Tanzu Data Services:

tanzu package repository add <PACKAGE-REPOSITORY-NAME> \
     --url <MY-REGISTRY>/<TARGET-REPOSITORY>/tds-packages:<TDS-VERSION> \
     -n <NAMESPACE>

where: - PACKAGE-REPOSITORY-NAME is a name chosen to identify this package repository - MY-REGISTRY is your own image registry - TARGET-REPOSITORY is your target repository - TDS-VERSION is the tag for the image bundle (e.g. 1.12.0). Each VMware MySQL Operator release corresponds to a TDS package version. For instance, MySQL Operator version 1.10.0 is part of TDS version 1.12.0. Insert the correct version for your VMware MySQL Operator release. - NAMESPACE is the namespace where the Package and PackageInstall will be created

For example:

tanzu package repository add sql-data-services \
     --url registry.tanzu.vmware.com/packages-for-vmware-tanzu-data-services/tds-packages:1.12.0 \
     -n data-services-operators

List the latest packages to confirm the addition:

tanzu package available list -n <NAMESPACE> mysql-operator.with.sql.tanzu.vmware.com

  NAME                                      VERSION   RELEASED-AT
  ...
  mysql-operator.with.sql.tanzu.vmware.com  1.9.0     2023-09-05 11:28:29 -0700 PDT
  mysql-operator.with.sql.tanzu.vmware.com  1.10.0    2023-10-18 13:48:21 -0700 PDT

Check the values for the MySQL Operator package:

tanzu package available get mysql-operator.with.sql.tanzu.vmware.com/1.10.0 --values-schema -n <NAMESPACE>

  KEY                           DEFAULT                                                      TYPE     DESCRIPTION
  certManagerClusterIssuerName  vmware-sql-with-mysql-operator-ca-certificate-clusterissuer  string   A cert-manager based clusterissuer used to sign mysql certificates using a
                                                                                                      custom certificate authority
  enableSecurityContext         true                                                         boolean  EnableSecurityContext sets the security context for the operator and its managed
                                                                                                      instances, typically disabled on OpenShift
  imagePullSecretName           tanzu-image-registry                                         string   Reference to a secret in the same namespace as the operator to use for pulling
                                                                                                      any of the images used by the operator.
  resources                                                                                  object   Specifies the resource requests and limits for the operator pod

Consider overriding the Operator values in a separate YAML file, if the defaults do not suit your deployment environment. A sample overrides YAML could be:

Note: When installing the Operator on OpenShift, set enableSecurityContext to false.

certManagerClusterIssuerName: custom-issuer
imagePullSecretName: custom-secret
resources:
  limits:
    cpu: 500m
    memory: 300Mi
  requests:
    cpu: 500m
    memory: 300Mi
enableSecurityContext: true

Install the Operator

Install the operator package.

Install the MySQL operator package, using the overrides file you created:
```
tanzu package install <PACKAGE-NAME> \
    --package mysql-operator.with.sql.tanzu.vmware.com \
    --version 1.10.0 \
    -f <YOUR-OVERRIDES-FILE-PATH> -n <NAMESPACE>
```
where:
- PACKAGE-NAME is the name you choose for the package installation.
- YOUR-OVERRIDES-FILE-PATH is your custom overrides path and file, for example overrides.yaml.
- NAMESPACE is the namespace where the Package Repository has been added
For example:
```
tanzu package install vmware-mysql-operator \
   --package mysql-operator.with.sql.tanzu.vmware.com \
   --version 1.10.0 \
   -n data-services-operators
```

Verify PackageInstall has been created.

tanzu package installed list -n <NAMESPACE>

For example:

tanzu package installed list -n data-services-operators

  NAME                   PACKAGE-NAME                              PACKAGE-VERSION   STATUS
  vmware-mysql-operator  mysql-operator.with.sql.tanzu.vmware.com  1.10.0            Reconcile succeeded

A service account is created so that the kapp-controller can create cluster-scope objects such as CustomResourceDefinitions, and so it will have permissions to create objects on any namespace. This service account is different than the service account for the MySQL operator to manage other Kubernetes resources (statefulsets, secrets, etc…)

To check the service accounts run:

kubectl get serviceaccount -n <NAMESPACE>

NAME                                               SECRETS   AGE
default                                            0         22h
vmware-mysql-operator                              0         4m46s
vmware-mysql-operator-data-services-operators-sa   0         4m52s

Verify the MySQL Operator pod is running.

kubectl get all -n <NAMESPACE>

The output would be similar to:

NAME                                        READY   STATUS    RESTARTS   AGE
pod/vmware-mysql-operator-d8545b9c6-pwbxd   1/1     Running   0          20s

NAME                                   TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
service/vmware-mysql-webhook-service   ClusterIP   10.8.2.19    <none>        443/TCP   22s

NAME                                    READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/vmware-mysql-operator   1/1     1            1           22s

NAME                                              DESIRED   CURRENT   READY   AGE
replicaset.apps/vmware-mysql-operator-d8545b9c6   1         1         1       22s