docs: explain how to remove errored apps in k8s tutorial

[gcomneno]

Summary

• explain that juju refresh won't work when the app is in awaiting error resolution
• document using juju remove-application fastapi-demo --force in that situation
• add this guidance to the affected Kubernetes tutorial pages

Issue

• closes In the K8s tutorial, advise how to remove an errored app #2442

[tonyandrewmeyer]

The "juju refresh will not work" isn't really true, because in the tutorial we say to use --force-units, which ignores the error state.

I'm also not sold on suggesting remove-application here, because you're either about to deploy it for the first time (if something went wrong, we should have advice for fixing that after the deploy step), or it's deployed and you're refreshing, in which case we are suggesting removing without suggesting deploying again.

@gcomneno did you have this problem, or are you just working on the PR because there is an open issue for it? If you had the problem, did you try using --force-units, and it failed?

@dwilding you opened the linked issue - did you experience this or get feedback from someone working through the tutorial?

In general, I would prefer that we encourage people to use --force-units and resolve than teach them that they should reach for --force as a first step. A 'remove and redeploy' is ok, but I think there are methods people should be trying before that too.

[gcomneno]

Thanks, that makes sense.

I did not hit this personally while working through the tutorial — I picked it up based on the open issue and followed the problem statement there. So yes, this change was based on the issue report rather than on a reproduction from my side.

You are right that my wording is too absolute, especially given the existing --force-units usage in the tutorial. I also agree that jumping straight to remove-application --force is probably too strong if we have not first established the exact failure mode and the intermediate recovery steps we want users to try.

I will hold off on pushing a revised version until we get clarification from @dwilding on the scenario they had in mind, unless you would prefer that I just trim this back now and remove the remove-application --force guidance entirely.

[james-garner-canonical]

@dwilding opened the issue after discussion with me. An onboarder I was mentoring encountered this after getting a charm into a bad state, after which juju refresh did not appear to succeed. I missed that the tutorial already says to use --force-units, which presumably would have resolved the problem.

The current formatting of the command in the docs somewhat hides the flag:

juju refresh \
  --path="./fastapi-demo_amd64.charm" \
  fastapi-demo --force-units --resource \
  demo-server-image=ghcr.io/canonical/api_demo_server:1.0.2

I wonder if we should reformat to something like this in all cases (need to test that Juju is happy with the options ordered like this, and that it doesn't linebreak awkwardly in the docs):

juju refresh fastapi-demo --force-units \
  --path="./fastapi-demo_amd64.charm" \
  --resource demo-server-image=ghcr.io/canonical/api_demo_server:1.0.2

And perhaps add a tip after the first use of refresh like: "Don't forget --force-units! Otherwise if your charm is in a bad state, juju refresh won't succeed."

[tonyandrewmeyer]

Thanks @james-garner-canonical - I talked to David about this today but hadn't had a chance to reach out to you yet (busy day!).

I think rearranging to emphasise force-units, and a tip that suggest it and explains what it does sound like good ideas. I've rather avoid the remove-deploy pattern unless we hear that force-units is breaking (and even then, I would rather talk to the Juju folk first).

I think we ought to be able to do the rearranging in each chapter, but I think the tip in just the first one would be sufficient.

[gcomneno]

Updated the tutorial as discussed:

• reordered each juju refresh command to make --force-units more visible
• added a tip about --force-units at the first relevant refresh step
• removed the remove-application --force fallback suggestion

Validated locally with:

• make -C docs html
• make -C docs vale TARGET='\''docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/*.md'\''
• make -C docs spelling TARGET='\''docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/*.md'\''

[tonyandrewmeyer]

Thanks @gcomneno ! I think this will help people, and if there are any continuing issues we should look into what's going wrong before adjusting the docs.

[gcomneno]

Thanks Tony — glad this looks helpful.

Agreed: if people keep running into issues here, it’s better to understand what’s actually going wrong in Juju before we make the docs more prescriptive.

Happy to tweak anything else if needed.

[gcomneno]

Thanks again for the review and approval.

Just checking in: from my side this looks ready, but please let me know if there is anything else you’d like me to adjust before merge.