IaCConsole CLI — Configuration Management for OpenTofu and Terraform

IaCConsole CLI is a configuration management tool that dynamically orchestrates OpenTofu or Terraform deployments. It separates infrastructure configuration from code, enabling DevOps teams to reuse Terraform modules across multiple environments (dev, staging, production) without code duplication. Configuration can be sourced from files or the IaCConsole API (CMDB), an OpenAPI-powered configuration database.

Table of Contents

• Key Features

• Use Cases

• Quick Start

• Installation

• Usage

• Configuration

• License

• Environment configuration stored outside the Terraform/OpenTofu code

• Terraform/OpenTofu code, called "unit", should be generic enough to handle provided configuration to deploy the same resources with different configurations

• tfvars and variables are automatically generated in the temporary folder with selected terraform code ("unit") resulting in a full set of the Terraform code and configuration variables

• After the temporary folder is ready, it executes terraform or tofu with specified parameters

• Maintains separate state files for each environment, automatically providing configuration for remote state management (different path on storage based on configured dimensions). So the deployed configuration is stored in different tfstate files in remote storage (S3, GCS)

Use Cases

• Infrastructure as Code management across multiple environments
• CI/CD pipeline integration for automated deployments
• Configuration management for development, staging, and production
• Terraform/OpenTofu workflow automation
• Multi-cloud infrastructure orchestration

Quick start with Jenkins and demo configuration

You will need any Kubernetes cluster (best small temporary like Podman+Kind or MiniKube). Check that kubectl context poiting to this test cluster! Not Production!

For a full end-to-end example of using IaCConsole CLI in a CI/CD pipeline, see the pre-configured Jenkins deployment in examples/jenkins/README.md.

Installation

Download Pre-built Binaries

1. Download the latest release from GitHub Releases (version >= 0.5.0)
2. Extract the binary for your platform (Linux/macOS)
3. Make it executable: chmod +x iacconsole-cli
4. Move to your PATH: sudo mv iacconsole-cli /usr/local/bin/

Build from Source

git clone https://github.com/alt-dima/iacconsole-cli.git
cd iacconsole-cli
go build -o bin/iacconsole-cli .

Prerequisites

• OpenTofu or Terraform
• Go 1.19+ (for building from source)

Quick start locally with demo configuration

2. Install OpenTofu
3. Execute to generate simple demo configuration with connection to demo account in the IaCConsole API (CMDB):

iacconsole-cli init

To generate with file based inventory:

iacconsole-cli init --iacconsole-db=false

4. Follow on-screen instructions

Quick start with AI Coding Assistants

Getting started with IaCConsole CLI is even easier using AI coding assistants:

1. Open the repository in your preferred editor with an AI assistant installed:

• GitHub Copilot in VS Code
• Cursor
• Claude/Anthropic
• WindSurf
• Cline

2. Ask questions like:

• "How do I set up IaCConsole for AWS resources?"
• "Help me create a new unit for a GCP instance"
• "How do I use the IaCConsole API (CMDB)?"
• "Show me how to pass environment variables to my terraform code"

These instructions provide context about:

• The architecture and key concepts of IaCConsole CLI
• How to work with units, dimensions, and inventory sources
• Integration with the IaCConsole API (CMDB) and IaCConsole Web UI for centralized configuration
• Project-specific conventions and workflows

For more complex tasks, you can ask the AI assistant to guide you step-by-step through creating configurations, setting up the backend, or troubleshooting deployment issues.

What about alternative tools?

Yes, you should check other Infrastructure as Code (IaC) orchestration tools for Terraform:

• Atmos
• Digger
• Spacelift
• Terragrunt
• Terramate

So why another tool?

1. The more open source tools, the better (for GitHub Copilot, not for Earth).
2. The more choice, the better (there are countries where people have no choice).
3. Imagine there is only AWS CloudFormation.

Usage

Organization with AWS resources and state stored in S3

./iacconsole-cli exec --config examples/.iacconsolerc -o demo-org -d account:test-account -d datacenter:staging1 -u vpc -- init
./iacconsole-cli exec --config examples/.iacconsolerc -o demo-org -d account:test-account -d datacenter:staging1 -u vpc -- plan
./iacconsole-cli exec --config examples/.iacconsolerc -o demo-org -d account:test-account -d datacenter:staging1 -u vpc -- apply

Organization with Google Cloud resources and state stored in Google Cloud Storage

./iacconsole-cli exec --config examples/.iacconsolerc -o gcp-org -d account:free-tier -u free_instance -- init
./iacconsole-cli exec --config examples/.iacconsolerc -o gcp-org -d account:free-tier -u free_instance -- plan
./iacconsole-cli exec --config examples/.iacconsolerc -o gcp-org -d account:free-tier -u free_instance -- apply

• Everything after -- will be passed as parameters to the cmd_to_exec
• -c = to remove temp dir after any iacconsole-cli execution (after apply or destroy and exit code=0 temp dir removed automatically)
• -o = name of the organization (subfolder in Inventory, units folders and in .iacconsolerc config section)
• -d = dimension to attach to tofu/terraform. You may specify as many -d pairs as you need!
• -t = name of the unit in the units folder

unit Manifest

Special JSON file with the name unit_manifest.json in the unit folder provides options for iacconsole-cli.

Currently, only dimensions with a list of the required/expected dimensions (from Inventory Store)

unit_manifest.json example

Configuration Storage

Configuration Management Database (CMDB) — IaCConsole API

IaCConsole API is an OpenAPI-powered Configuration Management Database with a web-based IaCConsole Web UI for centrally managing infrastructure configurations.

You can set the env variable iacconsole_api_url to point to the IaCConsole API (CMDB), like:

export IACCONSOLE_API_URL='https://accountid:accountpass@api.iacconsole.com'

To generate your own credentials please go to https://iacconsole.com/, fill the form with Account Name, Email, and press Create Account and you will receive generated credentials and a ready-to-use export command like:

export IACCONSOLE_API_URL=https://6634b72292e9e996105de19e:generatedpassword@api.iacconsole.com

With the correct IACCONSOLE_API_URL, the CLI will connect and receive all the required dimension data from the IaCConsole API (CMDB). An additional parameter could be passed to iacconsole-cli -w workspacename. In general, workspacename is the branch name of the source repo where the dimension is stored. If Toaster CMDB does not find the dimension with the specified workspacename, it will try to return the dimension from the master workspace/branch!

IaCConsole API (CMDB) provides additional features for your CI/CD pipelines:

• IaCConsole Web UI - Visual console for managing configurations at https://iacconsole.com/console
• OpenAPI RESTful API - Programmatic access to configuration data with full API documentation
• CI/CD Integration - Fetch configurations directly in pipelines (e.g., first-app.json for validation)
• Dynamic Dropdowns - Get dimension lists for Jenkins drop-downs to select deployment targets

OpenAPI Documentation: Swagger API docs - Full RESTful API documentation and examples

To upload/update dimensions to the IaCConsole API from your Inventory Files repo you can use inventory-to-toaster.sh script example and execute it like bash examples/inventory-to-toaster.sh examples/inventory/

Please join the IaCConsole beta-testers!

File-based Configuration Storage (Inventory Files)

If the env variable IACCONSOLE_API_URL is not set, the CLI will use file-based configuration Storage (probably dedicated git repo), specified by the path configured in inventory_path.

Examples:

• staging1.json in Inventory Files
• dim_defaults.json in Inventory Files

Dimensions usage in tf-code

When you set dimensions in the CLI flags -d datacenter:staging1, IaCConsole CLI will provide you inside tf-code the following variables:

• var.iacconsole_datacenter_name = will contain string staging1
• var.iacconsole_datacenter_data = will contain the whole object from staging1.json
• var.iacconsole_datacenter_defaults = will contain the whole object from dim_defaults.json IF the file dim_defaults.json exists!

Examples:

• datacenter object with defaults used in tf-code

Passing environment variables from shell

For example, you need to pass a variable (AWS region) from shell to the terraform code, simply set it and use it!

Environment variable must start with iacconsole-cli_envvar_ prefix!

export iacconsole-cli_envvar_awsregion=us-east-1

In the TF code:

provider "aws" {
    region = var.iacconsole_envvar_awsregion
}

Env variables used in code example

$HOME/.iacconsolerc

Config file (in YAML format) path may be provided by the --config flag, for example:

iacconsole-cli --config path_to_config/iacconsole-cliconfig exec -o demo-org -d account:test-account -d datacenter:staging1 -u vpc -- init

If the --config flag is not set, then it will try to load from the default location $HOME/.iacconsolerc (current binary name remains iacconsole-cli).

.iacconsolerc example:

defaults:
  units_path: examples/units
  shared_modules_path: examples/units/shared-modules
  inventory_path: examples/inventory
  cmd_to_exec: tofu
  backend:
    bucket: default-tfstates
    key: $iacconsole-cli_state_path
    region: us-east-2
gcp-org:
  backend:
    bucket: gcp-tfstates
    prefix: $iacconsole-cli_state_path

• units_path = relative path to the folder with terraform code (unit)
• shared_modules_path = relative path to the folder with shared TF modules maybe used by any unit
• inventory_path = relative path to the folder with JSONs
• cmd_to_exec = name of the binary to execute (tofu or terraform)
• backend = Config values for backend provider. All the child key:values will be provided to init and $iacconsole-cli_state_path will be replaced by the generated path. For example, when you execute iacconsole-cli exec ...... -- init, IaCConsole CLI actually will execute init -backend-config=bucket=gcp-tfstates -backend-config=prefix=account_free-tier/free_instance.tfstate

At least

defaults:
  backend:
    bucket: default-tfstates
    key: $iacconsole-cli_state_path

must be set in the config file! With key:values specific for the backend provider being used in org!

Other options contain hard-coded defaults:

defaults:
  inventory_path: "examples/inventory"
  shared_modules_path: ""
  units_path: "examples/units"
  cmd_to_exec: "tofu"

Shared modules support

It is a good practice to move some generic terraform code to the modules and reuse those modules in multiple terraform code (units)

Path to the folder with such private shared modules is configured by the shared_modules_path parameter in the .iacconsolerc configuration file.

This folder will be mounted/linked to every temporary folder (set) so you could use any module by short path like

//use shared-module
module "vpc" {
  source = "./shared-modules/create_vpc"
}

Examples:

• Shared module for VPC creation
• Shared module for VPC creation used in code

Remote state (Terraform Backend where state data files are stored)

AWS, Google Cloud, and some other backends are supported! You can configure any backend provider in the Config file

For AWS S3 your terraform code (unit) should contain at least::

terraform {
  backend "s3" {}
}

For Google Cloud Storage your terraform code (unit) should contain at least::

terraform {
  backend "gcs" {}
}

If for the demo-org config bucket is set, then $iacconsole-cli_state_path will be like: dimName1_dimValue1/dimNameN_dimValueN/unitName.tfstate

If for the demo-org config bucket is NOT set, then $iacconsole-cli_state_path will be like org_demo-org/dimName1_dimValue1/dimNameN_dimValueN/unitName.tfstate

This could be useful if you want to store by default tfstate for all the organizations in the same/default bucket default-tfstates but for some specific organization you need to store tfstates in a dedicated bucket demo-org-tfstates

Data Source Configuration (data "terraform_remote_state")

To simplify "Data Source Configuration" (data "terraform_remote_state" "tfstate" { }) it will be nice to have backend config values as tfvars.

var.iacconsole_backend_config will contain all the parameters from the config (backend Section)

For example, for AWS S3:

data "terraform_remote_state" "network" {
  backend = "s3"
  config = {
    bucket = var.iacconsole_backend_config.bucket
    key    = "network/terraform.tfstate"
    region = var.iacconsole_backend_config.region
  }
}

And for GCS:

data "terraform_remote_state" "free_instance" {
  backend = "gcs"
  config = {
    bucket  = var.iacconsole_backend_config.bucket
    prefix  = "account_free-tier/free_instance.tfstate"
  }
}

You will set key/prefix to another unite's tfstate, which outputs you want to use.

$HOME/.tofurc

Recommended to enable plugin_cache_dir to reuse providers.

.tofurc example:

plugin_cache_dir   = "$HOME/.terraform.d/plugin-cache"
plugin_cache_may_break_dependency_lock_file = true

Do not forget to create the plugin-cache dir: mkdir "$HOME/.terraform.d/plugin-cache"

License

IaCConsole CLI is licensed with Apache License Version 2.0. Please read the LICENSE file for more details.