Migrate unique ID of Portainer integration (home-assistant#165123)

Author: erwindouna

homeassistant/components/portainer/__init__.py

@@ -5,6 +5,7 @@
 import logging
 
 from pyportainer import Portainer
+from pyportainer.exceptions import PortainerError
 
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.const import (
@@ -138,6 +139,26 @@ async def async_migrate_entry(hass: HomeAssistant, entry: PortainerConfigEntry)
 
         hass.config_entries.async_update_entry(entry=entry, version=4)
 
+    if entry.version < 5:
+        client = Portainer(
+            api_url=entry.data[CONF_URL],
+            api_key=entry.data[CONF_API_TOKEN],
+            session=async_create_clientsession(
+                hass=hass, verify_ssl=entry.data[CONF_VERIFY_SSL]
+            ),
+        )
+        try:
+            system_status = await client.portainer_system_status()
+        except PortainerError:
+            _LOGGER.exception("Failed to fetch instance ID during migration")
+            return False
+
+        hass.config_entries.async_update_entry(
+            entry=entry,
+            unique_id=system_status.instance_id,
+            version=5,
+        )
+
     return True
 
 

homeassistant/components/portainer/config_flow.py

@@ -12,6 +12,7 @@
     PortainerConnectionError,
     PortainerTimeoutError,
 )
+from pyportainer.models.portainer import PortainerSystemStatus
 import voluptuous as vol
 
 from homeassistant.config_entries import ConfigFlow, ConfigFlowResult
@@ -32,7 +33,9 @@
 )
 
 
-async def _validate_input(hass: HomeAssistant, data: dict[str, Any]) -> None:
+async def _validate_input(
+    hass: HomeAssistant, data: dict[str, Any]
+) -> PortainerSystemStatus:
     """Validate the user input allows us to connect."""
 
     client = Portainer(
@@ -41,7 +44,7 @@ async def _validate_input(hass: HomeAssistant, data: dict[str, Any]) -> None:
         session=async_get_clientsession(hass=hass, verify_ssl=data[CONF_VERIFY_SSL]),
     )
     try:
-        await client.get_endpoints()
+        system_status = await client.portainer_system_status()
     except PortainerAuthenticationError:
         raise InvalidAuth from None
     except PortainerConnectionError as err:
@@ -50,22 +53,22 @@ async def _validate_input(hass: HomeAssistant, data: dict[str, Any]) -> None:
         raise PortainerTimeout from err
 
     _LOGGER.debug("Connected to Portainer API: %s", data[CONF_URL])
+    return system_status
 
 
 class PortainerConfigFlow(ConfigFlow, domain=DOMAIN):
     """Handle a config flow for Portainer."""
 
-    VERSION = 4
+    VERSION = 5
 
     async def async_step_user(
         self, user_input: dict[str, Any] | None = None
     ) -> ConfigFlowResult:
         """Handle the initial step."""
         errors: dict[str, str] = {}
         if user_input is not None:
-            self._async_abort_entries_match({CONF_URL: user_input[CONF_URL]})
             try:
-                await _validate_input(self.hass, user_input)
+                system_status = await _validate_input(self.hass, user_input)
             except CannotConnect:
                 errors["base"] = "cannot_connect"
             except InvalidAuth:
@@ -76,7 +79,7 @@ async def async_step_user(
                 _LOGGER.exception("Unexpected exception")
                 errors["base"] = "unknown"
             else:
-                await self.async_set_unique_id(user_input[CONF_API_TOKEN])
+                await self.async_set_unique_id(system_status.instance_id)
                 self._abort_if_unique_id_configured()
                 return self.async_create_entry(
                     title=user_input[CONF_URL], data=user_input
@@ -142,7 +145,7 @@ async def async_step_reconfigure(
 
         if user_input:
             try:
-                await _validate_input(
+                system_status = await _validate_input(
                     self.hass,
                     data={
                         **reconf_entry.data,
@@ -159,12 +162,8 @@ async def async_step_reconfigure(
                 _LOGGER.exception("Unexpected exception")
                 errors["base"] = "unknown"
             else:
-                # Logic that can be reverted back once the new unique ID is in
-                existing_entry = await self.async_set_unique_id(
-                    user_input[CONF_API_TOKEN]
-                )
-                if existing_entry and existing_entry.entry_id != reconf_entry.entry_id:
-                    return self.async_abort(reason="already_configured")
+                await self.async_set_unique_id(system_status.instance_id)
+                self._abort_if_unique_id_mismatch()
                 return self.async_update_reload_and_abort(
                     reconf_entry,
                     data_updates={

homeassistant/components/portainer/strings.json

@@ -3,7 +3,8 @@
     "abort": {
       "already_configured": "[%key:common::config_flow::abort::already_configured_device%]",
       "reauth_successful": "[%key:common::config_flow::abort::reauth_successful%]",
-      "reconfigure_successful": "[%key:common::config_flow::abort::reconfigure_successful%]"
+      "reconfigure_successful": "[%key:common::config_flow::abort::reconfigure_successful%]",
+      "unique_id_mismatch": "The Portainer instance ID does not match the previously configured instance. This can occur if the device was reset or reconfigured outside of Home Assistant."
     },
     "error": {
       "cannot_connect": "[%key:common::config_flow::error::cannot_connect%]",

tests/components/portainer/conftest.py

@@ -9,7 +9,7 @@
     DockerSystemDF,
 )
 from pyportainer.models.docker_inspect import DockerInfo, DockerVersion
-from pyportainer.models.portainer import Endpoint
+from pyportainer.models.portainer import Endpoint, PortainerSystemStatus
 from pyportainer.models.stacks import Stack
 import pytest
 
@@ -29,6 +29,7 @@
 }
 
 TEST_ENTRY = "portainer_test_entry_123"
+TEST_INSTANCE_ID = "299ab403-70a8-4c05-92f7-bf7a994d50df"
 
 
 @pytest.fixture
@@ -77,6 +78,9 @@ def mock_portainer_client() -> Generator[AsyncMock]:
             Stack.from_dict(stack)
             for stack in load_json_array_fixture("stacks.json", DOMAIN)
         ]
+        client.portainer_system_status.return_value = PortainerSystemStatus.from_dict(
+            load_json_value_fixture("portainer_system_status.json", DOMAIN)
+        )
 
         client.restart_container = AsyncMock(return_value=None)
         client.images_prune = AsyncMock(return_value=None)
@@ -95,7 +99,7 @@ def mock_config_entry() -> MockConfigEntry:
         domain=DOMAIN,
         title="Portainer test",
         data=MOCK_TEST_CONFIG,
-        unique_id=MOCK_TEST_CONFIG[CONF_API_TOKEN],
+        unique_id=TEST_INSTANCE_ID,
         entry_id=TEST_ENTRY,
-        version=2,
+        version=5,
     )

tests/components/portainer/fixtures/portainer_system_status.json

@@ -0,0 +1,4 @@
+{
+  "InstanceID": "299ab403-70a8-4c05-92f7-bf7a994d50df",
+  "Version": "2.0.0"
+}

tests/components/portainer/snapshots/test_diagnostics.ambr

@@ -21,8 +21,8 @@
       'subentries': list([
       ]),
       'title': 'Portainer test',
-      'unique_id': 'test_api_token',
-      'version': 4,
+      'unique_id': '299ab403-70a8-4c05-92f7-bf7a994d50df',
+      'version': 5,
     }),
     'coordinator': dict({
       'endpoints': list([

tests/components/portainer/test_config_flow.py

@@ -7,6 +7,7 @@
     PortainerConnectionError,
     PortainerTimeoutError,
 )
+from pyportainer.models.portainer import PortainerSystemStatus
 import pytest
 
 from homeassistant.components.portainer.const import DOMAIN
@@ -81,7 +82,7 @@ async def test_form_exceptions(
     reason: str,
 ) -> None:
     """Test we handle all exceptions."""
-    mock_portainer_client.get_endpoints.side_effect = exception
+    mock_portainer_client.portainer_system_status.side_effect = exception
 
     result = await hass.config_entries.flow.async_init(
         DOMAIN, context={"source": SOURCE_USER}
@@ -98,7 +99,7 @@ async def test_form_exceptions(
     assert result["type"] is FlowResultType.FORM
     assert result["errors"] == {"base": reason}
 
-    mock_portainer_client.get_endpoints.side_effect = None
+    mock_portainer_client.portainer_system_status.side_effect = None
 
     result = await hass.config_entries.flow.async_configure(
         result["flow_id"],
@@ -199,7 +200,7 @@ async def test_reauth_flow_exceptions(
     """Test we handle all exceptions in the reauth flow."""
     mock_config_entry.add_to_hass(hass)
 
-    mock_portainer_client.get_endpoints.side_effect = exception
+    mock_portainer_client.portainer_system_status.side_effect = exception
 
     result = await hass.config_entries.flow.async_init(
         DOMAIN, context={"source": SOURCE_USER}
@@ -216,7 +217,7 @@ async def test_reauth_flow_exceptions(
     assert result["errors"] == {"base": reason}
 
     # Now test that we can recover from the error
-    mock_portainer_client.get_endpoints.side_effect = None
+    mock_portainer_client.portainer_system_status.side_effect = None
 
     result = await hass.config_entries.flow.async_configure(
         result["flow_id"],
@@ -255,23 +256,17 @@ async def test_full_flow_reconfigure(
     assert len(mock_setup_entry.mock_calls) == 1
 
 
-async def test_full_flow_reconfigure_unique_id(
+async def test_full_flow_reconfigure_unique_id_mismatch(
     hass: HomeAssistant,
     mock_portainer_client: AsyncMock,
     mock_setup_entry: MagicMock,
     mock_config_entry: MockConfigEntry,
 ) -> None:
-    """Test the full flow of the config flow, this time with a known unique ID."""
+    """Test reconfigure aborts when credentials point to a different Portainer instance."""
     mock_config_entry.add_to_hass(hass)
-
-    other_entry = MockConfigEntry(
-        domain=DOMAIN,
-        title="Portainer other",
-        data=USER_INPUT_RECONFIGURE,
-        unique_id=USER_INPUT_RECONFIGURE[CONF_API_TOKEN],
+    mock_portainer_client.portainer_system_status.return_value = PortainerSystemStatus(
+        instance_id="different-instance-id", version="2.0.0"
     )
-    other_entry.add_to_hass(hass)
-
     result = await mock_config_entry.start_reconfigure_flow(hass)
     assert result["type"] is FlowResultType.FORM
     assert result["step_id"] == "reconfigure"
@@ -282,7 +277,7 @@ async def test_full_flow_reconfigure_unique_id(
     )
 
     assert result["type"] is FlowResultType.ABORT
-    assert result["reason"] == "already_configured"
+    assert result["reason"] == "unique_id_mismatch"
     assert mock_config_entry.data[CONF_API_TOKEN] == "test_api_token"
     assert mock_config_entry.data[CONF_URL] == "https://127.0.0.1:9000/"
     assert len(mock_setup_entry.mock_calls) == 0
@@ -323,7 +318,7 @@ async def test_full_flow_reconfigure_exceptions(
     assert result["type"] is FlowResultType.FORM
     assert result["step_id"] == "reconfigure"
 
-    mock_portainer_client.get_endpoints.side_effect = exception
+    mock_portainer_client.portainer_system_status.side_effect = exception
     result = await hass.config_entries.flow.async_configure(
         result["flow_id"],
         user_input=USER_INPUT_RECONFIGURE,
@@ -332,7 +327,7 @@ async def test_full_flow_reconfigure_exceptions(
     assert result["type"] is FlowResultType.FORM
     assert result["errors"] == {"base": reason}
 
-    mock_portainer_client.get_endpoints.side_effect = None
+    mock_portainer_client.portainer_system_status.side_effect = None
     result = await hass.config_entries.flow.async_configure(
         result["flow_id"],
         user_input=USER_INPUT_RECONFIGURE,