DDevelopment & Design

Real-life Ansible – chapter one – how to run playbooks on production (more) safely

This is the first blog post in a series presenting some various real-life examples of Ansible in our projects. If you are interested in Ansible going production-ready – stay tuned!

Problem definition

We have a few inventories, like dev, stage and prod. For some of them, stability is not as important as for the others. On the other hand, our playbooks may contain several parameters, and we also want to pass some ansible-playbook parameters (e.g. tags), so a command to perform some action could be pretty long. It’s easy to overlook the crucial ones, especially for the production environment.

ansible-playbook -i inventories/dev app1.yml -e app_version=snapshot -t app --skip-tags maintenance -e serial=2

In such a situation there is a very high risk that we find a command in our shell history and run a playbook forgetting to change the inventory. While running the wrong command on dev is not so painful, we want to prevent accidental playbook running on production.

Confirmation on production

In the next few paragraphs I will show you our solution of making our playbooks production-aware.

Dedicated role

We decided to create a dedicated role named confirm, which is responsible for confirming our production actions. Why a dedicated role? Because we can include it in all playbooks that require confirmation. So to ensure confirmation is prompted, it’s enough to add a role to your playbook.

- hosts: app1 gather_facts: no roles: - confirm tags: - always

We can skip the fact-gathering stage, as we do not depend on any system parameter. Most importantly, by using the always tag, we run this role always, regardless of the tags given in the command line.

Role tasks

I will show you the tasks’ evolution leading to the final version. Firstly, there might be just two simple tasks:

- name: wait for confirmation if required pause: prompt: "You are running playbook for {{ env }}, type environment name to confirm" register: confirm_response - name: fail if wrong confirmation fail: msg: "Aborting due to incorrect input, given <<{{ confirm_response.user_input }}>>, expected <<{{ env }}>>" when: env != confirm_response.user_input

The snippet above shows a simple prompt asking a person to type the environment name to confirm their actions. This gives us the solution to our main goal – getting rid of playbooks that are running mindlessly. After prompt, you must type again the environment name (e.g. prod), so you must be aware that the playbook is run on production. If the confirmation response is wrong, the playbook is aborted.

Running multiple playbooks at once

Sometimes we need to run multiple playbooks at once, e.g.:

ansible-playbook -i inventories/dev app1.yml app2.yml app3.yml

In the solution above, we should confirm our actions in each playbook. To avoid this drawback, let’s introduce a slight modification:

- name: wait for confirmation if required pause: prompt: "You are running playbook for {{ env }}, type environment name to confirm" register: confirm_response when: confirm_response_user_input is not defined - set_fact: confirm_response_user_input: "{{ confirm_response.user_input }}" when: confirm_response_user_input is not defined - name: fail if wrong confirmation fail: msg: "Aborting due to incorrect input, given <<{{ confirm_response_user_input }}>>, expected <<{{ env }}>>" when: env != confirm_response_user_input

Now, we save the confirmation to the variable, so we can confirm only once. Why a dedicated variable? Why can’t we use confirm_response? Because if we skip the first task, confirm_response would contain info about the skipped first task instead of previous user input.

Securing only prod

Securing all playbooks would give us some inconvenience – it’s only important in a prod environment. To run security only on prod, we can wrap all tasks in a block, where we would test if this environment needs securing.

- block: - name: wait for confirmation if required pause: prompt: "You are running playbook for {{ env }}, type environment name to confirm" register: confirm_response when: confirm_response_user_input is not defined - set_fact: confirm_response_user_input: "{{ confirm_response.user_input }}" when: confirm_response_user_input is not defined - name: fail if wrong confirmation fail: msg: "Aborting due to incorrect input, given <<{{ confirm_response_user_input }}>>, expected <<{{ env }}>>" when: env != confirm_response_user_input when: confirm_actions is defined and confirm_actions delegate_to: localhost run_once: true

Now, only production has the variable defined as confirm_actions: true and only production needs manual confirmation before running. We must delegate the whole block to localhost, because we need to set fact – and we want to do it once and for all hosts.

Summary

Using the solution given above, we achieved the following goals:

  • Confirmation is required before running a playbook on production.
  • Even if we run a few playbooks at once, only single confirmation is required.
  • It’s easy to secure additional roles.

— Previous article

TouK Hackathon - April 2021

Next article —

TouK hackathon (TouKathon) - April 2022

You May Also Like
DDevelopment & Design

Using WsLite in practice

TL;DR

There is a example working GitHub project which covers unit testing and request/response logging when using WsLite.

Why Groovy WsLite ?

I’m a huge fan of Groovy WsLite project for calling SOAP web services. Yes, in a real world you have to deal with those - big companies have huge amount of “legacy” code and are crazy about homogeneous architecture - only SOAP, Java, Oracle, AIX…

But I also never been comfortable with XFire/CXF approach of web service client code generation. I wrote a bit about other posibilites in this post. With JAXB you can also experience some freaky classloading errors - as Tomek described on his blog. In a large commercial project the “the less code the better” principle is significant. And the code generated from XSD could look kinda ugly - especially more complicated structures like sequences, choices, anys etc.

Using WsLite with native Groovy concepts like XmlSlurper could be a great choice. But since it’s a dynamic approach you have to be really careful - write good unit tests and log requests. Below are my few hints for using WsLite in practice.

Unit testing

Suppose you have some invocation of WsLite SOAPClient (original WsLite example):

def getMothersDay(long _year) {
    def response = client.send(SOAPAction: action) {
       body {
           GetMothersDay('xmlns':'http://www.27seconds.com/Holidays/US/Dates/') {
              year(_year)
           }
       }
    }
    response.GetMothersDayResponse.GetMothersDayResult.text()
}

How can the unit test like? My suggestion is to mock SOAPClient and write a simple helper to test that builded XML is correct. Example using great SpockFramework: 

void setup() {
   client = Mock(SOAPClient)
   service.client = client
}

def "should pass year to GetMothersDay and return date"() {
  given:
      def year = 2013
  when:
      def date = service.getMothersDay(year)
  then:
      1 * client.send(_, _) >> { Map params, Closure requestBuilder ->
            Document doc = buildAndParseXml(requestBuilder)
            assertXpathEvaluatesTo("$year", '//ns:GetMothersDay/ns:year', doc)
            return mockResponse(Responses.mothersDay)
      }
      date == "2013-05-12T00:00:00"
}

This uses a real cool feature of Spock - even when you mock the invocation with “any mark” (_), you are able to get actual arguments. So we can build XML that would be passed to SOAPClient's send method and check that specific XPaths are correct:

void setup() {
    engine = XMLUnit.newXpathEngine()
    engine.setNamespaceContext(new SimpleNamespaceContext(namespaces()))
}

protected Document buildAndParseXml(Closure xmlBuilder) {
    def writer = new StringWriter()
    def builder = new MarkupBuilder(writer)
    builder.xml(xmlBuilder)
    return XMLUnit.buildControlDocument(writer.toString())
}

protected void assertXpathEvaluatesTo(String expectedValue,
                                      String xpathExpression, Document doc) throws XpathException {
    Assert.assertEquals(expectedValue,
            engine.evaluate(xpathExpression, doc))
}

protected Map namespaces() {
    return [ns: 'http://www.27seconds.com/Holidays/US/Dates/']
}

The XMLUnit library is used just for XpathEngine, but it is much more powerful for comparing XML documents. The NamespaceContext is needed to use correct prefixes (e.g. ns:GetMothersDay) in your Xpath expressions.

Finally - the mock returns SOAPResponse instance filled with envelope parsed from some constant XML:

protected SOAPResponse mockResponse(String resp) {
    def envelope = new XmlSlurper().parseText(resp)
    new SOAPResponse(envelope: envelope)
}

Request and response logging

The WsLite itself doesn’t use any logging framework. We usually handle it by adding own sendWithLogging method:

private SOAPResponse sendWithLogging(String action, Closure cl) {
    SOAPResponse response = client.send(SOAPAction: action, cl)
    log(response?.httpRequest, response?.httpResponse)
    return response
}

private void log(HTTPRequest request, HTTPResponse response) {
    log.debug("HTTPRequest $request with content:\n${request?.contentAsString}")
    log.debug("HTTPResponse $response with content:\n${response?.contentAsString}")
}

This logs the actual request and response send through SOAPClient. But it logs only when invocation is successful and errors are much more interesting… So here goes withExceptionHandler method:

private SOAPResponse withExceptionHandler(Closure cl) {
    try {
        cl.call()
    } catch (SOAPFaultException soapEx) {
        log(soapEx.httpRequest, soapEx.httpResponse)
        def message = soapEx.hasFault() ? soapEx.fault.text() : soapEx.message
        throw new InfrastructureException(message)
    } catch (HTTPClientException httpEx) {
        log(httpEx.request, httpEx.response)
        throw new InfrastructureException(httpEx.message)
    }
}
def send(String action, Closure cl) {
    withExceptionHandler {
        sendWithLogging(action, cl)
    }
}

XmlSlurper gotchas

Working with XML document with XmlSlurper is generally great fun, but is some cases could introduce some problems. A trivial example is parsing an id with a number to Long value:

def id = Long.valueOf(edit.'@id' as String)

The Attribute class (which edit.'@id' evaluates to) can be converted to String using as operator, but converting to Long requires using valueOf.

The second example is a bit more complicated. Consider following XML fragment:

<edit id="3">
   <params>
      <param value="label1" name="label"/>
      <param value="2" name="param2"/>
   </params>
   <value>123</value>
</edit>
<edit id="6">
   <params>
      <param value="label2" name="label"/>
      <param value="2" name="param2"/>
   </params>
   <value>456</value>
</edit>

We want to find id of edit whose label is label1. The simplest solution seems to be:

def param = doc.edit.params.param.find { it['@value'] == 'label1' }
def edit = params.parent().parent()

But it doesn’t work! The parent method returns multiple edits, not only the one that is parent of given param…

Here’s the correct solution:

doc.edit.find { edit ->
    edit.params.param.find { it['@value'] == 'label1' }
}

Example

The example working project covering those hints could be found on GitHub.