This lesson will walk you through how to get started using Vitess, specifically on an Amazon EC2 instance. We'll walk you through how to configure your instance and how to connect to it. We'll then go over how to download, build, and run Vitess.
Before getting Vitess installed, you'll need to get a fresh EC2 instance spun up and properly configured. Doing this will make it easier for anyone to follow along, and we'll be starting form a completely new instance, so you will be able to closely replicate the exact environment being shown here.
From the EC2 instances dashboard, click on the "new instance" button. Make sure to configure change the following settings on this instance:
- Name the instance
vitess-main. - Choose Ubuntu for your operating system.
- In order to ensure you have enough capacity to build, install, and run Vitess, make sure you choose an instance type with sufficient resources. Here, we'll be using a
c5.xlarge. - For the purpose of this example, we'll want to enable HTTP and HTTPS traffic, and add an additional security group rule to allow TCP traffic form ports
1024-50000. This configuration has negative security implications, so should not be used for a production environment. However, this configuration will be useful for testing purposes. - Make sure you download the corresponding
.pem file for this instance and place it somewhere safe on your computer. - Increase the storage capacity to at least 20 gigabytes.
All other settings can be left at their default values. After creating this instance, navigate in the UI to find the ssh connection command. Copy this, and execute it from your terminal in the same directory that you stored your .pem file. Now, you're connected to your instance!
Next, create a directory for Vitess to live in and grab the source code from GitHub. For this example, we'll be working with Vitess version 19.
mkdir dev ; cd dev
git clone https://github.com/vitessio/vitess.git
cd vitess
git checkout release-19.0
There are several OS and Python packages that will be needed for building Vitess and the examples in this lesson series. Let's go ahead and get all those downloaded and installed here:
sudo apt update
sudo apt install -y mysql-server etcd-server etcd-client curl golang make
sudo apt install -y python3-dev python3-pip default-libmysqlclient-dev build-essential pkg-config
pip3 install --break-system-packages mysqlclient
We also need to ensure that both mysql and etcd services are stopped and disabled. We want to be able to manage these separately, since both are used by Vitess. In addition, we want to disable AppArmor.
sudo service mysql stop
sudo service etcd stop
sudo systemctl disable mysql
sudo systemctl disable etcd
sudo ln -s /etc/apparmor.d/usr.sbin.mysqld /etc/apparmor.d/disable/
sudo apparmor_parser -R /etc/apparmor.d/usr.sbin.mysqld
Now, time to build!
export PATH=/home/ubuntu/dev/vitess/bin/:${PATH}
make build
This many take a few minutes, depending on the instance size you chose.
The Vitess repository comes with a collection of scripts to quickly get started running a simple local Vitess cluster. Let's run one of these and try connecting to it. Before running the scripts, change to the local directory and source env.sh:
cd ./examples/local
source ../common/env.sh
Next, open up ../common/env.sh and change the hostname variable to be the public IPv4 domain name of your EC2 instance. Then, run the script:
At the end, this script should print out a URL you can visit to view the VTAdmin panel for your cluster. You can also connect to the cluster to execute queries using the mysql client:
mysql -P 15306 -u root --protocol tcp
From here, you can poke around, view tables, and insert data. You should see a database (which is called a "keyspace" in vitess terminology) named commerce. This was created by the ./101_initial_cluster.sh script.
When finished, log out of the MySQL client. You've now create a Vitess cluster - great work!