rewrite architecture page as lifecycle

Author: emily-shen

src/content/docs/containers/platform-details/architecture.mdx

@@ -1,56 +1,46 @@
 ---
 pcx_content_type: reference
-title: Container Lifecycle
+title: Lifecycle of a Container
 sidebar:
   order: 1
 ---
 
-## How and where containers run
+## Deployment
 
-After you deploy a Worker that uses a Container, your image is uploaded to
-[Cloudflare's Registry](/containers/image-management) and distributed globally to Cloudflare's Network.
+After you deploy an application with a Container, your image is uploaded to
+[Cloudflare's Registry](/containers/platform-details/image-management) and distributed globally to Cloudflare's Network.
 Cloudflare will pre-schedule instances and pre-fetch images across the globe to ensure quick start
-times when scaling up the number of concurrent container instances. This allows you to call
-`env.YOUR_CONTAINER.get(id)` and get a new instance quickly without worrying
-about the underlying scaling.
+times when scaling up the number of concurrent container instances.
 
-When a request is made to start a new container instance, the nearest location
-with a pre-fetched image is selected. Subsequent requests to the same instance,
-regardless of where they originate, will be routed to this location as long as
-the instance stays alive.
+Unlike Workers, which are updated immediately on deploy, container instances are updated using a rolling deploy strategy.
+This allows you to gracefully shutdown any running instances during a rollout. Refer to [rollouts](/containers/platform-details/rollouts/) for more details.
 
-Starting additional container instances will use other locations with pre-fetched images,
-and Cloudflare will automatically begin prepping additional machines behind the scenes
-for additional scaling and quick cold starts. Because there are a finite number pre-warmed
-locations, some container instances may be started in locations that are farther away from
-the end-user. This is done to ensure that the container instance starts quickly. You are
-only charged for actively running instances and not for any unused pre-warmed images.
+## Lifecycle of a Request
 
-Each container instance runs inside its own VM, which provides strong
-isolation from other workloads running on Cloudflare's network. Containers
-should be built for the `linux/amd64` architecture, and should stay within
-[size limits](/containers/platform-details/#limits). Logging, metrics collection, and
-networking are automatically set up on each container.
+### Client to Worker
 
-## Life of a Container Request
-
-When a request is made to any Worker, including one with an associated Container, it is generally handled
+Recall that Containers are backed by Durable Objects and Workers.
+Requests are first routed through a Worker, which is generally handled
 by a datacenter in a location with the best latency between itself and the requesting user.
 A different datacenter may be selected to optimize overall latency, if [Smart Placement](/workers/configuration/smart-placement/)
 is on, or if the nearest location is under heavy load.
 
-When a request is made to a Container instance, it is sent through a Durable Object, which
-can be defined by either using a `DurableObject` or the [`Container` class](/containers/container-package), which
-extends Durable Objects with Container-specific APIs and helpers. We recommend using `Container`, see
-the [`Container` class documentation](/containers/container-package) for more details.
+Because all Container requests are passed through a Worker, end-users cannot make TCP or
+UDP requests to a Container instance. If you have a use case that requires inbound TCP
+or UDP from an end-user, please [let us know](https://forms.gle/AGSq54VvUje6kmKu8).
+
+### Worker to Durable Object
 
-Each Durable Object is a globally routable isolate that can execute code and store state. This allows
+From the Worker, a request passes through a Durable Object instance (the [Container package](/containers/container-package) extends a Durable Object class).
+Each Durable Object instance is a globally routable isolate that can execute code and store state. This allows
 developers to easily address and route to specific container instances (no matter where they are placed),
 define and run hooks on container status changes, execute recurring checks on the instance, and store persistent
 state associated with each instance.
 
-As mentioned above, when a container instance starts, it is launched in the nearest pre-warmed location. This means that
-code in a container is usually executed in a different location than the one handling the Workers request.
+### Starting a Container
+
+When a Durable Object instance requests to start a new container instance, the **nearest location
+with a pre-fetched image** is selected.
 
 :::note
 Currently, Durable Objects may be co-located with their associated Container instance, but often are not.
@@ -59,6 +49,73 @@ Cloudflare is currently working on expanding the number of locations in which a
 which will allow container instances to always run in the same location as their Durable Object.
 :::
 
-Because all Container requests are passed through a Worker, end-users cannot make TCP or
-UDP requests to a Container instance. If you have a use case that requires inbound TCP
-or UDP from an end-user, please [let us know](https://forms.gle/AGSq54VvUje6kmKu8).
+Starting additional container instances will use other locations with pre-fetched images,
+and Cloudflare will automatically begin prepping additional machines behind the scenes
+for additional scaling and quick cold starts. Because there are a finite number of pre-warmed
+locations, some container instances may be started in locations that are farther away from
+the end-user. This is done to ensure that the container instance starts quickly. You are
+only charged for actively running instances and not for any unused pre-warmed images.
+
+#### Cold starts
+
+A cold start is when a container instance is started from a completely stopped state.
+If you call `env.MY_CONTAINER.get(id)` with a completely novel ID and launch
+this instance for the first time, it will result in a cold start.
+This will start the container image from its entrypoint for the first time. Depending
+on what this entrypoint does, it will take a variable amount of time to start.
+
+Container cold starts can often be the 2-3 second range, but this is dependent
+on image size and code execution time, among other factors.
+
+### Requests to running Containers
+
+When a request _starts_ a new container instance, the nearest location with a pre-fetched image is selected.
+Subsequent requests to a particular instance, regardless of where they originate, will be routed to this location as long as
+the instance stays alive.
+
+However, once that container instance stops and restarts, future requests could be routed to a _different_ location.
+This location will again be the nearest location to the originating request with a pre-fetched image.
+
+### Container runtime
+
+Each container instance runs inside its own VM, which provides strong
+isolation from other workloads running on Cloudflare's network. Containers
+should be built for the `linux/amd64` architecture, and should stay within
+[size limits](/containers/platform-details/limits). [Logging](containers/faq/#how-do-container-logs-work), metrics collection, and
+networking are automatically set up on each container, if configured by the developer.
+
+### After a request
+
+Cloudflare will not actively shut off a container instance after a specific amount of
+time. If you do not set `sleepAfter` on your Container class, or stop the instance
+manually, it will continue to run unless its host server is restarted. This
+happens on an irregular cadence, but frequently enough where Cloudflare does not
+guarantee that any instance will run for any set period of time.
+
+When a container instance is going to be shut down, it is sent a `SIGTERM` signal,
+and then a `SIGKILL` signal after 15 minutes. You should perform any necessary
+cleanup to ensure a graceful shutdown in this time. The container instance
+will be rebooted elsewhere shortly after this.
+
+All disk is ephemeral. When a Container instance goes to sleep, the next time
+it is started, it will have a fresh disk as defined by its container image.
+
+Persistent disk is something the Cloudflare team is exploring in the future, but
+is not slated for the near term.
+
+## An example request
+
+- A developer deploys a Container. Cloudflare automatically readies instances across its Network.
+- A request is made from a client in Bariloche, Argentina. It reaches the Worker in a nearby
+  Cloudflare location in Neuquen, Argentina.
+- This Worker request calls `getContainer(env.MY_CONTAINER, "session-1337")`. Under the hood, this brings up a Durable
+  Object, which then calls `this.ctx.container.start`.
+- This requests the nearest free Container instance. Cloudflare recognizes that an instance is free in Buenos Aires, Argentina, and
+  starts it there.
+- A different user needs to route to the same container. This user's request reaches
+  the Worker running in Cloudflare's location in San Diego, US.
+- The Worker again calls `getContainer(env.MY_CONTAINER, "session-1337")`.
+- If the initial container instance is still running, the request is routed to the original location
+  in Buenos Aires. If the initial container has gone to sleep, Cloudflare will once
+  again try to find the nearest "free" instance of the Container, likely
+  one in North America, and start an instance there.