125 lines
4.0 KiB
Markdown
125 lines
4.0 KiB
Markdown
---
|
|
description: 'The converge Packer provisioner uses Converge modules to provision the machine.'
|
|
layout: docs
|
|
page_title: 'Converge - Provisioners'
|
|
sidebar_current: 'docs-provisioners-converge'
|
|
---
|
|
|
|
# Converge Provisioner
|
|
|
|
Type: `converge`
|
|
|
|
The [Converge](http://converge.aster.is) Packer provisioner uses Converge
|
|
modules to provision the machine. It uploads module directories to use as
|
|
source, or you can use remote modules.
|
|
|
|
The provisioner can optionally bootstrap the Converge client/server binary onto
|
|
new images.
|
|
|
|
## Basic Example
|
|
|
|
The example below is fully functional.
|
|
|
|
``` json
|
|
{
|
|
"type": "converge",
|
|
"module": "https://raw.githubusercontent.com/asteris-llc/converge/master/samples/fileContent.hcl",
|
|
"params": {
|
|
"message": "Hello, Packer!"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Configuration Reference
|
|
|
|
The reference of available configuration options is listed below. The only
|
|
required element is "module". Every other option is optional.
|
|
|
|
- `module` (string) - Path (or URL) to the root module that Converge will
|
|
apply.
|
|
|
|
Optional parameters:
|
|
|
|
- `bootstrap` (boolean, defaults to false) - Set to allow the provisioner to
|
|
download the latest Converge bootstrap script and the specified `version`
|
|
of Converge from the internet.
|
|
|
|
- `version` (string) - Set to a [released Converge
|
|
version](https://github.com/asteris-llc/converge/releases) for bootstrap.
|
|
|
|
- `module_dirs` (array of directory specifications) - Module directories to
|
|
transfer to the remote host for execution. See below for the specification.
|
|
|
|
- `working_directory` (string) - The directory that Converge will change to
|
|
before execution.
|
|
|
|
- `params` (maps of string to string) - parameters to pass into the root
|
|
module.
|
|
|
|
- `execute_command` (string) - the command used to execute Converge. This has
|
|
various [configuration template variables](/docs/templates/engine.html)
|
|
available.
|
|
|
|
- `prevent_sudo` (boolean) - stop Converge from running with administrator
|
|
privileges via sudo
|
|
|
|
- `bootstrap_command` (string) - the command used to bootstrap Converge. This
|
|
has various [configuration template variables](/docs/templates/engine.html)
|
|
available.
|
|
|
|
- `prevent_bootstrap_sudo` (boolean) - stop Converge from bootstrapping with
|
|
administrator privileges via sudo
|
|
|
|
### Module Directories
|
|
|
|
The provisioner can transfer module directories to the remote host for
|
|
provisioning. Of these fields, `source` and `destination` are required in every
|
|
directory.
|
|
|
|
- `source` (string) - the path to the folder on the local machine.
|
|
|
|
- `destination` (string) - the path to the folder on the remote machine.
|
|
Parent directories will not be created; use the shell module to do this.
|
|
|
|
- `exclude` (array of string) - files and directories to exclude from
|
|
transfer.
|
|
|
|
### Execute Command
|
|
|
|
By default, Packer uses the following command (broken across multiple lines for
|
|
readability) to execute Converge:
|
|
|
|
``` liquid
|
|
cd {{.WorkingDirectory}} && \
|
|
{{if .Sudo}}sudo {{end}}converge apply \
|
|
--local \
|
|
--log-level=WARNING \
|
|
--paramsJSON '{{.ParamsJSON}}' \
|
|
{{.Module}}
|
|
```
|
|
|
|
This command can be customized using the `execute_command` configuration. As
|
|
you can see from the default value above, the value of this configuration can
|
|
contain various template variables:
|
|
|
|
- `WorkingDirectory` - `directory` from the configuration.
|
|
- `Sudo` - the opposite of `prevent_sudo` from the configuration.
|
|
- `ParamsJSON` - The unquoted JSONified form of `params` from the
|
|
configuration.
|
|
- `Module` - `module` from the configuration.
|
|
|
|
### Bootstrap Command
|
|
|
|
By default, Packer uses the following command to bootstrap Converge:
|
|
|
|
``` liquid
|
|
curl -s https://get.converge.sh | {{if .Sudo}}sudo {{end}}sh {{if ne .Version ""}}-s -- -v {{.Version}}{{end}}
|
|
```
|
|
|
|
This command can be customized using the `bootstrap_command` configuration. As
|
|
you can see from the default values above, the value of this configuration can
|
|
contain various template variables:
|
|
|
|
- `Sudo` - the opposite of `prevent_bootstrap_sudo` from the configuration.
|
|
- `Version` - `version` from the configuration.
|