How to query the Red Hat Insights API for Red Hat Enterprise Linux Application Streams life cycle information?

Updated -

This tutorial provides information on how to query the Red Hat Insights API for Red Hat Enterprise Linux (RHEL) Application Streams Life Cycle information. To keep this tutorial brief I will link to existing documentation where I see fit.

The following guidelines are based on official Red Hat Documentation and knowledge articles and intend to provide information to accomplish the user's needs. It must be reviewed, monitored, and revisited by customers and partners according to its own business requirements, application workloads, and new demands.

User Story

As a systems administrator I would like to query the Red Hat Insights API for the RHEL Application Streams life cycle information to process them automatically and programmatically for life cycle management and documentation in our internal tooling.

Terminology

In this knowledge article I discuss how to check RHEL Application Streams life cycle information. I might call this app streams for short. This information is provided by an API that is called Planning in our API documentation. In the API URL we call it roadmap however.

So the URL https://console.redhat.com/api/roadmap/v1provides access to the Insights for RHEL Planning API where you can find life cycle information for RHEL app streams and other things.

Requirements

Get an access token to query the Insights REST API

To get an <access_token> for the first involves multiple steps:

  1. Create a service account on the Hybrid Cloud Console
  2. Optional: Associate it with a user group with the appropriate permissions
  3. Use this service account credentials to obtain an <access_token> that is valid for 15 minutes

Lifecycle data is open in the sense that you only need a service account to query the API. This applies any API with /roadmap/v1/lifecycle/ in their path. Follow the steps 1-5 and 7 from configuring service account access to obtain an <access_token>.

If you like to query an API with /roadmap/v1/relevant/in the path you need to assign your service account to some suitable group. In case you don't have a suitable group, you need to create one and add at least the role RHEL viewer to it.1 The following screenshot shows a minimal example of a group that would be sufficient. You can skip this step if you only interested in lifecycle information.

The screenshot shows the group settings of a group named grp-query-insights-api with the assigned role RHEL Advisor viewer and the service account svc-insights-api as only member of the group.
Fig. 1: Screenshot of a group for the service account

I use the following curl command to check whether my request returns an <access_token>:

$ curl https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token -d "grant_type=client_credentials" -d "scope=api.console" -d client_id=<client_id> -d client_secret=<client_secret>

The expected output looks similar to the following code block where <access_token> is the placeholder for the string with my actual token:

{"access_token":"<access_token>","expires_in":900,"refresh_expires_in":0,"token_type":"Bearer","not-before-policy":0,"scope":"api.console"}

The <access_token> needs to be submitted with each request in the Bearer HTTP header. It expires after 15 minutes.

API Documentation

General documentation on how to use our Insights APIs can be found in:

Documentation on the Insights for RHEL Planning API can be found at:

These are two different presentations of the same specification. Both provide information about available endpoints and how to query them, giving some examples for curl and python.

Examples

The following examples illustrate how curl can be used to query life cycle information for app streams from the Insights API. More endpoints can be found in the API documentation. For example, the API provides information regarding:

  • Lifecycle dates for app streams modules packages
  • App stream modules and packages for a specific RHEL version
  • List package names for a specific RHEL version
  • List app stream names for a specific RHEL version
  • Return lifecycle data for all RHEL versions
  • Full lifecycle dates for all major versions of RHEL
  • App streams based on hosts in inventory
  • RHEL lifecycle dates for systems in inventory
  • Upcoming changes, deprecations, additions, and enhancements

More generally speaking this API provides multiple endpoints for information on roadmap and lifecycle of RHEL and app streams. Check out the documentation for further information. I this tutorial I focus on just two simple examples in more detail.

List app stream names in RHEL 9

$ curl --request GET --url https://console.redhat.com/api/roadmap/v1/lifecycle/app-streams/9/streams --header 'Authorization: Bearer <access_token>' --header 'Content-Type: application/json' | jq

{
  "meta": {
    "count": 594,
    "total": 594
  },
  "data": [
    ".NET 6",
    ".NET 7",
    ".NET 8",
    ".NET 9",
    "Ansible Core",
    "Apache httpd 2.4",
    "BIND 9.18",
    "Firefox",
    "GNU Autoconf (Latest Version)",
    "GNU Make (Latest Version)",
    "Git",
    "Go",
    "IDM",
    "JBoss mod_cluster for Apache",
    "Java Mission Control",
    "LLVM",
    "MariaDB 10.11",
    "MariaDB 10.5",
    "Maven 3.8",
    "MySQL 8.0",
    "NGINX 1.20",
    "NGINX 1.22",
    "NGINX 1.24",
    "Node.js 16",
    "Node.js 18",
    "Node.js 20",
    "Node.js 22",
    "OpenJDK 1.8.0",
    "OpenJDK 11",
    "OpenJDK 17",
    "OpenJDK 21",
    "PHP 8.0",
    "PHP 8.1",
    "PHP 8.2",
    "Perl 5.32",
    "PostgreSQL 13",
    "PostgreSQL 15",
    "PostgreSQL 16",
    "Python 3.11",
    "Python 3.12",
    "Python 3.9",
    "Redis 7",
    "Ruby 3.0",
    "Ruby 3.1",
    "Ruby 3.3",
    "Rust",
    "Thunderbird",
    "Tomcat mod_jk connector for Apache",
    "container-tools",
    "gcc-toolset 14"
  ]
}

Show life cycle information for a specific app stream

For the following example I query the life cycle information of PHP 8.2:

$ curl --request GET --url https://console.redhat.com/api/roadmap/v1/lifecycle/app-streams?application_stream_name=PHP%208.2 --header 'Authorization: Bearer <access_token>' --header 'Content-Type: application/json' | jq

{
  "meta": {
    "count": 2,
    "total": 2
  },
  "data": [
    {
      "name": "php",
      "display_name": "PHP 8.2",
      "application_stream_name": "PHP 8.2",
      "stream": "8.2",
      "start_date": "2019-05-07",
      "end_date": "2029-05-31",
      "impl": "dnf_module",
      "initial_product_version": null,
      "support_status": "Supported",
      "os_major": 8,
      "os_minor": null,
      "lifecycle": null,
      "rolling": false
    },
    {
      "name": "php",
      "display_name": "PHP 8.2",
      "application_stream_name": "PHP 8.2",
      "stream": "8.2",
      "start_date": "2022-05-18",
      "end_date": "2029-05-31",
      "impl": "dnf_module",
      "initial_product_version": null,
      "support_status": "Supported",
      "os_major": 9,
      "os_minor": null,
      "lifecycle": null,
      "rolling": false
    }
  ]
}

Additional information

Upstream, a collection of Ansible playbooks is available to access and query the API. Those are provided as is and not covered by Red Hat Support. You can find them at URL: https://github.com/RedHatInsights/digital-roadmap-backend/tree/main/playbooks

  1. This role might include more permissions as are necessary. To assign least privileges you might need to create a new custom role. I'm going to update this article in regards to this topic in the future. ↩︎

Comments