This topic describes how to install the Tanzu MySQL Operator.

The primary method for installing Tanzu 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 Tanzu Postgres 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 Tanzu 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 v3 command-line tool installed. For more information, see Installing Helm from the Helm documentation.

    Note: Helm 3.7.0 is not supported. Use Helm 3.7.1 and above, or Helm 3.6 and earlier.

  • 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. Use the latest verion.

    To verify the cert manager installation run:

    kubectl get all --namespace=cert-manager
    

    For TLS security scenario setup, refer to Configuring TLS for MySQL Instances.

Access the Resources

You can access and install using two different methods:

Setup the Tanzu Operator via the Tanzu Network Registry

  1. Set the environment variable to enable OCI support in the Helm v3 client by running:

    export HELM_EXPERIMENTAL_OCI=1
    

    If you skip this step, the following error message might appear:

    Error: this feature has been marked as experimental and is not enabled by default.
    
  2. 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.

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

    If you're using Helm CLI 3.6 and earlier:

    helm chart pull registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/tanzu-mysql-operator-chart:1.5.0
    
    helm chart export registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/tanzu-mysql-operator-chart:1.5.0 --destination=/tmp/
    

    If you're using Helm CLI 3.7.1 and later:

    helm pull oci://registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/tanzu-mysql-operator-chart --version 1.5.0 --untar --untardir /tmp
    

Setup the Tanzu Operator via a Downloaded Archive File

IMPORTANT: Helm 3.7.0 is not supported. Use Helm 3.7.1 and above, or Helm 3.6 and earlier.

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

  2. Unpack the downloaded software:

    cd ~/Downloads
    tar xzf tanzu-mysql-for-kubernetes-<version>.tgz
    

    This command unpacks the distribution into a new directory named tanzu-mysql-for-kubernetes-<version>, for example tanzu-mysql-for-kubernetes-1.5.0.

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

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

    where is the release you selected.

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

    docker load -i ./images/tanzu-mysql-instance-8.0.26
    docker load -i ./images/tanzu-mysql-instance-8.0.27
    docker load -i ./images/tanzu-mysql-instance-8.0.28
    
  5. Load the MySQL Operator image to the Docker registry:

    docker load -i ./images/tanzu-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/tanzu-mysql-instance-8.0.26    1.5.0     110f35a9006d   2 weeks ago    842MB
       registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/tanzu-mysql-instance-8.0.27    1.5.0     b2767c434c61   2 weeks ago    907MB
       registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/tanzu-mysql-instance-8.0.28    1.5.0     3j2h83j93msl   2 weeks ago    917MB
       registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/tanzu-mysql-operator   	       1.5.0     8b46a4d26aa0   2 weeks ago    76.9MB
    
  7. Push the Tanzu 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}/tanzu-mysql-instance:$(cat ./images/tanzu-mysql-instance-8.0.26-tag)"
    docker tag $(cat ./images/tanzu-mysql-instance-8.0.26-id) ${INSTANCE_IMAGE_NAME}
    docker push ${INSTANCE_IMAGE_NAME}
    
    INSTANCE_IMAGE_NAME="${REGISTRY}/tanzu-mysql-instance:$(cat ./images/tanzu-mysql-instance-8.0.27-tag)"
    docker tag $(cat ./images/tanzu-mysql-instance-8.0.27-id) ${INSTANCE_IMAGE_NAME}
    docker push ${INSTANCE_IMAGE_NAME}
    
    INSTANCE_IMAGE_NAME="${REGISTRY}/tanzu-mysql-instance:$(cat ./images/tanzu-mysql-instance-8.0.28-tag)"
    docker tag $(cat ./images/tanzu-mysql-instance-8.0.28-id) ${INSTANCE_IMAGE_NAME}
    docker push ${INSTANCE_IMAGE_NAME}
    
    OPERATOR_IMAGE_NAME="${REGISTRY}/tanzu-mysql-operator:$(cat ./images/tanzu-mysql-operator-tag)"
    docker tag $(cat ./images/tanzu-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 tanzu-mysql-for-kubernetes-system
    

    where tanzu-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 Tanzu MySQL instances, and replace the Operator namespace tanzu-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 tanzu-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 tanzu-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 tanzu-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 tanzu-sql-with-mysql-operator.

  • If you setup the Tanzu Operator via Tanzu Network Registry, tanzu-sql-with-mysql-operator should be in the temporary CHART_DIR directory (created when you ran helm chart export...).

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

    cd tanzu-mysql-for-kubernetes-*/charts
    

    (or cd charts from within that unpacked archive file).

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

ls -F tanzu-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 Tanzu SQL 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/tanzu-mysql-operator:1.5.0
    registry: "registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/"
    resources: {}
    certManagerClusterIssuerName: ""
    
  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.

    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 Tanzu 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 Tanzu MySQL images.
    resources List Limits and requests for CPU and memory for the Tanzu 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).
  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

IMPORTANT: Helm 3.7.0 is not supported. Use Helm 3.7.1 and above, or Helm 3.6 and earlier.

  1. By default, the Tanzu 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/tanzu-sql-with-mysql-operator/ \
      --values=operator-values-overrides.yaml \
      --namespace=tanzu-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/tanzu-sql-with-mysql-operator/ is the location of the MySQL Operator helm chart
    • tanzu-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: tanzu-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=tanzu-mysql-for-kubernetes-system
    

    The output would be similar to:

    NAME                                       READY   STATUS    RESTARTS   AGE
    pod/tanzu-mysql-operator-d8545b9c6-pwbxd   1/1     Running   0          20s
    
    NAME                                  TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
    service/tanzu-mysql-webhook-service   ClusterIP   10.8.2.19    <none>        443/TCP   22s
    
    NAME                                   READY   UP-TO-DATE   AVAILABLE   AGE
    deployment.apps/tanzu-mysql-operator   1/1     1            1           22s
    
    NAME                                             DESIRED   CURRENT   READY   AGE
    replicaset.apps/tanzu-mysql-operator-d8545b9c6   1         1         1       22s
    

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

    kubectl logs -n tanzu-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

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.2.0). Each Tanzu MySQL release corresponds to a TDS package version. For instance, MySQL Operator version 1.5.0 is part of TDS version 1.2.0. Insert the right version for your Tanzu 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.2.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 Tanzu SQL with MySQL for Kubernetes     Kubernetes Operator for MySQL       1.5.0
  postgres-operator.sql.tanzu.vmware.com    VMware Tanzu SQL with Postgres for Kubernetes  Kubernetes Operator for PostgreSQL  1.8.0

Check the values for the MySQL Operator package:

tanzu package available get mysql-operator.with.sql.tanzu.vmware.com/1.5.0 --values-schema -n <NAMESPACE>
- Retrieving package details for mysql-operator.with.sql.tanzu.vmware.com/1.5.0...
  KEY                           DEFAULT                                                     TYPE    DESCRIPTION
  certManagerClusterIssuerName  tanzu-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

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:

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

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

    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 'tanzu-mysql-operator-carvel-sa'
    - Creating cluster admin role 'tanzu-mysql-operator-carvel-cluster-role'
    - Creating cluster role binding 'tanzu-mysql-operator-carvel-cluster-rolebinding'
    | Creating package resource
    | Waiting for 'PackageInstall' reconciliation for 'tanzu-mysql-operator'
    \ 'PackageInstall' resource install status: Reconciling
    
    
    Added installed package 'tanzu-mysql-operator'
    
  2. Verify PackageInstall has been created.

    tanzu package installed list -n <NAMESPACE>
    
    - Retrieving installed packages...
      NAME                  PACKAGE-NAME                              PACKAGE-VERSION  STATUS
      tanzu-mysql-operator  mysql-operator.with.sql.tanzu.vmware.com  1.5.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                          1         3d17h
    tanzu-mysql-operator             1         2m32s
    tanzu-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/tanzu-mysql-operator-d8545b9c6-pwbxd   1/1     Running   0          20s
    
    NAME                                  TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
    service/tanzu-mysql-webhook-service   ClusterIP   10.8.2.19    <none>        443/TCP   22s
    
    NAME                                   READY   UP-TO-DATE   AVAILABLE   AGE
    deployment.apps/tanzu-mysql-operator   1/1     1            1           22s
    
    NAME                                             DESIRED   CURRENT   READY   AGE
    replicaset.apps/tanzu-mysql-operator-d8545b9c6   1         1         1       22s
    
check-circle-line exclamation-circle-line close-line
Scroll to top icon