diff --git a/charms/garm-configurator/lib/garm_configurator_relation.py b/charms/garm-configurator/lib/garm_configurator_relation.py index d4e76c1a..8af96367 100644 --- a/charms/garm-configurator/lib/garm_configurator_relation.py +++ b/charms/garm-configurator/lib/garm_configurator_relation.py @@ -19,6 +19,11 @@ ``ConfiguratorData.invalid_relation_ids`` instead of being exposed as an empty provider. Relations that publish the same scaleset name are also invalid: a scaleset name must identify exactly one scaleset in GARM. + +The models distinguish the fields that block provider or scaleset creation (required, with no +default) from the fields GARM can default (optional, with the default shown on the field). A +payload missing a required field, or carrying a blank value for one, does not validate, so the +consumer never renders a provider or scaleset from a partial databag. """ import dataclasses @@ -30,6 +35,25 @@ logger = logging.getLogger(__name__) + +def _reject_blank(value: str, info: pydantic.ValidationInfo) -> str: + """Reject a required string that is empty or whitespace-only. + + Args: + value: The field value. + info: Pydantic validation context. + + Raises: + ValueError: If the value has no non-whitespace content. + + Returns: + The unchanged value, so optional whitespace is preserved where it is meaningful. + """ + if not value.strip(): + raise ValueError(f"{info.field_name} must not be empty") + return value + + GARM_CONFIGURATOR_RELATION_NAME: typing.Final[str] = "garm-configurator" @@ -39,15 +63,15 @@ class ProviderConfig: This is the nested ``provider`` value of the application databag. The field names are the keys inside that value, so they are the wire contract between the configurator and GARM. - The auth URL is required: an application publishes the rest of the provider payload - alongside it, so a databag without it is incomplete and treated as invalid rather than as an - empty provider. + + The OpenStack credentials, the GitHub App ids, and the private-key secret URI are required: + GARM cannot create a provider, credential, entity, or scaleset without them. A payload that + omits one, or leaves it blank, is invalid. The password is required too, either inline for + backwards compatibility or through the secret URI the configurator publishes. Attributes: openstack_auth_url: Keystone authentication URL. openstack_username: OpenStack username. - openstack_password: Legacy plaintext password, or None when the secret URI is used. - openstack_password_secret_uri: Juju secret URI holding the password. openstack_project_name: OpenStack project (tenant). openstack_user_domain_name: Domain of the user. openstack_project_domain_name: Domain of the project. @@ -56,23 +80,52 @@ class ProviderConfig: github_app_id: GitHub App ID. github_installation_id: GitHub App installation ID. github_private_key_secret_uri: Juju secret URI holding the GitHub App private key. + openstack_password: Inline OpenStack password, superseded by the secret URI. + openstack_password_secret_uri: Juju secret URI holding the OpenStack password. """ openstack_auth_url: str - openstack_username: str | None = None + openstack_username: str + openstack_project_name: str + openstack_user_domain_name: str + openstack_project_domain_name: str + openstack_region_name: str + openstack_network: str + github_app_id: int + github_installation_id: int + github_private_key_secret_uri: str openstack_password: str | None = None openstack_password_secret_uri: str | None = None - openstack_project_name: str | None = None - openstack_user_domain_name: str | None = None - openstack_project_domain_name: str | None = None - openstack_region_name: str | None = None - openstack_network: str | None = None - github_app_id: int | None = None - github_installation_id: int | None = None - github_private_key_secret_uri: str | None = None + _validate_required_strings = pydantic.field_validator( + "openstack_auth_url", + "openstack_username", + "openstack_project_name", + "openstack_user_domain_name", + "openstack_project_domain_name", + "openstack_region_name", + "openstack_network", + "github_private_key_secret_uri", + )(_reject_blank) -@dataclasses.dataclass(frozen=True) + @pydantic.model_validator(mode="after") + def _require_password_source(self) -> "ProviderConfig": + """Require the password inline or through a secret URI. + + Raises: + ValueError: If neither password source is published. + + Returns: + The validated provider configuration. + """ + if not (self.openstack_password or self.openstack_password_secret_uri): + raise ValueError( + "one of openstack_password or openstack_password_secret_uri is required" + ) + return self + + +@pydantic.dataclasses.dataclass(frozen=True) class ScalesetConfig: """Scaleset and runner fields published by one ``garm-configurator`` application. @@ -83,14 +136,20 @@ class ScalesetConfig: These fields are published on the application databag by the configurator's leader unit, so every unit of a deployment sees one consistent payload. + A scaleset cannot be created without a name, provider, image, flavor, and architecture; those + fields are required and must not be blank. It also needs an entity to register runners to, + so exactly one of ``org`` or ``repo`` must be set. The remaining fields have the defaults + shown on the field, because GARM or the configurator's own config supplies a sensible value + when they are omitted. + Attributes: name: The name of the scaleset. provider_name: The GARM provider the scaleset runs on. image_id: Image name or ID used for runners. - image_visibility: Glance visibility used for an image-name lookup. - security_group: Security group attached to runner instances. flavor: Runner flavor. os_arch: Runner CPU architecture. + image_visibility: Glance visibility used for an image-name lookup. + security_group: Security group attached to runner instances. min_idle_runner: Minimum number of idle runners. max_runner: Maximum number of runners. labels: Comma-separated runner labels. @@ -107,18 +166,18 @@ class ScalesetConfig: pre_job_script: Bash script appended to the runner pre-job hook. """ - name: str = "" - provider_name: str = "" - image_id: str = "" + name: str + provider_name: str + image_id: str + flavor: str + os_arch: str image_visibility: str = "" security_group: str = "" - flavor: str = "" - os_arch: str = "" - min_idle_runner: str = "" - max_runner: str = "" + min_idle_runner: str = "0" + max_runner: str = "1" labels: str = "" - runner_group: str = "" - enable_shell: str = "" + runner_group: str = "Default" + enable_shell: str = "false" pre_install_scripts: str = "" org: str = "" repo: str = "" @@ -129,6 +188,28 @@ class ScalesetConfig: otel_collector_endpoint: str = "" pre_job_script: str = "" + _validate_required_strings = pydantic.field_validator( + "name", + "provider_name", + "image_id", + "flavor", + "os_arch", + )(_reject_blank) + + @pydantic.model_validator(mode="after") + def _require_exactly_one_entity(self) -> "ScalesetConfig": + """Require exactly one of the mutually exclusive entity fields. + + Raises: + ValueError: If neither or both of ``org`` and ``repo`` are set. + + Returns: + The validated scaleset configuration. + """ + if bool(self.org) == bool(self.repo): + raise ValueError("exactly one of org or repo is required") + return self + @pydantic.dataclasses.dataclass class ConfiguratorApplicationData: diff --git a/charms/garm-configurator/src/charm.py b/charms/garm-configurator/src/charm.py index 672bb9cc..aa4db514 100755 --- a/charms/garm-configurator/src/charm.py +++ b/charms/garm-configurator/src/charm.py @@ -49,9 +49,9 @@ def _reconcile(self, event: ops.EventBase) -> None: Only the leader unit publishes configurator data, so a non-leader blocks before doing any work. The leader reads the current charm state, forwards OpenStack credentials to - the image-builder relation, publishes scaleset configuration (and secrets when the image - reference is available) to the garm-configurator relations' application databags, then - sets unit status to reflect readiness. + the image-builder relation, publishes the complete scaleset configuration (with secrets) + to the garm-configurator relations' application databags once every required value, + including the image, is available, then sets unit status to reflect readiness. Args: event: The triggering event. @@ -155,6 +155,12 @@ def _configure_garm_relation(self, state: CharmState) -> None: published before an image is configured and are retained when an image is withdrawn. Only the leader reaches this method, so the application databag has a single writer. + The relation contract marks the fields that block provider or scaleset creation as + required. The configurator therefore publishes nothing until every one of them is + available: while the image builder has not supplied an image yet, it withdraws any + previously published payload instead of writing one the consumer would reject as + incomplete. + Does nothing when no garm-configurator relation is joined yet. Status reporting is handled by the caller (_reconcile). @@ -164,6 +170,9 @@ def _configure_garm_relation(self, state: CharmState) -> None: garm_relation = self.model.get_relation(GARM_RELATION_NAME) if garm_relation is None: return + if state.image is None: + self._withdraw_garm_relation(garm_relation) + return password_secret = self._ensure_relation_secret( garm_relation, @@ -175,13 +184,15 @@ def _configure_garm_relation(self, state: CharmState) -> None: "configurator-github-key", state.github_app_config.private_key, ) + if password_secret is None or github_key_secret is None: + return pre_install = state.scaleset_config.pre_install_scripts rc = state.runner_config scaleset_data: dict[str, str] = { "name": state.scaleset_config.name, "provider_name": state.provider_config.provider_name, - "image_id": state.image or "", + "image_id": state.image, "image_visibility": state.scaleset_config.image_visibility or "", "security_group": state.scaleset_config.security_group, "flavor": state.scaleset_config.flavor, @@ -211,9 +222,7 @@ def _configure_garm_relation(self, state: CharmState) -> None: provider=RelationProviderConfig( openstack_auth_url=state.provider_config.auth_url, openstack_username=state.provider_config.username, - openstack_password_secret_uri=( - str(password_secret.id) if password_secret is not None else None - ), + openstack_password_secret_uri=str(password_secret.id), openstack_project_name=state.provider_config.project_name, openstack_user_domain_name=state.provider_config.user_domain_name, openstack_project_domain_name=state.provider_config.project_domain_name, @@ -221,15 +230,29 @@ def _configure_garm_relation(self, state: CharmState) -> None: openstack_network=state.provider_config.network, github_app_id=state.github_app_config.app_id, github_installation_id=state.github_app_config.installation_id, - github_private_key_secret_uri=( - str(github_key_secret.id) if github_key_secret is not None else None - ), + github_private_key_secret_uri=str(github_key_secret.id), ), scaleset=RelationScalesetConfig(**scaleset_data), ), self.app, ) + def _withdraw_garm_relation(self, relation: ops.Relation) -> None: + """Remove this application's payload from the garm-configurator relation. + + Used while a required value, such as the runner image, is not available. Leaving an + older payload in place would keep publishing a configuration the operator has already + changed, and writing a partial one would make the consumer reject the relation. + + Args: + relation: The garm-configurator relation to withdraw from. + """ + if relation.data[self.app]: + logger.info( + "Withdrawing garm-configurator relation data until required values are available" + ) + relation.data[self.app].clear() + if __name__ == "__main__": ops.main(GarmConfiguratorCharm) diff --git a/charms/garm-configurator/tests/unit/test_charm.py b/charms/garm-configurator/tests/unit/test_charm.py index 798739c0..a6f0ea40 100644 --- a/charms/garm-configurator/tests/unit/test_charm.py +++ b/charms/garm-configurator/tests/unit/test_charm.py @@ -222,12 +222,12 @@ def test_clearing_configured_image_falls_back_to_image_relation(): assert _relation_value(cleared.get_relation(garm_relation.id), "image_id") == "legacy-uuid" -def test_clearing_configured_image_without_relation_withdraws_only_image(): +def test_clearing_configured_image_without_relation_withdraws_payload(): """ arrange: A configured image has published a complete GARM relation payload. act: Clear the image config while no image builder relation exists. - assert: The charm blocks and withdraws only the image, retaining credentials so GARM - can remove the old scale set. + assert: The charm blocks and withdraws its whole payload, because the relation contract + marks the image required and an older payload would keep advertising the removed image. """ ctx = Context(GarmConfiguratorCharm) secret = _make_secret() @@ -254,12 +254,7 @@ def test_clearing_configured_image_without_relation_withdraws_only_image(): assert cleared.unit_status == ops.BlockedStatus( "Missing image config or image builder relation" ) - assert _relation_value(garm_out, "image_id") == "" - assert _relation_value(garm_out, "openstack_auth_url") == ( - "https://keystone.example.com:5000/v3" - ) - assert "openstack_password_secret_uri" in _relation_section(garm_out, "provider") - assert _relation_value(garm_out, "github_private_key_secret_uri") + assert garm_out.local_app_data == {} relation_id = garm_relation.id relation_secrets = { secret.label: secret for secret in cleared.secrets if secret.label is not None @@ -699,6 +694,7 @@ def test_garm_configurator_relation_data_reflects_charm_state(): secret = _make_secret() pk_secret = _make_private_key_secret() config = _valid_config(secret, pk_secret) + config["image"] = "runner-noble-amd64" config["labels"] = "self-hosted,linux" config["pre-install-scripts"] = "echo hello" garm_relation = _make_garm_configurator_relation() @@ -788,12 +784,12 @@ def test_reconcile_writes_full_config_to_garm_relation(): assert _relation_value(garm_out, "image_id") == "abc-image-uuid" -def test_reconcile_writes_garm_data_without_image_uuid(): +def test_reconcile_withholds_garm_data_without_image_uuid(): """ arrange: All configs valid, garm relation joined, but image relation has NO UUID. act: config-changed fires. - assert: The single save writes the basic scaleset fields and the provider payload with an - empty image ID, so GARM can still resolve the provider while no scaleset is created. + assert: Nothing is published, because the image is required by the relation contract and a + partial payload would make GARM reject the relation. """ ctx = Context(GarmConfiguratorCharm) secret = _make_secret() @@ -808,13 +804,8 @@ def test_reconcile_writes_garm_data_without_image_uuid(): ) out = ctx.run(ctx.on.config_changed(), state) garm_out = out.get_relation(garm_relation.id) - assert _relation_value(garm_out, "name") == "my-scaleset" - assert _relation_value(garm_out, "image_id") == "" - assert _relation_value(garm_out, "github_app_id") == 99999 - assert _relation_value(garm_out, "openstack_auth_url") == ( - "https://keystone.example.com:5000/v3" - ) - assert _relation_value(garm_out, "openstack_password_secret_uri") + assert out.unit_status == ops.WaitingStatus("Waiting for image UUID from image builder") + assert garm_out.local_app_data == {} def test_reconcile_writes_garm_data_on_relation_joined(): @@ -994,6 +985,7 @@ def test_runner_config_fields_written_to_garm_configurator_relation(): secret = _make_secret() pk_secret = _make_private_key_secret() config = _valid_config(secret, pk_secret) + config["image"] = "runner-noble-amd64" config["dockerhub-mirror"] = "https://mirror.example.com" config["runner-http-proxy"] = "http://proxy.example.com:3128" config["aproxy-exclude-addresses"] = ( @@ -1033,10 +1025,12 @@ def test_runner_config_fields_absent_when_unset(): ctx = Context(GarmConfiguratorCharm) secret = _make_secret() pk_secret = _make_private_key_secret() + config = _valid_config(secret, pk_secret) + config["image"] = "runner-noble-amd64" garm_relation = _make_garm_configurator_relation() state = State( leader=True, - config=_valid_config(secret, pk_secret), + config=config, secrets=[secret, pk_secret], relations=[garm_relation], ) @@ -1072,6 +1066,7 @@ def test_enable_shell_written_to_garm_configurator_relation(configured, expected secret = _make_secret() pk_secret = _make_private_key_secret() config = _valid_config(secret, pk_secret) + config["image"] = "runner-noble-amd64" if configured is not None: config["enable-shell"] = configured garm_relation = _make_garm_configurator_relation() @@ -1100,6 +1095,7 @@ def test_image_visibility_written_to_garm_configurator_relation(configured, expe secret = _make_secret() pk_secret = _make_private_key_secret() config = _valid_config(secret, pk_secret) + config["image"] = "runner-noble-amd64" if configured is not None: config["image-visibility"] = configured garm_relation = _make_garm_configurator_relation() @@ -1128,6 +1124,7 @@ def test_security_group_written_to_garm_configurator_relation(configured, expect secret = _make_secret() pk_secret = _make_private_key_secret() config = _valid_config(secret, pk_secret) + config["image"] = "runner-noble-amd64" if configured is not None: config["security-group"] = configured garm_relation = _make_garm_configurator_relation() diff --git a/charms/garm-configurator/tests/unit/test_garm_configurator_relation.py b/charms/garm-configurator/tests/unit/test_garm_configurator_relation.py index 945c21ef..09c65de3 100644 --- a/charms/garm-configurator/tests/unit/test_garm_configurator_relation.py +++ b/charms/garm-configurator/tests/unit/test_garm_configurator_relation.py @@ -6,6 +6,7 @@ import dataclasses from types import SimpleNamespace +import pydantic import pytest from garm_configurator_relation import ( ConfiguratorApplicationData, @@ -17,18 +18,46 @@ ) +def _provider(**overrides) -> ProviderConfig: + """Return a complete provider payload, with the given fields overridden.""" + values = { + "openstack_auth_url": "https://ks.example.com:5000/v3", + "openstack_username": "admin", + "openstack_password_secret_uri": "secret:openstack-password", + "openstack_project_name": "myproject", + "openstack_user_domain_name": "Default", + "openstack_project_domain_name": "Default", + "openstack_region_name": "RegionOne", + "openstack_network": "external-net", + "github_app_id": 123, + "github_installation_id": 456, + "github_private_key_secret_uri": "secret:github-private-key", + } + values.update(overrides) + return ProviderConfig(**values) + + +def _scaleset(**overrides) -> ScalesetConfig: + """Return a complete scaleset payload, with the given fields overridden.""" + values = { + "name": "my-scaleset", + "provider_name": "configurator-0", + "image_id": "ubuntu:24.04", + "flavor": "m1.large", + "os_arch": "amd64", + "repo": "myorg/myrepo", + } + values.update(overrides) + return ScalesetConfig(**values) + + def _relation(relation_id: int = 1, scaleset_name: str = "my-scaleset") -> ConfiguratorRelation: """Return a minimal valid configurator relation.""" return ConfiguratorRelation( relation_id=relation_id, application_name=f"configurator-{relation_id}", - provider=ProviderConfig( - openstack_auth_url="https://ks.example.com:5000/v3", - ), - scaleset=ScalesetConfig( - name=scaleset_name, - provider_name=f"configurator-{relation_id}-0", - ), + provider=_provider(), + scaleset=_scaleset(name=scaleset_name, provider_name=f"configurator-{relation_id}-0"), ) @@ -83,11 +112,8 @@ def test_application_data_nests_provider_and_scaleset(): only its own fields, so consumers parse the two concerns separately. """ application_data = ConfiguratorApplicationData( - provider=ProviderConfig( - openstack_auth_url="https://ks.example.com:5000/v3", - github_app_id=123, - ), - scaleset=ScalesetConfig( + provider=_provider(github_app_id=123), + scaleset=_scaleset( name="my-scaleset", provider_name="configurator-0", image_id="ubuntu:24.04", @@ -100,17 +126,17 @@ def test_application_data_nests_provider_and_scaleset(): assert set(nested) == {"provider", "scaleset"} assert nested["provider"] == { "openstack_auth_url": "https://ks.example.com:5000/v3", - "openstack_username": None, + "openstack_username": "admin", "openstack_password": None, - "openstack_password_secret_uri": None, - "openstack_project_name": None, - "openstack_user_domain_name": None, - "openstack_project_domain_name": None, - "openstack_region_name": None, - "openstack_network": None, + "openstack_password_secret_uri": "secret:openstack-password", + "openstack_project_name": "myproject", + "openstack_user_domain_name": "Default", + "openstack_project_domain_name": "Default", + "openstack_region_name": "RegionOne", + "openstack_network": "external-net", "github_app_id": 123, - "github_installation_id": None, - "github_private_key_secret_uri": None, + "github_installation_id": 456, + "github_private_key_secret_uri": "secret:github-private-key", } assert nested["scaleset"]["name"] == "my-scaleset" assert nested["scaleset"]["provider_name"] == "configurator-0" @@ -130,10 +156,20 @@ class _FakeRelation: id = 1 - def __init__(self, application_data: ConfiguratorApplicationData | None = None) -> None: + def __init__( + self, + application_data: ConfiguratorApplicationData | None = None, + *, + validates: bool = True, + ) -> None: self.app = _FakeApp() - self.data = {self.app: {"published": "true"}} if application_data is not None else {} + self.data = ( + {self.app: {"published": "true"}} + if application_data is not None or not validates + else {} + ) self._application_data = application_data + self._validates = validates self.loaded_entity = None def load(self, cls, entity, *args, **kwargs): @@ -141,6 +177,8 @@ def load(self, cls, entity, *args, **kwargs): if cls is not ConfiguratorApplicationData: raise AssertionError(f"unexpected databag load for {cls.__name__}") self.loaded_entity = entity + if not self._validates: + raise ValueError("incomplete application databag") return self._application_data @@ -153,14 +191,12 @@ def test_requirer_reads_nested_provider_and_scaleset(): nested value unchanged, so the configurator's single save remains the source of truth. """ application_data = ConfiguratorApplicationData( - provider=ProviderConfig( - openstack_auth_url="https://ks.example.com:5000/v3", - github_app_id=123, - ), - scaleset=ScalesetConfig( + provider=_provider(github_app_id=123), + scaleset=_scaleset( name="my-scaleset", provider_name="configurator-0", org="myorg", + repo="", max_runner="6", ), ) @@ -193,3 +229,121 @@ def test_requirer_ignores_relation_without_application_data(): assert data.is_empty assert not data.has_invalid_relations + + +def test_scaleset_optional_fields_have_garm_defaults(): + """ + arrange: A scaleset payload with only the fields GARM cannot create the scaleset without. + act: Read the optional fields. + assert: They carry the GARM defaults, so a databag that omits them is valid instead of + invalid or an empty scaleset. + """ + scaleset = _scaleset() + + assert scaleset.min_idle_runner == "0" + assert scaleset.max_runner == "1" + assert scaleset.labels == "" + assert scaleset.runner_group == "Default" + assert scaleset.enable_shell == "false" + assert scaleset.pre_install_scripts == "" + assert scaleset.image_visibility == "" + assert scaleset.security_group == "" + + +@pytest.mark.parametrize( + "field", + ["name", "provider_name", "image_id", "flavor", "os_arch"], +) +def test_scaleset_required_field_must_be_present_and_not_blank(field: str): + """ + arrange: A scaleset payload missing one of the fields scaleset creation depends on, first + omitted and then blank. + act: Build the scaleset payload. + assert: Both forms are rejected, so a consumer never creates a scaleset from a partial or + empty required value. + """ + missing = { + key: value for key, value in dataclasses.asdict(_scaleset()).items() if key != field + } + with pytest.raises(pydantic.ValidationError): + ScalesetConfig(**missing) + with pytest.raises(pydantic.ValidationError): + _scaleset(**{field: " "}) + + +@pytest.mark.parametrize( + "entity", + [{}, {"org": "myorg", "repo": "myorg/myrepo"}], + ids=["neither-org-nor-repo", "both-org-and-repo"], +) +def test_scaleset_requires_exactly_one_entity(entity: dict): + """ + arrange: A scaleset payload naming neither or both of the mutually exclusive entity fields. + act: Build the scaleset payload. + assert: It is rejected, because GARM registers runners to exactly one org or repo. + """ + data = dataclasses.asdict(_scaleset()) | {"org": "", "repo": ""} | entity + with pytest.raises(pydantic.ValidationError): + ScalesetConfig(**data) + + +@pytest.mark.parametrize( + "field", + [ + "openstack_auth_url", + "openstack_username", + "openstack_project_name", + "openstack_user_domain_name", + "openstack_project_domain_name", + "openstack_region_name", + "openstack_network", + "github_private_key_secret_uri", + ], +) +def test_provider_required_field_must_be_present_and_not_blank(field: str): + """ + arrange: A provider payload missing one of the fields provider or credential creation + depends on, first omitted and then blank. + act: Build the provider payload. + assert: Both forms are rejected, so a consumer never renders a provider from a partial or + empty required value. + """ + missing = { + key: value for key, value in dataclasses.asdict(_provider()).items() if key != field + } + with pytest.raises(pydantic.ValidationError): + ProviderConfig(**missing) + with pytest.raises(pydantic.ValidationError): + _provider(**{field: " "}) + + +def test_provider_requires_a_password_source(): + """ + arrange: A provider payload with neither an inline password nor a password secret URI. + act: Build the provider payload. + assert: It is rejected, because GARM cannot authenticate to Keystone without one; either + source is accepted on its own. + """ + with pytest.raises(pydantic.ValidationError): + _provider(openstack_password=None, openstack_password_secret_uri=None) + + assert _provider( + openstack_password_secret_uri=None, openstack_password="pass" + ).openstack_password + assert _provider().openstack_password_secret_uri + + +def test_requirer_marks_incomplete_payload_invalid(): + """ + arrange: A configurator relation whose published payload cannot satisfy the required fields. + act: Aggregate the relation data. + assert: The relation id is reported invalid and no partial provider is exposed, so GARM + blocks instead of rendering a partially configured provider. + """ + relation = _FakeRelation(validates=False) + charm = SimpleNamespace(model=SimpleNamespace(relations={"garm-configurator": [relation]})) + + data = GarmConfiguratorRequirer(charm).get_data() + + assert data.relations == () + assert data.invalid_relation_ids == frozenset({relation.id}) diff --git a/charms/garm/requirements.txt b/charms/garm/requirements.txt index a28dc2fe..061f69d6 100644 --- a/charms/garm/requirements.txt +++ b/charms/garm/requirements.txt @@ -9,4 +9,4 @@ pydantic==2.14.3 typing-extensions==4.16.0 owasp-logger==0.1.6 # garm_configurator/v0.0.1 -garm-configurator-relation @ git+https://github.com/canonical/github-runner-operators.git@1a68829a8a7f10a38879850cad030d64f2f5aa16#subdirectory=charms/garm-configurator/lib +garm-configurator-relation @ git+https://github.com/canonical/github-runner-operators.git@eef25b8941c8f15654c16c2331480f9a7ad43987#subdirectory=charms/garm-configurator/lib diff --git a/charms/garm/tests/unit/test_charm.py b/charms/garm/tests/unit/test_charm.py index d3d58a44..5b1f967a 100644 --- a/charms/garm/tests/unit/test_charm.py +++ b/charms/garm/tests/unit/test_charm.py @@ -97,6 +97,9 @@ "openstack_project_domain_name": "Default", "openstack_region_name": "RegionOne", "openstack_network": "net1", + "github_app_id": "12345", + "github_installation_id": "67890", + "github_private_key_secret_uri": "secret:github-private-key", } _SCALESET_VALUES = { @@ -1234,12 +1237,12 @@ def test_related_configurator_credentials_replace_the_recorded_ones( assert providers[0]["password"] == _PROVIDER_VALUES["openstack_password"] -def test_incomplete_related_provider_blocks_the_update(ctx: Context, garm_api: _GarmApiMocks): +def test_provider_without_password_invalidates_relation(ctx: Context, garm_api: _GarmApiMocks): """ arrange: A configurator publishes its provider with an empty password, as when its password secret is not readable yet, over a record holding the complete provider. act: Reconcile. - assert: The unit blocks naming the provider, and nothing is applied: GARM is not + assert: The unit blocks on the invalid relation, and nothing is applied: GARM is not restarted or reconciled and the record is not rewritten, so the running configuration is held instead of breaking the provider's scalesets and poisoning the record. """ @@ -1250,7 +1253,8 @@ def test_incomplete_related_provider_blocks_the_update(ctx: Context, garm_api: _ out = ctx.run(ctx.on.update_status(), state) - assert out.unit_status == ops.BlockedStatus("Incomplete provider config: garm-configurator-0") + assert isinstance(out.unit_status, ops.BlockedStatus) + assert out.unit_status.message.startswith("Invalid garm-configurator relation data:") assert "garm-command" not in out.get_container(CONTAINER_NAME).layers garm_api.auth.from_login.assert_not_called() assert _secret_content(out, GARM_PROVIDERS_LABEL) == _secret_content( @@ -1912,25 +1916,13 @@ def test_applications_sharing_a_github_app_yield_one_credential( assert len(credentials) == 1 -@pytest.mark.parametrize( - "github_data", - [ - pytest.param(_provider_data(github_app_id="1"), id="missing-fields"), - pytest.param( - _provider_data(**_github_provider_values("secret:unavailable")), - id="unreadable-key-secret", - ), - ], -) -def test_incomplete_github_config_yields_no_credential( - ctx: Context, garm_api: _GarmApiMocks, github_data: dict -): +def test_unreadable_github_key_yields_no_credential(ctx: Context, garm_api: _GarmApiMocks): """ - arrange: A configurator application whose GitHub App fields are incomplete or name a - private-key secret this unit cannot read. + arrange: A configurator application naming a private-key secret this unit cannot read. act: Run update-status. assert: No credential is built — GARM rejects a partial one. """ + github_data = _provider_data(**_github_provider_values("secret:unavailable")) state = _state(configurator_app_data={**github_data, **_SCALESET_UNIT_DATA}) ctx.run(ctx.on.update_status(), state) @@ -1958,30 +1950,22 @@ def test_scaleset_is_built_from_relation_data(ctx: Context, garm_api: _GarmApiMo assert scaleset.template_id == _TEMPLATE_ID -def test_stale_image_key_does_not_prevent_scaleset_removal(ctx: Context, garm_api: _GarmApiMocks): - """ - arrange: A downgraded configurator withdraws image_id while a stale image key remains. - act: Run update-status. - assert: GARM ignores the stale key and removes the scale set. - """ - scaleset = _scaleset_values(image="stable-image") - scaleset.pop("image_id") - data = {**_PROVIDER_UNIT_DATA, "scaleset": json.dumps(scaleset)} - - ctx.run(ctx.on.update_status(), _state(configurator_app_data=data)) - - garm_api.scaleset.return_value.reconcile.assert_called_once_with([]) - - -def test_missing_image_reconciles_existing_scaleset_away(ctx: Context, garm_api: _GarmApiMocks): +@pytest.mark.parametrize( + "extra", + [{}, {"image": "stable-image"}], + ids=["missing-image-id", "stale-image-key"], +) +def test_scaleset_without_image_id_invalidates_the_relation( + ctx: Context, garm_api: _GarmApiMocks, extra: dict[str, str] +): """ - arrange: A configurator publishes complete provider data and a scale-set payload without an - image, representing withdrawal of its previous image reference. + arrange: A configurator publishes a scaleset without the image those scalesets require, + optionally with the old stale image key instead. act: Run update-status. - assert: GARM remains provider-ready and reconciles an empty scale-set list, removing the old - scale set instead of waiting for configurator data. + assert: The relation is invalid, so GARM blocks and neither renders a provider nor + reconciles scalesets from a partial payload. """ - scaleset = _scaleset_values() + scaleset = _scaleset_values(**extra) scaleset.pop("image_id") out = ctx.run( @@ -1994,8 +1978,9 @@ def test_missing_image_reconciles_existing_scaleset_away(ctx: Context, garm_api: ), ) - garm_api.scaleset.return_value.reconcile.assert_called_once_with([]) - assert out.unit_status == ops.ActiveStatus() + assert isinstance(out.unit_status, ops.BlockedStatus) + assert out.unit_status.message.startswith("Invalid garm-configurator relation data:") + garm_api.scaleset.assert_not_called() # --- Controller URLs ---------------------------------------------------------------------- diff --git a/charms/garm/tests/unit/test_charm_state.py b/charms/garm/tests/unit/test_charm_state.py index 7333a00a..bf0b1aa9 100644 --- a/charms/garm/tests/unit/test_charm_state.py +++ b/charms/garm/tests/unit/test_charm_state.py @@ -4,6 +4,7 @@ """Unit tests for charm_state.py.""" import logging +from types import SimpleNamespace from unittest.mock import MagicMock import pytest @@ -162,6 +163,39 @@ def test_charm_state_from_charm_with_debug_ssh_relation(): {"github_app_id", "github_installation_id", "github_private_key_secret_uri"} ) +_DEFAULT_PROVIDER = { + "openstack_auth_url": "https://ks.example.com:5000/v3", + "openstack_username": "admin", + "openstack_password_secret_uri": "secret:openstack-password", + "openstack_project_name": "myproject", + "openstack_user_domain_name": "Default", + "openstack_project_domain_name": "Default", + "openstack_region_name": "RegionOne", + "openstack_network": "external-net", + "github_app_id": 1, + "github_installation_id": 2, + "github_private_key_secret_uri": "secret:github-private-key", +} + +_DEFAULT_SCALESET = { + "name": "my-scaleset", + "provider_name": "garm-configurator-0", + "image_id": "img-1", + "flavor": "m1.large", + "os_arch": "amd64", + "repo": "myorg/myrepo", +} + + +def _provider_config(**overrides) -> RelationProviderConfig: + """Return a complete provider payload with the given fields overridden.""" + return RelationProviderConfig(**(_DEFAULT_PROVIDER | overrides)) + + +def _scaleset_config(**overrides) -> ScalesetConfig: + """Return a complete scaleset payload with the given fields overridden.""" + return ScalesetConfig(**(_DEFAULT_SCALESET | overrides)) + def _configurator_relation(index: int, **unit_data) -> ConfiguratorRelation: """Build one configurator relation from a flat databag of provider and scaleset fields.""" @@ -169,13 +203,15 @@ def _configurator_relation(index: int, **unit_data) -> ConfiguratorRelation: scaleset_fields = { key: value for key, value in unit_data.items() if key not in _PROVIDER_FIELDS } + if "org" in scaleset_fields and "repo" not in scaleset_fields: + scaleset_fields["repo"] = "" + elif "repo" in scaleset_fields and "org" not in scaleset_fields: + scaleset_fields["org"] = "" return ConfiguratorRelation( relation_id=index, application_name="garm-configurator", - provider=RelationProviderConfig( - openstack_auth_url="https://ks.example.com:5000/v3", **provider_fields - ), - scaleset=ScalesetConfig(**scaleset_fields), + provider=_provider_config(**provider_fields), + scaleset=_scaleset_config(**scaleset_fields), ) @@ -216,14 +252,30 @@ def test_charm_state_from_charm_uses_the_provided_requirer(): ] +def _incomplete_entities(provider_overrides, scaleset_overrides): + """Build entities from a defensive relation whose provider or scaleset is incomplete.""" + relation = ConfiguratorRelation( + relation_id=0, + application_name="garm-configurator", + provider=SimpleNamespace(**(_DEFAULT_PROVIDER | provider_overrides)), + scaleset=SimpleNamespace(**(_DEFAULT_SCALESET | scaleset_overrides)), + ) + return _get_desired_entities(ConfiguratorData(relations=(relation,))) + + def test_desired_entities_log_skipped_unit_without_app_ids(caplog): """ arrange: A configurator unit naming an org but without GitHub App ids. act: Build the desired entities. assert: The unit is skipped and the skip is logged so a stalled bring-up is visible. + The strict relation model rejects this payload, but the consumer still tolerates it + defensively. """ with caplog.at_level(logging.INFO): - entities = _entities([{"org": "canonical"}]) + entities = _incomplete_entities( + {"github_app_id": None, "github_installation_id": None}, + {"org": "canonical", "repo": ""}, + ) assert entities == [] assert "Skipping entity organization 'canonical': GitHub App ids not yet published" in ( @@ -313,21 +365,27 @@ def test_desired_entities_distinguish_org_and_repo_with_same_name(): @pytest.mark.parametrize( - "unit_data", + "provider_overrides, scaleset_overrides", [ - {"github_app_id": "1", "github_installation_id": "2"}, - {"org": "canonical", "github_installation_id": "2"}, - {"org": "canonical", "github_app_id": "1"}, + pytest.param({}, {"org": "", "repo": ""}, id="no-org-or-repo"), + pytest.param( + {"github_app_id": None}, {"org": "canonical", "repo": ""}, id="missing-app-id" + ), + pytest.param( + {"github_installation_id": None}, + {"org": "canonical", "repo": ""}, + id="missing-installation-id", + ), ], - ids=["no-org-or-repo", "missing-app-id", "missing-installation-id"], ) -def test_desired_entities_skip_incomplete_unit(unit_data): +def test_desired_entities_skip_incomplete_unit(provider_overrides, scaleset_overrides): """ arrange: A configurator unit lacking an entity name or valid GitHub App ids. act: Build CharmState.desired_entities. - assert: No entity is built. + assert: No entity is built. The strict relation model rejects these payloads, but the + consumer still tolerates them defensively. """ - assert _entities([unit_data]) == [] + assert _incomplete_entities(provider_overrides, scaleset_overrides) == [] def test_runner_config_from_databag_and_has_config(): diff --git a/docs/changelog.md b/docs/changelog.md index ab16c497..41ee289f 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -8,6 +8,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Each revision is versioned by the date of the revision. +## 2026-11-19 + +- `garm-configurator`: define and enforce which `garm-configurator` relation fields are required. The scaleset name, provider name, image, flavor, architecture, and one of `repo` or `org`, along with the OpenStack credentials and GitHub App credentials, are now required; a payload that omits one or leaves it blank is invalid and the `garm` charm blocks instead of creating a partial provider or scale set. The idle-runner, max-runner, label, runner-group, pre-install-script, and runner networking options keep documented defaults and stay optional. The configurator now withholds its relation payload until every required value, including the image, is available, so a deployment waiting on its image builder no longer publishes an incomplete configuration. + ## 2026-11-12 - `garm`: stop applying configuration changes when a `garm-configurator` relation publishes an incomplete provider, such as one whose OpenStack password secret is not yet readable. The charm previously restarted GARM with the incomplete provider and recorded it, so the scale sets using that provider failed and later hooks error. The unit now goes to `Blocked` with `Incomplete provider config: ` and leaves GARM running with its existing provider and scale set configuration until the relation data is complete. diff --git a/docs/reference/charms.md b/docs/reference/charms.md index 45d305ec..d4490e02 100644 --- a/docs/reference/charms.md +++ b/docs/reference/charms.md @@ -57,18 +57,35 @@ The GARM configurator charm has no actions. ### Configurations -The GARM configurator charm holds the configuration for one GARM scaleset. The `os-arch` option, which specifies the -runner CPU architecture, is mandatory. The OpenStack credentials required by the provider include: - -* `openstack-auth-url` -* `openstack-password` -* `openstack-project-domain-name` -* `openstack-project-name` -* `openstack-user-domain-name` -* `openstack-username` - -The GitHub App ID, installation ID, and private key are also required for GitHub authentication. Review the remaining -options and defaults before applying the configuration. +The GARM configurator charm holds the configuration for one GARM scaleset. The following +options are required because the charm cannot publish a provider configuration or scaleset +without them: + +* `name`, `flavor`, and `os-arch`, which identify the scaleset and its runners. +* One of `repo` or `org`, which names the GitHub entity the runners register to. +* An image: either the `image` option or an image published over the image-builder relation. +* The OpenStack credentials required by the provider: + * `openstack-auth-url` + * `openstack-network` + * `openstack-password` + * `openstack-project-domain-name` + * `openstack-project-name` + * `openstack-region-name` + * `openstack-user-domain-name` + * `openstack-username` +* The GitHub App ID, installation ID, and private key, which GARM uses to authenticate. + +The scaleset options `min-idle-runner`, `max-runner`, `labels`, `runner-group`, +`pre-install-scripts`, `image-visibility`, `security-group`, and the runner networking and +observability options are optional; their documented defaults apply when they are unset. + +The charm reports `Blocked` while a required configuration value is missing and publishes +nothing to the GARM relation. It publishes the complete relation payload only once every +required value, including the image, is available. A relation payload that omits a required +field, or carries a blank value for one, is invalid and the GARM charm blocks rather than +creating a partially configured provider or scaleset. + +Review the remaining options and defaults before applying the configuration. ```{seealso} [Configurations for GARM configurator charm](https://charmhub.io/garm-configurator/configurations)