Unverified Commit 65e293c5 authored by Laura Pacilio's avatar Laura Pacilio Committed by GitHub
Browse files

Merge pull request #31790 from hashicorp/backport/remove-provisioners/readily-correct-ferret

Backport of Remove legacy provisioners from docs into v1.3
parents d848737b f30a1719
Showing with 3 additions and 483 deletions
+3 -483
......@@ -92,23 +92,6 @@
{
"title": "remote-exec",
"path": "resources/provisioners/remote-exec"
},
{ "divider": true },
{
"title": "chef",
"path": "resources/provisioners/chef"
},
{
"title": "habitat",
"path": "resources/provisioners/habitat"
},
{
"title": "puppet",
"path": "resources/provisioners/puppet"
},
{
"title": "salt-masterless",
"path": "resources/provisioners/salt-masterless"
}
]
}
......
---
page_title: 'Provisioner: chef'
description: >-
The `chef` provisioner installs, configures and runs the Chef client on a
resource.
---
# Chef Provisioner
The `chef` provisioner installs, configures and runs the Chef Client on a remote
resource. The `chef` provisioner supports both `ssh` and `winrm` type
[connections](/language/resources/provisioners/connection).
!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most situations. Refer to
[Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
## Requirements
The `chef` provisioner has some prerequisites for specific connection types:
* For `ssh` type connections, `cURL` must be available on the remote host.
* For `winrm` connections, `PowerShell 2.0` must be available on the remote host.
[Chef end user license agreement](https://www.chef.io/end-user-license-agreement/) must be accepted by setting `chef_license` to `accept` in `client_options` argument unless you are installing an old version of Chef client.
Without these prerequisites, your provisioning execution will fail.
## Example usage
```hcl
resource "aws_instance" "web" {
# ...
provisioner "chef" {
attributes_json = <<EOF
{
"key": "value",
"app": {
"cluster1": {
"nodes": [
"webserver1",
"webserver2"
]
}
}
}
EOF
environment = "_default"
client_options = ["chef_license 'accept'"]
run_list = ["cookbook::recipe"]
node_name = "webserver1"
secret_key = "${file("../encrypted_data_bag_secret")}"
server_url = "https://chef.company.com/organizations/org1"
recreate_client = true
user_name = "bork"
user_key = "${file("../bork.pem")}"
version = "15.10.13"
# If you have a self signed cert on your chef server change this to :verify_none
ssl_verify_mode = ":verify_peer"
}
}
```
## Argument Reference
The following arguments are supported:
* `attributes_json (string)` - (Optional) A raw JSON string with initial node attributes
for the new node. These can also be loaded from a file on disk using
[the `file` function](/language/functions/file).
* `channel (string)` - (Optional) The Chef Client release channel to install from. If not
set, the `stable` channel will be used.
* `client_options (array)` - (Optional) A list of optional Chef Client configuration
options. See the [Chef Client ](https://docs.chef.io/config_rb_client.html) documentation
for all available options.
* `disable_reporting (boolean)` - (Optional) If `true` the Chef Client will not try to send
reporting data (used by Chef Reporting) to the Chef Server (defaults to `false`).
* `environment (string)` - (Optional) The Chef environment the new node will be joining
(defaults to `_default`).
* `fetch_chef_certificates (boolean)` (Optional) If `true` the SSL certificates configured
on your Chef Server will be fetched and trusted. See the knife [ssl_fetch](https://docs.chef.io/knife_ssl_fetch.html)
documentation for more details.
* `log_to_file (boolean)` - (Optional) If `true`, the output of the initial Chef Client run
will be logged to a local file instead of the console. The file will be created in a
subdirectory called `logfiles` created in your current directory. The filename will be
the `node_name` of the new node.
* `use_policyfile (boolean)` - (Optional) If `true`, use the policy files to bootstrap the
node. Setting `policy_group` and `policy_name` are required if this is `true`. (defaults to
`false`).
* `policy_group (string)` - (Optional) The name of a policy group that exists on the Chef
server. Required if `use_policyfile` is set; `policy_name` must also be specified.
* `policy_name (string)` - (Optional) The name of a policy, as identified by the `name`
setting in a Policyfile.rb file. Required if `use_policyfile` is set; `policy_group`
must also be specified.
* `http_proxy (string)` - (Optional) The proxy server for Chef Client HTTP connections.
* `https_proxy (string)` - (Optional) The proxy server for Chef Client HTTPS connections.
* `max_retries (integer)` - (Optional) The number of times to retry the provisioning process
after receiving an exit code in the `retry_on_error` list. Defaults to `0`
* `named_run_list (string)` - (Optional) The name of an alternate run-list to invoke during the
initial Chef Client run. The run-list must already exist in the Policyfile that defines
`policy_name`. Only applies when `use_policyfile` is `true`.
* `no_proxy (array)` - (Optional) A list of URLs that should bypass the proxy.
* `node_name (string)` - (Required) The name of the node to register with the Chef Server.
* `ohai_hints (array)` - (Optional) A list with
[Ohai hints](https://docs.chef.io/ohai.html#hints) to upload to the node.
* `os_type (string)` - (Optional) The OS type of the node. Valid options are: `linux` and
`windows`. If not supplied, the connection type will be used to determine the OS type (`ssh`
will assume `linux` and `winrm` will assume `windows`).
* `prevent_sudo (boolean)` - (Optional) Prevent the use of the `sudo` command while installing, configuring
and running the initial Chef Client run. This option is only used with `ssh` type
[connections](/language/resources/provisioners/connection).
* `recreate_client (boolean)` - (Optional) If `true`, first delete any existing Chef Node and
Client before registering the new Chef Client.
* `retry_on_error (array)` - (Optional) The error codes upon which Terraform should
gracefully retry the provisioning process. Intended for use with
[Chef RFC062 codes](https://github.com/chef-boneyard/chef-rfc/blob/master/rfc062-exit-status.md).
(Defaults to `[35, 37, 213]`)
* `run_list (array)` - (Optional) A list with recipes that will be invoked during the initial
Chef Client run. The run-list will also be saved to the Chef Server after a successful
initial run. Required if `use_policyfile` is `false`; ignored when `use_policyfile` is `true`
(see `named_run_list` to specify a run-list defined in a Policyfile).
* `secret_key (string)` - (Optional) The contents of the secret key that is used
by the Chef Client to decrypt data bags on the Chef Server. The key will be uploaded to the remote
machine. This can also be loaded from a file on disk using
[the `file` function](/language/functions/file).
* `server_url (string)` - (Required) The URL to the Chef server. This includes the path to
the organization. See the example.
* `skip_install (boolean)` - (Optional) Skip the installation of Chef Client on the remote
machine. This assumes Chef Client is already installed when you run the `chef`
provisioner.
* `skip_register (boolean)` - (Optional) Skip the registration of Chef Client on the remote
machine. This assumes Chef Client is already registered and the private key (`client.pem`)
is available in the default Chef configuration directory when you run the `chef`
provisioner.
* `ssl_verify_mode (string)` - (Optional) Used to set the verify mode for Chef Client HTTPS
requests. The options are `:verify_none`, or `:verify_peer` which is default.
* `user_name (string)` - (Required) The name of an existing Chef user to register
the new Chef Client and optionally configure Chef Vaults.
* `user_key (string)` - (Required) The contents of the user key that will be used to
authenticate with the Chef Server. This can also be loaded from a file on disk using
[the `file` function](/language/functions/file).
* `vault_json (string)` - (Optional) A raw JSON string with Chef Vaults and Items to which the new node
should have access. These can also be loaded from a file on disk using
[the `file` function](/language/functions/file).
* `version (string)` - (Optional) The Chef Client version to install on the remote machine.
If not set, the latest available version will be installed.
* `wait_for_retry (integer)` - (Optional) - Amount of time in seconds to wait before
retrying the provisionining process after receiving an exit code in the `retry_on_error`
list. Defaults to `30`.
---
page_title: 'Provisioner: habitat'
description: >-
The `habitat` provisioner installs the Habitat supervisor, and loads
configured services.
---
# Habitat Provisioner
The `habitat` provisioner installs the [Habitat](https://habitat.sh) supervisor and loads configured services. This provisioner only supports Linux targets using the `ssh` connection type at this time.
!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most situations. Refer to
[Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
## Requirements
The `habitat` provisioner has some prerequisites for specific connection types:
* For `ssh` type connections, we assume a few tools to be available on the remote host:
* `curl`
* `tee`
* `setsid` - Only if using the `unmanaged` service type.
Without these prerequisites, your provisioning execution will fail.
## Example usage
```hcl
resource "aws_instance" "redis" {
count = 3
provisioner "habitat" {
peers = [aws_instance.redis[0].private_ip]
use_sudo = true
service_type = "systemd"
accept_license = true
service {
name = "core/redis"
topology = "leader"
user_toml = file("conf/redis.toml")
}
}
}
```
## Argument Reference
There are 2 configuration levels, `supervisor` and `service`. Configuration placed directly within the `provisioner` block are supervisor configurations, and a provisioner can define zero or more services to run, and each service will have a `service` block within the `provisioner`. A `service` block can also contain zero or more `bind` blocks to create service group bindings.
### Supervisor Arguments
* `accept_license (bool)` - (Required) Set to true to accept [Habitat end user license agreement](https://www.chef.io/end-user-license-agreement/)
* `version (string)` - (Optional) The Habitat version to install on the remote machine. If not specified, the latest available version is used.
* `auto_update (bool)` - (Optional) If set to `true`, the supervisor will auto-update itself as soon as new releases are available on the specified `channel`.
* `http_disable (bool)` - (Optional) If set to `true`, disables the supervisor HTTP listener entirely.
* `peer (string)` - (Optional, deprecated) IP addresses or FQDN's for other Habitat supervisors to peer with, like: `--peer 1.2.3.4 --peer 5.6.7.8`. (Defaults to none)
* `peers (array)` - (Optional) A list of IP or FQDN's of other supervisor instance(s) to peer with. (Defaults to none)
* `service_type (string)` - (Optional) Method used to run the Habitat supervisor. Valid options are `unmanaged` and `systemd`. (Defaults to `systemd`)
* `service_name (string)` - (Optional) The name of the Habitat supervisor service, if using an init system such as `systemd`. (Defaults to `hab-supervisor`)
* `use_sudo (bool)` - (Optional) Use `sudo` when executing remote commands. Required when the user specified in the `connection` block is not `root`. (Defaults to `true`)
* `permanent_peer (bool)` - (Optional) Marks this supervisor as a permanent peer. (Defaults to false)
* `listen_ctl (string)` - (Optional) The listen address for the countrol gateway system (Defaults to 127.0.0.1:9632)
* `listen_gossip (string)` - (Optional) The listen address for the gossip system (Defaults to 0.0.0.0:9638)
* `listen_http (string)` - (Optional) The listen address for the HTTP gateway (Defaults to 0.0.0.0:9631)
* `ring_key (string)` - (Optional) The name of the ring key for encrypting gossip ring communication (Defaults to no encryption)
* `ring_key_content (string)` - (Optional) The key content. Only needed if using ring encryption and want the provisioner to take care of uploading and importing it. Easiest to source from a file (eg `ring_key_content = "${file("conf/foo-123456789.sym.key")}"`) (Defaults to none)
* `ctl_secret (string)` - (Optional) Specify a secret to use (from `hab sup secret generate`) for control gateway communication between hab client(s) and the supervisor. (Defaults to none)
* `url (string)` - (Optional) The URL of a Builder service to download packages and receive updates from. (Defaults to <https://bldr.habitat.sh>)
* `channel (string)` - (Optional) The release channel in the Builder service to use. (Defaults to `stable`)
* `events (string)` - (Optional) Name of the service group running a Habitat EventSrv to forward Supervisor and service event data to. (Defaults to none)
* `organization (string)` - (Optional) The organization that the Supervisor and it's subsequent services are part of. (Defaults to `default`)
* `gateway_auth_token (string)` - (Optional) The http gateway authorization token (Defaults to none)
* `builder_auth_token (string)` - (Optional) The builder authorization token when using a private origin. (Defaults to none)
### Service Arguments
* `name (string)` - (Required) The Habitat package identifier of the service to run. (ie `core/haproxy` or `core/redis/3.2.4/20171002182640`)
* `binds (array)` - (Optional) An array of bind specifications. (ie `binds = ["backend:nginx.default"]`)
* `bind` - (Optional) An alternative way of declaring binds. This method can be easier to deal with when populating values from other values or variable inputs without having to do string interpolation. The following example is equivalent to `binds = ["backend:nginx.default"]`:
```hcl
bind {
alias = "backend"
service = "nginx"
group = "default"
}
```
* `topology (string)` - (Optional) Topology to start service in. Possible values `standalone` or `leader`. (Defaults to `standalone`)
* `strategy (string)` - (Optional) Update strategy to use. Possible values `at-once`, `rolling` or `none`. (Defaults to `none`)
* `user_toml (string)` - (Optional) TOML formatted user configuration for the service. Easiest to source from a file (eg `user_toml = "${file("conf/redis.toml")}"`). (Defaults to none)
* `channel (string)` - (Optional) The release channel in the Builder service to use. (Defaults to `stable`)
* `group (string)` - (Optional) The service group to join. (Defaults to `default`)
* `url (string)` - (Optional) The URL of a Builder service to download packages and receive updates from. (Defaults to <https://bldr.habitat.sh>)
* `application (string)` - (Optional) The application name. (Defaults to none)
* `environment (string)` - (Optional) The environment name. (Defaults to none)
* `service_key (string)` - (Optional) The key content of a service private key, if using service group encryption. Easiest to source from a file (eg `service_key = "${file("conf/redis.default@org-123456789.box.key")}"`) (Defaults to none)
---
page_title: 'Provisioner: puppet'
description: >-
The `puppet` provisioner installs, configures and runs the Puppet agent on a
resource.
---
# Puppet Provisioner
The `puppet` provisioner installs, configures and runs the Puppet agent on a
remote resource. The `puppet` provisioner supports both `ssh` and `winrm` type
[connections](/language/resources/provisioners/connection).
!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most situations. Refer to
[Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
## Requirements
The `puppet` provisioner has some prerequisites for specific connection types:
* For `ssh` type connections, `cURL` must be available on the remote host.
* For `winrm` connections, `PowerShell 2.0` must be available on the remote host.
Without these prerequisites, your provisioning execution will fail.
Additionally, the `puppet` provisioner requires
[Bolt](https://puppet.com/docs/bolt/latest/bolt.html) to be installed on your workstation
with the following [modules
installed](https://puppet.com/docs/bolt/latest/bolt_installing_modules.html#install-modules)
* `danieldreier/autosign`
* `puppetlabs/puppet_agent`
## Example usage
```hcl
resource "aws_instance" "web" {
# ...
provisioner "puppet" {
server = aws_instance.puppetmaster.public_dns
server_user = "ubuntu"
extension_requests = {
pp_role = "webserver"
}
}
}
```
## Argument Reference
The following arguments are supported:
* `server (string)` - (Required) The FQDN of the Puppet master that the agent
is to connect to.
* `server_user (string)` - (Optional) The user that Bolt should connect to the
server as (defaults to `root`).
* `os_type (string)` - (Optional) The OS type of the resource. Valid options
are: `linux` and `windows`. If not supplied, the connection type will be used
to determine the OS type (`ssh` will assume `linux` and `winrm` will assume
`windows`).
* `use_sudo (boolean)` - (Optional) If `true`, commands run on the resource
will have their privileges elevated with sudo (defaults to `true` when the OS
type is `linux` and `false` when the OS type is `windows`).
* `autosign (boolean)` - (Optional) Set to `true` if the Puppet master is using an autosigner such as
[Daniel Dreier's policy-based autosigning
tool](https://danieldreier.github.io/autosign). If `false` new agent certificate requests will have to be signed manually (defaults to `true`).
* `open_source (boolean)` - (Optional) If `true` the provisioner uses an open source Puppet compatible agent install method (push via the Bolt agent install task). If `false` the simplified Puppet Enterprise installer will pull the agent from the Puppet master (defaults to `true`).
* `certname (string)` - (Optional) The Subject CN used when requesting
a certificate from the Puppet master CA (defaults to the FQDN of the
resource).
* `extension_requests (map)` - (Optional) A map of [extension
requests](https://puppet.com/docs/puppet/latest/ssl_attributes_extensions.html#concept-932)
to be embedded in the certificate signing request before it is sent to the
Puppet master CA and then transferred to the final certificate when the CSR
is signed. These become available during Puppet agent runs as [trusted facts](https://puppet.com/docs/puppet/latest/lang_facts_and_builtin_vars.html#trusted-facts). Friendly names for common extensions such as pp_role and pp_environment have [been predefined](https://puppet.com/docs/puppet/latest/ssl_attributes_extensions.html#recommended-oids-for-extensions).
* `custom_attributes (map)` - (Optional) A map of [custom
attributes](https://puppet.com/docs/puppet/latest/ssl_attributes_extensions.html#concept-5488)
to be embedded in the certificate signing request before it is sent to the
Puppet master CA.
* `environment (string)` - (Optional) The name of the Puppet environment that the
Puppet agent will be running in (defaults to `production`).
* `bolt_timeout (string)` - (Optional) The timeout to wait for Bolt tasks to
complete. This should be specified as a string like `30s` or `5m` (defaults
to `5m` - 5 minutes).
---
page_title: 'Provisioner: salt-masterless'
description: >-
The salt-masterless Terraform provisioner provisions machines built by
Terraform
---
# Salt Masterless Provisioner
Type: `salt-masterless`
The `salt-masterless` Terraform provisioner provisions machines built by Terraform
using [Salt](http://saltstack.com/) states, without connecting to a Salt master. The `salt-masterless` provisioner supports `ssh` [connections](/language/resources/provisioners/connection).
!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most situations. Refer to
[Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
## Requirements
The `salt-masterless` provisioner has some prerequisites. `cURL` must be available on the remote host.
## Example usage
The example below is fully functional.
```hcl
provisioner "salt-masterless" {
"local_state_tree" = "/srv/salt"
}
```
## Argument Reference
The reference of available configuration options is listed below. The only
required argument is the path to your local salt state tree.
Optional:
- `bootstrap_args` (string) - Arguments to send to the bootstrap script. Usage
is somewhat documented on
[github](https://github.com/saltstack/salt-bootstrap), but the [script
itself](https://github.com/saltstack/salt-bootstrap/blob/develop/bootstrap-salt.sh)
has more detailed usage instructions. By default, no arguments are sent to
the script.
- `disable_sudo` (boolean) - By default, the bootstrap install command is prefixed with `sudo`. When using a
Docker builder, you will likely want to pass `true` since `sudo` is often not pre-installed.
- `remote_pillar_roots` (string) - The path to your remote [pillar
roots](https://docs.saltproject.io/en/latest/ref/configuration/master.html#pillar-configuration).
default: `/srv/pillar`. This option cannot be used with `minion_config`.
- `remote_state_tree` (string) - The path to your remote [state
tree](https://docs.saltproject.io/en/latest/ref/states/highstate.html#the-salt-state-tree).
default: `/srv/salt`. This option cannot be used with `minion_config`.
- `local_pillar_roots` (string) - The path to your local [pillar
roots](https://docs.saltproject.io/en/latest/ref/configuration/master.html#pillar-configuration).
This will be uploaded to the `remote_pillar_roots` on the remote.
- `local_state_tree` (string) - The path to your local [state
tree](https://docs.saltproject.io/en/latest/ref/states/highstate.html#the-salt-state-tree).
This will be uploaded to the `remote_state_tree` on the remote.
- `custom_state` (string) - A state to be run instead of `state.highstate`.
Defaults to `state.highstate` if unspecified.
- `minion_config_file` (string) - The path to your local [minion config
file](https://docs.saltproject.io/en/latest/ref/configuration/minion.html). This will be uploaded to the `/etc/salt` on the remote. This option overrides the `remote_state_tree` or `remote_pillar_roots` options.
- `skip_bootstrap` (boolean) - By default the salt provisioner runs [salt
bootstrap](https://github.com/saltstack/salt-bootstrap) to install salt. Set
this to true to skip this step.
- `temp_config_dir` (string) - Where your local state tree will be copied
before moving to the `/srv/salt` directory. Default is `/tmp/salt`.
- `no_exit_on_failure` (boolean) - Terraform will exit if the `salt-call` command
fails. Set this option to true to ignore Salt failures.
- `log_level` (string) - Set the logging level for the `salt-call` run.
- `salt_call_args` (string) - Additional arguments to pass directly to `salt-call`. See
[salt-call](https://docs.saltproject.io/en/latest/ref/cli/salt-call.html) documentation for more
information. By default no additional arguments (besides the ones Terraform generates)
are passed to `salt-call`.
- `salt_bin_dir` (string) - Path to the `salt-call` executable. Useful if it is not
on the PATH.
......@@ -7,10 +7,12 @@ description: >-
# Provisioners
Provisioners can be used to model specific actions on the local machine or on
You can use provisioners to model specific actions on the local machine or on
a remote machine in order to prepare servers or other infrastructure objects
for service.
-> **Note:** We removed the Chef, Habitat, Puppet, and Salt Masterless provisioners in Terraform v0.15.0. Information about these legacy provisioners is still available in the documentation for [Terraform v1.1 (and earlier)](/language/v1.1.x/resources/provisioners/syntax).
## Provisioners are a Last Resort
> **Hands-on:** To learn about more declarative ways to handle provisioning actions, try the [Provision Infrastructure Deployed with Terraform](https://learn.hashicorp.com/collections/terraform/provision?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment