Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update README.md #417

Merged
merged 1 commit into from
May 9, 2024
Merged

docs: update README.md #417

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 54 additions & 20 deletions .web-docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,18 @@
The vSphere plugin is able to create vSphere virtual machines for use with any VMware product.
To achieve this, the plugin comes with three builders, and two post-processors
to build the VM depending on the strategy you want to use.
<!-- markdownlint-disable first-line-h1 no-inline-html -->

The vSphere plugin is able to create vSphere virtual machines for use with VMware products.

To achieve this, the plugin comes with three builders, and two post-processors to build the virtual
machine depending on the strategy you want to use.

The Packer Plugin for VMware vSphere is a multi-component plugin can be used with
HashiCorp Packer to create virtual machine images for VMware vSphere.

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

### Installation

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

```hcl
Expand All @@ -23,25 +33,49 @@ packer plugins install github.com/hashicorp/vsphere
```

### Components
#### Builders:
- [vsphere-iso](/packer/integrations/hashicorp/vsphere/latest/components/builder/vsphere-iso) - This builder starts from an
ISO file and utilizes the vSphere API to build on a remote esx instance.
This allows you to build vms even if you do not have SSH access to your vSphere cluster.

- [vsphere-clone](/packer/integrations/hashicorp/vsphere/latest/components/builder/vsphere-clone) - This builder clones a
vm from an existing template, then modifies it and saves it as a new
template. It uses the vSphere API to build on a remote esx instance.
This allows you to build vms even if you do not have SSH access to your vSphere cluster.
#### Builders

- [vsphere-iso](/packer/integrations/hashicorp/vsphere/latest/components/builder/vsphere-iso) - This
builder starts from an ISO file and uses the vSphere API to build a virtual machine image on
an ESXi host.

- [vsphere-clone](/packer/integrations/hashicorp/vsphere/latest/components/builder/vsphere-clone) -
This builder clones a virtual machine from an existing template using the uses the vSphere API and
then modifies and saves it as a new template.

- [vsphere-supervisor](/packer/integrations/hashicorp/vsphere/latest/components/builder/vsphere-supervisor) - This builder deploys a
vm to a vSphere Supervisor cluster, using the VM-Service API. This allows you to build
vms without spec yaml files and configure them after using the Packer provisioners.
- [vsphere-supervisor](/packer/integrations/hashicorp/vsphere/latest/components/builder/vsphere-supervisor) -
This builder deploys and publishes new virtual machine to a vSphere Supervisor cluster using VM
Service.

#### Post-Processors
- [vsphere](/packer/integrations/hashicorp/vsphere/latest/components/post-processor/vsphere) - The Packer vSphere post-processor takes an artifact
and uploads it to a vSphere endpoint.

- [vsphere-template](/packer/integrations/hashicorp/vsphere/latest/components/post-processor/vsphere-template) - The Packer vSphere Template post-processor takes an
artifact from the vmware-iso builder, built on an ESXi host (i.e. remote) or an artifact from the
[vSphere](/packer/integrations/hashicorp/vsphere/latest/components/post-processor/vsphere) post-processor, marks the VM as a template, and leaves it in the path of
your choice.
- [vsphere](/packer/integrations/hashicorp/vsphere/latest/components/post-processor/vsphere) - This
post-processor uploads an artifact to a vSphere endpoint. The artifact must be a VMX, OVA, or OVF
file.

- [vsphere-template](/packer/integrations/hashicorp/vsphere/latest/components/post-processor/vsphere-template) - This post-processor uses an artifact from the `vmware-iso` builder with an ESXi host or an
artifact from the [vSphere](/packer/plugins/post-processors/vsphere/vsphere) post-processor. It
then marks the virtual machine as a template and moves it to your specified path.

### Differences from the Packer Plugin for VMware

While both this plugin and the [`packer-plugin-vmware`](packer/integrations/hashicorp/vmware) are
designed to create virtual machine images, there are some key differences:

- **Platforms**: This plugin 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. On the other hand, `packer-plugin-vmware` supports a variety of
platforms including VMware vSphere Hypervisor and desktop virtualization products such as VMware
Fusion, VMware Workstation, and VMware Player, though it does not utilize the vSphere API for its
operations.

- **Focus**: This plugin is purpose-built 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. In contrast, `packer-plugin-vmware`
includes builders that operate on both VMware vSphere Hypervisor and the aforementioned desktop
virtualization products, providing a different set of functionalities, including support for
Vagrant.

Please refer to the documentation for each plugin to understand the specific capabilities and
configuration options.
85 changes: 68 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,66 @@
# Packer Plugin for VMware vSphere

The Packer Plugin for VMware vSphere is a multi-component plugin can be used with [HashiCorp Packer][packer] to create virtual machine images for [VMware vSphere][docs-vsphere].
The Packer Plugin for VMware vSphere is a multi-component plugin can be used with
[HashiCorp Packer][packer] to create virtual machine images for [VMware vSphere][docs-vsphere]®.

The plugin includes two builders which are able to create images, depending on your desired strategy:
The plugin includes three builders and two post-processors which are able to create images,
depending on your desired strategy:

* `vsphere-iso` - This builder starts from an ISO file and utilizes the vSphere API to build images on a vSphere cluster or ESXi host by connecting to a vCenter Server instance.
**Builders**

* `vsphere-clone` - This builder clones an existing virtual machine template, modifies the template, and then saves it as a new image. The builder uses the vSphere API to build images on a vSphere cluster or ESXi host by connecting to a vCenter Server instance.
- `vsphere-iso` - This
builder starts from an ISO file and uses the vSphere API to build a virtual machine image on
an ESXi host.

* `vsphere-supervisor` - This builder creates a virtual machine on a vSphere Supervisor cluster by using the VM-Service API.
- `vsphere-clone` -
This builder clones a virtual machine from an existing template using the uses the vSphere API and
then modifies and saves it as a new template.

- `vsphere-supervisor` -
This builder deploys and publishes new virtual machine to a vSphere Supervisor cluster using VM
Service.

**Post-Processors**

- `vsphere` - This post-processor uploads an artifact to a vSphere endpoint. The artifact must be a
VMX, OVA, or OVF file.

- `vsphere-template` - This post-processor uses an artifact from the `vmware-iso` builder with an
ESXi host or an artifact from the [vSphere](/packer/plugins/post-processors/vsphere/vsphere)
post-processor. It then marks the virtual machine as a template and moves it to your specified
path.

## Differences from the Packer Plugin for VMware

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

- **Platforms**: This plugin 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. On the other hand, `packer-plugin-vmware` supports a variety of
platforms including VMware vSphere Hypervisor and desktop virtualization products such as VMware
Fusion, VMware Workstation, and VMware Player, though it does not utilize the vSphere API for its
operations.

- **Focus**: This plugin is purpose-built 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. In contrast, `packer-plugin-vmware`
includes builders that operate on both VMware vSphere Hypervisor and the aforementioned desktop
virtualization products, providing a different set of functionalities, including support for
Vagrant.

Please refer to the documentation for each plugin to understand the specific capabilities and configuration options.

## Requirements

* [VMware vSphere][docs-vsphere]
- [VMware vSphere][docs-vsphere]

The provider supports versions in accordance with the VMware Product Lifecycle Matrix from General Availability to End of General Support.
The provider supports versions in accordance with the VMware Product Lifecycle Matrix from
General Availability to End of General Support.

Learn more: [VMware Product Lifecycle Matrix][vmware-product-lifecycle-matrix]

* [Go 1.19][golang-install]
- [Go 1.19][golang-install]

Required if building the plugin.

Expand All @@ -28,9 +70,11 @@ The plugin includes two builders which are able to create images, depending on y

#### 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 @@ -46,31 +90,38 @@ packer {

#### Manual Installation

You can download [pre-built binary releases][releases-vsphere-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 [pre-built binary releases][releases-vsphere-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.

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-vsphere` 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-vsphere` 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][docs-vsphere-plugin].

* `vsphere-iso` [builder documentation][docs-vsphere-iso]
- `vsphere-iso` [builder documentation][docs-vsphere-iso]

* `vsphere-clone` [builder documentation][docs-vsphere-clone]
- `vsphere-clone` [builder documentation][docs-vsphere-clone]

* `vsphere-supervisor` [builder documentation][docs-vsphere-supervisor]
- `vsphere-supervisor` [builder documentation][docs-vsphere-supervisor]

## 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 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.
- 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.

[docs-packer-init]: https://developer.hashicorp.com/packer/docs/commands/init
[docs-packer-plugin-install]: https://developer.hashicorp.com/packer/docs/plugins/install-plugins
Expand Down
74 changes: 54 additions & 20 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,18 @@
The vSphere plugin is able to create vSphere virtual machines for use with any VMware product.
To achieve this, the plugin comes with three builders, and two post-processors
to build the VM depending on the strategy you want to use.
<!-- markdownlint-disable first-line-h1 no-inline-html -->

The vSphere plugin is able to create vSphere virtual machines for use with VMware products.

To achieve this, the plugin comes with three builders, and two post-processors to build the virtual
machine depending on the strategy you want to use.

The Packer Plugin for VMware vSphere is a multi-component plugin can be used with
HashiCorp Packer to create virtual machine images for VMware vSphere.

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

### Installation

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

```hcl
Expand All @@ -23,25 +33,49 @@ packer plugins install github.com/hashicorp/vsphere
```

### Components
#### Builders:
- [vsphere-iso](/packer/integrations/hashicorp/vsphere/latest/components/builder/vsphere-iso) - This builder starts from an
ISO file and utilizes the vSphere API to build on a remote esx instance.
This allows you to build vms even if you do not have SSH access to your vSphere cluster.

- [vsphere-clone](/packer/integrations/hashicorp/vsphere/latest/components/builder/vsphere-clone) - This builder clones a
vm from an existing template, then modifies it and saves it as a new
template. It uses the vSphere API to build on a remote esx instance.
This allows you to build vms even if you do not have SSH access to your vSphere cluster.
#### Builders

- [vsphere-iso](/packer/integrations/hashicorp/vsphere/latest/components/builder/vsphere-iso) - This
builder starts from an ISO file and uses the vSphere API to build a virtual machine image on
an ESXi host.

- [vsphere-clone](/packer/integrations/hashicorp/vsphere/latest/components/builder/vsphere-clone) -
This builder clones a virtual machine from an existing template using the uses the vSphere API and
then modifies and saves it as a new template.

- [vsphere-supervisor](/packer/integrations/hashicorp/vsphere/latest/components/builder/vsphere-supervisor) - This builder deploys a
vm to a vSphere Supervisor cluster, using the VM-Service API. This allows you to build
vms without spec yaml files and configure them after using the Packer provisioners.
- [vsphere-supervisor](/packer/integrations/hashicorp/vsphere/latest/components/builder/vsphere-supervisor) -
This builder deploys and publishes new virtual machine to a vSphere Supervisor cluster using VM
Service.

#### Post-Processors
- [vsphere](/packer/integrations/hashicorp/vsphere/latest/components/post-processor/vsphere) - The Packer vSphere post-processor takes an artifact
and uploads it to a vSphere endpoint.

- [vsphere-template](/packer/integrations/hashicorp/vsphere/latest/components/post-processor/vsphere-template) - The Packer vSphere Template post-processor takes an
artifact from the vmware-iso builder, built on an ESXi host (i.e. remote) or an artifact from the
[vSphere](/packer/integrations/hashicorp/vsphere/latest/components/post-processor/vsphere) post-processor, marks the VM as a template, and leaves it in the path of
your choice.
- [vsphere](/packer/integrations/hashicorp/vsphere/latest/components/post-processor/vsphere) - This
post-processor uploads an artifact to a vSphere endpoint. The artifact must be a VMX, OVA, or OVF
file.

- [vsphere-template](/packer/integrations/hashicorp/vsphere/latest/components/post-processor/vsphere-template) - This post-processor uses an artifact from the `vmware-iso` builder with an ESXi host or an
artifact from the [vSphere](/packer/plugins/post-processors/vsphere/vsphere) post-processor. It
then marks the virtual machine as a template and moves it to your specified path.

### Differences from the Packer Plugin for VMware

While both this plugin and the [`packer-plugin-vmware`](packer/integrations/hashicorp/vmware) are
designed to create virtual machine images, there are some key differences:

- **Platforms**: This plugin 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. On the other hand, `packer-plugin-vmware` supports a variety of
platforms including VMware vSphere Hypervisor and desktop virtualization products such as VMware
Fusion, VMware Workstation, and VMware Player, though it does not utilize the vSphere API for its
operations.

- **Focus**: This plugin is purpose-built 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. In contrast, `packer-plugin-vmware`
includes builders that operate on both VMware vSphere Hypervisor and the aforementioned desktop
virtualization products, providing a different set of functionalities, including support for
Vagrant.

Please refer to the documentation for each plugin to understand the specific capabilities and
configuration options.
Loading