Chapter 6: In Action

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:

{
  "kind": "s3",
  "flavor": "aws_s3_bucket",
  "version": "1.0",
  "spec": {
    "acl": "private",
    "versioning": true
  }
}

Example test.tf:

provider "aws" {
  profile = "your-aws-profile"
  region  = "us-east-1"
}

module "example_module" {
  source = "../"

  instance      = jsondecode(file("${path.module}/test.json"))
  instance_name = "example-instance"
  environment = {
    name        = "development"
    unique_name = "dev_project"
  }
  inputs = {}
}

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.

Step 2: Registering the Module in Facets

Once local testing is complete, the module can be registered in preview mode in Facets.cloud for testing. The module will be registered only in projects marked as preview projects.

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 uploadModule API or an equivalent script.

   • 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.

Note: Registered Modules will be visible only in certain projects, allowing users to test the module in specific environments. Run the following script to view the registered modules in a particular project.

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)

Step 3: Publishing the Module

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

Publish the Module

• Use the markAsPublished API or an equivalent script.

  • 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 organisational 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

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:
     plaintext

     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:
     plaintext

     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.