Initial Setup

AttentionThis page documents an earlier version. Go to the latest (v2.1)version.

A dedicated host or VM is needed to run YugaWare. See this faq for more details. This page highlights the basic setup needed in order to install YugaWare.

1. Create a new security group (optional)

In order to access YugaWare from outside the AWS environment, you would need to enable access by assigning an appropriate security group to the YugaWare machine. You will at minimum need to:

  • Access the YugaWare instance over ssh (port tcp:22)
  • Check, manage and upgrade YugaWare (port tcp:8800)
  • View the YugaWare console ui (port tcp:80)

Let us create a security group enabling all of that!

Go to EC2 -> Security Groups, click on Create Security Group and add the following values:

  • Enter yugaware-sg as the name (you can change the name if you want).
  • Add a description (eg: Security group for YugaWare access).
  • Add the appropriate ip addresses to the Source IP ranges field. To allow access from any machine, add 0.0.0.0/0 but note that this is not very secure.
  • Add the ports 22, 8800, 80 to the Port Range field. The Protocol must be TCP.

You should see something like the screenshot below, click Create next.

Create security group

2. Create a new IAM role (optional)

In order for YugaWare to manage Yugabyte nodes, it will require some limited access to your AWS infrastructure. This can be accomplished through directly providing a set of credentials, when configuring the AWS provider, which you can read more later on here. Alternatively, the EC2 instance where YugaWare will be running can be brought up with an IAM role with enough permissions to take all the actions required by YugaWare. Below we provide a sample of such a role:

  1. {
  2.     "Version": "2012-10-17",
  3.     "Statement": [
  4.         {
  5.             "Sid": "VisualEditor0",
  6.             "Effect": "Allow",
  7.             "Action": [
  8.                 "ec2:AttachVolume",
  9.                 "ec2:AuthorizeSecurityGroupIngress",
  10.                 "ec2:ImportVolume",
  11.                 "ec2:ModifyVolumeAttribute",
  12.                 "ec2:DescribeInstances",
  13.                 "ec2:DescribeInstanceAttribute",
  14.                 "ec2:CreateKeyPair",
  15.                 "ec2:DescribeVolumesModifications",
  16.                 "ec2:DeleteVolume",
  17.                 "ec2:DescribeVolumeStatus",
  18.                 "ec2:StartInstances",
  19.                 "ec2:DescribeAvailabilityZones",
  20.                 "ec2:CreateSecurityGroup",
  21.                 "ec2:DescribeVolumes",
  22.                 "ec2:ModifyInstanceAttribute",
  23.                 "ec2:DescribeKeyPairs",
  24.                 "ec2:DescribeInstanceStatus",
  25.                 "ec2:DetachVolume",
  26.                 "ec2:ModifyVolume",
  27.                 "ec2:TerminateInstances",
  28.                 "ec2:AssignIpv6Addresses",
  29.                 "ec2:ImportKeyPair",
  30.                 "ec2:DescribeTags",
  31.                 "ec2:CreateTags",
  32.                 "ec2:RunInstances",
  33.                 "ec2:AssignPrivateIpAddresses",
  34.                 "ec2:StopInstances",
  35.                 "ec2:AllocateAddress",
  36.                 "ec2:DescribeVolumeAttribute",
  37.                 "ec2:DescribeSecurityGroups",
  38.                 "ec2:CreateVolume",
  39.                 "ec2:EnableVolumeIO",
  40.                 "ec2:DescribeImages",
  41.                 "ec2:DescribeVpcs",
  42.                 "ec2:DeleteSecurityGroup",
  43.                 "ec2:DescribeSubnets",
  44.                 "ec2:DeleteKeyPair"
  45.             ],
  46.             "Resource": "*"
  47.         }
  48.     ]
  49. }

3. Provision instance for YugaWare

Create an instance to run YugaWare. In order to do so, go to EC2 -> Instances and click on Launch Instance. Fill in the following values.

  • Change the boot disk image to Ubuntu 16.04 and continue to the next step.Pick OS Image

  • Choose c5.xlarge (4 vCPUs are recommended for production) as the machine type. Continue to the next step.

  • Choose the VPC, subnet and other settings as appropriate. Make sure to enable the Auto-assign Public IP setting, otherwise this machine would not be accessible from outside AWS. If you created an IAM role above, or already had one that you would like to use, provide that under IAM role. Continue to the next step.

  • Increase the root storage volume size to at least 100GiB. Continue to the next step.

  • Add a tag to name the machine. You can set key to Name and value to yugaware-1. Continue to the next step.

  • Select the yugaware-sg security group we created in the previous step (or the custom name you chose when setting up the security groups). Launch the instance.

  • Pick an existing key pair (or create a new one) in order to access the machine. Make sure you have the ssh access key. This is important to enable ssh access to this machine. In this example, we will assume the key pair is ~/.ssh/yugaware.pem.

Finally, click Launch to launch the YugaWare server. You should see a machine being created as shown in the image below.

Pick OS Image

1. Create a new project (optional)

A project forms the basis for creating, enabling and using all GCP services, managing APIs, enabling billing, adding and removing collaborators, and managing permissions. You would need browse to the GCP cloud resource manager and click on create project to get started. You can follow these instructions to create a new GCP project.

Give the project a suitable name (eg: yugabyte-gcp) and note the project ID (eg: yugabyte-gcp). You should see a dialog that looks like the screenshot below.

Creating a GCP project

2. Set up a new service account

YugaWare admin console requires a service account with the appropriate permissions to provision and manage compute instances. Go to the IAM & admin -> Service accounts and click on Create Service Account. You can follow these instructions to create a service account.

Fill the form with the following values:

  • Service account name is yugaware (you can customize the name if needed).
  • Set role to Project -> Owner.
  • Check the box for Furnish a new private key, choose JSON option.

Here is a screenshot with the above values in the form, click create once the values are filled in.

Service Account -- filled create form

NOTE: Your browser would have downloaded the respective JSON format key. It is important to store it safely. This JSON key is needed to configure the YugaWare Admin Console.

3. Give permissions to the service account

  • Find the email address associated with the service account by going to IAM & admin -> Service accounts. Copy this value. The screen should look as shown below.

Service Account Email Address

  • Next, browse to IAM & admin -> IAM and click on ADD. Add the compute admin role for this service account. A screenshot is shown below.

Service Account Add Roles

4. Creating a firewall rule

In order to access YugaWare from outside the GCP environment, you would need to enable firewall rules. You will at minimum need to:

  • Access the YugaWare instance over ssh (port tcp:22)
  • Check, manage and upgrade YugaWare (port tcp:8800)
  • View the YugaWare console ui (port tcp:80)

Let us create a firewall entry enabling all of that!

Go to VPC network -> Firewall rules tab:

Firewall -- service entry

NOTE: If this is a new project, you might see a message saying Compute Engine is getting ready. If so, you would need to wait for a while. Once complete, you should see the default set of firewall rules for your default network, as shown below.

Firewall -- fresh list

Click on the CREATE FIREWALL RULE button and fill in the following.

  • Enter yugaware-firewall-rule as the name (you can change the name if you want).
  • Add a description (eg: Firewall setup for YugaWare Admin Console).
  • Add a tag yugaware-server to the Target tags field. This will be used later when creating instances.
  • Add the appropriate ip addresses to the Source IP ranges field. To allow access from any machine, add 0.0.0.0/0 but note that this is not very secure.
  • Add the ports tcp:22,8800,80 to the Protocol and ports field.

You should see something like the screenshot below, click Create next.

Firewall -- create full

5. Provision instance for YugaWare

Create an instance to run YugaWare. In order to do so, go to Compute Engine -> VM instances and click on Create. Fill in the following values.

  • Enter yugaware-1 as the name.
  • Pick a region/zone (eg: us-west1-b).
  • Choose 4 vCPUs (n1-standard-4) as the machine type.
  • Change the boot disk image to Ubuntu 16.04 and increase the boot disk size to 100GB.
  • Open the Management, disks, networking, SSH keys -> Networking tab. Add yugaware-server as the network tag (or the custom name you chose when setting up the firewall rules).
  • Switch to the SSH Keys tab and add a custom public key and login user to this instance. First create a key-pair.

You can do this as shown below.

  1. $ ssh-keygen -t rsa -f ~/.ssh/yugaware-1-gcp -C centos

Set the appropriate credentials for the ssh key.

  1. $ chmod 400 ~/.ssh/yugaware-1-gcp

Now enter the contents of yugaware-1-gcp.pub as the value for this field.

Here are the detailed instructions to create a new SSH key pair, as well as the expected format for this field (eg: ssh-rsa [KEY_VALUE] [USERNAME]). This is important to enable ssh access to this machine.

VM instances -- filled in create

Note on boot disk customization:

VM instances -- pick boot disk

Note on networking customization:

VM instances -- networking tweaks

Finally, click Create to launch the YugaWare server.

6. Connect to the YugaWare machine

From the GCP web management console, find the public ip address of the instance we just launched.

You can connect to this machine by running the following command (remember to replace XX.XX.XX.XX below with the ip address, and also to enter the appropriate ssh key instead of yugaware-1-gcp).

  1. $ ssh -i ~/.ssh/yugaware-1-gcp [email protected]