Installing the Tanzu SQL for Kubernetes Operator

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

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:

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

  1. Create the namespace by running:

    kubectl create namespace tanzu-mysql-for-kubernetes-system
    
  2. Set your kubectl context to the newly-created namespace by running:

    kubectl config set-context --current --namespace tanzu-mysql-for-kubernetes-system
    
  3. 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
    
  4. 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
    
    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:

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

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

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

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

  1. Load the MySQL instance image to the Docker registry.

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

    docker load -i ./images/tanzu-mysql-operator
    
  3. 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

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

  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.

Create the MySQL Operator

IMPORTANT: Helm 3.7.x is currently not supported.

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

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