Skip to main content

TerraformUtility

Octo's single interface to the terraform and terragrunt binaries.

Octo.generate writes module folders; this runs them, and turns their output back into the shapes the other modes expect - plan(dir, { json: true }) feeds Octo.validate, and output(dir, { json: true }) feeds Octo.commit. Routing every invocation through one class is what keeps flags, timeouts, and event emission consistent.

Resolve it from the Container so that a run's terraform events reach the same listeners as everything else.

@example
const terraform = await Container.getInstance().get(TerraformUtility);
const { errors, plans } = await terraform.plan('./infrastructure', { json: true });
const report = await octo.validate(app, { errors, plans });
@group

Utilities/Terraform

Index

Constructors

Methods

Constructors

constructor

  • TerraformUtility(options?: { stateCheckInIntervalInMs?: number; terraformBinary?: string; terragruntBinary?: string; timeoutInMs?: number }): TerraformUtility

  • Parameters

    • options: { stateCheckInIntervalInMs?: number; terraformBinary?: string; terragruntBinary?: string; timeoutInMs?: number } = {}

      Overrides for the binaries invoked, the per-command timeout, and the state check-in interval. terragruntBinary defaults to terragrunt.

      timeoutInMs defaults to 60 minutes for the commands that only read - plan, output, show. apply and destroy run unbounded unless it is given: a timeout there turns a slow apply into one killed part way through a mutation, and how long a stack legitimately takes is a fact about that stack rather than something a default can know. What bounds them instead is the caller - a CI job's own timeout, or a person at a terminal.

      stateCheckInIntervalInMs is how often terraform state is checked into the state provider while a command runs, 10 seconds by default. Terraform rewrites it as each resource completes.

      • optionalstateCheckInIntervalInMs: number
      • optionalterraformBinary: string
      • optionalterragruntBinary: string
      • optionaltimeoutInMs: number

    Returns TerraformUtility

Methods

apply

  • apply(terragruntDir: string): Promise<TerraformRawResult>

  • Runs terragrunt run --all -- apply over every generated module folder.

    This changes real infrastructure, and runs with -auto-approve. Use TerraformUtility.findPlannedDestroys beforehand if a destroy needs confirming.

    Parameters

    • terragruntDir: string

      The directory octo generated the module folders into.

    Returns Promise<TerraformRawResult>

deleteDestroyedFolders

  • deleteDestroyedFolders(terragruntDir: string, moduleIds: string[]): Promise<string[]>

  • Deletes the folder of each module in moduleIds whose terraform state holds no resources, as a folder emptied from intent holds once its destroy applied. A folder still holding resources is kept.

    Parameters

    • terragruntDir: string

      The directory octo generated the module folders into.

    • moduleIds: string[]

      The modules whose folders may go, such as those a commit emptied.

    Returns Promise<string[]>

    The modules whose folders were deleted.

destroy

  • destroy(terragruntDir: string): Promise<TerraformRawResult>

  • Runs terragrunt run --all -- destroy over every generated module folder.

    This tears down real infrastructure, and runs with -auto-approve.

    Parameters

    • terragruntDir: string

    Returns Promise<TerraformRawResult>

findPlannedDestroys

  • findPlannedDestroys(plans: Map<string, TerraformPlan>): { address: string; moduleId: string; tfActions: string[] }[]

  • Every address a set of plans may destroy, across all folders. A recreate (create + delete) counts, since the old object is still destroyed, and so does an action octo does not know.

    Lets a caller refuse to apply until the destroys have been shown, which apply cannot do on its own because it runs with -auto-approve.

    Parameters

    • plans: Map<string, TerraformPlan>

    Returns { address: string; moduleId: string; tfActions: string[] }[]

listModuleFolders

  • listModuleFolders(terragruntDir: string): Promise<string[]>

  • Returns the immediate sub-directories of terragruntDir that look like generated module folders (they contain a terragrunt.hcl). Each folder name is the octo moduleId.

    Parameters

    • terragruntDir: string

    Returns Promise<string[]>

setArgsOnce

  • setArgsOnce(args: string[]): this

  • To append extra CLI arguments to the next command only. Returns this, so it chains.

    Parameters

    • args: string[]

    Returns this

validate

  • validate(terragruntDir: string): Promise<TerraformRawResult>

  • Runs terragrunt run --all -- validate over every generated module folder, checking the generated HCL is well-formed. Unrelated to Octo.validate, which compares plans against intent.

    Parameters

    • terragruntDir: string

    Returns Promise<TerraformRawResult>

Page Options