Skip to main content
Tungsten Clustering

Deploying a Connector through Docker

Version availability

Available in 7.0.3 and later.

Providing you have a license to use Tungsten Clustering, you will be able to download the docker image from the download portal of the Continuent Website.

The image is available as a gzipped tar ball, and the following steps outline how to import and use the image

Step 1 : Download the files and load into Docker​

Download the correct file for your environment architecture, for example amd64 or arm64, and then extract the tar ball, and load into docker, for example:

shell> tar xvzf tungsten-connector-docker-${VERSION}-${ARCH}.tar.gz
shell> cd tungsten-connector-docker-${VERSION}
shell> docker load --input tungsten-connector-${VERSION}-${ARCH}.tar
shell> docker images

where:

  • VERSION = Tungsten Connector version with build number like 8.0.4-132
  • ARCH = [amd64 | arm64 ]

Step 2 : Configure the Connector​

Before launching the connector, you will need to apply a number of configuration changes so that the Connector can communicate with your cluster and act in the desired mode based on your needs.

The compose.yaml file

The following changes to compose.yaml are required:

  • Modify the container_name: variable.

    This defines the Connector name shown in the docker ps command.

  • Modify the hostname: variable.

    This defines the Connector hostname shown in the ls command.

  • Modify the extra_hosts: variable.

    Uncomment this section and add the proper values if the Manager's database server host names can't be resolved from the Connector container docker instance. Doing so will cause the values you add as a mapping to appear correctly as lines in the /etc/hosts file for the Connector container instance.

  • If enabling SSL security, uncomment the SSL lines in compose.yaml, edit conf/tungsten.ini, and follow the instructions under security/README.md.

  • If configuring Proxy Mode, uncomment the user.map line in compose.yaml.

  • If a Read-Only port or the Advanced Listeners functionality is needed:

    • Uncomment the - ./conf/listeners.json line in compose.yaml.

    • Modify conf/listeners.json to meet your needs.

Provided sample compose.yaml:

services:
connector:
  image: "${IMAGE_NAME}:${IMAGE_VERSION}"
  container_name: connector-alpha
  hostname: connector-host-alpha
  ports:
    # connector listen port RW
    - 3306:3306
    # connector listen port RO
    - 3307:3307
    # Prometheus exporter
    - 8093:8093
    # connector REST API listen port
    - 8096:8096
  # The below extra_hosts: section is a colon-separated list of hostnames and IPs
  # that will be added to the running container's /etc/hosts file
  # extra_hosts:
  #   - "db1:192.168.30.81"
  #   - "db2:192.168.30.82"
  #   - "db3:192.168.30.83"
  volumes:
    - ./conf/tungsten.ini:/etc/tungsten/tungsten.ini
    # If connector-bridge-mode=false in tungsten.ini,
    #  the INI-defined application-user={user} will be the only available user.
    # Additional users can be defined in a "user.map" file (uncomment this line to get it copied over)
    # - ./conf/user.map:/opt/continuent/tungsten/tungsten-connector/conf/user.map
    # For Read-Only port or advanced port-based settings, adjust listeners.json and uncomment the following line
    # - ./conf/listeners.json:/opt/continuent/tungsten/tungsten-connector/conf/listeners.json
    # If SSL is configured the following two lines are needed, please uncomment it
    # - ./conf/security.properties:/opt/continuent/tungsten/cluster-home/conf/security.properties
    # - ./security:/opt/continuent/share
  restart: unless-stopped

The conf/tungsten.ini File

Modify the conf/tungsten.ini file to match your needs:

Provided sample conf/tungsten.ini:

[defaults]
application-user=app_user
application-password=secret

# Do not touch! It should be 3306. The mapping is done in compose.yaml
application-port=3306

# This should be 2048 or higher, normally should not be touched.
conn-java-mem-size=2048

# If security is enabled in compose.yaml change the value to 'false'
disable-security-controls=true

# If security is enabled in compose.yaml change the value to 'true'
connector-ssl-capable=false

# If security is enabled in compose.yaml change the value to 'true'
connector-driver-options=?useSSL=false

# To enable Connector Proxy Mode, change the value to 'false'
connector-bridge-mode=true
# IMPORTANT: Be sure to add any additional users in the conf/user.map if you enable Proxy mode


[alpha]
topology=clustered
members=db1,db2,db3
master=db1

The .env File

  • Modify the .env file if you use a docker registry where the images are kept.

Provided sample .env:

IMAGE_NAME=your-corporate-registry.com/tungsten-connector
IMAGE_VERSION=8.0.2-10

Step 3 (optional): Enable Security​

  1. Uncomment two lines in compose.yaml :

    # If SSL is configured the following two lines are needed, please uncomment it
    - ./conf/security.properties:/opt/continuent/tungsten/cluster-home/conf/security.properties
    - ./security:/opt/continuent/share

  2. Ensure that disable-security-controls=false in conf/tungsten.ini

  3. Ensure that connector-ssl-capable=true and connector-driver-options=?useSSL=true in conf/tungsten.ini

  4. Copy the following files to the security/ folder from /opt/continuent/share on an existing, running, Tungsten Cluster node also configured with disable-security-controls=false:

    • passwords.store
    • tungsten_keystore.jks
    • tungsten_truststore.ts
    • tungsten_connector_keystore.jks
    • tungsten_connector_truststore.ts

  5. OPTIONAL - Copy the below MySQL Server certificates needed for secure SSL client access testing later on

    • ca.pem
    • client-cert.pem
    • client-key.pem

Step 4: Install and Launch the Connector Container​

shell> docker compose up -d
shell> docker ps

Step 5: Testing the Connector​

You can test the Connector using a MySQl client. Here are simple examples using the command line tool for both secure and non-secure sessions:

  • Without SSL Enabled

    shell> mysql -h 127.0.0.1 -u app_user -psecret -P 3306

  • With SSL Enabled

    shell> mysql -h 127.0.0.1 -u app_user -psecret -P 3306 --ssl-ca=ca.pem --ssl-cert=client-cert.pem --ssl-key=client-key.pem --ssl-mode=REQUIRED

Step 6: Post-Install Operations for the Connector Container​

  • Stopping the Connector Container:

    shell> docker stop {container_name}
    shell> docker ps

  • Starting the Connector Container:

    shell> docker start {container_name}
    shell> docker ps

  • Removing the Connector Container:

    Important

    Before uninstalling the docker container, you MUST ensure you are in the original installation directory and the compose.yaml file must also exist in that directory.

    shell> cd {ORIGINAL_INSTALL_PATH}
    shell> docker compose down -v
    shell> docker ps