Cloud Services

Enterprise Marketplace

GitOps intregration with Enterprise Marketplace
Published On Jun 13, 2024 - 12:12 PM

GitOps intregration with Enterprise Marketplace

Configuring GitOps to integrate with Enterprise Marketplace.
To configure GitOps to work with Kyndryl Modern Operations Applications, you must first set up an account in GitHub and then configure Kyndryl Modern Operations Applications to work with that account. Any templates that you place in the GitOps repository are ainutomatically imported into your Catalog.

Account setup on GitHub

Before configuring these features, you must perform a setup in GitHub to be able to link your account to Kyndryl Modern Operations Applications. The setup involves these steps:
  1. Create a GitHub organization.
  2. Create a GitHub personal access token.
  3. Create your GitHub repositories.

Creating a GitHub organization

To create a GitHub organization from scratch, if you have not done so already, complete these steps:
  1. Navigate to GitHub.
  2. Click the profile icon on the right side and click
    Settings
    .
  3. Click the
    Organizations
    tab.
  4. Click
    New organization
    .
  5. Provide a name for your organization account and click
    Next
    .
  6. Click
    Complete setup
    or
    Skip this step
    to continue.

Creating a GitHub personal access token

To create a personal access token to use in place of a password with the command line or the GitHub API, complete these steps:
  1. Navigate to GitHub.
  2. Click the
    Profile
    icon on the right side and click
    Settings
    .
  3. Click the
    Developer settings
    tab.
  4. Click the
    Personal access tokens
    tab.
  5. Click
    Generate a new token
    .
  6. Enter a name for your token in the
    Note
    field.
  7. Select the
    Repo
    checkbox.
  8. Click
    Generate token
    .
In the next screen, make sure to copy your new personal access token because this is the only time that it will be displayed.

Creating a GitHub repository

You need to create at least two repositories:
  • GitHub repository for approved orders:
    Kyndryl Modern Operations Applications uses a separate repository for approved orders to ensure that your DevOps pipelines/infrastructure is not triggered for any release/deployment request commits that have not been approved by the correct owners in Kyndryl Modern Operations Applications. This repository will be used to commit information related
    only
    to orders that have been approved in Kyndryl Modern Operations Applications. Your pipelines can use Kyndryl Modern Operations Applications to process the request.
  • GitHub repository for GitOps content and submitted orders not yet approved:
    Kyndryl Modern Operations Applications uses this repository for GitOps content and for submitted orders that have not been approved yet. This repository is used for these operations:
    • Ingesting request forms used for your GitOps/DevOps deployment workflows into Kyndryl Modern Operations Applications.
    • Committing information related to orders that have been approved in GitHub.
    Order tracking information for GitOps should not be committed by your pipelines to the repository used for approved orders because this action would trigger an unwanted commit webhook to your deployment pipelines.

Creating a repository

To create a repository, complete these steps:
  1. Navigate to GitHub.
  2. Click the profile icon on the right side and click
    Settings
    .
  3. Click the
    Repositories
    tab.
  4. Click
    Create one
    .
  5. Provide a name for your repository.
  6. Provide an optional description.
  7. Select whether the repository will be
    Private
    or
    Public
    .
  8. Select the
    Initialize this repository with a README
    checkbox, if wanted.
  9. Click
    Create repository
    .

Creating branches for the repositories

You must create the following branches in your repositories:
  • GitHub repository for approved orders repository:
    Create a branch called
    RELEASE
    . This is a mandatory requirement for Kyndryl Modern Operations Applications to be able to commit request forms to this repository.
  • GitHub repository for GitOps content and submitted orders not yet approved repository:
    Create a branch called
    Orders
    . This is a mandatory requirement for Kyndryl Modern Operations Applications to commit order tracking folders to the GitHub repository for approved orders. You will also be able to commit your own manually created order templates to this repository to kick off orders without navigating to Kyndryl Modern Operations Applications. Do not delete anything on this branch because doing so will impact the ability to trace previous orders placed using GitOps.

Configuration in Kyndryl Modern Operations Applications

All GitOps features are available for any Kyndryl Modern Operations Applications tenants that were created after May 2021, which was when these features were released. For tenants that were created before this date, the GitOps adapters have not been integrated automatically as part of the tenant onboarding process, so additional configuration is required. If this is the case, follow the configuration script available at https://github.kyndryl.net/MCMP-Integrations/cb-int-configurations/tree/master/GIT/setup_gitops to configure your Kyndryl Modern Operations Applications tenant with the following information:
usage: ./setup_gitops_adapter.sh [-h api-hostname] [-u username] [-p apikey]" -h (Required): Enterprise Marketplace API url. tenant API gateway url -u (Required): userid. userid to be used to connect with your Enterprise Marketplace tenant -p (Required): apikey. apikey required to connect with Enterprise Marketplace tenant
If you get an error message and the script does not work, repeat the configuration process again.

Creating an organization

To create an organization, complete the steps in Organizations management.

Creating a team

To create a team, complete the steps in Teams management.
Team and organization setup in Kyndryl Modern Operations Applications is flexible, but follow these guidelines to avoid security compliance issues:
  • Business requesters (such as delivery teams), who need to request GitOps deployments, should not be added to any team that has
    Financial Approver
    or
    Technical Approver
    permissions, or to any team that can modify Enterprise Marketplace approval policies.
    Buyer
    permissions are sufficient for business requester teams.
  • DevOps Engineering users, who require administrative access as well as the ability to place orders, can be made part of both approver and buyer teams as required for their roles in the organization.
  • Users who are only required to raise requests for DevOps Engineering deployment without administrative access should not be added to teams that have permissions other than the
    Buyer
    permissions.
This section has three examples of team set ups that can help you understand the logic behind team permissions.

DevOps Engineering (The DevOps Engineering Team)

Functionalities
Required permissions
  • Access the Secure Deployment Key request API
  • Access the webhook URL list API
  • Manage DevOps deployment master request forms  and submit deployment requests for approval
  • Create master request forms for SO ingestion
  • Create orders from Git
  • System Admin
  • Catalog Administrator
  • Provider Account Admin
The ID of this team needs to be added to the
Team
configuration parameter for the GitOps account credential that will be used to authenticate with GitHub. This configuration enforces security compliance to only allow the DevOps Engineering team to have access to secure keys that will be configured into the DevOps pipelines and webhook information that will be configured into GitHub.

Buyers (Business Requesters, DevOps Engineering Deployment Team)

Functionalities
Required permissions
  • Business Requester
  • Place orders from catalog
  • Buyer

GitOps Approver (Budget Administrator Team)

Functionalities
Required permissions
  • Manage budgets
  • Approve orders
  • Technical Approver
  • Financial Approver
  • Budget Administrator
Technical Approver, Financial Approver, and Budget Administrator can also be separate teams, as required by your organization.

Configuring budgets

For information about budget configuration, see Budget management.

Configuring a GitOps provider account

To configure a GitOps provider account, go to Kyndryl Modern Operations Applications and complete these steps:
  1. Navigate to the
    Provider Account
    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. The page displays a list of the accounts created. Click the
    Asset Accounts
    tab and then click
    New Asset Account
    .
  3. On the
    New Asset Account
    page, select
    GitOps
    .
  4. Enter a
    Name
    and an optional
    Description
    for your account.
  5. In the
    Endpoint URL
    field, enter your GitHub’s repository username URL, such as
    https://[your enterprise domain]/api/v3/repos/[username]
    . For standard GitHub, this would be
    https://api.github.com/repos/[organizationname]
    .
  6. Keep the
    Status
    as
    Active
    .
  7. Click
    Create Account
    .

Adding credentials

After you have configured your provider account, complete these steps to add a credential:
  1. In the provider account, click
    Add Credential
    .
  2. Enter a
    Name
    and an optional
    Description
    for your credential.
  3. In the
    Purpose
    menu, select
    Provisioning
    .
  4. In the
    Project
    field, enter the name of the repository that you created previously. See Creating a GitHub repository.
    You have two options when creating credentials for your repositories. The first option is to create separate credentials for each of the repositories. The second option is to create a single credential for both repositories. If this is the case, simply enter both repository names in the
    Project
    field separated by a comma.
  5. In the
    Team
    field, enter the ID of a team with System Admin privileges, as created in Creating a team.
  6. The
    Branch name
    field should be left blank because this is only required if the credential is to be used for catalog ingestion.
  7. Keep the
    Status
    as
    Active
    .
  8. Select the
    Create New or Update Credential in Vault
    checkbox to enable the
    Token
    field.
  9. In the
    Token
    field, enter the personal access token that you created in Creating a GitHub personal access token.
  10. In the
    Associate this credential with a business entity
    section, select the
    Associate
    checkbox, select
    Organization
    from the
    Business Entities
    menu, and select the organization name that you created earlier from the
    Values
    menu.
  11. Click
    Add
    .

Configuring public cloud provider accounts for resource pricing

Only IBM Cloud resource pricing is available in the current release. Resource pricing for other providers will be available in the future.
For information about configuring IBM Cloud provider accounts, see Getting started with IBM Cloud.

Viewing generated webhook URLs in Kyndryl Modern Operations Applications

To view the webhook URLs on the Developer Console, go to the Developer Console and look for the
List Webhook Listener API
.
You can also run the following API:
curl --request GET 'https://mcmp-emp-pdm-demo-api.multicloud-ibm.com/adapter/webhooklisteners' \ --header 'apikey: <apikey that is obtained from the Developer Console => API key . We can find the developer console on the right>' \ --header 'username: <userid that we get from the tenant instance by clicking on the profile icon on to the right side>' \ --header 'Content-Type: application/json' \ ample generated webhook url
Only users who are part of the DevOps administration team configured into the GitOps provider account will be able to access this API using the Developer Console. If other users attempt to use this API, the request will fail with a 401 error.
The URL and secret (
mcmpwebhooktoken
) can be configured in your GitHub repository so that Kyndryl Modern Operations Applications can receive webhooks from your repository in GitHub.
Use the following information to configure the webhook in GitHub:
{ "providerCode": "git", "mcmpwebhooktoken": "5f24f7bf-5222-4fe1-8e7d-99eef878e640", "url": "https://mcmp-emp-pdm-demo-api.multicloud-ibm.com/adapter/webhooks/git" }

Configuring webhooks in GitHub

To configure a webhook in GitHub, go to your GitHub repository and complete the
Creating webhooks
steps in GitHub Docs.

Generating deployment keys for your DevOps pipeline

Kyndryl Modern Operations Applications can generate deployment keys for you to let users send encrypted information as part of their GitOps order configured in Kyndryl Modern Operations Applications.

Generating deployment keys using the key request API

You can generate deployment keys using the key request API. When used with a passphrase, the API generates the following keys:
  1. RSA public and private key pair
  2. AES256 data key
The API returns the RSA private key to the requester, and the public key and data key are retained in Kyndryl Modern Operations Applications. All keys that are generated are "global" and can be replaced by using the key request API at any time. The key can be downloaded from the Developer Console where it is generated.
Only users who are part of the DevOps administration team configured into the GitOps provider account can access this API using the Developer Console. If other users attempt to use this API, the request will fail with a 401 error.
To access the key request API, go to Kyndryl Modern Operations Applications and 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. In the Application field, select
    consume
    .
  3. In the Service field, select
    GitOps_API
    .
  4. In the
    Key Request API
    section, select the POST API.
  5. Click
    Try it out
    .
  6. In the
    keys request body
    section, substitute the
    “string”
    text with your preferred passphrase.
  7. Click
    Execute
    .
If you wish to rotate your current keys with new keys, you will need to run the API and select the
true
parameter from the
Regenerate
menu. This ensures that the keys are not replaced unintentionally.
Run the following API from your command line to generate your key for the first time:
curl --location --request POST 'https://mcmp-emp-pdm-demo-api.multicloud-ibm.com/adapter/encryption/generateKeys' \ --header 'apikey: <apikey that is obtained from the Developer Console => API key . We can find the developer console on the right>' \ --header 'username: <userid that we get from the tenant instance by clicking on the profile icon on to the right side>' \ --header 'Content-Type: application/json' \ --data-raw '{ "password": "<passphrase>" }'
After you have generated the keys, you will receive the private key. Store this key in a secure location that can be accessed by your pipelines/jobs.

Decrypting secure encrypted information in your pipelines

After you have generated the keys and stored them in a secure location, your pipelines/jobs can decrypt secure encrypted information sent by Kyndryl Modern Operations Applications in the request forms using the following workflow:
  1. Parse the request form to get the encrypted information, the encrypted AES256 data key, and the encrypted initialization vector used for the AES256 data key.
  2. Decrypt the AES256 data key encrypted with the public key using the private key.
  3. Decrypt the encrypted information received in the request form using the AES256 data key.
For your pipelines to decrypt the encrypted information from the request forms, you might need to configure decryption and other pipeline job logic to implement the decryption workflow. Deployment keys and encrypted information can be decrypted by using any command line tool or encryption framework or library used by your pipelines/jobs, such as GnuPG or openSSL.
The following example shows how credentials can be decrypted. You can implement your own pipeline/job decryption logic using this example as a reference:
#!/bin/bash echo "this script is tested on rhel 8 and ubuntu 20.04" encryptedCredentials="$ENCRYPTED_CREDS" ecryptedAESDataKey="$ENCRYPTED_DATA_KEY" ecryptedIV="$ENCRYPTED_IV" privatekeyfilepath="$PRIVATE_KEY_FILEPATH" openssl rsa -in $privatekeyfilepath -out decryptedprivatekey.pem #decrpyt datakey using privatekey echo -n $ecryptedAESDataKey | base64 --decode | openssl rsautl -decrypt -inkey decryptedprivatekey.pem -out datakey.json -keyform PEM -oaep decryteddatakey=$( jq '.data' datakey.json ) #decrpyt IV using privatekey echo -n $ecryptedIV | base64 --decode | openssl rsautl -decrypt -inkey decryptedprivatekey.pem -out iv.json -keyform PEM -oaep decrytediv=$( jq '.data' iv.json ) convert_buffer_to_hex() { buffer=$1 spaced_array=$(echo "$buffer" | tr , " ") final_array=$(echo "$spaced_array" | tr [] " ") # Variable to hold hex value hex="" for ss in $final_array; do hex="$hex$(printf "%02x" "$ss")" done echo "$hex" } #converting datakey to hex hexedkey=$(convert_buffer_to_hex "$decryteddatakey") echo "$hexedkey" #converting iv to hex hexediv=$(convert_buffer_to_hex "$decrytediv") echo "$hexediv" # decrypt credentials using key and iv echo $encryptedCredentials | base64 -d | openssl enc -aes-256-cbc -A -d -p -out credentials.txt -K $hexedkey -iv $hexediv -nosalt -nopad
To run this sample script, export the following environment variables. The script takes these variables as input:
#encrypted credentials value received in the Request Form export ENCRYPTED_CREDS="" #encrypted data key received in the Request Form export ENCRYPTED_DATA_KEY="" #encrypted Initialization Vector value received in the Request Form export ENCRYPTED_IV="" #absolute filepath where private key is located on the system export PRIVATE_KEY_FILEPATH=""
After exporting the variables, run the script using the following command:
`sh decryption.sh`
This action should result in the following output:
$ ./decryption.sh Enter pass phrase for ./private.pem: writing RSA key 249c6022e2bc32c6b755c72147740d017fe1xxxxxxxxxxxxxxxxxxxxxxxxx key=249C6022E2BC32C6==================================================== iv =9DD301D2DBxxxxxxxxxxxxxxxxxxx
The credentials for this sample script are written to a file called
credentials.txt
. You can view the decrypted credentials using a text editor.
`cat credentials.txt`
Do you have two minutes for a quick survey?
Take Survey