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

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

2. 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.7.1 --untar --untardir /tmp
   

Setup the VMware MySQL Operator via a Downloaded Archive File

1. Download the VMware MySQL Operator distribution from VMware Tanzu Network. The download filename has the format: mysql-for-kubernetes-<version>.tgz.

2. 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.7.1.

3. Change to the new mysql-for-kubernetes-<version> directory. For example:

   cd ./mysql-for-kubernetes-<version>
   

   where is the release you selected.

4. Load the MySQL instance images to the Docker registry:

   docker load -i ./images/mysql-instance-8.0.27
   docker load -i ./images/mysql-instance-8.0.28
   docker load -i ./images/mysql-instance-8.0.29
   docker load -i ./images/mysql-instance-8.0.31
   

5. Load the MySQL Operator image to the Docker registry:

   docker load -i ./images/mysql-operator
   

6. Verify that the four Docker images are now available.

   docker images
   

      REPOSITORY                                                                  	 TAG       IMAGE ID       CREATED        SIZE
      registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/mysql-instance-8.0.27    1.7.0     b2767c434c61   2 weeks ago    907MB
      registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/mysql-instance-8.0.28    1.7.0     3j2h83j93msl   2 weeks ago    917MB
      registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/mysql-instance-8.0.29    1.7.0     19j38fj20xk3   2 weeks ago    902MB
      registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/mysql-instance-8.0.31    1.7.0     a5cb44250541   2 weeks ago    902MB
      registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/mysql-operator           1.7.0     8b46a4d26aa0   2 weeks ago    76.9MB
   

7. 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.27-tag)"
   docker tag $(cat ./images/mysql-instance-8.0.27-id) ${INSTANCE_IMAGE_NAME}
   docker push ${INSTANCE_IMAGE_NAME}
   
   INSTANCE_IMAGE_NAME="${REGISTRY}/mysql-instance:$(cat ./images/mysql-instance-8.0.28-tag)"
   docker tag $(cat ./images/mysql-instance-8.0.28-id) ${INSTANCE_IMAGE_NAME}
   docker push ${INSTANCE_IMAGE_NAME}
   
   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}
   
   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

1. Create the Operator namespace:

   kubectl create namespace vmware-mysql-for-kubernetes-system
   

   where vmware-mysql-for-kubernetes-system is an example namespace.

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

   These examples create a secret named tanzu-image-registry using Tanzu Registry, Harbor, or GCR.

   Tanzu Registry

   
   kubectl create secret docker-registry tanzu-image-registry \
       --docker-server=https://registry.tanzu.vmware.com/ \
       --docker-username="${DOCKER_USERNAME}" \
       --docker-password="${DOCKER_PASSWORD}" \
       --namespace=vmware-mysql-for-kubernetes-system
   

   Harbor

   kubectl create secret docker-registry tanzu-image-registry \
       --docker-server=${HARBOR_URL} \
       --docker-username=${HARBOR_USER} \
       --docker-password="${HARBOR_PASSWORD}" \
       --namespace=vmware-mysql-for-kubernetes-system
   

   GCR

   kubectl create secret docker-registry tanzu-image-registry \
       --docker-server=https://gcr.io \
       --docker-username=_json_key \
       --docker-password="$(cat ~/key.json)" \
       --namespace=vmware-mysql-for-kubernetes-system
   

   For GKE information on how to obtain the key.json service account file, refer to Creating service account credentials in the GKE documentation.

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 temporary CHART_DIR directory (created when you ran helm chart export...).

• If you setup the VMware MySQL Operator via a downloaded archive file, go to the directory of helm charts within the unpacked the archive file:

  cd vmware-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 it 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 deployed the VMware SQL with MySQL for Kubernetes images from a registry other than registry.tanzu.vmware.com.
• You named your registry secret something other than the default tanzu-image-registry in Create Operator Namespace and Secrets above.
• You want to allocate different CPU or memory resources for your Operator.
• You want to specify an alternate default version for new MySQL instances.

Create an Operator Values Override file:

1. 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.7.1
   registry: "registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/"
   resources: {}
   certManagerClusterIssuerName: ""
   enableSecurityContext: true
   

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

3. Edit the values that you want to change.

4. Delete the sections of the file that you do not change.

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

1. 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:

   helm install --wait my-mysql-operator /tmp/vmware-sql-with-mysql-operator/ \
     --values=operator-values-overrides.yaml \
     --namespace=vmware-mysql-for-kubernetes-system \
     --create-namespace
   

   where:

   • --wait flag waits for the Operator deployment to complete before any image installation starts
   • my-mysql-operator is the custom name you provide for your MySQL Operator
   • /tmp/vmware-sql-with-mysql-operator/ is the location of the MySQL Operator helm chart
   • vmware-mysql-for-kubernetes-system is the Operator namespace you created in Create Operator Namespace and Secrets
   • operator-values-overrides.yaml is the overrides file with your custom values, as per Review the Operator Values

   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.

2. 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 overrides file or with the --reset-values flag. For more details on Helm upgrades, see Helm Upgrade in the Helm documentation.

3. 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 --namespace=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 vmware-mysql-for-kubernetes-system -l app.kubernetes.io/name=tanzu-sql-with-mysql-operator
   

4. Clean up the temporary directory if you no longer need the exported chart:

    rm -rf ${CHART_DIR}
   

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 Accepting Tanzu Application Platform EULAs, installing Cluster Essentials and the Tanzu CLI in the TAP documentation.
• Cert Manager installed on the Kubernetes cluster.

Relocate Images to a Private Registry

Relocate the images from VMware Tanzu Network registry to a private registry before attempting the installation. 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:

1. Log in to your image registry by running:

   docker login <MY-REGISTRY>
   

   where:

   • MY-REGISTRY is your own image registry

2. Log in to the VMware Tanzu Network registry with your VMware Tanzu Network credentials by running:

   docker login registry.tanzu.vmware.com
   

3. Relocate the images with the Carvel tool imgpkg by running:

   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.7.1). Each VMware MySQL Operator release corresponds to a TDS package version. For instance, MySQL Operator version 1.7.1 is part of TDS version 1.7.1. Insert the right version for your VMware MySQL Operator release.

Create a Kubernetes Secret

Verify the existing secrets in your environment:

tanzu secret registry list

The output would be 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
• MY-REGISTRY-USERNAME is the username for your own container registry
• MY-REGISTRY-PASSWORD is the password for your own container registry

Add the Package Repository

Add the package repository for VMware Tanzu Data Services:

tanzu package repository add tanzu-data-services-repository \
     --url <MY-REGISTRY>/<TARGET-REPOSITORY>/tds-packages:<TDS-VERSION> 
     --n <NAMESPACE> --create-namespace

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.4.0)
• NAMESPACE is the namespace where the Package and PackageInstall will be created

List the latest packages to confirm the addition:

tanzu package available list -n <NAMESPACE>

- Retrieving available packages...
  NAME                                      DISPLAY-NAME                             SHORT-DESCRIPTION                   LATEST-VERSION
  mysql-operator.with.sql.tanzu.vmware.com  VMware SQL with MySQL for Kubernetes     Kubernetes Operator for MySQL       1.7.1
  postgres-operator.sql.tanzu.vmware.com    VMware SQL with Postgres for Kubernetes  Kubernetes Operator for PostgreSQL  2.0.0

Check the values for the MySQL Operator package:

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

- Retrieving package details for mysql-operator.with.sql.tanzu.vmware.com/1.7.1...
  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
  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                     map[]                                                        object  Specifies the resource requests and limits for the operator pod
  enableSecurityContext         true                                                         object  EnableSecurityContext sets the security context for the operator and its managed instances, typically disabled on OpenShift

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

1. Install the operator package.

   Install the MySQL operator package, using the overrides file you created:

   tanzu package install <PACKAGE-NAME> --package-name mysql-operator.with.sql.tanzu.vmware.com --version 1.7.1 -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

   The output is similar to:

   \ Installing package 'mysql-operator.with.sql.tanzu.vmware.com'
   - Getting package metadata for 'mysql-operator.with.sql.tanzu.vmware.com'
   - Creating service account 'vmware-mysql-operator-carvel-sa'
   - Creating cluster admin role 'vmware-mysql-operator-carvel-cluster-role'
   - Creating cluster role binding 'vmware-mysql-operator-carvel-cluster-rolebinding'
   | Creating package resource
   | Waiting for 'PackageInstall' reconciliation for 'vmware-mysql-operator'
   \ 'PackageInstall' resource install status: Reconciling
   
   
   Added installed package 'vmware-mysql-operator'
   

2. Verify PackageInstall has been created.

   tanzu package installed list -n <NAMESPACE>
   

   - Retrieving installed packages...
     NAME                   PACKAGE-NAME                              PACKAGE-VERSION  STATUS
     vmware-mysql-operator  mysql-operator.with.sql.tanzu.vmware.com  1.7.1            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                           1         3d17h
   vmware-mysql-operator             1         2m32s
   vmware-mysql-operator-carvel-sa   1         2m39s
   

3. 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 <NAMESPACE>
   

   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