iControl REST: Working with Pool Members

Since iControl REST is the new kid on the block, it's bound to start getting some of the same questions we've addressed with traditional iControl. One of these oft-asked and misunderstood questions is about enabling/disabling pool members. The original poster in this case is actually facing a syntax issue with the allowable state issues in the json payload, but I figured I'd kill two birds with one stone here and address both concerns going forward.

DevCentral member Rudi posted in Q&A asking for some assistance with disabling a pool member. He was able to change some properties on the pool member, but trying to change the state resulted in this error:

{"code":400,"message":"invalid property value \"state\":\"up\"","errorStack":[]}

The REST interface is complaining about an invalid property, mainline, the "up" state. If you do a query against an "up" pool member, you can see that the state is "unchecked" instead of up.

{
  "state": "unchecked",
  "connectionLimit": 0,
  "address": "192.168.101.11",
  "selfLink": "https://localhost/mgmt/tm/ltm/pool/testpool/members/~Common~192.168.101.11:8000?ver=11.5.1",
  "generation": 63,
  "fullPath": "/Common/192.168.101.11:8000",
  "partition": "Common",
  "name": "192.168.101.11:8000",
  "kind": "tm:ltm:pool:members:membersstate",
  "dynamicRatio": 1,
  "inheritProfile": "enabled",
  "logging": "disabled",
  "monitor": "default",
  "priorityGroup": 0,
  "rateLimit": "disabled",
  "ratio": 1,
  "session": "user-enabled"
}

You might also note the session keyword in the pool member attributes as well. This is the key that controls the forced offline behavior. The mappings for these two values (state and session) to the GUI state of a pool member are as follows

GUI: Enabled	{"state": "unchecked", "session": "user-enabled"}
GUI: Disabled	{"state": "unchecked", "session": "user-disabled"}
GUI: Forced Offline	{"state": "user-down", "session": "user-disabled"}

So to change a value on a pool member, you need to use the PUT method, and specify in the URL the pool, pool name, and the pool member:

curl -sk -u admin:admin https://192.168.6.5/mgmt/tm/ltm/pool/testpool/members/~Common~192.168.101.11:8000/ \
-H "Content-Type: application/json" -X PUT -d '{"state": "user-down", "session": "user-disabled"}'

This results in changed state and session for this pool member:

{
  "state": "user-down",
  "connectionLimit": 0,
  "address": "192.168.101.11",
  "selfLink": "https://localhost/mgmt/tm/ltm/pool/testpool/members/~Common~192.168.101.11:8000?ver=11.5.1",
  "generation": 63,
  "fullPath": "/Common/192.168.101.11:8000",
  "partition": "Common",
  "name": "192.168.101.11:8000",
  "kind": "tm:ltm:pool:members:membersstate",
  "dynamicRatio": 1,
  "inheritProfile": "enabled",
  "logging": "disabled",
  "monitor": "default",
  "priorityGroup": 0,
  "rateLimit": "disabled",
  "ratio": 1,
  "session": "user-disabled"
}

Best tip I can give with discovering the nuances of iControl REST is to query existing objects, and change their default values around in the GUI and re-query to see what the values are supposed to be. Happy coding!

Published Jun 10, 2014

Version 1.0

10 Comments

Cloverleaf_5340
Nimbostratus
Jun 10, 2014
I've been dealing with this same thing for a few days now, myself. One thing that I've been confused by, though, is the state of a pool member in the REST result when a node is disabled. As far as I can see, when I put a node in "user-down", the pool member that uses that node still displays as { "state": "up" }, even though the GUI shows the member as being Offline. Is there a different place I should be going to get that "merged" state?
BinaryCanary_19
Historic F5 Account
Jul 11, 2014
Note that you can also get a similar looking error message if the user you are authenticated as does not have permissions to perform the requested operation: My example below, is an attempt to create a pool using a user whose role is "certificate manager" [WARNING][60][11 Jul 2014 09:44:51 UTC][RestRequestReceiver][fail] Error processing request for URI:http://localhost:8100/mgmt/tm/ltm/pool {"code":400,"message":"\"pool\" unexpected argument","errorStack":[]} [WARNING][62][11 Jul 2014 09:45:37 UTC][RestRequestReceiver][fail] Error processing request for URI:http://localhost:8100/mgmt/tm/ltm/pool {"code":400,"message":"\"pool\" unexpected argument","errorStack":[]}
Amit_K_Sharma_1
Nimbostratus
Aug 10, 2014
Hi Jason, While i have been able to use REST API Calls to get, modify, delete the Pool Members and create new ones in a Virtual Server. However, i have not been able to find out how to add one member to an existing pool which already has, say, 2 members. I have gone through the documentation and it mentions that POST has to be used, but it gives me error. PATCH and PUT overwrite the existing Pool members. Ex. - curl -k -u user:pass -H "Content-Type: application/json" -X POST -d '{"name":"myPoolName","members":[{"name":"MEMBERIP:PORT","description":"Server3"}]}' https://MANAGEMENTIP/mgmt/tm/ltm/pool/myPoolName gives an error - {"code":400,"message":"Found unexpected json pair at configuration item /ltm/pool/myPoolName. The json pair is \"myPoolName\":null.","errorStack":[]} While the following with PUT works fine but overwrites - curl -k -u user:pass -H "Content-Type: application/json" -X PUT -d '{"name":"myPoolName","members":[{"name":"MEMBERIP:PORT","description":"Server3"}]}' https://MANAGEMENTIP/mgmt/tm/ltm/pool/myPoolName Appreciate some guidance here. Thanks.
Kapil_Malhotra_
Nimbostratus
Mar 13, 2015
Hi Jason, I am getting the below error after running the REST API call to modify the state of pool member {"code":415,"message":"Found invalid content-type. The content-type must be application/json. The received content-type is application/x-www-form-urlencoded","errorStack":[]}

Tim_Bohlender_2

Nimbostratus

Jun 07, 2017

Tried to enable a pool member by using

{"state": "unchecked", "session": "user-enabled"}

and got the error

{
  "code": 400,
  "message": "invalid property value \"state\":\"unchecked\"",
  "errorStack": []
}

Mikhail_Galiul1
Employee
Jan 09, 2018
Tim, Use "state":"user-up" instead of "unchecked".
dichotomouse
Nimbostratus
Jan 17, 2018
Mikhail's instructions above are correct. Use:

{"state": "user-up", "session": "user-enabled"}

This works on v12.1.2 anyway

donfouts_363600

Nimbostratus

Aug 31, 2018

Disable works fine - using Mikhail's instruction

{"state": "user-up", "session": "user-enabled"}

i get the following - is there a specific way to enable a pool member if it is part of an iapp?

{
    "code": 400,
    "message": "010715bd:3: The parent folder is owned by application service (/Common/poolname.app/poolname), the object ownership cannot be changed to ().",
    "errorStack": [],
    "apiError": 3
}

using BIG-IP 13.1.1 Build 0.0.4 Final - Thanks

Christen0125_35
Nimbostratus
Oct 11, 2018
Hi Jason, I am getting the below error after running the REST API call to modify the state of pool member {"code":415,"message":"Found invalid content-type. The content-type must be application/json. The received content-type is application/x-www-form-urlencoded","errorStack":[]}
C_Modisette_359
Nimbostratus
Apr 29, 2019
Is there anyway to disable/enable an array of pool members instead of just one at a time, via the REST API? I would like to send something like a PUT call to a pool via URL, and have the body contain a JSON array of items with pool members defined and, nested in those, the session/state JSON pairs to be set - instead of just one pool member with the [pool]/members/[pool-member] call with one set of session/state adjustments.

In other words, I want to be able to disable or enable (one of those ops) an ARRAY of pool-members in one call - not just one at a time.

Thanks!