Streamlining projects with the Red Hat Partner Connect API

Introduction

This post is the second in a series where we will be discussing the Partner Connect API. In case you missed it, please see the first post here where we introduced the Partner Connect API and provided some fundamental getting started information. In this post, we will dive deeper by examining the first use case that was introduced: Project Creation. Using the Partner Connect API is recommended for large products that are made up of tens or hundreds of container images.

Partner Connect Projects

When starting the software certification process, the first step is to create one or more Projects. Projects are organizational units within Partner Connect that have a one-to-one relationship with the container images that make up a partner’s certification product. A product can contain as many projects as necessary to correspond with the number of images. Projects are certified individually following this workflow: 1) Creation, 2) Image Upload, 3) Scanning, 4) Remediation, 5) Publishing. Today, we will be examining how to automate the first two steps in this workflow using the Partner Connect API. For further information on projects you can see our Partner Guide here. 

Prerequisites

We explained in the previous post that small certification products, which contain only a handful of images, can be certified manually using the Partner Connect web interface without much effort. However, for larger products, that may contain tens or even hundreds of images and projects, the Partner Connect web interface would be time consuming and inefficient. For products of this scale we suggest using the Partner Connect API. 

Create a product

First, using the Partner Connect web interface, you must create a Product within the Partner Connect system. This is required so that Projects created later can be attached to a parent Product.

Create a product

1. Navigate to Partner Connect using a web browser
2. Navigate to Product Certification > Manage products > Create Listing
3. Enter Product name and major version
4. Select OpenShift Operator or Containerized Product
5. Click Create listing

Second, you need to collect your Company ID from the Partner Connect web interface. This value will be used later when working with the API.

Company ID

1. Navigate to My Company > View company information
2. Note the URL. It will be in the following format:

            https://connect.redhat.com/node/#######/view

The ####### portion of the URL is the Company ID - record this seven digit integer.

Project Creation Functions

Now it’s time to create a project. Note that you can always refer to the complete list of Partner Connect API v2 functions here. We will, however, focus on the following key and value pair options. 

OS Content Type (os_content_type) has two options for container type. Note that UBI is the suggested value for RHEL 8 compatibility.

Distribution Method (distribution_method) specifies the hosting location of the project’s container images where they will be consumed by the end customer. Note that the Red Hat Container Catalog value enables hosting of containers, and Red Hat Marketplace hosting compatibility for Operators. Choosing an external registry would prevent Marketplace compatibility and require a separate Marketplace Only project to be created if hosting on the Red Hat Marketplace is desired. Only one value is allowed.

Registry Vendor (registry_vendor) is used in conjunction with Distribution Method above and is used to specify the external registry vendor if chosen.

Additionally, the following static values will be used later and are noted here for convenience.

Create Project

In this scenario we will be using curl on the command line. You could also use a utility like Postman as we discussed in the previous post. The following command should be used as a reference for creating projects. Note here that the values in italics must be replaced. This specific command creates a UBI container project using an external registry for hosting that is neither Docker or Quay.io. This example would support the use case where a partner’s private registry would be used for hosting.

This command does the following:

• Authenticates using the API_KEY value
• Creates a container project with the name PROJECT_NAME
• Associates the project with the company identified with COMPANY_ID
• The release category of GA is set for this project
• The container project is of type UBI
• The ‘own’ hosting option is set, which requires the ‘external’ distribution method, indicating that neither the Red Hat registry, Docker, or Quay.io will be used for hosting (this indicates a private registry)
• A repository namespace, description, and path are set
• Static fields for Red Hat product ID, version, and supported platforms indicating OpenShift are set
• Application categories applicable to the project are set

$ curl -X POST "https://connect.redhat.com/api/v2/projects" \

-H "accept: */*" \

-H "Authorization: Bearer API_KEY" \

-H "Content-Type: application/json" \

-d "{\"zone\":\"containers\",\"project_name\":\"PROJECT_NAME\",\company_id\":COMPANY_ID,\"project_type\":\"Container Application\",\"rel_cat\":\"generally_available\",\"rh_product_id\":3602271,\"rh_product_version\":3602281,\"os_content_type\":\"Red Hat Universal Base Image (UBI)\",\"registry_vendor\":\"Own\",\"registry_override_instruct\":\"Registry usage instructions here.\",\"repo\":\"REPO_NAMESPACE\",\"repo_desc\":\"Description of repo.\",\"repo_path\":\"registry.example.com:5000/path/to/repository\",\"support_platforms\":[\"OpenShift Container Platform\"],\"application_categories\":[\"Automation\",\"Business Process Management\",\"Developer Tools\"],\"distribution_method\":\"external\"}"

After running this command successfully, output will be similar to the following:

"status":"Ok","message":"Project created.","code":200,"data":{"rid":"4209251","pid":"ospid-3b0fedb9-c611-4a70-bf1e-b2a6323dd00e","api":"https://connect.redhat.com/api/v2/projects/ospid-3b0fedb9-c611-4a70-bf1e-b2a6323dd00e"}}

Note that the pid value is the unique project identifier for the project we just created. You can verify that the new project exists using the following curl command. Note the italicized values must be replaced.

$ curl -X GET "https://connect.redhat.com/api/v2/projects/PROJECT_ID" \

-H "accept: */*" \

-H  "Authorization: Bearer API_KEY"

Attach Project to Product

The project must now be associated with an existing product to be certified. This is required because later on in the certification workflow, the container image must be published to complete certification and be populated in the Red Hat Container Catalog and, if applicable, the OpenShift Embedded OperatorHub.

1. Select Product Certification > Manage products
2. Select the Product
3. Click Certification Projects on the left side
4. Click the appropriate Attach Project button (note Project type created above)
5. Select the new Project
6. Click Attach

Conclusion

In this post, we looked at the process for using the Partner Connect API to create certification projects that make up a product. The steps described here can be used from the command line or incorporated into scripts and custom tools with the goal of improving efficiency and enabling automation. In future posts, we will look at additional use cases for the Connect API. Watch this space for updates!