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.
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.
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.
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.7.1 --untar --untardir /tmp
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.7.1
.
Change to the new mysql-for-kubernetes-<version>
directory. For example:
cd ./mysql-for-kubernetes-<version>
where
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
Load the MySQL Operator image to the Docker registry:
docker load -i ./images/mysql-operator
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
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}
Create the Operator namespace:
kubectl create namespace vmware-mysql-for-kubernetes-system
where vmware-mysql-for-kubernetes-system
is an example namespace.
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.
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:
tanzu-image-registry
in Create Operator Namespace and Secrets above.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.7.1
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
.
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.
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 startsmy-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 chartvmware-mysql-for-kubernetes-system
is the Operator namespace you created in Create Operator Namespace and Secretsoperator-values-overrides.yaml
is the overrides file with your custom values, as per Review the Operator ValuesThe 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 overrides 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 --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
Clean up the temporary directory if you no longer need the exported chart:
rm -rf ${CHART_DIR}
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:
Log in to your image registry by running:
docker login <MY-REGISTRY>
where:
MY-REGISTRY
is your own image registryLog in to the VMware Tanzu Network registry with your VMware Tanzu Network credentials by running:
docker login registry.tanzu.vmware.com
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 registryTARGET-REPOSITORY
is your target repositoryTDS-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.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 createdMY-REGISTRY
is your own image registryMY-REGISTRY-USERNAME
is the username for your own container registryMY-REGISTRY-PASSWORD
is the password for your own container registryAdd 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 registryTARGET-REPOSITORY
is your target repositoryTDS-VERSION
is the tag for the image bundle (e.g. 1.4.0
)NAMESPACE
is the namespace where the Package and PackageInstall will be createdList 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 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 addedThe 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'
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
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