Using the terraform registry APIs to return examples and submodules

[vburckhardt]

Originally posted by @vburckhardt in #16 (comment)

--

Merging, but I think this should be using the terraform registry APIs like in original version and return json to minimize effort. the registry already return examples and submodule correctly

tim-mcp/models/terraform_module.py

Line 54 in 48a32e5

self.examples = module_data.get("examples", [])

only gap we may have is on the solutions, but I think we should move them under modules so that they actually also show in the registry ui.

[daniel-butler-irl]

Capturing both responses for comparison.

Content of the registry api response:

# registry://modules/terraform-ibm-modules/landing-zone-vsi

**Description:** Creates Virtual Server Instances (VSI) across multiple subnets with any number of block storage volumes that are connected by any number of load balancers

**Module Version:** 5.8.1

**Namespace:** terraform-ibm-modules

**Source:** https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone-vsi

### Inputs

| Name | Type | Description | Default | Required |
|---|---|---|---|---|
| monitoring_tags | list(string) | A list of tags in the form of `TAG_NAME:TAG_VALUE` to associate with the monitoring agent. | `[]` | false |
| tags | list(string) | List of tags to apply to resources created by this module. | `[]` | false |
| ssh_key_ids | list(string) | ssh key ids to use in creating vsi | `` | true |
| security_group_ids | list(string) | IDs of additional security groups to be added to VSI deployment primary interface. A VSI interface can have a maximum of 5 security groups. | `[]` | false |
| skip_iam_authorization_policy | bool | Set to true to skip the creation of an IAM authorization policy that permits all Storage Blocks to read the encryption key from the KMS instance. If set to false, pass in a value for the boot volume encryption key in the `boot_volume_encryption_key` variable. In addition, no policy is created if var.kms_encryption_enabled is set to false. | `false` | false |
| secondary_security_groups | list(
    object({
      security_group_id = string
      interface_name    = string
    })
  ) | The security group IDs to add to the VSI deployment secondary interfaces (5 maximum). Use the same value for interface_name as for name in secondary_subnets to avoid applying the default VPC security group on the secondary network interface. | `[]` | false |
| logging_target_host | string | Ingestion endpoint that corresponds to the IBM Cloud Logs instance the logging agent connects to. | `null` | false |
| vsi_per_subnet | number | Number of VSI instances for each subnet | `` | true |
| boot_volume_size | number | The capacity of the volume in gigabytes. This defaults to minimum capacity of the image and maximum to 250 GB | `null` | false |
| manage_reserved_ips | bool | Set to `true` if you want this terraform module to manage the reserved IP addresses that are assigned to VSI instances. If this option is enabled, when any VSI is recreated it should retain its original IP. | `false` | false |
| secondary_use_vsi_security_group | bool | Use the security group created by this module in the secondary interface | `false` | false |
| primary_vni_additional_ip_count | number | The number of secondary reversed IPs to attach to a Virtual Network Interface (VNI). Additional IPs are created only if `manage_reserved_ips` is set to true. | `0` | false |
| enable_floating_ip | bool | Create a floating IP for each virtual server created | `false` | false |
| kms_encryption_enabled | bool | Set this to true to control the encryption keys used to encrypt the data that for the block storage volumes for VPC. If set to false, the data is encrypted by using randomly generated keys. For more info on encrypting block storage volumes, see https://cloud.ibm.com/docs/vpc?topic=vpc-creating-instances-byok | `false` | false |
| custom_vsi_volume_names | map(map(list(string))) | A map of subnets, VSI names, and storage volume names. Subnet names should correspond to existing subnets, while VSI and storage volume names are used for resource creation. Example format: { 'subnet_name_1': { 'vsi_name_1': [ 'storage_volume_name_1', 'storage_volume_name_2' ] } }. If the 'custom_vsi_volume_names' input variable is not set, VSI and volume names are automatically determined using a prefix, the first 4 digits of the subnet_id, and number padding. In addition, for volume names, the name from the 'block_storage_volumes' input variable is also used. | `{}` | false |
| use_legacy_network_interface | bool | Set this to true to use legacy network interface for the created instances. | `false` | false |
| install_monitoring_agent | bool | Set to true to enable installing the monitoring agent into your VSI at time of creation. | `false` | false |
| resource_group_id | string | ID of resource group to create VSI and block storage volumes. If you wish to create the block storage volumes in a different resource group, you can optionally set that directly in the 'block_storage_volumes' variable. | `` | true |
| subnets | list(
    object({
      name = string
      id   = string
      zone = string
      cidr = optional(string)
    })
  ) | A list of subnet IDs where VSI will be deployed | `` | true |
| create_security_group | bool | Create security group for VSI. If this is passed as false, the default will be used | `` | true |
| install_logging_agent | bool | Set to true to enable installing the logging agent into your VSI at time of creation. | `false` | false |
| logging_auth_mode | string | Authentication mode the logging agent to use to authenticate with IBM Cloud, must be either `IAMAPIKey` or `VSITrustedProfile`. | `"IAMAPIKey"` | false |
| logging_trusted_profile_id | string | Trusted Profile used by the logging agent to access the IBM Cloud Logs instance, must be provided if `logging_auth_mode` is set to `VSITrustedProfile`. | `null` | false |
| monitoring_collector_port | string | Port the monitoring agent targets when sending metrics, defaults to `6443`. | `"6443"` | false |
| prefix | string | The prefix to add to all resources created by this module. | `` | true |
| image_id | string | Image ID used for VSI. Run 'ibmcloud is images' to find available images in a region | `` | true |
| boot_volume_encryption_key | string | CRN of boot volume encryption key | `null` | false |
| load_balancers | list(
    object({
      name                       = string
      type                       = string
      listener_port              = optional(number)
      listener_port_max          = optional(number)
      listener_port_min          = optional(number)
      listener_protocol          = string
      connection_limit           = optional(number)
      idle_connection_timeout    = optional(number)
      algorithm                  = string
      protocol                   = string
      health_delay               = number
      health_retries             = number
      health_timeout             = number
      health_type                = string
      pool_member_port           = string
      profile                    = optional(string)
      accept_proxy_protocol      = optional(bool)
      subnet_id_to_provision_nlb = optional(string) # Required for Network Load Balancer. If no value is provided, the first one from the VPC subnet list will be selected.
      dns = optional(
        object({
          instance_crn = string
          zone_id      = string
        })
      )
      security_group = optional(
        object({
          name = string
          rules = list(
            object({
              name      = string
              direction = string
              source    = string
              tcp = optional(
                object({
                  port_max = number
                  port_min = number
                })
              )
              udp = optional(
                object({
                  port_max = number
                  port_min = number
                })
              )
              icmp = optional(
                object({
                  type = number
                  code = number
                })
              )
            })
          )
        })
      )
    })
  ) | Load balancers to add to VSI | `[]` | false |
| secondary_floating_ips | list(string) | List of secondary interfaces to add floating ips | `[]` | false |
| secondary_allow_ip_spoofing | bool | Allow IP spoofing on additional network interfaces | `false` | false |
| access_tags | list(string) | A list of access tags to apply to the VSI resources created by the module. For more information, see https://cloud.ibm.com/docs/account?topic=account-access-tags-tutorial. | `[]` | false |
| allow_ip_spoofing | bool | Allow IP spoofing on the primary network interface | `false` | false |
| placement_group_id | string | Unique Identifier of the Placement Group for restricting the placement of the instance, default behaviour is placement on any host | `null` | false |
| security_group | object({
    name = string
    rules = list(
      object({
        name      = string
        direction = string
        source    = string
        tcp = optional(
          object({
            port_max = number
            port_min = number
          })
        )
        udp = optional(
          object({
            port_max = number
            port_min = number
          })
        )
        icmp = optional(
          object({
            type = number
            code = number
          })
        )
      })
    )
  }) | Security group created for VSI | `null` | false |
| boot_volume_snapshot_id | string | The snapshot id of the volume to be used for creating boot volume attachment (if specified, the `image_id` parameter will not be used) | `null` | false |
| snapshot_consistency_group_id | string | The snapshot consistency group Id. If supplied, the group will be queried for snapshots that are matched with both boot volume and attached (attached are matched based on name suffix). You can override specific snapshot Ids by setting the appropriate input variables as well. | `null` | false |
| monitoring_collector_endpoint | string | Endpoint the monitoring agent sends metrics to, required when `install_agents` is true. For more information on collector endpoints, see https://cloud.ibm.com/docs/monitoring?topic=monitoring-endpoints#endpoints_ingestion. | `null` | false |
| user_data | string | User data to initialize VSI deployment | `` | true |
| use_boot_volume_key_as_default | bool | Set to true to use the key specified in the `boot_volume_encryption_key` input as default for all volumes, overriding any key value that may be specified in the `encryption_key` option of the `block_storage_volumes` input variable. If set to `false`,  the value passed for the `encryption_key` option of the `block_storage_volumes` will be used instead. | `false` | false |
| use_static_boot_volume_name | bool | Sets the boot volume name for each VSI to a static name in the format `{hostname}_boot`, instead of a random name. Set this to `true` to have a consistent boot volume name even when VSIs are recreated. | `false` | false |
| secondary_subnets | list(
    object({
      name = string
      id   = string
      zone = string
      cidr = optional(string)
    })
  ) | List of secondary network interfaces to add to vsi secondary subnets must be in the same zone as VSI. This is only recommended for use with a deployment of 1 VSI. | `[]` | false |
| enable_dedicated_host | bool | Enabling this option will activate dedicated hosts for the VSIs. When enabled, the dedicated_host_id input is required. The default value is set to false. Refer [Understanding Dedicated Hosts](https://cloud.ibm.com/docs/vpc?topic=vpc-creating-dedicated-hosts-instances&interface=ui#about-dedicated-hosts) for more details | `false` | false |
| logging_target_port | string | Port the logging agent targets when sending logs, defaults to `443` for sending logs to an IBM Cloud Logs instance. | `"443"` | false |
| logging_target_path | string | Path the logging agent targets when sending logs, defaults to `/logs/v1/singles` for sending logs to an IBM Cloud Logs instance. | `"/logs/v1/singles"` | false |
| monitoring_access_key | string | Access key used by the monitoring agent to authenticate, required when `install_agents` is true. For more information on access keys, see https://cloud.ibm.com/docs/monitoring?topic=monitoring-access_key. | `null` | false |
| vpc_id | string | ID of VPC | `` | true |
| machine_type | string | VSI machine type. Run 'ibmcloud is instance-profiles' to get a list of regional profiles | `` | true |
| block_storage_volumes | list(
    object({
      name              = string
      profile           = string
      capacity          = optional(number)
      iops              = optional(number)
      encryption_key    = optional(string)
      resource_group_id = optional(string)
      snapshot_id       = optional(string) # set if you would like to base volume on a snapshot
      tags              = optional(list(string), [])
    })
  ) | List describing the block storage volumes that will be attached to each vsi | `[]` | false |
| dedicated_host_id | string | ID of the dedicated host for hosting the VSI's. The enable_dedicated_host input should be set to true if passing a dedicated host ID | `null` | false |
| logging_api_key | string | API key used by the logging agent to authenticate with IBM Cloud, must be provided if `logging_auth_mode` is set to `IAMAPIKey`. For more information on creating an API key for the logging agent, see https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-iam-ingestion-serviceid-api-key. | `null` | false |
| logging_use_private_endpoint | bool | Set to true to use the private endpoint when sending logs to the IBM Cloud Logs instance. | `true` | false |

### Outputs

| Name | Description |
|---|---|
| ids | The IDs of the VSI |
| vsi_security_group | Security group for the VSI |
| list | A list of VSI with name, id, zone, and primary ipv4 address |
| fip_list | A list of VSI with name, id, zone, and primary ipv4 address, and floating IP. This list only contains instances with a floating IP attached. |
| load_balancers_metadata | Load Balancers metadata. |
| lb_security_groups | Load Balancer security groups |
| consistency_group_boot_snapshot_id | The Snapshot Id used for the VSI boot volume, determined from an optionally supplied consistency group |
| consistency_group_storage_snapshot_ids | Map of attached storage volumes requested, and the Snapshot Ids that will be used, determined from an optionally supplied consistency group, and mapped  |

### Provider Dependencies

| Name | Namespace | Source | Version |
|---|---|---|---|
| ibm | IBM-Cloud | IBM-Cloud/ibm | >= 1.78.4, < 2.0.0 |
| time | hashicorp | hashicorp/time | >= 0.9.1, < 1.0.0 |

### Examples

#### basic

**Readme:**

# End to end basic example

An end-to-end basic example that will provision the following:

- A new resource group if one is not passed in.
- A new public SSH key if one is not passed in.
- A new VPC with 3 subnets
- A new placement group
- A VSI in each subnet


#### complete

**Readme:**

# Complete Example using a placement group, attaching a load balancer, creating secondary interface, and adding additional data volumes

It will provision the following:

- A new resource group if one is not passed in.
- A new public SSH key if one is not passed in.
- A new VPC with 3 subnets.
- A new placement group for 3 VSI's
- A VSI in each subnet placed in the placement group.
- A floating IP for each virtual server created.
- A secondary VSI with secondary subnets and secondary security group.
- **(Optional) A dedicated host and a dedicated host group.** - Disabled by default.
- **(Optional) A VSI will be created on the dedicated host if enabled.**
- A new Application Load Balancer and Network Load Balancer to balance traffic between all virtual servers that are created by this example.


> Note: The Dedicated Host module is disabled by default . If you need to deploy a dedicated host, you must explicitly enable it by setting `enable_dedicated_host = true`


#### fscloud

**Readme:**

# Financial Services Cloud profile example

An end-to-end example that uses the [Profile for IBM Cloud Framework for Financial Services](https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone-vsi/tree/main/modules/fscloud) to deploy a VSI.

The example uses the IBM Cloud Terraform provider to create the following infrastructure:
* A resource group, if one is not passed in.
* An SSH Key, if one is not passed in.
* A Secure Landing Zone virtual private cloud (VPC).
* An IBM Cloud VSI instance with Hyper Protect Crypto Services root key that is passed in for encrypting block storage.
* Additional data volumes on each VSI

:exclamation: **Important:** In this example, only the VSI instance complies with the IBM Cloud Framework for Financial Services. Other parts of the infrastructure do not necessarily comply.

## Before you begin

- You need a Hyper Protect Crypto Services instance and root key available in the region that you want to deploy your VSI instance to.


#### snapshot

**Readme:**

# Basic example using a Snapshot Consistency Group for volumes

An end-to-end basic example that will provision the following, using previously created snapshots for storage volumes:

- A new resource group if one is not passed in.
- A new public SSH key if one is not passed in.
- A new VPC with 3 subnets
- A VSI in each subnet
- Two additional block storage attached to each VSI
- Reserved and Floating IPs managed by Terraform for each VSI
- Boot volume and additional storage volumes will be based on snapshots from consistency group, if ID is supplied


#### multi-profile-one-vpc

**Readme:**

# Example demonstrating the deployment of different sets of VSIs (with different machine types) to the same VPC and subnets, empoying two calls to the module.

It will provision the following:

- A new resource group if one is not passed in.
- A new public SSH key if one is not passed in.
- A new VPC with 3 subnets.
- Two sets of virtual servers, one set with `cx` machine type, one set with `bx`, deployed to the same VPC and subnets
- Each of the virtual server sets will deploy the following:
    - A VSI in each subnet.
    - A managed reserved IP for each virtual server created.
    - A floating IP for each virtual server created.
    - A secondary VSI with secondary subnets and secondary security group.
    - A new Application Load Balancer and Network Load Balancer to balance traffic between all virtual servers that are created by this example.

Current response for the same repo:

# terraform-ibm-modules/landing-zone-vsi/ibm - Available Content

**Version:** v5.8.1

## Root Module
**Path:** `` (empty string)
**Description:** This module creates Virtual Server Instances (VSI) across multiple subnets with any number of block storage volumes that are connected by any number of load balancers. Overview Overview terraform-ibm-landing-zone-vsi Submodules fscloud Examples Basic example using a Snapshot Consistency Group for volumes Complete Example using a placement group, attaching a load balancer, creating secondary interface, and adding additional data volumes End to end basic example Example demonstrating the deployment of different sets of VSIs (with different machine types) to the same VPC and subnets, empoying two calls to the module. Financial Services Cloud profile example Contributing.

## Examples
**Path:** `examples/basic`
**Description:** An end-to-end basic example that will provision the following: • A new resource group if one is not passed in. • A new public SSH key if one is not passed in. • A new VPC with 3 subnets • A new placement group • A VSI in each subnet.

**Path:** `examples/complete`
**Description:** It will provision the following: • A new resource group if one is not passed in. • A new public SSH key if one is not passed in. • A new VPC with 3 subnets. • A new placement group for 3 VSI's • A VSI in each subnet placed in the placement group. • A floating IP for each virtual server created. • A secondary VSI with secondary subnets and secondary security group. • (Optional) A dedicated host and a dedicated host group. • Disabled by default. • (Optional) A VSI will be created on the dedicated host if . • A new Application Load Balancer and Network Load Balancer to balance traffic between all virtual servers that are created by this example. Note: The Dedicated Host module is disabled by default . If you need to deploy a dedicated host, you must explicitly enable it by setting enable_dedicated_host = true.

**Path:** `examples/fscloud`
**Description:** An end-to-end example that uses the Profile for IBM Cloud Framework for Financial Services to deploy a VSI. The example uses the IBM Cloud Terraform provider to create the following infrastructure: A resource group, if one is not passed in. An SSH Key, if one is not passed in. A Secure Landing Zone virtual private cloud (VPC). An IBM Cloud VSI instance with Hyper Protect Crypto Services root key that is passed in for encrypting block storage. • Additional data volumes on each VSI :exclamation: Important: In this example, only the VSI instance complies with the IBM Cloud Framework for Financial Services. Other parts of the infrastructure do not necessarily comply.

**Path:** `examples/multi-profile-one-vpc`
**Description:** It will provision the following: • A new resource group if one is not passed in. • A new public SSH key if one is not passed in. • A new VPC with 3 subnets. • Two sets of virtual servers, one set with cx machine type, one set with bx, deployed to the same VPC and subnets • Each of the virtual server sets will deploy the following: • A VSI in each subnet. • A managed reserved IP for each virtual server created. • A floating IP for each virtual server created. • A secondary VSI with secondary subnets and secondary security group. • A new Application Load Balancer and Network Load Balancer to balance traffic between all virtual servers that are created by this example.

**Path:** `examples/snapshot`
**Description:** An end-to-end basic example that will provision the following, using previously created snapshots for storage volumes: • A new resource group if one is not passed in. • A new public SSH key if one is not passed in. • A new VPC with 3 subnets • A VSI in each subnet • Two additional block storage attached to each VSI • Reserved and Floating IPs managed by Terraform for each VSI • Boot volume and additional storage volumes will be based on snapshots from consistency group, if ID is supplied.

## Submodules
**Path:** `modules/fscloud`
**Description:** This code is a version of the parent root module that includes a default configuration that complies with the relevant controls from the IBM Cloud Framework for Financial Services. See the Example for IBM Cloud Framework for Financial Services for logic that uses this module. The default values in this profile were scanned by IBM Code Risk Analyzer (CRA) for compliance with the IBM Cloud Framework for Financial Services profile that is specified by the IBM Security and Compliance Center. The scan passed for all applicable goals.

## Solutions
**Path:** `solutions/fully-configurable`
**Description:** Standard - Integrated setup with configurable services. This architecture supports deployment of a <b>Virtual Server Instance</b> within an IBM Cloud <b>Virtual Private Cloud (VPC)</b> environment.<br><br>The VPC is hosted within a designated resource group in a specific region. You can either provision a new VPC or use an existing one, depending on your workload requirements. The VPC includes a subnet for network segmentation and connectivity of compute resources.<br><br>At the core of this setup is the <b>Virtual Server Instance on VPC</b>, which can be optionally associated with block volumes for additional data storage. These block volumes can be encrypted using key management services (KMS), where a boot-volume key is managed under a defined key ring.<br><br>To enhance secure access and centralized credential management, <b>Secrets Manager</b> can be integrated. This enables storage and retrieval of sensitive information such as ssh private keys, helping ensure secure and auditable server access.<br><br>For external connectivity, the architecture supports optional assignment of a floating ip to the virtual server, allowing public network access as needed.<br><br>A security group is defined to control inbound and outbound traffic to the virtual server. It includes a load balancer setup, consisting of a <b>Load Balancer Listener</b>, <b>Load Balancer</b>, and <b>Load Balancer Pool</b> to distribute traffic efficiently across backend resources.<br><br>Observability capabilities can be optionally enabled to monitor and manage the health and performance of deployed resources. This includes <b>Cloud Monitoring</b> for metrics and <b>Cloud Logs</b> for log aggregation and analysis.<br><br>This architecture provides a scalable, secure, and flexible foundation for deploying applications on IBM Cloud, integrating optional services such as encryption, observability, and secure key management for enterprise-grade workloads.

**Path:** `solutions/quickstart`
**Description:** Quickstart - Basic and simple. This architecture supports deployment of a <b>Virtual Server Instance</b> within an IBM Cloud <b>Virtual Private Cloud (VPC)</b> environment.<br><br>The VPC is hosted within a resource group in a specific region. It includes a single-zone deployment with one subnet for network segmentation and connectivity of compute resources. A security group is also added to allow SSH access to Virtual Server Instance.<br><br>Users can select from predefined Virtual Server Instance sizes — <b>mini (default), small, medium, and large.</b> The chosen size determines the <b>machine type</b> of the Virtual Server Instance, <b>the number of virtual CPU</b>, <b>RAM capacity</b>, <b>Bandwidth</b> and <b>Instance Storage</b>. To get more information on this, refer [here](https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone-vsi/blob/main/solutions/quickstart/DA_docs.md).<br><br>For external connectivity, the architecture supports optional assignment of a floating IP to the virtual server, allowing public network access as needed.

[daniel-butler-irl]

Initial implementation needs more testing https://github.com/terraform-ibm-modules/tim-mcp/tree/use_registry_api