Kontena is a developer-friendly platform for orchestrating applications that are run in Docker containers. It simplifies deploying and running containerized applications by leveraging technologies such as Docker and CoreOS on top of high-performance UpCloud infrastructure, and provides a complete, cost-efficient solution for all types of workloads.

Kontena logo

In this tutorial, we will show you how to quickly get up and running with Kontena on UpCloud.

1. Sign up to UpCloud

If you have not already registered to UpCloud, you should begin by getting signed up. The link opens in a new window – we will wait here for you!

2. Configure UpCloud API access

To allow API access to your UpCloud account, you first need to enable the API permission by visiting My Account -> User accounts in your UpCloud Control Panel. We recommend you to set up a sub-account specifically for API usage with its own username and password, as it allows you to assign specific permissions for increased security.

Click Add user and fill in the required details, and check the “Allow API connections” checkbox to enable API for the user. You should also limit the API connections to a specific IP address or address range for additional security. Once you are done entering the user information, hit the Save button at the bottom of the page to create the new username.

3. Register to Kontena

All users should register for a personal cloud account. The accounts are used to enable access control and to generate audit trail logs from user actions. Create your own personal user account at the Kontena Cloud portal.

4. Install Kontena CLI

At its basics, the Kontena command line interface is all you need to manage your Master, Nodes, and application stacks right from your own computer. Thanks to Ruby, Kontena is available on a multitude of operating systems including MacOS, Windows, and the majority of the Linux distributions. Follow the instructions in the official documentation to install Ruby on your system.

Thanks to the Ruby programming language, Kontena is available on a multitude of operating systems including MacOS, Windows, and the majority of the Linux distributions. Follow the instructions in the official documentation to install Ruby on your system.

To install and run Kontena, you will need Ruby version 2.1 or later installed on your system. For more details, check the official Ruby installation documentation.

You can then install the CLI using the RubyGems package manager, which is included in Ruby. Use the following command in your terminal or command prompt with admin privileges.

gem install kontena-cli

When the installation is complete, you can verify the interface is working by checking the current version with the command below.

kontena version

With the Kontena installed and ready, authenticate to the Cloud portal from your terminal. First, enter the command shown below to begin, then press any key to continue to log in via your web browser.

kontena cloud login

If you wish to install the Kontena client on a system without a graphical user interface, you can log in remotely with the following command.

kontena cloud login -r

Then open the URL from the output on another computer with a web browser, log into your Kontena account, and enter the code when asked.

Please visit https://cloud.kontena.io/remote-login/<identifier> and enter the code

<login code>

Once you have successfully logged in with your Kontena username and password, the verification is passed onto your terminal and you can close the browser window.

5. Create Kontena Master

We are now ready to start setting up the Master server. To allow Kontena to integrate with the UpCloud API, you will need to install the specific plugin using the next command.

kontena plugin install upcloud

Then continue by creating your first Kontena Master, which will take care of orchestration and provide management for your containers.

Note that an SSH key is required to create Master or Node servers. If you do not already have an SSH key available, you can find out how to generate a new key at our article about Using SSH Keys for Authentication.

Create a new Master server using the command below.

Replace the <UPCLOUD_USERNAME> and <UPCLOUD_PASSWORD> with your credentials, as well as the <PATH_TO_SSH_PUBLIC_KEY> with a path to your public SSH key.

kontena upcloud master create \
--username <UPCLOUD_USERNAME> \
--password <UPCLOUD_PASSWORD> \
--ssh-key <PATH_TO_SSH_PUBLIC_KEY>

An interactive setup process will then ask you to define a couple of settings for the new Master server.

  • Enter a hostname for the new Master or just press enter to use the default value as shown in the parenthesis.
  • Select the authentication provider you wish to use, the Kontena Cloud option is recommended for most cases.

Once you have made the required selections, a new server will be deployed in the UpCloud infrastructure. During the deployment process, you will see an output similar to the truncated example below.

 [done] Generating a self-signed SSL certificate
 [done] Creating an Upcloud server kontena-master
 [done] Waiting for kontena-master to start
 [done] Retrieving Kontena Master version
 [done] Kontena Master 1.1.2 is now running at https://<IP_ADDRESS>
 ...
 [done] Authenticating as <KONTENA_USERNAME> to Kontena Master 'kontena-master'

<IP_ADDRESS> is the IP-address that was assigned to your newly created Kontena Master on UpCloud.

If you have problems passing your public SSH key using the example command above, leave out the --ssh-key parameter when creating a new master or node and simply paste in the plain key when prompted.

6. Selecting the Kontena Master

When the Master has been successfully created, it is automatically selected as currently active. Enter the next command to verify that the new Master has the asterisk (*).

kontena master list
Name                     Url
* kontena-master         https://<IP_ADDRESS>
kontena-master-admin     https://<IP_ADDRESS>

You can always switch between Master servers with the following command if needed.

kontena master use <KONTENA_MASTER>

7. Create a Kontena Grid

With the Master server up and running, you should create a new Grid that is used when installing Nodes. A default “test” Grid is created while deploying the Master, which you can see using the following command.

kontena grid list
Name         Nodes     Services    Users 
test *       0         0           2

A new Grid can be created with the following command including the name for your Grid as an argument. In the example below, we will create a Grid with a name “cloud”.

kontena grid create cloud
 [done] Creating cloud grid
 [done] Switching scope to cloud grid

If you get an error when trying to use the Grid commands saying the server uses a certificate signed by an unknown authority, you can temporarily disable the check on your current terminal window by adding the following to your environmental variables.

export SSL_IGNORE_ERRORS=true
This should only be used for testing purposes. For more permanent setups, make sure to install valid certificates, for example using the Kontena Certificates features.

8. Create your Kontena Nodes

You have completed the setup of a Master server and successfully created a Grid. It is now time to deploy your first Kontena Node, that is used to run your containerized workloads.

The process is very similar to creating a Master and the newly created Nodes will automatically join the Grid you created in the previous step.

kontena upcloud node create \
--username <UPCLOUD_USERNAME> \
--password <UPCLOUD_PASSWORD> \
--ssh-key <PATH_TO_SSH_PUBLIC_KEY>
 [done] Creating Upcloud node <NODE_NAME>
 [done] Waiting for node <NODE_NAME> join to grid cloud

You should see an output similar to the example above following the deployment.

9. All done!

You have now successfully deployed your Kontena Master with a Grid containing your Nodes on UpCloud! You can verify your setup by running the following command, which will list all the Nodes belonging to the Grid we previously created.

kontena node list
   Name            Version    Status    Initial    Labels
⊛ <NODE_NAME>     1.3.4      online    1 / 1      region=fi-hel1,provider=upcloud

What’s next?

The guys at Kontena have written an excellent tutorial on how to install and run a private Parse server in production, which gives you a thorough introduction on just how easy and developer-friendly Kontena is. And if you want to learn more about Kontena, we highly recommend checking out their official documentation.