-
Notifications
You must be signed in to change notification settings - Fork 249
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #156 from buildkite/hosted_agents_api
Creating a hosted queue via GraphQL and REST
- Loading branch information
Showing
15 changed files
with
525 additions
and
62 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,98 @@ | ||
| # Hosted agents | ||
|
|
||
| A collection of common tasks with [Hosted agents](/docs/pipelines/hosted-agents) using the GraphQL API. | ||
|
|
||
| ## Create a Buildkite hosted queue | ||
|
|
||
| ```graphql | ||
| mutation { | ||
| clusterQueueCreate( | ||
| input: { | ||
| organizationId: "organization-id" | ||
| clusterId: "cluster-id" | ||
| key: "hosted_linux_small" | ||
| description: "Small AMD64 Linux agents hosted by Buildkite." | ||
| hostedAgents: { | ||
| instanceShape: LINUX_AMD64_2X4 | ||
| } | ||
| } | ||
| ) { | ||
| clusterQueue { | ||
| id | ||
| uuid | ||
| key | ||
| description | ||
| dispatchPaused | ||
| hosted | ||
| hostedAgents { | ||
| instanceShape { | ||
| name | ||
| size | ||
| vcpu | ||
| memory | ||
| } | ||
| } | ||
| createdBy { | ||
| id | ||
| uuid | ||
| name | ||
| avatar { | ||
| url | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Creates a small Buildkite hosted queue using AMD64-based Linux Buildkite hosted agents. The `instanceShape` value is referenced from the [InstanceShape](/docs/apis/graphql/schemas/enum/hostedagentinstanceshapename) enum, and represents the combination of machine type, architecture, CPU and Memory available to each job running on a hosted queue. The `LINUX_AMD64_2X4` value is a Linux AMD64 2 vCPU and 4 GB memory instance. | ||
|
|
||
| Learn more about the instance shapes available for [Linux](#instance-shape-values-for-linux) and [Mac](#instance-shape-values-for-mac) Buildkite hosted agents. | ||
|
|
||
| ## Change the instance shape of a Buildkite hosted queue's agents | ||
|
|
||
| ```graphql | ||
| mutation { | ||
| clusterQueueUpdate( | ||
| input: { | ||
| organizationId: "organization-id" | ||
| id: "cluster-queue-id" | ||
| hostedAgents: { | ||
| instanceShape: LINUX_AMD64_4X16 | ||
| } | ||
| } | ||
| ) { | ||
| clusterQueue { | ||
| id | ||
| hostedAgents { | ||
| instanceShape { | ||
| name | ||
| size | ||
| vcpu | ||
| memory | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| To increase the size of the AMD64-based Linux agent instances for a Buildkite hosted queue, update the `instanceShape` value to a one of a greater size, such as `LINUX_AMD64_4X8`, which is a 4 vCPU and 8 GB memory. This allows you to scale the resources available to each job running on this Buildkite hosted queue. | ||
|
|
||
| Learn more about the instance shapes available for [Linux](#instance-shape-values-for-linux) and [Mac](#instance-shape-values-for-mac) Buildkite hosted agents. | ||
|
|
||
| > 📘 | ||
| > It is only possible to change the _size_ of the current instance shape assigned to this queue. It is not possible to change the current instance shape's machine type (from macOS to Linux, or vice versa), or for a Linux machine, its architecture (from AMD64 to ARM64, or vice versa). | ||
| ## Instance shape values for Linux | ||
|
|
||
| Specify the appropriate **Instance shape** for the `instanceShape` value in your GraphQL API mutation. | ||
|
|
||
| <%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_linux' %> | ||
|
|
||
| ## Instance shape values for Mac | ||
|
|
||
| Specify the appropriate **Instance shape** for the `instanceShape` value in your GraphQL API mutation. | ||
|
|
||
| <%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -350,7 +350,7 @@ Required scope: `read_clusters` | |
|
|
||
| Success response: `200 OK` | ||
|
|
||
| ### Create a queue | ||
| ### Create a self-hosted queue | ||
|
|
||
| ```bash | ||
| curl -H "Authorization: Bearer $TOKEN" \ | ||
|
|
@@ -392,11 +392,91 @@ Required [request body properties](/docs/api#request-body-properties): | |
| </tbody> | ||
| </table> | ||
|
|
||
| Required scope: `write_clusters` | ||
|
|
||
| Success response: `201 Created` | ||
|
|
||
| Error responses: | ||
|
|
||
| <table class="responsive-table"> | ||
| <tbody> | ||
| <tr><th><code>422 Unprocessable Entity</code></th><td><code>{ "message": "Validation failed: Reason for failure" }</code></td></tr> | ||
| </tbody> | ||
| </table> | ||
|
|
||
| ### Create a Buildkite hosted queue | ||
|
|
||
| ```bash | ||
| curl -H "Authorization: Bearer $TOKEN" \ | ||
| -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/queues" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{ "key": "default", "description": "Queue of hosted Buildkite agents", "hostedAgents": { "instanceShape": "LINUX_AMD64_2X4" } }' | ||
| ``` | ||
|
|
||
| ```json | ||
| { | ||
| "id": "01885682-55a7-44f5-84f3-0402fb452e66", | ||
| "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==", | ||
| "key": "default", | ||
| "description": "Queue of hosted Buildkite agents", | ||
| "url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66", | ||
| "web_url": "http://buildkite.com/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66", | ||
| "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf", | ||
| "dispatch_paused": false, | ||
| "dispatch_paused_by": null, | ||
| "dispatch_paused_at": null, | ||
| "dispatch_paused_note": null, | ||
| "created_at": "2023-05-03T04:17:55.867Z", | ||
| "created_by": { | ||
| "id": "0187dfd4-92cf-4b01-907b-1146c8525dde", | ||
| "graphql_id": "VXNlci0tLTAxODdkZmQ0LTkyY2YtNGIwMS05MDdiLTExNDZjODUyNWRkZQ==", | ||
| "name": "Sam Kim", | ||
| "email": "[email protected]", | ||
| "avatar_url": "https://www.gravatar.com/avatar/example", | ||
| "created_at": "2023-05-03T04:17:43.118Z" | ||
| }, | ||
| "hosted": true, | ||
| "hosted_agents": { | ||
| "instance_shape": { | ||
| "machine_type": "linux", | ||
| "architecture": "amd64", | ||
| "cpu": 2, | ||
| "memory": 4, | ||
| "name": "LINUX_AMD64_2X4" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Required [request body properties](/docs/api#request-body-properties): | ||
|
|
||
| <table class="responsive-table"> | ||
| <tbody> | ||
| <tr><th><code>key</code></th><td>Key for the queue.<br><em>Example:</em> <code>"default"</code> | ||
| </tbody> | ||
| </table> | ||
|
|
||
| Optional [request body properties](/docs/api#request-body-properties): | ||
|
|
||
| <table class="responsive-table"> | ||
| <tbody> | ||
| <tr><th><code>description</code></th><td>Description for the queue.<br><em>Example:</em> <code>"The default queue for this cluster"</code> | ||
| <tr> | ||
| <th><code>hostedAgents</code></th> | ||
| <td> | ||
| Configures this queue to use <a href="/docs/pipelines/hosted-agents">Buildkite hosted agents</a>, along with its <em>instance shape</em>. This makes the queue a <a href="/docs/pipelines/clusters/manage-queues#create-a-buildkite-hosted-queue">Buildkite hosted queue</a>. | ||
| <br> | ||
| <em>Example:</em> | ||
| <br/> | ||
| <code> | ||
| { "instanceShape": "LINUX_AMD64_2X4" } | ||
| </code> | ||
| <br/> | ||
| <code>instanceShape</code> (required when <code>hostedAgents</code> is specified): Describes the machine type, architecture, CPU, and RAM to provision for Buildkite hosted agent instances running jobs in this queue. | ||
| <br/> | ||
| Learn more about the instance shapes available for <a href="#queues-instance-shape-values-for-linux">Linux</a> and <a href="#queues-instance-shape-values-for-mac">Mac</a> hosted agents. | ||
| </td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
|
|
||
|
|
@@ -451,6 +531,23 @@ curl -H "Authorization: Bearer $TOKEN" \ | |
| <table class="responsive-table"> | ||
| <tbody> | ||
| <tr><th><code>description</code></th><td>Description for the queue.<br><em>Example:</em> <code>"The default queue for this cluster"</code> | ||
| <tr> | ||
| <th><code>hostedAgents</code></th> | ||
| <td> | ||
| Configures this queue to use <a href="/docs/pipelines/hosted-agents">Buildkite hosted agents</a>, along with its <em>instance shape</em>. This makes the queue a <a href="/docs/pipelines/clusters/manage-queues#create-a-buildkite-hosted-queue">Buildkite hosted queue</a>. | ||
| <br> | ||
| <em>Example:</em> | ||
| <br/> | ||
| <code> | ||
| { "instanceShape": "LINUX_AMD64_2X4" } | ||
| </code> | ||
| <br/> | ||
| <code>instanceShape</code> (required when <code>hostedAgents</code> is specified): Describes the machine type, architecture, CPU, and RAM to provision for Buildkite hosted agent instances running jobs in this queue. | ||
| <br/> | ||
| It is only possible to change the <em>size</em> of the current instance shape assigned to this queue. It is not possible to change the current instance shape's machine type (from macOS to Linux, or vice versa), or for a Linux machine, its architecture (from AMD64 to ARM64, or vice versa).<br/> | ||
| Learn more about the instance shapes available for <a href="#queues-instance-shape-values-for-linux">Linux</a> and <a href="#queues-instance-shape-values-for-mac">Mac</a> Buildkite hosted agents. | ||
| </td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
|
|
||
|
|
@@ -599,6 +696,18 @@ Error responses: | |
| </tbody> | ||
| </table> | ||
|
|
||
| ### Instance shape values for Linux | ||
|
|
||
| Specify the appropriate **Instance shape** for the `instanceShape` value in your REST API call. | ||
|
|
||
| <%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_linux' %> | ||
|
|
||
| ### Instance shape values for Mac | ||
|
|
||
| Specify the appropriate **Instance shape** for the `instanceShape` value in your REST API call. | ||
|
|
||
| <%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> | ||
|
|
||
| ## Agent tokens | ||
|
|
||
| An agent token is used to [connect agents to a cluster](/docs/pipelines/clusters/manage-clusters#connect-agents-to-a-cluster). | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.