Apply for invite to IaCP

Module Private Registry

Overview

Terraforms powerful module NEWWIN system enables simple re-use of common Terraform “building blocks” in multiple templates.

A module is basically a Terraform template that can be called from other templates in order to manage the state of the resources defined in the module. A module can contain all the same types of constructs such as resources, data and variables as other templates, and can in turn call other modules as well.

Modern organizations typically need to create and share a library of common modules that will deploy resources in line with standards and configuration requirements. Scalr makes it possible to share the this library of modules securely within an organization by providing a private module registry. The registry is a catalog of releases from git repositories that provides the ability to search and filter items and review the documentation relating to inputs, outputs and examples of module usage in templates.

Note

A git release is a tagged version of the code. Once created a release never changes as it is pinned to a specific commit. Tags must use semantic version numbering (m.m.p, e.g v1.0.4, 0.7.3) and can be created via the CLI (see git tag) or in the git VCS console via the “releases” page.

Modules in the registry are automatically pulled into workspaces where they are needed and the registration process automatically creates internal references to the module to be used in the template.

Module Repositories

Each module must be in it’s own repository and all the .tf files must be in the root directory. The release tag must be applied to the Master branch.

Warning

You cannot put multiple modules in the same repository or use sub-directories within the repository.

This is necessary because the key purpose of the registry is to provide version control and sharing of individual modules. Versioning is done by creating tagged releases of the repository. This approach is in-line with standard practice for managing modules and it provides the following benefits.

  • Enables version management of individual modules

  • Allows impact assessment for module changes

  • Enforces the convention for module naming that requires a 1:1 mapping between repositories and modules

Publishing Modules

A module registry can be created at the environment, account, or global (self hosted IaCP only) scope. If a module is added to an environment it can only be referenced by workspaces within that environment. If a module is created at the account scope, it can be used by all environments within that account. If a module is created at the global (self hosted IaCP only) scope, it can be used by all environments and accounts.

  1. Set up a connection to your VCS provider as described in VCS Integration.

  2. Ensure your module repository is correctly named

Note

Module repositories must be named using the format terraform-<provider_name>-<module_name>

  1. Create a tagged release of the module in the VCS console or by using git tag

Note

The release tag MUST be on the Master branch.

../../_images/git_mod_rel_1.png


../../_images/git_mod_rel_2.png
  1. At environment, account or global scope go to modules.

Environment:

../../_images/modules_menu.png

Account:

../../_images/modules_menu_account.png

Global (self hosted IaCP only):

../../_images/modules_menu_global.png
  1. Click on New Module and select the VCS provider and module to be added.

    ../../_images/module_pub_1.png
  2. The resulting screen will show the boiler plate code with the internal source reference that can be used to call the module from any template in this environment or all environments if the module was created at the account scope.

    ../../_images/module_pub_2.png

Example

Below is an example of a module and the module call from the private registry.

Module

  • Does not require a provider block as this can be inherited from the calling templates

  • Variables become input parameters to the module call below. Variables with defaults must be specified in the module call.

resource "aws_instance" "scalr" {
  ami                    = var.ami
  instance_type          = var.instance_type
  subnet_id              = var.subnet
  vpc_security_group_ids = var.sg
  key_name               = var.key
  count                  = var.instance_count
}

variable "region" {
  description = "Region"
}

variable "instance_type" {
  description = "Instance Type"
}

variable "instance_count" {
  description = "Number of instances to deploy"
  default = "1"
}

variable "subnet" {
  description = "Subnet ID"
}

variable "sg" {
  description = "AWS Secruity Group"
  type        = list(string)
}

variable "key" {
  description = "AWS Key"
}

variable "vpc_id" {
  description = "VPC"
}

variable "ami" {
  description = "AMI"
}

Template with module call

  • Source format is host / organization / module-name / provider.

  • Organization is the same as specified in the terraform block. This maps to the environment in Scalr.

  • Version and input variables from the module definition must be included.

terraform {
  backend "remote" {
  hostname = "my.scalr.com"
    organization = "org-sfgari365m7sck0"
    workspaces {
      name = "module-test"
    }
  }
}

provider "aws" {
  region = var.region
}

module "instance" {
  source  = "my.scalr.com/org-sfgari365m7sck0/instance/aws"
  version = "1.0.1"
  instance_type = var.instance_type
  instance_count = var.instance_count
  subnet = var.subnet
  sg = var.security_group
  key = var.ssh_key
  vpc_id = var.vpc_id
  ami = var.ami
}

Note

Modules in the registry can be called from any workspace in Scalr that the user has access to. Your workspace does not have to be in the same environment that the module is registered in.