Cloud Services

Enterprise Marketplace

GitHub integrations
Published On Oct 11, 2024 - 8:21 AM

GitHub integrations

Concerns how to set up GitHub in order to create catalogs.
Before creating any catalogs in GitOps, you need to create a directory structure where you will organize the catalogs in your Git repository and create a GitOps configuration using the
mcmp.yaml
file.

Directory structure and conventions

Create a
mastercontent
directory in the root of your GitOps repository. This directory can contain subfolders to better organize your master request forms.
You need to place a single
master_request_form
JSON file in each subdirectory, which can be based on the Master request form data model available on GitHub integrations. This JSON file will be pulled into Kyndryl Modern Operations Applications when you commit the file in the repository. It will then be parsed by Kyndryl Modern Operations Applications to generate a catalog that will be visible to Buyers to configure and order in Enterprise Marketplace.
You can create any folder in the root of your repository. For example, you can create a folder called
templates
and use to it keep templates where you do not want to ingest the content into Kyndryl Modern Operations Applications to be visible as
DRAFT
or
PUBLISHED
.
Kyndryl Modern Operations Applications will ignore any JSON files that you have placed outside the
mastercontent
directory when ingesting content.

Configuring the GitOps mcmp.yaml file

Configure the
mcmp.yaml
file to control the content import behavior of all content in the directory structure where you place this file. You have these options:
  • To enforce a global behavior for importing, publishing, and versioning, create a single
    <git_root>/mastercontent/mcmp.yaml
    file in your
    mastercontent
    directory. You are not required to place another
    mcmp.yaml
    file in any of the subdirectories that you have created to further organize your content.
    If a top-level
    mcmp.yaml
    file is defined in the root of the
    mastercontent
    directory, and you alter the file (such as changing a configuration option), Kyndryl Modern Operations Applications will recognize it as a configuration change and will not attempt to pull the JSON file or parse it for that commit.
  • To enforce a single import, publish, and versioning behavior for specific sets of content, place a
    mcmp.yaml
    file in any subdirectory where you want to override the configuration of the
    mcmp.yaml
    files in the parent directories relative to that directory.
    For example, if you need all content to be imported as a
    DRAFT
    in the Catalog by default, but you also need some content to be published by default, you can place an
    mcmp.yaml
    file configured to not publish during the import in the top-level directory and override it by placing another
    mcmp.yaml
    file in a subdirectory where other content is organized. You can configure this
    mcmp.yaml
    file to automatically publish GitOps content where it is placed so it is visible to Buyers in the Enterprise Marketplace Catalog.
Consider the following data model of an
mcmp.yaml
file when creating your own file:
  • type:
    (required) Type of import request. The default is
    gitops
    , which is the only allowed value.
  • deployment:
    (optional) This section identifies the infrastructure you will deploy the applications on. It includes the following subsections:
    • deployedby:
      The underlying technology used during the deployment, such as Terraform.
    • serviceofferingids:
      The IDs of the infrastructure resource catalog that you want your clients to be able to select during the ordering process. All stacks of that type of deployment will automatically be included in the
      Additional Parameters
      section of the catalog.
  • repoconfig:
    (required) The
    mcmp.yaml
    subsection for GitOps content.
  • publish:
    (required) Publish the catalog content automatically. Allowed values are
    true
    and
    false
    , of which the default is
    true
    .
  • monitoring:
    (required) Branch name that will be monitored by Kyndryl Modern Operations Applications for ingesting GitOps content as catalogs. Only required if a separate Git branch for your content is needed, for example if you want to use master for templates that should not be imported to Kyndryl Modern Operations Applications and use a branch called content for content that needs to be imported to Kyndryl Modern Operations Applications as a catalog. In this case, this parameter can be configured as content to let Kyndryl Modern Operations Applications know which branches are to be used. The branch
    must
    exist before this commit where this parameter is defined in any of the
    mcmp.yaml
    files. Allowed values take the form
    master \< my content branch name for my content repo >
    , such as
    master mybranch
    .
  • defaultPricingAccountTeam:
    The ID of the team in Kyndryl Modern Operations Applications that has permissions to order catalogs for at least one required provider account in Kyndryl Modern Operations Applications such as  IBM Cloud. The required provider account associated with this team is used to request pricing from the provider for the resources that will be provisioned during the deployment. Only IBM Cloud is currently supported for resource pricing. The allowed values are the
    < Kyndryl Platform Team ID >
    , such as
    MYTEAM-Consume
    .
  • versions:
    (required) The
    mcmp.yaml
    subsection for GitOps content.
  • defaultVersion:
    (required) The version selected by default when the user configures an order. The user can change the version. The allowed value is  your specific default version for the catalog, controlled by this
    mcmp.yaml
    . Example:
    master my_version_string 1.0.0.0 ubuntu-xenial
  • values:
    (required) The
    mcmp.yaml
    subsection for GitOps content.
  • < version values >:
    (required) A list of your version strings that control the versions you want to be available for deployment, such as the version of your applications deployed by your DevOps pipelines or the pipelines themselves. The version selected by the user will be available to your pipeline after the order is approved in Enterprise Marketplace. The allowed value is  your specific default version for the catalog, controlled by this
    mcmp.yaml
    . Example:
    master my_version_string 1.0.0.0 ubuntu-xenial
Use the following script as an example of the minimal parameters to set up the
mcmp.yaml
file:
type: gitops repoconfig: releaseRepo: myorg/mcmpgitopsrelease publish: true monitoring: master defaultPricingAccountTeam : MYTEAM-Consume versions: defaultVersion: 2.0 values: - master - 1.0 - 1.1 - 2.0
The following example shows a more complex use case where the application deployment is targeted at a Day 0 Terraform stack that creates infrastructure. Note the deployment section that points to the Terraform-based infrastructure catalog.
type: gitops deployment: deployedby: terraform serviceofferinggroups: [“<service offering group ID>”] repoconfig: releaseRepo: myorg/mcmpgitopsrelease publish: true monitoring: master defaultPricingAccountTeam : MYTEAM-Consume versions: defaultVersion: 2.0 values: - master - 1.0 - 1.1 - 2.0

Creating a master request form

A master request form is a single JSON file within your
mastercontent
directory. Name it so that its function is clear (for example,
mastercontent.json
,
myapp.json
, or
productionstack.json
). This file specifies the structure of a single GitOps catalog that will be visible to Buyers in the Enterprise Marketplace Catalog. It is used to define an order configuration form format that contains the configuration parameters that the user must specify to request a GitOps pipeline workflow.
The following types of items can be added into a master request form:
  • Arrays:
    Single or multi select arrays, such as Environment or Dev/Test/Staging/Production.
  • Text inputs:
    Strings, names, numbers, such as username, example.com, mongodb, or versions of specific components of your application stack or release pipeline.
  • Dates and datetimes
  • Secure Credentials:
    Passwords or other secure data, which will be masked from the user.
  • Kyndryl Modern Operations Applications provider account references:
    References to other provider accounts in Kyndryl Modern Operations Applications. When an order is approved and committed to your Git repository for approved orders, the credentials from these accounts will be added to the request forms as encrypted keys that your pipelines can use.

User interface supported component types for master request forms

The following component types are supported for master request forms.
Type
UI Type
Use Case
Min/Max Size
Default Value
Array
multiselect
If user must select more than one value from a dropdown.
Applicable
Date
date
If user wants to provide a date while ordering.
Applicable
Datetime
datetime
If user wants to provide a date and time while ordering.
Applicable
Password
password
If user wants to provide sensitive information.
String
checkbox
The checkbox is a square box that is ticked (checked) when activated.
Applicable
String
freetext
A simple text box where the user is free to enter any information.
Applicable
Applicable
String
numberinput
A simple text box where user is free to enter data in numeric format only.
Applicable for numberinput, specify the step value
Applicable
String
radio
Option that allows user to choose only one of a predefined set of mutually exclusive options.
Applicable
String
selectOne
If user must select one value from a dropdown.
Applicable
String
textArea
A larger text box to collect user inputs in multiline format.
Applicable
Applicable

Master request form data model

The following is the data model for the master request form:
  • mcmpOffering:
    (required) Request Form subsection for the catalog details/metadata.
  • name:
    (required) Name of the catalog that will be displayed in the Enterprise Marketplace Catalog. This name is visible to Buyers when they navigate to the catalog, and it can also be searched for when using the Catalog search feature.
  • serviceDetails:
    Details about what the catalog provides, such as "Kyndryl Modern Operations Applications is a digital consumption and delivery suite with integration and orchestration layers."
  • features:
    Description of the catalog features. The allowed values are a list of objects.
  • features.description:
    Bullet point description for each feature to provide more information. The allowed values are a list of strings.
  • features.shortDesc:
    Online short description for each feature, such as "Visibility to your multicloud management and governance." The allowed values are any strings.
  • parameters:
    (required) Attribute that includes all available parameters for user configuration. The allowed values are any objects.
  • parameters.configGroupName
    (required) Identifier for the group that the catalog belongs to. The allowed values are any strings.
  • parameters.configGroupName.configName:
    (required) Identifier for the configuration attribute, such as "region." The allowed values are any strings.
  • type:
    (required) Attribute that determines which type of data this configuration accepts. The allowed values are string, date, datetime, and password.
  • uitype:
    (required) Attribute that determines the type of values accepted according to datatype (subset of value for a datatype). The allowed values are selectOne, password, checkbox, freetext, numberinput, radio, searchList, and textArea.
  • description:
    Readable description that tells what the configuration parameter does, such as "Select IBM Cloud datacenter region." This parameter allows a string.
  • values:
    (required) Set of values to be shown for a particular configuration attribute. This parameter requires an object such as the one shown in the following example:
    { "Frankfurt (fra)": "fra", "London (lon)": "lon", "Washington DC (wdc)": "wdc", "Sydney (syd)": "syd", "Dallas (dal)": "dal", "Tokyo (tok)": "tok" } array example: ["mango", "apple", "banana"]
  • defaultValue:
    One of the values set up in the 'values' attribute can be configured as a default value. Only
    one
    default value is allowed. This parameter requires an object such as the one shown in the following example:
    { "Frankfurt (fra)": "fra" }
  • ui-label:
    (required) The value given against the ui-label for a configuration parameter will be displayed as a header for that configuration parameter. It provides information about the usage of the parameter. The parameter requires a string such as "Select IBM Cloud datacenter region."
  • isHidden:
    (required) Flag that determines the visibility of the parameter on the user interface. The allowed values are Boolean.
  • isEditable:
    Flag that determines whether the parameter can be edited or not post provisioning during the stack edit flow. The allowed values are Boolean.
  • isRequired:
    (required) Attribute that determines whether this parameter is required to progress forward. If a parameter is marked required true within a configuration group, then if that parameter is not configured the user cannot proceed to configure other groups. The allowed values are Boolean.
  • visibilityRule:
    Placeholder that determines whether the parameter for which the rule is being added should be hidden or not, based on the values selected by the user in other parameters. An example is "deploymentModel=='shared'", in which the deploymentModel is the identifier of a different parameter, and if deploymentModel is equal to shared, then the current parameter for which this rule is being enforced is hidden.
  • validation:
    Configuration parameter Request Form subsection for required validations for the parameter.
  • validation > regularExpression:
    Set validation to use a regular expression. For more information, see documentation about regular expressions.
  • dependsOn:
    (required) This parameter can be used if there are any parameters whose values should be loaded dynamically upon the selection of a prior parameter. Each parameter inside the dependsOn object will be explained in rows below. This parameter requires an object.
  • dependsOn.type:
    Parameter based on the type of the behavior of loading the values change, such as "Non-external." This parameter requires an object.
  • dependsOn.dependent-values:
    (required) This parameter contains the values that need to be loaded based on each value of the parent parameter. There is a
    parentConfig
    attribute that holds the key value pair of a parameter and its value. In the example,
    { "deploymentModel": "dedicated",   ”deploymentModel”
    identifies the parent parameter, and “dedicated” identifies its value. The
    values
    array will be displayed when the user selects dedicated as the value for the parent parameter. There can be another object with a different value of the parent parameter and a different set of values as dependent-values takes list of objects.
    [ { "parentConfig": { "deploymentModel": "dedicated" }, "values": [ "Upto 2 tenants", "Upto 5 tenants" ] } ]
  • dependsOn.dependent-values[0].parentConfig:
    (required) Object that contains the key values of a parent parameter, and its value and values array that contain the values of the child parameter. Example:
    { "parentConfig": { "deploymentModel": "dedicated" }, "values": { "master":"master" } }
  • dependsOn.dependent-values[0].values:
    (required) Object of key values/list of strings that denotes the values that will be rendered dynamically based on the parent parameter selection. This parameter requires an object or a list/array of strings. Example:
    { "master":"master" } ####################### [ "Upto 2 tenants", "Upto 5 tenants"
Do you have two minutes for a quick survey?
Take Survey