Supported features

Import and publish the template in the Enterprise Marketplace Catalog
Catalog configuration
Estimated pricing (for certain Terraform resources)
Provisioning and De-provisioning (New and Delete Order)
View inventory stack offering component
Template output params (if specified in the Terraform configuration file during import)

Prerequisites

https://www.terraform.io/docs/configuration/index.html
https://www.terraform.io/docs/configuration/syntax.html
https://www.terraform.io/docs/configuration/blocks/resources/syntax.html
https://www.terraform.io/docs/configuration/data-sources.html
https://learn.hashicorp.com/tutorials/terraform/resource?in=terraform/configuration-language
https://learn.hashicorp.com/tutorials/terraform/variables#parameterize-your-configuration
https://learn.hashicorp.com/tutorials/terraform/dependencies?in=terraform/configuration-language

Overview of steps

Create a Terraform configuration file (written in HashiCorp Configuration Language (HCL) with a
.tf
extension).
Create an
icb_catalog_metadata.json
containing the provider code to be used.
Create a zip file containing the
icb_catalog_metadata.json
at the root level and tf file in a directory (this can be nested based on how you want to structure your directories).
Import this zip file.
Publish that catalog, after which the catalog will be visible on the Catalog for configuring and provisioning.

Onboarding a new provider

Register the Provider Adapter to enable the provider in the Catalog using this API:
Endpoint:

http://cb-catalog-api:5080/catalog/v3/providers_adapters

Method:

POST

Payload:

https://github.kyndryl.net/MCMP-Integrations/cb-int-configurations/blob/master/IBMCLOUD/provider-adapter/provider_adapter.json
Use one of the following options to enable the provider:
Create a new Content Server MicroService as per the provider
Modify an existing microservice to support a new provider
Use GCS
Expose the following required APIs:
GET/POST configurations
GET/POST the templates and catalogs
POST nativeTemplate
GET/POST pricingTemplate
Register the queue subscriptions with the Kyndryl Terraform Engine using the following API:
Endpoint:

http://cb-consume-common-api:7080/emp/common/clients

Method:

POST

Payload:

https://github.kyndryl.net/MCMP-Integrations/cb-int-configurations/tree/master/IBMCLOUD/queue-subscriptions
Create
provider_tf
files with the credential keys for the provider.
Add the provider binary with the require version in the InitContainer.

Creating Terraform configuration files

A provider block
Optional terraform block
Single or multiple resource blocks
Optional data block
Optional output block
Optional depends_on attribute that manages the execution of Terraform resource provisioning if one resource needs to wait for another one to complete
Optional dependency of a resource attribute on another attribute in a different resource (dependency graph)
Optional nested blocks inside a resource
Optional local-exec, remote-exec, and connection provisioners
Variables in a separate configuration file
Multiple resources in separate configuration files

Terraform block

Provider block

provider <provider_name_on_terraform> {}

Amazon Web Services:

provider aws {
region = “us-east-1”
}

Google:

provider google {
region = “asia-east-1”
}

Alibaba Cloud:

provider alicloud {
profile = default
region = ap-south-1
}

Microsoft Azure:

provider azurerm {
features {}
}

IBM Cloud:

provider ibm {}

Resource blocks

resource "aws_instance" "web" {
ami                    = "ami-a0cfeed8"
instance_type          = "t2.micro"
user_data              = file("init-script.sh")

tags = {
  Name = random_pet.name.id
}
}

Implicit and explicit dependencies

resource "aws_instance" "example_a" {
ami           = data.aws_ami.amazon_linux.id
instance_type = "t2.micro"
}

resource "aws_instance" "example_b" {
ami           = data.aws_ami.amazon_linux.id
instance_type = "t2.micro"
}

resource "aws_eip" "ip" {
  vpc = true
  instance = aws_instance.example_a.id
}

resource "ibm_security_group" "sg_public_lamp" {
 name = "sg_public_lamp"
 description = "Public access for LAMP stack to repos"
}

resource "ibm_security_group_rule" "https-pub" {
 direction = "egress"
 ether_type = "IPv4"
 port_range_min = 443
 port_range_max = 443
 protocol = "tcp"
 security_group_id = [ibm_security_group.sg_public_lamp.id]
 depends_on = [ibm_security_group.sg_public_lamp]
}

Data sources

data "ibm_dns_domain_registration" "dns-domain-test" {
  name = "test-domain.com"
}

resource "ibm_dns_domain_registration_nameservers" "dns-domain-test" {
  dns_registration_id =
  data.ibm_dns_domain_registration.dns-domain-test.id
  name_servers = [
      "ns006.name.ibm.cloud.com",
      "ns017.name.ibm.cloud.com"]
}

Provisioners

variable private_key {
  default = ""
}
resource "ibm_compute_vm_instance" "vm1" {
  hostname = "vmremote-exec"
  domain = "example.com"
  os_reference_code = "CENTOS_8_64"
  datacenter = "dal09"
  network_speed = 100
  cores = 1
  memory = 1024
  disks = [25]
  provisioner "remote-exec" {
    inline = [
"mkdir -p /root/test-directory"
]
      connection {
          type = "ssh"
          user = "root"
          host = self.ipv4_address
          private_key = var.private_key
      }
  }
}

Importing and publishing Terraform Templates

The directories inside the zip file uploaded for a provider must contain either Terraform configuration files or provider native templates, but not both. When importing a Terraform template, the directories must contain only Terraform configuration files with a .tf extension.
When importing multiple Terraform files in a single folder, only one of them should contain the provider block.
When importing Terraform configuration files, each folder is considered as one catalog. A single folder can contain multiple .tf files (for example, resource_1.tf, resource_2.tf, variables.tf). When there are multiple terraform configuration files in a folder, they are combined and then used to generate the metadata required.
The cloud provider codes for Terraform and those for the tenant are different. Make sure to add the valid provider code in the provider block of the Terraform configuration file and the provider code in the
icb_catalog_metadata.json
file. Incorrect mapping would result in failure when Catalog Admin tries to import that template.
The following are the corresponding codes for the tenant and Terraform:
Tenant code	Terraform code
ibmcloud	ibm
aws	aws
azure	azurerm
alicloud	alicloud
gcp	google
The provider block in the Terraform configuration file should contain an empty provider block whenever possible. Sample provider blocks for each provider are specified in the Provider block. In any case, the provider block should NOT contain any keys/credential information. Credentials are picked up from the payload during order provisioning and therefore must not be provided in the Terraform configuration files.

Imported service details

provider ibm {}
resource ibm_compute_vm_instance vm1 {
 hostname = “test1”
 domain = “test.co”
}
resource ibm_compute_vm_instance vm2 {
hostname = “test2”
domain = “test.co”
}
resource ibm_security_group secGrp {
name = “testSecGrp”
}

Configuration Group Name: Ibm compute vm instance vm1
Config Name: Ibm compute vm instance vm1 hostname
Config ID: ibm_compute_vm_instance-vm1-hostname

Config Name: Ibm compute vm instance vm1 domain
Config ID: ibm_compute_vm_instance-vm1-domain
=============================================
Configuration Group Name: Ibm compute vm instance vm2
Config Name: Ibm compute vm instance vm2 hostname
Config ID: ibm_compute_vm_instance-vm2-hostname

Config Name: Ibm compute vm instance vm2 domain
Config ID: ibm_compute_vm_instance-vm2-domain
=============================================
Configuration Group Name: Ibm security group secGrp
Config Name: Ibm security group secGrp name
Config ID: ibm_security_group-secGrp-name

Pricing information based on Terraform resource types

Virtual Machine
Virtual Network
Storage Account

Compute Engine
Compute Disk
Cloud Storage
Spanner
Cloud DNS

EC2 (aws_instance)
S3 (aws_s3_bucket)

instance (alicloud_instance)
db (alicloud_db_database)
vpc (alicloud_vpc)

Pricing template available for resources present at https://github.kyndryl.net/MCMP-Integrations/cb-provisioning-template/tree/master/IBMCLOUD/PricingTemplate (all JSON files)

Inventory details

Usage of modules

The parent terraform template that is using modules should be at the root level (not inside a folder). Example:

- icb_catalog_metadata.json
- Temp
  - rich-value-types
      - main.tf
      - network
          - main.tf
          - outputs.tf
          - variables.tf

Variables that need to be configurable also have to be at the root level where the parent terraform template is placed, from inside which the modules are referenced. Example:

- icb_catalog_metadata.json
- Temp
  - rich-value-types
      - main.tf
      - network
          - main.tf
          - outputs.tf
          - variables.tf

Modules that are present inside a catalog should be used for that catalog alone. To use the same module for another catalog, it should be inside the other catalog's folder. Example:

- icb_catalog_metadata.json
- templates
  - Service1
      - main.tf
      - output.tf
      - provider.tf
      - variables.tf
      - MODULE1      //used in main.tf
  - Service2
      - pool.tf
      - provider.tf
      - variables.tf
      - MODULE1      //used in pool.tf

If

required_providers

is used in the

terraform block

of the module (

main.tf

) and also the parent template that uses the module, then both should use the same block. The following block must be present in both

pool.tf

and

main.tf

of the module.

terraform {
required_version = ">=0.13"
required_providers {
   ibm = {
   source = "IBM-Cloud/ibm"
   }
 }
}

For a catalog structure use the following directory structure:

- icb_catalog_metadata.json
- templates
  - Service1
      - pool.tf
      - output.tf
      - provider.tf
      - variables.tf
      - example      // module used in pool.tf
          - main.tf
          - variables.tf

Preferred practices

To attach system-generated tags like SOIID and SID to the provisioned resource, declare tags as variables in the Terraform template because implicit tagging of resources is not supported.
Ensure that no sensitive information is present if the return type of output parameter is an object because whatever JSON object is being returned as output param will be JSON STRINGIFied and shown on the
Ordered Services
page (inventory).
When data type in the variables is map(<>), the value that is present against the default value of the variable with map data type in the Terraform template is carried and shown in a text area in the UI after servicification. If the map data type is used, then the value against default must be supplied in the text area on the
Additional parameters
page.
Importing a Terraform configuration file takes the folder name as the catalog name for the catalog.
Check the features supported by Terraform 1.5.7 and 1.0.9.x version for the Terraform configuration file being created.
Make sure to provide only mandatory attributes in the provider block. Credentials should not be present. References are provided in the Provider block.
One single directory inside the zip file uploaded for a particular provider must contain either Terraform configuration files or provider native templates, but not both.
When importing a Terraform template, a single directory must contain files with a .tf extension.
If there are multiple .tf files in a directory, add the provider block only in one of those files.
Check the mapping of Terraform providers and the tenant provider code when creating the
icb_catalog_metadata.json
file.
Any issues/errors during import can be checked in the Catalog Discovery History.
All configurations on the UI are of freetext inputType and are marked as required. If you want the optional fields to not be marked as required, do not add them in the Terraform configuration file because Terraform will compute those fields during provisioning.
While importing the zip file (containing terraform files) from the
Catalog Admin
page as part of the servicification process, it is a best practice to abstract all the attributes used in your resource section as variables declarations. Doing so will abstract all those attributes and the same attributes will be transformed as configuration attributes for buyers while submitting an order

Known issues

Generic known issues

Only tags added from Terraform templates are supported.
For list(Object)/Set(Object), if there is more than one default value in a template, the user will see only one default value in the Enterprise Marketplace UI.
Dynamic modules are only supported with public Git repositories and Terraform registry modules as source. Private Git repositories are not supported.
In Bulk VM, per quantity price is not supported.
Price will be calculated for single unit even if "count" in the Terraform template contains count in resource.
For variables of the type list (object) , the object will show up in the common configuration group.
Pricing is 0 for the whole catalog if the Terraform template contains both 0 cost resource (sec-group) and non-zero cost resource (VM) and all configs contributing to the cost are not added as variables.
Join and concatenate are not supported together, so the catalog import will fail. For more information, see https://github.com/amplify-education/python-hcl2/issues/72. Example:
output "instances_ips" {
 value = join(",", concat(ibm_is_instance.instance_az1.*.primary_network_interface.0.primary_ipv4_address,ibm_is_instance.instance_az2.*.primary_network_interface.0.primary_ipv4_address))
}
For a single catalog, the
resource name
should be unique regardless of the
resource type
to which it is bound. This holds true even if there are multiple terraform configuration files that are part of the same catalog (in a single folder). For example, the following annotation is not allowed. However, there will not be any explicit validation errors, although duplicate configurations might be seen in the UI.
resource ibm_security_group test {}
resource ibm_compute_vm_instance test {}
If tag related attributes are specified in the resource as part of the Terraform configuration file, then they will be added in the resource on provider along with the
ibm_mcmp_soiid
. There is no mechanism for explicit resource tagging.
Terraform configuration files that contain attributes with special characters will not be servicified (such as
user_metadata = "{\"value\":\"newvalue\"}"
).
For multiple terraform configuration files in a single folder, only one of them should contain the
provider
block. Otherwise the import will fail.
For multiple terraform configuration files in a single folder, there is no explicit validation if the configuration files are for different providers. The import might fail/succeed depending on which provider block is processed first.
While using the
object
and
map
data types, servification converts these into free text.
Servicification through Terraform Engine supports the
type = any
in variable declaration. the variable with
type = any
declaration will be transformed into a text area on the UI.
For catalogs created from Terraform templates,
Edit Order
is not supported on the stack created on the
Ordered Services
page because it will not create any change management on the provider side.

Google Cloud Platform known issues

Tags are not supported for GCP. Use user-defined labels instead.
GCP Pricing is only supported for OOTB catalogs. For compute instance and compute disk resource types, some key attributes such as machineType, region, image, and preemptible should not be modified in the Terraform template.
Currently only the {project}/{family} format is supported for images.
For GPU pricing, duplicated keys are generated for type, so those values cannot be fetched.
For disks with the
local-ssd
parameter set multiple times, the count for
local-ssd
cannot be retrieved at the time of pricing.
For the Spanner service, location values are typically of the form
regional- (regional-europe-west1)
.
For MachineType, pricing is supported for only N1 series, f1-micro, and g1-small.
For the loadBalancer Service, pricing depends on the number of Forwarding rules being created, which cannot be fetched.
Pricing is only supported for a single resource.
Pricing cannot be calculated if a resource is part of a section.
Only out of the box (OOTB) resources are supported for pricing.
Compute Engine templates with tags fail at provisioning.

For more information

https://www.terraform.io/
https://learn.hashicorp.com/terraform
https://www.terraform.io/docs/configuration/index.html