Citizen

A Private Terraform Module and Terraform Provider registry.

Requirements

• Node.js 16+

• HTTPS - Terraform module registry only support HTTPS.

Download

Download the latest release!

Also, you can use to launch the registry server. The docker image is in GitHub Container Registry .

$ docker run -d -p "3000:3000" ghcr.io/outsideris/citizen:latest

Server Usage

citizen server

To launch the registry server

$ ./citizen server

It will be launched at http://localhost:3000. You can check it at http://localhost:3000/health.

Because Terraform CLI works with only HTTPS server, you should set up HTTPS in front of the registry server.

If you want to test it at local, you need a tool which provides HTTPS like ngrok.

Environment variables:

• CITIZEN_DATABASE: Backend provider for registry metadata. Set to mongodb to use MongoDB. Leaving unset will use local nedb file.

• CITIZEN_MONGO_DB_URI: MongoDB database URI if using MongoDB backend. URI format is mongodb://username:password@host:port/database?options…​. Default is mongodb://localhost:27017/citizen

• CITIZEN_DB_DIR: A directory to save database file if using local backend storage. The default is data directory in a current working directory (absolute/relative path can be used).

• CITIZEN_STORAGE : Storage type to store module files. You can use file or s3 type.

• CITIZEN_STORAGE_PATH: A directory to save module files only if CITIZEN_STORAGE is file (absolute/relative path can be used).

• CITIZEN_AWS_S3_BUCKET`: A S3 bucket to save module files only if CITIZEN_STORAGE is s3.(And AWS credentials required.)

The project supports dotenv-flow and will load a .env.test file with the configs.

New Relic has been added to the project. * NEW_RELIC_LICENSE_KEY: Required to publish APM to New RElic. Format is a '40HexadecimalCharacters' string. * NEW_RELIC_APP_NAME: Unique application name for your New Relic sub-account.

More details about dotenv-flow can be found at the project homepage.

Client Usage

citizen module <namespace> <name> <provider> <version>

Since official Terraform Module Registry is integrated with GitHub, users can publish terraform modules if they just push it on GitHub.

Citizen provides a special command to publish a module onto citizen registry server instead integrating GitHub.

In a module directory, you can publish your terraform module via a command below:

$ ./citizen module <namespace> <name> <provider> <version>

You should set CITIZEN_ADDR as citizen registry server address which you will publish your modules to. e.g. https://registry.example.com.

Examples

If you have ALB module in ./alb directory, and your registry server is launched at https://registry.example.com, you run below command in ./alb directory to publish ALB module.

$ CITIZEN_ADDR=https://registry.example.com \
  citizen module dev-team alb aws 0.1.0

Then, you can define it in your terraform file like this:

module "alb" {
  source = "registry.example.com/dev-team/alb/aws"
  version = "0.1.0"
}

citizen provider <namespace> <type> <version> <protocols>

Citizen provides a special command to publish providers onto citizen.

• -g, --gpg-key <gpgkey>: GPG key to sign your SHA256SUMS.

  • You need to publish your provider with your GPG public key to terraform registry. Otherwise, terraform will refuse to install providers. Terraform official resistry manage partners' public keys, but, each provider version has own public key and signature in citizen registry.

You must first build and package, citizen expects following files in the provider location:

• <namespace>-<type>_<version>_<os>_<arch>.zip (one per os/arch combination)

Where <namespace> and <type> is a name of the provider and <version> is a provider version in the MAJOR.MINOR.PATCH version format.

Citizen will generate a SHA256SUMS file and a GPG signature file automatically for you: Following files will be generated in your directory during publising provider. So, you don’t need to prepare these files.

• <namespace>-<type>_<version>_SHA256SUMS

• <namespace>-<type>_<version>_SHA256SUMS.sig

Therefore, shasum and gpg commands should be available in your machine.

In a provider directory, you can publish your terraform provider via a command below:

$ ./citizen provider <namespace> <type> <version> <protocols>

<protocols> is comma separated Terraform provider API versions, with MAJOR.MINOR. Although the spec says that protocols is an option value, the GET fails if it is not set, as on GET it is a required field. The list of current protobuf versions can be found here.

You should set CITIZEN_ADDR as citizen registry server address which you will publish your modules to. e.g. https://registry.example.com.

Examples

If you have ALB provider in ./utilities directory, and your registry server is launched at https://registry.example.com, you run below command in ./utilities directory to publish utilities provider.

$ CITIZEN_ADDR=https://registry.example.com \
  citizen provider dev-team utilities 0.1.0 5.2,6.1

Then, you can define it in your terraform file like this:

provider "utilities" {
}

terraform {
  required_providers {
    utilities = {
      source = "registry.example.com/dev-team/utilities"
      version = "0.1.0"
    }
  }
}

Development

Set environment variables, see above.

$ ./bin/citizen server
$ ./bin/citizen module

Test

Set at least a storage path and the s3 bucket name variables for the tests to succeed. You need to be able to access the bucket, so you probably want to have an active aws or aws-vault profile.

IF you do not want verbose DEBUG logs, create a .env.test.local file with the content of DEBUG=.

Run mongodb first like:

$ docker run --rm -p 27017:27017 --name mongo mongo

Run the tests:

$ npm test

Run the tests with the environment variables prefixed:

$ CITIZEN_STORAGE_PATH=storage CITIZEN_AWS_S3_BUCKET=terraform-registry-modules npm test

Build distributions

$ npm run build

Under dist/, citizen binaries for linux, darwin and windows made.

License