Mastering CloudForms Automation

Preface

Red Hat CloudForms is a powerful cloud management platform that allows us to efficiently manage our virtual infrastructure and Infrastructure as a Service (IaaS) clouds. Part of this efficient management involves automating many of the day-to-day tasks that would otherwise require manual involvement, or time-consuming and possibly error-prone repetitive steps.

This book is an introduction and how-to guide to working with the Automate feature of Red Hat CloudForms.

CloudForms Automate simplifies our lives and increases our operational efficiency. It allows us to do such things as:

• Eliminate many of the manual decisions and operations involved in provisioning virtual machines and cloud instances.

• Load-balance our virtual machines across our virtual infrastructure to match our organization’s way of working, be it logical (e.g., cost center, department), operational (e.g., infrastructure lifecycle environment), or categorical (e.g., server role or virtual machine characteristic).

• Create service catalogs to allow our users to provision virtual machines from a single Order button.

• Create autoscalable cloud applications in which new virtual machines are dynamically provisioned on demand.

• Manage our complete virtual machine lifecycle.

• Integrate our virtual machine provisioning workflow with the wider enterprise—for example, automatically registering new virtual machines with a Red Hat Satellite server.

• Implement intelligent virtual machine retirement workflows that de-allocate resources such as IP addresses and unregister from directory services.

A Brief Word on Terminology

This book refers to Automate as the CloudForms capability or product feature, and automation as the thing that Automate allows us to do. The Automation Engine allows us to create intelligent automation workflows and run automation scripts written in Ruby.

Who Should Read This Book?

This book will appeal to cloud or virtualization administrators who are interested in automating parts of their virtual infrastructure or cloud computing environment. Although it’s primarily aimed at those with some familiarity with Red Hat CloudForms, many of the concepts and terms, such as orchestration and automation workflows, will be easily understood even to those unfamiliar with the product.

Automate can be one of the more challenging aspects of CloudForms to master. The practitioner requires an unusual blend of skills: a familiarity with traditional “infrastructure” concepts such as virtual machines, hypervisors, and tenant networks, but also a flair for scripting in Ruby and mastery of a programming object model. There is no black magic, however, and all of the skills can be learned if we are shown the way.

The book assumes a reasonable level of competence with the Ruby language on the part of the reader. There are many good online Ruby tutorials available, including Codecademy’s “Learn to program in Ruby”.

The book also presumes a comfortable level of working experience and familiarity with the Web User Interface (WebUI) features of CloudForms, particularly Insight, Control, tagging, and provisioning VMs via the Lifecycle → Provision VMs entry point. Many of these features will be automated as we follow the examples in the book, and so an understanding of why tagging is useful (for example) is helpful.

Note

CloudForms is a web application, so interaction is predominantly via the browser-based WebUI. We only use a command-line terminal when we initially configure a CloudForms appliance, or when troubleshooting or examining logfiles.

Why I Wrote This Book

I was fortunate in having two of the early masters of CloudForms Automate, John Hardy and Brad Ascar from Red Hat, teach me the fundamentals of automation. They opened my eyes to the possibilities and whetted my appetite to learn more. This book is an attempt to pass on that knowledge, supplemented with my real-world experience as an architect at Red Hat, so that others can use this really powerful feature of the product.

I’ve tried to structure the book around the periodic revelations that I’ve had while learning CloudForms Automate, the if only I’d known that weeks ago moments. In places, this includes some deep code examination and theory, and in-depth logfile analysis, but hopefully this will help the reader’s understanding process (it did for me). I also try to illustrate the theory with code snippets and examples.

Versions and Releases

Although the descriptions and screenshots in this book are taken from Red Hat CloudForms 3.2 and 4.0, most of the content also applies to the ManageIQ Botvinnik and Capablanca releases. CloudForms 4.0 (ManageIQ Capablanca) is the latest release at the time of writing.

Navigating This Book

The book is divided into six parts.

Part I, Working with CloudForms Automate

Chapter 1, Introduction to CloudForms, sets the scene and describes the capabilities of CloudForms as a cloud management product.

Chapter 2, Introduction to the Automate Datastore, takes us on a tour of the objects that we work with when we use the Automate capabilities of CloudForms.

Chapter 3, Writing and Running Our Own Automation Scripts, introduces us to writing automation scripts in Ruby, with a simple “Hello, World!” example.

Chapter 4, Using Schema Variables, shows how we can use our instance’s schema to store and retrieve variables.

Chapter 5, Working with Virtual Machines, demonstrates how to work with an Automation Engine virtual machine object, and how to run an automation script from a custom button in the WebUI.

Chapter 6, Peeping Under the Hood, introduces some background theory about Rails models, and how CloudForms abstracts these as service models that we work with when we write our automation scripts.

Chapter 7, $evm and the Workspace, takes us on a tour of the useful $evm methods that we frequently use when scripting, such as $evm.vmdb and $evm.object.

Chapter 8, A Practical Example: Enforcing Anti-Affinity Rules, is a real-world, full-script example of how we could use the techniques learned so far to implement anti-affinity rules in our virtual infrastructure, based on tags.

Chapter 9, Using Tags from Automate, describes in detail how we can create, assign, read, and work with tags from our Ruby automation scripts.

Chapter 10, Investigative Debugging, discusses the ways that we can discover which Automate objects are available to us when scripting. This is useful both from an investigative viewpoint when we’re developing scripts, and for debugging our scripts when things are not working as expected.

Chapter 11, Ways of Entering Automate, shows us the various workflow entry points into the Automate Datastore. It also illustrates how we can determine programmatically the way that our automation script has been called, enabling us to create re-usable scripts.

Chapter 12, Requests and Tasks, illustrates how more advanced Automate operations are separated into a Request stage, which requires administrative approval to progress into the Task stage. The corresponding request and task objects are described and their usage compared.

Chapter 13, State Machines, introduces us to state machines and how we can use them to intelligently sequence our workflows.

Chapter 14, More Advanced Schema Features, discusses the more advanced but less frequently used schema features: messages, assertions, and collections.

Chapter 15, Event Processing, describes the way that CloudForms responds to external events such as a virtual machine shutting down, and traces the event handling sequence through the Automate Datastore. It also shows how Automate manages its own internal events such as request_started.

Part II, Provisioning Virtual Machines

Chapter 16, Provisioning a Virtual Machine, introduces the concept of virtual machine provisioning, the most complex out-of-the-box Automate operation that is performed by CloudForms.

Chapter 17, The Provisioning Profile, describes how the provisioning profile is referenced to determine the initial group-specific processing that is performed at the start of a virtual machine provisioning operation.

Chapter 18, Approval, shows how the approval workflow operates and how we can adjust auto-approval criteria, such as the number of virtual machines to be provisioned or the amount of storage, to suit our needs.

Chapter 19, Quota Management, gives details of the new CloudForms 4.0 quota handling mechanism and how it enables us to establish quotas for tenants or groups.

Chapter 20, The Options Hash, explains the importance of a data structure called the options hash and how we can use it to retrieve and store variables to customize the virtual machine provisioning operation.

Chapter 21, The Provisioning State Machine, discusses the stages in the state machine that governs the sequence of operations involved in provisioning a virtual machine.

Chapter 22, Customizing Virtual Machine Provisioning, is a practical example showing how we can customize the state machine and include our own methods to add a second hard disk during the virtual machine provisioning operation.

Chapter 23, Virtual Machine Naming During Provisioning, explains how we can customize the naming logic that determines the name given to the newly provisioned virtual machine.

Chapter 24, Virtual Machine Placement During Provisioning, explains how we can customize the placement logic that determines the host, cluster, and datastore locations for our newly provisioned virtual machine.

Chapter 25, The Provisioning Dialog, describes the WebUI dialogs that prompt for the parameters that are required before a new virtual machine can be provisioned. The chapter also explains how the dialogs can be customized to expand optional ranges for items like size of memory or to present a cut-down, bespoke dialog to certain user groups.

Chapter 26, Virtual Machine Provisioning Objects, details the four main objects that we work with when we write Ruby scripts to interact with the virtual machine provisioning process.

Chapter 27, Creating Provisioning Requests Programmatically, shows how we can initiate a virtual machine provisioning operation from an automation script, instead of from the WebUI.

Chapter 28, Integrating with Satellite 6 During Provisioning, is a practical example showing how to automate the registration of a newly created virtual machine with Red Hat Satellte 6, both as a host and content host.

Part III, Working with Services

Chapter 29, Service Dialogs, introduces the components that make up a service dialog, including elements that can be dynamically populated by Ruby methods.

Chapter 30, The Service Provisioning State Machine, discusses the stages in the state machine that governs the sequence of operations involved in creating a service.

Chapter 31, Catalog{Item,Bundle}Initialization, describes two specific instances of the service-provisioning state machine that have been designed to simplify the process of creating service catalog items and bundles.

Chapter 32, Approval and Quota, shows the approval workflow for services, and how the new consolidated quota-handling mechanism for CloudForms 4.0 also applies to services.

Chapter 33, Creating a Service Catalog Item, is a practical example showing how to create a service catalog item to provision a virtual machine.

Chapter 34, Creating a Service Catalog Bundle, is a practical example showing how to create a service catalog bundle of three virtual machines.

Chapter 35, Service Objects, is an exposé of the various objects that work behind the scenes when a service catalog item is provisioned.

Chapter 36, Log Analysis During Service Provisioning, is a step-by-step walk-through, tracing the lines written to automation.log at various stages of a service provision operation. This can help our understanding of the several levels of concurrent state-machine activity taking place.

Chapter 37, Service Hierarchies, illustrates how services can contain other services and how we can arrange our service groups into hierarchies for organizational and management convenience.

Chapter 38, Service Reconfiguration, describes how we can create reconfigurable services. These are capable of accepting configuration parameters at order time via the service dialog and can later be reconfigured with new configuration parameters via the same service dialog.

Chapter 39, Service Tips and Tricks, mentions some useful tips to remember when we are developing services.

Part IV, Retirement

Chapter 40, Virtual Machine and Instance Retirement, discusses the retirement process for virtual machines and instances.

Chapter 41, Service Retirement, discusses the retirement process for services.

Part V, Integration

Chapter 42, Calling Automation Using the RESTful API, shows how we can make external calls into CloudForms to run Automate instances via the RESTful API. We can also return results to our caller in this way, enabling us to create our own pseudo-API endpoints within CloudForms.

Chapter 43, Automation Request Approval, explains how to customize the default approval behavior for automation requests, so that nonadministrators can submit RESTful API requests without needing administrative approval.

Chapter 44, Calling External Services, shows the various ways that we can call out from Automate to integrate with our wider enterprise. This includes making outbound REST and SOAP calls, connecting to MySQL databases, and interacting with OpenStack using the fog gem.

Part VI, Miscellaneous

Chapter 45, Distributed Automation Processing, describes how CloudForms Automate has been designed to be horizontally scalable. The chapter describes the mechanism by which automation requests are distributed among multiple appliances in a region.

Chapter 46, Argument Passing and Handling, explains how arguments are passed to, and handled internally by, Automate methods for each of the different ways that we’ve called them up to this point in the book.

Chapter 47, Miscellaneous Tips, closes the book with some useful tips for Automate method development.

Online Resources

There are several online resources that any student of CloudForms Automate should be aware of.

Official Documentation

The official Red Hat documentation for CloudForms is here: http://red.ht/1rfeDkq.

Code Repositories

One of the best sources of reference material is the excellent CloudForms_Essentials code collection maintained by Kevin Morey from Red Hat (https://github.com/ramrexx/CloudForms_Essentials). This contains a wealth of useful code samples, and many of the examples in this book originate from this source.

There is also the very useful Red Hat Consulting (https://github.com/rhtconsulting) GitHub repository maintained by several Red Hat consultants.

Forums

The ManageIQ project hosts the ManageIQ Talk forum.

Blogs

There are several blogs that have good CloudForms-related articles, including some useful “notes from the field.” These include:

• CloudForms NOW (http://cloudformsblog.redhat.com/)

• Christian’s blog (http://www.jung-christian.de)

• Laurent Domb OSS blog (http://blog.domb.net/)

• ALL THINGS OPEN (http://allthingsopen.com/)

• TigerIQ (http://www.tigeriq.co/)

Conventions Used in This Book

The following typographical conventions are used in this book:

Italic

Indicates new terms, URLs, email addresses, filenames, and file extensions.

Constant width

Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords.

Constant width bold

Shows commands or other text that should be typed literally by the user.

Constant width italic

Shows text that should be replaced with user-supplied values or by values determined by context.

Tip

This element signifies a tip or suggestion.

Note

This element signifies a general note.

Warning

This element indicates a warning or caution.

Using Code Examples

Supplemental material (code examples, exercises, etc.) is available for download at https://github.com/pemcg/oreilly-mastering-cloudforms-automation.

This book is here to help you get your job done. In general, if example code is offered with this book, you may use it in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission.

We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Mastering CloudForms Automation by Peter McGowan (O’Reilly). Copyright 2016 Red Hat, Inc., 978-1-4919-5722-6.”

If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at [e-mail].

Safari® Books Online

Note

Safari Books Online is an on-demand digital library that delivers expert content in both book and video form from the world’s leading authors in technology and business.

Technology professionals, software developers, web designers, and business and creative professionals use Safari Books Online as their primary resource for research, problem solving, learning, and certification training.

Safari Books Online offers a range of plans and pricing for enterprise, government, education, and individuals.

Members have access to thousands of books, training videos, and prepublication manuscripts in one fully searchable database from publishers like O’Reilly Media, Prentice Hall Professional, Addison-Wesley Professional, Microsoft Press, Sams, Que, Peachpit Press, Focal Press, Cisco Press, John Wiley & Sons, Syngress, Morgan Kaufmann, IBM Redbooks, Packt, Adobe Press, FT Press, Apress, Manning, New Riders, McGraw-Hill, Jones & Bartlett, Course Technology, and hundreds more. For more information about Safari Books Online, please visit us online.

How to Contact Us

Please address comments and questions concerning this book to the publisher:

• O’Reilly Media, Inc.
• 1005 Gravenstein Highway North
• Sebastopol, CA 95472
• 800-998-9938 (in the United States or Canada)
• 707-829-0515 (international or local)
• 707-829-0104 (fax)

We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at http://shop.oreilly.com/product/0636920050735.do.

To comment or ask technical questions about this book, send email to [e-mail].

For more information about our books, courses, conferences, and news, see our website at http://www.oreilly.com.

Find us on Facebook: http://facebook.com/oreilly

Follow us on Twitter: http://twitter.com/oreillymedia

Watch us on YouTube: http://www.youtube.com/oreillymedia

Acknowledgments

Anyone who works for Red Hat and starts to write a book like this has the advantage of working in an incredible culture of knowledge sharing (one of Red Hat’s mottos is “we grow when we share”). There is a long list of people who have helped me in one way or another, but in particular the following people deserve a special mention.

For code samples (many of which have been used in this book), ideas for content, and general sounding-board advice over a long period, thanks goes to Kevin Morey, Bill Helgeson, Cameron Wyatt, Tom Hennessy, Lester Claudio, Brett Thurber, Fabien Dupont, Ed Seymour, and George Goh.

I’ve lost count of the number of times that Christian Jung, Krain Arnold, Loic Avenal, and Nick Catling from the EMEA CloudForms “Tiger Team” have helped me, and made me wonder now why didn’t I think of that?

For their patience with my questions and help in proofreading this book for technical correctness, I’d like to thank Tina Fitzgerald, Madhu Kanoor, and Greg McCullough from the CloudForms/ManageIQ engineering Automate team.

For their suggestion of turning a documentation hobby project borne of frustration into a real book, and for the behind-the-scenes organization to make it happen, I am indebted to the CloudForms marketing team members Marty Wesley and Geert Jensen.

I would like to thank Brian Anderson from O’Reilly for his encouragement and patience with a new and naive author, and Mark Reynolds from HPE for reviewing the book from a useful non–Red Hat point of view.

And finally, a big thank you to my wife Sarah, for her tireless support and encouragement, and tolerance of the other woman in my life for the past two years, named Ruby.