RUNBOOK CONCEPTS


In order to use RunBook Orchestrator more effectivelt, let's first understand some of the important RunBook concepts. this section, we will go through the basic explanation for all the key run-book concepts:

RunBook Orchestrator : RunBook Orchestrator allows users to create, edit, document, and execute RunBooks. The figure above showed an example of multi-language run-book being edited using RunBook Orcehstrator. It provides real-time progress for each step of the deploy process. Operators are able to see exactly what step their process is executing and look back on details of previous steps (success, failure, skip, etc).

RunBook Types : There are two types of RunBooks: Standard RunBooks & Utility RunBooks.

Standard RunBooks are expected to be ran from the first step to the last step. Users can skip few steps while running, in some cases, but in most cases, it makes sense to run all the steps from start to end.

For Example: One can create a Tomcat server installation RunBook, with steps like download tomcat binary, un-tar the binary, change permission, execute the startup script. In this RunBook example, it is expected to execute the steps from start to finish.

Utility RunBooks are expected to be ran on individual step basis.

For example: One can create an AWS S3 Utility RunBook, with steps like create S3 bucket, delete s3 bucket, change permission, and so on. In this case, it is not expected to run all the steps of this RunBooks from start to finish, instead each step can be run separately as needed.

RunBook Steps : Each RunBook is composed of one or more steps. Each step represents a unit of work. Step can be written in any language including Shell script, PERL, Ruby, Python, Scala, Groovy, etc.

By composing the RunBook of multiple steps, DevOps can orchestrate pretty complex deployments, distributed across multiple nodes. During execution of RunBook, DevOps can decide which step to run on which node(s).

RunBook Step Types : Each RunBook step can be one of the following types:

Step Name Description
Command This step type represents any linux system command.
Multi-Command This step type represents list of linux system commands.
Script This step type represents script written in any language including Shell script, PERL, Ruby, Python, Scala, Groovy, etc.
Multi-Script This step type represents list of scripts written in any language including Shell script, PERL, Ruby, Python, Scala, Groovy, etc.
Multi-OS Script This step type represents list of scripts - one per OS - written in any language including Shell script, PERL, Ruby, Python, Scala, Groovy, etc.
File Upload or download file step.
RunBook Reference Reference to another run-book.
Save Text This step type provides an easy way to save text file.
Replace Text This step type provides an easy way for replacing text in the specified file.
Properties Transfer This step type outputs all the user-specified properties and its value in the specified text file.

 

Properties : Properties are tokens specified inside the script or command within any step, that gets replaced with dynamic value at runtime. The value for the properties are specified by the user just before executing the RunBook. RunBook supports two type of properties: RunBook Properties & Step Properties.

Global Properties : This properties are defined at RunBook level and can be used in any steps. Basically if a property is to be shared by multiple steps, then its a candidate for being RunBook level property.

Step Properties : Step properties are defined at step level, and are only applicable for that particular step.

Property Types : Each RunBook property can be one of the following types :

Property Type Description
Text Property value is a simple text
Password If Property value is a secret value, by setting the property as type "Password", ensures the value is not visible on UI as the user types it.
Select Comma seperate list of values
Node Set Single display name to represent a set of nodes
Node IP Node IP address, auto-filled based on the nodes already on-boarded into the system
Grid Dynamic grid for user to add more than one record, as needed.
Grid (JSON Output) Dynamic grid for user to add more than one record, as needed. The output of the grid is converted into JSON format at runtime before being made available to any step during run-book execution.

Generated Properties : Generated Properties are a powerful conduit for sharing properties generated in one RunBook Step with other steps that will be executed. When users want the information to be shared between steps, generated properties is an approach to go for.

Node Set : If different steps within the RunBook are expected to be executed on same nodes, then by giving the same Node Set name to each of those steps, allows users of the RunBook to just have to select Nodes for one step, and the rest of the steps with same Node Set, automatically are assigned the same set of Nodes.

Let's take an example where a run-book has 8 steps, and for 5 out of those 8 steps, they are supposed to be executed on same set of Nodes. By defining a Node Set, and associating that Node Set with all those 5 steps, comes in very handy when executing the run-book, as the user does not have to repeatedly associate all the nodes with each of those 5 steps.

Dynamic Node Tag : There will be scenarios where, the nodes will be created during one of the steps, and later steps might be executed on these dynamically created nodes. To associate the step with the nodes that will be created dynamically during run-book execution, one has to define a dynamic node tag, and associate the appropriate step(s) with that dynamic node tag. Dynamic Node Tag and the Nodes Import File Path, both concepts work in tandem, allowing users to execute steps on nodes that will be created dyanmicall during the execution of run-book in one of the prior steps.

Nodes Import Path : The Nodes Import file path allows the step to provide information about dynamically created nodes to the RunBook Orchestrator, so that information can be used in later steps in tandem with Dynamic Nodes Tag.

Transient Nodes : Transient nodes, are the nodes that are not on-boarded into the DivineCloud. These are temporary nodes, on which some execution needs to be performed for just one or two times, so not worth on-boarding them into DivineCloud permenantly. For such temporary nodes, users can add them as Transient Nodes, during run-book execution, and can get the task accomplished, without having to permanently on-board them into the DivineCloud.

Group Steps : DevOps can decide how they would like the users of RunBook to see the steps of RunBook. If the RunBook is to be included as reference in the step of another RunBook, then by selecting Group Steps, the whole runbook will be visible as a single step within the referring RunBook.

For Example: Let's say there is a RunBook called Deploy Web Application. Let's say this RunBook refers to another RunBook called Install Tomcat Server, which has 4 steps. When the user executes the Deploy Web Application RunBook, they would see the Install Tomcat Server as a single step instead of 4 steps, if the Group Steps option is selected.

RunBook Repository : RunBook repository provides a way of organizing run-books in groups. RunBook Repository is defined as a folder in a file system by user, and this folder acts as a root folder for storing all the run-books belonging to that run-book repository.