From 9f4c12491be1978838440bc4aeb4023e96589904 Mon Sep 17 00:00:00 2001 From: andie787 <4andie@gmail.com> Date: Mon, 18 Sep 2023 20:36:50 -0400 Subject: [PATCH 1/2] add machine restart policy doc --- .../machine-restart-policy.html.markerb | 92 +++++++++++++++++++ partials/_firecracker_nav.html.erb | 3 + 2 files changed, 95 insertions(+) create mode 100644 machines/guides-examples/machine-restart-policy.html.markerb diff --git a/machines/guides-examples/machine-restart-policy.html.markerb b/machines/guides-examples/machine-restart-policy.html.markerb new file mode 100644 index 0000000000..1bf8435d47 --- /dev/null +++ b/machines/guides-examples/machine-restart-policy.html.markerb @@ -0,0 +1,92 @@ +--- +title: Machine restart policy +layout: framework_docs +sitemap: false +order: 35 +nav: firecracker +--- + +A machine restart policy defines whether and how flyd restarts a Machine after its main process exits. The restart policy applies to an individual Machine, and is not an app-wide setting. + +The restart policies are: + +- **`no`**: Never try to restart a Machine when its main process exits, whether that’s on purpose or on a crash. +- **`always`**: Always restart a Machine, even when the main process exits cleanly. `always` is the default when you create a Machine with `fly m run` and for Fly Postgres app Machines. Recommended for "always-on" apps with no services configured, since the Machine restarts regardless of the exit code. +- **`on-fail`**: Try up to 10 times to restart the Machine if it exits with a non-zero exit code, before letting it stop. Recommended for most Machines with services configured that Fly Proxy can wake on request. `on-fail` lets Machines be restarted if they crash, and allows your app Machines to effectively scale down by exiting cleanly. `on-fail` is the default when there's no explicit restart policy in a Machine's config, such as Machines created by `fly launch` and `fly deploy`. Machines with a schedule also default to the `on-fail` restart policy. + +## Check a Machine's restart policy + +Display a Machine's status and its config in `json` format: + +```cmd +fly m status -d +``` + +Example output with a restart policy of `always`: + +```out +... +Config: +{ + "init": {}, + "image": "registry-1.docker.io/flyio/hellofly:latest", + "restart": { + "policy": "always" + }, + "guest": { + "cpu_kind": "shared", + "cpus": 1, + "memory_mb": 256 + }, + "dns": {} +} +``` + + +## Change a Machine's restart policy with flyctl + +Update the Machine config: + +```cmd +fly m update --restart +``` + +The following example updates a Machine's restart policy to `on-fail`: + +```cmd +fly m update 3908032c794088 --restart on-fail +``` +```out +Configuration changes to be applied to machine: 3908032c794088 (my-app-name) + +   ... // 2 identical lines +   "image": "registry-1.docker.io/flyio/hellofly:latest", +   "restart": { +-  "policy": "always" ++  "policy": "on-failure" +   }, +   "guest": { +   ... // 6 identical lines + +? Apply changes? (y/N) +``` + +Enter 'y' to apply the changes. + +## Change a Machine's restart policy with the Machines API + +With the Machines API, you can set the restart policy, and the maximum number of retries when the policy is `on-fail`. + +Endpoint:`POST /apps/{app_name}/machines/{machine_id}` + +For example: +``` +... + "restart": { + "max_retries": 5, + "policy": "on-failure" + }, +... +``` + +Refer to the Machines API docs for [Machine update](https://docs.machines.dev/swagger/index.html#/Machines/Machines_update). \ No newline at end of file diff --git a/partials/_firecracker_nav.html.erb b/partials/_firecracker_nav.html.erb index d5e31f8ad3..bb7fbfec27 100644 --- a/partials/_firecracker_nav.html.erb +++ b/partials/_firecracker_nav.html.erb @@ -130,6 +130,9 @@
  • <%= nav_link "Machine Sizing", "/docs/machines/guides-examples/machine-sizing/" %>
    • +
  • + <%= nav_link "Machine restart policy", "/docs/machines/guides-examples/machine-restart-policy/" %> +
  • <%= nav_link "Run User Code on Fly Machines", "/docs/machines/guides-examples/functions-with-machines/" %>
    • From b5012c8dff4cff6067b267d888640cc34e61baed Mon Sep 17 00:00:00 2001 From: andie787 <4andie@gmail.com> Date: Tue, 19 Sep 2023 19:32:08 -0400 Subject: [PATCH 2/2] minor edits --- .../machine-restart-policy.html.markerb | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/machines/guides-examples/machine-restart-policy.html.markerb b/machines/guides-examples/machine-restart-policy.html.markerb index 1bf8435d47..099c52db04 100644 --- a/machines/guides-examples/machine-restart-policy.html.markerb +++ b/machines/guides-examples/machine-restart-policy.html.markerb @@ -6,13 +6,15 @@ order: 35 nav: firecracker --- -A machine restart policy defines whether and how flyd restarts a Machine after its main process exits. The restart policy applies to an individual Machine, and is not an app-wide setting. +The Machine restart policy defines whether and how flyd restarts a Machine after its main process exits. The restart policy applies per Machine, and is not an app-wide setting. The restart policies are: -- **`no`**: Never try to restart a Machine when its main process exits, whether that’s on purpose or on a crash. -- **`always`**: Always restart a Machine, even when the main process exits cleanly. `always` is the default when you create a Machine with `fly m run` and for Fly Postgres app Machines. Recommended for "always-on" apps with no services configured, since the Machine restarts regardless of the exit code. -- **`on-fail`**: Try up to 10 times to restart the Machine if it exits with a non-zero exit code, before letting it stop. Recommended for most Machines with services configured that Fly Proxy can wake on request. `on-fail` lets Machines be restarted if they crash, and allows your app Machines to effectively scale down by exiting cleanly. `on-fail` is the default when there's no explicit restart policy in a Machine's config, such as Machines created by `fly launch` and `fly deploy`. Machines with a schedule also default to the `on-fail` restart policy. +- **`no`**: Never try to restart a Machine automatically when its main process exits, whether that’s on purpose or on a crash. + +- **`always`**: Always restart a Machine automatically and never let it enter a `stopped` state, even when the main process exits cleanly. `always` is the default when you create a Machine with `fly m run` and for Fly Postgres app Machines. Recommended for "always-on" apps with no services configured, since the Machine restarts regardless of the exit code. + +- **`on-fail`**: Try up to 10 times to automatically restart the Machine if it exits with a non-zero exit code, before letting it stop. Recommended for most Machines with services configured, since Fly Proxy can wake them request. `on-fail` lets Machines be restarted if they crash, and allows your app Machines to effectively scale down by exiting cleanly. `on-fail` is the default when there's no explicit restart policy in a Machine's config, such as Machines created by `fly launch` and `fly deploy`. Machines with a schedule also default to the `on-fail` restart policy. ## Check a Machine's restart policy @@ -42,7 +44,6 @@ Config: } ``` - ## Change a Machine's restart policy with flyctl Update the Machine config: @@ -77,7 +78,7 @@ Enter 'y' to apply the changes. With the Machines API, you can set the restart policy, and the maximum number of retries when the policy is `on-fail`. -Endpoint:`POST /apps/{app_name}/machines/{machine_id}` +Endpoint: `POST /apps/{app_name}/machines/{machine_id}` For example: ``` @@ -89,4 +90,4 @@ For example: ... ``` -Refer to the Machines API docs for [Machine update](https://docs.machines.dev/swagger/index.html#/Machines/Machines_update). \ No newline at end of file +Refer to the Machines API docs for more information about [Machine update](https://docs.machines.dev/swagger/index.html#/Machines/Machines_update). \ No newline at end of file