qontract-reconcile 0.10.1rc802__py3-none-any.whl → 0.10.1rc803__py3-none-any.whl

{qontract_reconcile-0.10.1rc802.dist-info → qontract_reconcile-0.10.1rc803.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: qontract-reconcile
-Version: 0.10.1rc802
+Version: 0.10.1rc803
 Summary: Collection of tools to reconcile services with their desired state as defined in the app-interface DB.
 Home-page: https://github.com/app-sre/qontract-reconcile
 Author: Red Hat App-SRE Team

{qontract_reconcile-0.10.1rc802.dist-info → qontract_reconcile-0.10.1rc803.dist-info}/RECORD

@@ -433,6 +433,15 @@ reconcile/skupper_network/integration.py,sha256=178Q9RSYuZ9NmrCK4jRMLMekrewUaaRd
 reconcile/skupper_network/models.py,sha256=DNTI7HZv-rqY42GIIxyRuvroHLvdH6rJerjIq9lj3RU,6663
 reconcile/skupper_network/reconciler.py,sha256=XS-1oKBr_1l3dYUAVqUH6gCHg1G5ZuOfY_7fgGVAiFA,9996
 reconcile/skupper_network/site_controller.py,sha256=A3K-62BjJ5HiFVydV0ouGoD1NwrO7XhAH15BHAcS9fk,1550
+reconcile/statuspage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+reconcile/statuspage/atlassian.py,sha256=m8tRECVD_9KnIvqWs6pUocAnmfj2w_eDTFE4il7hkH8,15335
+reconcile/statuspage/integration.py,sha256=hsazrQMceJbr61nEkJLxJbHhudTGtFuH0mlCo66-2ug,711
+reconcile/statuspage/page.py,sha256=DB69C6yAfwZIdo4HBQi8BTUZXL8l9yOPnjnt3k_HZgk,3177
+reconcile/statuspage/state.py,sha256=HD9EOoKm_nEqCMLIwW809En3cq5VhyzKJPUbsh-bae8,1617
+reconcile/statuspage/status.py,sha256=mfRJ_tW7jM4_Vy_1cc8C0fKJEoA2GwrA3gJeV1KImAw,2834
+reconcile/statuspage/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+reconcile/statuspage/integrations/components.py,sha256=49KHd_E9AdRvcEA6n75q1McZv2LfN-hRsW-WA7dgw9g,2651
+reconcile/statuspage/integrations/maintenances.py,sha256=pwt3WHymfkqP7ox1GB-D6Wn0crmcrDE_p4SW9wRaqWE,2651
 reconcile/templates/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 reconcile/templates/aws_access_key_email.j2,sha256=2MUr1ERmyISzKgHqsWYLd-1Wbl-peUa-FsGUS-JLUFc,238
 reconcile/templates/email.yml.j2,sha256=OZgczNRgXPj2gVYTgwQyHAQrMGu7xp-e4W1rX19GcrU,690
@@ -788,8 +797,8 @@ tools/test/test_app_interface_metrics_exporter.py,sha256=SX7qL3D1SIRKFo95FoQztvf
 tools/test/test_qontract_cli.py,sha256=_D61RFGAN5x44CY1tYbouhlGXXABwYfxKSWSQx3Jrss,4941
 tools/test/test_sd_app_sre_alert_report.py,sha256=v363r9zM7__0kR5K6mvJoGFcM9BvE33fWAayrqkpojA,2116
 tools/test/test_sre_checkpoints.py,sha256=SKqPPTl9ua0RFdSSofnoQX-JZE6dFLO3LRhfQzqtfh8,2607
-qontract_reconcile-0.10.1rc802.dist-info/METADATA,sha256=ZX90nMGQNMCTXIBib8Objt33uoTAraXDTmTSXq6tdtQ,2314
-qontract_reconcile-0.10.1rc802.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-qontract_reconcile-0.10.1rc802.dist-info/entry_points.txt,sha256=rIxI5zWtHNlfpDeq1a7pZXAPoqf7HG32KMTN3MeWK_8,429
-qontract_reconcile-0.10.1rc802.dist-info/top_level.txt,sha256=l5ISPoXzt0SdR4jVdkfa7RPSKNc8zAHYWAnR-Dw8Ey8,24
-qontract_reconcile-0.10.1rc802.dist-info/RECORD,,
+qontract_reconcile-0.10.1rc803.dist-info/METADATA,sha256=NTfgWm43JS7pKaeQtl4uuf73kEQxGqfhtxg1alCle_E,2314
+qontract_reconcile-0.10.1rc803.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+qontract_reconcile-0.10.1rc803.dist-info/entry_points.txt,sha256=rIxI5zWtHNlfpDeq1a7pZXAPoqf7HG32KMTN3MeWK_8,429
+qontract_reconcile-0.10.1rc803.dist-info/top_level.txt,sha256=l5ISPoXzt0SdR4jVdkfa7RPSKNc8zAHYWAnR-Dw8Ey8,24
+qontract_reconcile-0.10.1rc803.dist-info/RECORD,,

reconcile/statuspage/atlassian.py

@@ -0,0 +1,425 @@
+import logging
+import time
+from typing import (
+    Any,
+    Optional,
+    Self,
+)
+
+import requests
+from pydantic import BaseModel
+from requests import Response
+from sretoolbox.utils import retry
+
+from reconcile.gql_definitions.statuspage.statuspages import StatusPageV1
+from reconcile.statuspage.page import (
+    StatusComponent,
+    StatusMaintenance,
+    StatusPage,
+)
+from reconcile.statuspage.state import ComponentBindingState
+from reconcile.statuspage.status import ManualStatusProvider
+
+
+class AtlassianRawComponent(BaseModel):
+    """
+    atlassian status page REST schema for component
+    """
+
+    id: str
+    name: str
+    description: Optional[str]
+    position: int
+    status: str
+    automation_email: Optional[str]
+    group_id: Optional[str]
+    group: Optional[bool]
+
+
+class AtlassianRawMaintenanceUpdate(BaseModel):
+    """
+    atlassian status page REST schema for maintenance updates
+    """
+
+    body: str
+
+
+class AtlassianRawMaintenance(BaseModel):
+    """
+    atlassian status page REST schema for maintenance
+    """
+
+    id: str
+    name: str
+    scheduled_for: str
+    scheduled_until: str
+    incident_updates: list[AtlassianRawMaintenanceUpdate]
+
+
+class AtlassianAPI:
+    """
+    This API class wraps the statuspageio REST API for basic component operations.
+    """
+
+    def __init__(self, page_id: str, api_url: str, token: str):
+        self.page_id = page_id
+        self.api_url = api_url
+        self.token = token
+        self.auth_headers = {"Authorization": f"OAuth {self.token}"}
+
+    @retry(max_attempts=10)
+    def _do_get(self, url: str, params: dict[str, Any]) -> Response:
+        response = requests.get(
+            url, params=params, headers=self.auth_headers, timeout=30
+        )
+        response.raise_for_status()
+        return response
+
+    def _list_items(self, url: str) -> list[Any]:
+        all_items: list[Any] = []
+        page = 1
+        per_page = 100
+        while True:
+            params = {"page": page, "per_page": per_page}
+            response = self._do_get(url, params=params)
+            items = response.json()
+            all_items += items
+            if len(items) < per_page:
+                break
+            page += 1
+            # https://developer.statuspage.io/#section/Rate-Limiting
+            # Each API token is limited to 1 request / second as measured on a 60 second rolling window
+            time.sleep(1)
+
+        return all_items
+
+    def list_components(self) -> list[AtlassianRawComponent]:
+        url = f"{self.api_url}/v1/pages/{self.page_id}/components"
+        all_components = self._list_items(url)
+        return [AtlassianRawComponent(**c) for c in all_components]
+
+    def update_component(self, id: str, data: dict[str, Any]) -> None:
+        url = f"{self.api_url}/v1/pages/{self.page_id}/components/{id}"
+        requests.patch(
+            url, json={"component": data}, headers=self.auth_headers
+        ).raise_for_status()
+
+    def create_component(self, data: dict[str, Any]) -> str:
+        url = f"{self.api_url}/v1/pages/{self.page_id}/components"
+        response = requests.post(
+            url, json={"component": data}, headers=self.auth_headers
+        )
+        response.raise_for_status()
+        return response.json()["id"]
+
+    def delete_component(self, id: str) -> None:
+        url = f"{self.api_url}/v1/pages/{self.page_id}/components/{id}"
+        requests.delete(url, headers=self.auth_headers).raise_for_status()
+
+    def list_scheduled_maintenances(self) -> list[AtlassianRawMaintenance]:
+        url = f"{self.api_url}/v1/pages/{self.page_id}/incidents/scheduled"
+        all_scheduled_incidents = self._list_items(url)
+        return [AtlassianRawMaintenance(**i) for i in all_scheduled_incidents]
+
+    def create_incident(self, data: dict[str, Any]) -> str:
+        url = f"{self.api_url}/v1/pages/{self.page_id}/incidents"
+        response = requests.post(
+            url, json={"incident": data}, headers=self.auth_headers
+        )
+        response.raise_for_status()
+        return response.json()["id"]
+
+
+class AtlassianStatusPageProvider:
+    """
+    The provider implements CRUD operations for Atlassian status pages.
+    It also takes care of a mixed set of components on a page, where some
+    components are managed by app-interface and some are managed manually
+    by various teams. The term `bound` used throughout the code refers to
+    components that are managed by app-interface. The binding status is
+    managed by the injected `ComponentBindingState` instance and persists
+    the binding information (what app-interface component name is bound to
+    what status page component id).
+    """
+
+    def __init__(
+        self,
+        page_name: str,
+        api: AtlassianAPI,
+        component_binding_state: ComponentBindingState,
+    ):
+        self.page_name = page_name
+        self._api = api
+        self._binding_state = component_binding_state
+
+        # component cache
+        self._components: list[AtlassianRawComponent] = []
+        self._components_by_id: dict[str, AtlassianRawComponent] = {}
+        self._components_by_displayname: dict[str, AtlassianRawComponent] = {}
+        self._group_name_to_id: dict[str, str] = {}
+        self._group_id_to_name: dict[str, str] = {}
+        self._build_component_cache()
+
+    def _build_component_cache(self):
+        self._components = self._api.list_components()
+        self._components_by_id = {c.id: c for c in self._components}
+        self._components_by_displayname = {c.name: c for c in self._components}
+        self._group_name_to_id = {g.name: g.id for g in self._components if g.group}
+        self._group_id_to_name = {g.id: g.name for g in self._components if g.group}
+
+    def get_component_by_id(self, id: str) -> Optional[StatusComponent]:
+        raw = self.get_raw_component_by_id(id)
+        if raw:
+            return self._bound_raw_component_to_status_component(raw)
+        return None
+
+    def get_raw_component_by_id(self, id: str) -> Optional[AtlassianRawComponent]:
+        return self._components_by_id.get(id)
+
+    def get_current_page(self) -> StatusPage:
+        """
+        Builds a StatusPage instance from the current state of the page. This
+        way the current state of the page can be compared to the desired state
+        of the page coming from GQL.
+        """
+        components = [
+            self._bound_raw_component_to_status_component(c) for c in self._components
+        ]
+        return StatusPage(
+            name=self.page_name,
+            components=[c for c in components if c is not None],
+        )
+
+    def _bound_raw_component_to_status_component(
+        self, raw_component: AtlassianRawComponent
+    ) -> Optional[StatusComponent]:
+        bound_component_name = self._binding_state.get_name_for_component_id(
+            raw_component.id
+        )
+        if bound_component_name:
+            group_name = (
+                self._group_id_to_name.get(raw_component.group_id)
+                if raw_component.group_id
+                else None
+            )
+            return StatusComponent(
+                name=bound_component_name,
+                display_name=raw_component.name,
+                description=raw_component.description,
+                group_name=group_name,
+                status_provider_configs=[
+                    ManualStatusProvider(
+                        component_status=raw_component.status,
+                    )
+                ],
+            )
+        return None
+
+    def lookup_component(
+        self, desired_component: StatusComponent
+    ) -> tuple[Optional[AtlassianRawComponent], bool]:
+        """
+        Finds the component on the page that matches the desired component. This
+        is either done explicitely by using binding information if available or
+        by using the display name of the desired component to find a matching
+        component on the page. This way, this provider offers adoption logic
+        for existing components on the page that are not yes bound to app-interface.
+        """
+        component_id = self._binding_state.get_id_for_component_name(
+            desired_component.name
+        )
+        component = None
+        bound = True
+        if component_id:
+            component = self.get_raw_component_by_id(component_id)
+
+        if component is None:
+            bound = False
+            # either the component name is not bound to an ID or for whatever
+            # reason or the component is not found on the page anymore
+            component = self._components_by_displayname.get(
+                desired_component.display_name
+            )
+            if component and self._binding_state.get_name_for_component_id(
+                component.id
+            ):
+                # this component is already bound to a different component
+                # in app-interface. we are protecting this binding here by
+                # not allowing this component to be found via display name
+                component = None
+
+        return component, bound
+
+    def should_apply(
+        self, desired: StatusComponent, current: Optional[AtlassianRawComponent]
+    ) -> bool:
+        """
+        Verifies if the desired component should be applied to the status page
+        when compared to the current state of the component on the page.
+        """
+        current_group_name = (
+            self._group_id_to_name.get(current.group_id)
+            if current and current.group_id
+            else None
+        )
+
+        # check if group exists
+        group_id = None
+        if desired.group_name:
+            group_id = self._group_name_to_id.get(desired.group_name, None)
+            if not group_id:
+                raise ValueError(
+                    f"Group {desired.group_name} referenced "
+                    f"by {desired.name} does not exist"
+                )
+
+        # Special handling if a component needs to be moved out of any grouping.
+        # We would need to use the component_group endpoint but for not lets
+        # ignore this situation.
+        if current and current_group_name and not desired.group_name:
+            raise ValueError(
+                f"Remove grouping from the component "
+                f"{desired.group_name} is currently unsupported"
+            )
+
+        # component status
+        desired_component_status = desired.desired_component_status()
+        status_update_required = desired_component_status is not None and (
+            not current or desired_component_status != current.status
+        )
+
+        # shortcut execution if there is nothing to do
+        update_required = (
+            current is None
+            or desired.display_name != current.name
+            or desired.description != current.description
+            or desired.group_name != current_group_name
+            or status_update_required
+        )
+        return update_required
+
+    def apply_component(self, dry_run: bool, desired: StatusComponent) -> None:
+        current_component, bound = self.lookup_component(desired)
+
+        # if the component is not yet bound to a statuspage component, bind it now
+        if current_component and not bound:
+            self._bind_component(
+                dry_run=dry_run,
+                component_name=desired.name,
+                component_id=current_component.id,
+            )
+
+        # validte the component and check if the current state needs to be updated
+        needs_update = self.should_apply(desired, current_component)
+        if not needs_update:
+            return
+
+        # calculate update
+        component_update = {
+            "name": desired.display_name,
+            "description": desired.description,
+        }
+
+        # resolve group
+        group_id = (
+            self._group_name_to_id.get(desired.group_name, None)
+            if desired.group_name
+            else None
+        )
+        if group_id:
+            component_update["group_id"] = group_id
+
+        # resolve status
+        desired_component_status = desired.desired_component_status()
+        if desired_component_status:
+            component_update["status"] = desired_component_status
+
+        if current_component:
+            logging.info(f"update component {desired.name}: {component_update}")
+            if not dry_run:
+                self._api.update_component(current_component.id, component_update)
+        else:
+            logging.info(f"create component {desired.name}: {component_update}")
+            if not dry_run:
+                component_id = self._api.create_component(component_update)
+                self._bind_component(
+                    dry_run=dry_run,
+                    component_name=desired.name,
+                    component_id=component_id,
+                )
+
+    def delete_component(self, dry_run: bool, component_name: str) -> None:
+        component_id = self._binding_state.get_id_for_component_name(component_name)
+        if component_id:
+            if not dry_run:
+                self._api.delete_component(component_id)
+                self._binding_state.forget_component(component_name)
+                self._build_component_cache()
+        else:
+            logging.warning(
+                f"can't delete component {component_name} because it is not "
+                f"bound to any component on page {self.page_name}"
+            )
+
+    def has_component_binding_for(self, component_name: str) -> bool:
+        return self._binding_state.get_id_for_component_name(component_name) is not None
+
+    def _bind_component(
+        self,
+        dry_run: bool,
+        component_name: str,
+        component_id: str,
+    ) -> None:
+        logging.info(
+            f"bind component {component_name} to ID {component_id} "
+            f"on page {self.page_name}"
+        )
+        if not dry_run:
+            self._binding_state.bind_component(component_name, component_id)
+
+    @classmethod
+    def init_from_page(
+        cls,
+        page: StatusPageV1,
+        token: str,
+        component_binding_state: ComponentBindingState,
+    ) -> Self:
+        """
+        Initializes the provider for atlassian status page.
+        """
+        return cls(
+            page_name=page.name,
+            api=AtlassianAPI(
+                page_id=page.page_id,
+                api_url=page.api_url,
+                token=token,
+            ),
+            component_binding_state=component_binding_state,
+        )
+
+    @property
+    def maintenances(self) -> list[StatusMaintenance]:
+        return [
+            StatusMaintenance(
+                name=m.name,
+                message=m.incident_updates[0].body,
+                schedule_start=m.scheduled_for,
+                schedule_end=m.scheduled_until,
+            )
+            for m in self._api.list_scheduled_maintenances()
+        ]
+
+    def create_maintenance(self, maintenance: StatusMaintenance) -> None:
+        data = {
+            "name": maintenance.name,
+            "status": "scheduled",
+            "scheduled_for": maintenance.schedule_start,
+            "scheduled_until": maintenance.schedule_end,
+            "body": maintenance.message,
+        }
+        incident_id = self._api.create_incident(data)
+        self._bind_component(
+            dry_run=False,
+            component_name=maintenance.name,
+            component_id=incident_id,
+        )

reconcile/statuspage/integration.py

@@ -0,0 +1,22 @@
+from reconcile.gql_definitions.statuspage import statuspages
+from reconcile.gql_definitions.statuspage.statuspages import StatusPageV1
+from reconcile.statuspage.state import S3ComponentBindingState
+from reconcile.utils import gql
+from reconcile.utils.secret_reader import (
+    SecretReaderBase,
+)
+from reconcile.utils.state import init_state
+
+
+def get_status_pages() -> list[StatusPageV1]:
+    return statuspages.query(gql.get_api().query).status_pages or []
+
+
+def get_binding_state(
+    integration: str, secret_reader: SecretReaderBase
+) -> S3ComponentBindingState:
+    state = init_state(
+        integration=integration,
+        secret_reader=secret_reader,
+    )
+    return S3ComponentBindingState(state)

reconcile/statuspage/integrations/components.py

@@ -0,0 +1,77 @@
+import logging
+import sys
+
+from reconcile.statuspage.atlassian import AtlassianStatusPageProvider
+from reconcile.statuspage.integration import get_binding_state, get_status_pages
+from reconcile.statuspage.page import StatusPage
+from reconcile.utils.runtime.integration import (
+    NoParams,
+    QontractReconcileIntegration,
+)
+from reconcile.utils.semver_helper import make_semver
+
+QONTRACT_INTEGRATION = "status-page-components"
+QONTRACT_INTEGRATION_VERSION = make_semver(0, 1, 0)
+
+
+class StatusPageComponentsIntegration(QontractReconcileIntegration[NoParams]):
+    def __init__(self) -> None:
+        super().__init__(NoParams())
+
+    @property
+    def name(self) -> str:
+        return QONTRACT_INTEGRATION
+
+    def reconcile(
+        self,
+        dry_run: bool,
+        desired_state: StatusPage,
+        current_state: StatusPage,
+        provider: AtlassianStatusPageProvider,
+    ) -> None:
+        """
+        Reconcile the desired state with the current state of a status page.
+        """
+        #
+        # D E L E T E
+        #
+        desired_component_names = {c.name for c in desired_state.components}
+        current_component_names = {c.name for c in current_state.components}
+        component_names_to_delete = current_component_names - desired_component_names
+        for component_name in component_names_to_delete:
+            logging.info(
+                f"delete component {component_name} from page {desired_state.name}"
+            )
+            provider.delete_component(dry_run, component_name)
+
+        #
+        # C R E A T E   OR   U P D A T E
+        #
+        for desired in desired_state.components:
+            provider.apply_component(dry_run, desired)
+
+    def run(self, dry_run: bool = False) -> None:
+        binding_state = get_binding_state(self.name, self.secret_reader)
+        pages = get_status_pages()
+
+        error = False
+        for p in pages:
+            try:
+                desired_state = StatusPage.init_from_page(p)
+                page_provider = AtlassianStatusPageProvider.init_from_page(
+                    page=p,
+                    token=self.secret_reader.read_secret(p.credentials),
+                    component_binding_state=binding_state,
+                )
+                self.reconcile(
+                    dry_run,
+                    desired_state=desired_state,
+                    current_state=page_provider.get_current_page(),
+                    provider=page_provider,
+                )
+            except Exception:
+                logging.exception(f"failed to reconcile statuspage {p.name}")
+                error = True
+
+        if error:
+            sys.exit(1)

reconcile/statuspage/integrations/maintenances.py

@@ -0,0 +1,73 @@
+import logging
+import sys
+
+from reconcile.statuspage.atlassian import AtlassianStatusPageProvider
+from reconcile.statuspage.integration import get_binding_state, get_status_pages
+from reconcile.statuspage.page import StatusMaintenance
+from reconcile.utils.differ import diff_iterables
+from reconcile.utils.runtime.integration import (
+    NoParams,
+    QontractReconcileIntegration,
+)
+from reconcile.utils.semver_helper import make_semver
+
+QONTRACT_INTEGRATION = "status-page-maintenances"
+QONTRACT_INTEGRATION_VERSION = make_semver(0, 1, 0)
+
+
+class StatusPageMaintenancesIntegration(QontractReconcileIntegration[NoParams]):
+    @property
+    def name(self) -> str:
+        return QONTRACT_INTEGRATION
+
+    def reconcile(
+        self,
+        dry_run: bool,
+        desired_state: list[StatusMaintenance],
+        current_state: list[StatusMaintenance],
+        provider: AtlassianStatusPageProvider,
+    ) -> None:
+        diff = diff_iterables(
+            current=current_state, desired=desired_state, key=lambda x: x.name
+        )
+        for a in diff.add.values():
+            logging.info(f"Create StatusPage Maintenance: {a.name}")
+            if not dry_run:
+                provider.create_maintenance(a)
+        for c in diff.change.values():
+            raise NotImplementedError(
+                f"Update StatusPage Maintenance is not supported at this time: {c.desired.name}"
+            )
+        for d in diff.delete.values():
+            raise NotImplementedError(
+                f"Delete StatusPage Maintenance is not supported at this time: {d.name}"
+            )
+
+    def run(self, dry_run: bool = False) -> None:
+        binding_state = get_binding_state(self.name, self.secret_reader)
+        pages = get_status_pages()
+
+        error = False
+        for p in pages:
+            try:
+                desired_state = [
+                    StatusMaintenance.init_from_maintenance(m)
+                    for m in p.maintenances or []
+                ]
+                page_provider = AtlassianStatusPageProvider.init_from_page(
+                    page=p,
+                    token=self.secret_reader.read_secret(p.credentials),
+                    component_binding_state=binding_state,
+                )
+                self.reconcile(
+                    dry_run=dry_run,
+                    desired_state=desired_state,
+                    current_state=page_provider.maintenances,
+                    provider=page_provider,
+                )
+            except Exception:
+                logging.exception(f"failed to reconcile statuspage {p.name}")
+                error = True
+
+        if error:
+            sys.exit(1)

reconcile/statuspage/page.py

@@ -0,0 +1,114 @@
+from typing import Optional, Self
+
+from pydantic import BaseModel
+
+from reconcile.gql_definitions.statuspage.statuspages import (
+    MaintenanceV1,
+    StatusPageComponentV1,
+    StatusPageV1,
+)
+from reconcile.statuspage.status import (
+    StatusProvider,
+    build_status_provider_config,
+)
+
+
+class StatusComponent(BaseModel):
+    """
+    Represents a status page component from the desired state.
+    """
+
+    name: str
+    display_name: str
+    description: Optional[str]
+    group_name: Optional[str]
+    status_provider_configs: list[StatusProvider]
+    """
+    Status provider configs hold different ways for a component to determine its status
+    """
+
+    def status_management_enabled(self) -> bool:
+        """
+        Determines if this component has any status configurations available for
+        it to be able to manage its status.
+        """
+        return bool(self.status_provider_configs)
+
+    def desired_component_status(self) -> Optional[str]:
+        if self.status_management_enabled():
+            for provider in self.status_provider_configs:
+                status = provider.get_status()
+                if status:
+                    return status
+            return "operational"
+        return None
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    @classmethod
+    def init_from_page_component(cls, component: StatusPageComponentV1) -> Self:
+        status_configs = [
+            build_status_provider_config(cfg) for cfg in component.status_config or []
+        ]
+        return cls(
+            name=component.name,
+            display_name=component.display_name,
+            description=component.description,
+            group_name=component.group_name,
+            status_provider_configs=[c for c in status_configs if c is not None],
+        )
+
+
+class StatusPage(BaseModel):
+    """
+    Represents the desired state of a status page and its components.
+    """
+
+    name: str
+    """
+    The name of the status page.
+    """
+
+    components: list[StatusComponent]
+    """
+    The desired components of the status page are represented in this list.
+    Important note: the actual status page might have more components than
+    this desired state does. People can still manage components manually.
+    """
+
+    @classmethod
+    def init_from_page(
+        cls,
+        page: StatusPageV1,
+    ) -> Self:
+        """
+        Translate a desired state status page into a status page object.
+        """
+        return cls(
+            name=page.name,
+            components=[
+                StatusComponent.init_from_page_component(component=c)
+                for c in page.components or []
+            ],
+        )
+
+
+class StatusMaintenance(BaseModel):
+    """
+    Represents the desired state of a status maintenance.
+    """
+
+    name: str
+    message: str
+    schedule_start: str
+    schedule_end: str
+
+    @classmethod
+    def init_from_maintenance(cls, maintenance: MaintenanceV1) -> Self:
+        return cls(
+            name=maintenance.name,
+            message=maintenance.message.rstrip("\n"),
+            schedule_start=maintenance.scheduled_start,
+            schedule_end=maintenance.scheduled_end,
+        )

reconcile/statuspage/state.py

@@ -0,0 +1,47 @@
+from typing import (
+    Optional,
+    Protocol,
+)
+
+from reconcile.utils.state import State
+
+# This module manages the binding state of components in the desired state
+# and their representation on an actual status page.
+#
+# This state management is required to map component identities between app-interface
+# and the status page provider.
+
+
+class ComponentBindingState(Protocol):
+    def get_id_for_component_name(self, component_name: str) -> Optional[str]: ...
+
+    def get_name_for_component_id(self, component_id: str) -> Optional[str]: ...
+
+    def bind_component(self, component_name: str, component_id: str) -> None: ...
+
+    def forget_component(self, component_name: str) -> None: ...
+
+
+class S3ComponentBindingState(ComponentBindingState):
+    def __init__(self, state: State):
+        self.state = state
+        self._update_cache()
+
+    def _update_cache(self) -> None:
+        self.name_to_id_cache: dict[str, str] = self.state.get_all("")
+        self.id_to_name_cache: dict[str, str] = {
+            v: k for k, v in self.name_to_id_cache.items()
+        }
+
+    def get_id_for_component_name(self, component_name: str) -> Optional[str]:
+        return self.name_to_id_cache.get(component_name)
+
+    def get_name_for_component_id(self, component_id: str) -> Optional[str]:
+        return self.id_to_name_cache.get(component_id)
+
+    def bind_component(self, component_name: str, component_id: str) -> None:
+        self.state.add(component_name, component_id, force=True)
+        self._update_cache()
+
+    def forget_component(self, component_name: str) -> None:
+        self.state.rm(component_name)

reconcile/statuspage/status.py

@@ -0,0 +1,97 @@
+from abc import (
+    ABC,
+    abstractmethod,
+)
+from datetime import (
+    datetime,
+    timezone,
+)
+from typing import Optional
+
+from dateutil.parser import isoparse
+from pydantic import BaseModel
+
+from reconcile.gql_definitions.statuspage.statuspages import (
+    ManualStatusProviderV1,
+    StatusProviderV1,
+)
+
+# This module defines the interface for status providers for components on status
+# pages. A status provider is responsible for determining the status of a component.
+# This status will then be used to update the status page component.
+
+
+class StatusProvider(ABC):
+    """
+    The generic static provider interface that can be used to determine the
+    status of a component.
+    """
+
+    @abstractmethod
+    def get_status(self) -> Optional[str]: ...
+
+
+class ManualStatusProvider(StatusProvider, BaseModel):
+    """
+    This status provider is used to manually define the status of a component.
+    An optional time windows can be defined in which the status is applied to
+    the component.
+    """
+
+    start: Optional[datetime] = None
+    """
+    The optional start time of the time window in which the manually
+    defined status is active.
+    """
+
+    end: Optional[datetime] = None
+    """
+    The optional end time of the time window in which the manually
+    defined status is active.
+    """
+
+    component_status: str
+    """
+    The status to be used for the component if the
+    time window is active or if no time window is defined.
+    """
+
+    def get_status(self) -> Optional[str]:
+        if self._is_active():
+            return self.component_status
+        return None
+
+    def _is_active(self) -> bool:
+        """
+        Returns true if the config is active in regards to the start and
+        end time window. If no time window is defined, the config is always
+        active.
+        """
+        if self.start and self.end and self.end < self.start:
+            raise ValueError(
+                "manual component status time window is invalid: end before start"
+            )
+        now = datetime.now(timezone.utc)
+        if self.start and now < self.start:
+            return False
+        if self.end and self.end < now:
+            return False
+        return True
+
+
+def build_status_provider_config(
+    cfg: StatusProviderV1,
+) -> Optional[StatusProvider]:
+    """
+    Translates a status provider config from the desired state into
+    provider specific implementation that provides the status resolution logic.
+    """
+    if isinstance(cfg, ManualStatusProviderV1):
+        start = isoparse(cfg.manual.q_from) if cfg.manual.q_from else None
+        end = isoparse(cfg.manual.until) if cfg.manual.until else None
+        return ManualStatusProvider(
+            component_status=cfg.manual.component_status,
+            start=start,
+            end=end,
+        )
+    return None