instance

Documentation

Index

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

Constants

const BuilderID = "oxide.instance"

Types

type Artifact

type Artifact struct {
	// Unique identifier of the created image.
	ImageID string
	// Name of the created image.
	ImageName string
	// Unique identifier of the source image used to create this artifact.
	SourceImageID string
	// Additional state data associated with the build.
	StateData map[string]any
}

Artifact represents the Oxide image created by the builder. This artifact contains the image ID and name that can be used to launch new instances.

func (*Artifact) BuilderId

func (*Artifact) BuilderId() string

BuilderId returns the builder ID used to create this artifact.

func (*Artifact) Destroy

func (a *Artifact) Destroy() error

Destroy deletes the artifact when it is determined to no longer be needed.

func (*Artifact) Files

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

Files returns the files associated with the artifact.

func (*Artifact) Id

func (a *Artifact) Id() string

Id returns the unique identifier for this artifact.

func (*Artifact) State

func (a *Artifact) State(name string) any

State returns builder state related to the artifact.

func (*Artifact) String

func (a *Artifact) String() string

String returns a description of the artifact.

type Builder

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

The `oxide-instance` builder creates custom images for use with [Oxide](https://oxide.computer). The builder launches a temporary instance from an existing source image, connects to the instance using its external IP, provisions the instance, and then creates a new image from the instance's boot disk. The resulting image can be used to launch new instances on Oxide.

The builder does not manage images. Once it creates an image, it is up to you to use it or delete it.

func (*Builder) ConfigSpec

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

ConfigSpec returns the HCL configuration specification for the builder.

func (*Builder) Prepare

func (b *Builder) Prepare(args ...any) ([]string, []string, error)

Prepare configures the builder and validates its configuration.

func (*Builder) Run

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

Run executes the builder steps to create an Oxide image.

type Config

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

	// Packer communicator configuration to configure how Packer connects to the
	// instance for provisioning.
	Comm communicator.Config `mapstructure:",squash"`

	// Oxide API URL (e.g., `https://oxide.sys.example.com`). If not specified,
	// this defaults to the value of the `OXIDE_HOST` environment variable. When
	// specified, `token` must be specified. Conflicts with `profile`.
	Host string `mapstructure:"host" required:"false"`

	// Oxide API token. If not specified, this defaults to the value of the
	// `OXIDE_TOKEN` environment variable. When specified, `host` must be specified.
	// Conflicts with `profile`.
	Token string `mapstructure:"token" required:"false"`

	// Oxide credentials profile. If not specified, this defaults to the value of
	// the `OXIDE_PROFILE` environment variable. Conflicts with `host` and `token`.
	Profile string `mapstructure:"profile" required:"false"`

	// Skip TLS certificate verification when connecting to the Oxide API.
	// Defaults to `false`.
	InsecureSkipVerify bool `mapstructure:"insecure_skip_verify" required:"false"`

	// Image ID to use for the instance's boot disk. This can be obtained from the
	// `oxide-image` data source.
	BootDiskImageID string `mapstructure:"boot_disk_image_id" required:"true"`

	// Name or ID of the project where the temporary instance and resulting image
	// will be created.
	Project string `mapstructure:"project" required:"true"`

	// Size of the boot disk in bytes. Defaults to `21474836480`, or 20 GiB.
	BootDiskSize uint64 `mapstructure:"boot_disk_size"`

	// IP pool to allocate the instance's external IP from. If not specified, the
	// silo's default IP pool will be used.
	IPPool string `mapstructure:"ip_pool"`

	// VPC to create the instance within. Defaults to `default`.
	VPC string `mapstructure:"vpc"`

	// Subnet to create the instance within. Defaults to `default`.
	Subnet string `mapstructure:"subnet"`

	// Name of the temporary instance and its boot disk, primary network interface,
	// and snapshot. Defaults to `packer-UUID`, where `UUID` is a unique identifier
	// generated for the current build. This must be unique to prevent Oxide
	// resource name conflicts.
	Name string `mapstructure:"name"`

	// Hostname of the temporary instance. Defaults to the value of `name`.
	Hostname string `mapstructure:"hostname"`

	// Number of vCPUs to provision the instance with. Defaults to `1`.
	CPUs uint64 `mapstructure:"cpus"`

	// Amount of memory to provision the instance with, in bytes. Defaults to
	// `2147483648`, or 2 GiB.
	Memory uint64 `mapstructure:"memory"`

	// An array of names or IDs of SSH public keys to inject into the instance.
	SSHPublicKeys []string `mapstructure:"ssh_public_keys"`

	// Name of the resulting image artifact. Required unless `skip_create_image`
	// is `true`.
	ArtifactName string `mapstructure:"artifact_name" required:"true"`

	// Description of the resulting image artifact. Defaults to a description that
	// identifies the Packer build that created it.
	ArtifactDescription string `mapstructure:"artifact_description"`

	// Operating system of the resulting image artifact. Defaults to the OS of the
	// source image as retrieved from Oxide.
	ArtifactOS string `mapstructure:"artifact_os"`

	// Version of the resulting image artifact. Defaults to the version of the
	// source image as retrieved from Oxide.
	ArtifactVersion string `mapstructure:"artifact_version"`

	// Skip creating the final image. When set to `true`, the build will boot the
	// temporary instance and run all provisioners but will not create a snapshot
	// or image. The temporary instance is still cleaned up normally. This is useful
	// for testing provisioner logic without incurring the cost of image creation.
	// Defaults to `false`.
	SkipCreateImage bool `mapstructure:"skip_create_image" required:"false"`

	// User data for instance initialization systems such as cloud-init. The
	// value is a UTF-8 string and will be Base64-encoded by the plugin before
	// transmission. The maximum size is 32 KiB, measured before encoding. Use
	// Packer's built-in functions such as `file` to read content from disk.
	// Packer does not wait for user data to finish executing before shutting
	// down the instance. If your user data must complete before the image is
	// created, run `cloud-init status --wait` or an equivalent in a
	// provisioner.
	UserData string `mapstructure:"user_data" required:"false"`
	// contains filtered or unexported fields
}

The configuration arguments for the builder. Arguments can either be required or optional.

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.

func (*Config) Prepare

func (c *Config) Prepare(args ...any) ([]string, error)

Prepare decodes the configuration and validates it.

type FlatConfig

type FlatConfig struct {
	PackerBuildName           *string           `mapstructure:"packer_build_name" cty:"packer_build_name" hcl:"packer_build_name"`
	PackerBuilderType         *string           `mapstructure:"packer_builder_type" cty:"packer_builder_type" hcl:"packer_builder_type"`
	PackerCoreVersion         *string           `mapstructure:"packer_core_version" cty:"packer_core_version" hcl:"packer_core_version"`
	PackerDebug               *bool             `mapstructure:"packer_debug" cty:"packer_debug" hcl:"packer_debug"`
	PackerForce               *bool             `mapstructure:"packer_force" cty:"packer_force" hcl:"packer_force"`
	PackerOnError             *string           `mapstructure:"packer_on_error" cty:"packer_on_error" hcl:"packer_on_error"`
	PackerUserVars            map[string]string `mapstructure:"packer_user_variables" cty:"packer_user_variables" hcl:"packer_user_variables"`
	PackerSensitiveVars       []string          `mapstructure:"packer_sensitive_variables" cty:"packer_sensitive_variables" hcl:"packer_sensitive_variables"`
	Type                      *string           `mapstructure:"communicator" cty:"communicator" hcl:"communicator"`
	PauseBeforeConnect        *string           `mapstructure:"pause_before_connecting" cty:"pause_before_connecting" hcl:"pause_before_connecting"`
	SSHHost                   *string           `mapstructure:"ssh_host" cty:"ssh_host" hcl:"ssh_host"`
	SSHPort                   *int              `mapstructure:"ssh_port" cty:"ssh_port" hcl:"ssh_port"`
	SSHUsername               *string           `mapstructure:"ssh_username" cty:"ssh_username" hcl:"ssh_username"`
	SSHPassword               *string           `mapstructure:"ssh_password" cty:"ssh_password" hcl:"ssh_password"`
	SSHKeyPairName            *string           `mapstructure:"ssh_keypair_name" undocumented:"true" cty:"ssh_keypair_name" hcl:"ssh_keypair_name"`
	SSHTemporaryKeyPairName   *string           `mapstructure:"temporary_key_pair_name" undocumented:"true" cty:"temporary_key_pair_name" hcl:"temporary_key_pair_name"`
	SSHTemporaryKeyPairType   *string           `mapstructure:"temporary_key_pair_type" cty:"temporary_key_pair_type" hcl:"temporary_key_pair_type"`
	SSHTemporaryKeyPairBits   *int              `mapstructure:"temporary_key_pair_bits" cty:"temporary_key_pair_bits" hcl:"temporary_key_pair_bits"`
	SSHCiphers                []string          `mapstructure:"ssh_ciphers" cty:"ssh_ciphers" hcl:"ssh_ciphers"`
	SSHClearAuthorizedKeys    *bool             `mapstructure:"ssh_clear_authorized_keys" cty:"ssh_clear_authorized_keys" hcl:"ssh_clear_authorized_keys"`
	SSHKEXAlgos               []string          `mapstructure:"ssh_key_exchange_algorithms" cty:"ssh_key_exchange_algorithms" hcl:"ssh_key_exchange_algorithms"`
	SSHPrivateKeyFile         *string           `mapstructure:"ssh_private_key_file" undocumented:"true" cty:"ssh_private_key_file" hcl:"ssh_private_key_file"`
	SSHCertificateFile        *string           `mapstructure:"ssh_certificate_file" cty:"ssh_certificate_file" hcl:"ssh_certificate_file"`
	SSHPty                    *bool             `mapstructure:"ssh_pty" cty:"ssh_pty" hcl:"ssh_pty"`
	SSHTimeout                *string           `mapstructure:"ssh_timeout" cty:"ssh_timeout" hcl:"ssh_timeout"`
	SSHWaitTimeout            *string           `mapstructure:"ssh_wait_timeout" undocumented:"true" cty:"ssh_wait_timeout" hcl:"ssh_wait_timeout"`
	SSHAgentAuth              *bool             `mapstructure:"ssh_agent_auth" undocumented:"true" cty:"ssh_agent_auth" hcl:"ssh_agent_auth"`
	SSHDisableAgentForwarding *bool             `mapstructure:"ssh_disable_agent_forwarding" cty:"ssh_disable_agent_forwarding" hcl:"ssh_disable_agent_forwarding"`
	SSHHandshakeAttempts      *int              `mapstructure:"ssh_handshake_attempts" cty:"ssh_handshake_attempts" hcl:"ssh_handshake_attempts"`
	SSHBastionHost            *string           `mapstructure:"ssh_bastion_host" cty:"ssh_bastion_host" hcl:"ssh_bastion_host"`
	SSHBastionPort            *int              `mapstructure:"ssh_bastion_port" cty:"ssh_bastion_port" hcl:"ssh_bastion_port"`
	SSHBastionAgentAuth       *bool             `mapstructure:"ssh_bastion_agent_auth" cty:"ssh_bastion_agent_auth" hcl:"ssh_bastion_agent_auth"`
	SSHBastionUsername        *string           `mapstructure:"ssh_bastion_username" cty:"ssh_bastion_username" hcl:"ssh_bastion_username"`
	SSHBastionPassword        *string           `mapstructure:"ssh_bastion_password" cty:"ssh_bastion_password" hcl:"ssh_bastion_password"`
	SSHBastionInteractive     *bool             `mapstructure:"ssh_bastion_interactive" cty:"ssh_bastion_interactive" hcl:"ssh_bastion_interactive"`
	SSHBastionPrivateKeyFile  *string           `mapstructure:"ssh_bastion_private_key_file" cty:"ssh_bastion_private_key_file" hcl:"ssh_bastion_private_key_file"`
	SSHBastionCertificateFile *string           `mapstructure:"ssh_bastion_certificate_file" cty:"ssh_bastion_certificate_file" hcl:"ssh_bastion_certificate_file"`
	SSHFileTransferMethod     *string           `mapstructure:"ssh_file_transfer_method" cty:"ssh_file_transfer_method" hcl:"ssh_file_transfer_method"`
	SSHProxyHost              *string           `mapstructure:"ssh_proxy_host" cty:"ssh_proxy_host" hcl:"ssh_proxy_host"`
	SSHProxyPort              *int              `mapstructure:"ssh_proxy_port" cty:"ssh_proxy_port" hcl:"ssh_proxy_port"`
	SSHProxyUsername          *string           `mapstructure:"ssh_proxy_username" cty:"ssh_proxy_username" hcl:"ssh_proxy_username"`
	SSHProxyPassword          *string           `mapstructure:"ssh_proxy_password" cty:"ssh_proxy_password" hcl:"ssh_proxy_password"`
	SSHKeepAliveInterval      *string           `mapstructure:"ssh_keep_alive_interval" cty:"ssh_keep_alive_interval" hcl:"ssh_keep_alive_interval"`
	SSHReadWriteTimeout       *string           `mapstructure:"ssh_read_write_timeout" cty:"ssh_read_write_timeout" hcl:"ssh_read_write_timeout"`
	SSHRemoteTunnels          []string          `mapstructure:"ssh_remote_tunnels" cty:"ssh_remote_tunnels" hcl:"ssh_remote_tunnels"`
	SSHLocalTunnels           []string          `mapstructure:"ssh_local_tunnels" cty:"ssh_local_tunnels" hcl:"ssh_local_tunnels"`
	SSHPublicKey              []byte            `mapstructure:"ssh_public_key" undocumented:"true" cty:"ssh_public_key" hcl:"ssh_public_key"`
	SSHPrivateKey             []byte            `mapstructure:"ssh_private_key" undocumented:"true" cty:"ssh_private_key" hcl:"ssh_private_key"`
	WinRMUser                 *string           `mapstructure:"winrm_username" cty:"winrm_username" hcl:"winrm_username"`
	WinRMPassword             *string           `mapstructure:"winrm_password" cty:"winrm_password" hcl:"winrm_password"`
	WinRMHost                 *string           `mapstructure:"winrm_host" cty:"winrm_host" hcl:"winrm_host"`
	WinRMNoProxy              *bool             `mapstructure:"winrm_no_proxy" cty:"winrm_no_proxy" hcl:"winrm_no_proxy"`
	WinRMPort                 *int              `mapstructure:"winrm_port" cty:"winrm_port" hcl:"winrm_port"`
	WinRMTimeout              *string           `mapstructure:"winrm_timeout" cty:"winrm_timeout" hcl:"winrm_timeout"`
	WinRMUseSSL               *bool             `mapstructure:"winrm_use_ssl" cty:"winrm_use_ssl" hcl:"winrm_use_ssl"`
	WinRMInsecure             *bool             `mapstructure:"winrm_insecure" cty:"winrm_insecure" hcl:"winrm_insecure"`
	WinRMUseNTLM              *bool             `mapstructure:"winrm_use_ntlm" cty:"winrm_use_ntlm" hcl:"winrm_use_ntlm"`
	Host                      *string           `mapstructure:"host" required:"false" cty:"host" hcl:"host"`
	Token                     *string           `mapstructure:"token" required:"false" cty:"token" hcl:"token"`
	Profile                   *string           `mapstructure:"profile" required:"false" cty:"profile" hcl:"profile"`
	InsecureSkipVerify        *bool             `mapstructure:"insecure_skip_verify" required:"false" cty:"insecure_skip_verify" hcl:"insecure_skip_verify"`
	BootDiskImageID           *string           `mapstructure:"boot_disk_image_id" required:"true" cty:"boot_disk_image_id" hcl:"boot_disk_image_id"`
	Project                   *string           `mapstructure:"project" required:"true" cty:"project" hcl:"project"`
	BootDiskSize              *uint64           `mapstructure:"boot_disk_size" cty:"boot_disk_size" hcl:"boot_disk_size"`
	IPPool                    *string           `mapstructure:"ip_pool" cty:"ip_pool" hcl:"ip_pool"`
	VPC                       *string           `mapstructure:"vpc" cty:"vpc" hcl:"vpc"`
	Subnet                    *string           `mapstructure:"subnet" cty:"subnet" hcl:"subnet"`
	Name                      *string           `mapstructure:"name" cty:"name" hcl:"name"`
	Hostname                  *string           `mapstructure:"hostname" cty:"hostname" hcl:"hostname"`
	CPUs                      *uint64           `mapstructure:"cpus" cty:"cpus" hcl:"cpus"`
	Memory                    *uint64           `mapstructure:"memory" cty:"memory" hcl:"memory"`
	SSHPublicKeys             []string          `mapstructure:"ssh_public_keys" cty:"ssh_public_keys" hcl:"ssh_public_keys"`
	ArtifactName              *string           `mapstructure:"artifact_name" required:"true" cty:"artifact_name" hcl:"artifact_name"`
	ArtifactDescription       *string           `mapstructure:"artifact_description" cty:"artifact_description" hcl:"artifact_description"`
	ArtifactOS                *string           `mapstructure:"artifact_os" cty:"artifact_os" hcl:"artifact_os"`
	ArtifactVersion           *string           `mapstructure:"artifact_version" cty:"artifact_version" hcl:"artifact_version"`
	SkipCreateImage           *bool             `mapstructure:"skip_create_image" required:"false" cty:"skip_create_image" hcl:"skip_create_image"`
	UserData                  *string           `mapstructure:"user_data" required:"false" cty:"user_data" hcl:"user_data"`
}

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.