Installing the Tanzu SQL for Kubernetes Operator

This topic describes how Kubernetes admins install, configure, and deploy the Tanzu MySQL using two different methods.

Use Installing Tanzu MySQL Operator via Tanzu Network Registry for a faster installation process, and if your server hosts have access to the internet.
Use Installing Tanzu 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.

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.
IMPORTANT: Helm 3.7.x is currently not supported.
cluster-admin ClusterRole access to the Kubernetes cluster. For more information, see the Kubernetes documentation.

Cert Manager installed on the Kubernetes cluster.

Install cert-manager by running these commands from your local client:

kubectl create namespace cert-manager
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager --namespace cert-manager  --version <1.latest> --set installCRDs=true

where:

--namespace cert-manager is the namespace used for cert manager in the Kubernetes cluster
--version <1.latest> is the latest cert-manager version available (minimum above 1.0.2)
--set installCRDs=true ensures cert manager installs all types necessary to create certificates

To verify the installation run:

kubectl get all --namespace=cert-manager

The output should be similar to:

NAME                                           READY   STATUS    RESTARTS   AGE
pod/cert-manager-57b65b7fc-x8vjt               1/1     Running   5          4d19h
pod/cert-manager-cainjector-5f988f74c6-tgk25   1/1     Running   15         4d19h
pod/cert-manager-webhook-7cf554f879-b5ss9      1/1     Running   4          4d19h

NAME                           TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
service/cert-manager           ClusterIP   10.106.253.7    <none>        9402/TCP   4d19h
service/cert-manager-webhook   ClusterIP   10.108.17.113   <none>        443/TCP    4d19h

NAME                                      READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/cert-manager              1/1     1            1           4d19h
deployment.apps/cert-manager-cainjector   1/1     1            1           4d19h
deployment.apps/cert-manager-webhook      1/1     1            1           4d19h

NAME                                                 DESIRED   CURRENT   READY   AGE
replicaset.apps/cert-manager-57b65b7fc               1         1         1       4d19h
replicaset.apps/cert-manager-cainjector-5f988f74c6   1         1         1       4d19h
replicaset.apps/cert-manager-webhook-7cf554f879      1         1         1       4d19h

For security scenarios setup, see Configuring TLS for MySQL Instances.

Install the Operator via the Tanzu Network Registry

This section describes how to access the resources, and deploy the Tanzu MySQL Operator using the Tanzu Network Registry. To install the Tanzu MySQL Operator, you must use kubectl to create a namespace and secret. Then, use the Helm CLI to install the Operator.

IMPORTANT: Helm 3.7.x is currently not supported.

Access the Resources

To install the Tanzu MySQL Operator, you must download the Helm chart and images.

To download the resources:

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.
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 tanzu-mysql-operator-chart using Helm:

helm chart pull registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/tanzu-mysql-operator-chart:1.2.0
1.2.0: Pulling from registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/tanzu-mysql-operator-chart
ref:     <span style="color: #77bf00;">registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/tanzu-mysql-operator-chart:1.2.0</span>
digest:  2b6e1d010ab1737dcc5a426b223a06db1c616107d2ceaf368db6fda48d96a61a
size:    4.2 KiB
name:    tanzu-sql-with-mysql-operator
version: 1.2.0
Status: Downloaded newer chart for registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/tanzu-mysql-operator-chart:1.2.0

Create Namespace and Secret

To create the namespace and secret:

Create the namespace by running:

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

Set your kubectl context to the newly-created namespace by running:

kubectl config set-context --current --namespace tanzu-mysql-for-kubernetes-system

Create a Kubernetes secret for accessing registry containing the Tanzu MySQL images by running:

kubectl create secret docker-registry tanzu-image-registry --docker-server=https://registry.tanzu.vmware.com/ \
--docker-username=DOCKER-USERNAME --docker-password=DOCKER-PASSWORD

Download the Helm chart to your current working directory on your local machine by running:
```
helm chart export REGISTRY-URL
```
Where REGISTRY-URL is the reference to the Tanzu MySQL Helm chart.

The value of REGISTRY-URL has the following pattern:
```
registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/tanzu-mysql-operator-chart:VERSION-NUMBER-TAG
```
Where VERSION-NUMBER-TAG is the version of the Helm chart.

This downloads a directory named tanzu-sql-with-mysql-operator/ into your current working directory that contains:
- The Tanzu MySQL Helm chart
- Custom Resource Definitions (CRDs)
- Role-Based Access Control (RBAC) definitions required to install the operator with Helm
For example:
```
helm chart export registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/tanzu-mysql-operator-chart:1.2.0
<br>
ref:     registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/tanzu-mysql-operator-chart:1.2.0
digest:  2b6e1d010ab1737dcc5a426b223a06db1c616107d2ceaf368db6fda48d96a61a
size:    4.2 KiB
name:    tanzu-sql-with-mysql-operator
version: 1.2.0
Exported chart to tanzu-sql-with-mysql-operator/
```

Review values.yaml and Create Overrides If Needed

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

However, if any of the following are true, follow the steps described in Edit the Operator Configuration to override the defaults:

You deployed the Tanzu SQL for Kubernetes images from a registry other than registry.tanzu.vmware.com.
You did not use the default tanzu-image-registry for the secret name in Step 4 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.

Use Helm CLI to Install the Operator

IMPORTANT: Helm 3.7.x is currently not supported.

To install the Operator using the Helm CLI:

Verify that you are in the same working directory as where you downloaded the Helm chart in Step 4 of Create Namespace and Secret above.
By default, the Tanzu MySQL Operator 1.2.0 configures a self-signed 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.

If you do not require a custom CA, continue with the default installation. If you created a custom values-override.yaml in Review values.yaml and Create Overrides If Needed above, then run the following Helm command, including the --values flag with the location of your override file:
```
helm install --values=/your/values-override.yaml tanzu-sql-with-mysql-operator ./tanzu-sql-with-mysql-operator/
```
Otherwise, omit the --values flag:
```
helm install tanzu-sql-with-mysql-operator ./tanzu-sql-with-mysql-operator/
```

See that the Operator has installed successfully by running:

kubectl get all

The Tanzu MySQL Operator has finished installing when you see the value of the STATUS column for the Tanzu MySQL Operator Pod is Running. See example output:

kubectl get all

NAME                                                           READY   STATUS    RESTARTS   AGE
pod/mysql-for-kubernetes-controller-manager-84d76dfb77-lq5mb   1/1     Running   0          21s
NAME                                                      READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/mysql-for-kubernetes-controller-manager   1/1     1            1           23s
NAME                                                                 DESIRED   CURRENT   READY   AGE
replicaset.apps/mysql-for-kubernetes-controller-manager-84d76dfb77   1         1         1       23s

Note: You can only have one Tanzu MySQL operator installed in a Kubernetes cluster.

To review the default TLS configuration for the MySQL Operator, see Using the Default provided TLS.

Install the Operator via a Downloaded File

Choose this method if:

The installation destination (for example an air-gapped network) cannot access the VMware Tanzu Network.
Or you wish to load the Operator and instance images to a private Docker registry.

IMPORTANT: Helm 3.7.x is currently not supported.

This section covers:

Downloading and unpacking the distribution from VMware Tanzu Network
Loading the images to a local Docker registry
Pushing the images from the local Docker registry to a private container registry
Configuring a Kubernetes secret for accessing the private container registry
Deploying the MySQL Operator

Prerequisites

Before you deploy the Tanzu MySQL Operator, review the list of Prerequisites that apply to both installation methods.

Download and unpack the Tanzu MySQL distribution

Download the Tanzu MySQL distribution from VMware Tanzu Network. The download filename has the format: tanzu-mysql-for-kubernetes-<version>.tgz
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.2.0.
Change to the new tanzu-mysql-for-kubernetes-<version> directory.
```
cd ./tanzu-mysql-for-kubernetes-1.2.0
```

Load the Images to a Local Docker Registry

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

Verify that the two Docker images are now available.

docker images

REPOSITORY                                                                  TAG       IMAGE ID       CREATED        SIZE
registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/tanzu-mysql-instance   1.2.0     5f0ad7bad51b   5 weeks ago    792MB
registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/tanzu-mysql-operator   1.2.0     eb1458d2e1bd   5 weeks ago    76MB

Push the Images to a Private Container Registry

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-tag)"
docker tag $(cat ./images/tanzu-mysql-instance-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}

Configure a Kubernetes Secret for Accessing the Private Container Registry

Create a docker-registry type secret to allow the Kubernetes cluster to authenticate with the private container registry so it can pull images. These examples create a secret named tanzu-image-registry using Harbor, Google Cloud Registry (GCR), and Amazon Elastic Container Registry (ECR).

Important: The commands below create the secret in the current configured namespace for the kubectl context. Only pods created in the same namespace can reference the secret. To create a secret in a different namespace, use the `--namespace` flag. You should create an identical secret in the Operator namespace and in each namespace where you will create Tanzu MySQL instances.

Harbor

kubectl create secret docker-registry tanzu-image-registry \
    --docker-server=${HARBOR_URL} \
    --docker-username=${HARBOR_USER} \
    --docker-password="${HARBOR_PASSWORD}"

GCR

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

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

ECR

TOKEN=`aws ecr --region=$REGION get-authorization-token --output text --query authorizationData[].authorizationToken | base64 -d | cut -d: -f2`
kubectl create secret docker-registry tanzu-image-registry \
    --docker-server=https://${ACCOUNT}.dkr.ecr.${REGION}.amazonaws.com \
    --docker-username=AWS \
    --docker-password="${TOKEN}"

Next follow Deploying a MySQL Operator. The MySQL Operator will use this secret to allow the Kubernetes cluster to authenticate with the container registry to pull images.

Deploy the Tanzu MySQL Operator

The MySQL Operator is the controller for MySQL instances resources. You install the MySQL Operator using the Helm package manager.

Edit the Operator Configuration

Go to the directory where you unpacked the Tanzu MySQL distribution.

cd tanzu-mysql-for-kubernetes-*

The file charts/tanzu-sql-with-mysql-operator/values.yaml in the Tanzu MySQL directory 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.2.0
registry: "registry.tanzu.vmware.com/tanzu-mysql-for-kubernetes/"
defaultInstanceVersion: 1.2.0
resources: {}

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 secret. This value must match the name of the Kubernetes secret you create in Create Namespace and Secret above.
`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.
`defaultInstanceVersion`	String	The default version of Tanzu MySQL to use when creating new instances.
`resources`	List	Limits and requests for CPU and memory for the Tanzu MySQL Operator. You can change these values to scale your resources.

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.

Create the MySQL Operator

IMPORTANT: Helm 3.7.x is currently not supported.

By default, the Tanzu MySQL Operator 1.2.0 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.

To continue with the default installation, use Helm to install the MySQL Operator in your Kubernetes cluster:
```
helm install --wait my-mysql-operator Operator/
```
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
- operator/ is the location of the MySQL Operator helm chart
or
```
helm install --wait my-mysql-operator -f charts/tanzu-sql-with-mysql-operator/operator-values-overrides.yaml charts/tanzu-sql-with-mysql-operator/
```
Replace charts/tanzu-sql-with-mysql-operator/operator-values-overrides.yaml with your custom location.

To create the Operator in a namespace different that the default, use:
```
helm install --wait my-mysql-operator charts/tanzu-sql-with-mysql-operator/ \
  --values=operator-values-overrides.yaml \
  --namespace=mysql-for-kubernetes-system \
  --create-namespace
```
The command displays a message similar to:
```
NAME: my-mysql-operator
LAST DEPLOYED: Wed Jun 16 13:28:05 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
```
Note: The secret namespace in step Create a Kubernetes Access Secret must match the Operator namespace.

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

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

kubectl logs -l app=tanzu-mysql-operator

Use the label app=tanzu-mysql-operator to search across resources created by the MySQL Operator Helm chart:

kubectl get all -l app=tanzu-mysql-operator -n mysql-for-kubernetes-system

where -n mysql-for-kubernetes-system defines the namespace. The output would be similar to:

NAME                                             READY       STATUS           RESTARTS      AGE
pod/tanzu-mysql-operator-69765b8b74-rtms7        1/1         Running          0             3d19h
NAME                                             READY       UP-TO-DATE       AVAILABLE     AGE
deployment.apps/tanzu-mysql-operator             1/1         1                1             3d19h
NAME                                             DESIRED     CURRENT          READY         AGE
replicaset.apps/tanzu-mysql-operator-69765b8b74  1           1                1             3d19h