Calling RELIANOID API REST from Powershell

Table of Contents

Ways to manage RELIANOID API from Windows
Using Powershell to make API calls
Prerequisites to enable remote API automation
- Enabling API Permissions and Creating an API Key
- Identifying the API Endpoint
Powershell API Examples
Further API documentation

Ways to manage RELIANOID API from Windows #

Managing and automating remotely a RELIANOID Load Balancer can be effectively done using noid-cli, a Perl-based command-line interface program. noid-cli is designed to make API calls directly from the command line, simplifying tasks such as configuring virtual servers, monitoring system status, and adjusting load balancing settings. This tool provides a set of predefined commands that abstract the complexities of API interactions, allowing administrators to quickly execute operations without needing to manually construct HTTP requests. Its ease of use and integration with shell scripting make it a practical choice for routine maintenance and quick adjustments in a terminal environment.

On the other hand, programming a PowerShell script with Invoke-RestMethod to manage API calls to the RELIANOID Load Balancer offers more flexibility and automation potential. PowerShell scripts can automate complex sequences of API interactions, handle dynamic data, and integrate with other Windows-based services and tools. By using Invoke-RestMethod, administrators can craft custom automation scripts that precisely meet their operational needs, such as orchestrating failover procedures, performing bulk updates, or integrating load balancer management into broader system management workflows. This method leverages the full power of PowerShell’s scripting capabilities, including error handling, logging, and advanced data manipulation, making it ideal for sophisticated automation tasks and integration scenarios.

This article will describe the API calls using the Powershell method.

Using Powershell to make API calls #

Making a call to an API using PowerShell to automate systems involves leveraging the Invoke-RestMethod cmdlet, which simplifies sending HTTP and HTTPS requests to RESTful web services. This cmdlet allows for interaction with APIs by specifying the endpoint URL, HTTP method (GET, POST, PUT, DELETE), headers (like authorization tokens), and request body (typically in JSON format). By doing so, you can retrieve, create, update, or delete resources on the target system. PowerShell scripts can automate repetitive tasks, such as managing virtual machines, configuring network devices, or fetching system statuses, enhancing operational efficiency and consistency.

To begin, you’ll typically define the API endpoint and any necessary credentials. For example, you might use basic authentication or an API key in the headers. Next, depending on the API operation, you may need to prepare a JSON payload for POST or PUT requests, which can be easily created and converted from PowerShell objects using the ConvertTo-Json cmdlet. Once the request is crafted and sent, Invoke-RestMethod processes the response, which you can further manipulate or use in subsequent tasks within your script. This streamlined process makes PowerShell a powerful tool for system administrators and developers aiming to automate and integrate various systems and services through APIs.

Prerequisites to enable remote API automation #

To make API calls from PowerShell to manage RELIANOID Load Balancer, several prerequisites must be met:

Enabling API Permissions and Creating an API Key #

Firstly, you need to enable API permissions for the user account that will be making the calls. This involves accessing the web GUI of the load balancer and navigating to System > User. In this section, you can configure user accounts and assign API permissions. Create or select a user account and generate an API Key, which will be used to authenticate the API calls. If you are using Role-Based Access Control (RBAC) users, ensure that their roles include the necessary permissions to interact with the API. This API Key is essential for authenticating and authorizing the API requests from your PowerShell scripts.

For more information, please refer to this article https://www.relianoid.com/resources/knowledge-base/system-enterprise-edition-v8-administration-guide/system-user/ .

Identifying the API Endpoint #

Secondly, you need to identify the correct API endpoint for connecting to the load balancer. The API endpoint typically includes the base URL of your load balancer followed by specific paths for different functionalities. In the case of a clustered load balancer setup, it is crucial to use a shared IP address for the API endpoint. This shared IP address ensures that the API call is always directed to the master node, regardless of which node is currently acting as the master. Using the shared IP prevents issues where the API call might be made to a standby node, ensuring that all configurations and operations are applied consistently to the active master node.

Powershell API Examples #

The option SkipCertificateCheck could not be recognized in older versions of Powershell. If this is your case, please define this option at the beginning of your Powershell script:

[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }

In addition, it will be required to add the following line in our Powershell scripts to avoid the error “Invoke-RestMethod : The underlying connection was closed: An unexpected error occurred on a receive“.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls -bor [Net.SecurityProtocolType]::Tls11 -bor [Net.SecurityProtocolType]::Tls12

Getting Farm details #

This script performs a GET request to retrieve information about a specific farm in the RELIANOID Load Balancer.

Prerequisites

Replace <API_KEY> with your actual API key.
Replace <RELIANOID_SERVER> with the actual server address of your RELIANOID Load Balancer.
Replace <FARM_NAME> with the actual farm.
Ensure that you have the necessary API permissions enabled.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls -bor [Net.SecurityProtocolType]::Tls11 -bor [Net.SecurityProtocolType]::Tls12

# Define variables
$apiKey = "<API_KEY>"
$server = "<RELIANOID_SERVER>"
$farmName = "<FARM_NAME>"

# Define the API endpoint URL
$apiUrl = "https://${server}:444/api/v4.0/api.cgi/farms/$farmName"

# Make the API call using Invoke-RestMethod
$response = Invoke-RestMethod -Uri $apiUrl -Method Get -Headers @{ "API_KEY" = $apiKey } -SkipCertificateCheck

# Output the response
$response

Explanation

1. Variables:

$apiKey: Your API key.
$server: The address of your RELIANOID Load Balancer.
$farmName: The name of the farm you want to retrieve information about.

2. API Endpoint URL:

$apiUrl: Constructed using the server address and farm name.

3. Invoke-RestMethod:

-Uri $apiUrl: Specifies the API endpoint.
-Method Get: Specifies the HTTP GET method.
-Headers @{ "API_KEY" = $apiKey }: Adds the API key to the request headers.
-SkipCertificateCheck: Skips SSL certificate validation (equivalent to -k in curl). This is useful for testing or when the server uses a self-signed certificate.

4. Output:
The response from the API call is stored in the $response variable and then outputted to the console.

Please refer to the official Apidoc to have more information about this call https://www.relianoid.com/apidoc/v4.0/#retrieve-farm-by-name

Adding a new Backend in Farm #

This script performs a POST request to add a new backend to a specific service within a farm on the Relianoid load balancer.

Prerequisites

Replace <API_KEY> with your actual API key.
Replace <RELIANOID_SERVER> with the actual server address of your RELIANOID Load Balancer.
Replace <FARM_NAME> with the actual farm.
Replace <HTTP_SERVICE> with the HTTP service where the backend will be added.
Replace <BACKEND_IP> with the IP of the new backend.
Replace <BACKEND_PORT> with the PORT of the new backend.
Ensure that you have the necessary API permissions enabled.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls -bor [Net.SecurityProtocolType]::Tls11 -bor [Net.SecurityProtocolType]::Tls12

# Define variables
$apiKey = "<API_KEY>"
$server = "<RELIANOID_SERVER>"
$farmName = "<FARM_NAME>"
$serviceName = "<HTTP_SERVICE>"

# Define the API endpoint URL
$apiUrl = "https://${server}:444/api/v4.0/api.cgi/farms/$farmName/services/$serviceName/backends"

# Define the request body
$requestBody = @{
    ip = "<BACKEND_IP>"
    port = <BACKEND_PORT>
    weight = 1
    priority = 1
} | ConvertTo-Json

# Make the API call using Invoke-RestMethod
$response = Invoke-RestMethod -Uri $apiUrl -Method Post -Headers @{
    "Content-Type" = "application/json"
    "API_KEY" = $apiKey
} -Body $requestBody -SkipCertificateCheck

# Output the response
$response

Explanation

1. Variables:

$apiKey: Your API key.
$server: The address of your RELIANOID Load Balancer.
$farmName: The name of the farm you want to add a new backend.
$serviceName: The name of the service within the farm where the backend will be added.

2. API Endpoint URL:

$apiUrl: Constructed using the server address, farm name, and service name.

3. Request Body:

$requestBody: Contains the JSON payload with the backend server details. It is converted to JSON format using ConvertTo-Json.

4. Invoke-RestMethod:

-Uri $apiUrl: Specifies the API endpoint.
-Method Post: Specifies the HTTP POST method.
-Headers @{ "Content-Type" = "application/json"; "API_KEY" = $apiKey }: Adds the Content-Type and API_KEY to the request headers.
-Body $requestBody: Specifies the JSON payload for the POST request.
-SkipCertificateCheck: Skips SSL certificate validation (equivalent to -k in curl). This is useful for testing or when the server uses a self-signed certificate.

5. Output:
The response from the API call is stored in the $response variable and then outputted to the console.

Please refer to the official Apidoc to have more information about this call https://www.relianoid.com/apidoc/v4.0/#create-a-new-backend

Enable Backend in maintenance mode #

This script performs a PUT request to set a backend server to maintenance mode on the RELIANOID Load Balancer.

Prerequisites

Replace <API_KEY> with your actual API key.
Replace <RELIANOID_SERVER> with the actual server address of your RELIANOID Load Balancer.
Replace <FARM_NAME> with the actual farm.
Replace <HTTP_SERVICE> with the HTTP service where the backend will be put in maintenance.
Replace <BACKEND_ID> with the ID of the backend to modify the maintenance mode.
Ensure that you have the necessary API permissions enabled.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls -bor [Net.SecurityProtocolType]::Tls11 -bor [Net.SecurityProtocolType]::Tls12

# Define variables
$apiKey = "<API_KEY>"
$server = "<RELIANOID_SERVER>"
$farmName = "<FARM_NAME>"
$serviceName = "<HTTP_SERVICE>"
$backendId = <BACKEND_ID>

# Define the API endpoint URL
$apiUrl = "https://${server}:444/api/v4.0/api.cgi/farms/$farmName/services/$serviceName/backends/$backendId/maintenance"

# Define the request body
$requestBody = @{
    action = "maintenance"
    mode = "drain"
} | ConvertTo-Json

# Make the API call using Invoke-RestMethod
$response = Invoke-RestMethod -Uri $apiUrl -Method Put -Headers @{
    "Content-Type" = "application/json"
    "API_KEY" = $apiKey
} -Body $requestBody -SkipCertificateCheck

# Output the response
$response

Explanation

1. Variables:

$apiKey: Your API key.
$server: The address of your RELIANOID Load Balancer.
$farmName: The name of the farm where the backend to put in maintenance is added.
$serviceName: The name of the service within the farm where the backend will be in maintenance.
$backendId: The ID of the backend to put in maintenance mode.

2. API Endpoint URL:

$apiUrl: Constructed using the server address, farm name, and service name.

3. Request Body:

$requestBody: Contains the JSON payload with the action and mode for setting the backend to maintenance mode. It is converted to JSON format using ConvertTo-Json.

4. Invoke-RestMethod:

-Uri $apiUrl: Specifies the API endpoint.
-Method Put: Specifies the HTTP PUT method.
-Headers @{ "Content-Type" = "application/json"; "API_KEY" = $apiKey }: Adds the Content-Type and API_KEY to the request headers.
-Body $requestBody: Specifies the JSON payload for the PUT request.
-SkipCertificateCheck: Skips SSL certificate validation (equivalent to -k in curl). This is useful for testing or when the server uses a self-signed certificate.

5. Output:
The response from the API call is stored in the $response variable and then outputted to the console.

Please refer to the official Apidoc to have more information about this call https://www.relianoid.com/apidoc/v4.0/#backend-in-maintenance

Further API documentation #

For more detailed information about the API calls available for managing the RELIANOID Load Balancer, you can refer to the official API documentation at RELIANOID API Documentation. This comprehensive resource provides detailed descriptions of each API endpoint, including the required HTTP methods, request parameters, and response formats.

The documentation is structured to help you understand how to interact with various aspects of the load balancer, such as managing farms, services, and backends, as well as monitoring system status and performance. Each API call is accompanied by examples and explanations to guide you through the process of crafting your requests and handling the responses. This is an essential resource for system administrators and developers looking to automate and streamline their load balancer management tasks using the API.