Tungsten Operator

Installing Tungsten Cluster

Installation of the cluster is done via the kubectl command, passing in yaml files that pre-define the cluster configuration.

The following sections outline the sample files provided and how to customise them to suit your requirements.

Working with the YAML files

The first step is to build the yaml files, and to make this simple we provide a number of example files that can be used and adjusted to suit your requirements.

The files are located within the examples directory of the extracted operator package, for example:

shell> cd /opt/continuent/software/tungsten-operator-8.0.0-27/examples

The following table lists the available template files and what each one can be used for:

Option	Description
`mysql-init-script.yaml`	A ConfigMap used to initialize the database. This file can contain SQL statements that will be executed during installation.
`mysql-passwords.yaml`	Used to specify user account passwords, if not used then paswords will be auto-generated.
`tungsten_v1alpha1_backup.yaml`	Used as an example to create a backup. This is an operational task, not installation.
`tungsten_v1alpha1_backupconfiguration.yaml`	Examples to use to configure the backup endpoints - S3, Folder etc.
`tungsten_v1alpha1_mysqlcluster_caa_with_init.yaml`	Example deployment for a 6-node Composite Active/Active cluster that also calls the `mysql-init-script.yaml`.
`tungsten_v1alpha1_mysqlcluster_caa.yaml`	Example deployment for a 6-node Composite Active/Active cluster.
`tungsten_v1alpha1_mysqlcluster_cap_with_affinity.yaml`	Example deployment for a 6-node Composite Active/Passive cluster that set Kubernetes node affinity.
`tungsten_v1alpha1_mysqlcluster_cap_with_init.yaml`	Example deployment for a 6-node Composite Active/Passive cluster that also calls the `mysql-init-script.yaml`.
`tungsten_v1alpha1_mysqlcluster_cap.yaml`	Example deployment for a 6-node Composite Active/Passive cluster.
`tungsten_v1alpha1_mysqlcluster_from_backup.yaml`	Example deployment for a 3-node cluster using a specified backup to provision from first.
`tungsten_v1alpha1_mysqlcluster_with_backup.yaml`	Example deployment for a 3-node cluster that will also schedule backups at a specific schedule.
`tungsten_v1alpha1_mysqlcluster_with_init.yaml`	Example deployment for a 3-node cluster that also calls the `mysql-init-script.yaml`.
`tungsten_v1alpha1_mysqlcluster.yaml`	Example deployment for a 3-node cluster.
`tungsten_v1alpha1_opsrequest_reset_node.yaml`	Used as an example to restore a backup. This is an operational task, not installation.
`tungsten_v1alpha1_opsrequest_reset_replicator.yaml`	Used as an example to reset the replicator. This is an operational task, not installation.

important

Example YAML files are provided to deploy Composite Active/Active and Composite Active/Passive clusters, however at this time it is not possible to deploy these topologies across regions.

Depending on the use-case, you may choose to employ one or more of the sample YAML files, additionally you may wish to create one single YAML file that combines more than one of the above samples together. Whilst this is supported, it is not recommended as this may result in large files that may become difficult to manage.

An example of some of the use-cases that can be achieved using combined YAML files is shown below. This is not an exhaustive list of all possibilities, but are provided as examples of the kind of combinations you can leverage.

To install a cluster, with auto-generated passwords:
- One of tungsten_v1alpha1_mysqlcluster.yaml, tungsten_v1alpha1_mysqlcluster_cap.yaml or tungsten_v1alpha1_mysqlcluster_caa.yaml
To install a cluster, defining your own custom passwords:
- mysql-passwords.yaml
- One of tungsten_v1alpha1_mysqlcluster.yaml, tungsten_v1alpha1_mysqlcluster_cap.yaml or tungsten_v1alpha1_mysqlcluster_caa.yaml
To install a cluster, defining your own custom passwords, and manually take your own backups:
- mysql-passwords.yaml
- tungsten_v1alpha1_backupconfiguration.yaml
- One of tungsten_v1alpha1_mysqlcluster.yaml, tungsten_v1alpha1_mysqlcluster_cap.yaml or tungsten_v1alpha1_mysqlcluster_caa.yaml
To install a cluster, defining your own custom passwords, and configure automated backups:
- mysql-passwords.yaml
- tungsten_v1alpha1_backupconfiguration.yaml
- tungsten_v1alpha1_backup.yaml
- One of tungsten_v1alpha1_tmysqlcluster.yaml, tungsten_v1alpha1_mysqlcluster_cap.yaml or tungsten_v1alpha1_mysqlcluster_caa.yaml
To install a cluster, defining your own custom passwords, and provisioning from an existing backup:
- mysql-passwords.yaml
- tungsten_v1alpha1_backupconfiguration.yaml
- tungsten_v1alpha1_mysqlcluster_from_backup.yaml

Configuring Custom Passwords

The operator, by default, generates the MySQL root password, along with the passwords for the replicator and application user during the creation of the cluster.

You have the option to provide custom passwords using a pre-existing Kubernetes secret during cluster creation, using the following example as a guide.

You can use the provided mysql-passwords.yaml file as a template. Either edit directly or make a copy to a directory of your choice. You can then edit it, changing the passwords to suit.

An example is shown below:

apiVersion: v1
kind: Secret
metadata:
 name: tungsten-passwords-sample-secret
type: Opaque
stringData:
 mysqlRootPassword: rootsecret
 applicationPassword: appsecret
 replicatorPassword: replicatorsecret
 restApiAdminPassword: apisecret

In the above example, apiVersion, kind and type should be left untouched. The passwords within the stringData block can be changed to suit, along with the name in the metadata block.

This name can be used if you have multiple clusters and different password yaml files with different passwords for each cluster. You could then change the name to help identify which cluster the passwords are associated with. The value you set here should then be used within the customPasswordSecret property in the cluster yaml file.

For more details on the cluster yaml files, see "Configuring Custom Cluster YAML templates."

To then apply this configuration, issue:

shell> kubectl apply -f mysql-passwords.yaml

warning

Changing the passwords after cluster creation is not supported or tested. If passwords need to be changed, they can be first changed in the secret, and manually changed in the MySQL database.

Configuring Custom Cluster YAML templates

To configure the cluster, it is recommended to first select the example YAML file that matches the topology you wish the deploy, and then customize the content to match your needs.

A full list of all the sample files available is outlined in "Working with the YAML files"

You can either edit the sample file directly or copy it and rename it to a different location. A number of options can be edited, and these are all explained below. Additionally, you can create your own if you wish but it is strongly recommended to take a sample file as the template to ensure you do not miss out any key entries.

Each YAML file has a number of key/value blocks depending on the complexity of the chosen deployment topology. The following is a complete example of the tungsten_v1alpha1_mysqlcluster.yaml, the sections that follow explain each individual component of the file and how it can be changed to suit your needs.

apiVersion: tungsten.continuent.com/v1alpha1
kind: MySQLCluster
metadata:
 labels:
  app.kubernetes.io/name: mysqlcluster
  app.kubernetes.io/instance: sample
  app.kubernetes.io/part-of: tungsten-operator
  app.kubernetes.io/managed-by: kustomize
  app.kubernetes.io/created-by: tungsten-operator
 name: sample
spec:
 configuration:
  customPasswordSecret: tungsten-passwords-sample-secret
  enablePodDisruptionBudget: true
 monitoring:
  enabled: false
 dataServices:
 - name: alpha
  topology: clustered
  size: 3
 connector:
  replicas: 2
  podTemplate:
   spec:
    containers:
    - name: connector
     resources:
      requests:
       cpu: 1
       memory: 512Mi
      limits:
       memory: 512Mi
  # Uncomment to expose via external load balancer
  #serviceTemplate:
  # spec:
  #  externalTrafficPolicy: Local
  #  type: LoadBalancer
 podTemplate:
  spec:
   containers:
   - name: mysql
    resources:
     requests:
      cpu: 1
      memory: 2Gi
     limits:
      memory: 2Gi
   - name: manager
    resources:
     requests:
      cpu: 100m
      memory: 512Mi
     limits:
      memory: 512Mi
   - name: replicator
    resources:
     requests:
      cpu: 1
      memory: 2Gi
     limits:
      memory: 2Gi
 volumeClaimTemplates:
 - metadata:
   name: mysql-data
  spec:
   accessModes: [ "ReadWriteOnce" ]
   resources:
    requests:
     storage: 40Gi
 - metadata:
   name: thl
  spec:
   accessModes: [ "ReadWriteOnce" ]
   resources:
    requests:
     storage: 20Gi
 - metadata:
   name: state
  spec:
   accessModes: [ "ReadWriteOnce" ]
   resources:
    requests:
     storage: 100Mi

apiVersion and kind

At the top of every file, there will be apiVersion and kind. These values should be left as they are, and look like the following:

apiVersion: tungsten.continuent.com/v1alpha1
kind: MySQLCluster 

metadata

The metadata section must also always be included with all values left as per the template, with the exception of app.kubernetes.io/instance and name. These values can be changed but must be set to the same value for each. An example of this section is as follows:

metadata:
 labels:
  app.kubernetes.io/name: mysqlcluster
  app.kubernetes.io/instance: sample
  app.kubernetes.io/part-of: tungsten-operator
  app.kubernetes.io/managed-by: kustomize
  app.kubernetes.io/created-by: tungsten-operator
 name: sample 

spec: configuration

Within this section, you specify the password configuration to associate with this cluster if you are setting custom passwords. The value for customPasswordSecret should be the same as the value of name within the mysql-passwords.yaml, or the file you are using for the password secrets.

An example of this section is as follows:

spec:
 configuration:
  customPasswordSecret: tungsten-passwords-sample-secret
  enablePodDisruptionBudget: true

spec: monitoring

Monitoring can be enabled by specifying true, or disabled by specifying false.

Setting this value to true will enable the various Prometheus exporters that will provide metrics that can be used with, for example, Graphana or other monitoring tools.

 monitoring:
  enabled: false

spec: dataServices

The dataServices section allows you to configure the desired topology and the cluster data service names. There are 3 different layouts for this section depending on the topology required, for example a standard cluster, a Composite Active/Passive cluster or a Composite Active/Active cluster. They all follow the same basic pattern.

The name is used for the corresponding dataservice. This must only be alphanumeric characters along with - or _ and is not case-sensitive. For Composite Active/Passive and Composite Active/Active topologies, each cluster must be given a different name.

topology is used to specify the topology of the cluster. The accepted values are as follows:

clustered: This should be used to define a standard cluster. It should also be used to define the individual clusters within a composite cluster. See examples below.
composite-active-passive: This should be used to define the top level cluster within a Composite Active/Passive cluster. clustered should then be used to define the clusters within.
composite-active-active: This should be used to define the top level cluster within a Composite Active/Active cluster. clustered should then be used to define the clusters within.

sources is used in composite clusters only. Within the top level composite cluster it defines the names of the clusters within. For a Composite Active/Passive cluster it should also be defined within the passive cluster to define the source cluster.

sizes is used to specify the number of nodes within the cluster. This must be an odd number per cluster to conform to quorum.

Examples:

A standard 3-node cluster called alpha:

 dataServices:
 - name: alpha
  topology: clustered
  size: 3

A Composite Active/Passive cluster with a composite cluster called global comprising of an active cluster of 3 nodes called east and a passive cluster of 3 nodes called west:

 dataServices:
 - name: global
  topology: composite-active-passive
  sources:
  - east
  - west
 - name: east
  topology: clustered
  size: 3
 - name: west
  topology: clustered
  sources:
  - east
  size: 3

A Composite Active/Active cluster with a composite cluster called global comprising of 2 x 3-node clusters called north and south:

 dataServices:
 - name: global
  topology: composite-active-active
  sources:
  - north
  - south
 - name: north
  topology: clustered
  size: 3
 - name: south
  topology: clustered
  size: 3

spec: connector

The connector section allows you to define the number of connectors to launch using the replicas option. For Composite Active/Passive and Composite Active/Active topologies this number is per cluster, so in the above examples where we define 2 clusters, setting replicas to 2 would result in a total of 4 connectors.

Additionally, within the containers block you can specify the number of CPU's and memory allocation per connector. The default values in the template are generally sufficient for the majority of workloads and shouldn't require changing.

An example of the connector block is as follows:

 connector:
  replicas: 2
  podTemplate:
   spec:
    containers:
    - name: connector
     resources:
      requests:
       cpu: 1
       memory: 512Mi
      limits:
       memory: 512Mi

spec: podTemplate

The podTemplate section allows for configuration of the MySQL, Tungsten Manager and Tungsten Replicator containers, allowing you to specify appropriate Memory and CPU properties. The name values shouldn't be changed. The MySQL limits should be adjusted based on your expected workload in line with your MySQL usage. The Tungsten Manager and Tungsten Replicator default values are generally sufficient for the majority of workloads and shouldn't require changing.

An example of this block is as follows:

 podTemplate:
  spec:
   containers:
   - name: mysql
    resources:
     requests:
      cpu: 1
      memory: 2Gi
     limits:
      memory: 2Gi
   - name: manager
    resources:
     requests:
      cpu: 100m
      memory: 512Mi
     limits:
      memory: 512Mi
   - name: replicator
    resources:
     requests:
      cpu: 1
      memory: 2Gi
     limits:
      memory: 2Gi

spec: volumeClaimTemplates

The volumeClaimTemplates section allows you to adjust the storage allocated. The only values that should be changed here are the storage values, adjusting to suit the expected usage for the MySQL databases and THL files. For THL allocation you should calculate this storage based on roughly 1.5-2 times the size of the binary logs generated within the retention period set (Default 10 days)

An example of this block is as follows:

 volumeClaimTemplates:
 - metadata:
   name: mysql-data
  spec:
   accessModes: [ "ReadWriteOnce" ]
   resources:
    requests:
     storage: 40Gi
 - metadata:
   name: thl
  spec:
   accessModes: [ "ReadWriteOnce" ]
   resources:
    requests:
     storage: 20Gi
 - metadata:
   name: state
  spec:
   accessModes: [ "ReadWriteOnce" ]
   resources:
    requests:
     storage: 100Mi

Configuring Custom tungsten.ini properties

If you are familiar with Tungsten Clustering, you will know that there are many properties that can be set via the /etc/tungsten/tungsten.ini file which will influence the behavior of the cluster. You have the option to include these custom properties by including the name/value key pairs within the yaml file.

You will need to include a section with the keyword customTungstenIniProperties under which you add the appropriate name and value. The location of this property will influence where within the /etc/tungsten/tungsten.ini the property is included.

For it to be part of the [defaults] and apply to all clusters, you should add this within configuration. For the values to apply only to a specific cluster, you should include this within the relevant cluster section under dataServices section.

The example below shows values included in both of these sections:

...
spec:
 configuration:
  customPasswordSecret: custom-tungsten-passwords-sample
  customTungstenIniProperties:
   - name: connector-bridge-mode
    value: "true"
   - name: repl-buffer-size
    value: "10"
 dataServices:
 - name: composite
  topology: composite-active-passive
  sources:
  - east
  - west
 - name: east
  topology: clustered
  size: 3
  customTungstenIniProperties:
   - name: connector-disconnect-timeout
    value: "10"
   - name: property=manager.prometheus.exporter.enabled
    value: "true"
...

For a full list of valid properties, their behavior and options, consult "tpm Configuration Options".

Installing the cluster using kubectl

When you have prepared the yaml files to suit your needs, you install the cluster using the kubectl apply command. The following example sets custom passwords using the mysql-passwords.yaml file and then creates a 3-node cluster using the tungsten_v1alpha1_mysqlcluster.yaml file:

shell> kubectl apply -f examples/mysql-passwords.yaml
shell> kubectl apply -f examples/tungsten_v1alpha1_mysqlcluster.yaml

Working with the YAML files​

Configuring Custom Passwords​

Configuring Custom Cluster YAML templates​

apiVersion and kind​

metadata​

spec: configuration​

spec: monitoring​

spec: dataServices​

spec: connector​

spec: podTemplate​

spec: volumeClaimTemplates​

Configuring Custom tungsten.ini properties​

Installing the cluster using kubectl​