»Converge Provisioner

Type: converge

The Converge 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.

{
  "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 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 is a configuration template variables. See below for detailed usage instructions.

  • prevent_sudo (boolean) - stop Converge from running with administrator privileges via sudo

  • bootstrap_command (string) - the command used to bootstrap Converge. This is a template engine. Therefore, you may use user variables and template functions in this field. The following extra variables are also avilable in this engine:

    • Version: The version of Converge to use.
    • Sudo: Boolean; intended to say whether to use sudo or not.

    By default, this is "curl -s https://get.converge.sh | {{if .Sudo}}sudo {{end}}sh {{if ne .Version \"\"}}-s -- -v {{.Version}}{{end}}"

  • prevent_bootstrap_sudo (boolean) - stop Converge from bootstrapping with administrator privileges via sudo

Parameters common to all provisioners:

  • pause_before (duration) - Sleep for duration before execution.

  • max_retries (int) - Max times the provisioner will retry in case of failure. Defaults to zero (0). Zero means an error will not be retried.

  • only (array of string) - Only run the provisioner for listed builder(s) by name.

  • override (object) - Override the builder with different settings for a specific builder, eg :

    {
      "type": "shell",
      "script": "script.sh",
      "override": {
        "vmware-iso": {
          "execute_command": "echo 'password' | sudo -S bash {{.Path}}"
        }
      }
    }
    
  • timeout (duration) - If the provisioner takes more than for example 1h10m1s or 10m to finish, the provisioner will timeout and fail.

»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:

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:

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.