generated from hashicorp/packer-plugin-scaffolding
-
Notifications
You must be signed in to change notification settings - Fork 95
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore(post-processor): update
vsphere
- Updates and simplifies code comments. - Updates post-processor to generate documentation from structs. - Generates the updated post-processor documentation. Signed-off-by: Ryan Johnson <[email protected]>
- Loading branch information
1 parent
a236f67
commit 15bac9d
Showing
6 changed files
with
234 additions
and
210 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,84 +1,94 @@ | ||
| Type: `vsphere` | ||
| Artifact BuilderId: `packer.post-processor.vsphere` | ||
|
|
||
| The Packer vSphere post-processor takes an artifact and uploads it to a vSphere endpoint. | ||
| The artifact must have a vmx/ova/ovf image. | ||
| This post-processor uploads an artifact to a vSphere endpoint. | ||
|
|
||
| The artifact must be a VMX, OVA, or OVF file. | ||
|
|
||
| ## Configuration | ||
|
|
||
| There are many configuration options available for the post-processor. They are | ||
| segmented below into two categories: required and optional parameters. Within | ||
| each category, the available configuration keys are alphabetized. | ||
| The following configuration options are available for the post-processor. | ||
|
|
||
| Required: | ||
|
|
||
| - `cluster` (string) - The vSphere cluster or ESXi host to upload the VM. This can be | ||
| either the name of the vSphere cluster or the FQDN/IP address of an ESXi host. | ||
| <!-- Code generated from the comments of the Config struct in post-processor/vsphere/post-processor.go; DO NOT EDIT MANUALLY --> | ||
|
|
||
| - `cluster` (string) - Specifies the vSphere cluster or ESXi host to upload the virtual machine. | ||
| This can be either the name of the vSphere cluster or the fully qualified domain name (FQDN) | ||
| or IP address of the ESXi host. | ||
|
|
||
| - `datacenter` (string) - Specifies the name of the vSphere datacenter object to place the virtual machine. | ||
| This is _not required_ if `resource_pool` is specified. | ||
|
|
||
| - `datacenter` (string) - The name of the datacenter within the vSphere environemnt | ||
| to add the VM. | ||
| - `datastore` (string) - Specifies the name of the vSphere datastore to place the virtual machine. | ||
|
|
||
| - `datastore` (string) - The name of the datastore to place the VM. This is | ||
| _not required_ if `resource_pool` is specified. | ||
| - `host` (string) - Specifies the fully qualified domain name or IP address of the vCenter Server or ESXi host. | ||
|
|
||
| - `host` (string) - The vSphere endpoint that will be contacted to perform | ||
| the VM upload. | ||
| - `password` (string) - Specifies the password to use to authenticate to the vSphere endpoint. | ||
|
|
||
| - `password` (string) - The password to use to authenticate to the endpoint. | ||
| - `username` (string) - Specifies the username to use to authenticate to the vSphere endpoint. | ||
|
|
||
| - `username` (string) - The username to use to authenticate to the endpoint. | ||
| <!-- End of code generated from the comments of the Config struct in post-processor/vsphere/post-processor.go; --> | ||
|
|
||
| - `vm_name` (string) - The name of the VM after upload. | ||
|
|
||
| Optional: | ||
|
|
||
| - `esxi_host` (string) - Target ESXi host. Used to assign specific ESXi | ||
| host to upload the resulting VM, when a vCenter Server is used as | ||
| `host`. Can be either an FQDN (e.g., "esxi-01.example.com", requires proper DNS | ||
| setup and/or correct DNS search domain setting) or an IPv4 address. | ||
| <!-- Code generated from the comments of the Config struct in post-processor/vsphere/post-processor.go; DO NOT EDIT MANUALLY --> | ||
|
|
||
| - `disk_mode` (string) - Specifies the disk format of the target virtual machine. One of `thin`, `thick`, | ||
|
|
||
| - `esxi_host` (string) - Specifies the fully qualified domain name or IP address of the ESXi host to upload the | ||
| virtual machine. This is _not required_ if `host` is a vCenter Server. | ||
|
|
||
| - `disk_mode` (string) - Target disk format. See `ovftool` manual for | ||
| available options. Default: `thick`. | ||
| - `insecure` (bool) - Specifies whether to skip the verification of the server certificate. Defaults to `false`. | ||
|
|
||
| - `insecure` (boolean) - Whether or not the connection can be done | ||
| over an insecure connection. Default: `false` | ||
| - `options` ([]string) - Specifies custom options to add in `ovftool`. | ||
| Use `ovftool --help` to list all the options available. | ||
|
|
||
| - `keep_input_artifact` (boolean) - When `true`, preserve the local VM files, | ||
| even after importing them to the vSphere endpoint. Default: `false`. | ||
| - `overwrite` (bool) - Specifies whether to overwrite the existing files. | ||
| If `true`, forces existing files to to be overwritten. Defaults to `false`. | ||
|
|
||
| - `resource_pool` (string) - The resource pool in which to upload the VM. | ||
| - `resource_pool` (string) - Specifies the name of the resource pool to place the virtual machine. | ||
|
|
||
| - `vm_folder` (string) - The folder within the datastore to place the VM. | ||
| - `vm_folder` (string) - Specifies the name of the virtual machine folder path where the virtual machine will be | ||
| placed. | ||
|
|
||
| - `vm_network` (string) - The name of the network in which to place the VM. | ||
| - `vm_name` (string) - Specifies the name of the virtual machine to be created on the vSphere endpoint. | ||
|
|
||
| - `overwrite` (boolean) - If `true`, force the system to overwrite the | ||
| existing files instead create new ones. Default: `false` | ||
| - `vm_network` (string) - Specifies the name of the network in which to place the virtual machine. | ||
|
|
||
| - `hardware_version` (string) - This option sets the maximum virtual hardware version | ||
| for the deployed VM. It does not upgrade the virtual hardware version of the source VM. | ||
| Instead, it limits the virtual hardware version of the deployed VM to the specified | ||
| version. If the source VM's hardware version is higher than the specified version, | ||
| the deployed VM's hardware version will be downgraded to the specified version. | ||
| If the source VM's hardware version is lower than or equal to the specified version, | ||
| the deployed VM's hardware version will be the same as the source VM's. | ||
| This option is useful when deploying to a vSphere / ESXi host whose version is different | ||
| than the one used to create the artifact. | ||
| - `hardware_version` (string) - Specifies the maximum virtual hardware version for the deployed virtual machine. | ||
|
|
||
| See [VMware KB 1003746](https://kb.vmware.com/s/article/1003746) for more information | ||
| on the virtual hardware versions supported for each vSphere / ESXi version. | ||
| It does not upgrade the virtual hardware version of the source VM. Instead, it limits the | ||
| virtual hardware version of the deployed virtual machine to the specified version. | ||
| If the source virtual machine's hardware version is higher than the specified version, the | ||
| deployed virtual machine's hardware version will be downgraded to the specified version. | ||
|
|
||
| If the source virtual machine's hardware version is lower than or equal to the specified | ||
| version, the deployed virtual machine's hardware version will be the same as the source | ||
| virtual machine's. | ||
|
|
||
| This option is useful when deploying to vCenter Server instance ot an ESXi host whose | ||
| version is different than the one used to create the artifact. | ||
|
|
||
| See [VMware KB 1003746](https://kb.vmware.com/s/article/1003746) for more information on the | ||
| virtual hardware versions supported. | ||
|
|
||
| <!-- End of code generated from the comments of the Config struct in post-processor/vsphere/post-processor.go; --> | ||
|
|
||
| - `options` (array of strings) - Custom options to add in `ovftool`. See | ||
| `ovftool --help` to list all the options | ||
|
|
||
| # Example | ||
| - `keep_input_artifact` (boolean) - Specifies to preserve the local virtual machines files, even | ||
| after importing them to the vSphere endpoint. Defaults to `false`. | ||
|
|
||
| The following is an example of the vSphere post-processor being used in | ||
| conjunction with the null builder to upload a vmx to a vSphere cluster. | ||
| # Example Usage | ||
|
|
||
| You can also use this post-processor with the vmx artifact from a build. | ||
| The following is an example of the vSphere post-processor being used in conjunction with the `null` | ||
| builder to upload a VMX to a vSphere cluster. You can also use this post-processor with the VMX | ||
| artifact from a build. | ||
|
|
||
| **HCL2** | ||
| An example is shown below, showing only the post-processor configuration: | ||
|
|
||
| In HCL2: | ||
|
|
||
| ```hcl | ||
| source "null" "example" { | ||
|
|
@@ -96,7 +106,7 @@ build { | |
| host = "vcenter.example.com" | ||
| username = "[email protected]" | ||
| password = "VMw@re1!" | ||
| datacenter = "dc-01" | ||
| datacenter = "dc-01" | ||
| cluster = "cluster-01" | ||
| datastore = "datastore-01" | ||
| vm_network = "VM Network" | ||
|
|
@@ -106,7 +116,7 @@ build { | |
| } | ||
| ``` | ||
|
|
||
| **JSON** | ||
| In JSON: | ||
|
|
||
| ```json | ||
| { | ||
|
|
@@ -135,33 +145,34 @@ build { | |
| } | ||
| ``` | ||
|
|
||
|
|
||
| # Privileges | ||
|
|
||
| The post-processor uses `ovftool` and therefore needs the same privileges | ||
| as `ovftool`. Rather than giving full administrator access, you can create a role | ||
| to give the post-processor the permissions necessary to run. Below is an example | ||
| role. Please note that this is a user-supplied list so there may be a few | ||
| extraneous permissions that are not strictly required. | ||
|
|
||
| For vSphere the role needs the following privileges: | ||
|
|
||
| Datastore.AllocateSpace | ||
| Host.Config.AdvancedConfig | ||
| Host.Config.NetService | ||
| Host.Config.Network | ||
| Network.Assign | ||
| System.Anonymous | ||
| System.Read | ||
| System.View | ||
| VApp.Import | ||
| VirtualMachine.Config.AddNewDisk | ||
| VirtualMachine.Config.AdvancedConfig | ||
| VirtualMachine.Inventory.Delete | ||
|
|
||
| And this role must be authorized on the: | ||
|
|
||
| Cluster of the host | ||
| The destination folder (not on Datastore, on the vSphere logical view) | ||
| The network to be assigned | ||
| The destination datastore. | ||
| The post-processor uses `ovftool` and tneeds several privileges to be able to run `ovftool`. | ||
|
|
||
| Rather than giving full administrator access, you can create a role to give the post-processor the | ||
| privileges necessary to run. | ||
|
|
||
| Below is an example role that will work. Please note that this is a user-supplied list so there may | ||
| be a few extraneous privileges that are not strictly required. | ||
|
|
||
| For vSphere, the role needs the following privileges: | ||
|
|
||
| - `Datastore.AllocateSpace` | ||
| - `Host.Config.AdvancedConfig` | ||
| - `Host.Config.NetService` | ||
| - `Host.Config.Network` | ||
| - `Network.Assign` | ||
| - `System.Anonymous` | ||
| - `System.Read` | ||
| - `System.View` | ||
| - `VApp.Import` | ||
| - `VirtualMachine.Config.AddNewDisk` | ||
| - `VirtualMachine.Config.AdvancedConfig` | ||
| - `VirtualMachine.Inventory.Delete` | ||
|
|
||
| The role must be authorized on the: | ||
|
|
||
| - Cluster of the host. | ||
| - The destination folder. | ||
| - The destination datastore. | ||
| - The network to be assigned. | ||
51 changes: 29 additions & 22 deletions
51
docs-partials/post-processor/vsphere/Config-not-required.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,35 +1,42 @@ | ||
| <!-- Code generated from the comments of the Config struct in post-processor/vsphere/post-processor.go; DO NOT EDIT MANUALLY --> | ||
|
|
||
| - `cluster` (string) - Cluster | ||
| - `disk_mode` (string) - Specifies the disk format of the target virtual machine. One of `thin`, `thick`, | ||
|
|
||
| - `datacenter` (string) - Datacenter | ||
| - `esxi_host` (string) - Specifies the fully qualified domain name or IP address of the ESXi host to upload the | ||
| virtual machine. This is _not required_ if `host` is a vCenter Server. | ||
|
|
||
| - `datastore` (string) - Datastore | ||
| - `insecure` (bool) - Specifies whether to skip the verification of the server certificate. Defaults to `false`. | ||
|
|
||
| - `disk_mode` (string) - Disk Mode | ||
| - `options` ([]string) - Specifies custom options to add in `ovftool`. | ||
| Use `ovftool --help` to list all the options available. | ||
|
|
||
| - `host` (string) - Host | ||
| - `overwrite` (bool) - Specifies whether to overwrite the existing files. | ||
| If `true`, forces existing files to to be overwritten. Defaults to `false`. | ||
|
|
||
| - `esxi_host` (string) - ES Xi Host | ||
| - `resource_pool` (string) - Specifies the name of the resource pool to place the virtual machine. | ||
|
|
||
| - `insecure` (bool) - Insecure | ||
| - `vm_folder` (string) - Specifies the name of the virtual machine folder path where the virtual machine will be | ||
| placed. | ||
|
|
||
| - `options` ([]string) - Options | ||
| - `vm_name` (string) - Specifies the name of the virtual machine to be created on the vSphere endpoint. | ||
|
|
||
| - `overwrite` (bool) - Overwrite | ||
| - `vm_network` (string) - Specifies the name of the network in which to place the virtual machine. | ||
|
|
||
| - `password` (string) - Password | ||
|
|
||
| - `resource_pool` (string) - Resource Pool | ||
|
|
||
| - `username` (string) - Username | ||
|
|
||
| - `vm_folder` (string) - VM Folder | ||
|
|
||
| - `vm_name` (string) - VM Name | ||
|
|
||
| - `vm_network` (string) - VM Network | ||
|
|
||
| - `hardware_version` (string) - Hardware Version | ||
| - `hardware_version` (string) - Specifies the maximum virtual hardware version for the deployed virtual machine. | ||
|
|
||
| It does not upgrade the virtual hardware version of the source VM. Instead, it limits the | ||
| virtual hardware version of the deployed virtual machine to the specified version. | ||
| If the source virtual machine's hardware version is higher than the specified version, the | ||
| deployed virtual machine's hardware version will be downgraded to the specified version. | ||
|
|
||
| If the source virtual machine's hardware version is lower than or equal to the specified | ||
| version, the deployed virtual machine's hardware version will be the same as the source | ||
| virtual machine's. | ||
|
|
||
| This option is useful when deploying to vCenter Server instance ot an ESXi host whose | ||
| version is different than the one used to create the artifact. | ||
|
|
||
| See [VMware KB 1003746](https://kb.vmware.com/s/article/1003746) for more information on the | ||
| virtual hardware versions supported. | ||
|
|
||
| <!-- End of code generated from the comments of the Config struct in post-processor/vsphere/post-processor.go; --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| <!-- Code generated from the comments of the Config struct in post-processor/vsphere/post-processor.go; DO NOT EDIT MANUALLY --> | ||
|
|
||
| - `cluster` (string) - Specifies the vSphere cluster or ESXi host to upload the virtual machine. | ||
| This can be either the name of the vSphere cluster or the fully qualified domain name (FQDN) | ||
| or IP address of the ESXi host. | ||
|
|
||
| - `datacenter` (string) - Specifies the name of the vSphere datacenter object to place the virtual machine. | ||
| This is _not required_ if `resource_pool` is specified. | ||
|
|
||
| - `datastore` (string) - Specifies the name of the vSphere datastore to place the virtual machine. | ||
|
|
||
| - `host` (string) - Specifies the fully qualified domain name or IP address of the vCenter Server or ESXi host. | ||
|
|
||
| - `password` (string) - Specifies the password to use to authenticate to the vSphere endpoint. | ||
|
|
||
| - `username` (string) - Specifies the username to use to authenticate to the vSphere endpoint. | ||
|
|
||
| <!-- End of code generated from the comments of the Config struct in post-processor/vsphere/post-processor.go; --> |
Oops, something went wrong.