Module

Block Types

This document provides an overview of the block types available in the module system. Each block includes required/optional arguments, nested blocks, behavior, and example usage to help you implement them correctly.

module block

module is the defination for a module. It declares what image to launch, what the module is called, and itsmetadata (description and help url) that surfaces in documentation and editor hover data.

Required Arguments

The following arguments are required arguments.

description (string): One-sentence purpose statement shown in docs and editor intellisense.

Optional Arguments

The following arguments are optional arguments.

url (string): Link to docs, blog post, or source repo with deeper details. Rendered as a clickable link id docs and editor intellisense.

Outputs

The following arguments are outputs.

dir (string): Directory of this module file.

Example Block

module {
  description = ""
  url         = ""
}

import block

The import block declares a dependency on a reusable collection of modules It allows you to reference, install, and invoke modules from the specified import. Import sorces can be local filesystem or remote Git repositories.

Required Arguments

The following arguments are required arguments.

source (string): The source location of the import. It must be a Git repository URL (for example: https://github.com/org/import).

This is where the import will be downloaded from.

Optional Arguments

The following arguments are optional arguments.

version (string): A version constraint in SemVer format. This tells the system to download the highest matching Git tag. If not set, the latest stable version is used by default.

Outputs

The following arguments are outputs.

dir (string): The local path where the import was downloaded.

Example Block

import "example" {
  source  = ""
  version = ""
}

var block

The var block lets you define reusable variables that can reference values or call functions. These variables are read-only after they are set, and they help avoid repeating the same value in multiple places.

Variables can be used in any part of your module where expressions are allowed.

Example Block

var {
}

input block

Input blocks let users pass values into the module. These values are used to configure how the module behaves. Inputs can be set from the CLI, environment variables, or passed as arguments at runtime.

Required Arguments

The following arguments are required arguments.

description (string): A short explanation of what this input is for. It should describe the expected type and any special usage.
example (any type): An example value that shows what a valid input looks like. This is used in documentation or tools that generate input forms.
type (type): The expected type for this input (e.g. string, number, list(string)). This helps validate the input and gives better editor support.

Optional Arguments

The following arguments are optional arguments.

default (any type): The value to use if the user doesn’t set this input. Optional, but helpful for simplifying usage.
nullable (bool): If true, the input can be set to null. Defaults to false (null not allowed).

Nested Blocks

Nested blocks used to control the behavior of parent blocks.

assert

assert blocks are used to validate values. If the condition is false, the block fails with the error message.

condition (bool): A boolean expression that must be true. If false, the assertion fails.

For example: len(var.password) >= 8 checks that a password is at least 8 characters long.

error_msg (string): A custom message to show when the assertion fails. Use this to help users fix the issue.

Example Block

input "example" {
  description = ""
  example     = null
  type        = null
  default     = null
  nullable    = false
}

output block

Output blocks define values that are shared with other modules or tools. These outputs can expose the results of logic, values from inputs, or dynamic values created in the module.

Required Arguments

The following arguments are required arguments.

description (string): Explains what this output is for and what value it represents.
example (any type): A sample value that shows what this output will typically return.

This is useful for documentation, examples, and auto-completion tools.

type (type): The data type of the output value. For example: string, number, map, or list(string).

This is used for validation and helps users understand what kind of data to expect.

value (any type): The value to be shared by this output. Usually this is a reference to something like a result from a run, exec, or computed expression.

Nested Blocks

Nested blocks used to control the behavior of parent blocks.

assert

assert blocks are used to validate values. If the condition is false, the block fails with the error message.

condition (bool): A boolean expression that must be true. If false, the assertion fails.

For example: len(var.password) >= 8 checks that a password is at least 8 characters long.

error_msg (string): A custom message to show when the assertion fails. Use this to help users fix the issue.

Example Block

output "example" {
  description = ""
  example     = null
  type        = null
  value       = null
}

action ssh_download

This action describes a command to execute on a remote ssh endpoint.

Required Arguments

The following arguments are required arguments.

address (string): The address of the SSH endpoint to connect to.
local_path (string): This local (destination) path of the local host.
username (string): The username to use for the connection.

Optional Arguments

The following arguments are optional arguments.

password (string): The password to use for the connection.
port (number): The port to connect to. Defaults to 22.
private_key_file (string): The private key file to use for the connection.
private_key_password (string): The private key password to use for the connection.
remote_path (list of string): This remote (source) path on the remote host.
timeout_seconds (number): The timeout in seconds to wait for the connection to become available. Defaults to 300.
trust_new_hosts (bool): Specifies if new hosts can be trusted. Defaults to False.
use_agent_auth (bool): Specifies if auth via ssh agent is to be used for the connection. Defaults to False.

Example Block

action "example" {
  with                 = "ssh_download"
  address              = ""
  local_path           = ""
  username             = ""
  password             = ""
  port                 = 22
  private_key_file     = ""
  private_key_password = ""
  remote_path          = []
  timeout_seconds      = 300
  trust_new_hosts      = false
  use_agent_auth       = false
}

action command

The command runs any command. You can control the environment variables, command arguments, working directory, stdintimeout, and capture output values like stdout and exit code.

Required Arguments

The following arguments are required arguments.

command (list of string): Command to run.

Optional Arguments

The following arguments are optional arguments.

envs (map of string): Environment variables to set for the container. This overrides or adds to the image defaults.
host_network (bool): Connects the container directly to the host machine's network.
privileged (bool): Run the container in privileged mode, allowing full access like a root user.
stdin (string): Input data to send to the command's standard input (stdin).
timeout (number): Maximum number of seconds to allow the command to run.
workdir (string): Working directory where the command will run.

Outputs

The following arguments are outputs.

exit_code (number): The numeric exit code returned by the command. A value of 0 usually means success.
stderr (string): The standard error output of the command.
stdout (string): The standard output of the command.

Example Block

action "example" {
  with         = "command"
  command      = []
  envs         = {}
  host_network = false
  privileged   = false
  stdin        = ""
  timeout      = 0
  workdir      = ""
}

action http_request

The action specifies an HTTP request that can be executed. It supports performing operations such as GET, POST, PUT, or DELETE on specified URLs and handling the responses.

Required Arguments

The following arguments are required arguments.

url (string): The full URL to which the HTTP request is made. This is a required attribute and must specify a valid URL.

Optional Arguments

The following arguments are optional arguments.

ca_certs (list of string): A list of additional CA certificates for verifying the server's certificate.
client_cert (string): The client certificate (in PEM format) to use for mutual TLS authentication.
client_key (string): The private key (in PEM format) to use for mutual TLS authentication.
cookies (map of string): A map of cookies to include with the HTTP request.
method (string): The HTTP method to use for the request (e.g., GET, POST, PUT, DELETE). If omitted, defaults to GET.
queries (map of list of string): A map of query parameters to append to the URL (e.g., ?key=value).
request_body (string): The body of the HTTP request, typically used for POST or PUT methods. It can contain JSON, XML, or other supported formats.
request_headers (map of list of string): A map of HTTP headers to include in the request (e.g., Content-Type, Authorization).
skip_tls_verify (bool): If set to true, skips server TLS certificate verification. Useful for testing with self-signed certificates.
timeout (number): The timeout, in seconds, for the HTTP request. Defaults to 30.

Outputs

The following arguments are outputs.

response_body (string): The body of the HTTP response. This is computed after the request completes.
response_headers (list of string): The HTTP response headers. This is computed after the request completes.
status_code (number): The HTTP response status code (e.g., 200, 404). This is computed after the request completes.

Example Block

action "example" {
  with            = "http_request"
  url             = ""
  ca_certs        = []
  client_cert     = ""
  client_key      = ""
  cookies         = {}
  method          = "GET"
  queries         = {}
  request_body    = ""
  request_headers = {}
  skip_tls_verify = false
  timeout         = 30
}

action ssh_command

This action describes a command to execute on a remote ssh endpoint.

Required Arguments

The following arguments are required arguments.

address (string): The address of the SSH endpoint to connect to.
command (string): This is the path of the command to execute.
username (string): The username to use for the connection.

Optional Arguments

The following arguments are optional arguments.

args (list of string): If provided, this is a list of command arguments to append to the command. They are appended to the command (space separated) in the order they are provided.
envs (map of string): Map of key value pairs for providing additional and/or overwriting existing environment variables available to the the executed command. The executed command inherits the current process environment variables by default.
interpreter (list of string): If provided, this is a list of interpreter arguments used to execute the command. The first argument is the interpreter itself. The remaining arguments are appended prior to the command. This allows building command lines of the form "/bin/bash", "-c", "echo foo". If interpreter is unspecified, the command is invoked directly.
password (string): The password to use for the connection.
port (number): The port to connect to. Defaults to 22.
private_key_file (string): The private key file to use for the connection.
private_key_password (string): The private key password to use for the connection.
timeout_seconds (number): The timeout in seconds to wait for the connection to become available. Defaults to 300.
trust_new_hosts (bool): Specifies if new hosts can be trusted. Defaults to False.
use_agent_auth (bool): Specifies if auth via ssh agent is to be used for the connection. Defaults to False.

Outputs

The following arguments are outputs.

stderr (string): The executed commands's error output.
stdout (string): The executed commands's standard output.

Example Block

action "example" {
  with                 = "ssh_command"
  address              = ""
  command              = ""
  username             = ""
  args                 = []
  envs                 = {}
  interpreter          = []
  password             = ""
  port                 = 22
  private_key_file     = ""
  private_key_password = ""
  timeout_seconds      = 300
  trust_new_hosts      = false
  use_agent_auth       = false
}

action ssh_upload

This action describes a command to execute on a remote ssh endpoint.

Required Arguments

The following arguments are required arguments.

address (string): The address of the SSH endpoint to connect to.
local_path (string): This local (source) path of the file to upload from the local host.
username (string): The username to use for the connection.

Optional Arguments

The following arguments are optional arguments.

password (string): The password to use for the connection.
port (number): The port to connect to. Defaults to 22.
private_key_file (string): The private key file to use for the connection.
private_key_password (string): The private key password to use for the connection.
remote_path (list of string): This remote (destination) path on the remote host.
timeout_seconds (number): The timeout in seconds to wait for the connection to become available. Defaults to 300.
trust_new_hosts (bool): Specifies if new hosts can be trusted. Defaults to False.
use_agent_auth (bool): Specifies if auth via ssh agent is to be used for the connection. Defaults to False.

Example Block

action "example" {
  with                 = "ssh_upload"
  address              = ""
  local_path           = ""
  username             = ""
  password             = ""
  port                 = 22
  private_key_file     = ""
  private_key_password = ""
  remote_path          = []
  timeout_seconds      = 300
  trust_new_hosts      = false
  use_agent_auth       = false
}