Private Module Registry

The module registry can be used to publish modules directly from VCS providers without having to provide or share VCS credentials with other users that need to consume the module. The Scalr module registry is not designed in an opinonated way, all repository structures are supported (module per repo, mono-repo, sub-modules, etc). When adding modules to Scalr, they can be used two different ways:

  • Library module - Boilerplate code with the internal source reference that can be used to call the module from any Terraform configuration in a Scalr environment.

  • Deployable module - The same as a library type module, but can be deployed through the Scalr UI by linking a workspace to the module source.

The module registry also provides version control for modules. Modules can only be registered if Git releases or tagged versions have been created in the repository. Module calls via the registry must use versions, thus new versions can be released without impacting existing deployments.

Here is an example module call from the registry:

module "instance" {
  source  = "my-account.scalr.io/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

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 called and the registration process automatically creates internal references to the module to be used in the Terraform configuration.

Publishing Modules

A module can be registered at the Scalr environment or account scope. Modules registered at the account scope can be used in any environment or workspace. To publish a module, navigate to “Modules”, click on “New Module”:

_images/new_module_reg.png

As seen above, if each repository contains a single module, just define the repository and publish. If the module is a sub-module in a mono repo, define the path to the root module in the advanced tab. The release tag can be on any branch. Follow the VCS system specific method to create a release or tagged version.

Module-Per-Repo

For modules in their own unique repository, the repository itself must be named using the format terraform-<provider_name>-<module_name>, e.g. terraform-aws-vcs_module. Here is an example from Github:

_images/git_mod_rel_1.png _images/git_mod_rel_2.png

Sub-Modules (Mono Repo)

For modules in a hybrid repo, the repository itself can have any name, but the sub-folders for each module must use the format terraform-<provider_name>-<module_name>, e.g. terraform-aws-instance. Here is an example from Github:

_images/git_mod_rel_3.png _images/git_mod_rel_4.png

Deployable Modules

A deployable module can be deployed through the Scalr UI by linking a workspace to the module source. By default, when a module is registered in the Scalr module registry it will be added to the list of deployable modules. In some cases, modules should only be library modules and users should not see a module in the dropdown of deployable modules. To prevent a module from appearing in the list of deployable modules, you must add a scalr-module.hcl file to the repo that contains the module. The scalr-module.hcl uses rules based on gitignore NEWWIN specifications to restrict which modules appear in the deployable module dropdown.

Deployable modules are also controlled through Git releases. If you update the scalr-module.hcl to include or exclude a module, then a new release must be published and only that module release will be included or excluded from the list of deployable modules. If you want former module versions to be excluded from the deployable module dropdown list, you must re-tag those versions from your VCS provider.

Here are some scalr-module.hcl examples:

Exclude all modules in the repository:

version="v2"
root-modules = ["!**"]

All modules in the modules/ directory are included, except for the system module:

version="v2"
root-modules = ["modules/**", "!modules/system"]

Any module at the root directory and only modules/foo and modules/bar in the sub directory are included:

version="v2"
root-modules = [".", "modules/foo", "modules/bar"]

See more syntax examples in the gitignore NEWWIN documentation.

Module Source Types

When a module is called from a Terraform configuration the source parameter specifies where Terraform should pull the module from. Terraform configuration files executed in Scalr can use 3 source types:

Source Type

Description

Example

Modules from Scalr

Versions or tagged release of modules in VCS repositories can be registered in Scalr and pulled using Scalr internal URLs (VCS and CLI)

source = "my-account.scalr.io/acc-sscctbisjkl35b8/scalr_dynamic_vpc_dns/aws"

Modules from Git

Module sources can be pulled from git repos using same authentication as the configuration (VCS only).

source = "github.com/user/repo"

Modules from Paths

Module is in a sub-directory of the repository (VCS) or local folder (CLI).

source = "./my_module" or source = "/home/user/my_module"

Modules from Scalr

This is an example of Terraform configuration file executed via the CLI calling a module via the Scalr module registry. Note the source and version parameters.

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

provider "aws" {
  region = var.region
}

module "instance" {
  source  = "my-account.scalr.io/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
}

Modules from Git

Note

This only works for VCS integration. It does not work for CLI runs

Terraform configuration files running in a Scalr VCS integrated workspaces can call modules directly via git HTTPs URLs. This option will work if the VCS Provider used by the workspace to pull the configuration will also allow access to the modules repository. When a workspace is integrated with VCS the access token is propagated to the workspace, thus making it possible to pull the module as well.

provider "aws" {
  region = var.region
}

module "instance" {
  source  = "github.com/scalr-eap/instance"
  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
}

Modules from Paths

If a module exists as a sub-directory in the Terraform configuration directory it can also be sourced using a relative or absolute path. This works for VCS integration and the CLI as the directory and all it’s sub-directories are always loaded into the Scalr workspace.

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

provider "aws" {
  region = var.region
}

module "instance" {
  source  = "./instance"
  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
}