diff --git a/docs/explanation/charm-relation-interfaces.md b/docs/explanation/charm-relation-interfaces.md index b6b5dfa82..96fed6bdd 100644 --- a/docs/explanation/charm-relation-interfaces.md +++ b/docs/explanation/charm-relation-interfaces.md @@ -3,13 +3,13 @@ > See also: {ref}`manage-interfaces` -[`charm-relation-interfaces`](https://github.com/canonical/charm-relation-interfaces) is a repository containing specifications, databag schemas and interface tests for Juju relation interfaces. In other words, it is the source of truth for data and behavior of providers and requirers of integrations. +[`charm-relation-interfaces`](https://github.com/canonical/charm-relation-interfaces) is a repository containing specifications, databag schemas and interface tests for Juju relation interfaces. In other words, it is the source of truth for data and behavior of providers and requirers of relations. -The purpose of this project is to provide uniformity in the landscape of all possible integrations and promote charm interoperability. +The purpose of this project is to provide uniformity in the landscape of all possible relations and promote charm interoperability. -Juju interfaces are untyped, which means that for juju to think two charms can be integrated all it looks at is whether the interface names of the two endpoints you're trying to connect are the same string. But it might be that the two charms have different, incompatible implementations of two different integrations that happen to have the same name. +Juju interfaces are untyped, which means that for juju to think two charms can be integrated all it looks at is whether the interface names of the two endpoints you're trying to connect are the same string. But it might be that the two charms have different, incompatible implementations of two different relations that happen to have the same name. -In order to prevent two separate charms from rolling their own integration with the same name, and prevent a sprawl of many subtly different interfaces with similar semantics and similar purposes, we introduced `charm-relation-interfaces`. +In order to prevent two separate charms from rolling their own relation with the same name, and prevent a sprawl of many subtly different interfaces with similar semantics and similar purposes, we introduced `charm-relation-interfaces`. ## Using `charm-relation-interfaces` @@ -37,7 +37,6 @@ For each interface, the charm-relation-interfaces repository hosts: ## Charm relation interfaces in Charmhub -In the future, Charmhub will have a searchable collection of integration interfaces. Charmhub will, for all charms using the interface, verify that they implement it correctly (regardless of whether they use the 'official' implementation or they roll their own) in order to give the charm a happy checkmark on `charmhub.io`. In order to do that it will need to fetch the specification (from `charm-relation-interfaces`) *and* the charm repo, because we can't know what implementation they are using: we need the source code. diff --git a/docs/explanation/interface-tests.md b/docs/explanation/interface-tests.md index 56580e288..c0605946b 100644 --- a/docs/explanation/interface-tests.md +++ b/docs/explanation/interface-tests.md @@ -5,7 +5,7 @@ Interface tests are tests that verify the compliance of a charm with an interface specification. Interface specifications, stored in {ref}`charm-relation-interfaces `, are contract definitions that mandate how a charm should behave when integrated with another charm over a registered interface. -Interface tests will allow `charmhub` to validate the integrations of a charm and verify that your charm indeeed supports "the" `ingress` interface and not just an interface called "ingress", which happens to be the same name as "the official `ingress` interface v2" as registered in charm-relation-interfaces (see [here](https://github.com/canonical/charm-relation-interfaces/tree/main/interfaces/ingress/v2)). +Interface tests will allow `charmhub` to validate the relations of a charm and verify that your charm indeeed supports "the" `ingress` interface and not just an interface called "ingress", which happens to be the same name as "the official `ingress` interface v2" as registered in charm-relation-interfaces (see [here](https://github.com/canonical/charm-relation-interfaces/tree/main/interfaces/ingress/v2)). Also, they allow alternative implementations of an interface to validate themselves against the contractual specification stored in charm-relation-interfaces, and they help verify compliance with multiple versions of an interface. diff --git a/docs/explanation/storedstate-uses-limitations.md b/docs/explanation/storedstate-uses-limitations.md index 21fed2358..9bf7682ed 100644 --- a/docs/explanation/storedstate-uses-limitations.md +++ b/docs/explanation/storedstate-uses-limitations.md @@ -103,7 +103,7 @@ def some_event_handler(event): return ``` -In the other cases where state is needed, authors ideally want to relate a charm to a database, attach storage (see Juju storage), or simply be opinionated, and hard code the single "correct" state into the charm. (Perhaps `ExampleBlog` should always be run in `production` mode when deployed as a charm?) +In the other cases where state is needed, authors ideally want to integrate a charm with a database, attach storage (see Juju storage), or simply be opinionated, and hard code the single "correct" state into the charm. (Perhaps `ExampleBlog` should always be run in `production` mode when deployed as a charm?) > See more: {external+juju:ref}`Juju Storage ` diff --git a/docs/explanation/testing.md b/docs/explanation/testing.md index bb35b532a..20a322672 100644 --- a/docs/explanation/testing.md +++ b/docs/explanation/testing.md @@ -58,7 +58,7 @@ Integration tests typically take significantly longer to run than unit tests. **Coverage.** * Charm actions -* Charm integrations +* Charm relations * Charm configurations * That the workload is up and running, and responsive * Upgrade sequence diff --git a/docs/howto/get-started-with-charm-testing.md b/docs/howto/get-started-with-charm-testing.md index 95988b20e..3fdcf185c 100644 --- a/docs/howto/get-started-with-charm-testing.md +++ b/docs/howto/get-started-with-charm-testing.md @@ -64,7 +64,7 @@ The "inputs" of a charm run are therefore: - integration (relation) data - stored state -Only the event context is guaranteed to be present. The other input sources are optional, but typically a charm will have at least some config and a few integrations adding to its inputs. +Only the event context is guaranteed to be present. The other input sources are optional, but typically a charm will have at least some config and a few relations adding to its inputs. The charm code executes and typically produces side-effects aimed at its workload (for example: it writes files to a disk, runs commands on a system, or reconfigures a process) or at other charms it integrates with (for example: it writes relation data). We call this 'operating' a workload, and that is what a charm is meant to do. The ways in which a charm operates can be roughly categorised as: @@ -115,7 +115,7 @@ When you instantiate `Context` and `State` objects, the charm instance does not The `Context` provides methods for all the Juju events. For example: - the cloud admin changes the charm config: `ctx.on.config_changed()` - - the cloud admin relates this charm to some other: `ctx.on.relation_created(relation)` + - the cloud admin integrates this charm with some other: `ctx.on.relation_created(relation)` - a remote unit joins in a relation (for example, because the cloud admin has scaled up a remote charm): `ctx.on.relation_joined(relation)` - a remote unit touches its relation data: `ctx.on.relation_changed(relation)` - a cloud admin removes a relation: `ctx.on.relation_departed(relation)` @@ -177,7 +177,7 @@ Things you typically want to test with integration tests: - The charm can be deployed (i.e. `juju deploy ./packed_charm.charm` deploys an application that reaches `active` or `waiting` within a reasonable time frame) These are 'smoke tests' that should always be present, and are provided for you when using `charmcraft init`. The following are non-smokey, proper integration tests. -- The charm can be related to other applications without erroring +- The charm can be integrated with other applications without erroring - and the relation has the expected effect on the charm's operation logic - The charm can be configured - and the config has the expected effect on the charm's operation logic @@ -208,7 +208,7 @@ async def test_operation(ops_test: OpsTest): app: Application = ops_test.model.applications.get("tester") await app.set_config({"my-key": "my-value"}) - # Add another charm and relate them: + # Add another charm and integrate them: await ops_test.model.deploy('other-app') await ops_test.model.relate('tester:endpoint1', 'other-charm:endpoint2') diff --git a/docs/howto/manage-libraries.md b/docs/howto/manage-libraries.md index 01dfa53b3..5403d2b48 100644 --- a/docs/howto/manage-libraries.md +++ b/docs/howto/manage-libraries.md @@ -220,7 +220,7 @@ def test_my_object_data(context, endpoint, n_relations): Fetch the library. -In your `src/charm.py`, observe the custom events it puts at your disposal. For example, a database library may have provided a `database_relation_ready` event -- a high-level wrapper around the relevant `juju` relation events -- so you use it to manage the database integration in your charm as below: +In your `src/charm.py`, observe the custom events it puts at your disposal. For example, a database library may have provided a `database_relation_ready` event -- a high-level wrapper around the relevant `juju` relation events -- so you use it to manage the database relation in your charm as below: ```python diff --git a/docs/howto/manage-relations.md b/docs/howto/manage-relations.md index 6198445a5..cf5f86807 100644 --- a/docs/howto/manage-relations.md +++ b/docs/howto/manage-relations.md @@ -2,7 +2,7 @@ # How to manage relations > See first: {external+juju:ref}`Juju | Relation `, {external+juju:ref}`Juju | Manage relations `, {external+charmcraft:ref}`Charmcraft | Manage relations ` -To add integration capabilities to a charm, you’ll have to define the relation in your charm’s charmcraft.yaml file and then add relation event handlers in your charm’s `src/charm.py` file. +To add relation capabilities to a charm, you’ll have to define the relation in your charm’s charmcraft.yaml file and then add relation event handlers in your charm’s `src/charm.py` file. ## Implement the feature @@ -65,7 +65,7 @@ Other than this, implement a subordinate relation in the same way as any other r #### Using a charm library -For most integrations, you will now want to progress with using the charm library recommended by the charm that you are integrating with. Read the documentation for the other charm on Charmhub and follow the instructions, which will typically involve adding a requirer object in your charm’s `__init__` and then observing custom events. +For most relations, you will now want to progress with using the charm library recommended by the charm that you are integrating with. Read the documentation for the other charm on Charmhub and follow the instructions, which will typically involve adding a requirer object in your charm’s `__init__` and then observing custom events. In most cases, the charm library will handle observing the Juju relation events, and your charm will only need to interact with the library’s custom API. Come back to this guide when you are ready to add tests. diff --git a/docs/howto/write-integration-tests-for-a-charm.md b/docs/howto/write-integration-tests-for-a-charm.md index 5aff7fea0..337fbad41 100644 --- a/docs/howto/write-integration-tests-for-a-charm.md +++ b/docs/howto/write-integration-tests-for-a-charm.md @@ -132,7 +132,7 @@ For `oci-images` you can reference an image registry. ### Test a relation -To test an integration between two applications, you can just integrate them through +To test a relation between two applications, integrate them through the model. Both applications have to be deployed beforehand. ``` diff --git a/docs/howto/write-unit-tests-for-a-charm.md b/docs/howto/write-unit-tests-for-a-charm.md index 55ac42be2..925cd2b72 100644 --- a/docs/howto/write-unit-tests-for-a-charm.md +++ b/docs/howto/write-unit-tests-for-a-charm.md @@ -99,7 +99,7 @@ harness.charm.unit.status = BlockedStatus("Testing") Any of your charm’s properties and methods (including event callbacks) can be accessed using `harness.charm`. You can check out the [harness API docs](ops_testing_harness) for more ways to use the -harness to trigger other events and to test your charm (e.g. triggering leadership-related events, +harness to trigger other events and to test your charm (e.g. triggering events regarding leadership, testing pebble events and sidecar container interactions, etc.). diff --git a/docs/index.md b/docs/index.md index a3a3462c7..8acc2d0d5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -24,7 +24,7 @@ The library provides: - {ref}`ops_testing`, the recommended API for unit testing charms - {ref}`ops_testing_harness`, the deprecated API for unit testing charms -You can structure your charm however you like, but with the `ops` library, you get a framework that promotes consistency and readability by following best practices. It also helps you organise your code better by separating different aspects of the charm, such as managing the application's state, handling integrations with other services, and making the charm easier to test. +You can structure your charm however you like, but with the `ops` library, you get a framework that promotes consistency and readability by following best practices. It also helps you organise your code better by separating different aspects of the charm, such as managing the application's state, handling integrating with other services, and making the charm easier to test. --------- diff --git a/docs/reference/ops-testing.rst b/docs/reference/ops-testing.rst index 16da0e5d5..29d9271cd 100644 --- a/docs/reference/ops-testing.rst +++ b/docs/reference/ops-testing.rst @@ -11,7 +11,7 @@ Juju state all at once, define the Juju context against which to test the charm, and fire a single event on the charm to execute its logic. The tests can then assert that the Juju state has changed as expected. -A very simple test, where the charm has no config, no integrations, the unit +A very simple test, where the charm has no config, no relations, the unit is the leader, and has a `start` handler that sets the status to active might look like this: @@ -38,8 +38,8 @@ Writing these tests should nudge you into thinking of a charm as a black-box 'input to output' function. The inputs are: - Event: why am I, the charm, being executed -- State: am I the leader? what is my integration data? what is my config? -- Context: what integrations can I have? what containers can I have? +- State: am I the leader? what is my relation data? what is my config? +- Context: what relations can I have? what containers can I have? The output is another `State`: the state after the charm has interacted with the mocked Juju model. diff --git a/docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/create-a-minimal-kubernetes-charm.md b/docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/create-a-minimal-kubernetes-charm.md index c595a6184..f11257366 100644 --- a/docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/create-a-minimal-kubernetes-charm.md +++ b/docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/create-a-minimal-kubernetes-charm.md @@ -59,7 +59,7 @@ title: | demo-fastapi-k8s description: | This is a demo charm built on top of a small Python FastAPI server. - This charm could be related to PostgreSQL charm and COS Lite bundle (Canonical Observability Stack). + This charm could be integrated with the PostgreSQL charm and COS Lite bundle (Canonical Observability Stack). summary: | FastAPI Demo charm for Kubernetes ``` diff --git a/docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/integrate-your-charm-with-postgresql.md b/docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/integrate-your-charm-with-postgresql.md index e6e711488..fd13498d2 100644 --- a/docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/integrate-your-charm-with-postgresql.md +++ b/docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/integrate-your-charm-with-postgresql.md @@ -47,7 +47,7 @@ Well done, you've got everything you need to set up a database relation! ## Define the charm relation interface Now, time to define the charm relation interface. @@ -243,12 +243,12 @@ def _on_database_created(self, event: DatabaseCreatedEvent) -> None: self._update_layer_and_restart() ``` -The diagram below illustrates the workflow for the case where the database integration exists and for the case where it does not: +The diagram below illustrates the workflow for the case where the database relation exists and for the case where it does not: ![Integrate your charm with PostgreSQL](../../resources/integrate_your_charm_with_postgresql.png) -## Update the unit status to reflect the integration state +## Update the unit status to reflect the relation state Now that the charm is getting more complex, there are many more cases where the unit status needs to be set. It's often convenient to do this in a more declarative fashion, which is where the collect-status event can be used. @@ -322,7 +322,7 @@ Now, integrate our charm with the newly deployed `postgresql-k8s` charm: juju integrate postgresql-k8s demo-api-charm ``` -> Read more: [Integration](https://juju.is/docs/olm/integration), [`juju integrate`](https://juju.is/docs/olm/juju-integrate) +> Read more: {external+juju:ref}`Juju | Relation (integration) `, [`juju integrate`](inv:juju:std:label#command-juju-integrate) Finally, run: @@ -379,7 +379,7 @@ This should produce something similar to the output below (of course, with the n {"names":{"1":"maksim","2":"simon"}} ``` -Congratulations, your integration with PostgreSQL is functional! +Congratulations, your relation with PostgreSQL is functional! ## Review the final code diff --git a/docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/observe-your-charm-with-cos-lite.md b/docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/observe-your-charm-with-cos-lite.md index 90f8345ca..b8454f1fc 100644 --- a/docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/observe-your-charm-with-cos-lite.md +++ b/docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/observe-your-charm-with-cos-lite.md @@ -67,7 +67,7 @@ Note: When you rebuild your charm with `charmcraft pack`, Charmcraft will copy t ### Define the Prometheus relation interface -In your `charmcraft.yaml` file, before the `peers` block, add a `provides` endpoint with relation name `metrics-endpoint` and interface name `prometheus_scrape`, as below. This declares that your charm can offer services to other charms over the `prometheus-scrape` interface. In short, that your charm is open to integrations with, for example, the official Prometheus charm. (Note: `metrics-endpoint` is the default relation name recommended by the `prometheus_scrape` interface library.) +In your `charmcraft.yaml` file, before the `peers` block, add a `provides` endpoint with relation name `metrics-endpoint` and interface name `prometheus_scrape`, as below. This declares that your charm can offer services to other charms over the `prometheus-scrape` interface. In short, that your charm is open to integrating with, for example, the official Prometheus charm. (Note: `metrics-endpoint` is the default relation name recommended by the `prometheus_scrape` interface library.) ```yaml provides: @@ -139,7 +139,7 @@ Note: When you rebuild your charm with `charmcraft pack`, Charmcraft will copy t ### Define the Loki relation interface -In your `charmcraft.yaml` file, beneath your existing `requires` endpoint, add another `requires` endpoint with relation name `log-proxy` and interface name `loki_push_api`. This declares that your charm can optionally make use of services from other charms over the `loki_push_api` interface. In short, that your charm is open to integrations with, for example, the official Loki charm. (Note: `log-proxy` is the default relation name recommended by the `loki_push_api` interface library.) +In your `charmcraft.yaml` file, beneath your existing `requires` endpoint, add another `requires` endpoint with relation name `log-proxy` and interface name `loki_push_api`. This declares that your charm can optionally make use of services from other charms over the `loki_push_api` interface. In short, that your charm is open to integrating with, for example, the official Loki charm. (Note: `log-proxy` is the default relation name recommended by the `loki_push_api` interface library.) ```yaml @@ -203,7 +203,7 @@ Note: The `grafana_dashboard` library also depends on the [`juju_topology`](htt ### Define the Grafana relation interface -In your `charmcraft.yaml` file, add another `provides` endpoint with relation name `grafana-dashboard` and interface name `grafana_dashboard`, as below. This declares that your charm can offer services to other charms over the `grafana-dashboard` interface. In short, that your charm is open to integrations with, for example, the official Grafana charm. (Note: Here `grafana-dashboard` endpoint is the default relation name recommended by the `grafana_dashboard` library.) +In your `charmcraft.yaml` file, add another `provides` endpoint with relation name `grafana-dashboard` and interface name `grafana_dashboard`, as below. This declares that your charm can offer services to other charms over the `grafana-dashboard` interface. In short, that your charm is open to integrating with, for example, the official Grafana charm. (Note: Here `grafana-dashboard` endpoint is the default relation name recommended by the `grafana_dashboard` library.) ```yaml provides: @@ -287,9 +287,9 @@ juju deploy cos-lite --trust ``` -### Expose the application integration endpoints +### Expose the application relation endpoints -Once all the COS Lite applications are deployed and settled down (you can monitor this by using `juju status --watch 2s`), expose the integration points you are interested in for your charm -- `loki:logging`, `grafana-dashboard`, and `metrics-endpoint` -- as below. +Once all the COS Lite applications are deployed and settled down (you can monitor this by using `juju status --watch 2s`), expose the relation points you are interested in for your charm -- `loki:logging`, `grafana-dashboard`, and `metrics-endpoint` -- as below. ```text juju offer prometheus:metrics-endpoint diff --git a/docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/write-integration-tests-for-your-charm.md b/docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/write-integration-tests-for-your-charm.md index 0540e77c7..ad65be6b9 100644 --- a/docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/write-integration-tests-for-your-charm.md +++ b/docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/write-integration-tests-for-your-charm.md @@ -79,7 +79,7 @@ APP_NAME = METADATA['name'] @pytest.mark.abort_on_fail async def test_build_and_deploy(ops_test: OpsTest): - """Build the charm-under-test and deploy it together with related charms. + """Build the charm-under-test and deploy it. Assert on the unit status before any relations/configurations take place. """ diff --git a/ops/_private/harness.py b/ops/_private/harness.py index 009b7ff94..3403aa9c9 100644 --- a/ops/_private/harness.py +++ b/ops/_private/harness.py @@ -537,7 +537,7 @@ def begin_with_initial_hooks(self) -> None: # Note: Juju *does* fire relation events for a given relation in the sorted order of # the unit names. It also always fires relation-changed immediately after # relation-joined for the same unit. - # Juju only fires relation-changed (app) if there is data for the related application + # Juju only fires relation-changed (app) if there is data for the integrated app relation = self._model.get_relation(rel_name, rel_id) if self._backend._relation_data_raw[rel_id].get(app_name): app = self._model.get_app(app_name) diff --git a/ops/charm.py b/ops/charm.py index 98bb8b1ac..13184353e 100644 --- a/ops/charm.py +++ b/ops/charm.py @@ -550,7 +550,7 @@ def restore(self, snapshot: Dict[str, Any]): class RelationCreatedEvent(RelationEvent): """Event triggered when a new relation is created. - This is triggered when a new integration with another app is added in Juju. This + This is triggered when a new relation with another app is added in Juju. This can occur before units for those applications have started. All existing relations will trigger `RelationCreatedEvent` before :class:`~ops.StartEvent` is emitted. @@ -563,7 +563,7 @@ class RelationCreatedEvent(RelationEvent): class RelationJoinedEvent(RelationEvent): """Event triggered when a new unit joins a relation. - This event is triggered whenever a new unit of a related + This event is triggered whenever a new unit of an integrated application joins the relation. The event fires only when that remote unit is first observed by the unit. Callback methods bound to this event may set any local unit data that can be @@ -579,8 +579,8 @@ class RelationJoinedEvent(RelationEvent): class RelationChangedEvent(RelationEvent): """Event triggered when relation data changes. - This event is triggered whenever there is a change to the data bucket for a - related application or unit. Look at ``event.relation.data[event.unit/app]`` + This event is triggered whenever there is a change to the data bucket for an + integrated application or unit. Look at ``event.relation.data[event.unit/app]`` to see the new information, where ``event`` is the event object passed to the callback method bound to this event. @@ -682,7 +682,7 @@ class RelationBrokenEvent(RelationEvent): class StorageEvent(HookEvent): - """Base class representing storage-related events. + """Base class representing events to do with storage. Juju can provide a variety of storage types to a charms. The charms can define several different types of storage that are @@ -766,7 +766,7 @@ class StorageDetachingEvent(StorageEvent): class WorkloadEvent(HookEvent): - """Base class representing workload-related events. + """Base class representing events to do with the workload. Workload events are generated for all containers that the charm expects in metadata. diff --git a/ops/model.py b/ops/model.py index a86c2db2b..b3fac6d65 100644 --- a/ops/model.py +++ b/ops/model.py @@ -253,7 +253,7 @@ def get_relation( given application has more than one relation on a given endpoint. Raises: - TooManyRelatedAppsError: is raised if there is more than one integration with the + TooManyRelatedAppsError: is raised if there is more than one relation with the supplied relation_name and no relation_id was supplied """ return self.relations._get_unique(relation_name, relation_id) @@ -2107,7 +2107,7 @@ class MaintenanceStatus(StatusBase): ``apt install``, or is waiting for something under its control, such as ``pebble-ready`` or an exec operation in the workload container. In contrast to :class:`WaitingStatus`, "maintenance" reflects activity on - this unit or charm, not on peers or related units. + this unit (for unit status), or this app (for app status). """ name = 'maintenance' @@ -2120,7 +2120,8 @@ class WaitingStatus(StatusBase): example, a web app charm would set "waiting" status when it is integrated with a database charm that is not ready yet (it might be creating a database). In contrast to :class:`MaintenanceStatus`, "waiting" reflects - activity on related units, not on this unit or charm. + activity on integrated units (for unit status) and integrated apps (for + app status). """ name = 'waiting' diff --git a/testing/README.md b/testing/README.md index b9eedeefa..77a538b53 100644 --- a/testing/README.md +++ b/testing/README.md @@ -414,7 +414,7 @@ remote_unit_2_is_joining_event = ctx.on.relation_joined(relation, remote_unit=2) ## Networks -Simplifying a bit the Juju "spaces" model, each integration endpoint a charm defines in its metadata is associated with a network. Regardless of whether there is a living relation over that endpoint, that is. +Simplifying a bit the Juju "spaces" model, each relation endpoint a charm defines in its metadata is associated with a network. Regardless of whether there is a living relation over that endpoint, that is. If your charm has a relation `"foo"` (defined in its metadata), then the charm will be able at runtime to do `self.model.get_binding("foo").network`. The network you'll get by doing so is heavily defaulted (see `state.Network`) and good for most use-cases because the charm should typically not be concerned about what IP it gets. diff --git a/testing/src/scenario/__init__.py b/testing/src/scenario/__init__.py index 2cf042cc6..5693a3944 100644 --- a/testing/src/scenario/__init__.py +++ b/testing/src/scenario/__init__.py @@ -20,8 +20,8 @@ Writing these tests should nudge you into thinking of a charm as a black-box input->output function. The input is the union of an `Event` (why am I, charm, -being executed), a `State` (am I leader? what is my integration data? what is my -config?...) and the charm's execution `Context` (what integrations can I have? +being executed), a `State` (am I leader? what is my relation data? what is my +config?...) and the charm's execution `Context` (what relations can I have? what containers can I have?...). The output is another `State`: the state after the charm has had a chance to interact with the mocked Juju model and affect the state. @@ -49,7 +49,7 @@ assertions on APIs and state internal to it. The most basic scenario is one in which all is defaulted and barely any data is -available. The charm has no config, no integrations, no leadership, and its +available. The charm has no config, no relations, no leadership, and its status is `unknown`. With that, we can write the simplest possible test: .. code-block:: python diff --git a/testing/src/scenario/_consistency_checker.py b/testing/src/scenario/_consistency_checker.py index 33bcc4936..2b90289a5 100644 --- a/testing/src/scenario/_consistency_checker.py +++ b/testing/src/scenario/_consistency_checker.py @@ -534,7 +534,7 @@ def check_network_consistency( endpoints = {endpoint for endpoint, _ in all_relations} if collisions := endpoints.intersection(meta_bindings): errors.append( - f"Extra bindings and integration endpoints cannot share the same name: {collisions}.", + f"Extra bindings and relation endpoints cannot share the same name: {collisions}.", ) return Results(errors, []) diff --git a/testing/src/scenario/state.py b/testing/src/scenario/state.py index d68bfc660..da22e3fe9 100644 --- a/testing/src/scenario/state.py +++ b/testing/src/scenario/state.py @@ -490,7 +490,7 @@ def _next_relation_id(*, update: bool = True): @dataclasses.dataclass(frozen=True) class RelationBase(_max_posargs(2)): - """Base class for the various types of integration (relation).""" + """Base class for the various types of relation.""" endpoint: str """Relation endpoint name. Must match some endpoint name defined in the metadata.""" @@ -573,14 +573,14 @@ def _validate_databag(self, databag: dict[str, str]): @dataclasses.dataclass(frozen=True) class Relation(RelationBase): - """An integration between the charm and another application.""" + """A relation between the charm and another application.""" remote_app_name: str = "remote" """The name of the remote application, as in the charm's metadata.""" # local limit limit: int = 1 - """The maximum number of integrations on this endpoint.""" + """The maximum number of relations on this endpoint.""" remote_app_data: RawDataBagContents = dataclasses.field(default_factory=dict) """The current content of the application databag."""