Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: fill out remaining external link placeholders #1564

Merged
merged 3 commits into from
Feb 11, 2025
Merged

docs: fill out remaining external link placeholders #1564

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e54b766
Remove the trailing slash, which is not required.
tonyandrewmeyer Feb 4, 2025
6e1f4eb
Fill out remaining 'update links' notes in the docs.
tonyandrewmeyer Feb 4, 2025
7484568
Update docs/howto/write-integration-tests-for-a-charm.md
tonyandrewmeyer Feb 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/custom_conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@
# For example: "ubuntu.com/lxd" or "microcloud.is"
# If there is no product website, edit the header template to remove the
# link (see the readme for instructions).
'product_page': 'juju.is/docs/sdk',
'product_page': 'juju.is',
# Add your product tag (the orange part of your logo, will be used in the
# header) to ".sphinx/_static" and change the path here (start with "_static")
# (default is the circle of friends)
Expand Down Expand Up @@ -297,8 +297,8 @@
# that should be linked to in this documentation.
intersphinx_mapping = {
'python': ('https://docs.python.org/3', None),
'juju': ('https://canonical-juju.readthedocs-hosted.com/en/latest/', None),
'charmcraft': ('https://canonical-charmcraft.readthedocs-hosted.com/en/latest/', None),
'juju': ('https://canonical-juju.readthedocs-hosted.com/en/latest', None),
'charmcraft': ('https://canonical-charmcraft.readthedocs-hosted.com/en/latest', None),
}

# -- General configuration ---------------------------------------------------
Expand Down
12 changes: 3 additions & 9 deletions docs/explanation/storedstate-uses-limitations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,7 @@

This is an explanatory doc covering how charm authors might track local state in a Juju unit. We'll cover the `ops` concept of [](ops.StoredState), along with some differences in how it works between machine charms and Kubernetes charms. We'll talk about Peer Relations as an alternative for storing some kinds of information, and also talk about how charm authors probably should avoid recording state when they can avoid doing so.

<!-- UPDATE LINKS
"Peer Relations", above
-->
> See more: {external+juju:ref}`Peer Relations <manage-relations>`

## A trivial example

Expand Down Expand Up @@ -107,14 +105,10 @@ def some_event_handler(event):

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?)

<!-- UPDATE LINKS
"Juju Storage" above
-->
> See more: {external+juju:ref}`Juju Storage <manage-storage>`

In the cases where it is important to share some lightweight configuration data between units of an application, charm author's should look into peer relations. And in the cases where data must be written to a container's local file system (Canonical's Kubeflow bundle, for example, must do this, because the sheer number of services mean that we run into limitations on attached storage in the underlying cloud), authors should do so mindfully, with an understanding of the pitfalls involved.

<!-- UPDATE LINKS
"peer relations", above
-->
> See more: {external+juju:ref}`Peer Relations <manage-relations>`

In sum: use state mindfully, with well chosen tools, only when necessary.
4 changes: 0 additions & 4 deletions docs/howto/get-started-with-charm-testing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,10 +77,6 @@ If the charm is a machine charm, workload operation calls can be done directly,

"Juju operations" are the most 'meta' of them all: they do not affect the workload in and of itself, but they share data which is meant to affect the operation of *other* charms that this charm is integrated with.

<!-- UPDATE LINKS:
> See more: [Talking to a workload: control flow from A to Z](), [Charm lifecycle]()
-->

### What we are testing when we unit-test

A 'live', deployed Juju application will have access to all the inputs we discussed above, including environment variables, host system access, and more. Unit tests will typically want to mock all that and focus on mapping inputs to expected outputs. Any combination of the input sources we mentioned above can result in any combination of operations. A few examples of increasing complexity of scenarios we may want to unit test:
Expand Down
6 changes: 1 addition & 5 deletions docs/howto/manage-stored-state.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,18 +120,14 @@ store the data in the relation databag.

#### Define a peer relation

Update the `charmcraft.yaml` file to add a `peers` block, as below:
Update the {external+charmcraft:ref}`charmcraft.yaml file <charmcraft-yaml-file>` to add a `peers` block, as below:

```yaml
peers:
charm-peer:
interface: my_charm_peers
```

<!-- UPDATE LINKS
> Read more: [File ‘charmcraft.yaml`]()
-->

#### Set and get data from the peer relation databag

In your `src/charm.py` file, set and get the data from the peer relation
Expand Down
25 changes: 6 additions & 19 deletions docs/howto/write-integration-tests-for-a-charm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,7 @@ The instructions all use the Juju `python-libjuju` client, either through the `p

In order to run integrations tests you will need to have your environment set up with `tox` installed.

<!-- UPDATE LINKS
> See more: {ref}`How to set up your development environment <set-up-your-development-environment>`
-->
> See more: {external+juju:ref}`How to set up your development environment <manage-your-deployment-environment>`

## Prepare the `tox.ini` configuration file

Expand Down Expand Up @@ -175,9 +173,7 @@ async def test_config_changed(ops_test: OpsTest):

### Test an action

<!-- UPDATE LINKS
> See also: [Action]()
-->
> See also: {external+juju:ref}`Action <action>`

You can execute an action on a unit and get its results.

Expand Down Expand Up @@ -214,11 +210,9 @@ How you can connect to a private or public address is dependent on your configur

> Example implementations: [mongodb-k8s-operator](https://github.com/canonical/mongodb-k8s-operator/blob/8b9ebbee3f225ca98175c25781f1936dc4a62a7d/tests/integration/metrics_tests/test_metrics.py#L33), [tempo-k8s-operator](https://github.com/canonical/tempo-k8s-operator/blob/78a1143d99af99a1a56fe9ff82b1a3563e4fd2f7/tests/integration/test_integration.py#L69), [synapse](https://github.com/canonical/synapse-operator/blob/eb44f4959a00040f08b98470f8b17cae4cc616da/tests/integration/conftest.py#L170)

<!-- UPDATE LINKS:
> See more:
> - [Charm development best practices > Fetching network information]()
> - [`juju` CLI commands > juju expose]()
-->
> - {external+juju:ref}`Charm development best practices > Fetching network information <charm-development-best-practices>`
> - {external+juju:ref}`juju CLI commands > juju expose <command-juju-expose>`

### Run a subprocess command within Juju context

Expand Down Expand Up @@ -280,15 +274,12 @@ Using the new alias, you can switch context to the new created model, similar to

> Example implementations: [`charm-kubernetes-autoscaler`](https://github.com/charmed-kubernetes/charm-kubernetes-autoscaler/blob/8f4ddf5d66802ade73ed3aab2bb8d09fd9e4d63a/tests/integration/test_kubernetes_autoscaler.py#L31)

<!-- UPDATE LINKS:
> See more:
> - [Juju offers]()
> - [How to manage clouds]()
> - {external+juju:ref}`Juju offers <manage-offers>`
> - {external+juju:ref}`How to manage clouds <manage-clouds>`
> - [pytest-operator | track_model](https://github.com/charmed-kubernetes/pytest-operator/blob/ab50fc20320d3ea3d8a37495f92a004531a4023f/pytest_operator/plugin.py#L720)
> - [pytest-operator | model_context](https://github.com/charmed-kubernetes/pytest-operator/blob/ab50fc20320d3ea3d8a37495f92a004531a4023f/pytest_operator/plugin.py#L480)
> - [pytest-operator | forget_model](https://github.com/charmed-kubernetes/pytest-operator/blob/ab50fc20320d3ea3d8a37495f92a004531a4023f/pytest_operator/plugin.py#L812)
-->


### Deploy a bundle

Expand Down Expand Up @@ -377,10 +368,6 @@ There are different ways of specifying a subset of tests to run using `pytest`.
tox -e integration -- tests/integration/test_charm.py -k "not test_one"
```

<!-- UPDATE LINKS:
> Example implementations: [`mysql-k8s-operator`]()
-->

Comment on lines -380 to -383
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dropping this seems fine especially since we're going to be recommending jubilant for integration tests

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I figure this entire page will be rewritten this cycle so there's no much point making any improvements.

> See more:
> - [`pytest-operator` | `skip_if_deployed`](https://github.com/charmed-kubernetes/pytest-operator/blob/ab50fc20320d3ea3d8a37495f92a004531a4023f/pytest_operator/plugin.py#L139)
> - [`pytest | How to invoke pytest`](https://docs.pytest.org/en/7.1.x/how-to/usage.html)
Expand Down