PowerShell module for the F5 LTM REST API
Problem this snippet solves:
To report an issue with the F5-LTM or F5-BIGIP modules, please use the Issues sections of the GitHub repos (here and here) instead of commenting here. Thanks!
This PowerShell module uses the iControlREST API to manipulate and query pools, pool members, virtual servers, and iRules. It aims to support version 11.5.1 and higher, and to conform to the schedule for technical support of versions, though this may eventually prove to become difficult.
The module currently includes some functionality that, strictly speaking, is outside the scope of the LTM module. Hence, there is an active effort to wrap this LTM module into a larger BIG-IP module, and relocate that functionality elsewhere within that parent module, as well as expand the scope of functionality to include BIG-IP DNS (formerly GTM) and possibly other areas. Both the LTM module and the parent BIG-IP module are projects on github. Please use these projects to report any issues you discover. Thanks!
The module contains the following functions.
- Add-iRuleToVirtualServer
- Add-iRuleToVirtualServer
- Add-PoolMember
- Add-PoolMonitor
- Disable-PoolMember
- Disable-VirtualServer
- Enable-PoolMember
- Enable-VirtualServer
- Get-CurrentConnectionCount (deprecated; use Get-PoolMemberStats | Select-Object -ExpandProperty 'serverside.curConns')
- Get-F5Session (will be deprecated in future versions. use New-F5Session)
- Get-F5Status
- Get-HealthMonitor
- Get-HealthMonitorType
- Get-iRule
- Get-iRuleCollection (deprecated; use Get-iRule)
- Get-Node
- Get-BIGIPPartition
- Get-Pool
- Get-PoolList (deprecated; use Get-Pool)
- Get-PoolMember
- Get-PoolMemberCollection (deprecated; use Get-PoolMember)
- Get-PoolMemberCollectionStatus
- Get-PoolMemberDescription (deprecated; use Get-PoolMember)
- Get-PoolMemberIP (deprecated; use Get-PoolMember)
- Get-PoolMembers (deprecated; use Get-PoolMember)
- Get-PoolMemberStats
- Get-PoolMemberStatus (deprecated; use Get-PoolMember)
- Get-PoolMonitor
- Get-PoolsForMember
- Get-StatusShape
- Get-VirtualServer
- Get-VirtualServeriRuleCollection (deprecated; use Get-VirtualServer | Where rules | Select -ExpandProperty rules)
- Get-VirtualServerList (deprecated; use Get-VirtualServer)
- Invoke-RestMethodOverride
- New-F5Session
- New-HealthMonitor
- New-Node
- New-Pool
- New-VirtualServer
- Remove-HealthMonitor
- Remove-iRule
- Remove-iRuleFromVirtualServer
- Remove-Pool
- Remove-PoolMember
- Remove-PoolMonitor
- Remove-ProfileRamCache
- Remove-Node
- Remove-VirtualServer
- Set-iRule
- Set-PoolLoadBalancingMode (deprecated; use Set-Pool)
- Set-PoolMemberDescription
- Set-Pool
- Set-VirtualServer
- Sync-DeviceToGroup
- Test-F5Session
- Test-Functionality
- Test-HealthMonitor
- Test-Node
- Test-Pool
- Test-VirtualServer
How to use this snippet:
To use the module, click 'Download Zip', extract the files, and place them in a folder named F5-LTM beneath your PowerShell modules folder. By default, this is %USERPROFILE%\Documents\WindowsPowerShell\Modules. The WindowsPowerShell and Modules folders may need to be created.
You will most likely need to unblock the files after extracting them. Use the Unblock-File PS cmdlet to accomplish this.
The Validation.cs class file (based on code posted by Brian Scholer) allows for using the REST API with LTM devices with self-signed SSL certificates.
Nearly all of the functions require an F5 session object as a parameter, which contains the base URL for the F5 LTM and a credential object for a user with privileges to manipulate the F5 LTM via the REST API. Use the New-F5session function to create this object. This function expects the following parameters:
- The name or IP address of the F5 LTM device
- A credential object for a user with rights to use the REST API
- An optional TokenLifespan value for extending the life of the authentication token past the default 20 minutes
You can create a credential object using Get-Credential and entering the username and password at the prompts, or programmatically like this:
$secpasswd = ConvertTo-SecureString "PlainTextPassword" -AsPlainText -Force $mycreds = New-Object System.Management.Automation.PSCredential "username", $secpasswd
Thanks to Kotesh Bandhamravuri and his blog entry for this snippet.
There is a function called Test-Functionality that takes an F5Session object, a new pool name, a new virtual server, an IP address for the virtual server, and a computer name as a pool member, and validates nearly all the functions in the module.
I've also contributed this code sample for how to gather some basic info about your LTM with this PS module.
The module has been tested on:
- 11.5.1 Build 8.0.175 Hotfix 8 and later
- 11.6.0 Build 5.0.429 Hotfix 4 and later
- 12.0 / 12.1
- 13.0
Code :
https://github.com/joel74/POSH-LTM-Rest
Tested this on version:
11.5- blashmet_319176Nimbostratus
Can this module be used to return the state of the "Source Address Translation" property on a VIP? (e.g., return whether it is set to SNAT, AutoMap, or none).
Thank you.
EDIT:
Turns out this property is accessible on a virtual server object:
$virtualserver = Get-VirtualServer | where-object {$_.name -eq "virtualservername" }
$virtualserver.sourceAddressTranslation
- Joel_NewtonCirrus
Correct. Not all available properties, such as sourceAddressTranslation, gtmScore and mobileAppTunnel, are defined in the VirtualServer LTM object type, but they are still accessible via the object.
- ELtheNINO_31450Nimbostratus
When using a try catch block with Get-Virtualserver the error terminates in the try block
EXAMPLE:
try { get-VirtualServer -F5Session -Name |select rules } catch [System.Exception] { Write-Host "NOPE $_.Exception.Message" -ForegroundColor Cyan }
It returns:
Invoke-F5RestMethod : "404 Not Found: 01020036:3: The requested Virtual Server (/Common/EnterSomethingFalse) was not found. At C:\Program Files\WindowsPowerShell\Modules\F5-LTM\1.4.196\Public\Get-VirtualServer.ps1:42 char:21 + ... $JSON = Invoke-F5RestMethod -Method Get -Uri $URI -F5Session $F5S ... + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
INSTEAD OF in the catch block
NOPE. ERROR MESSAGE
Is anyone else experiencing this?
- Joel_NewtonCirrus
Hi, This is a PowerShell thing, not something specific to this module. The error thrown is non-terminating, so PowerShell doesn't go into the Catch block. If you set $ErrorActionPreference to 'Stop', then it will be caught.
- igor_curic_2239Nimbostratus
Hi,
I'm trying to automate virtual server deployment from top to bottom, an currently am failing on Add-PoolMember.
PS C:\Windows\system32> Add-PoolMember -Address 10.18.2.22 -PoolName iCPRF02BO.pool_80 -PortNumber 80 -Status Enabled -F5Session $SessionToken -Name ICPRF02-BO1 Invoke-F5RestMethod : "400 Bad Request: 01070734:3: Configuration error: Cannot assign (/Common/ICPRF02-BO1-10.18.2.22) as a pool member. At C:\Program Files\WindowsPowerShell\Modules\f5-ltm\Public\Add-PoolMember.ps1:88 char:33 + Invoke-F5RestMethod -Method POST -Uri "$MembersL ... + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorExceptio n + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,I nvoke-F5RestMethod
I can add it manually through GUI, but this function returns an error.
Any help would be appreciated.
Br, Igor
- Joel_NewtonCirrus
Hi, Igor,
I tested this, and I can successfully execute basically the same Add-PoolMember command you used against 11.5, 11.6 and 12.1. What version LTM are you working with (including hotfixes) and do you have the latest version of the PS module from github? Matan's issue was with searching different partitions. Are you using other than the Common partition?
Cheers, Joel
- igor_curic_2239Nimbostratus
Hi Joel,
I'm working on BIG-IP 13.0.0 Build 0.0.1645 Final. I downloaded PS module a week ago from https://github.com/joel74/POSH-LTM-Rest I'm using the Common partition. As you can see from the error, it sees the node, but fails to join it to the pool.
Configuration error: Cannot assign (/Common/ICPRF02-BO1-10.18.2.22) as a pool member.
Br, Igor
- Joel_NewtonCirrus
Hi, Igor, I tested this morning with 13.0.0 Build 2.0.1671 Hotfix HF2 and couldn't repro the error. A couple questions, that may or may not shed some light:
- Do all calls to Add-PoolMember fail?
- Did it work initially and then started failing?
- Does the user creating the iControlRest session have admin privs?
- Is the pool member (ICPRF02-BO1-10.18.2.22) listed as a node ( https://{BIGIP}/mgmt/tm/ltm/node/ )
Cheers, Joel
- igor_curic_2239Nimbostratus
Hi Joel,
Thank you for the quick responses.
First the answer to all questions: 1) yes...but, 2) no, 3) yes, 4) yes
Now but:
My plan is to add nodes using FQDN and I was testing using nodes created manually/or trough script using FQDN and all tests on may BIGIPs failed (i have two in HA). Then I tried creating nodes using IP, and it turns out nodes created that way can be added to the pool using the Add-PoolMember. So my question changes to: Why can't I use Add-PoolMember to add FQDN nodes? Did you test the command with FQDN nodes?
And I have two additional questions, since I wasn't able to find it in the module: 1) Is there a way to add SSL Profile (client) to virtual server? 2) Is there a way to add HTTP profile to virtual server?
Br, Igor
- Joel_NewtonCirrus
Hi, Igor, Answering in reverse order, yes, you can use Set-VirtualServer to add SSL and HTTP (and other server and client) profiles to virtual servers. Check out the examples for that function on how to do this.
Currently, Add-PoolMember does not support the creation of new FQDN nodes. There are a number of additional params that Add-PoolMember would need to accept, so it could pass them on to New-Node. My recommendation for the time-being would be to call New-Node to create your FQDN nodes, and then add the existing nodes with Add-PoolMember. Please let me know if you have any issue accomplishing that.
All the best, Joel