Posh-IBWAPI

A PowerShell module to help with Infoblox automation via WAPI requests and functions. It is not intended to wrap every object into a set of custom cmdlets or strong types. Instead, it aims to hide the some of the tedious complexity in calling the Infoblox REST API via PowerShell.

Features

Automatic paging for large GET result sets (Requires WAPI version 1.5+)
Automatic session handling
Receive-IBFile and Send-IBFile wrappers for upload/download WAPI functions. (Guide)
Optionally return all fields for an object without needing to specify each one individually (Requires WAPI version 1.7.5+)
Use Get-IBSchema for Get-Help style querying of the WAPI object model (Requires WAPI version 1.7.5+). (Guide)
Error details in the body of HTTP 400 responses are exposed instead of being swallowed by Invoke-RestMethod.
Optionally batch pipelined requests to increase performance.
Optionally ignore certificate validation errors.
Save connection profiles to use automatically with functions instead of supplying them to each call. Multiple profiles supported for multi-grid environments or differing credentials on the same grid.
SecretManagement support for connection profiles. (Guide)
Cloud friendly stateless mode supported via environment variables. (Guide)
Cross-platform PowerShell support

Installation (Stable)

The latest release can found in the PowerShell Gallery or the GitHub releases page. Installing is easiest from the gallery using Install-Module. See Installing PowerShellGet if you run into problems with it.

# install for all users (requires elevated privs)
Install-Module -Name Posh-IBWAPI -Scope AllUsers

# install for current user
Install-Module -Name Posh-IBWAPI -Scope CurrentUser

NOTE: If you use PowerShell 5.1 or earlier, Install-Module may throw an error depending on your Windows and .NET version due to a change PowerShell Gallery made to their TLS settings. For more info and a workaround, see the official blog post.

Installation (Development)

Use the following PowerShell command to install the latest development version from the git main branch. This method assumes a default PSModulePath environment variable and installs to the CurrentUser scope.

iex (irm https://raw.githubusercontent.com/rmbolger/Posh-IBWAPI/main/instdev.ps1)

You can also download the source manually from GitHub and extract the Posh-IBWAPI folder to your desired module location.

Quick Start

Every WAPI call needs a host, version, and credentials. Set them once using Set-IBConfig and you won't need to add them to every call. If your grid is still using self-signed certs, you may also need to use the SkipCertificateCheck parameter. In addition to standard version numbers like '2.2', the -WAPIVersion parameter also accepts 'latest' and will query the grid master for the latest supported version.

Set-IBConfig -ProfileName 'mygrid' -WAPIHost 'gridmaster.example.com' `
    -WAPIVersion 'latest' -Credential (Get-Credential) -SkipCertificateCheck

Retrieve a set of objects using Get-IBObject. The only required parameter is ObjectType. Everything else like filters and return fields are optional.

Get-IBObject 'record:host'
Get-IBObject 'record:host' -Filter @{'name~'='example\.com'} -MaxResults 10 -ReturnField 'extattrs'

If you're just exploring the WAPI object model, it can be helpful to convert the resulting objects back to JSON for readability.

Get-IBObject 'record:host' | Select -First 1 | ConvertTo-Json -Depth 5

You may notice that all objects returned by Infoblox have a _ref field. That is known as the object reference and can be used in any function that accepts an ObjectRef parameter. In the case of Get-IBObject, it will return that specific object.

Get-IBObject -ObjectRef 'record:host/asdfqwerasdfqwerasdfqwerasdfqwer'

Create a new object with New-IBObject by supplying the object type and an object with the minimum required fields defined. Embedded WAPI functions work just fine here.

# Build the record:host object we want to create.
# NOTE: An error will be thrown if the example.com DNS zone doesn't
# exist in Infoblox
$newhost = @{
    name = 'web1.example.com'
    ipv4addrs = @(
        @{ ipv4addr = '10.10.10.1' }
    )
    comment = 'web server'
}

# Create the object
New-IBObject -ObjectType 'record:host' -IBObject $newhost

# Modify the object so we can make another and this time use an
# embedded function to set the IP address.
$newhost.name = 'web2.example.com'
$newhost.ipv4addrs = @(
    @{ ipv4addr = 'func:nextavailableip:10.10.10.0/24'}
)
New-IBObject -ObjectType 'record:host' -IBObject $newhost

To modify an existing object, the easiest way is usually to get a copy of it, modify the copy, and save the result with Set-IBObject. Be wary of objects that return read-only fields. You need to strip them out before saving or an error will be thrown.

# Get a copy of the host
$myhost = Get-IBObject 'record:host' -Filter 'name=web1.example.com'

# Modify the first listed IP address
$myhost.ipv4addrs[0].ipv4addr = '10.10.10.100'

# remove the read-only 'host' field from the nested 'record:host_ipv4addr' object
$myhost.ipv4addrs[0].PSObject.Properties.Remove('host')

# Save the result
$myhost | Set-IBObject

If you need to make the same change to a set of objects, you can also pass the set of object references via the pipeline and use a template object to change all of them in the same way.

# Get all hosts in the Los Angeles site
$laHosts = Get-IBObject 'record:host' -Filter @{'*Site'='Los Angeles'}

# Move them to the New York site
$laHosts | Set-IBObject -Template @{extattrs=@{Site=@{value='New York'}}}

Deleting one or more objects is as simple as passing one or more object references to Remove-IBObject.

# Get hosts being decommissioned
$toDelete = Get-IBObject 'record:host' -Filter 'comment=decommission'

# Delete them
$toDelete | Remove-IBObject

For more examples, check the Definitive REST Examples guide.

Requirements and Platform Support

Supports Windows PowerShell 5.1 (Desktop edition) with .NET Framework 4.5.2 or later
Supports PowerShell 7.0 or later (Core edition) on all supported OS platforms.
Supports any NIOS/WAPI version, but only regularly tested against Infoblox supported versions.

Changelog

See CHANGELOG.md