# VMware vSphere
In Juju, [VMware vSphere](https://www.vmware.com/products/vsphere.html) is a [machine cloud](https://documentation.ubuntu.com/juju/3.6/reference/cloud.md#machine-cloud) and works as described below.
#### NOTE
This reference assumes basic familiarity with Juju. If you are new to Juju, start with the [Tutorial](https://documentation.ubuntu.com/juju/3.6/tutorial.md#tutorial), then use this page together with the generic materials it links to.
## Requirements
In order to add a vSphere cloud you will need an existing vSphere installation which supports, or has access to, the following:
- VMware Hardware Version 8 or greater.
- ESXi 5.0 or greater.
- Internet access.
- DNS and DHCP.
Juju supports both high-availability vSAN deployments and standard deployments.
### Minimal vSphere permissions
Juju does not require full administrator privileges. You can create a
dedicated vSphere role with the permissions listed below, scoped to the
datacenter and its children. These permissions allow Juju to import templates,
provision VMs, manage folders, and tear down resources.
Apply the role at the **datacenter level** with propagation to child
objects. For a tighter scope, restrict to the specific datacenter,
cluster, host folder, datastore folder, and network folder that Juju
will use.
**Global**
| VMware UI path | Privilege ID |
|------------------|----------------|
| System > Read | `System.Read` |
**Datastore**
| VMware UI path | Privilege ID |
|---------------------------------------|----------------------------|
| Datastore > Allocate space | `Datastore.AllocateSpace` |
| Datastore > Browse datastore | `Datastore.Browse` |
| Datastore > Low level file operations | `Datastore.FileManagement` |
**Folder**
| VMware UI path | Privilege ID |
|------------------------|-----------------|
| Folder > Create folder | `Folder.Create` |
| Folder > Delete folder | `Folder.Delete` |
| Folder > Move folder | `Folder.Move` |
**Network**
| VMware UI path | Privilege ID |
|--------------------------|------------------|
| Network > Assign network | `Network.Assign` |
**Resource**
| VMware UI path | Privilege ID |
|----------------------------------------------------|---------------------------|
| Resource > Assign virtual machine to resource pool | `Resource.AssignVMToPool` |
| Resource > Import | `Resource.Import` |
**vApp**
| VMware UI path | Privilege ID |
|---------------------------------------|------------------------------|
| vApp > Import | `vApp.Import` |
| vApp > vApp application configuration | `vApp.VAppApplicationConfig` |
**Virtual Machine > Configuration**
| VMware UI path | Privilege ID |
|-------------------------------------------------------------------------|------------------------------------------------|
| Virtual Machine > Configuration > Add or remove device | `VirtualMachine.Config.AddRemoveDevice` |
| Virtual Machine > Configuration > Change CPU count | `VirtualMachine.Config.CPUCount` |
| Virtual Machine > Configuration > Change Memory | `VirtualMachine.Config.Memory` |
| Virtual Machine > Configuration > Change Settings | `VirtualMachine.Config.Settings` |
| Virtual Machine > Configuration > Extend virtual disk | `VirtualMachine.Config.DiskExtend` |
| Virtual Machine > Configuration > Modify device settings | `VirtualMachine.Config.EditDevice` |
| Virtual Machine > Configuration > Advanced | `VirtualMachine.Config.AdvancedConfig` |
| Virtual Machine > Configuration > Upgrade virtual machine compatibility | `VirtualMachine.Config.UpgradeVirtualHardware` |
**Virtual Machine > Interaction**
| VMware UI path | Privilege ID |
|-------------------------------------------|------------------------------------|
| Virtual Machine > Interaction > Power On | `VirtualMachine.Interact.PowerOn` |
| Virtual Machine > Interaction > Power Off | `VirtualMachine.Interact.PowerOff` |
**Virtual Machine > Inventory**
| VMware UI path | Privilege ID |
|----------------------------------------------------|-----------------------------------------------|
| Virtual Machine > Inventory > Create from existing | `VirtualMachine.Inventory.CreateFromExisting` |
| Virtual Machine > Inventory > Move | `VirtualMachine.Inventory.Move` |
| Virtual Machine > Inventory > Remove | `VirtualMachine.Inventory.Delete` |
**Virtual Machine > Provisioning**
| VMware UI path | Privilege ID |
|---------------------------------------------------|----------------------------------------------|
| Virtual Machine > Provisioning > Deploy template | `VirtualMachine.Provisioning.DeployTemplate` |
| Virtual Machine > Provisioning > Mark as template | `VirtualMachine.Provisioning.MarkAsTemplate` |
#### TIP
The `System.Read` privilege provides read access to the entire inventory tree
(datacenters, folders, hosts, clusters, datastores, networks, VMs, resource
pools, and distributed virtual switches). The API session cannot enumerate
objects without it.
## Concepts
The following table shows how vSphere abstractions map to Juju concepts:
| vSphere | Juju |
|---------------------------------|------------------------------------------------------------------------|
| Virtual machine | [machine](https://documentation.ubuntu.com/juju/3.6/reference/machine.md#machine) |
| Process inside a VM | [unit](https://documentation.ubuntu.com/juju/3.6/reference/unit.md#unit) |
| Group of units for one workload | [application](https://documentation.ubuntu.com/juju/3.6/reference/application.md#application) |
| Datastore disk | [storage](https://documentation.ubuntu.com/juju/3.6/reference/storage.md#storage) |
| Port group / network | Network spaces and placement targets (roughly) |
| Cluster/resource pool | Placement target (`zones`) |
## The cloud
See also: [Cloud](https://documentation.ubuntu.com/juju/3.6/reference/cloud.md#cloud), [Juju | Manage clouds](https://documentation.ubuntu.com/juju/3.6/howto/manage-clouds.md#manage-clouds), [Terraform Provider for Juju | Manage clouds](https://canonical.com/juju/docs/terraform-provider-juju/latest/howto/manage-clouds/#manage-clouds)
As for all machine clouds, the cloud is registered in Juju via a cloud definition, stored in `clouds.yaml` on the client (on Linux: `~/.local/share/juju/clouds.yaml`) and following this schema:
```yaml
clouds:
: # User-defined name
type: vsphere
auth-types:
- # See Authentication types below
endpoint: # vCenter API endpoint
config: # Optional: model config defaults
: # See Configuration keys below
```
## Credentials
See also: [Credential](https://documentation.ubuntu.com/juju/3.6/reference/credential.md#credential), [Juju | Manage credentials](https://documentation.ubuntu.com/juju/3.6/howto/manage-credentials.md#manage-credentials), [Terraform Provider for Juju | Manage credentials](https://canonical.com/juju/docs/terraform-provider-juju/latest/howto/manage-credentials/#manage-credentials)
As for all machine clouds, credentials are stored in `credentials.yaml` on the client and follow this schema:
```yaml
credentials:
# Cloud name as defined above
: # User-defined credential name
auth-type: # userpass (the only type)
: # Auth-type-specific attributes (see below)
```
### Authentication types
VMware vSphere supports the following authentication types:
#### `userpass`
Attributes:
- `user`: The username to authenticate with (required).
- `password`: The password to authenticate with (required).
- `vmfolder`: The folder to add VMs from the model (optional).
## Controllers
See also: [Controller](https://documentation.ubuntu.com/juju/3.6/reference/controller.md#controller), [Juju | Manage controllers](https://documentation.ubuntu.com/juju/3.6/howto/manage-controllers.md#manage-controllers), [Terraform Provider for Juju | Manage controllers](https://canonical.com/juju/docs/terraform-provider-juju/latest/howto/manage-controllers/#manage-controllers)
### Bootstrap behavior
Creates a controller VM on vSphere by cloning from a template and waiting for provisioning tasks to complete.
Bootstrap downloads a cloud image to the client, uploads it to the ESX host, and creates a template. This process can be slow depending on network connection. Using pre-created templates speeds up bootstrap and machine deployment.
#### TIP
Bootstrap with cloud-specific model-configuration keys `datastore` and `primary-network` to avoid ambiguity.
### Resources created at bootstrap
The controller runs on a vSphere VM provisioned using the same mechanisms as workload machines – see [Resources created per machine](#vsphere-machine-resources-created-per-machine) for the full per-machine resource model. Controller-specific differences are noted below.
**Compute**
- **VM folder hierarchy**: Creates folder `Juju Controller ()` with nested structure `/Juju Controller (UUID)/Model "name" (UUID)/`. Folders enable cleanup by controller/model.
- **Template cache**: Creates `Juju Controller ()/templates/_