`Action.wait_until_finished()` does not wait long enough after server shutdown

[scy]

Bug Report

I'm not exactly sure whether this is a bug in the API client or rather in the backend service.

Current Behavior
Before rescaling a server, it needs to be shut down. However, issuing a rescale request directly after the shutdown has completed will still lead to an APIException: server must be stopped before changing type (server_not_stopped). If you check the server's status after the shutdown action completes, it's still running for several seconds.

Input Code

server = client.servers.get_by_name("bojack")
action = server.shutdown()
action.wait_until_finished()
# Now, action.finished has a timestamp, i.e. the action has been completed.
# We should be able to do this now:
server.change_type(server_type="cax31", upgrade_disk=False)
# But it'll throw a "server_not_stopped" exception instead.

Expected behavior/code
I should be able to issue the change_type request instantly after wait_until_finished() has returned. But I can't. The only option that's left for me at this point is to wait until the status is actually off like this:

server = client.servers.get_by_name("bojack")
action = server.shutdown()
action.wait_until_finished()
for i in range(10):
    if client.servers.get_by_name("bojack").status == "off":
        break
    time.sleep(5)
server.change_type(server_type="cax31", upgrade_disk=False)

Environment

• Python Version: 3.13.1
• Hcloud-Python Version: 2.5.1

Possible Solution

As I said, I'm not sure whether this is an issue in this library at all or the API server or backend is to blame, but right now it's kind of counter-intuitive.

You know what might actually the most convenient solution? Add two options to the rescale API call: shutdown: bool and power_off: bool. Both should default to false, but it I set one of them to true, the server will be ACPI shut down or forcefully powered off (respectively) before the rescale. That way, users wouldn't even have to do multiple API calls for this operation.

[jooola]

The shutdown action does not wait for the guest os to fully shutdown, this behavior is expected, according to the API documentation: https://docs.hetzner.cloud/#server-actions-shutdown-a-server

You may use poweroff instead as suggested by the API docs, but you won't have a clean shutdown.

The best solution (for a clean shutdown) is indeed that you wait for the server status to be "off":

action = server.shutdown()
action.wait_until_finished()

for i in range(10):
    sleep(5)
    server.reload()
    if server.status == Server.STATUS_OFF:
        break

# handle timeout

[scy]

Thanks for the explanation. Makes sense that it works like this. And you're right, the API docs mention it pretty explicitly.

Maybe adding it to the hcloud-python docs for the shutdown and reboot methods on ServerClient and BoundServer would be a good idea then, because I can imagine that not everyone using the Python client will cross-reference with the API docs for each method call.

Would you mind taking my suggestion to extend the change_type endpoint to the appropriate product feedback channels, even though it's pretty off-topic here? To recap, the (slightly expanded) suggestion is:

Add three new boolean fields to the change_type endpoint:

• poweroff_before: If true and the server is running and shutdown_before is false, pull the virtual power plug and then start changing the server type. Defaults to false for backwards compatibility.
• shutdown_before: If the server is running, send an ACPI shutdown request to it. Wait a sensible amount of time for the server's status to change to off. Then start changing the server type. Defaults to false for backwards compatibility.
  • If it didn't power off when the timeout elapsed, either force-unplug it (if poweroff_before is also true), or return an error (if poweroff_before is false, i.e. hard power-offs are not desired).
• poweron_after: After changing the server type, power it on again. Some users might prefer to have some manual control over this. Defaults to true for backwards compatibility.

Feel free to close this issue here as you see fit.

[jooola]

I reported you feature request to the relevant team, and they do not see those flags being added to the change_type endpoint. We already have the other endpoints, and do not want to mix concerns.

For the shutdown trigger, we do not have control over the guest OS, we therefor cannot have an action that wait for something we cannot control (e.g. the guest does not listen ACPI shutdown).

That said, I think its fair to say that SDK should provide a better documentation or even a helper function to accomplish a clean shutdown.

I'll leave this open until I implemented a good solution for this use case.

Again thanks for the report, we appreciate any feedback to improve our tools :).

[github-actions]

This issue has been marked as stale because it has not had recent activity. The bot will close the issue if no further action occurs.