Matador Deploy - Making Deployment on Rancher Fun

By Timon Sotiropoulos, software engineer at SEED. SEED is a leading product development company that builds design-driven web and mobile applications for startup founders and enterprise innovators. Deployment days can be quite confronting and scary for new developers. We realized through onboarding some of our developers and introducing them to the world of DevOps that the complexity and stress of deployment days could take a toll on morale and productivity, with everyone always half dreading a deployment on the upcoming calendar. After learning the no.1 rule of “never deploy on a Friday” the hard way, the team at SEED decided there had to be a better way than the traditional “pull down from Git repository and deploy to a server” method. The Road to Matador This journey started with a trip down the lane of the hottest containerisation framework in the business, the flying whale Docker. For those have haven’t heard of it, Docker essentially allows you to create a blueprint for your application inside its own contained virtual machine image. What this means is that you can create a working version of your app on any server that has Docker installed and be confident that everything will work as expected. The next link in the chain we discovered was Rancher, an excellent tool for automatically connecting and configuring Docker containers. Rancher allows you to break your application up into multiple, separate components the same way you would break up a program into different classes, allowing single responsibility as well as the ability to scale certain services up and down as required. This process and procedure became second nature to us, but it was easy to mess things up. It was easy to accidentally update the wrong Rancher environment and as we planned on moving to a more continuous development lifecycle, the manual updating of the Rancher environments had to stop. Our long term plan for our continuous deployment process is to get to a point where a developer can push their code to GitHub, build a copy of the Docker container, tag it with that commit ID, and then push that code to their desired Rancher environment. All the separate parts work independently, but we are working towards integrating all of these tools into a fully-fledged continuous deployment service. The first step is Matador Deploy. Matador is a tool we have created to handle the creation and building of our Docker containers and deploying them to the Rancher environments. The complication here is that for each of our projects, we would have two or three separate environments, one each for Production, Staging and Development. To do this, we would have to duplicate all of our DevOps configurations and scripts for each of our environments and then build the application using a Makefile that set specific variables for each of the Rancher Compose commands. However, we found that these Makefiles were simply starting to duplicate themselves across all of our projects and we knew there had to be a better way.

So what does Matador do?

The first thing we wanted Matador to do was combine the similar parts of our environments and Docker/Rancher configurations into one file, while still also allowing us to have the environment-specific parts when required, such as the environment variables that connected to our production or staging database. This led to the creation of three files that Matador requires to run: two generic templates that setup the basics of the project, and one configuration file that holds all our environment specific configuration:

• docker-compose-template.yml: The generic Docker Compose file for the application. This file contains all the configuration that builds the docker containers that together create your application stack, as well as the connections between them.
• rancher-compose-template.yml: The generic Rancher Compose file for the application. This file contains all the configuration that is specific to your Rancher environments, such as the scale for each of your docker containers or your SSL certificates that have been setup for the Rancher environment.
• config.yml: The config file is the one where you can define your environment specific configuration between your production, staging and development environments that have been set up on Rancher. Below is a short example of how this config file should be structured out:

image_base: seed/example-image
project_name: tester
global:
 web:
  environment:
   - TEST=forall
dev:
 web:
  environment:
   - NODE_ENV=dev
  labels:
   io.rancher.scheduler.affinity:host_label: client=ibackpacker,env=development
staging:
 web:
  environment:
   - NODE_ENV=staging
  labels:
   # io.rancher.scheduler.affinity:host_label: client=alessi,env=staging
   com.alessimutants.pods: version=0.1,branch=dev
prod:
 lb:
  labels:
   io.rancher.scheduler.local: 'false'
  web:
   image: seed/web
   environment:
    - NODE_ENV=prod
   labels:
    io.rancher.scheduler.local: 'false'

Everything defined in the config.yml file will be added to your docker-compose-template depending on the environment variable that you pass the application at run time. Matador will take the additional config provided, then append or overwrite what is in the docker-compose-template file and write out a new docker-compose file for you automatically. The same is done with your rancher-compose-template; although at this point in time there are no configuration options to alter the template, this will be added in future releases. These output files are then used as part of the Rancher Compose process to update your environment on Rancher. They are also saved locally so that you can review the configuration that Matador has created for you.

So How Do I Use Matador?

We have put together some extremely detailed usage instructions on the GitHub repository, but the general gist is pretty straight forward. You will need to download the latest version of Matador Deploy from the Python Package Index - PyPI, as well as Rancher Compose, which can be downloaded from their release page on GitHub. Once that is done, there are a few required fields that you must supply to the configuration file to make things work. These are the first two entries in the config.yml:

• project_name: This field will be the name that your stack receives when it is deployed to Rancher. It will also be automatically namespaced with the environment that you pass to Matador when you deploy. Note, this is not the Rancher environment name, but rather the Rancher stack name.
• image_base: This field is the most important because it provides the DockerHub registry that your application will attempt to load your docker images from. These also have a naming convention that is required for each of your respective environment images as follows:

seed/example-image:latest // Production Image seed/example-image:staging // Staging Image seed/example-image:dev // Development Image

We do plan to include the building of your Docker images within Matador itself in future releases, however for now you will need to add these tags manually when pushing your images to DockerHub. Once your config.yml, docker-compose-template.yml and rancher-compose-template.yml have been configured, place them inside a folder called “templates” in the root of your project directory. Finally, from the root of your project directory call the following command:

$ matador-deploy –url http://rancher.url.co –key RANCHER_KEY –secret RANCHER_SECRET –env dev

The fields themselves are explained here:

--url: This refers to the rancher url that you are trying to upload your rancher configuration to. --key: This is the API Key that needs to be created specifically for the rancher environment that you are trying to update. --secret: This is the Secret Key of Password that is provided to you when you create a new API Key for your rancher environment. --env: This is the environment that you wish to update. It takes one of the following options are

The benefit of Matador in this instance is that it forces you to provide the authentication information for your Rancher environment. One of the issues with Rancher Compose is that it will search your local environment in your shell for the Rancher environment keys, so if you are pushing a lot of different stacks to Rancher (for example pushing to Staging, then to Production), it can be easy to make a mistake and push the wrong image to the wrong environment. If these fields aren’t provided to Matador, the process will simply fail. There are also plans to improve this even further by querying your Rancher server with your API keys and having Matador actually tell you what environment it is attempting to update - look for that too in a future release!

Where To From Here?

We have a few ideas of things we want the application to be able to do as we work our way into building a full continuous deployment tool. A few basic examples would be: ● Adding Support for building docker images and pushing them to Docker Hub ● Adding a tagging system that connects your Docker Hub images to your currently loaded Image on your Rancher environment ● Add a simplified rollback option, most likely using the tagging system However, what we really want to know are the features that you would find most useful. We have open sourced Matador because we think that it could be really helpful in integrating all these excellent services together in the future. So please give it a try, and if you have any ideas either write an issue and we will have a look into it, or just fork the repository and give it a go. We can’t wait to see what you come up with.