2 # Copyright 2022 Canonical Ltd.
3 # See LICENSE file for licensing details.
4 # http://www.apache.org/licenses/LICENSE-2.0
7 This library offers some utilities made for but not limited to Charmed OSM.
11 Execute the following command inside your Charmed Operator folder to fetch the library.
14 charmcraft fetch-lib charms.osm_libs.v0.utils
17 # CharmError Exception
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.
24 from charms.osm_libs.v0.utils import CharmError
26 class MyCharm(CharmBase):
27 def _on_config_changed(self, _):
29 if not self.config.get("some-option"):
30 raise CharmError("need some-option", BlockedStatus)
32 if not self.mysql_ready:
33 raise CharmError("waiting for mysql", WaitingStatus)
37 exception CharmError as e:
38 self.unit.status = e.status
43 The `check_container_ready` function checks that a container is ready,
44 and therefore Pebble is ready.
46 The `check_service_active` function checks that a service in a container is running.
48 Both functions raise a CharmError if the validations fail.
52 from charms.osm_libs.v0.utils import check_container_ready, check_service_active
54 class MyCharm(CharmBase):
55 def _on_config_changed(self, _):
57 container: Container = self.unit.get_container("my-container")
58 check_container_ready(container)
59 check_service_active(container, "my-service")
62 exception CharmError as e:
63 self.unit.status = e.status
68 The debug-mode allows OSM developers to easily debug OSM modules.
72 from charms.osm_libs.v0.utils import DebugMode
74 class MyCharm(CharmBase):
75 _stored = StoredState()
77 def __init__(self, _):
79 container: Container = self.unit.get_container("my-container")
82 config="module-hostpath",
83 container_path="/usr/lib/python3/dist-packages/module"
86 vscode_workspace_path = "files/vscode-workspace.json"
87 self.debug_mode = DebugMode(
92 vscode_workspace_path,
95 def _on_update_status(self, _):
96 if self.debug_mode.started:
100 def _get_debug_mode_information(self):
101 command = self.debug_mode.command
102 password = self.debug_mode.password
103 return command, password
108 - Get pod IP with `get_pod_ip()`
114 from pathlib
import Path
115 from typing
import List
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 (
130 from ops
.pebble
import ServiceStatus
132 # The unique Charmhub library identifier, never change it
133 LIBID
= "e915908eebee4cdd972d484728adf984"
135 # Increment this major API version when introducing breaking changes
138 # Increment this PATCH version before using `charmcraft publish-lib` or reset
139 # to 0 if you are raising the major API version
142 logger
= logging
.getLogger(__name__
)
145 class CharmError(Exception):
146 """Charm Error Exception."""
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
)
154 def check_container_ready(container
: Container
) -> None:
155 """Check Pebble has started in the container.
158 container (Container): Container to be checked.
161 CharmError: if container is not ready.
163 if not container
.can_connect():
164 raise CharmError("waiting for pebble to start", MaintenanceStatus
)
167 def check_service_active(container
: Container
, service_name
: str) -> None:
168 """Check if the service is running.
171 container (Container): Container to be checked.
172 service_name (str): Name of the service to check.
175 CharmError: if the service is not running.
177 if service_name
not in container
.get_plan().services
:
178 raise CharmError(f
"{service_name} service not configured yet", WaitingStatus
)
180 if container
.get_service(service_name
).current
!= ServiceStatus
.ACTIVE
:
181 raise CharmError(f
"{service_name} service is not running")
184 def get_pod_ip() -> str:
185 """Get Kubernetes Pod IP.
188 str: The IP of the Pod.
190 return socket
.gethostbyname(socket
.gethostname())
193 _DEBUG_SCRIPT
= r
"""#!/bin/bash
196 function download_code(){{
197 wget https://go.microsoft.com/fwlink/?LinkID=760868 -O code.deb
200 function setup_envs(){{
201 grep "source /debug.envs" /root/.bashrc || echo "source /debug.envs" | tee -a /root/.bashrc
203 function setup_ssh(){{
205 cat /etc/ssh/sshd_config |
206 grep -E '^PermitRootLogin yes$$' || (
207 echo PermitRootLogin yes |
208 tee -a /etc/ssh/sshd_config
213 usermod --password $(echo {} | openssl passwd -1 -stdin) root
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
224 export DEBIAN_FRONTEND=noninteractive
225 apt update && apt install wget -y
236 """Represents a hostpath."""
238 def __init__(self
, config
: str, container_path
: str) -> None:
239 mount_path_items
= config
.split("-")
240 mount_path_items
.reverse()
241 self
.mount_path
= "/" + "/".join(mount_path_items
)
243 self
.container_path
= container_path
244 self
.module_name
= container_path
.split("/")[-1]
247 class DebugMode(Object
):
248 """Class to handle the debug-mode."""
254 container
: Container
,
255 hostpaths
: List
[HostPath
] = [],
256 vscode_workspace_path
: str = "files/vscode-workspace.json",
258 super().__init
__(charm
, "debug-mode")
261 self
._stored
= stored
262 self
.hostpaths
= hostpaths
263 self
.vscode_workspace
= Path(vscode_workspace_path
).read_text()
264 self
.container
= container
266 self
._stored
.set_default(
267 debug_mode_started
=False,
268 debug_mode_vscode_command
=None,
269 debug_mode_password
=None,
272 self
.framework
.observe(self
.charm
.on
.config_changed
, self
._on
_config
_changed
)
273 self
.framework
.observe(self
.charm
.on
[container
.name
].pebble_ready
, self
._on
_config
_changed
)
274 self
.framework
.observe(self
.charm
.on
.update_status
, self
._on
_update
_status
)
276 def _on_config_changed(self
, _
) -> None:
277 """Handler for the config-changed event."""
278 if not self
.charm
.unit
.is_leader():
281 debug_mode_enabled
= self
.charm
.config
.get("debug-mode", False)
282 action
= self
.enable
if debug_mode_enabled
else self
.disable
285 def _on_update_status(self
, _
) -> None:
286 """Handler for the update-status event."""
287 if not self
.charm
.unit
.is_leader() or not self
.started
:
290 self
.charm
.unit
.status
= ActiveStatus("debug-mode: ready")
293 def started(self
) -> bool:
294 """Indicates whether the debug-mode has started or not."""
295 return self
._stored
.debug_mode_started
298 def command(self
) -> str:
299 """Command to launch vscode."""
300 return self
._stored
.debug_mode_vscode_command
303 def password(self
) -> str:
305 return self
._stored
.debug_mode_password
307 def enable(self
, service_name
: str = None) -> None:
308 """Enable debug-mode.
310 This function mounts hostpaths of the OSM modules (if set), and
311 configures the container so it can be easily debugged. The setup
312 includes the configuration of SSH, environment variables, and
313 VSCode workspace and plugins.
316 service_name (str, optional): Pebble service name which has the desired environment
317 variables. Mandatory if there is more than one Pebble service configured.
319 hostpaths_to_reconfigure
= self
._hostpaths
_to
_reconfigure
()
320 if self
.started
and not hostpaths_to_reconfigure
:
321 self
.charm
.unit
.status
= ActiveStatus("debug-mode: ready")
324 logger
.debug("enabling debug-mode")
326 # Mount hostpaths if set.
327 # If hostpaths are mounted, the statefulset will be restarted,
328 # and for that reason we return immediately. On restart, the hostpaths
329 # won't be mounted and then we can continue and setup the debug-mode.
330 if hostpaths_to_reconfigure
:
331 self
.charm
.unit
.status
= MaintenanceStatus("debug-mode: configuring hostpaths")
332 self
._configure
_hostpaths
(hostpaths_to_reconfigure
)
335 self
.charm
.unit
.status
= MaintenanceStatus("debug-mode: starting")
336 password
= secrets
.token_hex(8)
337 self
._setup
_debug
_mode
(
340 mounted_hostpaths
=[hp
for hp
in self
.hostpaths
if self
.charm
.config
.get(hp
.config
)],
343 self
._stored
.debug_mode_vscode_command
= self
._get
_vscode
_command
(get_pod_ip())
344 self
._stored
.debug_mode_password
= password
345 self
._stored
.debug_mode_started
= True
346 logger
.info("debug-mode is ready")
347 self
.charm
.unit
.status
= ActiveStatus("debug-mode: ready")
349 def disable(self
) -> None:
350 """Disable debug-mode."""
351 logger
.debug("disabling debug-mode")
352 current_status
= self
.charm
.unit
.status
353 hostpaths_unmounted
= self
._unmount
_hostpaths
()
355 if not self
._stored
.debug_mode_started
:
357 self
._stored
.debug_mode_started
= False
358 self
._stored
.debug_mode_vscode_command
= None
359 self
._stored
.debug_mode_password
= None
361 if not hostpaths_unmounted
:
362 self
.charm
.unit
.status
= current_status
365 def _hostpaths_to_reconfigure(self
) -> List
[HostPath
]:
366 hostpaths_to_reconfigure
: List
[HostPath
] = []
368 statefulset
= client
.get(StatefulSet
, self
.charm
.app
.name
, namespace
=self
.charm
.model
.name
)
369 volumes
= statefulset
.spec
.template
.spec
.volumes
371 for hostpath
in self
.hostpaths
:
372 hostpath_is_set
= True if self
.charm
.config
.get(hostpath
.config
) else False
373 hostpath_already_configured
= next(
374 (True for volume
in volumes
if volume
.name
== hostpath
.config
), False
376 if hostpath_is_set
!= hostpath_already_configured
:
377 hostpaths_to_reconfigure
.append(hostpath
)
379 return hostpaths_to_reconfigure
381 def _setup_debug_mode(
384 service_name
: str = None,
385 mounted_hostpaths
: List
[HostPath
] = [],
387 services
= self
.container
.get_plan().services
388 if not service_name
and len(services
) != 1:
389 raise Exception("Cannot start debug-mode: please set the service_name")
393 service_name
, service
= services
.popitem()
395 service
= services
.get(service_name
)
397 logger
.debug(f
"getting environment variables from service {service_name}")
398 environment
= service
.environment
399 environment_file_content
= "\n".join(
400 [f
'export {key}="{value}"' for key
, value
in environment
.items()]
402 logger
.debug(f
"pushing environment file to {self.container.name} container")
403 self
.container
.push("/debug.envs", environment_file_content
)
405 # Push VSCode workspace
406 logger
.debug(f
"pushing vscode workspace to {self.container.name} container")
407 self
.container
.push("/debug.code-workspace", self
.vscode_workspace
)
409 # Execute debugging script
410 logger
.debug(f
"pushing debug-mode setup script to {self.container.name} container")
411 self
.container
.push("/debug.sh", _DEBUG_SCRIPT
.format(password
), permissions
=0o777)
412 logger
.debug(f
"executing debug-mode setup script in {self.container.name} container")
413 self
.container
.exec(["/debug.sh"]).wait_output()
414 logger
.debug(f
"stopping service {service_name} in {self.container.name} container")
415 self
.container
.stop(service_name
)
417 # Add symlinks to mounted hostpaths
418 for hostpath
in mounted_hostpaths
:
419 logger
.debug(f
"adding symlink for {hostpath.config}")
420 self
.container
.exec(["rm", "-rf", hostpath
.container_path
]).wait_output()
425 f
"{hostpath.mount_path}/{hostpath.module_name}",
426 hostpath
.container_path
,
430 def _configure_hostpaths(self
, hostpaths
: List
[HostPath
]):
432 statefulset
= client
.get(StatefulSet
, self
.charm
.app
.name
, namespace
=self
.charm
.model
.name
)
434 for hostpath
in hostpaths
:
435 if self
.charm
.config
.get(hostpath
.config
):
436 self
._add
_hostpath
_to
_statefulset
(hostpath
, statefulset
)
438 self
._delete
_hostpath
_from
_statefulset
(hostpath
, statefulset
)
440 client
.replace(statefulset
)
442 def _unmount_hostpaths(self
) -> bool:
444 hostpath_unmounted
= False
445 statefulset
= client
.get(StatefulSet
, self
.charm
.app
.name
, namespace
=self
.charm
.model
.name
)
447 for hostpath
in self
.hostpaths
:
448 if self
._delete
_hostpath
_from
_statefulset
(hostpath
, statefulset
):
449 hostpath_unmounted
= True
451 if hostpath_unmounted
:
452 client
.replace(statefulset
)
454 return hostpath_unmounted
456 def _add_hostpath_to_statefulset(self
, hostpath
: HostPath
, statefulset
: StatefulSet
):
458 logger
.debug(f
"adding volume {hostpath.config} to {self.charm.app.name} statefulset")
461 hostPath
=HostPathVolumeSource(
462 path
=self
.charm
.config
[hostpath
.config
],
466 statefulset
.spec
.template
.spec
.volumes
.append(volume
)
469 for statefulset_container
in statefulset
.spec
.template
.spec
.containers
:
470 if statefulset_container
.name
!= self
.container
.name
:
474 f
"adding volumeMount {hostpath.config} to {self.container.name} container"
476 statefulset_container
.volumeMounts
.append(
477 VolumeMount(mountPath
=hostpath
.mount_path
, name
=hostpath
.config
)
480 def _delete_hostpath_from_statefulset(self
, hostpath
: HostPath
, statefulset
: StatefulSet
):
481 hostpath_unmounted
= False
482 for volume
in statefulset
.spec
.template
.spec
.volumes
:
484 if hostpath
.config
!= volume
.name
:
488 for statefulset_container
in statefulset
.spec
.template
.spec
.containers
:
489 if statefulset_container
.name
!= self
.container
.name
:
491 for volume_mount
in statefulset_container
.volumeMounts
:
492 if volume_mount
.name
!= hostpath
.config
:
496 f
"removing volumeMount {hostpath.config} from {self.container.name} container"
498 statefulset_container
.volumeMounts
.remove(volume_mount
)
502 f
"removing volume {hostpath.config} from {self.charm.app.name} statefulset"
504 statefulset
.spec
.template
.spec
.volumes
.remove(volume
)
506 hostpath_unmounted
= True
507 return hostpath_unmounted
509 def _get_vscode_command(
513 workspace_path
: str = "/debug.code-workspace",
515 return f
"code --remote ssh-remote+{user}@{pod_ip} {workspace_path}"
518 self
.container
.exec(["kill", "-HUP", "1"])