diff --git a/content/terraform/v1.14.x/data/language-nav-data.json b/content/terraform/v1.14.x/data/language-nav-data.json index 4d5633fc2d..449f29fabd 100644 --- a/content/terraform/v1.14.x/data/language-nav-data.json +++ b/content/terraform/v1.14.x/data/language-nav-data.json @@ -1,42 +1,10 @@ [ - { "heading": "Terraform Language" }, - { "title": "Overview", "path": "" }, { - "title": "Attributes as Blocks - Configuration Language", - "path": "attr-as-blocks", - "hidden": true + "title": "Get started", + "href": "https://developer.hashicorp.com/terraform/tutorials" }, { - "title": "Style guide", - "path": "style" - }, - { - "title": "Syntax", - "routes": [ - { "title": "Overview", "path": "syntax" }, - { - "title": "Configuration syntax", - "path": "syntax/configuration" - }, - { - "title": "JSON configuration syntax", - "path": "syntax/json" - } - ] - }, - { - "title": "Files and configuration structure", - "routes": [ - { "title": "Overview", "path": "files" }, - { "title": "Override files", "path": "files/override" }, - { "title": "Dependency lock file", "path": "files/dependency-lock" }, - { "title": "Test files", "path": "files/tests" }, - { "title": "Query files", "path": "files/tfquery" }, - { "title": "Stack files", "path": "files/stack" } - ] - }, - { - "title": "Install providers", + "title": "Configure providers", "routes": [ { "title": "Overview", "path": "providers" }, { @@ -46,60 +14,80 @@ { "title": "Dependency lock file", "href": "/language/files/dependency-lock" + }, + { + "title": "provider block reference", + "path": "block/provider" + }, + { + "title": "terraform block reference", + "path": "block/terraform" } ] }, { - "title": "Create and manage resources", + "title": "Resources", "routes": [ { "title": "Overview", "path": "resources" }, { "title": "Configure a resource", "path": "resources/configure" }, - { "title": "Destroy a resource", "path": "resources/destroy" } + { "title": "Destroy a resource", "path": "resources/destroy" }, + { "title": "resource block reference", "path": "block/resource" } ] }, { - "title": "Manage values in modules", - "alias": "variables, outputs, locals", + "title": "Data sources", + "routes": [ + { + "title": "Query infrastructure data", + "path": "data-sources" + }, + { + "title": "data block reference", + "path": "block/data" + } + ] + }, + { + "title": "Variables", "routes": [ - { - "title": "Overview", - "path": "values" - }, { "title": "Use variables", "path": "values/variables" }, { - "title": "Use locals", - "path": "values/locals" - }, - { - "title": "Use outputs", - "path": "values/outputs" + "title": "variable block reference", + "path": "block/variable" } ] - }, - { - "title": "Manage sensitive data", + }, + { + "title": "Locals", "routes": [ { - "title": "Overview", - "path": "manage-sensitive-data" + "title": "Use locals", + "path": "values/locals" }, { - "title": "Ephemeral values in resources", - "path": "manage-sensitive-data/ephemeral" + "title":"locals block reference", + "path": "block/locals" + } + ] + }, + { + "title": "Outputs", + "routes": [ + { + "title": "Use outputs", + "path": "values/outputs" }, { - "title": "Use temporary write-only arguments", - "path": "manage-sensitive-data/write-only", - "alias": "write only" + "title": "output block reference", + "path": "block/output" } ] }, - { "title": "Query infrastructure data", "path": "data-sources", "alias": "data sources" }, - { - "title": "Build and use modules", + { + "title": "Modules", "routes": [ { "title": "Overview", "path": "modules" }, { "title":"Use modules", "path": "modules/configuration" }, @@ -128,33 +116,45 @@ "path": "modules/develop/refactoring" } ] + }, + { + "title": "module block reference", + "path": "block/module" } ] }, - { - "title": "Manage state", + { + "title": "Meta-arguments", + "alias": "depends_on, count, for_each, lifecycle, providers, provider meta-argument", + "path": "meta-arguments" + }, + { + "title": "Sensitive data", "routes": [ - { "title": "Overview", "path": "state" }, - { "title": "Purpose", "path": "state/purpose" }, { - "title": "Manage state in remote backends", - "path": "state/backends" + "title": "Manage sensitive data", + "path": "manage-sensitive-data" }, { - "title": "Refactor state", - "path": "state/refactor" + "title": "Use temporary write-only arguments", + "path": "manage-sensitive-data/write-only", + "alias": "write only" }, - { "title": "Remove a resource from state", "path": "state/remove" }, - { "title": "Locking", "path": "state/locking" }, - { "title": "Workspaces", "path": "state/workspaces" }, - { "title": "Remote state", "path": "state/remote" } + { + "title": "Ephemeral values in resources", + "path": "manage-sensitive-data/ephemeral" + }, + { + "title": "ephemeral block reference", + "path": "block/ephemeral" + } ] }, { - "title": "Store state remotely", + "title": "Backends", "routes": [ { - "title": "Overview", + "title": "Configure a backend", "path": "backend" }, { @@ -208,42 +208,47 @@ ] }, { - "title": "Import existing resources", - "routes": [ - { "title": "Overview", "path": "import"}, - { - "title": "Import resources in bulk", - "path": "import/bulk", - "alias": "search, terraform search, query, list" - }, - { "title": "Import a single resource", "path": "import/single-resource" }, - { - "title": "Generate configuration for single imports", - "path": "import/generating-configuration" - } + "title": "Search and import", + "routes": [ + { "title": "Overview", "path": "import"}, + { + "title": "Import resources in bulk", + "alias": "search, terraform search, query, list", + "path": "import/bulk" + }, + { "title": "Import a single resource", "path": "import/single-resource" }, + { + "title": "Generate configuration for single imports", + "path": "import/generating-configuration" + }, + { + "title": "import block reference", + "path": "block/import" + }, + { + "title": "list block reference", + "alias": "search, terraform search, query, list", + "path": "block/tfquery/list" + } ] }, { - "title": "Test and validate configuration", + "title": "State", "routes": [ - { "title": "Validate your configuration", "path": "validate" }, - { - "title": "Test your configuration", - "routes": [ - { - "title": "Overview", - "path": "tests" - }, - { - "title": "Mocks", - "path": "tests/mocking" - } - ] - } + { "title": "Overview", "path": "state" }, + { "title": "Purpose", "path": "state/purpose" }, + { "title": "Manage state in remote backends", "path": "state/backends" }, + { "title": "Refactor state", "path": "state/refactor" }, + { "title": "Remove a resource from state", "path": "state/remove" }, + { "title": "Locking", "path": "state/locking" }, + { "title": "Workspaces", "path": "state/workspaces" }, + { "title": "Remote state", "path": "state/remote" }, + { "title": "removed block reference", "path": "block/removed" }, + { "title": "moved block reference", "path": "block/moved" } ] }, { - "title": "Manage infrastructure at scale with Stacks", + "title": "Stacks", "routes": [ { "title": "Overview", "path": "stacks", "alias": "stacks"}, { "title": "Update from beta to general availability", "path": "stacks/update-GA" }, @@ -269,24 +274,94 @@ ] }, { - "title": "Invoke actions", - "path": "invoke-actions" - }, - { - "title": "Use provisioners for post-apply operations", - "path": "provisioners", - "alias": "provisioners" + "title": "Test and validate", + "routes": [ + { "title": "Validate your configuration", "path": "validate" }, + { + "title": "Test your configuration", + "routes": [ + { + "title": "Overview", + "path": "tests" + }, + { + "title": "Mocks", + "path": "tests/mocking" + } + ] + }, + { + "title": "check block reference", + "path": "block/check" + } + ] }, { - "title": "Upgrade to Terraform v1.12", - "path": "upgrade-guides" + "title": "Extend CRUD operations", + "alias": "actions, terraform actions", + "routes": [ + { + "title": "Invoke actions", + "path": "invoke-actions" + }, + { + "title": "Post-apply operations", + "path": "post-apply-operations" + }, + { + "title": "Provisioners", + "path": "provisioners" + }, + { + "title": "action block reference", + "path": "block/action" + } + ] }, + { "divider": true }, + { "heading": "UPGRADE"}, + { "title": "Overview", "path": "upgrade-guides" }, { - "title": "v1.x Compatibility promises", + "title": "v1.x compatibility promises", "path": "v1-compatibility-promises" }, - { "divider": true }, + { + "divider": true }, { "heading": "REFERENCE" }, + { + "title": "Style guide", + "path": "style" + }, + { + "title": "Syntax", + "routes": [ + { "title": "Overview", "path": "syntax" }, + { + "title": "Configuration syntax", + "path": "syntax/configuration" + }, + { + "title": "JSON configuration syntax", + "path": "syntax/json" + }, + { + "title": "Attributes as blocks", + "path": "attr-as-blocks", + "hidden": false + } + ] + }, + { + "title": "Files and configuration structure", + "routes": [ + { "title": "Overview", "path": "files" }, + { "title": "Override files", "path": "files/override" }, + { "title": "Dependency lock file", "path": "files/dependency-lock" }, + { "title": "Test files", "path": "files/tests" }, + { "title": "Query files", "path": "files/tfquery" }, + { "title": "Stack files", "path": "files/stack" } + ] + }, { "title": "Configuration blocks", "routes": [ @@ -1163,5 +1238,5 @@ { "title": "zipmap", "path": "functions/zipmap", "hidden": true } ] }, - { "title": "Terraform internals", "href": "/internals" } + { "title": "Internals", "href": "/internals" } ] diff --git a/content/terraform/v1.14.x/docs/language/block/check.mdx b/content/terraform/v1.14.x/docs/language/block/check.mdx index 8f03965e02..0c1220bf24 100644 --- a/content/terraform/v1.14.x/docs/language/block/check.mdx +++ b/content/terraform/v1.14.x/docs/language/block/check.mdx @@ -7,7 +7,8 @@ description: How to use the `check` block to validate infrastructure outside of Use the `check` block to validate your infrastructure outside of the typical resource lifecycle. -Terraform executes the `check` block as the last step of plan or apply operation, after Terraform has planned or provisioned your infrastructure. When a `check` block's assertion fails, Terraform reports a warning and continues executing the current operation. +Terraform executes the `check` block as the last step of plan or apply operation, after Terraform has planned or provisioned your infrastructure. When a `check` block's assertion fails, Terraform reports a warning and continues executing the current operation. Refer to [Validate your configuration](/terraform/language/validate) for more information. + ## Background diff --git a/content/terraform/v1.14.x/docs/language/block/ephemeral.mdx b/content/terraform/v1.14.x/docs/language/block/ephemeral.mdx index 87c4960846..e2682365a9 100644 --- a/content/terraform/v1.14.x/docs/language/block/ephemeral.mdx +++ b/content/terraform/v1.14.x/docs/language/block/ephemeral.mdx @@ -5,14 +5,12 @@ description: Use the `ephemeral` block to define temporary resources that Terraf # `ephemeral` block reference -Use the `ephemeral` block to define temporary resources that Terraform does not store in state or plan files. +Use the `ephemeral` block to define temporary resources that Terraform does not store in state or plan files. To learn more about the `ephemeral` block and its unique lifecycle and provisioning order, refer to [Manage sensitive data](/terraform/language/manage-sensitive-data). ## Background The `ephemeral` block declares a temporary ephemeral resource that only exists during the current Terraform operation. Terraform does not store ephemeral resources in state or plan files, making them ideal for managing sensitive or temporary data that you do not want to persist, such as temporary passwords or connections to other systems. -To learn more about the `ephemeral` block and its unique lifecycle and provisioning order, refer to [Manage sensitive data](/terraform/language/manage-sensitive-data). - ### Lifecycle Ephemeral resources have a unique lifecycle compared to regular resources and data sources. Terraform performs the following lifecycle steps for each ephemeral resource: diff --git a/content/terraform/v1.14.x/docs/language/block/locals.mdx b/content/terraform/v1.14.x/docs/language/block/locals.mdx index 5de7543f63..f6e15015b8 100644 --- a/content/terraform/v1.14.x/docs/language/block/locals.mdx +++ b/content/terraform/v1.14.x/docs/language/block/locals.mdx @@ -5,9 +5,7 @@ description: Use the `locals` block to define values and reuse them within a Ter # `locals` block reference -Use the `locals` block to define values and reuse them within a Terraform module. - -> **Hands-on:** Try the [Simplify Terraform Configuration with Locals](/terraform/tutorials/configuration-language/locals) tutorial. +Use the `locals` block to define values and reuse them within a Terraform module. To learn more about using `locals` blocks in your configurations, refer to [Use locals to reuse expressions](/terraform/language/values/locals). ## Background @@ -15,7 +13,7 @@ The `locals` block is similar to function-scoped variables in other programming You can define local values in any module. Local values can be any valid Terraform expression, and can reference variables, resource attributes, function outputs, or other local values to transform or combine data. -To learn more about using `locals` blocks in your configurations, refer to [Use locals to reuse expressions](/terraform/language/values/locals). +> **Hands-on:** Try the [Simplify Terraform Configuration with Locals](/terraform/tutorials/configuration-language/locals) tutorial. ## Configuration model diff --git a/content/terraform/v1.14.x/docs/language/block/module.mdx b/content/terraform/v1.14.x/docs/language/block/module.mdx index 28d2aeedc6..90d2e49691 100644 --- a/content/terraform/v1.14.x/docs/language/block/module.mdx +++ b/content/terraform/v1.14.x/docs/language/block/module.mdx @@ -5,11 +5,7 @@ description: Learn how to configure a `module` block, which instructs Terraform # `module` block reference -The `module` block instructs Terraform to create resources defined in a local or remote module. - -## Introduction - -A module is a collection of multiple resources that Terraform manages together. Refer to the following topics for more information: +The `module` block instructs Terraform to create resources defined in a local or remote module. A module is a collection of multiple resources that Terraform manages together. Refer to the following topics for more information: - [Modules overview](/terraform/language/modules) - [Use modules in your configuration](/terraform/language/modules/configuration) diff --git a/content/terraform/v1.14.x/docs/language/block/output.mdx b/content/terraform/v1.14.x/docs/language/block/output.mdx index 57d1a71e4b..966d01d722 100644 --- a/content/terraform/v1.14.x/docs/language/block/output.mdx +++ b/content/terraform/v1.14.x/docs/language/block/output.mdx @@ -5,9 +5,7 @@ description: Use the `output` block to expose information about your module's in # `output` block reference -The `output` block lets you expose information about your infrastructure. - -> **Hands-on:** Try the [Output Data From Terraform](/terraform/tutorials/configuration-language/outputs) tutorial. +The `output` block lets you expose information about your infrastructure. To learn more about using `output` blocks, refer to [Use outputs to expose module data](/terraform/language/values/outputs). ## Background @@ -20,7 +18,7 @@ The value of an `output` block is similar to a return value in other programming In HCP Terraform, your `output` block values appear in the UI after Terraform applies your configuration. You can [mark outputs as sensitive in HCP Terraform](/terraform/cloud-docs/workspaces/variables/managing-variables#sensitive-values) to hide their values in the UI and in API responses. -To learn more about using `output` blocks, refer to [Use outputs to expose module data](/terraform/language/values/outputs). +> **Hands-on:** Try the [Output Data From Terraform](/terraform/tutorials/configuration-language/outputs) tutorial. ## Configuration model diff --git a/content/terraform/v1.14.x/docs/language/block/provider.mdx b/content/terraform/v1.14.x/docs/language/block/provider.mdx index dfa7f1327b..9c0a041584 100644 --- a/content/terraform/v1.14.x/docs/language/block/provider.mdx +++ b/content/terraform/v1.14.x/docs/language/block/provider.mdx @@ -5,9 +5,7 @@ description: Use the `provider` block to declare and configure Terraform plugins # `provider` block reference -Use the `provider` block to declare and configure Terraform plugins, called providers. Providers let Terraform manage real-world infrastructure with provider-defined resources and data sources. - -> **Hands-on:** Try the [Perform CRUD Operations with Providers](/terraform/tutorials/configuration-language/provider-use) tutorial. +Use the `provider` block to declare and configure Terraform plugins, called providers. Providers let Terraform manage real-world infrastructure with provider-defined resources and data sources. To learn how to declare providers in your configuration, refer to [Provider requirements](/terraform/language/providers/requirements). ## Background @@ -17,7 +15,9 @@ HashiCorp's public [Terraform registry](https://registry.terraform.io/browse/pro Anyone can develop a Terraform provider and use it locally, or publish it to the Terraform public registry or HCP Terraform private registry. To learn more about authoring providers, refer to the [Plugin framework](/terraform/plugin/framework). -Define provider configurations in the root module of your Terraform configuration. Child modules receive their provider configurations from their parent modules, so we strongly recommend against defining `provider` blocks in child modules. To learn how to declare providers in your configuration, refer to [Provider requirements](/terraform/language/providers/requirements). +Define provider configurations in the root module of your Terraform configuration. Child modules receive their provider configurations from their parent modules, so we strongly recommend against defining `provider` blocks in child modules. + +> **Hands-on:** Try the [Perform CRUD Operations with Providers](/terraform/tutorials/configuration-language/provider-use) tutorial. ## Configuration model diff --git a/content/terraform/v1.14.x/docs/language/block/resource.mdx b/content/terraform/v1.14.x/docs/language/block/resource.mdx index 29aec01a7d..61d82d3107 100644 --- a/content/terraform/v1.14.x/docs/language/block/resource.mdx +++ b/content/terraform/v1.14.x/docs/language/block/resource.mdx @@ -6,7 +6,9 @@ description: >- # `resource` block reference -The `resource` block defines a piece of infrastructure and specifies the settings for Terraform to create it with. The arguments that an individual resource supports are determined by the provider. Refer to the provider documentation for more information about specific resource configuration. +The `resource` block defines a piece of infrastructure and specifies the settings for Terraform to create it with. Refer to [Create and manage resources](/terraform/language/resources) for more information about using `resource` blocks in your configuration. + +The arguments that an individual resource supports are determined by the provider. Refer to the provider documentation for more information about specific resource configuration. ## Configuration model diff --git a/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/component.mdx b/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/component.mdx index f37cbec8b0..65eecb6fee 100644 --- a/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/component.mdx +++ b/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/component.mdx @@ -5,7 +5,7 @@ description: Use the `component` block to define infrastructure modules in your # `component` block reference -Use the `component` block to source the individual modules that make up your Stack. You can define `component` blocks in a `.tfcomponent.hcl` file, which is a component configuration file for your Stack. Each component represents a reusable piece of infrastructure that you can provision and manage. +Use the `component` block to source the individual modules that make up your Stack. You can define `component` blocks in a `.tfcomponent.hcl` file, which is a component configuration file for your Stack. Each component represents a reusable piece of infrastructure that you can provision and manage. Refer to [Define configuration](/terraform/language/stacks/component/config) for more information. ## Background diff --git a/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/output.mdx b/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/output.mdx index 514f968122..d35d5fa48e 100644 --- a/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/output.mdx +++ b/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/output.mdx @@ -5,7 +5,7 @@ description: Use the `output` block to expose information about your Stack's inf # `output` block reference for component configurations -Use the `output` block in a Stack to expose information about your Stack's infrastructure in the HCP Terraform UI. +Use the `output` block in a Stack to expose information about your Stack's infrastructure in the HCP Terraform UI. Refer to [Define configuration](/terraform/language/stacks/component/config) for more information. ## Background diff --git a/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/provider.mdx b/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/provider.mdx index 31f8d6626d..e3a3e92332 100644 --- a/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/provider.mdx +++ b/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/provider.mdx @@ -5,7 +5,7 @@ description: Use the `provider` block in component configurations to configure p # `provider` block reference for component configurations -Terraform relies on plugins called providers to interact with cloud providers, SaaS providers, and other APIs. Use the `provider` block to configure your Stack's declared providers. +Terraform relies on plugins called providers to interact with cloud providers, SaaS providers, and other APIs. Use the `provider` block to configure your Stack's declared providers. Refer to [Define configuration](/terraform/language/stacks/component/config) for more information. If you are declaring a `provider` block in a traditional Terraform configuration file, ending in `.tf`, refer to the Terraform configuration [`provider` block reference](/terraform/language/block/provider) instead. diff --git a/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/removed.mdx b/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/removed.mdx index c83bc7e0f4..4803e816c7 100644 --- a/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/removed.mdx +++ b/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/removed.mdx @@ -5,7 +5,7 @@ description: Use the `removed` block to systematically remove components from yo # `removed` block reference for component configurations -Use the `removed` block to systematically remove components from your component configuration. Define `removed` blocks in a `.tfcomponent.hcl` file, which is a component configuration file for your Stack. +Use the `removed` block to systematically remove components from your component configuration. Define `removed` blocks in a `.tfcomponent.hcl` file, which is a component configuration file for your Stack. Refer to [Define configuration](/terraform/language/stacks/component/config) for more information. If you are declaring a `removed` block in a traditional Terraform configuration file, ending in `.tf`, refer to the Terraform configuration [`removed` block reference](/terraform/language/block/removed) instead. diff --git a/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/required_providers.mdx b/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/required_providers.mdx index 8f0b30e740..a5b7d71046 100644 --- a/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/required_providers.mdx +++ b/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/required_providers.mdx @@ -5,7 +5,7 @@ description: Use the `required_providers` block to declare which providers your # `required_providers` block reference -Terraform relies on plugins called providers to interact with cloud providers, SaaS providers, and other APIs. Use the `required_providers` block in your component configuration to declare which providers your Stack requires. +Terraform relies on plugins called providers to interact with cloud providers, SaaS providers, and other APIs. Use the `required_providers` block in your component configuration to declare which providers your Stack requires. Refer to [Declare providers](/terraform/language/stacks/component/declare-providers) for more information. If you are declaring a `required_providers` block in a traditional Terraform configuration file, ending in `.tf`, refer to the Terraform configuration [`terraform` block reference](/terraform/language/block/terraform#required_providers) instead. diff --git a/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/variable.mdx b/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/variable.mdx index bf7bfe67ef..ccf688bc5a 100644 --- a/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/variable.mdx +++ b/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/variable.mdx @@ -5,7 +5,7 @@ description: Use the `variable` block to declare input variables for your compon # `variable` block reference for component configurations -Use the `variable` block to declare input variables for your component configuration, making your components dynamic and reusable. +Use the `variable` block to declare input variables for your component configuration, making your components dynamic and reusable. Refer to [Define configuration](/terraform/language/stacks/component/config) for more information. If you are declaring a `variable` block in a traditional Terraform configuration file, ending in `.tf`, refer to the Terraform configuration [`variable` block reference](/terraform/language/block/variable) instead. diff --git a/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/deployment.mdx b/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/deployment.mdx index 8c15b6ace1..7ee1f97dd1 100644 --- a/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/deployment.mdx +++ b/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/deployment.mdx @@ -5,7 +5,7 @@ description: Use the `deployment` block to define how many times you want to dep # `deployment` block reference -Use the `deployment` block to define how many times you want to deploy your Stack's infrastructure. You can define `deployment` blocks in a `.tfdeploy.hcl` file, which is the deployment configuration file for your Stack. +Use the `deployment` block to define how many times you want to deploy your Stack's infrastructure. You can define `deployment` blocks in a `.tfdeploy.hcl` file, which is the deployment configuration file for your Stack. Refer to [Define deployment configuration](/terraform/language/stacks/deploy/config) for more information. ## Background diff --git a/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/deployment_auto_approve.mdx b/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/deployment_auto_approve.mdx index 8c7a72ed52..d4a52b4646 100644 --- a/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/deployment_auto_approve.mdx +++ b/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/deployment_auto_approve.mdx @@ -5,7 +5,7 @@ description: Use the `deployment_auto_approve` block to define rules that automa # `deployment_auto_approve` block reference -Use the `deployment_auto_approve` block to define rules that automatically approve deployment plans based on specific conditions. +Use the `deployment_auto_approve` block to define rules that automatically approve deployment plans based on specific conditions. Refer to [Define deployment configuration](/terraform/language/stacks/deploy/config) for more information. ## Background diff --git a/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/deployment_group.mdx b/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/deployment_group.mdx index 2ad3b593c7..f64c206fde 100644 --- a/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/deployment_group.mdx +++ b/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/deployment_group.mdx @@ -5,7 +5,7 @@ description: Use the `deployment_group` block to configure shared settings and a # `deployment_group` block reference -Use the `deployment_group` block to define a group that can manage deployments and add orchestration rules for those deployments. +Use the `deployment_group` block to define a group that can manage deployments and add orchestration rules for those deployments. Refer to [Set conditions for deployment runs](/terraform/language/stacks/deploy/conditions) for more information. ## Background diff --git a/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/identity_token.mdx b/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/identity_token.mdx index ef079820f9..663b033403 100644 --- a/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/identity_token.mdx +++ b/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/identity_token.mdx @@ -5,7 +5,7 @@ description: Use the `identity_token` block to define JSON Web Tokens (JWT) that # `identity_token` block reference -Use the `identity_token` block to define JSON Web Tokens (JWT) that Terraform generates for OIDC authentication with cloud providers and other services. +Use the `identity_token` block to define JSON Web Tokens (JWT) that Terraform generates for OIDC authentication with cloud providers and other services. Refer to [Authenticate a Stack](/terraform/language/stacks/deploy/authenticate) for more information. ## Background diff --git a/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/publish_output.mdx b/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/publish_output.mdx index 36db997f24..b9f0544a6e 100644 --- a/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/publish_output.mdx +++ b/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/publish_output.mdx @@ -5,7 +5,7 @@ description: Use the `publish_output` block to export values from your Stack to # `publish_output` block reference -Use the `publish_output` block to export values from your Stack to another Stack in the same project. +Use the `publish_output` block to export values from your Stack to another Stack in the same project. Refer to [Pass data from one Stack to another](/terraform/language/stacks/deploy/pass-data) for more information. ## Background diff --git a/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/store.mdx b/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/store.mdx index 9d760a9e40..5a840a13aa 100644 --- a/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/store.mdx +++ b/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/store.mdx @@ -5,7 +5,7 @@ description: Use the `store` block to access the values of HCP Terraform variabl # `store` block reference -Use the `store` block to access the values of HCP Terraform variable sets in your deployment configuration and use those secrets in deployments. +Use the `store` block to access the values of HCP Terraform variable sets in your deployment configuration and use those secrets in deployments. Refer to [Define deployment configuration](/terraform/language/stacks/deploy/config) for more information. ## Background diff --git a/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/upstream_input.mdx b/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/upstream_input.mdx index f0844cba83..70c35127fa 100644 --- a/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/upstream_input.mdx +++ b/content/terraform/v1.14.x/docs/language/block/stack/tfdeploy/upstream_input.mdx @@ -5,7 +5,7 @@ description: Use the `upstream_input` block to consume outputs from another Stac # `upstream_input` block reference -Use the `upstream_input` block to consume outputs from another Stack in the same project to use them in your current Stack. +Use the `upstream_input` block to consume outputs from another Stack in the same project to use them in your current Stack. Refer to [Pass data from one Stack to another](/terraform/language/stacks/deploy/pass-data) for more information. ## Background diff --git a/content/terraform/v1.14.x/docs/language/block/terraform.mdx b/content/terraform/v1.14.x/docs/language/block/terraform.mdx index 8954290776..83c1c96eae 100644 --- a/content/terraform/v1.14.x/docs/language/block/terraform.mdx +++ b/content/terraform/v1.14.x/docs/language/block/terraform.mdx @@ -6,7 +6,11 @@ description: >- # `terraform` block reference -This topic provides reference information about the `terraform` block. The `terraform` block allows you to configure Terraform behavior, including the Terraform version, backend, integration with HCP Terraform, and required providers. +This topic provides reference information about the `terraform` block. The `terraform` block allows you to configure Terraform behavior, including the Terraform version, backend, integration with HCP Terraform, and required providers. Refer to the following topics for more information about configuring the `terraform` block: + +- [Provider requirements](/terraform/language/providers/requirements) +- [Backend block configuration](/terraform/language/backend) +- [Connect to HCP Terraform](/terraform/cli/cloud/settings) ## Configuration model diff --git a/content/terraform/v1.14.x/docs/language/block/variable.mdx b/content/terraform/v1.14.x/docs/language/block/variable.mdx index e9d2848c93..f7f2707159 100644 --- a/content/terraform/v1.14.x/docs/language/block/variable.mdx +++ b/content/terraform/v1.14.x/docs/language/block/variable.mdx @@ -5,9 +5,7 @@ description: Use variables to parameterize your configuration, making your modul # `variable` block reference -Use the `variable` block to parameterize your configuration so that module consumers can pass custom values into the configuration at runtime. - -> **Hands-on:** Try the [Customize Terraform Configuration with Variables](/terraform/tutorials/configuration-language/variables) tutorial. +Use the `variable` block to parameterize your configuration so that module consumers can pass custom values into the configuration at runtime. To learn more about the different ways to use and set values for variables, refer to [Use variables to input module arguments](/terraform/language/values/variables). ## Background @@ -17,7 +15,7 @@ You can define variables in root modules, or in child modules: - In the root modules, you can set variable values using CLI options, environment variables, variable definition files, or through an HCP Terraform workspace. - In child modules, the parent module passes values to child modules as arguments to the `module` block. -To learn more about the different ways to use and set values for variables, refer to [Use variables to input module arguments](/terraform/language/values/variables). +> **Hands-on:** Try the [Customize Terraform Configuration with Variables](/terraform/tutorials/configuration-language/variables) tutorial. ## Configuration model diff --git a/content/terraform/v1.14.x/docs/language/post-apply-operations.mdx b/content/terraform/v1.14.x/docs/language/post-apply-operations.mdx new file mode 100644 index 0000000000..492fb2edae --- /dev/null +++ b/content/terraform/v1.14.x/docs/language/post-apply-operations.mdx @@ -0,0 +1,114 @@ +--- +page_title: Perform post-apply operations using provisioners +description: Learn how to run commands and scripts and upload files to prepare resources for service after applying the configuration with provisioners, config-init, and configuration management software. +--- + +# Perform post-apply operations + +You may need to upload files, run commands and scripts, and perform other operations to prepare resources you create and manage with Terraform for service. Terraform is primarily designed for immutable infrastructure operations, so we strongly recommend using purpose-built solutions to perform post-apply operations. + +> **Hands-on:** Try the [Provision Infrastructure with Cloud-Init](/terraform/tutorials/provision/cloud-init) tutorial. + +## Overview + +You can use the following methods to prepare a resource for service after applying the configuration: + +- Pass data to the resource using the provider's `cloud-init` implementation. +- Use the `cloudinit-config` data source. +- Provision machine images with the necessary tools and packages. +- Use configuration management tools. + +The provider may support post-apply operations, such as runing CLI commands and scripts on the resource. Refer to the resource provider documentation for instructions. If the provider does not include a mechanism for interacting with the resource, we recommend opening a feature request ticket with the provider. When you are unable to use a purpose-built solution, you can use functionality built into Terraform called [provisioners](/terraform/language/provisioners). + +## Requirements + +If you are using third-party software to set resources up for service, such as configuration management or automation software, refer to your vendor's documentation for specific requirements. + +## Pass data into compute resources + +When deploying virtual machines or other similar compute resources, you can pass data to the resource. Most cloud computing platforms provide mechanisms to pass data to instances at the time of their creation. This makes the data immediately available on system boot. + +### Cloud-init + +Many Linux distribution disk images include [cloud-init](https://cloudinit.readthedocs.io/en/latest/), which lets you run scripts and configure systems on system boot up. Some providers let you configure cloud-init on the virtual machine's guest operating system. For providers that support cloud-init, the `user_data` and `custom_data` arguments are common methods for passing data. Refer to the provider documentation for details. + +In the following example, the `custom_data` argument in the `azurerm_linux_virtual_machine` resource specifies a file containing the data to pass to the resource on startup: + +```hcl +resource "azurerm_linux_virtual_machine" "example" { + # . . . + custom_data = base64encode(file("custom-data.sh")) +} +``` + +If you build custom machine images, you may be able to access the data passed to the resource using `user_data` or `metadata` at runtime. Refer to your vendor's documentation for more information. + +This approach is required when you use your cloud provider to automatically launch and destroy servers in a group because individual servers will launch unattended when Terraform is not available to provision them. + +Even if you're deploying individual servers directly with Terraform, using `user_data` or `metadata` to pass data allows for faster boot times. It also simplifies deployment by avoiding the need for direct network access from Terraform to the new server and for remote access credentials to be provided. + +### Input arguments + +Refer to the following provider resources for instructions on how to pass data to respective compute resources. Note that you can also specify cloud-config files as values. You can use the `cloudinit_config` data source to render cloud-config files. Refer to the [cloudinit_config documentation](https://registry.terraform.io/providers/hashicorp/cloudinit/latest/docs/data-sources/config) for more information. + +| Cloud service | Argument | Resource type | +| --- | --- | --- | +| Alibaba Cloud | `user_data` | [`alicloud_instance`](https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/instance), [`alicloud_launch_template`](https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/launch_template) | +| Amazon EC2 | `user_data`, `user_data_base64` | [`aws_instance`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance), [`aws_launch_template`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template), [`aws_launch_configuration`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_configuration) | +| Amazon Lightsail | `user_data` | [`aws_lightsail_instance`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lightsail_instance) | +| Microsoft Azure | `custom_data` | [`azurerm_virtual_machine`](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/virtual_machine), [`azurerm_virtual_machine_scale_set`](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/virtual_machine_scale_set) | +| Google Cloud Platform | `metadata` | [`google_compute_instance`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_instance), [`google_compute_instance_group`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_instance_group) | +| Oracle Cloud Infrastructure | `metadata`, `extended_metadata` | [`oci_core_instance`](https://registry.terraform.io/providers/oracle/oci/), [`oci_core_instance_configuration`](https://registry.terraform.io/providers/oracle/oci/) | +| VMware vSphere | `cdrom` block | Attach a virtual CDROM to [`vsphere_virtual_machine`](https://registry.terraform.io/providers/hashicorp/vsphere/latest/docs/resources/virtual_machine) using the `cdrom` block and specify a file called `user-data.txt` | + +## Use the `cloud-config` data source to pass data + +You can add the [`cloudinit_config`](https://registry.terraform.io/providers/hashicorp/cloudinit/latest/docs) data source to your Terraform configuration and specify the files you want to provision as `text/cloud-config` content. The `cloudinit_config` data source renders multi-part MIME configurations for use with [cloud-init](https://cloudinit.readthedocs.io/en/latest/). Pass the files in the `content` field as YAML-encoded configurations using the `write_files` block. + +In the following example, the `my_cloud_config` data source specifies a `text/cloud-config` MIME part named `cloud.conf`. The `part.content` field is set to [`yamlencode`](/terraform/language/functions/yamlencode), which encodes the `write_files` JSON object as YAML so that the system can provision the referenced files. + +```hcl +data "cloudinit_config" "my_cloud_config" { + gzip = false + base64_encode = false + + part { + content_type = "text/cloud-config" + filename = "cloud.conf" + content = yamlencode( + { + "write_files" : [ + { + "path" : "/etc/foo.conf", + "content" : "foo contents", + }, + { + "path" : "/etc/bar.conf", + "content" : file("bar.conf"), + }, + { + "path" : "/etc/baz.conf", + "content" : templatefile("baz.tpl.conf", { SOME_VAR = "qux" }), + }, + ], + } + ) + } +} +``` + +## Build configuration into machine images + +You can use [HashiCorp Packer](/packer) or similar systems to build system configuration steps into custom images. Packer uses configuration management provisioners that can run installation steps during the build process before creating a system disk image that you can reuse. + +Configuration management software that uses a centralized server component may require you to register the software as part of the configuration process. You must delay the registration step until the final system is booted from your custom image. You can [pass the necessary information to the resource](#pass-data-into-compute-resources) to delay registration so that the configuration management software can register itself with the centralized server immediately on boot without requiring the resource to accept commands from Terraform over SSH or WinRM. + +> **Hands-on:** Try the [Provision Infrastructure with Packer](/terraform/tutorials/provision/packer) tutorial. + +## Run CLI commands + +The provider may support executing CLI commands on the resource. Refer to the resource provider documentation for instructions on how to invoke the CLI on your target system. If the provider does not include a mechanism for interacting with the resource CLI, we recommend opening a feature request ticket with the provider. + +## Execute remote scripts + +If the provider does not include a mechanism for executing scripts, we recommend opening a feature request ticket with the provider. \ No newline at end of file diff --git a/content/terraform/v1.14.x/docs/language/provisioners.mdx b/content/terraform/v1.14.x/docs/language/provisioners.mdx index 169ce1fbef..4eabaa5298 100644 --- a/content/terraform/v1.14.x/docs/language/provisioners.mdx +++ b/content/terraform/v1.14.x/docs/language/provisioners.mdx @@ -3,203 +3,36 @@ page_title: Perform post-apply operations using provisioners description: Learn how to run commands and scripts and upload files to prepare resources for service after applying the configuration with provisioners, config-init, and configuration management software. --- -# Perform post-apply operations +# Use provisioners to perform post-apply operations -You may need to upload files, run commands and scripts, and perform other operations to prepare resources you create and manage with Terraform for service. Terraform is primarily designed for immutable infrastructure operations, so we strongly recommend using purpose-built solutions to perform post-apply operations. When you are unable to use a purpose-built solution, you can use functionality built into Terraform called provisioners. +You may need to upload files, run commands and scripts, and perform other operations to prepare resources you create and manage with Terraform for service. -> **Hands-on:** Try the [Provision Infrastructure Deployed with Terraform](/terraform/tutorials/provision?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials to learn how to use provisioners. - -## Overview + -You can use the following methods to prepare a resource for service after applying the configuration: +Terraform is primarily designed for immutable infrastructure operations, so we strongly recommend using purpose-built solutions to [perform post-apply operations](/terraform/language/post-apply-operations). When you are unable to use a purpose-built solution, you can use functionality built into Terraform called provisioners. -- Pass data to the resource using the provider's `cloud-init` implementation. -- Use the `cloudinit-config` data source. -- Provision machine images with the necessary tools and packages. -- Use configuration management tools. -- Use provisioners built into Terraform. + -You should exercise extreme caution when using provisioners. Terraform cannot predictably model provisioner behaviors represented in the configuration. Additionally, most provisioners require direct network access to your servers and credentials to install and configure external software, which introduces complexity and potential security issues. +## Overview -## Requirements +Before using a provisioner, you should check with your provider for instructions on how to perform post-apply operations, such as executing CLI commands and scripts on your target system. If the provider does not include a mechanism for interacting with the resource CLI, we recommend opening a feature request ticket with the provider. Refer to [Perform post-apply operations](/terraform/language/post-apply-operations) for more information. -If you are using third-party software to set resources up for service, such as configuration management or automation software, refer to your vendor's documentation for specific requirements. +Terraform includes several built-in provisioners for helping you prepare resources for service when you cannot use machine images or configuration management. You should exhaust all alternatives before using provisioners in your configurations. This is because Terraform cannot predictably model provisioner behaviors represented in the configuration. Additionally, most provisioners require direct network access to your servers and credentials to install and configure external software, which introduces complexity and potential security issues. -### Provisioner requirements +## Requirements - Terraform v0.9 is required to use provisioners. - Terraform v1.10 and later is required to use ephemeral values in `provisioner` and `connection` blocks. - Many provisioners require access to the remote resource. Refer to [Connect to remote resources](#connect-to-remote-resources) for instructions on configuring connection settings. - To use provisioners that upload files over SSH, the `scp` service program must be installed on the remote system. -## Pass data into compute resources - -When deploying virtual machines or other similar compute resources, you can pass data to the resource. Most cloud computing platforms provide mechanisms to pass data to instances at the time of their creation. This makes the data immediately available on system boot. - -### Cloud-init - -Many Linux distribution disk images include [cloud-init](https://cloudinit.readthedocs.io/en/latest/), which lets you run scripts and configure systems on system boot up. Some providers let you configure cloud-init on the virtual machine's guest operating system. For providers that support cloud-init, the `user_data` and `custom_data` arguments are common methods for passing data. Refer to the provider documentation for details. - -In the following example, the `custom_data` argument in the `azurerm_linux_virtual_machine` resource specifies a file containing the data to pass to the resource on startup: - -```hcl -resource "azurerm_linux_virtual_machine" "example" { - # . . . - custom_data = base64encode(file("custom-data.sh")) -} -``` - -If you build custom machine images, you may be able to access the data passed to the resource using `user_data` or `metadata` at runtime. Refer to your vendor's documentation for more information. - -This approach is required when you use your cloud provider to automatically launch and destroy servers in a group because individual servers will launch unattended when Terraform is not available to provision them. - -Even if you're deploying individual servers directly with Terraform, using `user_data` or `metadata` to pass data allows for faster boot times. It also simplifies deployment by avoiding the need for direct network access from Terraform to the new server and for remote access credentials to be provided. - -### Input arguments - -Refer to the following provider resources for instructions on how to pass data to respective compute resources. Note that you can also specify cloud-config files as values. You can use the `cloudinit_config` data source to render cloud-config files. Refer to the [cloudinit_config documentation](https://registry.terraform.io/providers/hashicorp/cloudinit/latest/docs/data-sources/config) for more information. - -| Cloud service | Argument | Resource type | -| --- | --- | --- | -| Alibaba Cloud | `user_data` | [`alicloud_instance`](https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/instance), [`alicloud_launch_template`](https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/launch_template) | -| Amazon EC2 | `user_data`, `user_data_base64` | [`aws_instance`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance), [`aws_launch_template`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template), [`aws_launch_configuration`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_configuration) | -| Amazon Lightsail | `user_data` | [`aws_lightsail_instance`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lightsail_instance) | -| Microsoft Azure | `custom_data` | [`azurerm_virtual_machine`](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/virtual_machine), [`azurerm_virtual_machine_scale_set`](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/virtual_machine_scale_set) | -| Google Cloud Platform | `metadata` | [`google_compute_instance`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_instance), [`google_compute_instance_group`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_instance_group) | -| Oracle Cloud Infrastructure | `metadata`, `extended_metadata` | [`oci_core_instance`](https://registry.terraform.io/providers/oracle/oci/), [`oci_core_instance_configuration`](https://registry.terraform.io/providers/oracle/oci/) | -| VMware vSphere | `cdrom` block | Attach a virtual CDROM to [`vsphere_virtual_machine`](https://registry.terraform.io/providers/hashicorp/vsphere/latest/docs/resources/virtual_machine) using the `cdrom` block and specify a file called `user-data.txt` | - -> **Hands-on:** Try the [Provision Infrastructure with Cloud-Init](/terraform/tutorials/provision/cloud-init) tutorial. - -## Use the `cloud-config` data source to pass data - -You can add the [`cloudinit_config`](https://registry.terraform.io/providers/hashicorp/cloudinit/latest/docs) data source to your Terraform configuration and specify the files you want to provision as `text/cloud-config` content. The `cloudinit_config` data source renders multi-part MIME configurations for use with [cloud-init](https://cloudinit.readthedocs.io/en/latest/). Pass the files in the `content` field as YAML-encoded configurations using the `write_files` block. - -In the following example, the `my_cloud_config` data source specifies a `text/cloud-config` MIME part named `cloud.conf`. The `part.content` field is set to [`yamlencode`](/terraform/language/functions/yamlencode), which encodes the `write_files` JSON object as YAML so that the system can provision the referenced files. - -```hcl -data "cloudinit_config" "my_cloud_config" { - gzip = false - base64_encode = false - - part { - content_type = "text/cloud-config" - filename = "cloud.conf" - content = yamlencode( - { - "write_files" : [ - { - "path" : "/etc/foo.conf", - "content" : "foo contents", - }, - { - "path" : "/etc/bar.conf", - "content" : file("bar.conf"), - }, - { - "path" : "/etc/baz.conf", - "content" : templatefile("baz.tpl.conf", { SOME_VAR = "qux" }), - }, - ], - } - ) - } -} -``` - -## Build configuration into machine images - -You can use [HashiCorp Packer](/packer) or similar systems to build system configuration steps into custom images. Packer uses configuration management provisioners that can run installation steps during the build process before creating a system disk image that you can reuse. - -Configuration management software that uses a centralized server component may require you to register the software as part of the configuration process. You must delay the registration step until the final system is booted from your custom image. You can [pass the necessary information to the resource](#pass-data-into-compute-resources) to delay registration so that the configuration management software can register itself with the centralized server immediately on boot without requiring the resource to accept commands from Terraform over SSH or WinRM. - -> **Hands-on:** Try the [Provision Infrastructure with Packer](/terraform/tutorials/provision/packer) tutorial. - -## Run CLI commands - -The provider may support executing CLI commands on the resource. Refer to the resource provider documentation for instructions on how to invoke the CLI on your target system. If the provider does not include a mechanism for interacting with the resource CLI, we recommend opening a feature request ticket with the provider. - -As a workaround, you can use a Terraform provisioner to run commands on the machine where Terraform or on a remote resource. Refer to [Use a provisioner](#use-a-provisioner) for instructions on adding provisioners to the resource configuration. - -### Commands on the local machine - -To run commands on the machine where Terraform is installed, add the `provisioner "local-exec"` block to your `resource` block and specify commands to run in the `command` argument. The following example configures an `aws_instance` resource named `web` to run a local command that prints its IP address: - -```hcl -resource "aws_instance" "web" { - # ... - - provisioner "local-exec" { - command = "echo The server's IP address is ${self.private_ip}" - } -} -``` - -Refer to the [`provisioner` block reference](/terraform/language/block/resource#provisioner) for details about the available arguments. - -### Commands on a remote resource - -To run commands on a remote resource, add the `remote-exec` provisioner type. This provisioner lets you run the CLI for your target system in order to create, update, or otherwise interact with remote objects in that system. You must include [a `connection` block](/terraform/language/block/resource#connection) for Terraform to connect to the server. - -## Execute remote scripts - - If the provider does not include a mechanism for executing scripts, we recommend opening a feature request ticket with the provider. - -As a workaround, you can use a Terraform provisioner to execute scripts. Refer to [Use a provisioner](#use-a-provisioner) for instructions on adding provisioners to the resource configuration. - -When provisioners execute scripts on a remote system over SSH, they usually upload the script file to the remote system then use the default shell to execute it. Provisioners use this strategy because it allows you to use all of the typical scripting techniques supported by that shell, including preserving environment variable values and other context between script statements. - -### Remote system paths - -Terraform requires a suitable location in the remote filesystem where the provisioner can create the script file. By default, Terraform chooses a path containing a random number using the following patterns depending on how `target_platform` is set: - -- `"unix"`: `/tmp/terraform_%RAND%.sh` -- `"windows"`: `C:/windows/temp/terraform_%RAND%.cmd` - -In both cases, the provisioner replaces the sequence `%RAND%` with randomly-chosen decimal digits. - -Provisioners cannot react directly to remote environment variables, such as `TMPDIR`, or use functions such as `mktemp` because they run on the system where Terraform is running, not on the remote system. As a result, you can configure the `script_path` argument in your `connection` block to override the path when your remote system doesn't use the filesystem layout expected by these default paths. - -```hcl -connection { - # ... - script_path = "H:/terraform-temp/script_%RAND%.sh" -} -``` - -Provisioners replace the `%RAND%` sequence with randomly-selected decimal digits to reduce the likelihood of collisions between multiple provisioners running concurrently. - -For Windows systems, we recommend using forward slashes instead of backslashes, despite the typical convention on Windows, because the Terraform language uses backslash as the quoted string escape character. - -### Execute scripts using SCP over SSH - - - -When using Terraform v1.0 and earlier, avoid using untrusted external values as part of the `script_path` argument. - - - -Provisioners pass the specified script path, after `%RAND%` expansion, directly to the remote `scp` process, which interprets the path. With the default configuration of `scp` as distributed with OpenSSH, you can place temporary scripts in the home directory of the remote user by specifying a relative path: - -```hcl -connection { - type = "ssh" - # ... - script_path = "terraform_provisioner_%RAND%.sh" -} -``` - -## Use a provisioner - -Terraform includes several built-in provisioners for helping you prepare resources for service when you cannot use machine images or configuration management. You should exhaust all alternatives before using provisioners in your configurations. - -### Add a provisioner to your resource +## Add a provisioner to your resource Add one or more `provisioner ""` blocks to the `resource` block you want to perform operations on. You can specify the following types: - - `file`: Copies files or directories from the machine where Terraform is running to the new resource. - - `local-exec`: Invokes an executable on the local machine after Terraform creates the resource. - - `remote-exec`: Invokes an executable on the remote resource after Terraform creates the resource. +- `file`: Copies files or directories from the machine where Terraform is running to the new resource. +- `local-exec`: Invokes an executable on the local machine after Terraform creates the resource. Refer to [Run commands on the local machine](#run-commands-on-the-local-machine) for more information. +- `remote-exec`: Invokes an executable on the remote resource after Terraform creates the resource. Refer to [Run commands on a remote resource](#run-commands-on-a-remote-resource) for more information. For details about each provisioner type and its arguments, refer to the [`provisioner` block reference](/terraform/language/block/resource#provisioner). @@ -288,11 +121,75 @@ Expressions in `provisioner` blocks and `connection` blocks cannot refer to thei You must use the `self` object to reference the resource because using references in the configuration creates dependencies, and referring to a resource by name within its own block would create a dependency cycle. +## Run commands on the local machine + +To run commands on the machine where Terraform is installed, add the `provisioner "local-exec"` block to your `resource` block and specify commands to run in the `command` argument. The following example configures an `aws_instance` resource named `web` to run a local command that prints its IP address: + +```hcl +resource "aws_instance" "web" { + # ... + + provisioner "local-exec" { + command = "echo The server's IP address is ${self.private_ip}" + } +} +``` + +Refer to the [`provisioner` block reference](/terraform/language/block/resource#provisioner) for details about the available arguments. + +## Run commands on a remote resource + +To run commands on a remote resource, add the `remote-exec` provisioner type. This provisioner lets you run the CLI for your target system in order to create, update, or otherwise interact with remote objects in that system. You must include [a `connection` block](/terraform/language/block/resource#connection) for Terraform to connect to the server. + +## Execute remote scripts + +When provisioners execute scripts on a remote system over SSH, they usually upload the script file to the remote system then use the default shell to execute it. Provisioners use this strategy because it allows you to use all of the typical scripting techniques supported by that shell, including preserving environment variable values and other context between script statements. + +### Remote system paths + +Terraform requires a suitable location in the remote filesystem where the provisioner can create the script file. By default, Terraform chooses a path containing a random number using the following patterns depending on how `target_platform` is set: + +- `"unix"`: `/tmp/terraform_%RAND%.sh` +- `"windows"`: `C:/windows/temp/terraform_%RAND%.cmd` + +In both cases, the provisioner replaces the sequence `%RAND%` with randomly-chosen decimal digits. + +Provisioners cannot react directly to remote environment variables, such as `TMPDIR`, or use functions such as `mktemp` because they run on the system where Terraform is running, not on the remote system. As a result, you can configure the `script_path` argument in your `connection` block to override the path when your remote system doesn't use the filesystem layout expected by these default paths. + +```hcl +connection { + # ... + script_path = "H:/terraform-temp/script_%RAND%.sh" +} +``` + +Provisioners replace the `%RAND%` sequence with randomly-selected decimal digits to reduce the likelihood of collisions between multiple provisioners running concurrently. + +For Windows systems, we recommend using forward slashes instead of backslashes, despite the typical convention on Windows, because the Terraform language uses backslash as the quoted string escape character. + +### Execute scripts using SCP over SSH + + + +When using Terraform v1.0 and earlier, avoid using untrusted external values as part of the `script_path` argument. + + + +Provisioners pass the specified script path, after `%RAND%` expansion, directly to the remote `scp` process, which interprets the path. With the default configuration of `scp` as distributed with OpenSSH, you can place temporary scripts in the home directory of the remote user by specifying a relative path: + +```hcl +connection { + type = "ssh" + # ... + script_path = "terraform_provisioner_%RAND%.sh" +} +``` + ## Sensitive values You can use sensitive values in `provisioner` blocks. Terraform suppresses sensitive values in all log output. Refer to [Manage sensitive data](/terraform/language/manage-sensitive-data) for more information about using sensitive values in your configurations. -### Ephemeral values +## Ephemeral values You can use ephemeral values in `provisioner` blocks and `connection` blocks that enable provisioners to connect to remote resources. Terraform does not store ephemeral values in your plan or state or output them in logs. Refer to the following topics for more information about using ephemeral values in your configurations: @@ -300,7 +197,7 @@ You can use ephemeral values in `provisioner` blocks and `connection` blocks tha - [`ephemeral` variables](/terraform/language/block/variable#ephemeral) - [`ephemeral` output values](/terraform/language/block/output#ephemeral) -### Determine when provisioners perform tasks +## Determine when provisioners perform tasks By default, Terraform runs provisioners immediately after it finishes creating the resource, but you can set the `when` argument a Terraform stage control when provisioners perform their configured actions. @@ -330,7 +227,7 @@ Destroy provisioners run before the resource is destroyed. If the provisioner fa Enabling the [`create_before_destroy` argument](/terraform/language/block/resource#create_before_destroy) on the resource prevents destroy-time provisioners from running. -#### Remove a `resource` block containing a destroy-time provisioner +### Remove a `resource` block containing a destroy-time provisioner Destroy-time provisioners can only run if they remain in the configuration at the time a resource is destroyed. If a `resource` block with a destroy-time provisioner is removed entirely from the configuration, its provisioner configurations are removed along with it. The destroy provisioner won't run as a result. To work around this, configure a multi-step process to safely remove a resource with a destroy-time provisioner: @@ -341,11 +238,11 @@ Destroy-time provisioners can only run if they remain in the configuration at th Because of this limitation, you should use destroy-time provisioners sparingly and with care. -#### Tainted resources +### Tainted resources A destroy-time provisioner within a resource that is tainted will not run. This includes resources that are marked tainted from a failed creation-time provisioner or tainted manually using `terraform taint`. -### Configure multiple provisioners +## Configure multiple provisioners You can specify multiple provisioners within a `resource` block. Terraform executes provisioners in the order they are defined in the configuration file. @@ -367,7 +264,7 @@ resource "aws_instance" "web" { } ``` -### Configure provisioner failure behavior +## Configure provisioner failure behavior By default, provisioners that fail also cause the `terraform apply` command to fail. To configure Terraform to continue its operation, set the `on_failure` argument to `continue`. Terraform ignores the error and continues the operation. Refer to the [`on_failure` argument reference](/terraform/language/block/resource#define-provisioner-failure-behaviors) for more information. @@ -384,7 +281,7 @@ resource "aws_instance" "web" { } ``` -### Install third-party provisioners +## Install third-party provisioners We recommend using only provisioners built into Terraform, but you can use third-party provisioners as plugins when no other alternative is available. Place third-party provisioners into the `%APPDATA%\terraform.d\plugins` directory, `~/.terraform.d/plugins` directory, or in the directory where the Terraform binary is installed.