Cloud Services

Enterprise Marketplace

Generic Proxy Adapter
Published On Sep 20, 2024 - 12:19 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:
  1. 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.
  2. 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 - Editor and Enterprise Marketplace access - Order Administrator roles. For more information, see IAM overview.
  3. To generate the API Key, click
    Manage
    Add API Key
    .
  4. 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:
  1. 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.
  2. In the
    Application
    field, select
    EMP
    .
  3. In the
    Service
    field, select
    consume_common_api
    .
  4. Scroll down to the
    Proxy Installer
    section.
  5. 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:
      {}
  6. In the
    Responses
    section, click
    Download file
    .
  7. Save the compressed file in a convenient location on the computer or virtual machine where the proxy container will be run and extract it.
  8. 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>
  9. 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
.
  1. Run the
    installer.sh
    file to create a secure network extension (proxy) Docker image:
    ./installer.s
    h.
  2. Run the
    run_container.sh
    file to create the secure network extension (proxy) container:
    ./run_container
    .
  3. 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
    .
  4. 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.

Create 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:
  1. 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.
  2. In the navigation pane, click
    Connections
    .
  3. Click Add New → Add Connection.
  4. 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:
  1. 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.
  2. Enter these parameters:
    1. Application:
      EMP
    2. Service:
      consume_common_api
  3. Scroll down to the
    Client Management API
    section.
  4. 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:
  1. 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.
  2. Enter these parameters:
    1. Application:
      EMP
    2. Service:
      catalog_api
  3. 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 } ] }
  4. 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:
  1. Edit the Dockerfile and uncomment these lines that refer to the volume mount to the docker container:
    • #ENV VOLUME_PATH /certs
    • #VOLUME ${VOLUME_PATH}
  2. 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.
  3. 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:
  1. Delete the existing proxy container and image using the following command:
    ./delete_container.sh
    .
  2. 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/.
Do you have two minutes for a quick survey?
Take Survey