🐙 A FUN way to deploy dockerized applications to OpenShift with Ansible
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci (ci) add tests for the switch playbook Dec 7, 2018
.github 🚸(github) add templates for github issues and PRs Jun 5, 2018
apps ♻️(databases) migrate databases settings into app's settings file Dec 10, 2018
bin (ci) add tests for the switch playbook Dec 7, 2018
core_apps/acme 🐛(acme) restore live/staging certificates switch Oct 4, 2018
docs 📝(docs) complete playbook document with create_vaults.yml playbook Nov 26, 2018
env.d 👷(environment) add ci docker env vars file Jul 31, 2018
group_vars ♻️ (ip) remove default cluster ip configuration Dec 7, 2018
plugins (apps) define settings for an app Dec 6, 2018
requirements ♻️ (ip) remove default cluster ip configuration Dec 7, 2018
tasks ♻️(databases) migrate databases settings into app's settings file Dec 10, 2018
templates (databases) generate databases access credentials for an application Nov 23, 2018
tests ♻️ (databases) add an environment mapping to prefix databases resources Dec 5, 2018
.dockerignore 🐳(ignore) remove oc cluster files from context Oct 1, 2018
.flake8 👷(circle) add python code linters Jul 11, 2018
.gitignore 🙈(openshift) ignore local cluster tree Aug 29, 2018
.gitlab-ci.yml 🔧(customer) rename patient0 customer in eugene Nov 22, 2018
CHANGELOG.md 🔖(alpha) bump version to 1.0.0-alpha.1 Dec 10, 2018
CODE_OF_CONDUCT.md 📝(README) add contributing & code of conduct May 23, 2018
CONTRIBUTING.md 📝(README) add contributing & code of conduct May 23, 2018
Dockerfile 🔥(oc) remove oc client in arnold's image Nov 26, 2018
LICENSE 📄(LICENSE) switch to MIT Open Source license May 23, 2018
README.md 🔧(customer) rename patient0 customer in eugene Nov 22, 2018
VERSION 🔖(alpha) bump version to 1.0.0-alpha.1 Dec 10, 2018
ansible.cfg 🎨(apps) make apps lookup a lookup plugin Jul 11, 2018
bootstrap.yml (bin) secure bootstrap by asking confirmation before deletion Dec 3, 2018
build_images.yml (playbook) create a pre task to enforce customer name max length <= 6 Nov 22, 2018
create_acme.yml (playbook) create a pre task to enforce customer name max length <= 6 Nov 22, 2018
create_databases_vault.yml (databases) generate databases access credentials for an application Nov 23, 2018
create_htpasswds.yml (playbook) create a pre task to enforce customer name max length <= 6 Nov 22, 2018
create_object.yml (playbook) create a pre task to enforce customer name max length <= 6 Nov 22, 2018
create_project.yml (playbook) create a pre task to enforce customer name max length <= 6 Nov 22, 2018
create_secrets.yml (playbook) create a pre task to enforce customer name max length <= 6 Nov 22, 2018
create_vaults.yml (vault) add a playbook to create a vault per application Nov 26, 2018
delete_project.yml (playbook) create a pre task to enforce customer name max length <= 6 Nov 22, 2018
deploy.yml (deploy) prevent deploy playbook to deploy all defined apps Dec 6, 2018
init_project.yml (playbook) create a pre task to enforce customer name max length <= 6 Nov 22, 2018
inventory 😎(ansible): POC generating deployment description files per project (#1) Mar 9, 2018
load_fixtures.yml (playbook) create a pre task to enforce customer name max length <= 6 Nov 22, 2018
pytest.ini (tests) add pytest environment Jul 11, 2018
switch.yml (playbook) create a pre task to enforce customer name max length <= 6 Nov 22, 2018

README.md

Arnold

CircleCI

Arnold is a tool to deploy dockerized applications to OpenShift with Ansible. It was built by France Université Numérique to ease its infrastructure deployment.

The current work mainly focuses on the Open edX MOOC platform, but it can be considered as a generic tool to deploy dockerized applications.

Overview

Arnold has been designed as a suite of Ansible playbooks and OpenShift object definition templates (Jinja2). We take advantage of the openshift_raw Ansible module to make Ansible talk with OpenShift.

As a DevOps using this project, you will need to adapt OpenShift object templates to suite your needs or constraints and run playbooks to push your changes to your OpenShift instance that orchestrates your services.

Requirements

  • Docker: we use docker to develop and run Arnold. This is a strict requirement to use this project.
  • OpenShift's client (aka oc): this CLI is used to communicate with the running OpenShift instance you will use. Plus, it offers the possibility to run a minimal cluster for development purpose (using a set of docker containers). For now please stick to the 3.9 release of oc, we've experienced too much DNS issues with the 3.10 newer release.

Even if we recommend to only use oc and docker to work locally with Arnold, you might also consider using MiniShift as a relevant alternative to run an isolated OpenShift cluster within a VM (please refer to our instructions to install MiniShift).

Quick start

Disclaimer: this quick start guide has been written with development / testing purpose in mind. If you are looking for more insights on how to use it in production, please refer to our documentation.

Build Arnold

First things first: you'll need to clone this repository to start playing with Arnold:

$ cd path/to/working/directory
$ git clone git@github.com:openfun/arnold.git

As we heavily rely on Ansible and OpenShift, we've cooked a Docker container image that bundles Ansible and the OpenShift CLI (you have already installed Docker on your machine right?). You can build this image with a little helper we provide:

$ cd path/to/cloned/repo
$ bin/build

If everything goes well, you must have built Arnold's Docker image. You can check its availability via:

$ docker images arnold
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
arnold              0.1.0-alpha         549baa2b861b        4 days ago          824MB

Run a local OpenShift cluster

You'll need to ensure that you have an OpenShift instance that will be used to deploy your services. For development or testing purpose, we recommend you to use the oc cluster up command to start a local minimalist cluster to work with (don't do it now, please read the next paragraph first).

Before starting the cluster, make sure that your system meets the following requirements:

  1. Make sure that the /etc/docker/daemon.json file contains at list 172.30.0.0/16 as insecure registry:
{
  "insecure-registries": ["172.30.0.0/16"]
}
  1. To run ElasticSearch (you'll probably have an application that will use it), you will need to ensure that your kernel's vm.max_map_count parameter is at least 262144:
$ sudo sysctl -w vm/max_map_count=262144

Now that you've configured your system, you can safely start a cluster via:

# Substitute 192.168.1.10 with your local IP
$ OPENSHIFT_DOMAIN="192.168.1.10"
$ K8S_AUTH_HOST="https://${OPENSHIFT_DOMAIN}:8443"
$ oc cluster up --public-hostname="${OPENSHIFT_DOMAIN}"

If everything goes well, you can start a web browser with the following address to access the web console: https://192.168.1.10:8443 (replace 192.168.1.10 with your local IP).

You can log in the web console with developer as your username and password.

nota bene: you'll probably be asked to accept the connection even if it is insecure (SSL certificate issue). Please do so.

And finally you must also login from the CLI to be allowed to perform requests on the OpenShift cluster:

$ oc login --insecure-skip-tls-verify=true -u developer -p developer "${K8S_AUTH_HOST}"

As we are gentle people, we also provide a shortcut to automate running a new cluster and login to it:

# Substitute 192.168.1.10 with your local IP that has access to the internet
$ bin/dev 192.168.1.10

Please, note that you do not need to run bin/dev if you have already started a local cluster and logged in with oc.

Deploy!

Now that you have a working OpenShift cluster, let's have fun (sic!) by creating a project for a customer in a particular environment with a new helper:

nota bene: when running this command, you'll be asked for a vault password. The default value for this demo is: arnold.

$ bin/bootstrap

Tadaaa! Arnold has created a new OpenShift project called eugene-development with a collection of services up and running.

When edxapp's first deployment has completed successfully, we invite you to test the lms or studio application with the following credentials:

username password email is staff is superuser
student student student@example.com no no
teacher teacher teacher@example.com no no
staff staff staff@example.com yes no
admin admin admin@example.com yes yes

nota bene: you will find URLs of the studio or lms services from the web console (Application > Routes). You should see a page like the screenshot below.

OpenShift routes

Going further

By following this quick start, you only scratched the surface of Arnold's capabilities. We invite you to read the project's documentation (see below), to know more about Arnold's core features such as:

  • multiple client/environment configurations support
  • blue/green deployment strategy
  • application discovery (add your own applications easily)
  • ...

Documentation

The full documentation of the project is available in this repository (see ./docs) (and also in readthedocs soon).

Contributing

Please, see the CONTRIBUTING file.

Contributor Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See CODE_OF_CONDUCT file.

License

The code in this repository is licensed under the MIT license terms unless otherwise noted.

Please see LICENSE for details.