mod

Every mod must contain a mod.pp file with a single mod block.

The mod block contains metadata for the mod (including metadata used in the hub site and social media), as well as dependency data. A mod author may edit the mod block directly, but Powerpipe will also edit the file, adding, removing and modifying dependencies in the file when users add and remove mods via the powerpipe mod commands. For this reason, it is recommended that the mod.pp only contain a mod block; do not add other mod resources (query, control, dashboard, etc) to this file.

The block name (aws_cis in the example) is the mod name. Mod names use lower_snake_case. They may contain lowercase chars, numbers or underscores, and must start with a letter.

Example Usage

mod "aws_cis" { 
  # hub metadata
  title          = "AWS CIS"
  description    = "AWS CIS Reporting and remediation"
  color          = "#FF9900"
  documentation  = file("./aws_cis_docs.md")
  icon           = "/images/plugins/turbot/aws.svg"
  categories         = ["Public Cloud", "AWS"]

  opengraph {
    title         = "Powerpipe Mod for AWS CIS"
    description   = "CIS reports, queries, and actions for AWS. Open source CLI. No DB required."
  }

  require {
    powerpipe {
      min_version = "0.20.0"
    }

    plugin "aws" {
      min_version = "0.86.0"
    }

    plugin "gcp" {
      min_version = "0.29.0"
    }

    mod "github.com/turbot/steampipe-mod-aws-compliance" {
      version = "^0.10"
    }
    mod "github.com/turbot/steampipe-mod-gcp-compliance" {
      version = "*"
    }
  }
}

Argument Reference

opengraph

The opengraph block is an optional block of metadata for use in social media applications that support Opengraph metadata.

require

A mod may contain a require block to specify version dependencies for the Powerpipe CLI, plugins, and mods. While it is possible to edit this section manually, Powerpipe will also modify it (including reordering and removing comments) when you run a powerpipe mod command to install, update, or uninstall a mod.

powerpipe

A mod may specify a dependency on the Powerpipe CLI. Powerpipe will evaluate the dependency when the mod is loaded and will error if the constraint is not met, but it will not install or upgrade the CLI. A powerpipe constraint specifies a minimum version, and does not support semver syntax:

require {
  powerpipe {
    min_version = "0.20.0"
  }
}

plugin

A mod may specify a dependency on one or more Steampipe plugins. Powerpipe will evaluate the dependency when the mod is loaded and will error if the constraint is not met, but it will not install or upgrade the plugin. A plugin constraint specifies a minimum version, and does not support semver syntax:

require {
  plugin "aws" {
    min_version = "0.24.0"
  }
}

mod

A mod may specify dependencies on other mods. While you can manually edit the mod dependencies in the mod.pp, they are more commonly managed by Powerpipe when you install, update, or uninstall mods via the powerpipe mod commands.

The mod dependency may specify a version. This can be a semver or an exact version:

require {
  mod "github.com/turbot/steampipe-mod-aws-insights" {
    version = "0.20.0"
  }
  mod "github.com/turbot/steampipe-mod-aws-compliance" {
    version = "^0.10"
  }
  mod "github.com/turbot/steampipe-mod-gcp-compliance" {
    version = "*"
  }
}

While in development, it is often easier to use local dependencies or install a mod from a branch or tagged commit.

To install from a branch, specify a branch:

require {
  mod "github.com/turbot/steampipe-mod-aws-compliance" {
    branch = "issue-779"
  }
}

To install from a tagged commit, specify a tag:

require {
  mod "github.com/turbot/steampipe-mod-aws-compliance" {
    tag = "issue-779"
  }
}

To install from a local directory, specify a path instead of a version:

require {
  mod "/Users/jsmyth/src/steampipe-mod-aws-insights" {
    path = "/Users/jsmyth/src/steampipe-mod-aws-insights"
  }
}

Note that for a given dependency, you must specify exactly one constraint (version, tag, branch or path).

You may pass args to set variables defined in the dependency mods. You can pass hard-coded values (literals), but it is more common to define variables in your mod that encapsulate the variables and optionality of your dependencies:

variable "common_dimensions" {
  type        = list(string)
  description = "A list of common dimensions to add to each control."
  default     = [ "account_id", "region" ]
}

variable "tag_dimensions" {
  type        = list(string)
  description = "A list of tags to add as dimensions to each control."
  default     = []
}

mod "aws_well_architected" {
  require {
    mod "github.com/turbot/steampipe-mod-aws-compliance" {
      version = "^0.63.0"
      args = {
        common_dimensions = var.common_dimensions,
        tag_dimensions    = var.tag_dimensions
      }
    }
  }
}

You may also override the search_path / search_path_prefix for the dependency mod if you want. Note that if you override search_path or search_path_prefix, the search_path and search_path_prefix workspace arguments and --search-path and --search-path-prefix CLI arguments will be ignored for the dependency mod.

variable "duckdb_database" {
  default = "duckdb:/home/ducks/mallard.db"
}

variable "steampipe_database" {
  type    = connection.steampipe
  default = connection.steampipe.default
}

mod "local" {
  require {
    mod "github.com/turbot/my-duckdb-mod" {
      version = ">=0.1.0"
      args = {
        database    = var.duckdb_database
      }
    }

    mod "github.com/turbot/steampipe-mod-aws-custom" {
      version = "~1.0.0"
      args = {
        database    = var.steampipe_database
      }
      search_path_prefix = "aws_01"
    }
  }
}