exoscale

README

Packer Builder plugin: Exoscale

The exoscale builder plugin can be used with HashiCorp Packer to create a new instance template from a Compute instance volume snapshot. This plugin creates a Compute instance in your Exoscale organization, logs into it via SSH to execute configured provisioners and then snapshots the storage volume of the instance to register a custom template from the exported snapshot.

Note: the exoscale Packer builder only supports UNIX-like operating systems (e.g. GNU/Linux, *BSD...). To build Exoscale custom templates for other OS, we recommend using the QEMU builder combined with the exoscale-import Packer post-processor plugin.

Installation

Using pre-built releases

You can find pre-built releases of the plugin here. Once you have downloaded the latest archive corresponding to your target OS, uncompress it to retrieve the packer-builder-exoscale plugin binary file. To install the plugin, please follow the official Packer documentation on installing a plugin.

From Sources

If you prefer to build the plugin from sources, clone the GitHub repository locally and run the command make build from the root of the sources directory. Upon successful compilation, a packer-builder-exoscale plugin binary file can be found in the bin/ directory. To install the plugin, please follow the official Packer documentation on installing a plugin.

Configuration

Here is the list of supported configuration parameters by the builder.

Required parameters

• api_key (string) - The API key used to communicate with Exoscale services.

• api_secret (string) - The API secret used to communicate with Exoscale services.

• instance_template (string) - The name of the template to use when creating the Compute instance.

• template_zone (string) - The Exoscale zone in which to create the template.

• template_name (string) - The name of the template.

Optional parameters

• api_endpoint (string) - The API endpoint used to communicate with the Exoscale API. Defaults to https://api.exoscale.com/v1.

• instance_type (string) - The instance type of the Compute instance. Defaults to Medium.

• instance_name (string) - The name of the Compute instance. Defaults to packer-<BUILD ID>.

• instance_zone (string) - The Exoscale zone in which to create the Compute instance. Defaults to the value of template_zone.

• instance_template_filter (string) - The template filter to specify for the instance_template parameter. Defaults to featured.

• instance_disk_size (int) - Volume disk size in GB of the Compute instance to create. Defaults to 50.

• instance_security_groups (list of strings) - List of Security Groups (names) to apply to the Compute instance. Defaults to ["default"].

• instance_private_networks (list of strings) - List of Private Networks (names) to attach to the Compute instance.

• instance_ssh_key (string) - Name of the Exoscale SSH key to use with the Compute instance. If unset, a throwaway SSH key named packer-<BUILD ID> will be created before creating the instance, and destroyed after a successful build.

• template_description (string) - The description of the template.

• template_username (string) - An optional username to be used to log into Compute instances using this template.

• template_boot_mode (string) - The template boot mode. Supported values: legacy (default), uefi.

• template_disable_password (boolean) - Whether the template should disable Compute instance password reset. Defaults to false.

• template_disable_sshkey (boolean) - Whether the template should disable SSH key installation during Compute instance creation. Defaults to false.

In addition to plugin-specific configuration parameters, you can also adjust the SSH communicator settings to configure how Packer will log into the Compute instance.

Usage

Here is an example of a simple Packer configuration using the exoscale builder:

{
  "variables": {
    "api_key": "{{env `EXOSCALE_API_KEY`}}",
    "api_secret": "{{env `EXOSCALE_API_SECRET`}}"
  },

  "builders": [{
    "type": "exoscale",
    "api_key": "{{user `api_key`}}",
    "api_secret": "{{user `api_secret`}}",
    "instance_template": "Linux Ubuntu 20.04 LTS 64-bit",
    "template_zone": "ch-gva-2",
    "template_name": "my-app",
    "template_username": "ubuntu",
    "ssh_username": "ubuntu"
  }],

  "provisioners": [{
    "type": "shell",
    "execute_command": "chmod +x {{.Path}}; sudo {{.Path}}",
    "scripts": ["install.sh"] 
  }]
}

The same configuration in HCL format (only with Packer >= 1.5.0):

variable "api_key" { default = "" }
variable "api_secret" { default = "" }

source "exoscale" "my-app" {
  api_key = var.api_key
  api_secret = var.api_secret
  instance_template = "Linux Ubuntu 20.04 LTS 64-bit"
  instance_security_group = "packer"
  template_zone = "ch-gva-2"
  template_name = "my-app"
  template_username = "ubuntu"
  ssh_username = "ubuntu"
}

build {
  sources = ["source.exoscale.test"]

  provisioner "shell" {
    execute_command = "chmod +x {{.Path}}; sudo {{.Path}}"
    scripts = ["install.sh"]
  }
}

To build your template using Packer, run the following command:

$ packer build my-app.pkr.hcl
exoscale: output will be in this color.

==> exoscale: Build ID: brjpaeh8d3b2liin7pm0
==> exoscale: Creating Compute instance
==> exoscale: Using ssh communicator to connect: 159.100.242.23
==> exoscale: Waiting for SSH to become available...
==> exoscale: Connected to SSH!
==> exoscale: Provisioning with shell script: install.sh
==> exoscale: Stopping Compute instance
==> exoscale: Creating Compute instance snapshot
==> exoscale: Exporting Compute instance snapshot
==> exoscale: Registering Compute instance template
==> exoscale: Destroying Compute instance template
Build 'exoscale' finished.

==> Builds finished. The artifacts of successful builds are:
--> exoscale: my-app @ ch-gva-2 (423e0bda-f127-417e-9c10-4e412d596478)

$ exo vm template show 423e0bda-f127-417e-9c10-4e412d596478
  ┼───────────────┼──────────────────────────────────────┼
  │   TEMPLATE    │                                      │
  ┼───────────────┼──────────────────────────────────────┼
  │ ID            │ 423e0bda-f127-417e-9c10-4e412d596478 │
  │ Name          │ my-app                               │
  │ OS Type       │ Other (64-bit)                       │
  │ Creation Date │ 2020-06-15T17:40:27+0200             │
  │ Zone          │ ch-gva-2                             │
  │ Disk Size     │ 50 GiB                               │
  │ Username      │ ubuntu                               │
  │ Password?     │ true                                 │
  ┼───────────────┼──────────────────────────────────────┼

Contributing

• If you think you've found a bug in the code or you have a question regarding the usage of this software, please reach out to us by opening an issue in this GitHub repository.
• Contributions to this project are welcome: if you want to add a feature or a fix a bug, please do so by opening a Pull Request in this GitHub repository. In case of feature contribution, we kindly ask you to open an issue to discuss it beforehand.

Documentation

Overview

Code generated by "mapstructure-to-hcl2 -type Config"; DO NOT EDIT.

Index

• Constants
• type Artifact
  • func (a *Artifact) BuilderId() string
  • func (a *Artifact) Destroy() error
  • func (a *Artifact) Files() []string
  • func (a *Artifact) Id() string
  • func (a *Artifact) State(name string) interface{}
  • func (a *Artifact) String() string
• type Builder
  • func (b *Builder) ConfigSpec() hcldec.ObjectSpec
  • func (b *Builder) Prepare(raws ...interface{}) ([]string, []string, error)
  • func (b *Builder) Run(ctx context.Context, ui packer.Ui, hook packer.Hook) (packer.Artifact, error)
• type Config
  • func NewConfig(raws ...interface{}) (*Config, error)
  • func (*Config) FlatMapstructure() interface{ ... }
• type FlatConfig
  • func (*FlatConfig) HCL2Spec() map[string]hcldec.Spec

Constants

const BuilderId = "packer.builder.exoscale"

Types

type Artifact

type Artifact struct {
	StateData map[string]interface{}
	// contains filtered or unexported fields
}

func (*Artifact) BuilderId

func (a *Artifact) BuilderId() string

func (*Artifact) Destroy

func (a *Artifact) Destroy() error

func (*Artifact) Files

func (a *Artifact) Files() []string

func (*Artifact) Id

func (a *Artifact) Id() string

func (*Artifact) State

func (a *Artifact) State(name string) interface{}

func (*Artifact) String

func (a *Artifact) String() string

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

func (*Builder) ConfigSpec

func (b *Builder) ConfigSpec() hcldec.ObjectSpec

func (*Builder) Prepare

func (b *Builder) Prepare(raws ...interface{}) ([]string, []string, error)

func (*Builder) Run

func (b *Builder) Run(ctx context.Context, ui packer.Ui, hook packer.Hook) (packer.Artifact, error)

type Config

type Config struct {
	common.PackerConfig `mapstructure:",squash"`
	Comm                communicator.Config `mapstructure:",squash"`

	APIEndpoint             string   `mapstructure:"api_endpoint"`
	APIKey                  string   `mapstructure:"api_key"`
	APISecret               string   `mapstructure:"api_secret"`
	InstanceName            string   `mapstructure:"instance_name"`
	InstanceZone            string   `mapstructure:"instance_zone"`
	InstanceTemplate        string   `mapstructure:"instance_template"`
	InstanceTemplateFilter  string   `mapstructure:"instance_template_filter"`
	InstanceType            string   `mapstructure:"instance_type"`
	InstanceDiskSize        int64    `mapstructure:"instance_disk_size"`
	InstanceSecurityGroups  []string `mapstructure:"instance_security_groups"`
	InstancePrivateNetworks []string `mapstructure:"instance_private_networks"`
	InstanceSSHKey          string   `mapstructure:"instance_ssh_key"`
	TemplateZone            string   `mapstructure:"template_zone"`
	TemplateName            string   `mapstructure:"template_name"`
	TemplateDescription     string   `mapstructure:"template_description"`
	TemplateUsername        string   `mapstructure:"template_username"`
	TemplateBootMode        string   `mapstructure:"template_boot_mode"`
	TemplateDisablePassword bool     `mapstructure:"template_disable_password"`
	TemplateDisableSSHKey   bool     `mapstructure:"template_disable_sshkey"`
	// contains filtered or unexported fields
}

func NewConfig

func NewConfig(raws ...interface{}) (*Config, error)

func (*Config) FlatMapstructure

func (*Config) FlatMapstructure() interface{ HCL2Spec() map[string]hcldec.Spec }

FlatMapstructure returns a new FlatConfig. FlatConfig is an auto-generated flat version of Config. Where the contents a fields with a `mapstructure:,squash` tag are bubbled up.

type FlatConfig

type FlatConfig struct {
	PackerBuildName           *string           `mapstructure:"packer_build_name" cty:"packer_build_name"`
	PackerBuilderType         *string           `mapstructure:"packer_builder_type" cty:"packer_builder_type"`
	PackerDebug               *bool             `mapstructure:"packer_debug" cty:"packer_debug"`
	PackerForce               *bool             `mapstructure:"packer_force" cty:"packer_force"`
	PackerOnError             *string           `mapstructure:"packer_on_error" cty:"packer_on_error"`
	PackerUserVars            map[string]string `mapstructure:"packer_user_variables" cty:"packer_user_variables"`
	PackerSensitiveVars       []string          `mapstructure:"packer_sensitive_variables" cty:"packer_sensitive_variables"`
	Type                      *string           `mapstructure:"communicator" cty:"communicator"`
	PauseBeforeConnect        *string           `mapstructure:"pause_before_connecting" cty:"pause_before_connecting"`
	SSHHost                   *string           `mapstructure:"ssh_host" cty:"ssh_host"`
	SSHPort                   *int              `mapstructure:"ssh_port" cty:"ssh_port"`
	SSHUsername               *string           `mapstructure:"ssh_username" cty:"ssh_username"`
	SSHPassword               *string           `mapstructure:"ssh_password" cty:"ssh_password"`
	SSHKeyPairName            *string           `mapstructure:"ssh_keypair_name" cty:"ssh_keypair_name"`
	SSHTemporaryKeyPairName   *string           `mapstructure:"temporary_key_pair_name" cty:"temporary_key_pair_name"`
	SSHClearAuthorizedKeys    *bool             `mapstructure:"ssh_clear_authorized_keys" cty:"ssh_clear_authorized_keys"`
	SSHPrivateKeyFile         *string           `mapstructure:"ssh_private_key_file" cty:"ssh_private_key_file"`
	SSHPty                    *bool             `mapstructure:"ssh_pty" cty:"ssh_pty"`
	SSHTimeout                *string           `mapstructure:"ssh_timeout" cty:"ssh_timeout"`
	SSHWaitTimeout            *string           `mapstructure:"ssh_wait_timeout" undocumented:"true" cty:"ssh_wait_timeout"`
	SSHAgentAuth              *bool             `mapstructure:"ssh_agent_auth" cty:"ssh_agent_auth"`
	SSHDisableAgentForwarding *bool             `mapstructure:"ssh_disable_agent_forwarding" cty:"ssh_disable_agent_forwarding"`
	SSHHandshakeAttempts      *int              `mapstructure:"ssh_handshake_attempts" cty:"ssh_handshake_attempts"`
	SSHBastionHost            *string           `mapstructure:"ssh_bastion_host" cty:"ssh_bastion_host"`
	SSHBastionPort            *int              `mapstructure:"ssh_bastion_port" cty:"ssh_bastion_port"`
	SSHBastionAgentAuth       *bool             `mapstructure:"ssh_bastion_agent_auth" cty:"ssh_bastion_agent_auth"`
	SSHBastionUsername        *string           `mapstructure:"ssh_bastion_username" cty:"ssh_bastion_username"`
	SSHBastionPassword        *string           `mapstructure:"ssh_bastion_password" cty:"ssh_bastion_password"`
	SSHBastionInteractive     *bool             `mapstructure:"ssh_bastion_interactive" cty:"ssh_bastion_interactive"`
	SSHBastionPrivateKeyFile  *string           `mapstructure:"ssh_bastion_private_key_file" cty:"ssh_bastion_private_key_file"`
	SSHFileTransferMethod     *string           `mapstructure:"ssh_file_transfer_method" cty:"ssh_file_transfer_method"`
	SSHProxyHost              *string           `mapstructure:"ssh_proxy_host" cty:"ssh_proxy_host"`
	SSHProxyPort              *int              `mapstructure:"ssh_proxy_port" cty:"ssh_proxy_port"`
	SSHProxyUsername          *string           `mapstructure:"ssh_proxy_username" cty:"ssh_proxy_username"`
	SSHProxyPassword          *string           `mapstructure:"ssh_proxy_password" cty:"ssh_proxy_password"`
	SSHKeepAliveInterval      *string           `mapstructure:"ssh_keep_alive_interval" cty:"ssh_keep_alive_interval"`
	SSHReadWriteTimeout       *string           `mapstructure:"ssh_read_write_timeout" cty:"ssh_read_write_timeout"`
	SSHRemoteTunnels          []string          `mapstructure:"ssh_remote_tunnels" cty:"ssh_remote_tunnels"`
	SSHLocalTunnels           []string          `mapstructure:"ssh_local_tunnels" cty:"ssh_local_tunnels"`
	SSHPublicKey              []byte            `mapstructure:"ssh_public_key" cty:"ssh_public_key"`
	SSHPrivateKey             []byte            `mapstructure:"ssh_private_key" cty:"ssh_private_key"`
	WinRMUser                 *string           `mapstructure:"winrm_username" cty:"winrm_username"`
	WinRMPassword             *string           `mapstructure:"winrm_password" cty:"winrm_password"`
	WinRMHost                 *string           `mapstructure:"winrm_host" cty:"winrm_host"`
	WinRMPort                 *int              `mapstructure:"winrm_port" cty:"winrm_port"`
	WinRMTimeout              *string           `mapstructure:"winrm_timeout" cty:"winrm_timeout"`
	WinRMUseSSL               *bool             `mapstructure:"winrm_use_ssl" cty:"winrm_use_ssl"`
	WinRMInsecure             *bool             `mapstructure:"winrm_insecure" cty:"winrm_insecure"`
	WinRMUseNTLM              *bool             `mapstructure:"winrm_use_ntlm" cty:"winrm_use_ntlm"`
	APIEndpoint               *string           `mapstructure:"api_endpoint" cty:"api_endpoint"`
	APIKey                    *string           `mapstructure:"api_key" cty:"api_key"`
	APISecret                 *string           `mapstructure:"api_secret" cty:"api_secret"`
	InstanceName              *string           `mapstructure:"instance_name" cty:"instance_name"`
	InstanceZone              *string           `mapstructure:"instance_zone" cty:"instance_zone"`
	InstanceTemplate          *string           `mapstructure:"instance_template" cty:"instance_template"`
	InstanceTemplateFilter    *string           `mapstructure:"instance_template_filter" cty:"instance_template_filter"`
	InstanceType              *string           `mapstructure:"instance_type" cty:"instance_type"`
	InstanceDiskSize          *int64            `mapstructure:"instance_disk_size" cty:"instance_disk_size"`
	InstanceSecurityGroups    []string          `mapstructure:"instance_security_groups" cty:"instance_security_groups"`
	InstancePrivateNetworks   []string          `mapstructure:"instance_private_networks" cty:"instance_private_networks"`
	InstanceSSHKey            *string           `mapstructure:"instance_ssh_key" cty:"instance_ssh_key"`
	TemplateZone              *string           `mapstructure:"template_zone" cty:"template_zone"`
	TemplateName              *string           `mapstructure:"template_name" cty:"template_name"`
	TemplateDescription       *string           `mapstructure:"template_description" cty:"template_description"`
	TemplateUsername          *string           `mapstructure:"template_username" cty:"template_username"`
	TemplateBootMode          *string           `mapstructure:"template_boot_mode" cty:"template_boot_mode"`
	TemplateDisablePassword   *bool             `mapstructure:"template_disable_password" cty:"template_disable_password"`
	TemplateDisableSSHKey     *bool             `mapstructure:"template_disable_sshkey" cty:"template_disable_sshkey"`
}

FlatConfig is an auto-generated flat version of Config. Where the contents of a field with a `mapstructure:,squash` tag are bubbled up.

func (*FlatConfig) HCL2Spec

func (*FlatConfig) HCL2Spec() map[string]hcldec.Spec

HCL2Spec returns the hcl spec of a Config. This spec is used by HCL to read the fields of Config. The decoded values from this spec will then be applied to a FlatConfig.