Why Automation Matters : Your automation is your documentation

How many times have you been following a process defined in a knowledge base note, only to find something has been omitted, or is unclear? This may be because of empire building, laziness or more often oversight, but the result is the same. Unless your processes are well documented, you always run the risk of progress drawing to a halt when “the right person” is not present.

One of the great things about automation is, by definition, every step of the process must be defined. If person X is on holiday, you can be 100% sure all the steps to complete the automation are present.

Of course, this doesn’t stop people writing stupid, ugly and hard to understand code, but your development process should have some control over that. Even if it doesn’t, you know the answer is there. It must be there because the process works.

Does that mean you don’t need to document automations?

No. The automations should be self documenting. I don’t mean that in the sense that “my code is so good it’s self-documenting”, which is the calling card of the lazy developer. I mean that automation code in your source control system should be documented. Markdown is a quick and easy tool that allows us to easily document our code, and the good thing about it is it remains close to the code. It’s right next to it in the repository. When we change our code, we should revise our documentation where necessary. The documentation becomes a living document, rather than some 1000 page word document that nobody ever reads, and nobody updates.

But documentation sucks!

Documentation gets a really bad rap because most people are doing it wrong. They fall into one of these traps.

  • They produce too little, which means people are unlikely to find what they are looking for.
  • They produce too much, which makes it daunting to look at, so nobody bothers.
  • It’s overly formal, which is dry and boring.
  • It’s hidden, or at least separate to the code, so people might not even know it exists.

Basic pointers and how-to examples are good enough for 90% of the cases, so make these the focus of your documentation. You can always give links to more detailed documentation for those people that need a little more. The context is slightly different, but this post on Structuring Content should give you some clues about how to structure your documentation. After all, documentation is content. 🙂

Conclusion

For some companies an automation or infrastructure as code project may well be the first time in their company history that they have got everything about a process documented. That has to be a positive result for the company!

Check out the rest of the series here.

Cheers

Tim…

Why Automation Matters : It doesn’t get much simpler than this!

Just a little story about something that happened recently…

The July Oracle quarterly security patches dropped, along with the downstream OpenJDK releases a little later. As soon as the OpenJDK release dropped I updated all our non-production Oracle REST Data Services (ORDS) middle tier to the latest and greatest. Production will follow shortly. I figured that was the end of it…

On Friday evening I noticed a post by Jeff Smith saying version 22.2.1 of SQLcl and ORDS had dropped. Now it was Friday evening, and I typically don’t work on Fridays, but I really didn’t want to have this hanging over me all weekend, so this is what I did…

  • Download the software.
  • Upload the software to Artifactory.
  • Change a couple of files in Git, specifying the new software versions.
  • Press a button in TeamCity to rebuild the ORDS Docker image and push the new image to JFrog Platform.
  • Press a button in TeamCity to redeploy all the non-production ORDS containers.

The whole process took a few minutes, and I was confident it would work because it’s all automated and works every time. I sent this message to Jeff.

I {expletive} love automation. I just noticed your post about 22.2.1 of SQLcl and ORDS. I logged on to work. Updated a couple of files in git and pressed a button in TeamCity. New ORDS Docker image built and pushed to all non-prod systems. Boom…

This is why automation matters. The combination of picking the right platform, in this case containers, and investing a little time in the automation means we can react really quickly to new releases. It doesn’t get much simpler than this!

Check out the rest of the series here.

Cheers

Tim…

PS. This post explains the application topology we use for ORDS and APEX.

Video : Ansible Playbooks : Roles

In today’s video we demonstrate how to use role with Ansible Playbooks.

The video is based on the following article.

You might find some useful stuff here.

The star of today’s video is Anton Els, who I first met when he worked for DBvisit.

Cheers

Tim…

Video : Ansible Playbooks : Users and Groups

In today’s video we demonstrate how to manage users and groups with Ansible Playbooks.

The video is based on the following article.

You might find some useful stuff here.

The star of today’s video is Connor McDonald of AskTom fame. You can check out his YouTube channel here.

Cheers

Tim…

Video : Ansible Playbooks : Tags


In today’s video we demonstrate how to use handlers in Ansible Playbooks.

The video is based on the following article.

You might find some useful stuff here.

The star of today’s video is Tanel Poder, who thinks he’s at the bow of a Viking ship by the look of it. 🙂

Cheers

Tim…

ORDS and APEX 22.1 : Vagrant and Docker Builds

I was on top of the recent ORDS 22.1 release, but somehow I managed to miss the APEX 22.1 release. Here’s an update on what’s been going on with my builds…

Vagrant Builds

A number of my Vagrant database builds include APEX. Those that do have been updated to use APEX 22.1. You can find them here.

They had already been updated to use the latest versions of Java, Tomcat, ORDS and SQLcl where appropriate, so the APEX upgrade was a small change. The ORDS update was done 11 days ago. It was a bigger update, as the installation process for ORDS 22.1 has changed quite a bit. I wrote about that here.

You can read my beginner’s guide to Vagrant here.

Docker/Container Builds

I have some ORDS containers that include the APEX images, so those image builds have been updated to use ORDS 22.1 and APEX 22.1 images now.

APEX is also included in the database builds. You can find them here.

I was a little slow to add the updates to the Docker builds. The Tomcat and SQLcl changes were done a couple of weeks ago, but I’ve only added the Java, ORDS and APEX changes today. I held back a little on the ORDS 22.1 changes, as I was rewriting a bunch of articles that were affected by the installation and configuration changes.

You can read my Docker/Container articles here.

Real Life

We probably won’t be putting APEX 22.1 live until the next patching cycle, which will be July. In the past I could be quite aggressive about the upgrades, but as APEX is becoming more important in the organisation, the rollout of updates has to be a bit more considered. 🙂

The same will probably be true for the ORDS 22.1 rollout. We run ORDS in containers, so it’s really quick and easy to replace all the infrastructure, but I wanted to be a bit cautious because of all the changes in the new version. Having played with it a bit now, I’m feeling a lot more confident, but at the time we were starting our patching cycle I was too nervous to include it.

As far as home systems are concerned, I only use the latest and greatest, unless there is a compelling reason not to. 😉

Cheers

Tim…

Video : Ansible Playbooks : Handlers

In today’s video we demonstrate how to use handlers in Ansible Playbooks.

The video is based on the following article.

You might find some useful stuff here.

The star of today’s video is my dad, Graham Wood, who spend most of his time galivanting and spending my inheritance, which I’ve been waiting patiently for!

Cheers

Tim…

Video : Ansible Playbooks : Host and Group Variables

In today’s video we demonstrate how to use lists and loops in Ansible Playbooks.

The video is based on the following article.

You might find some useful stuff here.

The star of today’s video is Toon Koppelaars, famous for The Helsinki Declaration (IT Version), which you may know better these days as the SmartDB approach to building applications.

Cheers

Tim…

Why Automation Matters : Taking a step backward to move forward!

There was a small thread on Twitter today about unit testing, which I’m going to extrapolate to automation generally.

There can be a certain reluctance towards writing unit tests. I guess the thinking goes, I’m here to write code and solve problems, not waste time writing test code. Unit test quality and code coverage varies, but it’s not unusual to hear people say their unit tests have more lines of code than the code they are testing. I guess that adds to the reluctance. What some people fail to see is once the unit tests are written, they may never have to manually test that code again. If the code changes over time, the unit test may only need a few small tweaks to bring them up to date. Over the lifetime of the project, that initial investment can represent a massive saving…

This is true of many aspects of automation. Yes, you can create a new database in a few minutes by clicking some buttons on a GUI, and that’s fine when you get one request a week. What happens when developers want a new database for every test they run? Your button presses don’t scale. If instead you automated the process, you would never have to manually create a database again, and developers could build and burn databases to their heart’s content.

You could be the gatekeeper who runs scripts in the production environment, but what happens when you’re on holiday? What happens when the rate of production deployments increase? You become the bottleneck doing meaningless work. If you had helped build a deployment pipeline, those production deployments could happen automatically, with the correct governance of course.

I’ve said it before in this series, but I’ll say it again. Working in the tech industry is like swimming upriver. You can’t just stop swimming, because that means you are moving backwards. If more water is added to the river, the flow rate increases and you are overwhelmed. You have to keep trying to improve your efficiency to protect yourself against what is coming round the next bend…

I know it can be hard when you have a pressing deadline, but you really are taking a step backward to move many steps forward!

Check out the rest of the series here.

Cheers

Tim…

How are you provisioning your databases on-prem and in the cloud? Poll results discussed.

Following on from my previous post, I wanted to discuss the results of the polls regarding database provisioning.

This was the first question I asked.

How are you provisioning your databases on-prem and in the cloud?

A couple of years ago I stopped putting GUI installation articles on my website. They look pretty and seem to get a lot of views, but I thought posting them was wrong because I never use GUI installations. Posting them felt like I was sending the wrong message. I wrote about that here. This was one of the reasons I lead with this question. I was pleased with the results of the poll.

  • Using GUI: I understand some people don’t want to take a step backwards to move forwards, but at nearly 20%, this number is still too high IMHO. You can’t check button clicks into version control. I’m sure some smart arse will tell me you can if you use Robotic Process Automation (RPA) to click them. 🙂
  • Shell scripts: If I’m honest I thought 34% was on the low side. I was expecting more people to be using silent installations using shell scripts, but the number is lower because of the next option. If people have made a big investment into writing robust shell scripts with good error handling, I can understand the reluctance to move away from them. Ansible and Terraform are nice, but they are not magic. 🙂
  • Ansible/Terraform/Other: This was actually the surprise of bunch. I wasn’t expecting this number to be so high, but I was pleasantly surprised. The previous post showed lots of people running their databases in the cloud, which has no doubt helped to drive the uptake of automation tools like Ansible and Terraform. Happy days!

Spurred on by a question from Jasmin Fluri, I asked the following question to drill down a little more.

For people using Ansible and/or Terraform, how automated is your process?

This was also a pleasant surprise.

  • We run it manually: I was expecting this to be way ahead of the pack, but at nearly 38% I was wrong, which made me happy. I have no problem if people are running Ansible or Terraform manually. A pipeline is just a bunch of building blocks threaded together. The fact people have taken the time to build these blocks is great. Threading them together is nice, but it’s not the “be all and end all”. The important bit is the definitions of the systems are in code!
  • Automated pipeline: Over 33% made me happy. My assumption was this would be lower, and I wrong and I’m glad.
  • Terrahawks was a cartoon: The people who picked this were wrong! Terrahawks was a kids TV show using puppets, not animation. I’m really surprised nobody noticed this. The community let me down! 😉 If we discount this response from the mix, it makes the other two responses close to 50:50, which is cool.

On a bit of a tangent, I wanted to know how dominant Git was these days.

What Version Control System (VCS) are you suing for your database scripts and code?
  • Git – On Prem: I knew Git would dominate, but I wasn’t sure if people would be hosting their repositories on-prem or in the cloud. With a response of over 30%, that means nearly half of the Git users were hosting their repositories on-prem, which was higher than I expected.
  • Git – Cloud-based: I expected this to dominate, so 37% was a little lower than I expected. Only a little over half of the Git users were using cloud-based repositories. We use cloud-based Git repositories, but we always keep a backup on-prem. Just in case.
  • Other VCS – Not Git: I expected this to have a reasonable showing as VCS software like Subversion used to be really popular, so I knew things would linger. Nearly 19% isn’t bad. I don’t think there is anything wrong with using something other than Git, but Git has become so pervasive in tooling it probably makes sense to take the plunge.
  • VCS is for wimps: I’m hoping nearly 13% of the respondents were picking this to wind me up, but I suspect they weren’t. If you are not currently using version control, please start!

Version control is at the heart of automation, DevOps, Infrastructure as Code (IaC) and all that funky business, so if people can just get that right they have taken the first step on the journey.

So overall this makes very pleasant reading. Lots of people are provisioning databases using some form of scripting, rather than GUIs, and a bunch of people are automating that provisioning. This is what I wanted to hear.

Cheers

Tim…

PS. You know the caveats. These are small sample sizes. My audience has an Oracle bias. I’m no expert at automation, DevOps and the cloud. Just a keen dabbler.