terraform

command module
v0.12.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 4, 2019 License: MPL-2.0 Imports: 32 Imported by: 2

README

Terraform

Terraform

Terraform is a tool for building, changing, and versioning infrastructure safely and efficiently. Terraform can manage existing and popular service providers as well as custom in-house solutions.

The key features of Terraform are:

  • Infrastructure as Code: Infrastructure is described using a high-level configuration syntax. This allows a blueprint of your datacenter to be versioned and treated as you would any other code. Additionally, infrastructure can be shared and re-used.

  • Execution Plans: Terraform has a "planning" step where it generates an execution plan. The execution plan shows what Terraform will do when you call apply. This lets you avoid any surprises when Terraform manipulates infrastructure.

  • Resource Graph: Terraform builds a graph of all your resources, and parallelizes the creation and modification of any non-dependent resources. Because of this, Terraform builds infrastructure as efficiently as possible, and operators get insight into dependencies in their infrastructure.

  • Change Automation: Complex changesets can be applied to your infrastructure with minimal human interaction. With the previously mentioned execution plan and resource graph, you know exactly what Terraform will change and in what order, avoiding many possible human errors.

For more information, see the introduction section of the Terraform website.

Getting Started & Documentation

If you're new to Terraform and want to get started creating infrastructure, please checkout our Getting Started guide, available on the Terraform website.

All documentation is available on the Terraform website:

Developing Terraform

If you wish to work on Terraform itself or any of its built-in providers, you'll first need Go installed on your machine (version 1.11+ is required).

This repository contains only Terraform core, which includes the command line interface and the main graph engine. Providers are implemented as plugins that each have their own repository in the terraform-providers organization on GitHub. Instructions for developing each provider are in the associated README file. For more information, see the provider development overview.

For local development of Terraform core, first make sure Go is properly installed and that a GOPATH has been set. You will also need to add $GOPATH/bin to your $PATH.

Next, using Git, clone this repository into $GOPATH/src/github.com/hashicorp/terraform.

You'll need to run make tools to install some required tools, then make. This will compile the code and then run the tests. If this exits with exit status 0, then everything is working! You only need to run make tools once (or when the tools change).

$ cd "$GOPATH/src/github.com/hashicorp/terraform"
$ make tools
$ make

To compile a development version of Terraform and the built-in plugins, run make dev. This will build everything using gox and put Terraform binaries in the bin and $GOPATH/bin folders:

$ make dev
...
$ bin/terraform
...

If you're developing a specific package, you can run tests for just that package by specifying the TEST variable. For example below, only terraform package tests will be run.

$ make test TEST=./terraform
...

If you're working on a specific provider which has not been separated into an individual repository and only wish to rebuild that provider, you can use the plugin-dev target. For example, to build only the Test provider:

$ make plugin-dev PLUGIN=provider-test
Dependencies

Terraform uses Go Modules for dependency management, but for the moment is continuing to use Go 1.6-style vendoring for compatibility with tools that have not yet been updated for full Go Modules support.

If you're developing Terraform, there are a few tasks you might need to perform.

Adding a dependency

If you're adding a dependency, you'll need to vendor it in the same Pull Request as the code that depends on it. You should do this in a separate commit from your code, as makes PR review easier and Git history simpler to read in the future.

To add a dependency:

Assuming your work is on a branch called my-feature-branch, the steps look like this:

  1. Add an import statement to a suitable package in the Terraform code.

  2. Run go mod vendor to download the latest version of the module containing the imported package into the vendor/ directory, and update the go.mod and go.sum files.

  3. Review the changes in git and commit them.

Updating a dependency

To update a dependency:

  1. Run go get -u module-path@version-number, such as go get -u github.com/hashicorp/hcl@2.0.0

  2. Run go mod vendor to update the vendored copy in the vendor/ directory.

  3. Review the changes in git and commit them.

Acceptance Tests

Terraform has a comprehensive acceptance test suite covering the built-in providers. Our Contributing Guide includes details about how and when to write and run acceptance tests in order to help contributions get accepted quickly.

Cross Compilation and Building for Distribution

If you wish to cross-compile Terraform for another architecture, you can set the XC_OS and XC_ARCH environment variables to values representing the target operating system and architecture before calling make. The output is placed in the pkg subdirectory tree both expanded in a directory representing the OS/architecture combination and as a ZIP archive.

For example, to compile 64-bit Linux binaries on Mac OS X, you can run:

$ XC_OS=linux XC_ARCH=amd64 make bin
...
$ file pkg/linux_amd64/terraform
terraform: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, not stripped

XC_OS and XC_ARCH can be space separated lists representing different combinations of operating system and architecture. For example, to compile for both Linux and Mac OS X, targeting both 32- and 64-bit architectures, you can run:

$ XC_OS="linux darwin" XC_ARCH="386 amd64" make bin
...
$ tree ./pkg/ -P "terraform|*.zip"
./pkg/
├── darwin_386
│   └── terraform
├── darwin_386.zip
├── darwin_amd64
│   └── terraform
├── darwin_amd64.zip
├── linux_386
│   └── terraform
├── linux_386.zip
├── linux_amd64
│   └── terraform
└── linux_amd64.zip

4 directories, 8 files

Note: Cross-compilation uses gox, which requires toolchains to be built with versions of Go prior to 1.5. In order to successfully cross-compile with older versions of Go, you will need to run gox -build-toolchain before running the commands detailed above.

Docker

When using docker you don't need to have any of the Go development tools installed and you can clone terraform to any location on disk (doesn't have to be in your $GOPATH). This is useful for users who want to build master or a specific branch for testing without setting up a proper Go environment.

For example, run the following command to install the required tools and build terraform in a linux-based container for macOS.

docker run --rm -v $(pwd):/go/src/github.com/hashicorp/terraform -w /go/src/github.com/hashicorp/terraform -e XC_OS=darwin -e XC_ARCH=amd64 golang:latest bash -c "apt-get update && apt-get install -y zip && make tools bin"

License

Mozilla Public License v2.0

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
Package addrs contains types that represent "addresses", which are references to specific objects within a Terraform configuration or state.
Package addrs contains types that represent "addresses", which are references to specific objects within a Terraform configuration or state.
Package backend provides interfaces that the CLI uses to interact with Terraform.
Package backend provides interfaces that the CLI uses to interact with Terraform.
init
Package init contains the list of backends that can be initialized and basic helper functions for initializing those backends.
Package init contains the list of backends that can be initialized and basic helper functions for initializing those backends.
remote-state/gcs
Package gcs implements remote storage of state on Google Cloud Storage (GCS).
Package gcs implements remote storage of state on Google Cloud Storage (GCS).
builtin
This file is automatically generated by scripts/generate-plugins.go -- Do not edit!
This file is automatically generated by scripts/generate-plugins.go -- Do not edit!
cliconfig
Package cliconfig has the types representing and the logic to load CLI-level configuration settings.
Package cliconfig has the types representing and the logic to load CLI-level configuration settings.
clistate
Package state exposes common helpers for working with state from the CLI.
Package state exposes common helpers for working with state from the CLI.
e2etest
Package e2etest contains a small number of tests that run against a real Terraform binary, compiled on the fly at the start of the test run.
Package e2etest contains a small number of tests that run against a real Terraform binary, compiled on the fly at the start of the test run.
format
Package format contains helpers for formatting various Terraform structures for human-readabout output.
Package format contains helpers for formatting various Terraform structures for human-readabout output.
jsonconfig
Package jsonconfig implements methods for outputting a configuration snapshot in machine-readable json format
Package jsonconfig implements methods for outputting a configuration snapshot in machine-readable json format
jsonplan
Package jsonplan implements methods for outputting a plan in a machine-readable json format
Package jsonplan implements methods for outputting a plan in a machine-readable json format
jsonprovider
Package jsonprovider contains types and functions to marshal terraform provider schemas into a json formatted output.
Package jsonprovider contains types and functions to marshal terraform provider schemas into a json formatted output.
jsonstate
Package jsonstate implements methods for outputting a state in a machine-readable json format
Package jsonstate implements methods for outputting a state in a machine-readable json format
ssh
The config package is responsible for loading and validating the configuration.
The config package is responsible for loading and validating the configuration.
Package configs contains types that represent Terraform configurations and the different elements thereof.
Package configs contains types that represent Terraform configurations and the different elements thereof.
configload
Package configload knows how to install modules into the .terraform/modules directory and to load modules from those installed locations.
Package configload knows how to install modules into the .terraform/modules directory and to load modules from those installed locations.
configschema
Package configschema contains types for describing the expected structure of a configuration block whose shape is not known until runtime.
Package configschema contains types for describing the expected structure of a configuration block whose shape is not known until runtime.
configupgrade
Package configupgrade upgrades configurations targeting our legacy configuration loader (in package "config") to be compatible with and idiomatic for the newer configuration loader (in package "configs").
Package configupgrade upgrades configurations targeting our legacy configuration loader (in package "config") to be compatible with and idiomatic for the newer configuration loader (in package "configs").
helper
acctest
Package acctest contains for Terraform Acceptance Tests
Package acctest contains for Terraform Acceptance Tests
customdiff
Package customdiff provides a set of reusable and composable functions to enable more "declarative" use of the CustomizeDiff mechanism available for resources in package helper/schema.
Package customdiff provides a set of reusable and composable functions to enable more "declarative" use of the CustomizeDiff mechanism available for resources in package helper/schema.
experiment
experiment package contains helper functions for tracking experimental features throughout Terraform.
experiment package contains helper functions for tracking experimental features throughout Terraform.
pathorcontents
Helpers for dealing with file paths and their contents
Helpers for dealing with file paths and their contents
plugin
Package plugin contains types and functions to help Terraform plugins implement the plugin rpc interface.
Package plugin contains types and functions to help Terraform plugins implement the plugin rpc interface.
schema
schema is a high-level framework for easily writing new providers for Terraform.
schema is a high-level framework for easily writing new providers for Terraform.
signalwrapper
Package signalwrapper is used to run functions that are sensitive to signals that may be received from outside the process.
Package signalwrapper is used to run functions that are sensitive to signals that may be received from outside the process.
variables
Package variables provides functions and types for working with Terraform variables provided as input.
Package variables provides functions and types for working with Terraform variables provided as input.
wrappedreadline
wrappedreadline is a package that has helpers for interacting with readline from a panicwrap executable.
wrappedreadline is a package that has helpers for interacting with readline from a panicwrap executable.
wrappedstreams
Package wrappedstreams provides access to the standard OS streams (stdin, stdout, stderr) even if wrapped under panicwrap.
Package wrappedstreams provides access to the standard OS streams (stdin, stdout, stderr) even if wrapped under panicwrap.
internal
earlyconfig
Package earlyconfig is a specialized alternative to the top-level "configs" package that does only shallow processing of configuration and is therefore able to be much more liberal than the full config loader in what it accepts.
Package earlyconfig is a specialized alternative to the top-level "configs" package that does only shallow processing of configuration and is therefore able to be much more liberal than the full config loader in what it accepts.
initwd
Package initwd contains various helper functions used by the "terraform init" command to initialize a working directory.
Package initwd contains various helper functions used by the "terraform init" command to initialize a working directory.
modsdir
Package modsdir is an internal package containing the model types used to represent the manifest of modules in a local modules cache directory.
Package modsdir is an internal package containing the model types used to represent the manifest of modules in a local modules cache directory.
legacy Module
terraform-ng Module
Package lang deals with the runtime aspects of Terraform's configuration language, with concerns such as expression evaluation.
Package lang deals with the runtime aspects of Terraform's configuration language, with concerns such as expression evaluation.
blocktoattr
Package blocktoattr includes some helper functions that can perform preprocessing on a HCL body where a configschema.Block schema is available in order to allow list and set attributes defined in the schema to be optionally written by the user as block syntax.
Package blocktoattr includes some helper functions that can perform preprocessing on a HCL body where a configschema.Block schema is available in order to allow list and set attributes defined in the schema to be optionally written by the user as block syntax.
Package moduledeps contains types that can be used to describe the providers required for all of the modules in a module tree.
Package moduledeps contains types that can be used to describe the providers required for all of the modules in a module tree.
Package plans contains the types that are used to represent Terraform plans.
Package plans contains the types that are used to represent Terraform plans.
internal/planproto
Package planproto is home to the Go stubs generated from the tfplan protobuf schema.
Package planproto is home to the Go stubs generated from the tfplan protobuf schema.
objchange
Package objchange deals with the business logic of taking a prior state value and a config value and producing a proposed new merged value, along with other related rules in this domain.
Package objchange deals with the business logic of taking a prior state value and a config value and producing a proposed new merged value, along with other related rules in this domain.
planfile
Package planfile deals with the file format used to serialize plans to disk and then deserialize them back into memory later.
Package planfile deals with the file format used to serialize plans to disk and then deserialize them back into memory later.
mock_proto
Package mock_tfplugin5 is a generated GoMock package.
Package mock_tfplugin5 is a generated GoMock package.
Package providers contains the interface and primary types required to implement a Terraform resource provider.
Package providers contains the interface and primary types required to implement a Terraform resource provider.
Package provisioners contains the interface and primary types to implement a Terraform resource provisioner.
Package provisioners contains the interface and primary types to implement a Terraform resource provisioner.
regsrc
Package regsrc provides helpers for working with source strings that identify resources within a Terraform registry.
Package regsrc provides helpers for working with source strings that identify resources within a Terraform registry.
Package repl provides the structs and functions necessary to run REPL for Terraform.
Package repl provides the structs and functions necessary to run REPL for Terraform.
Generate Plugins is a small program that updates the lists of plugins in command/internal_plugin_list.go so they will be compiled into the main terraform binary.
Generate Plugins is a small program that updates the lists of plugins in command/internal_plugin_list.go so they will be compiled into the main terraform binary.
Package states contains the types that are used to represent Terraform states.
Package states contains the types that are used to represent Terraform states.
statefile
Package statefile deals with the file format used to serialize states for persistent storage and then deserialize them into memory again later.
Package statefile deals with the file format used to serialize states for persistent storage and then deserialize them into memory again later.
statemgr
Package statemgr defines the interfaces and some supporting functionality for "state managers", which are components responsible for writing state to some persistent storage and then later retrieving it.
Package statemgr defines the interfaces and some supporting functionality for "state managers", which are components responsible for writing state to some persistent storage and then later retrieving it.
Package svchost deals with the representations of the so-called "friendly hostnames" that we use to represent systems that provide Terraform-native remote services, such as module registry, remote operations, etc.
Package svchost deals with the representations of the so-called "friendly hostnames" that we use to represent systems that provide Terraform-native remote services, such as module registry, remote operations, etc.
auth
Package auth contains types and functions to manage authentication credentials for service hosts.
Package auth contains types and functions to manage authentication credentials for service hosts.
disco
Package disco handles Terraform's remote service discovery protocol.
Package disco handles Terraform's remote service discovery protocol.
Package tfdiags is a utility package for representing errors and warnings in a manner that allows us to produce good messages for the user.
Package tfdiags is a utility package for representing errors and warnings in a manner that allows us to produce good messages for the user.
tools
terraform-bundle
terraform-bundle is a tool to create "bundle archives" that contain both a particular version of Terraform and a set of providers for use with it.
terraform-bundle is a tool to create "bundle archives" that contain both a particular version of Terraform and a set of providers for use with it.
terraform-bundle/e2etest
terraform bundle e2e tests
terraform bundle e2e tests
The version package provides a location to set the release versions for all packages to consume, without creating import cycles.
The version package provides a location to set the release versions for all packages to consume, without creating import cycles.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL