installers/charm/osm-temporal/lib/charms/osm_libs/v0/utils.py

   1 #!/usr/bin/env python3
   2 # Copyright 2022 Canonical Ltd.
   3 # See LICENSE file for licensing details.
   4 #         http://www.apache.org/licenses/LICENSE-2.0
   5 """OSM Utils Library.
   6
   7 This library offers some utilities made for but not limited to Charmed OSM.
   8
   9 # Getting started
  10
  11 Execute the following command inside your Charmed Operator folder to fetch the library.
  12
  13 ```shell
  14 charmcraft fetch-lib charms.osm_libs.v0.utils
  15 ```
  16
  17 # CharmError Exception
  18
  19 An exception that takes to arguments, the message and the StatusBase class, which are useful
  20 to set the status of the charm when the exception raises.
  21
  22 Example:
  23 ```shell
  24 from charms.osm_libs.v0.utils import CharmError
  25
  26 class MyCharm(CharmBase):
  27     def _on_config_changed(self, _):
  28         try:
  29             if not self.config.get("some-option"):
  30                 raise CharmError("need some-option", BlockedStatus)
  31
  32             if not self.mysql_ready:
  33                 raise CharmError("waiting for mysql", WaitingStatus)
  34
  35             # Do stuff...
  36
  37         exception CharmError as e:
  38             self.unit.status = e.status
  39 ```
  40
  41 # Pebble validations
  42
  43 The `check_container_ready` function checks that a container is ready,
  44 and therefore Pebble is ready.
  45
  46 The `check_service_active` function checks that a service in a container is running.
  47
  48 Both functions raise a CharmError if the validations fail.
  49
  50 Example:
  51 ```shell
  52 from charms.osm_libs.v0.utils import check_container_ready, check_service_active
  53
  54 class MyCharm(CharmBase):
  55     def _on_config_changed(self, _):
  56         try:
  57             container: Container = self.unit.get_container("my-container")
  58             check_container_ready(container)
  59             check_service_active(container, "my-service")
  60             # Do stuff...
  61
  62         exception CharmError as e:
  63             self.unit.status = e.status
  64 ```
  65
  66 # Debug-mode
  67
  68 The debug-mode allows OSM developers to easily debug OSM modules.
  69
  70 Example:
  71 ```shell
  72 from charms.osm_libs.v0.utils import DebugMode
  73
  74 class MyCharm(CharmBase):
  75     _stored = StoredState()
  76
  77     def __init__(self, _):
  78         # ...
  79         container: Container = self.unit.get_container("my-container")
  80         hostpaths = [
  81             HostPath(
  82                 config="module-hostpath",
  83                 container_path="/usr/lib/python3/dist-packages/module"
  84             ),
  85         ]
  86         vscode_workspace_path = "files/vscode-workspace.json"
  87         self.debug_mode = DebugMode(
  88             self,
  89             self._stored,
  90             container,
  91             hostpaths,
  92             vscode_workspace_path,
  93         )
  94
  95     def _on_update_status(self, _):
  96         if self.debug_mode.started:
  97             return
  98         # ...
  99
 100     def _get_debug_mode_information(self):
 101         command = self.debug_mode.command
 102         password = self.debug_mode.password
 103         return command, password
 104 ```
 105
 106 # More
 107
 108 - Get pod IP with `get_pod_ip()`
 109 """
 110 from dataclasses import dataclass
 111 import logging
 112 import secrets
 113 import socket
 114 from pathlib import Path
 115 from typing import List
 116
 117 from lightkube import Client
 118 from lightkube.models.core_v1 import HostPathVolumeSource, Volume, VolumeMount
 119 from lightkube.resources.apps_v1 import StatefulSet
 120 from ops.charm import CharmBase
 121 from ops.framework import Object, StoredState
 122 from ops.model import (
 123     ActiveStatus,
 124     BlockedStatus,
 125     Container,
 126     MaintenanceStatus,
 127     StatusBase,
 128     WaitingStatus,
 129 )
 130 from ops.pebble import ServiceStatus
 131
 132 # The unique Charmhub library identifier, never change it
 133 LIBID = "e915908eebee4cdd972d484728adf984"
 134
 135 # Increment this major API version when introducing breaking changes
 136 LIBAPI = 0
 137
 138 # Increment this PATCH version before using `charmcraft publish-lib` or reset
 139 # to 0 if you are raising the major API version
 140 LIBPATCH = 3
 141
 142 logger = logging.getLogger(__name__)
 143
 144
 145 class CharmError(Exception):
 146     """Charm Error Exception."""
 147
 148     def __init__(self, message: str, status_class: StatusBase = BlockedStatus) -> None:
 149         self.message = message
 150         self.status_class = status_class
 151         self.status = status_class(message)
 152
 153
 154 def check_container_ready(container: Container) -> None:
 155     """Check Pebble has started in the container.
 156
 157     Args:
 158         container (Container): Container to be checked.
 159
 160     Raises:
 161         CharmError: if container is not ready.
 162     """
 163     if not container.can_connect():
 164         raise CharmError("waiting for pebble to start", MaintenanceStatus)
 165
 166
 167 def check_service_active(container: Container, service_name: str) -> None:
 168     """Check if the service is running.
 169
 170     Args:
 171         container (Container): Container to be checked.
 172         service_name (str): Name of the service to check.
 173
 174     Raises:
 175         CharmError: if the service is not running.
 176     """
 177     if service_name not in container.get_plan().services:
 178         raise CharmError(f"{service_name} service not configured yet", WaitingStatus)
 179
 180     if container.get_service(service_name).current != ServiceStatus.ACTIVE:
 181         raise CharmError(f"{service_name} service is not running")
 182
 183
 184 def get_pod_ip() -> str:
 185     """Get Kubernetes Pod IP.
 186
 187     Returns:
 188         str: The IP of the Pod.
 189     """
 190     return socket.gethostbyname(socket.gethostname())
 191
 192
 193 _DEBUG_SCRIPT = r"""#!/bin/bash
 194 # Install SSH
 195
 196 function download_code(){{
 197     wget https://go.microsoft.com/fwlink/?LinkID=760868 -O code.deb
 198 }}
 199
 200 function setup_envs(){{
 201     grep "source /debug.envs" /root/.bashrc || echo "source /debug.envs" | tee -a /root/.bashrc
 202 }}
 203 function setup_ssh(){{
 204     apt install ssh -y
 205     cat /etc/ssh/sshd_config |
 206         grep -E '^PermitRootLogin yes$$' || (
 207         echo PermitRootLogin yes |
 208         tee -a /etc/ssh/sshd_config
 209     )
 210     service ssh stop
 211     sleep 3
 212     service ssh start
 213     usermod --password $(echo {} | openssl passwd -1 -stdin) root
 214 }}
 215
 216 function setup_code(){{
 217     apt install libasound2 -y
 218     (dpkg -i code.deb || apt-get install -f -y || apt-get install -f -y) && echo Code installed successfully
 219     code --install-extension ms-python.python --user-data-dir /root
 220     mkdir -p /root/.vscode-server
 221     cp -R /root/.vscode/extensions /root/.vscode-server/extensions
 222 }}
 223
 224 export DEBIAN_FRONTEND=noninteractive
 225 apt update && apt install wget -y
 226 download_code &
 227 setup_ssh &
 228 setup_envs
 229 wait
 230 setup_code &
 231 wait
 232 """
 233
 234
 235 @dataclass
 236 class SubModule:
 237     """Represent RO Submodules."""
 238
 239     sub_module_path: str
 240     container_path: str
 241
 242
 243 class HostPath:
 244     """Represents a hostpath."""
 245
 246     def __init__(self, config: str, container_path: str, submodules: dict = None) -> None:
 247         mount_path_items = config.split("-")
 248         mount_path_items.reverse()
 249         self.mount_path = "/" + "/".join(mount_path_items)
 250         self.config = config
 251         self.sub_module_dict = {}
 252         if submodules:
 253             for submodule in submodules.keys():
 254                 self.sub_module_dict[submodule] = SubModule(
 255                     sub_module_path=self.mount_path + "/" + submodule,
 256                     container_path=submodules[submodule],
 257                 )
 258         else:
 259             self.container_path = container_path
 260             self.module_name = container_path.split("/")[-1]
 261
 262
 263 class DebugMode(Object):
 264     """Class to handle the debug-mode."""
 265
 266     def __init__(
 267         self,
 268         charm: CharmBase,
 269         stored: StoredState,
 270         container: Container,
 271         hostpaths: List[HostPath] = [],
 272         vscode_workspace_path: str = "files/vscode-workspace.json",
 273     ) -> None:
 274         super().__init__(charm, "debug-mode")
 275
 276         self.charm = charm
 277         self._stored = stored
 278         self.hostpaths = hostpaths
 279         self.vscode_workspace = Path(vscode_workspace_path).read_text()
 280         self.container = container
 281
 282         self._stored.set_default(
 283             debug_mode_started=False,
 284             debug_mode_vscode_command=None,
 285             debug_mode_password=None,
 286         )
 287
 288         self.framework.observe(self.charm.on.config_changed, self._on_config_changed)
 289         self.framework.observe(self.charm.on[container.name].pebble_ready, self._on_config_changed)
 290         self.framework.observe(self.charm.on.update_status, self._on_update_status)
 291
 292     def _on_config_changed(self, _) -> None:
 293         """Handler for the config-changed event."""
 294         if not self.charm.unit.is_leader():
 295             return
 296
 297         debug_mode_enabled = self.charm.config.get("debug-mode", False)
 298         action = self.enable if debug_mode_enabled else self.disable
 299         action()
 300
 301     def _on_update_status(self, _) -> None:
 302         """Handler for the update-status event."""
 303         if not self.charm.unit.is_leader() or not self.started:
 304             return
 305
 306         self.charm.unit.status = ActiveStatus("debug-mode: ready")
 307
 308     @property
 309     def started(self) -> bool:
 310         """Indicates whether the debug-mode has started or not."""
 311         return self._stored.debug_mode_started
 312
 313     @property
 314     def command(self) -> str:
 315         """Command to launch vscode."""
 316         return self._stored.debug_mode_vscode_command
 317
 318     @property
 319     def password(self) -> str:
 320         """SSH password."""
 321         return self._stored.debug_mode_password
 322
 323     def enable(self, service_name: str = None) -> None:
 324         """Enable debug-mode.
 325
 326         This function mounts hostpaths of the OSM modules (if set), and
 327         configures the container so it can be easily debugged. The setup
 328         includes the configuration of SSH, environment variables, and
 329         VSCode workspace and plugins.
 330
 331         Args:
 332             service_name (str, optional): Pebble service name which has the desired environment
 333                 variables. Mandatory if there is more than one Pebble service configured.
 334         """
 335         hostpaths_to_reconfigure = self._hostpaths_to_reconfigure()
 336         if self.started and not hostpaths_to_reconfigure:
 337             self.charm.unit.status = ActiveStatus("debug-mode: ready")
 338             return
 339
 340         logger.debug("enabling debug-mode")
 341
 342         # Mount hostpaths if set.
 343         # If hostpaths are mounted, the statefulset will be restarted,
 344         # and for that reason we return immediately. On restart, the hostpaths
 345         # won't be mounted and then we can continue and setup the debug-mode.
 346         if hostpaths_to_reconfigure:
 347             self.charm.unit.status = MaintenanceStatus("debug-mode: configuring hostpaths")
 348             self._configure_hostpaths(hostpaths_to_reconfigure)
 349             return
 350
 351         self.charm.unit.status = MaintenanceStatus("debug-mode: starting")
 352         password = secrets.token_hex(8)
 353         self._setup_debug_mode(
 354             password,
 355             service_name,
 356             mounted_hostpaths=[hp for hp in self.hostpaths if self.charm.config.get(hp.config)],
 357         )
 358
 359         self._stored.debug_mode_vscode_command = self._get_vscode_command(get_pod_ip())
 360         self._stored.debug_mode_password = password
 361         self._stored.debug_mode_started = True
 362         logger.info("debug-mode is ready")
 363         self.charm.unit.status = ActiveStatus("debug-mode: ready")
 364
 365     def disable(self) -> None:
 366         """Disable debug-mode."""
 367         logger.debug("disabling debug-mode")
 368         current_status = self.charm.unit.status
 369         hostpaths_unmounted = self._unmount_hostpaths()
 370
 371         if not self._stored.debug_mode_started:
 372             return
 373         self._stored.debug_mode_started = False
 374         self._stored.debug_mode_vscode_command = None
 375         self._stored.debug_mode_password = None
 376
 377         if not hostpaths_unmounted:
 378             self.charm.unit.status = current_status
 379             self._restart()
 380
 381     def _hostpaths_to_reconfigure(self) -> List[HostPath]:
 382         hostpaths_to_reconfigure: List[HostPath] = []
 383         client = Client()
 384         statefulset = client.get(StatefulSet, self.charm.app.name, namespace=self.charm.model.name)
 385         volumes = statefulset.spec.template.spec.volumes
 386
 387         for hostpath in self.hostpaths:
 388             hostpath_is_set = True if self.charm.config.get(hostpath.config) else False
 389             hostpath_already_configured = next(
 390                 (True for volume in volumes if volume.name == hostpath.config), False
 391             )
 392             if hostpath_is_set != hostpath_already_configured:
 393                 hostpaths_to_reconfigure.append(hostpath)
 394
 395         return hostpaths_to_reconfigure
 396
 397     def _setup_debug_mode(
 398         self,
 399         password: str,
 400         service_name: str = None,
 401         mounted_hostpaths: List[HostPath] = [],
 402     ) -> None:
 403         services = self.container.get_plan().services
 404         if not service_name and len(services) != 1:
 405             raise Exception("Cannot start debug-mode: please set the service_name")
 406
 407         service = None
 408         if not service_name:
 409             service_name, service = services.popitem()
 410         if not service:
 411             service = services.get(service_name)
 412
 413         logger.debug(f"getting environment variables from service {service_name}")
 414         environment = service.environment
 415         environment_file_content = "\n".join(
 416             [f'export {key}="{value}"' for key, value in environment.items()]
 417         )
 418         logger.debug(f"pushing environment file to {self.container.name} container")
 419         self.container.push("/debug.envs", environment_file_content)
 420
 421         # Push VSCode workspace
 422         logger.debug(f"pushing vscode workspace to {self.container.name} container")
 423         self.container.push("/debug.code-workspace", self.vscode_workspace)
 424
 425         # Execute debugging script
 426         logger.debug(f"pushing debug-mode setup script to {self.container.name} container")
 427         self.container.push("/debug.sh", _DEBUG_SCRIPT.format(password), permissions=0o777)
 428         logger.debug(f"executing debug-mode setup script in {self.container.name} container")
 429         self.container.exec(["/debug.sh"]).wait_output()
 430         logger.debug(f"stopping service {service_name} in {self.container.name} container")
 431         self.container.stop(service_name)
 432
 433         # Add symlinks to mounted hostpaths
 434         for hostpath in mounted_hostpaths:
 435             logger.debug(f"adding symlink for {hostpath.config}")
 436             if len(hostpath.sub_module_dict) > 0:
 437                 for sub_module in hostpath.sub_module_dict.keys():
 438                     self.container.exec(
 439                         ["rm", "-rf", hostpath.sub_module_dict[sub_module].container_path]
 440                     ).wait_output()
 441                     self.container.exec(
 442                         [
 443                             "ln",
 444                             "-s",
 445                             hostpath.sub_module_dict[sub_module].sub_module_path,
 446                             hostpath.sub_module_dict[sub_module].container_path,
 447                         ]
 448                     )
 449
 450             else:
 451                 self.container.exec(["rm", "-rf", hostpath.container_path]).wait_output()
 452                 self.container.exec(
 453                     [
 454                         "ln",
 455                         "-s",
 456                         f"{hostpath.mount_path}/{hostpath.module_name}",
 457                         hostpath.container_path,
 458                     ]
 459                 )
 460
 461     def _configure_hostpaths(self, hostpaths: List[HostPath]):
 462         client = Client()
 463         statefulset = client.get(StatefulSet, self.charm.app.name, namespace=self.charm.model.name)
 464
 465         for hostpath in hostpaths:
 466             if self.charm.config.get(hostpath.config):
 467                 self._add_hostpath_to_statefulset(hostpath, statefulset)
 468             else:
 469                 self._delete_hostpath_from_statefulset(hostpath, statefulset)
 470
 471         client.replace(statefulset)
 472
 473     def _unmount_hostpaths(self) -> bool:
 474         client = Client()
 475         hostpath_unmounted = False
 476         statefulset = client.get(StatefulSet, self.charm.app.name, namespace=self.charm.model.name)
 477
 478         for hostpath in self.hostpaths:
 479             if self._delete_hostpath_from_statefulset(hostpath, statefulset):
 480                 hostpath_unmounted = True
 481
 482         if hostpath_unmounted:
 483             client.replace(statefulset)
 484
 485         return hostpath_unmounted
 486
 487     def _add_hostpath_to_statefulset(self, hostpath: HostPath, statefulset: StatefulSet):
 488         # Add volume
 489         logger.debug(f"adding volume {hostpath.config} to {self.charm.app.name} statefulset")
 490         volume = Volume(
 491             hostpath.config,
 492             hostPath=HostPathVolumeSource(
 493                 path=self.charm.config[hostpath.config],
 494                 type="Directory",
 495             ),
 496         )
 497         statefulset.spec.template.spec.volumes.append(volume)
 498
 499         # Add volumeMount
 500         for statefulset_container in statefulset.spec.template.spec.containers:
 501             if statefulset_container.name != self.container.name:
 502                 continue
 503
 504             logger.debug(
 505                 f"adding volumeMount {hostpath.config} to {self.container.name} container"
 506             )
 507             statefulset_container.volumeMounts.append(
 508                 VolumeMount(mountPath=hostpath.mount_path, name=hostpath.config)
 509             )
 510
 511     def _delete_hostpath_from_statefulset(self, hostpath: HostPath, statefulset: StatefulSet):
 512         hostpath_unmounted = False
 513         for volume in statefulset.spec.template.spec.volumes:
 514             if hostpath.config != volume.name:
 515                 continue
 516
 517             # Remove volumeMount
 518             for statefulset_container in statefulset.spec.template.spec.containers:
 519                 if statefulset_container.name != self.container.name:
 520                     continue
 521                 for volume_mount in statefulset_container.volumeMounts:
 522                     if volume_mount.name != hostpath.config:
 523                         continue
 524
 525                     logger.debug(
 526                         f"removing volumeMount {hostpath.config} from {self.container.name} container"
 527                     )
 528                     statefulset_container.volumeMounts.remove(volume_mount)
 529
 530             # Remove volume
 531             logger.debug(
 532                 f"removing volume {hostpath.config} from {self.charm.app.name} statefulset"
 533             )
 534             statefulset.spec.template.spec.volumes.remove(volume)
 535
 536             hostpath_unmounted = True
 537         return hostpath_unmounted
 538
 539     def _get_vscode_command(
 540         self,
 541         pod_ip: str,
 542         user: str = "root",
 543         workspace_path: str = "/debug.code-workspace",
 544     ) -> str:
 545         return f"code --remote ssh-remote+{user}@{pod_ip} {workspace_path}"
 546
 547     def _restart(self):
 548         self.container.exec(["kill", "-HUP", "1"])