Cloud Services

Introduction to Cloud Services

Expand menu Collapse menu

Introduction to Cloud Services

Generic Proxy Adapter

Published On Jul 07, 2025 - 2:10 PM

Generic Proxy Adapter

Installing the Generic Proxy Adapter that allows communication between repositories and Enterprise Marketplace.

The Generic Proxy Adapter establishes a secure communication channel between repositories and Enterprise Marketplace. It takes requests from Enterprise Marketplace generated by the wsmesh service and forwards them to the appropriate API endpoints so that services can be provisioned. The Generic Proxy Adapter currently works with GitHub.

The Generic Proxy Adapter is only used with the Foundation APIs. If your tenant does not use them, this does not apply.

Prerequisites

The following prerequisites need to be met before the Generic Proxy Adapter can be installed on your tenant:

Docker must be running on the tenant.

The service ID needs to have an access policy that at least provides Platform and Enterprise Marketplace access and the Administrator and Order Administrator roles. For more information, see IAM overview.

Based on the API calls made from proxy container to Enterprise Marketplace, the Access policies should be updated for the roles under Enterprise Marketplace.

Fetching the service ID and API key

To create a connection between GitHub and Enterprise Marketplace, you need the Service ID and the API Key for that ID. To get them, complete these steps:

Navigate to the Service ID that you created for GitHub integration in your Kyndryl Modern Operations Applications tenant. It can be located on the IAM:Identity and Access Management
page. To learn more about navigating to the different services from each tenant, refer to Landing page navigation or Kyndryl Bridge Landing page navigation.

Copy the Service ID from the URL of the Kyndryl Modern Operations Applications tenant. The ID is the alphanumeric string immediately after

/service-ids/

and before

/view/

The service ID needs to have an access policy that at least provides the Platform Operator role. For more information, see IAM overview.

To generate the API Key, click Manage
→ Add API Key
.

Record the generated API Key and store it in a secure location. It will not be displayed again.

Installing the Generic Proxy Adapter

Complete the following steps to install the Generic Proxy Adapter in your tenant:

Navigate to the Developer Console. To learn more about navigating to the different services from each tenant, refer to Landing page navigation or Kyndryl Bridge Landing page navigation.

In the Application
field, select EMP
.

In the Service
field, select consume_common_api
.

Scroll down to the Proxy Installer
section.

Run the POST /common/v1/proxy/installer
API with the following parameters to download the compressed file:

Accept:
"application/zip"

Parameter content type:
"application/json"

Payload:
{}

In the Responses
section, click
Download file
.

Save the compressed file in a convenient location on the computer or virtual machine where the proxy container will be run and extract it.

Open the configs.env
file and change the following parameters to match your tenant:

export IAM_SERVICE_ID=<IAM service ID>

export IAM_SERVICE_API_KEY= <IAM service API key>

Copy the PROXY_ID from the configs.env
file.

Running the proxy container

Complete these steps to run the proxy container:

If you need to change the proxy or run it again with modifications, delete the existing container and images by using ./delete_conatiner.sh
.

Run the docker login
command and enter the appropriate user name and password to log in to Docker Hub.

Logging in ahead of time reduces the chance of rate limit issues.

Run the installer.sh
file to create a secure network extension (proxy) Docker image: ./installer.sh
.

Run the run_container.sh
file to create the secure network extension (proxy) container: ./run_container
.

Run the check_logs.sh
file to check the logs of secure network extension container to ensure that the container is deployed and is communicating with Enterprise Marketplace: ./check_logs.sh
.

The container is running and should be connected to EMP wsmesh
.

To run a container with an existing proxyId, provide the following payload in the installer zip API:

{
existing_proxyId = "{existing proxy ID}"
}

After the compressed file is downloaded, run the container again.

Creating a connection to GitHub

After installing the Generic Proxy Adapter, you need to create a connection to GitHub to allow communication between the adapter and GitHub. To do so, complete these steps:

Navigate to the IAM: Identify and Access Management
page. To learn more about navigating to the different services from each tenant, refer to Landing page navigation or Kyndryl Bridge Landing page navigation.

In the navigation pane, click Connections
.

Click Add New
→ Add Connection
.

Enter the following parameters and then click Add
:

Connection Name:
Enter a descriptive name for the connection.

Select tags:
(optional) Add tags if desired to help categorize the connection.

Description:
(optional) Enter a more detailed explanation of the connection.

Select Technology Category:
Select Content Provider
.

Select Connection Type:
Select GitHub
.

User ID:
Email address of the user that is used to log in to GitHub.

Host URL:
API gateway URL of the GitHub repository. In the example repository https://github.kyndryl.net/MCMP-Marketplace/gcs-content-template
, the Host URL would be api.github.kyndryl.net
.

ProxyID:
This is the ID that you copied from the config.env
file that you used to create the proxy container. Despite this field being labeled as optional, it is in fact required
.

Repository URL:
API gateway URL of the GitHub repository. In https://github.kyndryl.net/MCMP-Marketplace/gcs-content-template
, the Repository URL is api.github.kyndryl.net
.

User:
Owner/Organization of the repository. In https://github.kyndryl.net/MCMP-Marketplace/gcs-content-template
, the User is MCMP-Marketplace
.

Personal Access Token:
User specific GitHub Token. For information about generating this token, see https://docs.github.com/en/[email protected]/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.

Project:
Name of the repository. In https://github.kyndryl.net/MCMP-Marketplace/gcs-content-template
, the Project is gcs-content-template
.

Branch:
Select the branch of the repository that you want to use. Generally this will be master
.

Creating an adapter registration for GitHub provider

Before GitHub and Enterprise Marketplace can communicate, you must create an adapter registration in GitHub using these steps:

Navigate to the Developer Console. To learn more about navigating to the different services from each tenant, refer to Landing page navigation or Kyndryl Bridge Landing page navigation.

Enter these parameters:

Application:
EMP

Service:
consume_common_api

Scroll down to the Client Management API
section.

Run the POST /emp/common/clients API to create a new subscriber with the following payload:

{
   "name":"order_fulfillment_github",
   "provider_code":"github",
   "applicable_for":[
       {
           "id":"integration",
           "values":[
               "OrderFulfillment"
           ],
           "workflowId":"",
           "eventType":""
       }
   ],
   "callback":{
       "url":"github.kyndryl.net/api/v3/repos/MCMP-Marketplace/gcs-content-template",
       "certs":{
           "endpoint_ca_cer":"",
           "endpoint_cer":"",
           "endpoint_key":""
       },
       "headers":{
           
       },
       "connection_protocol":"https"
   }

Curl command: curl -X 'POST' \ '<BASE_HOST_URL>/consume/emp/common/clients' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer <bearer token>' \ -d '{ "name":"order_fulfillment_github", "provider_code":"github", "applicable_for":[ { "id":"integration", "values":[ "OrderFulfillment" ], "workflowId":"", "eventType":"" } ], "callback":{ "url":"github.kyndryl.net/api/v3/repos/MCMP-Marketplace/gcs-content-template", "certs":{ "endpoint_ca_cer":"", "endpoint_cer":"", "endpoint_key":"" }, "headers":{ }, "connection_protocol":"https" } }'

Note the following about the payload:

provider_code:
github.

values:
OrderFulfillment.

eventType:
Required if user wants to trigger repository dispatch on GitHub Action. The following payload will be received by GitHub for repository dispatch:

{
   "event_type": "value of eventType",
   "client_payload": {
       "empOrderPayload": order details in json format
   }
}

workflowId:
The ID of the workflow. You can also pass the workflow file name as a string. Required if user wants to trigger workflow dispatch on GitHub Action. The following payload will be received by GitHub for workflow dispatch:

{
   "ref": "GitHub branchname",
   "inputs": {
       "empOrderPayload": order details in stringify json format
   }

If both eventType
and workflowId
are empty/null then values from applicable_for will be used as eventType
to trigger repository dispatch GitHub Action. If both fields have values, then repository dispatch will be triggered by using eventType
.

Creating a GitHub provider in Enterprise Marketplace

To create a GitHub provider in Enterprise Marketplace so that Enterprise Marketplace can send requests to GitHub, complete these steps:

Navigate to the Developer Console. To learn more about navigating to the different services from each tenant, refer to Landing page navigation or Kyndryl Bridge Landing page navigation.

Enter these parameters:

Application:
EMP

Service:
catalog_api

In the Catalogs section, locate and run the POST /catalog/v3/providers_adapters API with the following payload:

{
   "providers_adapters": [
       {
           "provider": "GitHub",
           "providerCode": "github",
           "adapter": "http://localhost:5000/genericcontentserver/v1/providers/github",
           "discoverContent": true,
           "providerOfferingTypes": [
               "iaas"
           ],
           "manageSOEnabled": true,
           "enableVersion": false
       }
   ]
}

The container is automatically connected to Enterprise Marketplace using wsmesh
: <BASE_HOST_URL >/api/wsmesh/v3/proxy/<proxy_id>?timeout=600 with the header {"Authorization": "Bearer <wsmesh token>"} with the following request body. No intervention is needed.

{
   "body": {
     "request_id": random_uuid,
     "request_resource": encoded base64 provisioning request data
    },
    "type": "proxy"
}

The request_resource should contain the API definition that needs to be passed to the proxy container. The GPA will parse this body and execute the API as per API definition. The following is sample request_resource code:

{
 "url": "url",
 "method": "method",
 "headers": {},
 "body": {},
 "tags": {
   "orderNumber": "",
   "serviceFulfillmentId":"",
   "requestTrackingId": ""
 },
 "failureCallback": {
   "url": "url",
   "method": "method",
   "headers": {},    
   "body": {}
 }
}

In the sample code, failureCallback
is the object that contains the URL, method, headers and body (if needed) to make an API call back to the source that needs to be notified if a failure occurs where the proxy container is not able to reach git actions.

The Tags
parameter is optional. You can pass it as empty {} => “tags”:{}

The connection is now established between the Enterprise Marketplace and the proxy adapter container, which is running in private network. Place orders to test the connection and the end-to-end flow.

Enabling MTLS

When the proxy container initiates the connection to Enterprise Marketplace to open web socket, the inbound call to EMP from the proxy adapter in the network must be through mutual TLS (mTLS). To enable mTLS, complete the following steps:

Edit the Dockerfile and uncomment these lines that refer to the volume mount to the docker container:

#ENV VOLUME_PATH /certs

#VOLUME ${VOLUME_PATH}

Open the configs.env
file and update the export CERTS_FOLDER="”
variable with the values of the folder path containing the certificates and names of the files containing the certificates, for example export CERTS_FOLDER=”/tmp/certs”
. The folder path of your host machine where the certificates are stored will be mounted as a volume to the proxy adapter container.

Add the file names of the client key, client cert and ca cert in the following variables. The Proxy container will create the socket connection with the certificates provided.

       export CA_CERT_FILE_NAME=""
       export CLIENT_KEY_FILE_NAME=""
       export CLIENT_CERT_FILE_NAME=""

While trying to generate the IAM token if there is any error the container will retry three times. If IAM token generation fails the three retries, then container will be stopped. Re-run the container using the following steps:

Delete the existing proxy container and image using the following command: ./delete_container.sh
.

Run the run_container.sh
file to create the secure network extension (proxy) container: ./run_container
.

For information about storing the issuer and subject with foundation and registering the client certificates with IAM, see https://pages.github.kyndryl.net/MCMP-Foundation/docs/mtls-inbound/.

Introduction to GitOps

Introduction to provider management

Do you have two minutes for a quick survey?

Take Survey