Demystifying iControl REST Part 7 - Understanding Transactions
iControl REST. It’s iControl SOAP’s baby, brother, introduced back in TMOS version 11.4 as an early access feature but released fully in version 11.5. Several articles on basic usage have been written about the rest interface so the intent here isn’t basic use, but rather to demystify some of the finer details of using the API.
A few months ago, a question in Q&A from community member spirrello asking how to update a tcp profile on a virtual. He was using bigsuds, the python wrapper for the soap interface. For the rest interface on this particular object, this is easy; just use the put method and supply the payload mapping the updated profile. But for soap, this requires a transaction. There are some changes to BIG-IP via the rest interface, however, like updating an ssl cert or key, that likewise will require a transaction to accomplish. In this article, I’ll show you how to use transactions with the rest interface.
The Fine Print
From the iControl REST user guide, the life cycle of a transaction progresses through three phases:
- Creation - This phase occurs when the transaction is created using a POST command.
- Modification - This phase occurs when commands are added to the transaction, or changes are made to the sequence of commands in the transaction.
- Commit - This phase occurs when iControl REST runs the transaction.
To create a transaction, post to /tm/transaction
POST https://192.168.25.42/mgmt/tm/transaction
{}
Response:
{
"transId":1389812351,
"state":"STARTED",
"timeoutSeconds":30,
"kind":"tm:transactionstate",
"selfLink":"https://localhost/mgmt/tm/transaction/1389812351?ver=11.5.0"
}
Note the transId, the state, and the timeoutSeconds. You'll need the transId to add or re-sequence commands within the transaction, and the transaction will expire after 30 seconds if no commands are added. You can list all transactions, or the details of a specific transaction with a get request.
GET https://192.168.25.42/mgmt/tm/transaction GET https://192.168.25.42/mgmt/tm/transaction/transId
To add a command to the transaction, you use the normal method uris, but include the
X-F5-REST-Coordination-Id
POST https://192.168.25.42/mgmt/tm/ltm/pool
X-F5-REST-Coordination-Id:1389812351
{
"name":"tcb-xact-pool",
"members": [ {"name":"192.168.25.32:80","description":"First pool for transactions"} ]
}
Not a great example because there is no need for a transaction here, but we'll roll with it! There are several other option methods for interrogating the transaction itself, see the user guide for details. Now we can commit the transaction. To do that, you reference the transaction id in the URI, remove the
X-F5-REST-Coordination-Idstate: VALIDATING
PATCH https://localhost/mgmt/tm/transaction/1389812351
{ "state":"VALIDATING" }
That's all there is to it! Now that you've seen the nitty gritty details, let's take a look at some code samples.
Roll Your Own
In this example, I am needing to update and ssl key and certificate. If you try to update the cert or the key, it will complain that they do not match, so you need to update both at the same time. Assuming you are writing all your code from scratch, this is all it takes in python. Note on line 21 I post with an empty payload, and then on line 23, I add the header with the transaction id. I make my modifications and then in line 31, I remove the header, and finally on line 32, I patch to the transaction id with the appropriate payload.
import json
import requests
btx = requests.session()
btx.auth = (f5_user, f5_password)
btx.verify = False
btx.headers.update({'Content-Type':'application/json'})
urlb = 'https://{0}/mgmt/tm'.format(f5_host)
domain = 'mydomain.local_sslobj'
chain = 'mychain_sslobj
try:
key = btx.get('{0}/sys/file/ssl-key/~Common~{1}'.format(urlb, domain))
cert = btx.get('{0}/sys/file/ssl-cert/~Common~{1}'.format(urlb, domain))
chain = btx.get('{0}/sys/file/ssl-cert/~Common~{1}'.format(urlb, 'chain'))
if (key.status_code == 200) and (cert.status_code == 200) and (chain.status_code == 200):
# use a transaction
txid = btx.post('{0}/transaction'.format(urlb), json.dumps({})).json()['transId']
# set the X-F5-REST-Coordination-Id header with the transaction id
btx.headers.update({'X-F5-REST-Coordination-Id': txid})
# make modifications
modkey = btx.put('{0}/sys/file/ssl-key/~Common~{1}'.format(urlb, domain), json.dumps(keyparams))
modcert = btx.put('{0}/sys/file/ssl-cert/~Common~{1}'.format(urlb, domain), json.dumps(certparams))
modchain = btx.put('{0}/sys/file/ssl-cert/~Common~{1}'.format(urlb, 'le-chain'), json.dumps(chainparams))
# remove header and patch to commit the transaction
del btx.headers['X-F5-REST-Coordination-Id']
cresult = btx.patch('{0}/transaction/{1}'.format(urlb, txid), json.dumps({'state':'VALIDATING'})).json()
A Little Help from a Friend
The f5-common-python library was released a few months ago to relieve you of a lot of the busy work with building requests. This is great, especially for transactions. To simplify the above code just to the transaction steps, consider:
# use a transaction
txid = btx.post('{0}/transaction'.format(urlb), json.dumps({})).json()['transId']
# set the X-F5-REST-Coordination-Id header with the transaction id
btx.headers.update({'X-F5-REST-Coordination-Id': txid})
# do stuff here
# remove header and patch to commit the transaction
del btx.headers['X-F5-REST-Coordination-Id']
cresult = btx.patch('{0}/transaction/{1}'.format(urlb, txid), json.dumps({'state':'VALIDATING'})).json()
With the library, it's simplified to:
tx = b.tm.transactions.transaction
with TransactionContextManager(tx) as api:
# do stuff here
api.do_stuff
Yep, it's that simple. So if you haven't checked out the f5-common-python library, I highly suggest you do! I'll be writing about how to get started using it next week, and perhaps a follow up on how to contribute to it as well, so stay tuned!
