iControl REST 101: Getting Started
So you’ve heard of this iControl REST thing, have you? You’re excited at the idea of a simple, light weight API that allows you programmatic access via tried and true tmsh commands with which you may already be familiar? Whether it was in the earlier iControl REST 101 article or elsewhere, your interest is piqued and you’re now looking to start digging in. Excellent, let’s get started. Links of Interest First you’ll want to save a couple of very handy links. These are sure to aid you in all of your future iControl REST endeavors, so take note: iControl REST On Cloud Docs– DevCentral is the place for all things programmatic and beyond the box when it comes to F5 technology. iControl REST is no different in this regard. The documentation, articles and examples on iControl REST available on DevCentral are already handy and will continue to grow as the community brings the power of this fully functional API to bear. No Death Stars were harmed in the making of that last sentence. Whether you’re looking for intro level docs or more advanced examples, this is a good place to start, so keep it close at hand. User’s Guide – If you’re looking into iControl REST programming and haven’t seen the user’s guide yet, you’re doing yourself a disservice. Chalk full of helpful examples, explanations and code snippets, the user’s guide will be your faithful companion on your iControl REST journey. Put together by the PD team responsible for bringing you iControl REST, you’ll find huge amounts of useful information here. Now you’ve got the documentation at the ready and you’re eager to get started. Excellent! The first step is to take a look at what an iControl REST call actually looks like. You can write all the code in the world in whatever language you’re most comfortable with, but you’ll need to know what calls to send and what to expect as a result before it amounts to much. Fortunately getting started with iControl REST is immensely simple. Because this is a REST based API there’s very little overhead or setup needed. All you really need to be able to do is send GET and POST requests to a web service. This can be done either directly from the command line with cURL, via a browser plug-in, a script, or anything else that allows you to build a custom body and send it via HTTP. Examples For these examples we’ll be using cURL, so let’s take a look at what that looks like. The first thing you’ll want to do, most likely, is get a listing of some different commands you can run. Of course, as I’ve said many times now iControl REST follows the tmsh structure, so if you’re familiar with that it will be nothing new. The rest of the setup, however, may be interesting. First we’ll use cURL to send a basic command to the BIG-IP asking it for a list of management resources. For this we use the –s (silent) and –k (insecure) cURL flags to strip out all status/usage info and allow for insecure SSL negotiation. We’ll also use –u to supply a username:password combo. This will get us into the test device and allow us to get an actual response. The constructed command looks like this (Keep in mind the output will vary per device based on version, configuration, etc.): curl –sk –u admin:admin https://dev.rest.box/mgmt/tm/ That isn’t hugely useful to a human, however, since it’s not overly readable. Given the formatting, however, it is pretty simple to break at each comma and insert a newline. We can do that easily from the command line to make this much more human readable. Here’s the appropriate sed string appended to the original command from above. Note that this is a bit different given that I’m running on a Mac, so I tweaked the regex replace a bit to suit my needs, though it should function fine on either Linux or OSX. curl -sk -u admin:admin https://dev.rest.box/mgmt/tm/ | sed 's/,/\'$'\n/g' What you’re seeing here is a list of available resources that you can query via iControl REST. Each of these is a part of the underlying tmsh system. This list goes on and on, the above is just a truncated snippet. If you’re looking for specific commands, check out the tmsh documentation and have at it. From this point it’s trivial to start sending commands that might get you useful information back from your device. Whatever you can think of you can send, for the most part. How about something handy like listing all virtual servers on your device and their associated info? Be warned that the below command will likely get you a huge amount of output on a device with a decent config. To list all virtuals you would do something like: curl -sk -u admin:admin https://dev.rest.box/mgmt/tm/cloud/ltm/virtual-servers | sed 's/,/\'$'\n/g' Again, this goes on and on, the above is just a snippet. Seriously, Note the familiar JSON formatting here. You have an item, identified by the address, and a list of name value pairs of info related to that item, including sub lists where necessary. This should look familiar to anyone that’s dealt in this kind of structure before. It is this simple, easy to parse formatting that is part of what makes iControl REST as widely applicable and easy to pick up or integrate as it is. There you are, a couple easy commands and you’re already connecting to your BIG-IP via iControl REST, grabbing data, and ready to start making changes and writing code. When I said iControl REST was light weight and simple, I wasn’t exaggerating. In the next installment of this series we’ll continue with the cURL usage but begin to make modifications to objects on the device.iControl REST 101: What is iControl REST?
tl;dr - iControlREST provides a representation state transfer interface to BIG-IP management plane functions. iControl Background iControl is F5’s API that allows for programmatic access to pretty much every system that F5 has put out for quite some time now. This API is based on SOAP/XML. It is robust, granular, and allows a huge range of functionality. Whether you’re looking to tweak a feature buried under 4 sub menus or spin up 1,000 new pool members, iControl is up to the task. Anything you can do via the command line or GUI, you can accomplish via iControl. What’s more, you can do it programmatically so you don’t have to enter in every single command in the chain, or have an admin up at 3am for the change control window just to bleed the servers off a pool and toggle it, etc. This has proved extremely powerful and useful over the years, with many F5 users leveraging iControl to great success.There has been, however, a burning need to continue to build on this tried and true technology. Namely by adding a different, lighter weight means of accessing the BIG-IP remotely. Enter iControl REST. It'ssimpler, leaner, and easier to pick up with minimal additional programming or API specific knowledge. It’s built on, as the name suggests, REST (Representational State Transfer), which is a simple, stateless architecture delivered over HTTP(S). It is a simpler approach to passing data to and from an endpoint than the well-known SOAP architecture. Where SOAP is near bullet-proof due to its robust definitions and structure, REST is nimble and fleet of foot. Making use of JSON (JavaScript Object Notation), which is rapidly becoming the most commonly used format for transferring data pairs, allows iCR to require very little structure at all. Combine this with the fact that iControl REST is effectively an extension of tmsh, and you have an extremely low overhead solution, both in terms of operational expense, as well as time to learn. More Methods to learn? If you have any exposure to the SOAP based iControl API you’re no doubt aware of how extensive the list of available methods, or commands, is. There are thousands of possible commands, each unique to iControl SOAP. This is amazingly powerful, in that it is highly granular and allows you to perform the specific action in the precise manner that you need. That’s powerful, and there is definitely a place for that. For many tasks, however, such as something simple like creating a virtual server, it isn’t really necessary. Rather than introduce an entirely new set of methods to learn, iCR acts as effectively an interpreter layer that lives on top of the already powerful tmsh infrastructure on all F5 devices. This means that anything you can do via tmsh, you can do via iCR. And what’s more, you do it the same way. No more learning how to add a virtual via the command line and re-learning how to do it in your code. Once you’ve learned it in tmsh, you’ve learned it in iControl REST. So…it’s just remote tmsh? Well, sort of. It’s not quite as simple as that, but nearly. You still have to connect to the system, properly format your desired arguments into JSON so that the server side can understand what you’re instructing it to do, and send those commands. Other than that, though…yes, it really does act a heck of a lot like remote tmsh. This is a good thing, trust me. Not only does this make for excellent command and code re-use, which we love, but it also means a couple other important things. First, it means command and feature parity. The fact that iControl REST rides on top of tmsh means that any command, for any module that ever gets added to tmsh is immediately available to iControl REST. By collapsing the development needs from tmsh plus iControl to only tmsh, we’re not just reducing the workload on our internal devs, which means more goodness for you. We’re also eliminating any delay or feature gaps between command line and API, and that seems like a very good thing indeed. Second, and just as importantly, there is less to learn. If you already know how to manipulate your device via the command line, it’s going to be conceptually very simple to step into doing so remotely via iCR. For instance, in SOAP iControl, if you want to add a virtual server, it might look something like: 1: #!/bin/env python 2: 3: import sys 4: import pycontrol.pycontrol as pc 5: import time 6: 7: if pc.__version__ == '2.0': 8: pass 9: else: 10: print "Requires pycontrol version 2.x!" 11: sys.exit() 12: 13: if len(sys.argv) < 4: 14: print "Usage %s ip_address username password" % sys.argv[0] 15: sys.exit() 16: 17: a = sys.argv[1:] 18: 19: b = pc.BIGIP( 20: hostname = a[0], 21: username = a[1], 22: password = a[2], 23: fromurl = True, 24: wsdls = ['LocalLB.VirtualServer']) 25: 26: 27: # Setup a shortcut 28: v = b.LocalLB.VirtualServer 29: 30: # create() takes four params: 31: # definitions, a Common.VirtualServerSequence, 32: # wildmasks, a Common.IPAddressSequence, 33: # resources, a LocalLB.VirtualServer.VirtualServerResourceSequence, 34: # profiles, a LocalLB.VirtualServer.VirtualServerProfileSequenceSequence 35: 36: name = 'PC2' + str(int(time.time())) # the name of our vs.ww 37: 38: # Setup types. 39: vs_def = v.typefactory.create('Common.VirtualServerDefinition') 40: 41: vs_def.name = name 42: vs_def.address = '10.100.100.92' 43: vs_def.port = 8888 44: 45: proto = v.typefactory.create('Common.ProtocolType') 46: vs_def.protocol = proto.PROTOCOL_TCP 47: 48: vs_def_seq = v.typefactory.create('Common.VirtualServerSequence') 49: vs_def_seq.item = [vs_def] 50: 51: … 52: 53: # Resource has a 'type' attribute, which must point to a 'VirtualServerType' 54: # object, so let's create that. 55: vs_type = v.typefactory.create('LocalLB.VirtualServer.VirtualServerType') 56: resource = v.typefactory.create('LocalLB.VirtualServer.VirtualServerResource') 57: 58: resource.type = vs_type.RESOURCE_TYPE_POOL 59: resource.default_pool_name = 'dummyServer' # Change to whatever pool you want 60: 61: # A resource sequence we can add the resource to. 62: resource_seq = v.typefactory.create( 63: 'LocalLB.VirtualServer.VirtualServerResourceSequence' 64: ) 65: resource_seq.item = [resource] 66: 67: 68: context = v.typefactory.create('LocalLB.ProfileContextType') 69: prof = v.typefactory.create('LocalLB.VirtualServer.VirtualServerProfile') 70: prof.profile_context = context.PROFILE_CONTEXT_TYPE_ALL 71: prof.profile_name = 'tcp' 72: 73: prof_http = v.typefactory.create('LocalLB.VirtualServer.VirtualServerProfile') 74: prof_http.profile_name = 'http' 75: 76: prof_oneconn = v.typefactory.create('LocalLB.VirtualServer.VirtualServerProfile') 77: prof_oneconn.profile_name = 'oneconnect' 78: 79: # We need to create a 'profile sequence' to add this profile to... 80: prof_seq = v.typefactory.create( 81: 'LocalLB.VirtualServer.VirtualServerProfileSequence' 82: ) 83: 84: prof_seq.item = [prof, prof_http, prof_oneconn] 85: try: 86: v.create( 87: definitions = vs_def_seq, 88: wildmasks=['255.255.255.255'], 89: resources=resource_seq, 90: profiles=[prof_seq] 91: ) 92: except Exception, e: 93: print "Error creating virtual server %s" % name 94: print e Not horrible, but not exactly light on its feet, either. Shall we see what doing effectively the same thing in iControl REST looks like? 1: # create virtual 2: create_http_virtual(bigip, VS_NAME, VS_ADDRESS, VS_PORT, POOL_NAME) 3: print "created virtual server \"%s\" with destination %s:%s..." % (VS_NAME, VS_ADDRESS, VS_PORT) 4: 5: 6: def create_http_virtual(bigip, name, address, port, pool): 7: payload = {} 8: 9: # define test virtual 10: payload['kind'] = 'tm:ltm:virtual:virtualstate' 11: payload['name'] = name 12: payload['description'] = 'A Python REST client test virtual server' 13: payload['destination'] = '%s:%s' % (address, port) 14: payload['mask'] = '255.255.255.255' 15: payload['ipProtocol'] = 'tcp' 16: payload['sourceAddressTranslation'] = { 'type' : 'automap' } 17: payload['profiles'] = [ 18: { 'kind' : 'ltm:virtual:profile', 'name' : 'http' }, 19: { 'kind' : 'ltm:virtual:profile', 'name' : 'tcp' } 20: ] 21: payload['pool'] = pool 22: 23: bigip.post('%s/ltm/virtual' % BIGIP_URL_BASE, data=json.dumps(payload)) I don’t know about you, but that looks decidedly shorter to me. And not just shorter, but more legible. If you’ve used tmsh before you can almost certainly understand what’s going on here, and that’s the beauty of it. Where are all the commands? Remember how this runs off tmsh? That means there isn’t a huge laundry list of extra commands. There is not, and will not be a command by command iterative list of documentation on DevCentral that steps through every possible iControl REST command. That’s because you’re pretty much running tmsh commands, packaged in a JSON format and sent over HTTP. Because of this, if you’re looking for specific commands to execute in your scripts I recommend checking out the tmsh section on DevCentral. If what you’re looking for is how to format and send commands, that will be covered in the next couple installments of this series, so stay tuned! So who is this for? The entire idea is to make scripting more accessible to everyone. Whether you’re a seasoned programmer that’s been hankering for a more modern approach to API access, or you have extensive BIG-IP knowledge and have been hoping to dabble a bit in scripting, iCR is definitely for you. For the programming types: Let’s face it, REST is in. The trend for most APIs is to head towards REST as opposed to other available architectures. So much so that if you aren’t running on REST, your API probably isn’t going to get much traction amongst the coding types of today. It’s easier to use, faster, and is generally what is expected when approaching a device to automate or manage via code. For the networking types: iCR presents way less of a programming hurdle than the SOAP based architecture. There is hugely less setup to begin actually executing commands, and the commands you’re using are mostly the commands you already know, if you’re familiar with BIG-IP. You can learn the formatting requirements, how to set up and tear down connections in your code, and you’re off. It really is a short jump from command line guru to iControl REST writing wizard, and that’s very much by design. What now? Gocheck it out! Go to DevCentral, check out the wiki, the examples, and start poking around. Read through the user’s guide, and if you’ve got them, start asking questions. The community will no doubt be eager to help wherever it can. If your needs go beyond that, or if you’re experiencing difficulties, there is always product support to save the day. Also, make sure to keep a look out for more iControl REST information coming your way, and check back next week for the next installment, iControl REST 101: Getting Started – which will walk you through just what it will take to make the leap to iCR coding yourself, if you haven’t already gotten there. Again, if you’re looking for specific commands to use within your iControl REST scripts, check out the tmsh section on DevCentral.iControl REST 101 – Creating Objects
If you’ve been following along so far you’ve gotten an idea about what iControl REST is all about, seen how to get up and running so you can send commands via cURL to the API, parsed some responses, and even got a peek at viewing some useful Virtual Server data. If you haven’t been keeping up, I recommend checking out the first two parts of the series so you’re caught up. iControl REST 101 – What is iControl REST? iControl REST 101 – Getting Started Now that we’ve figured out how to communicate with the REST based version of iControl let’s take it a little further. So far we’ve listed some available methods and information about a specific object. What would be nice now is to be able to not only list objects, but also to create them. Last time we looked at listing a virtual server. That’s something we’ll get to eventually but there are a lot of options for virtual servers. Let’s start with something simpler but no less useful and ubiquitous, like a self IP. First we’ll look at the list command and then the create command. Before we even get there, however, I need to give a nod to Jason and his awesome blog about jq. jq, for those that haven’t found it yet like me, is a fantastic little program. It is a single binary so it’s easy to distribute or grab, and it does some fantastic JSON formatting quickly and easily. For some more examples of using jq take a look at Jason’s blog post, or just keep reading, because I’ll be using it from here on out. Let’s take a look at what jq does for us. If we want to list the self IP addresses on our device it would look like this, with the following, not so pretty to read, output: curl -sk -u admin:admin https://dev.rest.box/mgmt/tm/net/self/ So, let’s look at how you would list the self IP addresses on a device using this handy new tool. I want to break this out into readable text based on the JSON formatting, and I also want to only list a particular self IP, to narrow down my results. Since the results from iControl REST are broken out into an array of items that becomes easy with jq. I just request the index of the item I want and it returns only that info in pretty, formatted, legible fashion: curl -sk -u admin:admin https://dev.rest.box/mgmt/tm/net/self/ | jq .items[4] How much better is that, right? So that’s jq and listing again. But what about adding? To add it’s actually very similar. You’re going to send a call via cURL to iControl REST, but this time instead of getting JSON formatted data back, you’re going to send JSON formatted data to the device. To do so you have to know what data to send and what format to send it in. Fortunately there was a method to my madness with reviewing what it looks like to list an item. If you look at the return info we got in our jq formatted self IP get, you already have all the data you’ll need to send, and even the format in which it needs to be sent. See the name value pairs? Blue text on the left is the name, the value is on the right of the colon. To create an object with iControl REST you simply send a request to the device using the proper formatting and filling in the required fields to create an object. For the self IP we just saw in the list example above that data would look something like: "name":"cw_test","address":"10.10.10.2/8","vlan":"internal" The rest will get set to defaults for the device. The other important part about sending a create request as opposed to a list request is letting the device know you’re attempting to create an object. The API knows this based on the request type. For a list we used a standard GET, meaning we didn’t specify anything in cURL because that’s the default. For a create we’re going to use a POST. We also want to add a Content-Type header. This means our cURL command will change slightly. The base command to add any self IP, minus the definition data required for the object you’re creating, is (Don’t run this yet): curl -sk -u admin:admin https://dev.rest.box/mgmt/tm/net/self/ -H 'Content-Type: application/json' -X POST To actually execute this and add the IP we simply take the above command and combine it with the data, and run it. I’m going to change the name and increment the IP address to 10.10.10.3/8 since I already have a .2. Then all we do is run it, then list the IP to make sure it worked and looks correct, which means running the following two commands: Create: curl -sk -u admin:admin https://dev.rest.box/mgmt/tm/net/self/ -H 'Content-Type: application/json' -X POST -d '{"name":"cw_test2","address":"10.10.10.3/8","vlan":"internal"}' List: curl -sk -u admin:admin https://dev.rest.box/mgmt/tm/net/self/ | jq . Which gives this, commands and all: As you can see there’s not a whole lot to it once you get comfortable with the JSON formatting and the data that’s required. For the record, that’s pretty much the same as running this via tmsh from the command line, minus the JSON formatting bit. This means that once you’ve mastered the command line tools, you’re already a pro with iControl REST … but I’m pretty sure I’ve mentioned that a few times already. So there you have it, a brand new self IP created on your device via iControl, and all with a single command via cURL. Automating F5 devices has never been easier. Go play around and tune in for the next installment on modifying items next week.iControl REST 101: ASM Intro
The iControl REST 101 series has covered most of the basics that you should need to get started developing against this new, lightweight API. As a recap, so far we’ve covered: · What is iControl REST? · Getting Started · Creating Objects · Modifying Objects · Deleting Objects With that you’ve got most of the standard bases covered. What you might need, however, is a little help delving into the more advanced functionality that iControl REST offers. In this installment we deal with something that is advanced due to the nature of its implementation. Given that it strays a bit from the model of mirroring tmsh commands the ASM support built into iControl REST may take a little bit more time to pick up. Those that were familiar with tmsh before touching iControl REST at all have surely seen how easy it is to transition. iControl REST is, after all, built on top of all of the pre-existing tmsh commands. What happens when there aren’t tmsh commands, though? While tmsh support for ASM is certainly something that’s been tossed around more than once, we didn’t want to leave any modules out in the meantime. That means we rolled in some custom commands that iControl REST can use to manipulate your ASM deployment. This is good news, as it means that you can maintain continuity with your management and automation scripting, even while making use of some of our more advanced modules, such as ASM. First and foremost, you should absolutely familiarize yourself with the iControl REEST user’s guide (available here for 11.5.0), as we’ll be drawing on that extensively for resources. Now that that’s out of the way, let’s dig in. As this is a more advanced module, the commands are a bit more advanced as well. Nothing we can’t tackle, but we’ll have to break it down a little bit into pieces that are consumable. Let’s take a look at how they work. As with all other iControl REST methods, the type of action is defined by issuing different types of HTTP calls. The methods that iControl REST supports for ASM are: GET, POST, DELETE, PUT, PATCH and “Other”. Note that “Other” isn’t directly a method in the sense that it isn’t specific in the HTTP method type itself, but rather in the HTTP body of a POST. Each of these methods works with the prescribed parameters, operators and namespaces. We’ll cover parameters, operators and namespaces in the next article. For now let’s just take a look at what connecting to an ASM device looks like, and leave the rest. Just like the rest of the iControl REST infrastructure the ASM namespace is discoverable. All you need to do is make a GET request to see the available resources, as is shown in the user’s guide: GET https://192.168.25.42/mgmt/tm/asm … and this carries on for the rest of the items in the return list. Once you have a list of the resources, as above, you can dig a bit deeper to get the details of a given resource pass another GET to one of the specific resource URLs, which will expand upon what is available. This looks like: GET https://192.168.25.42/mgmt/tm/asm/policies … and again, this carries on depending on the running config. As you can see, at least the listing of objects and items is very much the same as what you’re used to in the rest of ASM. Next time we’ll dig in a bit more to creating and modifying objects which will look a little bit different.iControl REST 101: Deleting Objects
The goal of iControl REST 101 has been to get you up to speed on the killer new way that you can manage your BIG-IP. So far we’ve covered most of the basics. Whether you’re just trying to figure out how to connect to the device or list objects, or wanting to create or modify a particular piece of your config, we’ve covered it. This means that, if you’ve been following along, you’re now able to list, add, modify and manage nearly any object on your F5 devices with iControl REST. That’s all well and good, but there’s a piece that’s missing in the lineup of basic operations that’s actually pretty important. What do you get when you can add objects rapidly, but have no way of removing them? Object sprawl, and a stressed DevOps team. Let’s avoid that and take a look at how to remove objects with iControl REST. Fortunately, like the rest of the things we’ve covered so far, this is straight forward and easy. Just like before we’re relying on the HTTP method to dictate the type of transaction. For a delete we send, not shockingly, DELETE. And because we’re removing an already existing item the only information we need to pass in is the item name and path. Easy, right? Let’s take a look. First let’s take a look at the object we want to remove: As before, you can see the object output. Listing things like this is always a good idea, especially when doing things manually like we’re doing here for testing, to be sure we have the object we actually want before nuking anything. This is, in fact, the item bound for the bit bucket in our case, so let’s make with the destruction. This cURL call will hopefully look completely familiar by now. The call is the same, listing the object name and the app/json content type. The only change is that we’re setting the method to delete and passing in no parameters whatsoever. No additional information is required to delete an object, after all. As you can see there’s not much output. None, to be precise. That means things worked. If there had been an issue an error would have been returned. Still, though, it’s good to double check that all went according to plan, right? Now we’ll run another list, just for grins and, as expected, get a confused expression from the BIG-IP as a result, since the object is no longer a member of this mortal plane of existence. Remember that before the IP in question was the 5th in the items array returned by jq. This time when we ask for that item we get a very different response: With that, you’re now able to connect, list, add, modify and delete. That was my goal with the series, and with the basics covered you should be well on your way to iControl REST mastery and mayhem. There’s still more to cover, however, and I’ll be back with some more advanced concepts in future installments. For fun with partitioning, transactions and more, stay tuned.
