Bitnami etcd Virtual Machine

IMPORTANT: The etcd OVA has been released for VMware vSphere only. The following information does not apply for VirtualBox or similar VM executors.

Description

etcd is a distributed key-value store designed to securely store data across a cluster. etcd is widely used in production on account of its reliability, fault-tolerance and ease of use.

First steps with the Bitnami etcd Stack

Welcome to your new Bitnami application! This guide includes some basic information you will need to get started with your application.

What credentials do I need?

You need two sets of credentials:

  • The application credentials, consisting of a username and password. These credentials allow you to log in to your new Bitnami application.
  • The server credentials, consisting of an SSH username and SSH key file. These credentials allow you to log in to your virtual machine using an SSH client and execute commands on the server using the command line. Contact your datacenter administrator for more information.

What is the administrator username set for me to log in to the application for the first time?

Username: root

What is the administrator password?

Password: The administrator password to log in to your application is randomly generated during the first boot. Check the FAQ to learn how to retrieve it.

What is my server IP address?

The IP address is displayed on screen at the end of the boot process, but you can check it at any time by running the following command:

$ sudo ifconfig

Check server IP address

How to start or stop the services?

Each Bitnami stack includes a control script that lets you easily stop, start and restart services. The script is located at /opt/bitnami/ctlscript.sh. Call it without any service name arguments to start all services:

$ sudo /opt/bitnami/ctlscript.sh start

Or use it to restart a single service, such as Apache only, by passing the service name as argument:

$ sudo /opt/bitnami/ctlscript.sh restart apache

Use this script to stop all services:

$ sudo /opt/bitnami/ctlscript.sh stop

Restart the services by running the script without any arguments:

$ sudo /opt/bitnami/ctlscript.sh restart

Obtain a list of available services and operations by running the script without any arguments:

$ sudo /opt/bitnami/ctlscript.sh

etcd default configuration

etcd configuration files

The etcd configuration files are located at the /opt/bitnami/etcd/conf/ directory.

etcd ports

By default, the etcd server runs on port 2379. Only conections from localhost are permitted.

Port 2380 is also available for clustering.

etcd log files

The etcd log file is /opt/bitnami/etcd/logs/etcd.log.

What are the default ports?

A port is an endpoint of communication in an operating system that identifies a specific process or a type of service. Bitnami stacks include several services or servers that require a port.

IMPORTANT: Making this application's network ports public is a significant security risk. You are strongly advised to only allow access to those ports from trusted networks. If, for development purposes, you need to access from outside of a trusted network, please do not allow access to those ports via a public IP address. Instead, use a secure channel such as a VPN or an SSH tunnel. Follow these instructions to remotely connect safely and reliably.

Port 22 is the default port for SSH connections.

The etcd access port is 2379, 2380. This port is closed by default. You must open it to enable remote access.

How to connect to etcd?

You can connect to etcd from the same server where it is installed with the etcdctl client tool. To get the list of available options execute the following command:

$ etcdctl --help

You will see an output similar to this:

Connect to etcd

Let's see how to use the etcdctl CLI. The example below shows how to add new keys to etcd, recover it, and delete the created keys:

IMPORTANT: The etcdctl CLI requires user authentication. It is necessary to include the default username and password when execute commands in the etcdctl CLI. Replace the PASSWORD placeholder with your admin password in the examples below.
  • Execute the ls command to see the data stored in the instance:

    $ etcdctl -u root:PASSWORD ls
    
  • Create a new key using the set command. In this example, create a new key called "data" with the string "my_data" as value. You should see an output similar to the following:

    $ etcdctl -u root:PASSWORD set /data my_data
    my_data
    
  • Use again the ls command to check the directory content:

    $ etcdctl -u root:PASSWORD ls
    /data
    
  • You can also check the value associated to the "data" key by using the get /data command:

    $ etcdctl -u root:PASSWORD get /data
    my_data
    
  • Delete the recently created key executing the rm /data command:

    $ etcdctl -u root:PASSWORD rm /data
    PrevNode.Value: my_data
    

How to connect to etcd from a different machine?

The etcd OVA can only be deployed within a VMware vSphere environment. For that reason, it does not include any specialized firewall software pre-installed or firewall rules set. It is assumed that this OVA will run on a private LAN.

Please contact your system administrator to learn how to remotely access this machine.

How to create a etcd cluster?

This section describes the creation of a etcd cluster with servers located on different hosts.

Launch as many etcd instances as the number of nodes you wish to have in your cluster (in this example, three instances) and then follow the steps below:

Configure each instance

Perform the steps below on each node:

  • Edit the /opt/bitnami/conf/etcd.conf.yml file and modify it as shown below. Remember to replace IP_ADDRESS_OWN with the IP address of the current node and IP_ADDRESS_NODE_X with the corresponding IP addresses of the other nodes.

    advertise-client-urls: http://IP_ADDRESS_OWN:2379
    initial-advertise-peer-urls: http://IP_ADDRESS_OWN:2380
    initial-cluster=http://IP_ADDRESS_OWN:2380,http://IP_ADDRESS_MEMBER_1:2380,http://IP_ADDRESS_MEMBER_2:2380
    

The example configuration above assumes a three-node cluster; if your cluster has fewer or more nodes, add or remove additional IP addresses accordingly.

  • Restart etcd services:

Test the cluster

To check if the replication is working correctly in the cluster, try the following:

IMPORTANT: The etcdctl CLI requires user authentication. It is necessary to include the default username and password when execute commands in the etcdctl CLI. Replace the PASSWORD placeholder with your admin password in the commands below.
  • In the first server, create a key-value by executing the following:

    $ etcdctl -u root:PASSWORD set /message Hello
    Hello
    
  • Log in to any other server and use the get /message command to check the existing data. It should show the key-value created in the first server:

    $ etcdctl -u root:PASSWORD get /message
    Hello
    

Congratulations! You now have a etcd cluster running and ready to replicate the data through all the instances/nodes.

How can I run a command in the Bitnami etcd Stack?

Log in to the server console as the bitnami user and run the command as usual. The required environment is automatically loaded for the bitnami user.

How to create a full backup of etcd?

Backup

The Bitnami etcd Stack is self-contained and the simplest option for performing a backup is to copy or compress the Bitnami stack installation directory. To do so in a safe manner, you will need to stop all servers, so this method may not be appropriate if you have people accessing the application continuously.

Follow these steps:

  • Change to the directory in which you wish to save your backup:

      $ cd /your/directory
    
  • Stop all servers:

      $ sudo /opt/bitnami/ctlscript.sh stop
    
  • Create a compressed file with the stack contents:

      $ sudo tar -pczvf application-backup.tar.gz /opt/bitnami
    
  • Restart all servers:

      $ sudo /opt/bitnami/ctlscript.sh start
    

You should now download or transfer the application-backup.tar.gz file to a safe location.

Restore

Follow these steps:

  • Change to the directory containing your backup:

      $ cd /your/directory
    
  • Stop all servers:

      $ sudo /opt/bitnami/ctlscript.sh stop
    
  • Move the current stack to a different location:

      $ sudo mv /opt/bitnami /tmp/bitnami-backup
    
  • Uncompress the backup file to the original directoryv

      $ sudo tar -pxzvf application-backup.tar.gz -C /
    
  • Start all servers:

      $ sudo /opt/bitnami/ctlscript.sh start
    

If you want to create only a database backup, refer to these instructions for MySQL and PostgreSQL.

How to debug etcd errors?

The main etcd log file is created at /opt/bitnami/etcd/logs/etcd.log.

virtualMachine

Bitnami Documentation