Cloud Services

Enterprise Marketplace

Service template importing from GitHub
Published On Dec 17, 2024 - 12:58 PM

Service template importing from GitHub

Set up a GitOps repository so you can automatically import catalog templates from it.
You can set up a GitOps repository that acts as storage for your catalog templates. If you do so, each template added to the repository is automatically added into Enterprise Marketplace a catalog. You can find these new catalogs on the
Catalog Management
 page in
Draft
 state unless you set the
Publish
 flag as
True
 in the
mcmp.yaml
 file. For more information about managing catalogs after creation, see Provider management. The process involves these steps:

Creating a GitHub repository

To set up GitHub to store templates, complete these steps:
  1. Create a
    Private
     repository in GitHub. Public repositories are not supported.
  2. Make a note of the initial branch name. This is generally
    main
    .
  3. In the
    main
     branch, create a folder called
    mastercontent
    .
  4. Locate any templates that you want to import in the Terraform Registry. Create the templates for the catalogs that you want to add to the Catalog and save them in the
    mastercontent
     folder in the
    main
     branch of the repository. Commit your changes in GitHub as needed. You can create subfolders within
    mastercontent
     to keep your files organized. The templates must be in the Terraform format.

Structuring your repository

For all repositories, only folders should exist at the root level, which are considered the master folders. Each master folder should contain one subfolder for each catalog. Each subfolder can have an individual
mcmp.yaml
 file, if desired. For more information, see Running the GitHub mcmp.yaml file. The following rules apply to different template types:
  • Terraform templates:
     If you are including more than one file, all of the files must be grouped together in a single directory.
  • Native templates:
     How these are structured depends on how the content server handles the flow. Consult the user documentation for the individual provider.
The following are some valid repository structures. They all assume the repository
github.<orgname>.net/<user-or-org>/<reponame>
.
  • The master folder includes one
    mcmp.yaml
     file and a catalog folder that consists of a
    main.tf
     file. 
    
Master-folder
------mcmp.yaml
------service-offering1
------------main.tf
  • The master folder consists of a catalog folder that consists of a
    mcmp.yaml
     file and a
    main.tf
     file. 
    
Master-folder
------service-offering2
------------main.tf
------------mcmp.yaml
  • The master folder consists of a
    mcmp.yaml
     file and a folder that contains all the files for the catalog. This structure is used for Terraform templates. 
    
Master-folder
------service-offering3
------------mcmp.yaml
------------complex_template
------------------main.tf
------------------variables.tf
------------------outputs.tf
  • The following example illustrates how
    mcmp.yaml
     precedence works in a complex repository. 
    
Master-folder
----mcmp.yaml (GLOBAL mcmp.yaml configuration, any serviceoffering without a mcmp.yaml will use this)
----service1/ (Master-folder/mcmp.yamlwill be used)
--------main.tf
----service2/ (Master-folder/service2/mcmp.yaml will be used)
--------main.tf
--------mcmp.yaml
----service3/ (Master-folder/service3/mcmp.yaml will be used)
--------mcmp.yaml
--------complex_template/
------------main.tf
------------output.tf

Creating a personal access key

To access the GitHub from Kyndryl Modern Operations Applications, you will need an access key. To generate it, 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. Provide a name for your token by completing the
    Note
     field.
  7. Select the
    Repo
     check box.
  8. Click
    Generate token
    .

Creating an organization in Kyndryl Modern Operations Applications

To create an asset account for GitHub, you must create an organization and team to associate the personal access key with. To do so, complete the steps in Organizations management.

Creating a team in Kyndryl Modern Operations Applications

To create an asset account for GitHub, you also must create a team to associate the personal access key with. To do so, 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 GitHub 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.
  • 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 Engineering deployment without administrative access should not be added to teams that have permissions other than the
    Buyer
     permissions.
This section has examples of team set ups that can help you understand the logic behind team permissions.

Engineering (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 catalog 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 Engineering team to have access to secure keys that will be configured into the GitHub pipelines and webhook information that will be configured into GitHub.

Buyers (Business Requesters, Engineering Deployment Team)

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

Configuring a provider account

To link Kyndryl Modern Operations Applications with GutHub, you must create a provider account by completing these steps:
  1. Log in to Kyndryl Modern Operations Applications.
  2. 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.
  3. The page displays a list of the accounts created. Click the
    Asset Accounts
     tab and then click
    New Asset Account
    .
  4. On the
    New Asset Account
     page, select
    GitOps
    .
  5. Enter a
    Name
     and an optional
    Description
     for your account.
  6. In the
    Endpoint URL
     field, enter your GitHub’s repository username URL, such as
    https://[your enterprise domain]/api/v3/repos/[username]
    .
  7. Keep the
    Status
     as
    Active
    .
  8. Click
    Create Account
    .

Adding credentials

After you have configured your provider account, complete these steps to add a credential:
  1. EmteIn the provider account, click
    Add Credential
    .
  2. Enter a
    Name
     and an optional
    Description
     for your credential.
  3. In the
    Purpose
     menu, select
    Provisioning
     and
    Catalog Ingestion
    .
  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 in Kyndryl Modern Operations Applications.
  6. The
    Branch name
     field should be
    main
     unless you changed the name of the initial branch.
  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 key that you created in Creating a personal access key.
  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
    .

Adding a webhook

The webhook is the link between Kyndryl Modern Operations Applications and your GitHub repository that retrieves your templates for conversion. You must add a webhook for each provider that you want to retrieve templates for. To add the webhook, complete these steps:
  1. Log in to Kyndryl Modern Operations Applications.
  2. 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.
  3. In the
    Application
     field, select
    consume
    .
  4. In the
    Service
     field, select
    GitOps_API
    .
  5. Click
    List Webhook Listener
    .
  6. Click
    Try it out
    .
  7. Click
    Execute
    .
  8. In the output, locate and copy the code for the provider that you are interested in. Copy the URL for the webhook and the mcmpwebhooktoken onto a notepad.
    You can also provide the providerCode during execution. To locate the code, navigate to the
    Terraform Provider Management
     page. Copy the code from the tile for that provider.
  9. Open your GitHub repository.
  10. Click
    Settings
    .
  11. Click
    Hooks
     in the left navigation pane.
  12. Click
    Add webhook
    .
  13. Paste the webhook URL that you got using the API into the
    Payload URL
     field.
  14. In
    Content type
    , select
    application/json
    .
  15. In
    Secret
    , paste the mcmpwebhooktoken that you got using the API.
  16. Leave
    SSL verification
     as
    Enable SSL verification
    .
  17. Leave
    Just the push event
     selected.
  18. Leave the webhook as
    Active
    .
  19. Click
    Add webhook
    .

Running the GitHub mcmp.yaml file

The
mcmp.yaml
  file controls all the content import behavior in the directory structure where you place the file. Configure your file based on the procedures in Configuring the GitOps mcmp.yaml file. The
monitoring
 branch name will be
main
 unless you changed it. One file is needed for each subfolder/provider. Place the completed file in the subfolder that contains that provider's information, if applicable. The
mcmp.yaml
 must be placed carefully because the innermost file in the tree takes precedence. Commit the file using the following commands:
git add mastercontent.<subfolder>/mcmp.yaml
git commit -m "mcmp.yamlfile added"
git push origin main
You will need to enter your passphrase. After this is done, the webhook will be triggered and your templates will be imported into Kyndryl Modern Operations Applications.
Do you have two minutes for a quick survey?
Take Survey