diff --git a/machines/api/machines-resource.html.markerb b/machines/api/machines-resource.html.markerb
index 625f99f9c7..90ee81e703 100644
--- a/machines/api/machines-resource.html.markerb
+++ b/machines/api/machines-resource.html.markerb
@@ -162,7 +162,7 @@ List all the Machines for an app.
## Create a Machine
-Given the name of a Fly App, create a Fly Machine, given the URI of a container image, in some region (or, by default, the region closest to you) on Fly.io’s platform. If successful, that Machine will boot up by default. Create a Machine without booting it by setting `skip_launch`.
+Given the name of a Fly App, create a Fly Machine, given the URI of a container image, in some region (or, by default, the region closest to you) on Fly.io's platform. If successful, that Machine will boot up by default. Create a Machine without booting it by setting `skip_launch`.
You can configure the Machine characteristics, like its CPU and memory. You can also allow connections from the internet through the Fly Proxy by [creating a Machine with services](#create-a-machine-with-services). Learn more about this behavior in the [networking section](#notes-on-networking).
@@ -212,12 +212,12 @@ The only required parameter in the body is `image` in the `config` object.
| --- | --- | --- | --- |
| `name` | string | no | Unique name for this Machine. If omitted, one is generated for you. String. |
| `region` | string | no | The target region. Omitting this param launches in the same region as your WireGuard peer connection (somewhere near you). String. |
- | `lease_ttl` | integer | no | Acquire a lease on the newly created Machine, waiting this many seconds before failing the request; use to create a Machine that can’t be updated by any other external process while waiting for it to come up and pass health checks. |
- | `skip_launch` | boolean | no | Create a Fly Machine, but don’t boot it up, leaving it in a state where it can be quickly started in response to events. Think of this as “warming the caches” on our hardware. (default: false) |
+ | `lease_ttl` | integer | no | Acquire a lease on the newly created Machine, waiting this many seconds before failing the request; use to create a Machine that can't be updated by any other external process while waiting for it to come up and pass health checks. |
+ | `skip_launch` | boolean | no | Create a Fly Machine, but don't boot it up, leaving it in a state where it can be quickly started in response to events. Think of this as "warming the caches" on our hardware. (default: false) |
| `lsvd` | boolean | no | Enable Log Structured Virtual Disks for this Machine. (default: false) |
- | `skip_service_registration` | boolean | no | Leave this Machine disconnected from Fly.io’s request routing. This is like a combined Create and Cordon operation; register the Machine later with an Uncordon request. Useful for bluegreen deploys: bring a Machine up, test it healthy, and only then let user requests hit it. (default: false) |
+ | `skip_service_registration` | boolean | no | Leave this Machine disconnected from Fly.io's request routing. This is like a combined Create and Cordon operation; register the Machine later with an Uncordon request. Useful for bluegreen deploys: bring a Machine up, test it healthy, and only then let user requests hit it. (default: false) |
| `config` | object | yes | Required for `image`. An object defining the Machine configuration. See the [`config` object properties](#machine-config-object-properties) section. |
- | `config.image` | string | yes | The container registry path to the image that defines this Machine (for example, ”registry-1.docker.io/library/ubuntu:latest”).
+ | `config.image` | string | yes | The container registry path to the image that defines this Machine (for example, "registry-1.docker.io/library/ubuntu:latest").
<% end %>
<% end %>
<%= render(CodeSampleComponent.new(title: 'Status: 200 OK – Example response', language: 'json')) do %>
@@ -270,13 +270,13 @@ Create a Machine with services defined on app. Learn more about [services and ne
| --- | --- | --- | --- |
| `name` | string | no | Unique name for this Machine. If omitted, one is generated for you. String. |
| `region` | string | no | The target region. Omitting this param launches in the same region as your WireGuard peer connection (somewhere near you). String. |
- | `lease_ttl` | integer | no | Acquire a lease on the newly created Machine, waiting this many seconds before failing the request; use to create a Machine that can’t be updated by any other external process while waiting for it to come up and pass health checks. |
- | `skip_launch` | boolean | no | Create a Fly Machine, but don’t boot it up, leaving it in a state where it can be quickly started in response to events. Think of this as “warming the caches” on our hardware. (default: false) |
+ | `lease_ttl` | integer | no | Acquire a lease on the newly created Machine, waiting this many seconds before failing the request; use to create a Machine that can't be updated by any other external process while waiting for it to come up and pass health checks. |
+ | `skip_launch` | boolean | no | Create a Fly Machine, but don't boot it up, leaving it in a state where it can be quickly started in response to events. Think of this as "warming the caches" on our hardware. (default: false) |
| `lsvd` | boolean | no | Enable Log Structured Virtual Disks for this Machine. (default: false) |
- | `skip_service_registration` | boolean | no | Leave this Machine disconnected from Fly.io’s request routing. This is like a combined Create and Cordon operation; register the Machine later with an Uncordon request. Useful for bluegreen deploys: bring a Machine up, test it healthy, and only then let user requests hit it. (default: false) |
+ | `skip_service_registration` | boolean | no | Leave this Machine disconnected from Fly.io's request routing. This is like a combined Create and Cordon operation; register the Machine later with an Uncordon request. Useful for bluegreen deploys: bring a Machine up, test it healthy, and only then let user requests hit it. (default: false) |
| `config` | object | yes | Required for `image`. An object defining the Machine configuration. See the [`config` object properties](#machine-config-object-properties) section. |
- | `config.image` | string | yes | The container registry path to the image that defines this Machine (for example, ”registry-1.docker.io/library/ubuntu:latest”).
- | `config.services` | array | no | Defines how Fly Proxy connects requests to an app’s public Anycast or private Flycast address to services running within Machines, and configures other Fly Proxy behavior for a service.
+ | `config.image` | string | yes | The container registry path to the image that defines this Machine (for example, "registry-1.docker.io/library/ubuntu:latest").
+ | `config.services` | array | no | Defines how Fly Proxy connects requests to an app's public Anycast or private Flycast address to services running within Machines, and configures other Fly Proxy behavior for a service.
<% end %>
<% end %>
<%= render(CodeSampleComponent.new(title: 'Status: 200 OK – Example response', language: 'json')) do %>
@@ -285,6 +285,106 @@ Create a Machine with services defined on app. Learn more about [services and ne
+## Create a Machine with containers
+
+Create a Machine that runs multiple containers. Each container runs independently within the Machine.
+
+
+
+ <% api_info = ApiInfoComponent.new(
+ heading: 'Path parameters',
+ name: 'app_name',
+ type: 'string',
+ required: true,
+ description: 'The name of the Fly App to create a Machine for.'
+ ) %>
+ <%= render(api_info) %>
+ <% api_info = ApiInfoComponent.new(
+ heading: 'Responses',
+ name: '200',
+ description: 'OK'
+ ) %>
+ <%= render(api_info) %>
+
+
+ <%= render(CodeToggleComponent.new(badge: 'POST', title: '/v1/apps/{app_name}/machines')) do |component| %>
+ <% component.with_curl do %>
+ curl -i -X POST \
+ -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \
+ "${FLY_API_HOSTNAME}/v1/apps/{app_name}/machines" \
+ -d '{
+ "config": {
+ "containers": [
+ {
+ "name": "web",
+ "image": "nginx:latest",
+ "command": ["nginx", "-g", "daemon off;"]
+ },
+ {
+ "name": "worker",
+ "image": "node:18",
+ "command": ["node", "worker.js"]
+ }
+ ]
+ }
+ }'
+ <% end %>
+ <% component.with_json do %>
+ {
+ "config": {
+ "containers": [
+ {
+ "name": "web",
+ "image": "nginx:latest",
+ "command": ["nginx", "-g", "daemon off;"]
+ },
+ {
+ "name": "worker",
+ "image": "node:18",
+ "command": ["node", "worker.js"]
+ }
+ ]
+ }
+ }
+ <% end %>
+ <% component.with_json_table do %>
+ | Property | Type | Required | Description |
+ | --- | --- | --- | --- |
+ | `config.containers` | array | yes | An array of container configurations to run within the Machine. |
+ | `config.containers[].name` | string | yes | The name of the container. |
+ | `config.containers[].image` | string | yes | The container registry path to the image for this container. |
+ | `config.containers[].command` | array | no | The command to run in the container. |
+ <% end %>
+ <% end %>
+ <%= render(CodeSampleComponent.new(title: 'Status: 200 OK – Example response', language: 'json')) do %>
+{
+ "id": "3d8d413b29d089",
+ "name": "quirky-rain-1234",
+ "state": "created",
+ "region": "lax",
+ "instance_id": "01GXSA8R7851294X9C4Q5J5P0M",
+ "private_ip": "fdaa:0:4:a:7b:1b:1b:2",
+ "config": {
+ "containers": [
+ {
+ "name": "web",
+ "image": "nginx:latest",
+ "command": ["nginx", "-g", "daemon off;"]
+ },
+ {
+ "name": "worker",
+ "image": "node:18",
+ "command": ["node", "worker.js"]
+ }
+ ]
+ },
+ "created_at": "2024-03-20T10:00:00Z",
+ "updated_at": "2024-03-20T10:00:00Z"
+}
+ <% end %>
+
+
@@ -469,10 +569,10 @@ This is, in particular, how you would update the running image of a Machine (whe
| `current_version` | string | no | The latest `instance_id` value of the Machine. |
| `name` | string | no | Unique name for this Machine. If omitted, one is generated for you. String. |
| `region` | string | no | The target region. Omitting this param launches in the same region as your WireGuard peer connection (somewhere near you). String. |
- | `lease_ttl` | integer | no | Acquire a lease on the newly created Machine, waiting this many seconds before failing the request; use to create a Machine that can’t be updated by any other external process while waiting for it to come up and pass health checks. |
- | `skip_launch` | boolean | no | Create a Fly Machine, but don’t boot it up, leaving it in a state where it can be quickly started in response to events. Think of this as “warming the caches” on our hardware. (default: false) |
+ | `lease_ttl` | integer | no | Acquire a lease on the newly created Machine, waiting this many seconds before failing the request; use to create a Machine that can't be updated by any other external process while waiting for it to come up and pass health checks. |
+ | `skip_launch` | boolean | no | Create a Fly Machine, but don't boot it up, leaving it in a state where it can be quickly started in response to events. Think of this as "warming the caches" on our hardware. (default: false) |
| `lsvd` | boolean | no | Enable Log Structured Virtual Disks for this Machine. (default: false) |
- | `skip_service_registration` | boolean | no | Leave this Machine disconnected from Fly.io’s request routing. This is like a combined Create and Cordon operation; register the Machine later with an Uncordon request. Useful for bluegreen deploys: bring a Machine up, test it healthy, and only then let user requests hit it. (default: false) |
+ | `skip_service_registration` | boolean | no | Leave this Machine disconnected from Fly.io's request routing. This is like a combined Create and Cordon operation; register the Machine later with an Uncordon request. Useful for bluegreen deploys: bring a Machine up, test it healthy, and only then let user requests hit it. (default: false) |
<% end %>
<% end %>
<%= render(CodeSampleComponent.new(title: 'Status: 200 OK – Example response', language: 'json')) do %>
@@ -1068,6 +1168,65 @@ Delete a metadata key-value pair on a specific Machine's config.
+## List containers in a Machine
+
+List all containers running in a specific Machine.
+
+
+
+ <% api_info = ApiInfoComponent.new(
+ heading: 'Path parameters',
+ name: 'app_name',
+ type: 'string',
+ required: true,
+ description: 'The name of the Fly App the Machine belongs to.'
+ ) %>
+ <% api_info.add_info(
+ name: 'machine_id',
+ type: 'string',
+ required: true,
+ description: 'The ID of the Machine to list containers for.'
+ ) %>
+ <%= render(api_info) %>
+ <% api_info = ApiInfoComponent.new(
+ heading: 'Responses',
+ name: '200',
+ description: 'OK'
+ ) %>
+ <%= render(api_info) %>
+
+
+ <%= render(CodeToggleComponent.new(badge: 'GET', title: '/v1/apps/{app_name}/machines/{machine_id}/containers')) do |component| %>
+ <% component.with_curl do %>
+ curl -i -X GET \\
+ -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
+ "${FLY_API_HOSTNAME}/v1/apps/{app_name}/machines/{machine_id}/containers"
+ <% end %>
+ <% component.with_json do %>
+ no body
+ <% end %>
+ <% component.with_json_table do %>
+ | Property | Type | Required | Description |
+ | --- | --- | --- | --- |
+ | no body | | | |
+ <% end %>
+ <% end %>
+ <%= render(CodeSampleComponent.new(title: 'Status: 200 OK - Example response', language: 'json')) do %>
+{
+ "containers": [
+ {
+ "id": "container_123",
+ "name": "main",
+ "state": "running",
+ "created_at": "2024-03-20T10:00:00Z",
+ "updated_at": "2024-03-20T10:00:00Z"
+ }
+ ]
+}
+ <% end %>
+
+