Proxmox VE is an open-source server virtualization environment. This integration allows you to poll various data and controls from your instance.
This integration started as improvements to the Home Assistant core's Proxmox VE integration, but I'm new to programming and couldn't meet all of the core's code requirements. So I decided to keep it as a custom integration. Therefore, when installing this, the core integration will be replaced.
After configuring this integration, the following information is available:
- Binary sensor entities with the status of node and selected virtual machines/containers.
- Sensor entities of the selected node and virtual machines/containers. Some sensors are created disabled by default, you can enable them by accessing the entity's configuration.
- Entities button to control selected virtual machines/containers (see about Proxmox user permissions below). By default, the entities buttons to control virtual machines/containers are created disabled, see how to enable them here.
⚠️ Important: See the section on Proxmox user permissions here.
Have HACS installed, this will allow you to update easily.
- Adding Proxmox VE to HACS can be using this button:
(If the button above doesn't work, add https://github.com/dougiteixeira/proxmoxve
as a custom repository of type Integration in HACS.)
- Click Install on the
Proxmox VE
integration. - Restart the Home Assistant.
- Copy
proxmoxve
folder from latest release tocustom_components
folder in your config directory. - Restart the Home Assistant.
Adding Proxmox VE to your Home Assistant instance can be done via the UI using this button:
If the button above doesn't work, you can also perform the following steps manually:
- Navigate to your Home Assistant instance.
- In the sidebar, click Settings.
- From the Setup menu, select: Devices & Services.
- In the lower right corner, click the Add integration button.
- In the list, search and select
Proxmox VE
. - Follow the on-screen instructions to complete the setup.
To enable debug for Proxmox VE integration, add following to your configuration.yaml
:
logger:
default: info
logs:
custom_components.proxmoxve: debug
To be able to obtain each type of integration information, the user used to connect must have the corresponding privilege.
It is not necessary to include all of the permission roles below, this will depend on your use of the integration.
The integration will create a repair for each resource that is exposed in the integration configuration but is not accessible by the user, indicating the path and privilege necessary to access it.
When executing a command, if the user does not have the necessary permission, a repair will be created indicating the path and privilege necessary to execute it.
The repairs created are informative, the responsibility for evaluating the risks involved in assigning the permissions to the user is the sole responsibility of the user.
Below is a summary of the permissions for each integration feature. I suggest you create the roles below to make it easier to assign only the necessary permissions to the user.
Purpose of Permission | Access Type | Role (name suggestion) | Privilegies |
---|---|---|---|
Get data from nodes, VM, CT and storages | Read only | HomeAssistant.Audit | VM.Audit, Sys.Audit and Datastore.Audit |
Perform commands on the node (shutdown, restart, start all, shutdown all) | Management permission | HomeAssistant.NodePowerMgmt | Sys.PowerMgmt |
Get information about available package updates to display on sensors (integration does not trigger the update) | Management permission | HomeAssistant.Update | Sys.Modify |
Perform commands on VM/CT (start, shutdown, restart, suspend, resume and hibernate) | Management permission | HomeAssistant.VMPowerMgmt | VM.PowerMgmt |
Before creating the user, we need to create a group for the user. Privileges can be either applied to Groups or Roles.
- Click
Datacenter
- Open
Permissions
and clickGroups
- Click the
Create
button above all the existing groups - Name the new group (e.g.,
HomeAssistant
) - Click
Create
- Click
Datacenter
- Click
Permissions
- Open
Add
and clickGroup Permission
- Select the path of the resource you want to authorize the user to access. To enable all features select
/
- Select your Home Assistant group (
HomeAssistant
) - Select the role according to the table above (you must add a permission for each role in the table).
- Make sure
Propagate
is checked
Creating a dedicated user for Home Assistant, limited to only to the access just created is the most secure method. These instructions use the pve
realm for the user. This allows a connection, but ensures that the user is not authenticated for SSH connections.
- Click
Datacenter
- Open
Permissions
and clickUsers
- Click
Add
- Enter a username (e.g.,
homeassistant
) - Set the realm to "Proxmox VE authentication server"
- Enter a secure password (it can be complex as you will only need to copy/paste it into your Home Assistant configuration)
- Select the group just created earlier (
HomeAssistant
) to grant access to Proxmox - Ensure
Enabled
is checked andExpire
is set to "never" - Click
Add
In your Home Assistant configuration, use homeassistant@pve
for the username and your chosen password for the password.
A step by step to enable entities
-
Go to the page for the device you want to enable the button (or sensor).
-
Click x entities not show
-
Click on the entity you want to enable and click on settings (on the gear icon):
-
Click the Enable button at the top of the dialog:
-
Wait a while (approximately 30 seconds) for the entity to be enabled. If you don't want to wait, just reload the configuration entry on the integration page.
For the entity to appear enabled on the device page, it may be necessary to refresh the page.