Proxmox VE Custom Integration Home Assistant

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.

Install

Installation via HACS

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.

Manual installation

Copy proxmoxve folder from latest release to custom_components folder in your config directory.
Restart the Home Assistant.

Configuration

Adding Proxmox VE to your Home Assistant instance can be done via the UI using this button:

You can either use password or token based authentication. For user based authentication leave the token name field empty. If you want to use token based authentication, fill the token name in the corresponding input field and put your token secret in the password field.

Manual Configuration

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.

Debugging

To enable debug for Proxmox VE integration, add following to your configuration.yaml:

logger:
  default: info
  logs:
    custom_components.proxmoxve: debug

Example screenshot:

Node
VM (QEMU)
Storage
Physical disks

Proxmox Permissions

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.

Suggestion for creating permission roles for use with integration

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

Create Home Assistant Group

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 click Groups
Click the Create button above all the existing groups
Name the new group (e.g., HomeAssistant)
Click Create

Add Group Permissions to all Assets

Click Datacenter
Click Permissions
Open Add and click Group 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

Create Home Assistant User

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 click Users
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 and Expire is set to "never"
Click Add

In your Home Assistant configuration, use homeassistant@pve for the username and your chosen password for the password.

Some entities are disabled by default (including control buttons), see below how to enable them.

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.