Skip to content

Commit d94f13e

Browse files
committed
Updated links that should loop back to Ops
1 parent 0b23b6f commit d94f13e

9 files changed

+9
-12
lines changed

docs/explanation/holistic-vs-delta-charms.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,6 @@ Only some events make sense to handle holistically. For example, `remove` is tri
6161

6262
Similarly, events like `secret-expired` and `secret-rotate` don't make sense to handle holistically, because the charm must do something specific in response to the event. For example, Juju will keep triggering `secret-expired` until the charm creates a new secret revision by calling [`event.secret.set_content()`](ops.Secret.set_content).
6363

64-
This is very closely related to [which events can be `defer`red](https://juju.is/docs/sdk/how-and-when-to-defer-events). A good rule of thumb is this: if an event can be deferred, it may make sense to handle it holistically.
64+
This is very closely related to [which events can be `defer`red](#how-and-when-to-defer-events). A good rule of thumb is this: if an event can be deferred, it may make sense to handle it holistically.
6565

6666
On the other hand, if an event cannot be deferred, the charm cannot handle it holistically. This applies to action "events", `stop`, `remove`, `secret-expired`, `secret-rotate`, and Ops-emitted events such as `collect-status`.

docs/explanation/how-and-when-to-defer-events.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
(how-and-when-to-defer-events)=
21
# How, and when, to defer events
32

43
Deferring an event is a common pattern, and when used appropriately is a convenient tool for charmers. However, there are limitations to `defer()` - in particular, that the charm has no way to specify when the handler will be re-run, and that event ordering and context move away from the expected pattern. Our advice is that `defer()` is a good solution for some problems, but is best avoided for others.
@@ -9,7 +8,7 @@ If the charm encounters a temporary failure (such as working with a container or
98

109
Note that it’s important to consider that when the deferred handler is run again, the Juju context may not be exactly the same as it was when the event was first emitted, so the charm code needs to be aware of this.
1110

12-
If the temporary failure is because the workload is busy, and the charm is deployed to a Kubernetes sidecar controller, you might be able to avoid the defer using a [Pebble custom notice](https://juju.is/docs/sdk/interact-with-pebble#heading--use-custom-notices-from-the-workload-container). For example, if the code can’t continue because the workload is currently restarting, if you can have a post-completion hook for the restart that executes `pebble notify`, then you can ensure that the charm is ‘woken up’ at the right time to handle the work.
11+
If the temporary failure is because the workload is busy, and the charm is deployed to a Kubernetes sidecar controller, you might be able to avoid the defer using a [Pebble custom notice](#use-custom-notices-from-the-workload-container). For example, if the code can’t continue because the workload is currently restarting, if you can have a post-completion hook for the restart that executes `pebble notify`, then you can ensure that the charm is ‘woken up’ at the right time to handle the work.
1312

1413
In the future, we hope to see a Juju ‘request re-emit event’ feature that will let the charm tell Juju when it expects the problem to be resolved.
1514

@@ -33,7 +32,7 @@ In some situations, the charm is waiting for a system to be ready, but it’s no
3332

3433
Deferring the work here is ok, but it’s important to consider the delay between deferring the event and its eventual re-emitting - it’s not safe to assume that this will be a small period of time, unless you know that another event can be expected.
3534

36-
For a Kubernetes charm, If the charm is waiting on the workload and it’s possible to have the workload execute a command when it’s ready, then using a [Pebble custom notice](https://juju.is/docs/sdk/interact-with-pebble#heading--use-custom-notices-from-the-workload-container) is much better than deferring. This then becomes another example of “waiting for a collection of events”, described above.
35+
For a Kubernetes charm, If the charm is waiting on the workload and it’s possible to have the workload execute a command when it’s ready, then using a [Pebble custom notice](#use-custom-notices-from-the-workload-container) is much better than deferring. This then becomes another example of “waiting for a collection of events”, described above.
3736

3837
## Not possible: actions, shutting down, framework generated events, secrets
3938

docs/howto/get-started-with-charm-testing.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
(get-started-with-charm-testing)=
21
# Get started with charm testing
32

43
Testing charm code is an essential part of charming. Here we will see how to get started with it. We will look at the templates we have available and the frameworks we can use to write good unit, integration, and functional tests.

docs/howto/manage-storage.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ In the `src/charm.py` file, in the `__init__` function of your charm, set up an
4848
self.framework.observe(self.on.cache_storage_attached, self._update_configuration)
4949
```
5050

51-
> See more: [](ops.StorageAttachedEvent), [Juju SDK | Holistic vs delta charms](https://juju.is/docs/sdk/holistic-vs-delta-charms)
51+
> See more: [](ops.StorageAttachedEvent), [](#holistic-vs-delta-charms)
5252

5353
Storage volumes will be automatically mounted into the charm container at either the path specified in the `location` field in the metadata, or the default location `/var/lib/juju/storage/<storage-name>`. However, your charm code should not hard-code the location, and should instead use the `.location` property of the storage object.
5454

docs/howto/manage-the-workload-version.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ def _on_start(self, event: ops.StartEvent):
5353
5454
## Test the feature
5555

56-
> See first: [Get started with charm testing](https://juju.is/docs/sdk/get-started-with-charm-testing)
56+
> See first: [](#get-started-with-charm-testing)
5757
5858
You'll want to add unit and integration tests.
5959

docs/howto/run-workloads-with-a-charm-kubernetes.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -823,6 +823,7 @@ Traceback (most recent call last):
823823
ops.pebble.ExecError: non-zero exit code 143 executing ['sleep', '10']
824824
```
825825

826+
(use-custom-notices-from-the-workload-container)=
826827
## Use custom notices from the workload container
827828

828829
### Record a notice

docs/howto/turn-a-hooks-based-charm-into-an-ops-charm.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,6 @@ It is in our interest to move the handler logic for each `/hooks/<hook_name>` to
136136
- We can avoid code duplication by accessing shared data via the CharmBase interface provided through `self`.
137137
- The code is all in one place, easier to maintain.
138138
- We automatically have one Python object we can test, instead of going back and forth between Bash scripts and Python wrappers.
139-
- We can use [the awesome testing Harness](https://juju.is/docs/sdk/testing).
140139

141140
So let's do that.
142141

@@ -206,7 +205,7 @@ That allows us to fetch the Relation wherever we need it and access its contents
206205
)
207206
```
208207

209-
Note how `relation.data` provides an interface to the relation databag (more on that [here](https://juju.is/docs/sdk/relations#heading--relation-data)) and we need to select which part of that bag to access by passing an `ops.model.Unit` instance.
208+
Note how `relation.data` provides an interface to the relation databag (see [](#ops.Relation.data)) and we need to select which part of that bag to access by passing an `ops.model.Unit` instance.
210209

211210
#### Logging
212211

docs/howto/write-unit-tests-for-a-charm.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ Notably, specifying relations in `charmcraft.yaml` does not automatically make t
7474
harness. If you have e.g. code that accesses relation data, you must manually add those relations
7575
(including peer relations) for the harness to provide access to that relation data to your charm.
7676

77-
In some cases it may be useful to start the test harness and fire the same hooks that Juju would fire on deployment. This can be achieved using the `begin_with_initial_hooks()` method , to be used in place of the `begin()` method. This method will trigger the events: `install -> relation-created -> config-changed -> start -> relation-joined` depending on whether any relations have been created prior calling `begin_with_initial_hooks()`. An example of this is shown in the [testing relations](https://juju.is/docs/sdk/relations) section.
77+
In some cases it may be useful to start the test harness and fire the same hooks that Juju would fire on deployment. This can be achieved using the `begin_with_initial_hooks()` method , to be used in place of the `begin()` method. This method will trigger the events: `install -> relation-created -> config-changed -> start -> relation-joined` depending on whether any relations have been created prior calling `begin_with_initial_hooks()`. An example of this is shown in [](#ops.testing.Harness).
7878

7979
Using the `harness` variable, we can simulate various events in the charm’s lifecycle:
8080

docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/integrate-your-charm-with-postgresql.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -252,8 +252,7 @@ The diagram below illustrates the workflow for the case where the database integ
252252

253253
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.
254254

255-
<!-- TODO: this page doesn't belong in the Juju docs, it should be moved over to ops and this can be a local reference. -->
256-
> Read more: [Events > Collect App Status and Collect Unit Status](https://juju.is/docs/sdk/events-collect-app-status-and-collect-unit-status)
255+
> Read more: [](#ops.CollectStatusEvent)
257256
258257
In your charm's `__init__` add a new observer:
259258

0 commit comments

Comments
 (0)