LBCLI /api/v2 automation update interface to lbcli.
If you read my previous article - 'How to automate your Loadbalancer.org appliance' - then you should find this blog even more useful.
Why should you be interested?
For our v8.4.1 release we added network, routing and HA functions to LBCLI, allowing you to completely automate the entire deployment from initial power-on to a fully configured HA pair. You need never touch the Loadbalancer.org appliance WUI again (just about) – with these enhancements come over 120 new JSON return messages and there are still features being added every week, waiting for each release target.
While adding these features we got a little carried away, and added more allowed values to the syntax checker – which now tells you where the mistake was made. Where possible it will make suggestions as to the correct key or value where the issue was observed.
I always limited the allowed input keys like --action or --layer . Mainly, this enhancement is not to allow anything other than what the equivalent WUI form would allow, less chance to intentionally or accidentally make bad JSON files or LBCLI input!
I will cover this at the end of the blog, because I'm sure you're much more interested in what is directly below!
With our v8.4.2 release we added Policy Based Routing(PBR) for VIPs to the WUI, and these features were added into LBCLI.
Now you can setup virtual service policy-based routing when required via LBCLI.
So why do I keep switching from LBCLI to api/v2 and then occasionally refer to /api? Well, all are linked to LBCLI. Both API Interfaces simply build and then call LBCLI and the mole working hard behind the scenes as a broker for the WUI executes the command and returns its output.
So the /api/v2 I mentioned?
It's a new API wrapper for LBCLI which has a much simpler JSON layout which I will describe shortly. First let me assure you /api is still available and takes the old badly formed JSON input.
Now I would expect you to be asking why I am so negative about something I created? Well lets have a look at the two JSON formats together and the syntax involved to add a Layer 4 Virtual Service.
So that is the old JSON format above and its post location, below is the new API interface and its post location
The simple LBCLI data format
If you wish to know how each command is formed then "lbcli --help lbcli" is the starting place.
Because without this neither JSON examples will make any sense or show how the format conversion works, with one limitation.
And that limitation is simply that the "action" must be the first --action in each API call or for any LBCLI command.
Now how much simpler is that to work with then?
Each API Call is now an "lbcli --action" command with it's syntax and is complete in one block and what is better you can use all edit-vip or edit-waf edit features when adding each Virtual Service, simply add the extra key values to the action array.
Now remember you can use either JSON format but I am sure you will much prefer the use of the /api/v2/ post interface!
You will see that the JSON data is missing the auth->apikey and the syntax has been merged with the action, this eased the portability of each snippet creating that all wonderful word "template" more about those soon to follow.
So how do you access /api/v2?
Below you will find bash(curl), php(curl), Python3(urllib) and Powershell (Windows) examples and we have seen seen customers using C# to connect to LBCLI via HTTP/s
Remember none of the scripts below get run on the Loadbalancer.org appliance, if they did they would be a little pointless. Neither can you execute LBCLI from an Execute a Shell Command as that would be quite pointless. Remember, LBCLI interfaces with the WUI and at this point you are using the WUI so why allow the abstraction there?
|Please note: you may need to use X-LB-APIKEY instead of X_LB_APIKEY for some languages/client libraries, including C#.|
Now that we have the function above, we can call it using the example below.
So we now know how to connect to /api/v2 on any version greater than v8.4.1 but what about the returned data? Well I will get to that very shortly however first one must enable the API and the Loadbalancer.org appliance since v8.3.8 has been Secure by default so we need something to change the security settings.
Below is a script for changing the Secure by default mode.
WARNING TIME and something required before we proceed.
So before the deployment can begin we must first make one requirement before we can proceed.
The workstation from where you will be doing your deployment must have an ip address in 192.168.2.0/24 subnet and not 192.168.2.21 as each default Loadbalancer.org appliance will have this in use.
This will enable the initial configuration of a default Loadbalancer.org appliance.
Below is an example to put your workstation in the same subnet, in my case the Loadbalancer.org appliances are connected to "virbr0"
Or you must run setup on the console to first make an IP Address accessible to you, The choice is yours!
Now let us turn secure by default off on the first Loadbalancer.org appliance.
So we have now turned the secure by default off and now we can do an SSH lbcli call to the first Loadbalancer.org appliance and get the APIKEY to be used in the API call as $apikey_master variable
As soon as we have the APIKEY we are able to put the first appliance back into its secure by default mode but first let us check to ensure we have populated $apikey_master
So we have an APIKEY and we can now turn secure by default back on
Now we are able to go ahead and deploy a Highly available pair of Loadbalancer.org appliances from scratch
To have the API add this setup to your first Master Loadbalancer.org appliance
Now let us setup what will become the Slave
First we need to change the secure by default mode on the second appliance and then get its APIKEY and store it in $apikey_slave
Now we can SSH to the Loadbalancer.org appliance in its default state we can go ahead and get its APIKEY
Let us see if we $apikey_slave has been populated.
Once we have obtained our APIKEY we will not longer need to access SSH, this was a one off operation to enable the API and set credentials so we will put the Loadbalancer.org appliance back to its secure by default mode below
Now we are able to complete the initial setup of the second Loadbalancer.org appliance using the JSON file below
This can now be added to the second Loadbalancer.org appliance with the command below:
Once complete you will have 2 Master appliances now and have received a JSON response as below:
Next is the process of creating HA on the Master and then we will go on to add some virtual services.
Notice the use of the 172.31.200.2,3 IP Addresses now and how the APICALL is no longer talking to the 192.168.2.21 addresses, this is because we have done the initial network setup of each Loadbalancer.org appliances and we no longer to have 192.168.2.1 on our deployment workstation
So lets remove the IP Address we added earlier, we do not need that subnet any more
You would add the JSON above as seen below using the php example:
The response from the apicall after creating a HA Pair.
Please note that creating a HA Pair does take a little while so do expect to wait upto 30 seconds for the response below:
Now that we have done the initial configuration to the pair of Loadbalancer.org appliances we can continue and create some Virtual Services and add the Real Servers to each Virtual Service.
We will call this JSON template as we have done before but this time to the IP Address the first appliance has "172.31.200.2"
While we wait for the JSON to be processed on the Loadbalancer.org appliance if you look at the WUI you will see the Virtual Services and their real servers being added and if successful you will then see the output much like below:
So what have we done? Initial network configuration of two appliances out of the box, next we created the HA Pair and then proceeded to add the virtual services and its associated real server and this leaves only to restart services which we will do now, we can use the same JSON file for each Master and Slave Loadbalancer.org appliance
We will take the above JSON now and reload the required services affected by creating the HA Pair and adding Layer7 Virtual services
And the results of reloading the two affected services should show this output for each APICALL
So there we have it, a pair of fully deployed Loadbalancer.org appliances in HA with a web server virtual virtual service, Exchange OWA and an SMTP VIP.
Now at the start of the blog I made reference to the spellchecking features added in v8.4.1 and I will not spend much time on this other than show a single example of how LBCLI tried to help you.
Below I intentionally spell forwarding incorrect to show how LBCLI will suggest the correct key or value:
So that shows how the keys are checked on your input. Now I will show you how your values are represented when correct by spelling tcp wrongly as ttcp:
The returned JSON reply hopefully shows you where things went wrong:
I think that sums up How to automate your load balancer, part 2. If you have any questions please do not hesitate to ask, and if all goes horribly wrong then email email@example.com and let us know what happened – so we can do our very best to fix whatever the issue might be! Attaching /var/log/lbadmin.log should be enough to find any problems. Happy Automation.