Skip to content

Commit

Permalink
docs: small updates to machine charm tutorial (#1583)
Browse files Browse the repository at this point in the history
This PR is for capturing small updates to [Write your first machine
charm](https://ops.readthedocs.io/en/latest/tutorial/write-your-first-machine-charm.html)
while I'm working on creating my own sample machine charm.

Summary of changes:

- Adjusted the "What you'll need section" to tidy up the language &
formatting, and to clarify that familiarity with Juju is not an absolute
requirement.

- When using `curl` to test the service after the initial deployment, we
don't need to `juju exec` into the unit first. Instead, we can do `curl
http://10.122.219.101:8080`, where 10.122.219.101 is the IP of the unit.
I've updated the command and the preceding text to match.

- Added missing context to the note that comes after using `curl` to
test the service. This note was supposed to say that the reader should
follow the four steps in case something went wrong after deploying the
charm. I added this context.

I also removed a commented-out part about inspecting hooks. In the
newly-added context, I mention about `juju debug-log`, which is probably
more useful than inspecting hooks.

**[Preview
doc](https://ops--1583.org.readthedocs.build/en/1583/tutorial/write-your-first-machine-charm.html)**
  • Loading branch information
dwilding authored Feb 26, 2025
1 parent 54eac5b commit b1b375e
Showing 1 changed file with 16 additions and 27 deletions.
43 changes: 16 additions & 27 deletions docs/tutorial/write-your-first-machine-charm.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,12 @@ When it's available in Juju.
-->

**What you'll need:**
- A workstation, e.g., a laptop, with amd64 architecture and which has sufficient resources to launch a virtual machine with 4 CPUs, 8 GB RAM, and 50 GB disk space
- Familiarity with Linux
- Familiarity with Juju.
- Familiarity with object-oriented programming in Python

- A workstation. For example, a laptop with an amd64 architecture. You'll need sufficient resources to launch a virtual machine with 4 CPUs, 8 GB RAM, and 50 GB disk space.
- Familiarity with Linux.
- Familiarity with the Python programming language, including Object-Oriented Programming and event handlers.

It will also help if you're familiar with Juju, but don't worry if you're new to Juju. This tutorial will guide you through each step.

**What you'll do:**

Expand Down Expand Up @@ -232,39 +234,26 @@ Machine State Address Inst id Base AZ Message
```

Finally, test that the service works by executing `curl` on your application unit:
Finally, use `curl` to test that the service works. Get the address of the running machine from the Juju status
(10.122.219.101 in this example), then run `curl`:

```text
ubuntu@charm-dev:~/microsample-vm$ juju exec --unit microsample/0 -- "curl -s http://localhost:8080"
ubuntu@charm-dev:~/microsample-vm$ curl http://10.122.219.101:8080
Online
```

```{note}
1. Fix the code in `src/charm.py`.
2. Rebuild the charm: `charmcraft pack`
3. Refresh the application from the repacked charm: `juju refresh microsample --path=./microsample-vm_ubuntu-22.04-amd64.charm --force-units`
4. Let the model know the issue is resolved (fixed): `juju resolved microsample/0`.
If the Juju status doesn't look right, for example if you see an "error" status instead of "active",
there might be an issue with the charm code. You can use a debug session (`juju debug-log`) to get
more detailed information about the issue. After you've identified the issue:
```
1. Fix the code in `src/charm.py`.
2. Rebuild the charm: `charmcraft pack`.
3. Refresh the application from the repacked charm: `juju refresh microsample --path=./microsample-vm_ubuntu-22.04-amd64.charm --force-units`.
4. Let the model know that you've fixed the issue: `juju resolved microsample/0`.
<!--Might be nice to get people to observe the hooks too:
```
unit-microsample-vm-0
root@microsample-vm-0:/var/lib/juju/agents# cd unit-microsample-vm-0/
root@microsample-vm-0:/var/lib/juju/agents/unit-microsample-vm-0# ls
agent.conf charm run.socket state
root@microsample-vm-0:/var/lib/juju/agents/unit-microsample-vm-0# cd charm
root@microsample-vm-0:/var/lib/juju/agents/unit-microsample-vm-0/charm# ls
LICENSE README.md dispatch hooks manifest.yaml metadata.yaml revision src venv
root@microsample-vm-0:/var/lib/juju/agents/unit-microsample-vm-0/charm# cd hooks
root@microsample-vm-0:/var/lib/juju/agents/unit-microsample-vm-0/charm/hooks# ls
install start upgrade-charm
root@microsample-vm-0:/var/lib/juju/agents/unit-microsample-vm-0/charm/hooks#
```
-->



```{note}
Expand Down

0 comments on commit b1b375e

Please sign in to comment.