VMware vSphere Supervisor Builder

Type: vsphere-supervisor Artifact BuilderId: vsphere.supervisor

This builder deploys new VMs to a vSphere Supervisor cluster.

• It uses kubeconfig file to connect to the vSphere Supervisor cluster.
• It uses the VM-Service API to deploy and configure the source VM.
• It uses the Packer provisioners to customize the VM after deployment.
• Planned enhancements that will introduce the ability to publish the customized VM as a new VM image to the vSphere endpoint.
• The builder supports versions following the VMware Product Lifecycle Matrix from General Availability to End of General Support. Builds on versions that are end of support may work, but configuration options may throw errors if they do not exist in the vSphere API for those versions.

Examples

Example Packer template:

source "vsphere-supervisor" "example-vm" {
  image_name = "<Image name of the source VM, e.g. 'ubuntu-impish-21.10-cloudimg'>"
  class_name = "<VM class that describes the virtual hardware settings, e.g. 'best-effort-large'>"
  storage_class = "<Storage class that provides the backing storage for volume, e.g. 'wcplocal-storage-profile'>"
}

build {
  sources = ["source.vsphere-supervisor.example-vm"]
}

{
  "builders": [
    {
      "type": "vsphere-supervisor",
      "image_name": "<Image name of the source VM, e.g. 'ubuntu-impish-21.10-cloudimg'>"
      "class_name": "<VM class that describes the virtual hardware settings, e.g. 'best-effort-large'>",
      "storage_class": "<Storage class that provides the backing storage for volume, e.g. 'wcplocal-storage-profile'>"
    }
  ]
}

Refer to the examples/supervisor directory within the GitHub repository for more complete examples.

Configuration Reference

There are various configuration options available for each step in this builder. The required items are listed below as well as the optional configs further down the page.

Required

• image_name (string) - Name of the source virtual machine (VM) image.

• class_name (string) - Name of the VM class that describes virtual hardware settings.

• storage_class (string) - Name of the storage class that configures storage-related attributes.

Optional

Supervisor Cluster Connection

• kubeconfig_path (string) - The path to kubeconfig file for accessing to the vSphere Supervisor cluster. Defaults to the value of KUBECONFIG envvar or $HOME/.kube/config if the envvar is not set.

• supervisor_namespace (string) - The Supervisor namespace to deploy the source VM. Defaults to the current context's namespace in kubeconfig.

Source VM Creation

• source_name (string) - Name of the source VM. Defaults to packer-vsphere-supervisor-built-source.

• network_type (string) - Name of the network type to attach to the source VM's network interface. Defaults to empty.

• network_name (string) - Name of the network to attach to the source VM's network interface. Defaults to empty.

• keep_input_artifact (bool) - Preserve the created objects even after importing them to the vSphere endpoint. Defaults to false.

Source VM Watching

• watch_source_timeout_sec (int) - The timeout in seconds to wait for the source VM to be ready. Defaults to 600.

SSH Configuration

• ssh_host (string) - The address to SSH to. This usually is automatically configured by the builder.

• ssh_port (int) - The port to connect to SSH. This defaults to 22.

• ssh_username (string) - The username to connect to SSH with. Required if using SSH.

• ssh_password (string) - A plaintext password to use to authenticate with SSH.

• ssh_ciphers ([]string) - This overrides the value of ciphers supported by default by Golang. The default value is [ "aes128-gcm@openssh.com", "chacha20-poly1305@openssh.com", "aes128-ctr", "aes192-ctr", "aes256-ctr", ]

  Valid options for ciphers include: "aes128-ctr", "aes192-ctr", "aes256-ctr", "aes128-gcm@openssh.com", "chacha20-poly1305@openssh.com", "arcfour256", "arcfour128", "arcfour", "aes128-cbc", "3des-cbc",

• ssh_clear_authorized_keys (bool) - If true, Packer will attempt to remove its temporary key from ~/.ssh/authorized_keys and /root/.ssh/authorized_keys. This is a mostly cosmetic option, since Packer will delete the temporary private key from the host system regardless of whether this is set to true (unless the user has set the -debug flag). Defaults to "false"; currently only works on guests with sed installed.

• ssh_key_exchange_algorithms ([]string) - If set, Packer will override the value of key exchange (kex) algorithms supported by default by Golang. Acceptable values include: "curve25519-sha256@libssh.org", "ecdh-sha2-nistp256", "ecdh-sha2-nistp384", "ecdh-sha2-nistp521", "diffie-hellman-group14-sha1", and "diffie-hellman-group1-sha1".

• ssh_certificate_file (string) - Path to user certificate used to authenticate with SSH. The ~ can be used in path and will be expanded to the home directory of current user.

• ssh_pty (bool) - If true, a PTY will be requested for the SSH connection. This defaults to false.

• ssh_timeout (duration string | ex: "1h5m2s") - The time to wait for SSH to become available. Packer uses this to determine when the machine has booted so this is usually quite long. Example value: 10m. This defaults to 5m, unless ssh_handshake_attempts is set.

• ssh_disable_agent_forwarding (bool) - If true, SSH agent forwarding will be disabled. Defaults to false.

• ssh_handshake_attempts (int) - The number of handshakes to attempt with SSH once it can connect. This defaults to 10, unless a ssh_timeout is set.

• ssh_bastion_host (string) - A bastion host to use for the actual SSH connection.

• ssh_bastion_port (int) - The port of the bastion host. Defaults to 22.

• ssh_bastion_agent_auth (bool) - If true, the local SSH agent will be used to authenticate with the bastion host. Defaults to false.

• ssh_bastion_username (string) - The username to connect to the bastion host.

• ssh_bastion_password (string) - The password to use to authenticate with the bastion host.

• ssh_bastion_interactive (bool) - If true, the keyboard-interactive used to authenticate with bastion host.

• ssh_bastion_private_key_file (string) - Path to a PEM encoded private key file to use to authenticate with the bastion host. The ~ can be used in path and will be expanded to the home directory of current user.

• ssh_bastion_certificate_file (string) - Path to user certificate used to authenticate with bastion host. The ~ can be used in path and will be expanded to the home directory of current user.

• ssh_file_transfer_method (string) - scp or sftp - How to transfer files, Secure copy (default) or SSH File Transfer Protocol.

  NOTE: Guests using Windows with Win32-OpenSSH v9.1.0.0p1-Beta, scp (the default protocol for copying data) returns a a non-zero error code since the MOTW cannot be set, which cause any file transfer to fail. As a workaround you can override the transfer protocol with SFTP instead ssh_file_transfer_protocol = "sftp".

• ssh_proxy_host (string) - A SOCKS proxy host to use for SSH connection

• ssh_proxy_port (int) - A port of the SOCKS proxy. Defaults to 1080.

• ssh_proxy_username (string) - The optional username to authenticate with the proxy server.

• ssh_proxy_password (string) - The optional password to use to authenticate with the proxy server.

• ssh_keep_alive_interval (duration string | ex: "1h5m2s") - How often to send "keep alive" messages to the server. Set to a negative value (-1s) to disable. Example value: 10s. Defaults to 5s.

• ssh_read_write_timeout (duration string | ex: "1h5m2s") - The amount of time to wait for a remote command to end. This might be useful if, for example, packer hangs on a connection after a reboot. Example: 5m. Disabled by default.

• ssh_remote_tunnels ([]string) -

• ssh_local_tunnels ([]string) -

• temporary_key_pair_type (string) - dsa | ecdsa | ed25519 | rsa ( the default )

  Specifies the type of key to create. The possible values are 'dsa', 'ecdsa', 'ed25519', or 'rsa'.

  NOTE: DSA is deprecated and no longer recognized as secure, please consider other alternatives like RSA or ED25519.

• temporary_key_pair_bits (int) - Specifies the number of bits in the key to create. For RSA keys, the minimum size is 1024 bits and the default is 4096 bits. Generally, 3072 bits is considered sufficient. DSA keys must be exactly 1024 bits as specified by FIPS 186-2. For ECDSA keys, bits determines the key length by selecting from one of three elliptic curve sizes: 256, 384 or 521 bits. Attempting to use bit lengths other than these three values for ECDSA keys will fail. Ed25519 keys have a fixed length and bits will be ignored.

  NOTE: DSA is deprecated and no longer recognized as secure as specified by FIPS 186-5, please consider other alternatives like RSA or ED25519.

Deprovisioning Tasks

If you would like to clean up the VM after the build is complete, you can use the Ansible provisioner to run the following tasks to delete machine-specific files and data.

build {
  sources = ["source.vsphere-supervisor.vm"]

  provisioner "ansible" {
    playbook_file = "cleanup-playbook.yml"
  }
}

{
  "builders": [
    {
      "type": "vsphere-supervisor"
    }
  ],
  "provisioners": [
    {
      "type": "ansible",
      "playbook_file": "./cleanup-playbook.yml"
    }
  ]
}

Content of cleanup-playbook.yml:

---
# cleanup-playbook.yml
- name: Clean up source VM
  hosts: default
  become: true
  tasks:
    - name: Truncate machine id
      file:
        state: "{{ item.state }}"
        path: "{{ item.path }}"
        owner: root
        group: root
        mode: "{{ item.mode }}"
      loop:
      - { path: /etc/machine-id, state: absent, mode: "0644" }
      - { path: /etc/machine-id, state: touch,  mode: "0644" }

    - name: Truncate audit logs
      file:
        state: "{{ item.state }}"
        path: "{{ item.path }}"
        owner: root
        group: utmp
        mode: "{{ item.mode }}"
      loop:
      - { path: /var/log/wtmp,    state: absent, mode: "0664" }
      - { path: /var/log/lastlog, state: absent, mode: "0644" }
      - { path: /var/log/wtmp,    state: touch,  mode: "0664" }
      - { path: /var/log/lastlog, state: touch,  mode: "0644" }

    - name: Remove cloud-init lib dir and logs
      file:
        state: absent
        path: "{{ item }}"
      loop:
      - /var/lib/cloud
      - /var/log/cloud-init.log
      - /var/log/cloud-init-output.log
      - /var/run/cloud-init

    - name: Truncate all remaining log files in /var/log
      shell:
        cmd: |
          find /var/log -type f -iname '*.log' | xargs truncate -s 0

    - name: Delete all logrotated log zips
      shell:
        cmd: |
          find /var/log -type f -name '*.gz' -exec rm {} +

    - name: Find temp files
      find:
        depth: 1
        file_type: any
        paths:
        - /tmp
        - /var/tmp
        pattern: '*'
      register: temp_files

    - name: Reset temp space
      file:
        state: absent
        path: "{{ item.path }}"
      loop: "{{ temp_files.files }}"

    - name: Truncate shell history
      file:
        state: absent
        path: "{{ item.path }}"
      loop:
      - { path: /root/.bash_history }
      - { path: "/home/{{ ansible_env.SUDO_USER | default(ansible_user_id) }}/.bash_history" }