Guides

Chapter 5: In Action

Suggest Edits

Once a Facets module is developed, it must be tested and registered in the Facets.cloud platform to ensure functionality, adherence to standards, and availability across projects.

Directory Structure of a Module

Here is an example directory structure for a custom module:

custom_s3_module/
├── facets.yaml
├── main.tf
├── variables.tf
├── outputs.tf
└── test/
    ├── test.json
    ├── test.tf

Step 1: Local Testing

Local testing validates the Terraform logic and configurations before registering the module in Facets.

Set Up a Testing Environment

  • Create a test directory within the module folder.
  • Include the following files:
    • test.json: A sample JSON file representing the declarative input for the module.
    • test.tf: A Terraform configuration file to invoke the module.

Example test.json:

{
  "bucket_name": "example-bucket",
  "acl": "private",
  "environment": "prod"
}

Example test.tf:

module "test_s3" {
  source      = "../"
  bucket_name = jsondecode(file("test.json")).bucket_name
  acl         = jsondecode(file("test.json")).acl
  environment = jsondecode(file("test.json")).environment
}

output "test_bucket_arn" {
  value = module.test_s3.bucket_arn
}

Run Terraform Commands

  1. Navigate to the test directory.
  2. Run the following commands:
    • terraform init: Initializes the Terraform environment.
    • terraform plan: Previews the changes to be applied.
    • terraform apply: Applies the configuration to validate the module.
  3. Verify the outputs (e.g., test_bucket_arn) to ensure the module behaves as expected.

🚧

Registering Modules

If you have a use case to test and register custom module developed by you before the time below features are live, get in touch with the facets team and they will assist you in doing this using our APIs.

Step 2: Registering the Module in Facets [Coming Soon]

Once local testing is complete, the module can be registered in Facets.cloud.

Prepare for Registration

  1. Ensure the following files are correctly configured:
    1. facets.yaml: Includes accurate metadata for the module.
    2. Terraform files (main.tf, variables.tf, outputs.tf): Match the schema defined in facets.yaml.
  2. Pre-requisites
    1. Control Plane URL: URL of the Facets Control plane.
    2. Username: The username is your registered email ID with which you access the Facets Control Plane.
    3. Token: Generate an authentication token using the steps mentioned [here](The username is your registered email ID with which you access the Facets Control Plane.).

Registering the Module

Facets provides APIs or scripts to register modules.

  1. Use the registerModule API or an equivalent script.

    • Set the required parameters, such as module path, intent, and flavor.
    • Example:
      • cd into the directory where the module (with the facets.yaml file) is present
      • curl -s https://facets-cloud.github.io/facets-schemas/scripts/module_register.sh | bash -s -- -c <control plane url> -u <username> -t <token>
      • Requirements:
        • Bash (Unix-based shell)
        • curl utility
        • zip utility

  2. Verify the registration in the Facets UI:

    • Navigate to the project where the module was registered.
    • Check the "Blueprint" tab to ensure the module appears in the resource list.

Preview Mode

  • Modules can be registered in preview mode for testing within specific projects before full-scale deployment. Only projects with "previewModulesAllowed" set as true will show all the modules in preview mode along with the published modules.
  • Run the following command to set previewModulesAllowed = true 
    curl -s https://facets-cloud.github.io/facets-schemas/scripts/allow_preview_modules.sh | bash -s -- -c <control plane url> -u <username> -t <token> -p <project-name> -a true
    • Requirements:
      • Bash (Unix-based shell)
      • curl utility
      • jq utility (for parsing JSON responses)
  • Preview registration lets Ops teams validate module behaviour in a controlled environment.

Step 3: Publishing the Module [Coming Soon]

After testing and preview registration, the module can be published for use across all projects.

Publish the Module

  • Use the publishModule API or an equivalent script.
    • Example:
    • curl -s https://facets-cloud.github.io/facets-schemas/scripts/module_publish.sh | bash -s -- -c <control plane url> -u <username> -t <token> -i <module_intent> -f <module_flavor> -v <module_version>
    • Requirements:
      • Bash (Unix-based shell)
      • curl utility
      • jq utility (for parsing JSON responses)
  • This makes the module available in the Control Plane for all projects.

Governance and Readiness Checks

Before publishing, check:

  • All inputs and outputs conform to organizational standards.
  • The module has been reviewed and approved by relevant stakeholders.
  • Metadata in facets.yaml is accurate and complete.

Step 4: Validation in Facets.cloud [Coming Soon]

After publishing, validate the module by creating a resource in a test project.

Steps to Validate

  1. Navigate to the "Blueprint" tab in the Facets UI.
  2. Add the newly published resource to the project.
  3. Deploy the blueprint and monitor the logs to ensure successful execution.

Console Testing

Once the module is registered and the resource is created and enabled:

  1. Perform a release for the resource.
  2. Open the Terraform logs and expand the PRE-BUILD section.
  3. Look for the following indicators:
    • "Module Matched": Confirms that the resource matches a registered module. Example: 
      Module Matched
- Module: ../modules/1_input_instance/grafana_dashboard
- Flavor: DEFAULT
- Version: latest
- Module Name: grafana_dashboard_vm-metrics
    • "No per instance module matched": Indicates that no module matches the kind, flavor, or version of the resource. Example: 
      No per instance module matched for ../stacks/infra-dev/aurora/disaster-recovery.json
- Kind: infra-dev
- Flavor: NONE
- Version: 0.1

This verifies that the custom resource is correctly associated with the registered module.

Troubleshooting

  • Check Terraform logs for errors during deployment.
  • Ensure the module inputs match the schema defined in facets.yaml.
  • Validate outputs to ensure consistency with the declared outputs in outputs.tf.

By following these steps, Ops teams can confidently test, register, and publish custom Terraform modules in Facets.cloud, ensuring reliable and standardized infrastructure management.

Updated about 3 hours ago