Generate API SDK for F5 Distributed Cloud

 

Introduction

F5’s Distributed Cloud (F5 XC) is a feature rich SaaS offering. Controlling these features is available using the web console, Terraform scripts, CLI (Vesctl) and direct REST API calls. This article will discuss using REST API calls via Swagger generated SDK clients and simplifying this process using F5’s open-sourced, API-Tools. This tool set is written in Python and provides an easier way to generate multiple SDK clients at once using a single configuration file. Also provided are API integrations for some common F5 XC tasks and a generated sample Python script for creating new API integrations. The steps in this article are performed on either a Linux or Mac system.

Background

F5 exposes most features of F5 XC services through API endpoints, as documented here. The scrolling window on the left side of this API documentation site lists all the different sections of the API users can leverage. 

Each of these items is documented with an OpenAPI specification that is available for download. Examples of API usage are available on this documentation site, including leveraging the CURL application for REST API calls. This document is helpful for creating scripts or custom integrations with F5 XC. Sometimes, multiple different API sections of F5 XC are needed in an integration or creating API clients directly is not desired.

Swagger.io's Codegen , can be used to generate an SDK client from a given OpenAPI specification file. This generated SDK client contains the code needed for developers to initiate a client for communicate with the REST API endpoint, as well as a model with the various API data attributes. This process is well documented on the Swagger.io's website; a given OpenAPI file creates a single SDK client. However, due to the large number of abundant features F5 XC provides, each API section is contained inside its own OpenAPI specification file. This means if your custom script or integration requires multiple API sections of F5 XC, multiple SDK client generations would be required. Each of these SDK clients would then need to be installed and configured inside the custom integration code. To help with this edge case, and to standardize single SDK client generation, the API-Tool application was created and released.

Generating Multiple SDK Clients

The API-Tools helpers can be used to simplify the creation of multiple SDK Clients. First clone the code repository located at API-Tools . Next download any OpenAPI specification files you wish to generate clients for. To find these file downloads, navigate to the F5 Dev Portal. Enter your F5 XC domain and click Access Portal. On the left-hand side of the page, select the API section you wish to use. Then on the top of the page find the swagger.json file and download the file. Make sure these files are stored under codegen/in/swagger/. To follow along with the examples detailed in this article, download the swaggers for the API sections Namespace and Configure HTTP Load Balancer. The Swagger.io Codegen process wrapped in API-Tools uses Docker, so ensure Docker is installed and running on your build system. More details on Docker can be found on Docker's website . Now create the file sdk.requirements inside the local cloned API-Tools folder. This file will contain the shortened name of each OpenAPI client desired. You can find these names by running the generateSDK.py script from inside the API-Tools folder. Below is an example where two OpenAPI specification files were downloaded, namespace and views_http_loadbalancer.

python3 generateSDK.py --listAllSwagger

swagger: namespace file_path: codegen/in/swagger/docs-cloud-f5-com.public.ves.io.schema.namespace.ves-swagger.json

swagger: views_http_loadbalancer file_path: codegen/in/swagger/docs-cloud-f5-com.public.ves.io.schema.views.http_loadbalancer.ves-swagger.json

Notice from the output a shortened name is provided along with the full file path of the downloaded swagger file. If no output is given or it is not as expected, confirm that the F5 XC swagger file is downloaded correctly into your local api-tools/codegen/in/swagger folder. To create both of these SDK clients, populate the sdk.requirements files as shown below.

namespace
views_http_loadbalancer

Now generate the SDK clients using the command python3 dockerSDKPackager.py. When the dockerSDKPackager.py script runs, it looks at the sdk.requirements file for a list of swagger clients to generate. It then looks through the codegen/in/swagger folder to find the matching swagger file for the actual generation. Next the script will download the Swagger.io Codegen docker container and run the generation for each swagger defined in the requirements file. If the command is successful, the new SDK clients will be present under the codegen/out directory.

Installing SDK Clients

Once SDK clients are generated, they need to be installed before they can be used in custom scripts and integrations, otherwise an error message like the following would be received.

ModuleNotFoundError: No module named 'f5xc_views_http_loadbalancer_client'

The preferred way to install Python SDK clients is by using a virtual environment. This creates a separate folder structure, path variables, and local install repository to contain everything needed for a specific application. The main benefit of using a virtual environment is the applications and modules downloaded are separated from the Operating System, helping make sure the application and its dependencies are unmodified by OS level updates. These virtual environments also work well for transferring applications and all their needed dependencies to different hosts without a lot of effort. Run the command below to create a virtual Python environment named F5-demo.

python3 -m venv F5-demo

The virtual environment is created in a directory with the name given, F5-demo in this example. Virtual environments must be activated, which is to configure the required environment variables like $PATH to point to the correct location of packages. This is done by running the following command.

source F5-demo/bin/activate

Now any SDK client that was generated can be installed in the F5-demo virtual environment. The command below simplifies this by installing any SDK client generated by the API-Tools helper. If only a specific SDK is required, then that SDK should be given instead of the wildcard (*).

python3 -m pip install codegen/out/*

Processing ./codegen/out/namespace
Preparing metadata (setup.py) ... done
Processing ./codegen/out/views_http_loadbalancer
Preparing metadata (setup.py) ... done
Collecting certifi>=2017.4.17
Downloading certifi-2022.12.7-py3-none-any.whl (155 kB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 155.3/155.3 kB 4.4 MB/s eta 0:00:00
Collecting python-dateutil>=2.1
Using cached python_dateutil-2.8.2-py2.py3-none-any.whl (247 kB)
Collecting six>=1.10
Using cached six-1.16.0-py2.py3-none-any.whl (11 kB)
Collecting urllib3>=1.23
Downloading urllib3-1.26.13-py2.py3-none-any.whl (140 kB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 140.6/140.6 kB 4.2 MB/s eta 0:00:00
Using legacy 'setup.py install' for F5 XC-namespace-client, since package 'wheel' is not installed.
Using legacy 'setup.py install' for F5 XC-views-http-loadbalancer-client, since package 'wheel' is not installed.
Installing collected packages: urllib3, six, certifi, python-dateutil, F5 XC-views-http-loadbalancer-client, F5 XC-namespace-client
Running setup.py install for F5 XC-views-http-loadbalancer-client ... done
Running setup.py install for F5 XC-namespace-client ... done
Successfully installed certifi-2022.12.7 F5 XC-namespace-client-0.0.0 F5 XC-views-http-loadbalancer-client-0.0.0 python-dateutil-2.8.2 six-1.16.0 urllib3-1.26.13

The SDK clients have now been installed in the virtual environment and can be used in custom scripts.

Example Run: cert-expire.py

The API-Tools helper contains more than just a wrapper for SDK client generator, it contains some common F5 XC integrations. One of those common integration is found in the helpers/certs/cert-expire.py folder of the API-Tools repository. This helper connects to the API using both the namespace and views_http_loadbalancer generated SDK clients to view all Load Balancer objects in all Namespaces. Then all HTTP certificate expire dates are displayed. This is very helpful to ensure any configured sites do not go down due to expired certificates. To simplify configuration, all API-Tools helpers use CLI argument option --config to provide the F5 XC API endpoint and required authentication Token. An example of a configuration file is below. If you do not already have an API Token for the desired F5 XC console, create one now and populate a configuration file.

{
"Host" : "https://<tenant>.console.ves.volterra.io",
"APIToken" : "<REMOVED>"
}

Change into the helpers folder and run the following command. This assumes the configuration file created is named config.json and is stored in the root directory of the API-Tools repository.

python3 certs/cert-expire.py --config ../config.json

A sample output is shown below.

{
  "namespace1": {
    "customsite1": {
      "domain": "customsite1.testing.org",
      "expires": "01/15/2023, 19:05:29"
    }
  },
  "namespace2": {
    "customsite2": {
      "domain": "customsite2.testing.org",
      "expires": "02/06/2023, 13:24:37"
    },
  },
}

Conclusion and Next Steps

This article has demonstrated how to use F5’s API-Tools helpers to simplify SDK client generation, install generated SDK clients and run common F5 XC API helpers. The scripts located in the folder helpers can be referenced to continue exploring how API-Tools can be used to simplify F5 XC API integrations. There is a script generated under the folder sample each time the generateSDK.py script is run. This sample script is a good starting point for creating new API integrations, as the new SDK client is already imported. Additionally, the configuration file parsing is included for simplifying F5 XC API authentication. A future article will continue exploring using F5’s API-Tools helper by walking through writing a new custom F5 XC API integration.