This post serves the purpose of showing how ansible and docker can be used together in order to automatically configure a keycloak docker container.

Following last post on how to use ansible, I’ve been following a good example on how both are not mutually exclusive, and why adopting docker in your technological stack, does’t mean you have to drop all other technological stacks in your arsenal, on which you may have an extensive inventory and technological expertise.

There are no silver bullets.

So now that we got past that, let’s see how we can use a few ansible modules that have been included in ansible 2.5 and how those can be used together with docker to configure keycloak on the fly.

Before starting please notice these modules are still considered experimental and used with that in mind.

The ansible module used will be keycloak_client and would also like to refer keycloak_clienttemplate by the same author eikef ( in order to interact with the Keycloak Rest API , though a bit limited still, as I prefer to make use of the keycloak admnistration cli, aka kcadm, maybe I should also start an ansible module to make use of… if I have the energy or time.

So let’s start by creating our project.

So our project folder should look similar to this. As always if you don’t wan’t to run all the steps, you will find a github link to a repo with all this.

├── create.yml
├── destroy.yml
├── docker
│   └── Dockerfile
├── inventory.yml
└── playbook.yml

A cmd line to start all this.

touch create.yml \
destroy.yml \
inventory.yml \
playbook.yml && \
mkdir docker && \
touch docker/Dockerfile

Ok first of all, since ansible requires python to be available in the target inventory, let’s start by creating our Dockerfile

#Dockerfile for keycloak:ansible
FROM jboss/keycloak:3.4.3.Final
USER root
RUN yum install -y python-devel
USER jboss

This is a very simple alteration to the base image, installing python-devel package, and alternating between the root and jboss users, as jboss is the last declared user, and the one to run keycloak, but doesn’t have sufficient permissions to install packages.

Ok, so now we have a keycloak image with python installed and ansible is able to perform its magic.

So now let’s edit our create.yml playbook so we have a way to create our container and run it.

- hosts: localhost
    #Create a docker image for keycloak configured with python based on Dockerifle at docker
    - docker_image:
        path: docker
        name: keycloak:ansible
    #Launch a container based on the image we just created
    - docker_container:
        name: keycloak.custom
        image: keycloak:ansible
          KEYCLOAK_USER: admin
          KEYCLOAK_PASSWORD: admin
          - 8080:8080
          - 8443:8443

So here we have docker_image and docker_container ansible modules, the first one responsible for creating the image based on our dockerfile, tagging it with keycloak:ansible, and the second one launching the container with a very simple configuration.

To know more about each of those, follow below documentation links:

Keycloak image:

Ansible docker_container:

Ansible docker_image:

Ok so now we have our creation playbook ready, we may start it.

ansible-playbook create.yml

If you navigate to http://localhost:8080/auth you should be greeted by keycloak splage page.

Ok, now that we have a keycloak running that we could have just used a docker run command, let’s configure a new client using our playbook.yml, but first we must set our:


      ansible_connection: docker

And now we can edit our:


- hosts: keycloak.custom
    - name: Configure it
        auth_client_id: admin-cli
        auth_keycloak_url: http://localhost:8080/auth
        auth_realm: master
        auth_username: admin
        auth_password: admin
        client_id: test
        realm: test
        state: present

Ok, since this is a sample post and not a full tutorial nor a how to extensively configure keycloak with ansible, i’ll keep it to a minmum, remember, I have to work for a living :D , and unfortunately don’t have enough time for it, and also compromise the prime business of the company I currently work for ( )

So with that in mind this playbook is composed of a rather simple task, but will allow us to have a starting point if we wish to expand on our client creation and edit.

so what is this playbook doing behind the curtains? Its using the keycloak rest api in order to create a single client, you may find all the parameters with their names in python convention on the module documentation page, all that you may do under the client endpoint at the rest interface is applied by this module, and any templates you may require are also available under the keycloak_clienttemplate module.

Note: you should use ansible-vault to encrypt your secrets such as the password for the user

Ok, so let’s test our playbook against our inventory.

ansible-playbook -i inventory.yml playbook.yml

It should output something similar to this:

PLAY [keycloak.custom] ***************************************************************************************************************************************************************************************

TASK [Gathering Facts] ***************************************************************************************************************************************************************************************
ok: [keycloak.custom]

TASK [Configure it] ******************************************************************************************************************************************************************************************
changed: [keycloak.custom]

PLAY RECAP ***************************************************************************************************************************************************************************************************
keycloak.custom            : ok=2    changed=1    unreachable=0    failed=0

And by navigating to :


And selecting the test client you should have a client with the bare minimal configuration.

And that’s it, we configured our docker container with ansible using ansible modules, this could be improved to your will, and also packaged with other tasks you may wish to do against your keycloak to configure it further, such as using the to create new realms etc.

Ok, so to finalize, let’s edit our destroy.yml playbook to clean up our environment.

If you wish you may improve it using the docker_image to remove the created images.

- hosts: localhost
    - docker_container:
        name: keycloak.custom
        state:  absent

To clean up:

ansible-playbook destroy.yml

As always the github url for this project:

André Ilhicas dos Santos

Devops Padawan, curious about systems automation, learning new languages, paradigms tools each day.

ilhicas ilhicas