I have updated this page on 22nd Jan 2019 to introduce improvements over the original Action template and module structure. I have introduced the new logger object and JSDoc documentation styles into my code.
Managing your code base in vRealize Orchestrator can be quite challenging and complex. Often, you won’t realise this until you’ve reached a point where it becomes difficult and time consuming to both organise or locate existing code that you have written. In this post, I am going to suggest ways to help you organise your code better, using methods that I have adopted with my time using vRO.
I am not suggesting this be the perfect solution, but it should provide a working standard to adopt to your own needs. I would also argue that the extra time spent getting this in place on the outset, will lead to time saved later on.
Just for reference, from this point on, I am going to refer to ‘code base‘ and ‘actions‘ interchangeably, because your vRO actions ARE your code base. Almost every single line of code you write in vRO should be in an action (I will discuss this in more detail in a later post which I will link here).
Here are some general principles I like to follow when creating actions: As a general rule, actions should:
- Contain small, manageable chunks of code that perform a specific task. Actions are just functions and just like any function, it should contain code that performs a specific task. If your action is doing many different tasks, then consider breaking these down into multiple, smaller actions.
- Validate inputs. I appreciate that some may debate this idea, but actions are not ‘private functions’. They are public code where you can never guarantee that the action ‘caller’ is properly validating its inputs. This is the nature of vRO, it is a ‘hub’ that has many different uses cases and scenarios for executing the same actions. I have seen dozens of cases where developers and support engineers have wasted time tracking unexpected errors;
- Be named appropriate to the task they perform. I generally like to use verbs in my action names, like, ‘getVirtualMachineNames’, ‘getVirtualMachineNetworks’ or ‘setCustomProperty’. Actions named this way will make it easier for other developers to identify what they are used for;
- Have variables declared in a single block. This will just make it easier to see what variables are being used. The data type can also be defined, but is not always necessary or as important;
- Provide consistent logging throughout. Make it so, the action almost tells the story of what is happening. Don’t go overboard, but generally a before, during and after style to logging works quite well;
- Nesting actions within an action is generally ‘OK’ but keep it to a minimum if possible. Too many nested actions can create depth that may be more difficult to maintain and troubleshoot later on. Typical use cases are ‘helper’ or ‘utility’ actions (you’ll be completely forgiven with actions used for workflow presentation as these are a pain);
- Perform singular tasks. Don’t write actions that perform plural tasks. Write the singular version first, then use a looping mechanism that re-uses the singular action (there are also ways this can be achieved with performance in mind in vRO). This way you’ll only have 1 version of the code;
- Be based on a user-defined template. Yup, I’m not crazy. Have a defined template (aka boilerplate) set out on how an action should generally look and have the team follow this. It will make code reviews far easier;
- Always use camel cased alphabetical characters (no dots);
Before purchasing or installing the software one of the first things you need to understand is what vRA is trying to solve. Unlike what VMware has released previously, vRA is a very different and tries to solve the problems related to managing multiple cloud platforms and the end to end delivery of IT services. Yes, there are a lot of tools out there that can help in the delivery of these services but it very quickly starts to turn into a complex mismash of applications and processes. It’s also important to point out that vRA is not exclusive to vSphere but is designed to be platform agnostic. Think of vRA operating as the management plane in your data centre that plugs into all the services around it.
So when I talk about ‘end to end delivery of IT services’ what exactly am I referring to? Well, consider the example process below of bringing a new virtual server into service:
- End user requests new virtual server, provides details and submits request to IT support services;
- A change is raised on the ITSM CMDB platform;
- Wait for change to be approved before provisioning starts (alternatively the request could be rejected and process cancelled);
- When approved, begin the provisioning process;
- Get the next available hostname (i.e. using a prefix and the next available number increment);
- Request and reserve the next available IP address from the IPAM software and update the record to reflect the new server being provisioned;
- Provision the virtual server with specific hardware configuration;
- Add/update DNS records;
- Add server to the Active Directory domain and place into the correct Organization Unit;
- Update OS with latest security patches;
- Add to existing firewall rules;
- Generate SSL certificates;
- Install software such as Anti-Virus and applications;
- Add new Configuration Item with server details;
- Update server inventory;
- Add to monitoring system;
- Mark change as complete;
- Email End user that requested the virtual server that it is now ready;
You’ll agree, that this is a lot of steps for provisioning something like a virtual server and will involve multiple different teams (and think about doing this on many different cloud platforms). Most of the time, a lot of these steps are performed manually using run books but are sometimes overlooked and can cause delays in fulfilling the request or lead to problems later, like outdated information. We have tools like Puppet which help us with deployments, software installations, etc. but most of these are very Linux focused. They also do not address the other steps, or at least not in a very friendly way.
Finally, and more interestingly, think about when the virtual server is taken out of service or decommissioned. This is almost always where things get messy. I have seen really well laid out and robust commissioning procedures but nothing to support the decommissioning. Often, it’s a case of ‘best effort’ and items get missed and are usually discovered later, often after they have caused a problem or identified with routine audits of DNS or firewalls. In some cases this could even pose a security risk. When we think of all of this what we are actually referring to is Compliance, Governance and Life Cycle Management.
My advise here is that even before you touch vRA, you need to think about how IT services are being provisioned within your organisation. This will involve engaging with the various operations or development teams and weed out every single process that is involved, how services are delivered, maintained, monitored and secured. You will need to fully understand the manual process and any automation that exists. Secondly, you will need to understand all of the applications that are being used to support these teams and how you will potentially interface with these during automated deployments.
vRealize Automation is designed to solve all of these problems. it is a fully extensible platform that allows Administrators to create policy driven processes for the provisioning of IT services. It does this whilst providing a catalog of available services that end users can simply request by providing some details and a couple of clicks of a button. Administrators are armed with a powerful Advanced Service Designer tool that allows items such as Virtual Servers or Software Components to be drag and dropped onto the design canvas and later submitted to the catalog. These ‘designs’ are what vRA refers to as blueprints.