Skip to content

Commit

Permalink
docs: update README.md
Browse files Browse the repository at this point in the history 
Updates `./README.md` and `./docs/README.md`

Note: This includes the references to the deprecation of support for both the VMware vSphere Hypervisor (ESXi) and VMware Workstation Player.

Signed-off-by: Ryan Johnson <[email protected]>
  • Loading branch information
@tenthirtyam @lbajolet-hashicorp
tenthirtyam authored and lbajolet-hashicorp committed Jul 26, 2024
1 parent 5cd2b39 commit ffc9155
Show file tree
Hide file tree
Showing 3 changed files with 156 additions and 128 deletions.
71 changes: 44 additions & 27 deletions .web-docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@

<!-- markdownlint-disable first-line-h1 no-inline-html -->

The Packer Plugin for VMware with which to create virtual machine images for use with VMware products.
The Packer Plugin for VMware is a plugin that can be used to create virtual machine images for use
with VMware [desktop hypervisors][desktop-hypervisors] (VMware Fusion Pro, VMware Workstation Pro,
and VMware Workstation Player [^1]) and [VMware vSphere Hypervisor][vsphere-hypervisor] [^2].

### Installation

To install this plugin add this code into your Packer configuration and run [packer init](/packer/docs/commands/init)
To install this plugin, add following to your Packer configuration and run
[`packer init`](/packer/docs/commands/init).

```hcl
packer {
Expand All @@ -26,36 +28,51 @@ packer plugins install github.com/hashicorp/vmware

### Components

The plugin includes two builders which are able to create images, depending on your desired strategy
The plugin includes two builders which are able to create images, depending on your desired
strategy.

#### Builders

- [vmware-iso](/packer/integrations/hashicorp/vmware/latest/components/builder/iso) - Starts from an ISO file,
creates a brand new VMware VM, installs an OS, provisions software within
the OS, then exports that machine to create an image. This is best for
people who want to start from scratch.
- `vmware-iso` - This builder creates a virtual machine, installs an operating system from an ISO,
provisions software within the operating system, and then exports the virtual machine as an image.
This is best for those who want to start by creating an image.

- `vmware-vmx` - This builder imports an existing virtual machine (from a`.vmx` file), runs
provisioners on the virtual machine, and then exports the virtual machine as an image. This is
best for those who want to start from an existing virtual machine as the source. You can feed the
artifact of this builder back into Packer to iterate on an image.

### Known Issues

#### VMware Workstation Player (Linux)

1. You may encounter issues due to dependencies and configuration requirements on VMware Workstation
Player for Linux [^1]:

- [vmware-vmx](/packer/integrations/hashicorp/vmware/latest/components/builder/vmx) - This builder imports an
existing VMware machine (from a VMX file), runs provisioners on top of that
VM, and exports that machine to create an image. This is best if you have
an existing VMware VM you want to use as the source. As an additional
benefit, you can feed the artifact of this builder back into Packer to
iterate on a machine.
- **Dependencies**
- Add `qemu-img`. This command is available in the `qemu` package in Red Hat Enterprise Linux,
Debian, and derivative distributions.
- Add `vmrun`. This command is available from VMware Virtual Infrastructure eXtension (VIX) SDK.
- **Configuration**

### VMware Workstation Player on Linux
Edit the file `/usr/lib/vmware-vix/vixwrapper-config.txt`. The version specified in the fourth
column must be changed to match the version in the third column of the output from the
`vmplayer -v` command.

To use VMware Workstation Player with Packer on Linux, you will also need
the `qemu-img` command, which is available in the `qemu` package in
Red Hat Enterprise Linux, Debian, and derivative distributions.
For detailed steps and troubleshooting, refer to [this][known-issues-so] StackOverflow thread.

Additionally you will need to have the `vmrun` command, which is part of the
VMware [Virtual Infrastructure eXtension][vix-api] [(VIX) SDK][vix-sdk].
[^1]: Support for VMware Workstation Player is deprecated and will be removed in a future release.
Read more about [discontinuation of VMware Workstation Player][footnote-player-discontinuation].
The project will continue to provide bug fixes; however, enhancements for this platform will
no longer be addressed.

Finally, you must edit the file `/usr/lib/vmware-vix/vixwrapper-config.txt`
and change the version specified in the fourth column to be the version in
the third column of the `vmplayer -v` command.
See [this StackOverflow thread][so] for more details.
[^2]: Support for VMware vSphere Hypervisor (ESXi) is deprecated and will be removed in a future release.
Please transition to using the [Packer Plugin for VMware vSphere][footnote-packer-plugin-vsphere].
The project will continue to provide bug fixes; however, enhancements for this platform will
no longer be addressed.

[vix-api]: https://www.vmware.com/support/developer/vix-api/
[vix-sdk]: https://customerconnect.vmware.com/downloads/details?downloadGroup=PLAYER-1400-VIX1170&productId=687
[so]: https://stackoverflow.com/questions/31985348/vix-vmrun-doesnt-work-with-vmware-player
[vsphere-hypervisor]: https://www.vmware.com/products/vsphere-hypervisor.html
[desktop-hypervisors]: https://www.vmware.com/products/desktop-hypervisor.html
[known-issues-so]: https://stackoverflow.com/questions/31985348/vix-vmrun-doesnt-work-with-vmware-player
[footnote-player-discontinuation]: https://blogs.vmware.com/workstation/2024/05/vmware-workstation-pro-now-available-free-for-personal-use.html
[footnote-packer-plugin-vsphere]: https://developer.hashicorp.com/packer/integrations/hashicorp/vsphere
142 changes: 68 additions & 74 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,87 +1,61 @@
# Packer Plugin for VMware

The Packer Plugin for VMware is a multi-component plugin that can be used with
[Packer][packer] to create virtual machine images for use with
[VMware vSphere Hypervisor][vsphere-hypervisor] and
[desktop hypervisor products][desktop-hypervisors] such as VMware Fusion Pro,
VMware Workstation Pro, and VMware Workstation Player,

The plugin includes two builders which are able to create images, depending on
your desired strategy:

- [`vmware-iso`][docs-vmware-iso] - This builder creates a virtual machine,
installs an operating system from an ISO, provisions software within the
operating system, and then exports the virtual machine as an image. This is
best for those who want to start by creating a base image.

- [`vmware-vmx`][docs-vmware-vmx] - This builder imports an existing virtual
machine (from a`.vmx` file), runs provisioners on the virtual machine, and
then exports the virtual machine as an image. This is best for those who want
to start from an existing virtual machine as the source. You can feed the
artifact of this builder back into Packer to iterate on a machine image.

## Differences from the Packer Plugin for VMware vSphere

While both this plugin and the `packer-plugin-vsphere` are designed to create
virtual machine images, there are some key differences:

- **Platforms**: This plugin facilitates the creation of virtual machine images
by integrating with VMware vSphere Hypervisor and desktop virtualization
products such as VMware Fusion Pro, VMware Workstation Pro, and VMware
Workstation Player; without using the VMware vSphere API. On the other hand,
`packer-plugin-vsphere` is specifically developed to utilize the VMware
vSphere API, facilitating the creation of virtual machine images by
integrating with VMware vCenter Server and the VMware vSphere Hypervisor.

- **Focus**: This plugin is purpose-built with a focus on VMware vSphere
Hypervisor and desktop virtualization products such as VMware Fusion Pro,
VMware Workstation Pro, and VMware Workstation Player. In contrast,
`packer-plugin-vsphere`, includes builders and post-processors with a focus on
VMware vSphere, offering capabilities such as creating virtual machine images,
cloning and modifying base virtual machine images, and exporting artifacts in
specified locations and formats.

Please refer to the documentation for each plugin to understand the specific
capabilities and configuration options.
The Packer Plugin for VMware is a plugin that can be used to create virtual machine images for use
with VMware [desktop hypervisors][desktop-hypervisors] ( VMware Fusion Pro, VMware Workstation Pro,
and VMware Workstation Player[^1] ) and [VMware vSphere Hypervisor][vsphere-hypervisor] [^2].

## Requirements
The plugin includes two builders which are able to create images, depending on your desired
strategy:

- [`vmware-iso`][docs-vmware-iso] - This builder creates a virtual machine, installs an operating
system from an ISO, provisions software within the operating system, and then exports the virtual
machine as an image. This is best for those who want to start by creating an image.

- [`vmware-vmx`][docs-vmware-vmx] - This builder imports an existing virtual machine (from a`.vmx`
file), runs provisioners on the virtual machine, and then exports the virtual machine as an image.
This is best for those who want to start from an existing virtual machine as the source. You can
feed the artifact of this builder back into Packer to iterate on an image.

## Supported Hypervisors

The following hypervisors are supported by this plugin.

**Desktop Hypervisor**:

- VMware Fusion Pro (macOS)
- VMware Workstation Pro (Linux and Windows)
- VMware Workstation Player (Linux)
- VMware Workstation Player (Linux and Windows) [^1]

**Bare Metal Hypervisor**:

- VMware vSphere Hypervisor
- VMware vSphere Hypervisor [^2]

The plugin supports versions in accordance with the [Broadcom Product Lifecycle][product-lifecycle].

The plugin supports versions in accordance with the
[Broadcom Product Lifecycle][product-lifecycle].
## Requirements

**Go**:

- [Go 1.21][golang-install]

Required if building the plugin.
Required if building the plugin.

## Usage

For a few examples on how to use this plugin with Packer refer to the
[example](example/) template directory.
For a examples on how to use this plugin with Packer refer to the [example](example/) directory of
the repository.

## Installation

### Using Pre-built Releases

#### Automatic Installation

Packer v1.7.0 and later supports the `packer init` command which enables the
automatic installation of Packer plugins. For more information, see the
[Packer documentation][docs-packer-init].
Packer v1.7.0 and later supports the `packer init` command which enables the automatic installation
of Packer plugins. For more information, see the [Packer documentation][docs-packer-init].

To install this plugin, copy and paste this code (HCL2) into your Packer
configuration and run `packer init`.
To install this plugin, copy and paste this code (HCL2) into your Packer configuration and run
`packer init`.

```hcl
packer {
Expand All @@ -97,50 +71,70 @@ packer {

#### Manual Installation

You can download [pre-built binary releases][releases-vmware-plugin] of the
plugin on GitHub. Once you have downloaded the latest release archive for your
target operating system and architecture, extract the release archive to
retrieve the plugin binary file for your platform.
You can download the plugin from the GitHub [releases][releases-vmware-plugin]. Once you have
downloaded the latest release archive for your target operating system and architecture, extract the
release archive to retrieve the plugin binary file for your platform.

To install the downloaded plugin, please follow the Packer documentation on
[installing a plugin][docs-packer-plugin-install].

### Using the Source

If you prefer to build the plugin from sources, clone the GitHub repository
locally and run the command `go build` from the repository root directory. Upon
successful compilation, a `packer-plugin-vmware` plugin binary file can be found
in the root directory.
If you prefer to build the plugin from sources, clone the GitHub repository locally and run the
command `go build` from the repository root directory. Upon successful compilation, a
`packer-plugin-vmware` plugin binary file can be found in the root directory.

To install the compiled plugin, please follow the Packer documentation on
[installing a plugin][docs-packer-plugin-install].

### Configuration

For more information on how to configure the plugin, please see the plugin
documentation.
For more information on how to configure the plugin, please see the plugin documentation.

- `vmware-iso` [builder documentation][docs-vmware-iso]
- `vmware-vmx` [builder documentation][docs-vmware-vmx]

## 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.
If you discover a bug or would like to suggest a feature or an enhancement, please use the GitHub
[issues][issues]. Issues are monitored by the maintainers and are prioritized based on the
criticality and community reactions.

Before opening an issue, please check existing open or recently closed issues to avoid duplicates.

When opening an issue, please include as much information as possible, such as:

- A minimal reproducible example or a series of reproduction steps.
- Details about your environment or deployment that might be unusual.

Please review the [contribution guidelines][contributing] before submitting a pull request.

For enhancements or features, please open an issue to discuss before submitting.

For comprehensive details on contributing, refer to the [contribution guidelines][contributing].

[^1]:
Support for VMware Workstation Player is deprecated and will be removed in a future release.
Read more about [discontinuation of VMware Workstation Player][footnote-player-discontinuation].
The project will continue to provide bug fixes; however, enhancements for this platform will
no longer be addressed.

- 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.
[^2]:
Support for VMware vSphere Hypervisor (ESXi) is deprecated and will be removed in a future release.
Please transition to using the [Packer Plugin for VMware vSphere][footnote-packer-plugin-vsphere].
The project will continue to provide bug fixes; however, enhancements for this platform will
no longer be addressed.

[contributing]: .github/CONTRIBUTING.md
[issues]: https://github.com/hashicorp/packer-plugin-vmware/issues
[vsphere-hypervisor]: https://www.vmware.com/products/vsphere-hypervisor.html
[desktop-hypervisors]: https://www.vmware.com/products/desktop-hypervisor.html
[docs-packer-init]: https://developer.hashicorp.com/packer/docs/commands/init
[docs-packer-plugin-install]: https://developer.hashicorp.com/packer/docs/plugins/install-plugins
[docs-vmware-iso]: https://developer.hashicorp.com/packer/plugins/builders/vmware/iso
[docs-vmware-vmx]: https://developer.hashicorp.com/packer/plugins/builders/vmware/vmx
[golang-install]: https://golang.org/doc/install
[packer]: https://www.packer.io
[releases-vmware-plugin]: https://github.com/hashicorp/packer-plugin-vmware/releases
[product-lifecycle]: https://support.broadcom.com/group/ecx/productlifecycle
[footnote-player-discontinuation]: https://blogs.vmware.com/workstation/2024/05/vmware-workstation-pro-now-available-free-for-personal-use.html
[footnote-packer-plugin-vsphere]: https://developer.hashicorp.com/packer/integrations/hashicorp/vsphere
Loading

0 comments on commit ffc9155

Please sign in to comment.