feat: Added support for Deploy and Run use case (#44)

* feat: added logic to manage subscriptionID

* fix: added sensitive flag to subscriptionId parameter

* feat: added subscription_id support into DA input

* fix: fixed cra scan with subid crn

* fix: disabled nullable for subid crn in both tests SKIP UPGRADE TEST

* fix: fixed subscriptionIDs in tests

* feat: implemented DR use-case

* docs: fixed readme

* feat: added support for DR use-case and modified existing examples

* feat: readded trial plan only for tests

* feat: renamed Trial plan to programmatic name free for testing

* docs: some renaming and fixes on docs

* docs: added link to main doc

* docs: updated doc

Author: vbontempi

README.md

@@ -1,5 +1,5 @@
 <!-- Update this title with a descriptive name. Use sentence case. -->
-# Enterprise Application Service for Java (also know as EASeJava)
+# Enterprise Application Service for Java
 
 <!--
 Update status and "latest release" badges:
@@ -20,7 +20,9 @@ For information, see "Module names and descriptions" at
 https://terraform-ibm-modules.github.io/documentation/#/implementation-guidelines?id=module-names-and-descriptions
 -->
 
-Use this module to provision and configure an [Enterprise Application Service](https://cloud.ibm.com/catalog/services/enterprise-application-service) instance on IBM Cloud.
+Use this module to provision and configure an [Enterprise Application Service](https://cloud.ibm.com/catalog/services/enterprise-application-service) (also shorthened to EASeJava or simply to `ease`) instance on IBM Cloud.
+
+For more information about the Enterprice Application Service product you can refer to the [product documentation](https://www.ibm.com/docs/en/ease?topic=overview)
 
 
 <!-- The following content is automatically populated by the pre-commit hook -->
@@ -29,7 +31,8 @@ Use this module to provision and configure an [Enterprise Application Service](h
 * [terraform-ibm-enterprise-app-java](#terraform-ibm-enterprise-app-java)
 * [Examples](./examples)
     * [Basic example](./examples/basic)
-    * [Complete example](./examples/complete)
+    * [Build, deploy and run complete example](./examples/bdr_complete)
+    * [Deploy and run complete example](./examples/dr_complete)
 * [Contributing](#contributing)
 <!-- END OVERVIEW HOOK -->
 
@@ -42,24 +45,49 @@ https://terraform-ibm-modules.github.io/documentation/#/implementation-guideline
 -->
 <!-- ## Reference architectures -->
 
-## Prerequisites
+## Enterprise Application Service use cases support
+
+This module supports both the use cases provided by the Enterprise Application Service:
+- **Deploy and Run your application** use case: you can provide your existing prebuilt enterprise archive (EAR) or web archive (WAR) file in a Maven artifact repository, the service will allow to deploy and to run it.
+- **Build, deploy and run your application** use case: you can provide your application source code through its GitHub repository URL, the service will allow to build, deploy and then run it.
+
+For more details about the two different use-cases and the input parameters to use please refer to the sections below.
+
+### Mandatory input parameters for both the use cases
 
-This module has the following prerequisites as mandatory input parameters:
+Both the use-cases supported by this module need you to specify the following parameters as mandatory inputs.
 
 1. The IBM Cloud API Key (https://cloud.ibm.com/iam/apikeys) for the account where to deploy the Enterprise Application Service instance
 1. Resource Group ID (https://cloud.ibm.com/account/resource-groups) containing the Enterprise Application Service instance
 
-Optionally, the following optional input parameters are required in order to pre-configure the Enterprise Application Service instance:
+## Deploy and Run use case input parameters
+
+The following optional input parameters are required in order to pre-configure the Enterprise Application Service instance for the Deploy and Run use case:
+
+1. URL of the Maven artifact repository storing the existing prebuilt enterprise archive (EAR) or web archive (WAR) file to run in the Enterprise Application Service instance
+   1. If your Maven artifact repository needs basic authentication, you can specify the username and password using the related input variables. If the repository doesn't need authentication, you can leave them to their default values.
+2. URL of the GitHub repository storing the application deployment configuration to run in the Enterprise Application Service instance
+3. GitHub token with read access to the configuration repository.
+
+**Note:** all these parameters (excluding the Maven repository username and password) are mandatory in the case any of them is different than their default null value (the GitHub token is mandatory also if the configuration repository is public). When all of them are left to the default null value it will be possible to configure the instance with their values once the instance is successfully created, as describe [here](#create-an-enterprise-application-service-instance-without-setting-any-repository)
+
+The GitHub configuration repository must satisfy a further prerequisite as described [here](#ibm-appflow-github-application-prerequisite)
 
-1. URL of the repository storing the Java liberty application source code to build in the Enterprise Application Service instance
-1. URL of the repository storing the Java liberty application configuration to build in the Enterprise Application Service instance
-1. GitHub token with read access to the source code and to the configuration repositories.
+For more details about this use-case please refer to the Enterprise Application Service product documentation section available [here](https://www.ibm.com/docs/en/ease?topic=deploy-run-your-application-option)
 
-**Note:** all these parameters are mandatory in the case any of them is different than their default null value, with the GitHub token mandatory also if the source code and the configuration repositories are both public.
+### Build, Deploy and Run use case input parameters
 
-In the case the source code and the configuration repositories are not set at Enterprise Application Service instance deployment time, it will be possible to configure them through the Enterprise Application Service dashboard url that will be included in the `ease_instance` output details of this module.
+The following optional input parameters are required in order to pre-configure the Enterprise Application Service instance for the Build, deploy and run use case:
 
-In both the cases (pre-configure the Enterprise Application Service instance at deployment time or configure it through its dashboard when the instance deployment is complete), the repositories must satisfy a further prerequisite as described [here](#ibm-appflow-github-application-prerequisite)
+1. URL of the GitHub repository storing your application source code to Build, deploy and run in the Enterprise Application Service instance
+1. URL of the GitHub repository storing your application configuration to Build, deploy and run in the Enterprise Application Service instance
+1. GitHub token with read access the source code and configuration repositories.
+
+**Note:** all these parameters are mandatory in the case any of them is different than their default null value (the GitHub token is mandatory also if both the repositories are public). When all of them are left to the default null value it will be possible to configure the instance with their values once the instance is successfully created, as describe [here](#create-an-enterprise-application-service-instance-without-setting-any-repository)
+
+Both the repositories must satisfy a further prerequisite as described [here](#ibm-appflow-github-application-prerequisite)
+
+For more details about this use-case please refer to the Enterprise Application Service product documentation section available [here](https://www.ibm.com/docs/en/ease?topic=build-deploy-run-your-application-option)
 
 #### IBM AppFlow GitHub application prerequisite
 
@@ -69,8 +97,13 @@ To install and configure the **IBM AppFlow** GitHub application refer to https:/
 
 **Note:** in the case you need to configure an Enterprise Application Service instance in an environment different from IBM Cloud public platform, you need to install and configure a specific version of the **IBM AppFlow** GitHub application.
 
+### Create an Enterprise Application Service instance without setting any repository
+
+This module also supports to create an instance of the Enterprise Application Service without setting any source (GitHub or Maven) and configuration repository: in this case it will be possible to configure them through the Enterprise Application Service dashboard accessible through the dashboard URL returned in the `ease_instance` output details of this module.
+
 ### Java liberty sample application
-For an example of source code and configuration repositories to build in an Enterprise Application Service instance you can fork the repositories below:
+
+For an example of source code and configuration repositories to Build, deploy and run in an Enterprise Application Service instance you can fork the repositories below:
 
 - source code repository: https://github.com/IBMAppFlowTest/sample-getting-started
 
@@ -107,8 +140,6 @@ module "ease_module" {
 }
 ```
 
-
-
 ### Required IAM access policies
 
 <!-- PERMISSIONS REQUIRED TO RUN MODULE
@@ -157,13 +188,16 @@ No modules.
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| <a name="input_config_repo"></a> [config\_repo](#input\_config\_repo) | The URL for the repository storing the configuration to use for the application to deploy through IBM Cloud Enterprise Application Service. | `string` | `null` | no |
+| <a name="input_config_repo"></a> [config\_repo](#input\_config\_repo) | The URL for the repository storing the configuration to use for the application to run through Enterprise Application Service on IBM Cloud. | `string` | `null` | no |
 | <a name="input_ease_name"></a> [ease\_name](#input\_ease\_name) | The name for the newly provisioned Enterprise Application Service instance. | `string` | n/a | yes |
+| <a name="input_maven_repository_password"></a> [maven\_repository\_password](#input\_maven\_repository\_password) | Maven repository authentication password if needed. Default to null. | `string` | `null` | no |
+| <a name="input_maven_repository_username"></a> [maven\_repository\_username](#input\_maven\_repository\_username) | Maven repository authentication username if needed. Default to null. | `string` | `null` | no |
 | <a name="input_plan"></a> [plan](#input\_plan) | The desired pricing plan for Enterprise Application Service instance. | `string` | `"standard"` | no |
 | <a name="input_region"></a> [region](#input\_region) | The desired region for deploying Enterprise Application Service instance. | `string` | `"us-east"` | no |
-| <a name="input_repos_git_token"></a> [repos\_git\_token](#input\_repos\_git\_token) | The GitHub token to read from the application and configuration repos. It cannot be null if var.source\_repo and var.config\_repo are not null. | `string` | `null` | no |
+| <a name="input_repos_git_token"></a> [repos\_git\_token](#input\_repos\_git\_token) | The GitHub token to read from the application and configuration repositories. It cannot be null if var.source\_repo and var.config\_repo are not null. | `string` | `null` | no |
 | <a name="input_resource_group_id"></a> [resource\_group\_id](#input\_resource\_group\_id) | The ID of the resource group to use for the creation of the Enterprise Application Service instance. | `string` | n/a | yes |
-| <a name="input_source_repo"></a> [source\_repo](#input\_source\_repo) | The URL for the repository storing the source code of the application to deploy through IBM Cloud Enterprise Application Service. | `string` | `null` | no |
+| <a name="input_source_repo"></a> [source\_repo](#input\_source\_repo) | The URL for the repository storing the source code of the application or the URL of the Maven artifact repository storing the existing prebuilt archive (WAR or EAR) to deploy and run through Enterprise Application Service on IBM Cloud. | `string` | `null` | no |
+| <a name="input_source_repo_type"></a> [source\_repo\_type](#input\_source\_repo\_type) | Type of the source code repository. For maven source repository type, use value `maven`. Git for GitHub repository. Default value set to git. | `string` | `"git"` | no |
 | <a name="input_subscription_id"></a> [subscription\_id](#input\_subscription\_id) | ID of the subscription to use to create the Enterprise Application Service instance. | `string` | n/a | yes |
 | <a name="input_tags"></a> [tags](#input\_tags) | Metadata labels describing the service instance, i.e. test | `list(string)` | `[]` | no |
 

examples/bdr_complete/README.md

@@ -0,0 +1,9 @@
+# Build, deploy and run complete example
+
+A Build, deploy and run use-case example to show how to provision an Enterprise Application Service instance by passing application source and configuration repositories as input.
+In addiction to the two repositories, the example shows how to include the GitHub token with the right permissions to access the repositories: in the example the token is pulled from an IBM Cloud secrets manager instance where it is stored, by passing the secret CRN which is used to extract the Secrets Manager instance, its region and the secretID to pull the secret value
+Note that the three parameters (repositories and token) are mandatory if any of them is not null.
+
+The following resources are provisioned by this example:
+ - A new resource group, if an existing one is not passed in.
+ - A new Enterprise Application Service instance in the given resource group on an IBM Cloud account.

examples/complete/main.tf renamed to examples/bdr_complete/main.tf

@@ -17,7 +17,7 @@ variable "resource_tags" {
 variable "prefix" {
   type        = string
   description = "Prefix to append to all resources created by this example"
-  default     = "ease-complete"
+  default     = "bdr-complete"
 }
 
 variable "resource_group" {

examples/complete/outputs.tf renamed to examples/bdr_complete/outputs.tf

@@ -0,0 +1,12 @@
+# Deploy and run complete example
+
+A Deploy and run use-case example to show how to provision an Enterprise Application Service instance by passing an already built maven application through its maven repository URL as source repository and the application configuration through the config repository as input parameters.
+The example sets also the var.source_repo_type input variable to "maven" and the "username" and "password" values to a set of fake values for testing purposes
+In addiction to the configuration repository, the example shows how to
+- include the GitHub token with the right permissions to access it: in the example the token is pulled from an IBM Cloud secrets manager instance where it is stored, by passing the secret CRN which is used to extract the Secrets Manager instance, its region and the secretID to pull the secret value.
+- include the maven repository credentials (username and password)
+Note that the three parameters, maven and configuration repositories and the github token, are mandatory if any of them is not null.
+
+The following resources are provisioned by this example:
+ - A new resource group, if an existing one is not passed in.
+ - A new Enterprise Application Service instance in the given resource group on an IBM Cloud account.

examples/complete/provider.tf renamed to examples/bdr_complete/provider.tf

@@ -0,0 +1,96 @@
+locals {
+  sleep_create = "30s"
+}
+
+########################################################################################################################
+# Resource group management
+########################################################################################################################
+
+module "resource_group" {
+  source  = "terraform-ibm-modules/resource-group/ibm"
+  version = "1.1.6"
+  # if an existing resource group is not set (null) create a new one using prefix
+  resource_group_name          = var.resource_group == null ? "${var.prefix}-resource-group" : null
+  existing_resource_group_name = var.resource_group
+}
+
+########################################################################################################################
+# Reading the GitHub token from the existing Secrets Manager instance
+########################################################################################################################
+
+# parsing secret crn to collect the secrets manager ID, the region and the secret ID
+module "crn_parser_token" {
+  count   = var.repos_git_token_secret_crn != null ? 1 : 0
+  source  = "terraform-ibm-modules/common-utilities/ibm//modules/crn-parser"
+  version = "1.1.0"
+  crn     = var.repos_git_token_secret_crn
+}
+
+data "ibm_sm_arbitrary_secret" "sm_repo_github_token" {
+  count       = var.repos_git_token_secret_crn != null ? 1 : 0
+  instance_id = module.crn_parser_token[0].service_instance
+  #checkov:skip=CKV_SECRET_6: does not require high entropy string as is static type
+  region    = module.crn_parser_token[0].region
+  secret_id = module.crn_parser_token[0].resource
+  provider  = ibm.ibm-sm
+}
+
+locals {
+  repos_git_token = var.repos_git_token_secret_crn != null ? data.ibm_sm_arbitrary_secret.sm_repo_github_token[0].payload : null
+}
+
+########################################################################################################################
+# Reading the subscriptionID value from the existing Secrets Manager instance
+########################################################################################################################
+
+# parsing secret crn to collect the secrets manager ID, the region and the secret ID
+module "crn_parser_subid" {
+  source  = "terraform-ibm-modules/common-utilities/ibm//modules/crn-parser"
+  version = "1.1.0"
+  crn     = var.subscription_id_secret_crn
+}
+
+data "ibm_sm_arbitrary_secret" "sm_subscription_id" {
+  instance_id = module.crn_parser_subid.service_instance
+  #checkov:skip=CKV_SECRET_6: does not require high entropy string as is static type
+  region    = module.crn_parser_subid.region
+  secret_id = module.crn_parser_subid.resource
+  provider  = ibm.ibm-sm
+}
+
+########################################################################################################################
+# Enterprise Application Service Instance deployment
+########################################################################################################################
+
+module "ease" {
+  source            = "../../"
+  ease_name         = "${var.prefix}-app"
+  resource_group_id = module.resource_group.resource_group_id
+  tags              = var.resource_tags
+  plan              = var.plan
+  region            = var.region
+  config_repo       = var.config_repo
+  source_repo       = var.source_repo
+  repos_git_token   = local.repos_git_token
+  subscription_id   = data.ibm_sm_arbitrary_secret.sm_subscription_id.payload
+  # deploy and run use-case specific inputs
+  source_repo_type          = "maven"
+  maven_repository_username = var.maven_repository_username
+  maven_repository_password = var.maven_repository_password
+}
+
+locals {
+  # collecting the dashboard_url from the resource creation output as it is not returned when reading using the datasource
+  app_dashboard_url = module.ease.ease_instance.dashboard_url
+}
+
+# as the EASeJava app deployment expects some asynch tasks to be performed we wait for a configured interval before loading the resource instance details
+resource "time_sleep" "wait_deployment" {
+  depends_on      = [module.ease]
+  create_duration = local.sleep_create
+}
+
+data "ibm_resource_instance" "ease_resource" {
+  depends_on = [time_sleep.wait_deployment]
+  identifier = module.ease.ease_instance.id
+}