From f0a94c7b64e0c012a7675462b2c74e2564f950cb Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Tue, 3 Dec 2024 22:30:51 +1100 Subject: [PATCH 01/22] Add instance shapes and REST/GraphQL API calls for updating a queue. --- data/nav.yml | 2 + .../_common_create_cluster_fields.md | 2 +- ...ted_agents_instance_shape_table_linux.html | 35 ++++ ...osted_agents_instance_shape_table_mac.html | 22 +++ pages/apis/graphql/cookbooks/hosted_agents.md | 80 +++++++++ pages/apis/rest_api/clusters.md | 120 +++++++++++++- pages/pipelines/clusters/manage_queues.md | 155 ++++++++++++++++-- pages/pipelines/getting_started.md | 2 +- pages/pipelines/hosted_agents.md | 11 +- pages/pipelines/hosted_agents/linux.md | 21 +-- pages/pipelines/hosted_agents/mac.md | 19 +-- .../Buildkite/existence-case-sensitive.yml | 2 +- 12 files changed, 425 insertions(+), 46 deletions(-) create mode 100644 pages/apis/descriptions/_hosted_agents_instance_shape_table_linux.html create mode 100644 pages/apis/descriptions/_hosted_agents_instance_shape_table_mac.html create mode 100644 pages/apis/graphql/cookbooks/hosted_agents.md diff --git a/data/nav.yml b/data/nav.yml index ecb46aad7a..26d791ad9c 100644 --- a/data/nav.yml +++ b/data/nav.yml @@ -725,6 +725,8 @@ path: apis/graphql/cookbooks/clusters - name: GitHub rate limits path: apis/graphql/cookbooks/github-rate-limits + - name: Hosted agents + path: apis/graphql/cookbooks/hosted-agents - name: Jobs path: apis/graphql/cookbooks/jobs - name: Pipelines diff --git a/pages/apis/descriptions/_common_create_cluster_fields.md b/pages/apis/descriptions/_common_create_cluster_fields.md index a46cc954f6..30b3a96f4b 100644 --- a/pages/apis/descriptions/_common_create_cluster_fields.md +++ b/pages/apis/descriptions/_common_create_cluster_fields.md @@ -7,4 +7,4 @@ - `color` (optional) provides the background color for this emoji and uses hex code syntax (for example, `#FFE0F1`). > 📘 A default queue is not automatically created -> Unlike creating a new cluster through the [Buildkite interface](#create-a-cluster-using-the-buildkite-interface), a default queue is not automatically created using this API call. To create a new/default queue for any new cluster created through an API call, you need to manually [create a new queue](/docs/pipelines/clusters/manage-queues#create-a-queue). +> Unlike creating a new cluster through the [Buildkite interface](#create-a-cluster-using-the-buildkite-interface), a default queue is not automatically created using this API call. To create a new/default queue for any new cluster created through an API call, you need to manually [create a new queue](/docs/pipelines/clusters/manage-queues#create-a-self-hosted-queue). diff --git a/pages/apis/descriptions/_hosted_agents_instance_shape_table_linux.html b/pages/apis/descriptions/_hosted_agents_instance_shape_table_linux.html new file mode 100644 index 0000000000..8d79940866 --- /dev/null +++ b/pages/apis/descriptions/_hosted_agents_instance_shape_table_linux.html @@ -0,0 +1,35 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Instance ShapeSizeArchitecturevCPUMemory
LINUX_AMD64_2X4SmallAMD6424 GB
LINUX_AMD64_4X16MediumAMD64416 GB
LINUX_AMD64_8X32LargeAMD64832 GB
LINUX_AMD64_16X64Extra LargeAMD641664 GB
LINUX_ARM64_2X4SmallARM6424 GB
LINUX_ARM64_4X16MediumARM64416 GB
LINUX_ARM64_8X32LargeARM64832 GB
LINUX_ARM64_16X64Extra LargeARM641664 GB
diff --git a/pages/apis/descriptions/_hosted_agents_instance_shape_table_mac.html b/pages/apis/descriptions/_hosted_agents_instance_shape_table_mac.html new file mode 100644 index 0000000000..4831f10c72 --- /dev/null +++ b/pages/apis/descriptions/_hosted_agents_instance_shape_table_mac.html @@ -0,0 +1,22 @@ + + + + + + + + + + + + + + + + + + + + + +
Instance ShapeSizevCPUMemory
MACOS_M2_4X7Small47 GB
MACOS_M2_6X14Medium614 GB
MACOS_M2_12X28Large1228 GB
MACOS_M4_12x56Extra Large1256 GB
diff --git a/pages/apis/graphql/cookbooks/hosted_agents.md b/pages/apis/graphql/cookbooks/hosted_agents.md new file mode 100644 index 0000000000..aac74f7fb6 --- /dev/null +++ b/pages/apis/graphql/cookbooks/hosted_agents.md @@ -0,0 +1,80 @@ +# Hosted agents + +A collection of common tasks with [Hosted agents](/docs/pipelines/hosted-agents) using the GraphQL API. + +## Creating a hosted cluster queue + +```graphql +mutation { + clusterQueueCreate( + input: { + organizationId: "organization-id" + clusterId: "cluster-id" + key: "hosted_linux_small" + description: "Small AMD64 Linux agents hosted by Buildkite." + hosted: true + hostedAgents: { + instanceShape: LINUX_AMD64_2X4 + } + } + ) { + clusterQueue { + id + uuid + key + description + dispatchPaused + hosted + hostedAgents { + instanceShape { + name + size + vcpu + memory + } + } + createdBy { + id + uuid + name + email + avatar { + url + } + } + } + } +} +``` + +Create a small AMD64 Linux hosted agent cluster queue, which is hosted by Buildkite. The `instanceShape` value is referenced from the [InstanceShape](/docs/apis/graphql/schemas/enum/instanceshape) 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 2 vCPU and 4 GB memory. + +## Changing the instance shape of a hosted agent cluster queue + +```graphql +mutation { + clusterQueueUpdate( + input: { + organizationId: "organization-id" + id: "cluster-queue-id" + hostedAgents: { + instanceShape: LINUX_AMD64_4X8 + } + } + ) { + clusterQueue { + id + hostedAgents { + instanceShape { + name + size + vcpu + memory + } + } + } + } +} +``` + +To increase the size of the agent instances for a hosted agent cluster queue, update the `instanceShape` value to `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 a hosted queue. diff --git a/pages/apis/rest_api/clusters.md b/pages/apis/rest_api/clusters.md index b4d5e82760..822426b83d 100644 --- a/pages/apis/rest_api/clusters.md +++ b/pages/apis/rest_api/clusters.md @@ -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,108 @@ Required [request body properties](/docs/api#request-body-properties): +Required scope: `write_clusters` + +Success response: `201 Created` + +Error responses: + + + + + +
422 Unprocessable Entity{ "message": "Validation failed: Reason for failure" }
+ +### Create a 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", "hosted": true, "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": "sam@example.com", + "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" + }, + "platform_settings": { + "linux": { + "agent_image_ref": null + } + } + } +} +``` + +Required [request body properties](/docs/api#request-body-properties): + + + + +
keyKey for the queue.
Example: "default" +
+ Optional [request body properties](/docs/api#request-body-properties): + + + + + + +
descriptionDescription for the queue.
Example: "The default queue for this cluster" +
+ hostedConfigure the queue to use [Hosted Agents](/docs/pipelines/hosted-agents).
Example: true +
hostedAgents + Configuration for hosted agents on this queue. +
+ Example:
+ + { "instanceShape": "LINUX_AMD64_2X4" } + + + instanceShape (required): The instance shape to provision hosted agent machines on this queue. +
+ +

Instance shapes for Linux hosted agents:

+ + <%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_linux' %> + +

Instance shapes for Mac hosted agents:

+ + <%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_mac' %> +
@@ -451,6 +548,27 @@ curl -H "Authorization: Bearer $TOKEN" \ + + +
descriptionDescription for the queue.
Example: "The default queue for this cluster" +
hostedAgents + Configuration for hosted agents on this queue. +
+ Example:
+ + { "instanceShape": "LINUX_AMD64_2X4" } + + + instanceShape (required): The instance shape describes the machine type, architecture, CPU, and RAM to provision for hosted agent instances running jobs in this queue. + + The architecture (AMD64, ARM64) and machine type (MACOS, LINUX) of the instance shape must match the existing hosted agents on the queue. + +
+ + <%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_linux' %> + + <%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_mac' %> +
diff --git a/pages/pipelines/clusters/manage_queues.md b/pages/pipelines/clusters/manage_queues.md index ad57b2a364..193f079f36 100644 --- a/pages/pipelines/clusters/manage_queues.md +++ b/pages/pipelines/clusters/manage_queues.md @@ -22,12 +22,9 @@ As part of setting up a queue, you can choose between setting up your agents usi Buildkite provides a hosted infrastructure for your [Buildkite Agents](/docs/agent/v3), as well as support for self-hosted infrastructure, where you provide the infrastructure that hosts Buildkite Agents. -> 📘 -> Creating [Buildkite hosted agent](/docs/pipelines/hosted-agents) queues is currently only supported through the [Buildkite interface](#create-a-queue-using-the-buildkite-interface). It is not possible to create hosted agent queues using the [REST](#create-a-queue-using-the-rest-api) or [GraphQL](#create-a-queue-using-the-graphql-api) APIs. +## Create a self-hosted queue -## Create a queue - -New queues can be created by a [cluster maintainer](/docs/pipelines/clusters/manage-clusters#manage-maintainers-on-a-cluster) using the [**Queues** page of a cluster](#create-a-queue-using-the-buildkite-interface), as well as the [REST API's](#create-a-queue-using-the-rest-api) or [GraphQL API's](#create-a-queue-using-the-graphql-api) create a queue feature. +Self-hosted queues use your own infrastructure to run your builds. New queues can be created by a [cluster maintainer](/docs/pipelines/clusters/manage-clusters#manage-maintainers-on-a-cluster) using the [**Queues** page of a cluster](#create-a-self-hosted-queue-using-the-buildkite-interface), as well as the [REST API's](#create-a-self-hosted-queue-using-the-rest-api) or [GraphQL API's](#create-a-self-hosted-queue-using-the-graphql-api) create a queue feature. For these API requests, the _cluster ID_ value submitted in the request is the target cluster the queue will be created in. @@ -42,18 +39,14 @@ To create a new queue using the Buildkite interface: 1. On the **Queues** page, select **New Queue** to open the **Create a new Queue** page. 1. In the **Create a key** field, enter a unique _key_ for the queue, which can only contain letters, numbers, hyphens, and underscores, as valid characters. 1. Select the **Add description** checkbox to enter an optional longer description for the queue. This description appears under the queue's key, which is listed on the **Queues** page, as well as when viewing the queue's details. -1. In the **Select your agent infrastructure** section, select between [**Hosted**](/docs/pipelines/hosted-agents) or **Self hosted** for your agent infrastructure. -1. If you chose **Hosted**, complete the remaining sub-steps: - 1. In the new **Configure your hosted agent infrastructure** section, select your **Machine type** ([**Linux**](/docs/pipelines/hosted-agents/linux) or [**macOS**](/docs/pipelines/hosted-agents/mac)). - 1. If you selected **Linux**, within **Architecture**, you can choose between **AMD64** (the default and recommended) or **ARM64** architectures for the Linux machines running as hosted agents. To switch to **ARM64**, select **Change**, followed by **ARM64 (AArch64)**. - 1. Select the appropriate **Capacity** for your hosted agent machine type (**Small**, **Medium** or **Large**). Take note of the additional information provided in the new **Hosted agents trial** section, which changes based on your selected **Capacity**. +1. In the **Select your agent infrastructure** section, select **Self hosted** for your agent infrastructure. 1. Select **Create Queue**. The new queue's details are displayed, indicating the queue's key and its description (if configured) underneath this key. Select **Queues** on the interface again to list all configured queues in your cluster. ### Using the REST API -To [create a new self-hosted agent queue](/docs/apis/rest-api/clusters#queues-create-a-queue) using the [REST API](/docs/apis/rest-api), run the following example `curl` command: +To [create a new self-hosted agent queue](/docs/apis/rest-api/clusters#queues-create-a-self-hosted-queue) using the [REST API](/docs/apis/rest-api), run the following example `curl` command: ```curl curl -H "Authorization: Bearer $TOKEN" \ @@ -117,6 +110,146 @@ where: <%= render_markdown partial: 'apis/descriptions/common_create_queue_fields' %> +## Create a hosted queue + +Hosted cluster queues use Buildkite's hosted agent infrastructure to run your builds. You can create a hosted queue using the [Buildkite interface](#create-a-hosted-queue-using-the-buildkite-interface), the [REST API](#create-a-hosted-queue-using-the-rest-api), or the [GraphQL API](#create-a-hosted-queue-using-the-graphql-api). + +When you create a hosted queue, you can choose the machine type (Linux or macOS) and the capacity (small, medium, or large) of the hosted agents that will run your builds. + +### Using the Buildkite interface + +To create a new hosted queue using the Buildkite interface: + +1. Select **Agents** in the global navigation to access the **Clusters** page. +1. Select the cluster in which to create the new queue. +1. On the **Queues** page, select **New Queue** to open the **Create a new Queue** page. +1. In the **Create a key** field, enter a unique _key_ for the queue, which can only contain letters, numbers, hyphens, and underscores, as valid characters. +1. Select the **Add description** checkbox to enter an optional longer description for the queue. This description appears under the queue's key, which is listed on the **Queues** page, as well as when viewing the queue's details. +1. In the **Select your agent infrastructure** section, select [**Hosted**](/docs/pipelines/hosted-agents) for your agent infrastructure. +1. In the new **Configure your hosted agent infrastructure** section, select your **Machine type** ([**Linux**](/docs/pipelines/hosted-agents/linux) or [**macOS**](/docs/pipelines/hosted-agents/mac)). +1. If you selected **Linux**, within **Architecture**, you can choose between **AMD64** (the default and recommended) or **ARM64** architectures for the Linux machines running as hosted agents. To switch to **ARM64**, select **Change**, followed by **ARM64 (AArch64)**. +1. Select the appropriate **Capacity** for your hosted agent machine type (**Small**, **Medium** or **Large**). Take note of the additional information provided in the new **Hosted agents trial** section, which changes based on your selected **Capacity**. +1. Select **Create Queue**. + + The new queue's details are displayed, indicating the queue's key and its description (if configured) underneath this key. Select **Queues** on the interface again to list all configured queues in your cluster. + +### Using the REST API + +To [create a new hosted agent queue](/docs/apis/rest-api/clusters#queues-create-a-hosted-queue) using the [REST API](/docs/apis/rest-api), run the following example `curl` command: + +```curl +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": "hosted_linux_small", + "description": "Small AMD64 Linux agents hosted by Buildkite.", + "hosted": true, + "hostedAgents": { + "instanceShape": "LINUX_AMD64_2X4" + } + }' +``` + +where: + +<%= render_markdown partial: 'apis/descriptions/rest_access_token' %> + +<%= render_markdown partial: 'apis/descriptions/rest_org_slug' %> + +<%= render_markdown partial: 'apis/descriptions/rest_cluster_id' %> + +<%= render_markdown partial: 'apis/descriptions/common_create_queue_fields' %> + +- `hostedAgents` - The hosted agents configuration for this queue, setting this field will make this queue a hosted queue. + + `instanceShape` - The instance shape describes the machine type, architecture, CPU, and RAM to provision for hosted agent instances running jobs in this queue. + +

Instance shapes for Linux hosted agents:

+<%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_linux' %> + +

Instance shapes for macOS hosted agents:

+<%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_mac' %> + + Example: + ```json + "hostedAgents": { + "instanceShape": "LINUX_AMD64_2X4" + } + ``` + + +### Using the GraphQL API + +To [create a new hosted agent queue](/docs/apis/graphql/schemas/mutation/clusterqueuecreate) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: + +```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 + email + avatar { + url + } + } + } + } +} +``` + +where: + +<%= render_markdown partial: 'apis/descriptions/graphql_organization_id' %> + +<%= render_markdown partial: 'apis/descriptions/graphql_cluster_id' %> + +<%= render_markdown partial: 'apis/descriptions/common_create_queue_fields' %> + +- `hosted` - Setting this field to `true` will make this queue a hosted queue. Setting this field to `false` will make this queue a self-hosted queue. Providing `hostedAgents` configuration is only valid for hosted queues and will implicitly set `hosted` to `true`. + +- `hostedAgents` - The hosted agents configuration for this queue, setting this field will make this queue a hosted queue. + `instanceShape` - The instance shape describes the machine type, architecture, CPU and RAM to provision for hosted agent instances running jobs in this queue. + + Example: + + ```graphql + hostedAgents: { + instanceShape: LINUX_AMD64_2X4 + } + ``` +

Instance shapes for Linux hosted agents:

+<%= render partial: 'apis/descriptions/hosted_agents_instance_shape_table_linux' %> + +

Instance shapes for Mac hosted agents:

+<%= render partial: 'apis/descriptions/hosted_agents_instance_shape_table_mac' %> + ## Pause and resume a queue You can pause a queue to prevent any jobs of the cluster's pipelines from being dispatched to agents associated with this queue. diff --git a/pages/pipelines/getting_started.md b/pages/pipelines/getting_started.md index dc51385648..f836dce977 100644 --- a/pages/pipelines/getting_started.md +++ b/pages/pipelines/getting_started.md @@ -57,7 +57,7 @@ To create a hosted agent: 1. Navigate to the [cluster](/docs/pipelines/clusters/manage-clusters) you want to run your pipeline in. To do this, select **Agents** in the global navigation to access the **Clusters** page. 1. Select the cluster (for example, **Default cluster**) to which the hosted agent will be added. -1. Follow the [Create a queue](/docs/pipelines/clusters/manage-queues#create-a-queue) > [Using the Buildkite interface](/docs/pipelines/clusters/manage-queues#create-a-queue-using-the-buildkite-interface) instructions to begin creating your hosted agent within its own queue. +1. Follow the [Create a queue](/docs/pipelines/clusters/manage-queues#create-a-hosted-queue) > [Using the Buildkite interface](/docs/pipelines/clusters/manage-queues#create-a-hosted-queue-using-the-buildkite-interface) instructions to begin creating your hosted agent within its own queue. As part of this process: * In the **Select your agent infrastructure** section, choose **Hosted**. diff --git a/pages/pipelines/hosted_agents.md b/pages/pipelines/hosted_agents.md index c9a4263c85..b3f19ee4cb 100644 --- a/pages/pipelines/hosted_agents.md +++ b/pages/pipelines/hosted_agents.md @@ -6,7 +6,13 @@ With hosted agents, Buildkite handles infrastructure management tasks, such as p ## Hosted agent types -Buildkite offers both [Mac](/docs/pipelines/hosted-agents/mac) and [Linux](/docs/pipelines/hosted-agents/linux) hosted agents. Refer to these respective pages for detailed information about available the sizes and configurations for these agents. +Buildkite offers both [Mac](/docs/pipelines/hosted-agents/mac) and [Linux](/docs/pipelines/hosted-agents/linux) hosted agents. + +

Linux hosted agents

+<%= render partial: 'apis/descriptions/hosted_agents_instance_shape_table_linux' %> + +

Mac hosted agents

+<%= render partial: 'apis/descriptions/hosted_agents_instance_shape_table_mac' %> Usage of all instance types is billed on a per-minute basis. @@ -14,6 +20,8 @@ Every Buildkite hosted agent within a cluster benefits from hypervisor-level iso ## Creating a hosted agent queue +You can create a hosted queue using the [Buildkite interface](#create-a-hosted-queue-using-the-buildkite-interface), the [REST API](#create-a-hosted-queue-using-the-rest-api), or the [GraphQL API](#create-a-hosted-queue-using-the-graphql-api). Learn more about configuring hosted queues in [Manage queues](/docs/pipelines/clusters/manage-queues). + You can set up distinct hosted agent queues, each configured with specific types and sizes to efficiently manage jobs with varying requirements. For example you may have two queues set up: @@ -24,7 +32,6 @@ For example you may have two queues set up: Learn more about: - Best practices for configuring queues in [How should I structure my queues](/docs/pipelines/clusters#clusters-and-queues-best-practices-how-should-i-structure-my-queues). -- How to set up and create a Buildkite hosted agent queue in [Manage queues](/docs/pipelines/clusters/manage-queues). ## Using GitHub repositories in your hosted agent pipelines diff --git a/pages/pipelines/hosted_agents/linux.md b/pages/pipelines/hosted_agents/linux.md index 7e9d9cc00c..dc4b99a25b 100644 --- a/pages/pipelines/hosted_agents/linux.md +++ b/pages/pipelines/hosted_agents/linux.md @@ -7,20 +7,11 @@ Linux instances for Buildkite hosted agents are offered with two architectures: To accommodate different workloads, instances are capable of running up to 8 hours. If you require longer running agents please contact support. -## Size - -Buildkite offers a selection of instance sizes, allowing you to tailor your hosted agents' resources to the demands of your jobs. Below is a breakdown of the available sizes. - - - - - - - - - - -
SizevCPURAM
Small24 GB
Medium416 GB
Large832 GB
+## Sizes + +Buildkite offers a selection of instance sizes, allowing you to tailor your hosted agents' resources to the demands of your jobs. Below is a breakdown of the available shapes. + +<%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_linux' %> ## Cache volumes @@ -181,7 +172,7 @@ You can create an agent image: 1. Select **Agents** in the global navigation to access the **Clusters** page. 1. Select the cluster in which to create the new agent image. - **Note:** Before continuing, ensure you have created a hosted agent queue (based on Linux architecture) within this cluster. Learn more about how to do this in [Create a queue](/docs/pipelines/clusters/manage-queues#create-a-queue). + **Note:** Before continuing, ensure you have created a hosted agent queue (based on Linux architecture) within this cluster. Learn more about how to do this in [Create a queue](/docs/pipelines/clusters/manage-queues#create-a-hosted-queue). 1. Select **Agent Images** to open the **Agent Images** page. 1. Select **New Image** to open the **New Agent Image** dialog. diff --git a/pages/pipelines/hosted_agents/mac.md b/pages/pipelines/hosted_agents/mac.md index f6dd6c9577..44e0532d4a 100644 --- a/pages/pipelines/hosted_agents/mac.md +++ b/pages/pipelines/hosted_agents/mac.md @@ -4,20 +4,11 @@ Mac instances for Buildkite hosted agents are only offered with [Apple silicon]( To accommodate different workloads, instances are capable of running up to 4 hours. If you require longer running agents please contact support. -## Size - -We offer a selection of instance sizes, allowing you to tailor your hosted agent resources to the demands of your jobs. Below is a breakdown of the available sizes. - - - - - - - - - - -
SizevCPURAM
Small47 GB
Medium614 GB
Large1228 GB
+## Sizes + +We offer a selection of instance sizes, allowing you to tailor your hosted agent resources to the demands of your jobs. Below is a breakdown of the available shapes. + +<%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_mac' %> ## Mac instances software support diff --git a/vale/styles/Buildkite/existence-case-sensitive.yml b/vale/styles/Buildkite/existence-case-sensitive.yml index 214e7c2c2f..9cacb4e89a 100644 --- a/vale/styles/Buildkite/existence-case-sensitive.yml +++ b/vale/styles/Buildkite/existence-case-sensitive.yml @@ -40,7 +40,7 @@ swap: (?i:GraphQL): GraphQL (?i:IronWorker): IronWorker (?i:iTerm): iTerm - (?i:Mac): Mac + (?i:(? Date: Fri, 13 Dec 2024 15:21:56 +1100 Subject: [PATCH 02/22] Change file extensions for partials to see if this fixes the build errors. --- ...le_linux.html => _hosted_agents_instance_shape_table_linux.md} | 0 ..._table_mac.html => _hosted_agents_instance_shape_table_mac.md} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename pages/apis/descriptions/{_hosted_agents_instance_shape_table_linux.html => _hosted_agents_instance_shape_table_linux.md} (100%) rename pages/apis/descriptions/{_hosted_agents_instance_shape_table_mac.html => _hosted_agents_instance_shape_table_mac.md} (100%) diff --git a/pages/apis/descriptions/_hosted_agents_instance_shape_table_linux.html b/pages/apis/descriptions/_hosted_agents_instance_shape_table_linux.md similarity index 100% rename from pages/apis/descriptions/_hosted_agents_instance_shape_table_linux.html rename to pages/apis/descriptions/_hosted_agents_instance_shape_table_linux.md diff --git a/pages/apis/descriptions/_hosted_agents_instance_shape_table_mac.html b/pages/apis/descriptions/_hosted_agents_instance_shape_table_mac.md similarity index 100% rename from pages/apis/descriptions/_hosted_agents_instance_shape_table_mac.html rename to pages/apis/descriptions/_hosted_agents_instance_shape_table_mac.md From 9c3da45405f3f53a71bc14519339d880292de2ef Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Mon, 16 Dec 2024 12:31:38 +1100 Subject: [PATCH 03/22] Fix formatting of nested (instance shape) tables by drawing them out into their own tables underneath their relevant table sections. --- ...osted_agents_instance_shape_table_linux.md | 4 +- ..._hosted_agents_instance_shape_table_mac.md | 4 +- pages/apis/rest_api/clusters.md | 45 ++++++++++--------- 3 files changed, 29 insertions(+), 24 deletions(-) diff --git a/pages/apis/descriptions/_hosted_agents_instance_shape_table_linux.md b/pages/apis/descriptions/_hosted_agents_instance_shape_table_linux.md index 8d79940866..83afcac2b0 100644 --- a/pages/apis/descriptions/_hosted_agents_instance_shape_table_linux.md +++ b/pages/apis/descriptions/_hosted_agents_instance_shape_table_linux.md @@ -6,7 +6,7 @@ vCPU Memory - + LINUX_AMD64_2X4SmallAMD6424 GB @@ -31,5 +31,5 @@ LINUX_ARM64_16X64Extra LargeARM641664 GB - + diff --git a/pages/apis/descriptions/_hosted_agents_instance_shape_table_mac.md b/pages/apis/descriptions/_hosted_agents_instance_shape_table_mac.md index 4831f10c72..7390538bcd 100644 --- a/pages/apis/descriptions/_hosted_agents_instance_shape_table_mac.md +++ b/pages/apis/descriptions/_hosted_agents_instance_shape_table_mac.md @@ -5,7 +5,7 @@ vCPU Memory - + MACOS_M2_4X7Small47 GB @@ -18,5 +18,5 @@ MACOS_M4_12x56Extra Large1256 GB - + diff --git a/pages/apis/rest_api/clusters.md b/pages/apis/rest_api/clusters.md index 822426b83d..0591698509 100644 --- a/pages/apis/rest_api/clusters.md +++ b/pages/apis/rest_api/clusters.md @@ -469,7 +469,7 @@ Optional [request body properties](/docs/api#request-body-properties): hosted - Configure the queue to use [Hosted Agents](/docs/pipelines/hosted-agents).
Example: true + Configure the queue to use Hosted agents.
Example: true @@ -477,21 +477,14 @@ Optional [request body properties](/docs/api#request-body-properties): Configuration for hosted agents on this queue.
- Example:
+ Example: +
{ "instanceShape": "LINUX_AMD64_2X4" } - instanceShape (required): The instance shape to provision hosted agent machines on this queue.
- -

Instance shapes for Linux hosted agents:

- - <%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_linux' %> - -

Instance shapes for Mac hosted agents:

- - <%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_mac' %> + Learn more about the instance shapes available for Linux and Mac hosted agents. @@ -509,6 +502,14 @@ Error responses: +

Instance shapes for Linux hosted agents

+ +<%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_linux' %> + +

Instance shapes for Mac hosted agents

+ +<%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_mac' %> + ### Update a queue ```bash @@ -553,20 +554,16 @@ curl -H "Authorization: Bearer $TOKEN" \ Configuration for hosted agents on this queue.
- Example:
+ Example: +
{ "instanceShape": "LINUX_AMD64_2X4" } - +
instanceShape (required): The instance shape describes the machine type, architecture, CPU, and RAM to provision for hosted agent instances running jobs in this queue. - - The architecture (AMD64, ARM64) and machine type (MACOS, LINUX) of the instance shape must match the existing hosted agents on the queue. -
- - <%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_linux' %> - - <%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_mac' %> + The architecture (AMD64, ARM64) and machine type (MACOS, LINUX) of the instance shape must match the existing hosted agents on the queue.
+ Learn more about the instance shapes available for Linux and Mac hosted agents. @@ -584,6 +581,14 @@ Error responses: +

Instance shapes for Linux hosted agents

+ +<%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_linux' %> + +

Instance shapes for Mac hosted agents

+ +<%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_mac' %> + ### Delete a queue ```bash From d40ab9e055d96521e558f7728c5aee5e94dc1974 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Mon, 16 Dec 2024 13:52:54 +1100 Subject: [PATCH 04/22] Relocate partial to a more obvious directory location and fix partial syntax, along with heading syntax. --- pages/apis/rest_api/clusters.md | 8 ++++---- pages/pipelines/hosted_agents.md | 10 ++++++---- pages/pipelines/hosted_agents/linux.md | 2 +- pages/pipelines/hosted_agents/mac.md | 2 +- .../_hosted_agents_instance_shape_table_linux.md | 0 .../_hosted_agents_instance_shape_table_mac.md | 0 6 files changed, 12 insertions(+), 10 deletions(-) rename pages/{apis/descriptions => shared/hosted_agents}/_hosted_agents_instance_shape_table_linux.md (100%) rename pages/{apis/descriptions => shared/hosted_agents}/_hosted_agents_instance_shape_table_mac.md (100%) diff --git a/pages/apis/rest_api/clusters.md b/pages/apis/rest_api/clusters.md index 0591698509..8e1d13b339 100644 --- a/pages/apis/rest_api/clusters.md +++ b/pages/apis/rest_api/clusters.md @@ -504,11 +504,11 @@ Error responses:

Instance shapes for Linux hosted agents

-<%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_linux' %> +<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_linux' %>

Instance shapes for Mac hosted agents

-<%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_mac' %> +<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> ### Update a queue @@ -583,11 +583,11 @@ Error responses:

Instance shapes for Linux hosted agents

-<%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_linux' %> +<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_linux' %>

Instance shapes for Mac hosted agents

-<%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_mac' %> +<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> ### Delete a queue diff --git a/pages/pipelines/hosted_agents.md b/pages/pipelines/hosted_agents.md index b3f19ee4cb..9cc7b520e9 100644 --- a/pages/pipelines/hosted_agents.md +++ b/pages/pipelines/hosted_agents.md @@ -8,11 +8,13 @@ With hosted agents, Buildkite handles infrastructure management tasks, such as p Buildkite offers both [Mac](/docs/pipelines/hosted-agents/mac) and [Linux](/docs/pipelines/hosted-agents/linux) hosted agents. -

Linux hosted agents

-<%= render partial: 'apis/descriptions/hosted_agents_instance_shape_table_linux' %> +### Instance shapes for Linux hosted agents -

Mac hosted agents

-<%= render partial: 'apis/descriptions/hosted_agents_instance_shape_table_mac' %> +<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_linux' %> + +### Instance shapes for Mac hosted agents + +<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> Usage of all instance types is billed on a per-minute basis. diff --git a/pages/pipelines/hosted_agents/linux.md b/pages/pipelines/hosted_agents/linux.md index dc4b99a25b..2b3bf42888 100644 --- a/pages/pipelines/hosted_agents/linux.md +++ b/pages/pipelines/hosted_agents/linux.md @@ -11,7 +11,7 @@ To accommodate different workloads, instances are capable of running up to 8 hou Buildkite offers a selection of instance sizes, allowing you to tailor your hosted agents' resources to the demands of your jobs. Below is a breakdown of the available shapes. -<%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_linux' %> +<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_linux' %> ## Cache volumes diff --git a/pages/pipelines/hosted_agents/mac.md b/pages/pipelines/hosted_agents/mac.md index 44e0532d4a..fe7c6b65a2 100644 --- a/pages/pipelines/hosted_agents/mac.md +++ b/pages/pipelines/hosted_agents/mac.md @@ -8,7 +8,7 @@ To accommodate different workloads, instances are capable of running up to 4 hou We offer a selection of instance sizes, allowing you to tailor your hosted agent resources to the demands of your jobs. Below is a breakdown of the available shapes. -<%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_mac' %> +<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> ## Mac instances software support diff --git a/pages/apis/descriptions/_hosted_agents_instance_shape_table_linux.md b/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_linux.md similarity index 100% rename from pages/apis/descriptions/_hosted_agents_instance_shape_table_linux.md rename to pages/shared/hosted_agents/_hosted_agents_instance_shape_table_linux.md diff --git a/pages/apis/descriptions/_hosted_agents_instance_shape_table_mac.md b/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_mac.md similarity index 100% rename from pages/apis/descriptions/_hosted_agents_instance_shape_table_mac.md rename to pages/shared/hosted_agents/_hosted_agents_instance_shape_table_mac.md From b2d29cdbcb84d898ea8407d6180869ab0a3d250d Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Mon, 16 Dec 2024 14:38:14 +1100 Subject: [PATCH 05/22] Fix remaining partials and heading syntax. --- pages/pipelines/clusters/manage_queues.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/pages/pipelines/clusters/manage_queues.md b/pages/pipelines/clusters/manage_queues.md index 193f079f36..240cedc187 100644 --- a/pages/pipelines/clusters/manage_queues.md +++ b/pages/pipelines/clusters/manage_queues.md @@ -244,11 +244,14 @@ where: instanceShape: LINUX_AMD64_2X4 } ``` -

Instance shapes for Linux hosted agents:

-<%= render partial: 'apis/descriptions/hosted_agents_instance_shape_table_linux' %> -

Instance shapes for Mac hosted agents:

-<%= render partial: 'apis/descriptions/hosted_agents_instance_shape_table_mac' %> +### Instance shapes for Linux hosted agents + +<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_linux' %> + +### Instance shapes for Mac hosted agents + +<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> ## Pause and resume a queue From d1c8c2c98e9b6f020a02b66c7ffcf9d7ab866781 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Mon, 16 Dec 2024 14:42:52 +1100 Subject: [PATCH 06/22] Missed a couple more! --- pages/pipelines/clusters/manage_queues.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/pages/pipelines/clusters/manage_queues.md b/pages/pipelines/clusters/manage_queues.md index 240cedc187..567b8f3ddf 100644 --- a/pages/pipelines/clusters/manage_queues.md +++ b/pages/pipelines/clusters/manage_queues.md @@ -164,11 +164,13 @@ where: - `hostedAgents` - The hosted agents configuration for this queue, setting this field will make this queue a hosted queue. + `instanceShape` - The instance shape describes the machine type, architecture, CPU, and RAM to provision for hosted agent instances running jobs in this queue. -

Instance shapes for Linux hosted agents:

-<%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_linux' %> +### Instance shapes for Linux hosted agents + +<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_linux' %> -

Instance shapes for macOS hosted agents:

-<%= render_markdown partial: 'apis/descriptions/hosted_agents_instance_shape_table_mac' %> +### Instance shapes for Mac hosted agents + +<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> Example: ```json From b4cdb2307012234e2cceb0c812b7d0082deee0ab Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Mon, 16 Dec 2024 15:47:53 +1100 Subject: [PATCH 07/22] Rationalise 'instance shape' tables on 'manage queues' page. --- pages/pipelines/clusters/manage_queues.md | 12 +--- pages/pipelines/hosted_agents.md | 8 ++- ...osted_agents_instance_shape_table_linux.md | 66 ++++++++++++++++--- ..._hosted_agents_instance_shape_table_mac.md | 30 +++++++-- 4 files changed, 89 insertions(+), 27 deletions(-) diff --git a/pages/pipelines/clusters/manage_queues.md b/pages/pipelines/clusters/manage_queues.md index 567b8f3ddf..cc477c32e8 100644 --- a/pages/pipelines/clusters/manage_queues.md +++ b/pages/pipelines/clusters/manage_queues.md @@ -164,14 +164,6 @@ where: - `hostedAgents` - The hosted agents configuration for this queue, setting this field will make this queue a hosted queue. + `instanceShape` - The instance shape describes the machine type, architecture, CPU, and RAM to provision for hosted agent instances running jobs in this queue. -### Instance shapes for Linux hosted agents - -<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_linux' %> - -### Instance shapes for Mac hosted agents - -<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> - Example: ```json "hostedAgents": { @@ -247,11 +239,11 @@ where: } ``` -### Instance shapes for Linux hosted agents +### Instance shape values for Linux <%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_linux' %> -### Instance shapes for Mac hosted agents +### Instance shape values for Mac <%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> diff --git a/pages/pipelines/hosted_agents.md b/pages/pipelines/hosted_agents.md index 9cc7b520e9..1a76641c58 100644 --- a/pages/pipelines/hosted_agents.md +++ b/pages/pipelines/hosted_agents.md @@ -22,8 +22,6 @@ Every Buildkite hosted agent within a cluster benefits from hypervisor-level iso ## Creating a hosted agent queue -You can create a hosted queue using the [Buildkite interface](#create-a-hosted-queue-using-the-buildkite-interface), the [REST API](#create-a-hosted-queue-using-the-rest-api), or the [GraphQL API](#create-a-hosted-queue-using-the-graphql-api). Learn more about configuring hosted queues in [Manage queues](/docs/pipelines/clusters/manage-queues). - You can set up distinct hosted agent queues, each configured with specific types and sizes to efficiently manage jobs with varying requirements. For example you may have two queues set up: @@ -33,7 +31,11 @@ For example you may have two queues set up: Learn more about: -- Best practices for configuring queues in [How should I structure my queues](/docs/pipelines/clusters#clusters-and-queues-best-practices-how-should-i-structure-my-queues). +- Creating hosted queues in [Create a hosted queue](/docs/pipelines/clusters/manage-queues#create-a-hosted-queue). + +- Best practices for configuring queues in [How should I structure my queues](/docs/pipelines/clusters#clusters-and-queues-best-practices-how-should-i-structure-my-queues) of the [Clusters overview](/docs/pipelines/clusters). + +- Configuring queues in general, in [Manage queues](/docs/pipelines/clusters/manage-queues). ## Using GitHub repositories in your hosted agent pipelines diff --git a/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_linux.md b/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_linux.md index 83afcac2b0..162800130c 100644 --- a/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_linux.md +++ b/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_linux.md @@ -1,6 +1,6 @@ - + @@ -8,28 +8,76 @@ - + + + + + - + + + + + - + + + + + - + + + + + - + + + + - + + + + + - + + + + + - + + + + +
Instance ShapeInstance shape value Size Architecture vCPU
LINUX_AMD64_2X4SmallAMD6424 GB + LINUX_AMD64_2X4 + SmallAMD6424 GB
LINUX_AMD64_4X16MediumAMD64416 GB + LINUX_AMD64_4X16 + MediumAMD64416 GB
LINUX_AMD64_8X32LargeAMD64832 GB + LINUX_AMD64_8X32 + LargeAMD64832 GB
LINUX_AMD64_16X64Extra LargeAMD641664 GB + LINUX_AMD64_16X64 + Extra LargeAMD641664 GB
LINUX_ARM64_2X4SmallARM6424 GB + LINUX_ARM64_2X4 + SmallARM6424 GB
LINUX_ARM64_4X16MediumARM64416 GB + LINUX_ARM64_4X16 + MediumARM64416 GB
LINUX_ARM64_8X32LargeARM64832 GB + LINUX_ARM64_8X32 + LargeARM64832 GB
LINUX_ARM64_16X64Extra LargeARM641664 GB + LINUX_ARM64_16X64 + Extra LargeARM641664 GB
diff --git a/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_mac.md b/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_mac.md index 7390538bcd..b008b005df 100644 --- a/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_mac.md +++ b/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_mac.md @@ -1,22 +1,42 @@ - + - + + + + - + + + + - + + + + - + + + +
Instance ShapeInstance shape value Size vCPU Memory
MACOS_M2_4X7Small47 GB + MACOS_M2_4X7 + Small47 GB
MACOS_M2_6X14Medium614 GB + MACOS_M2_6X14 + Medium614 GB
MACOS_M2_12X28Large1228 GB + MACOS_M2_12X28 + Large1228 GB
MACOS_M4_12x56Extra Large1256 GB + MACOS_M4_12x56 + Extra Large1256 GB
From 47c4e8adf082ead361e0a7d33d3d7bc0d9941355 Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Tue, 17 Dec 2024 09:22:31 +1100 Subject: [PATCH 08/22] Update pages/apis/graphql/cookbooks/hosted_agents.md --- pages/apis/graphql/cookbooks/hosted_agents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/apis/graphql/cookbooks/hosted_agents.md b/pages/apis/graphql/cookbooks/hosted_agents.md index aac74f7fb6..9b6632670b 100644 --- a/pages/apis/graphql/cookbooks/hosted_agents.md +++ b/pages/apis/graphql/cookbooks/hosted_agents.md @@ -47,7 +47,7 @@ mutation { } ``` -Create a small AMD64 Linux hosted agent cluster queue, which is hosted by Buildkite. The `instanceShape` value is referenced from the [InstanceShape](/docs/apis/graphql/schemas/enum/instanceshape) 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 2 vCPU and 4 GB memory. +Create a small AMD64 Linux hosted agent cluster queue, which is hosted by Buildkite. 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 2 vCPU and 4 GB memory. ## Changing the instance shape of a hosted agent cluster queue From 9cda5dc327d58924c535064152bd59242f2b34c5 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Tue, 17 Dec 2024 16:56:36 +1100 Subject: [PATCH 09/22] Reduce 'instance shape' table duplication, and heavily refactor 'managing queues' page to add more context around the differences between the hosted queue types. --- pages/apis/rest_api/clusters.md | 36 ++++---- pages/pipelines/clusters.md | 2 +- pages/pipelines/clusters/manage_clusters.md | 4 +- pages/pipelines/clusters/manage_queues.md | 84 +++++++++++-------- pages/pipelines/getting_started.md | 4 +- pages/pipelines/hosted_agents.md | 14 +--- pages/pipelines/hosted_agents/linux.md | 6 +- pages/pipelines/hosted_agents/mac.md | 4 +- ...osted_agents_instance_shape_table_linux.md | 2 +- ..._hosted_agents_instance_shape_table_mac.md | 2 +- 10 files changed, 82 insertions(+), 76 deletions(-) diff --git a/pages/apis/rest_api/clusters.md b/pages/apis/rest_api/clusters.md index 8e1d13b339..77060c6f22 100644 --- a/pages/apis/rest_api/clusters.md +++ b/pages/apis/rest_api/clusters.md @@ -404,7 +404,7 @@ Error responses: -### Create a hosted queue +### Create a Buildkite hosted queue ```bash curl -H "Authorization: Bearer $TOKEN" \ @@ -484,7 +484,7 @@ Optional [request body properties](/docs/api#request-body-properties): instanceShape (required): The instance shape to provision hosted agent machines on this queue.
- Learn more about the instance shapes available for Linux and Mac hosted agents. + Learn more about the instance shapes available for Linux and Mac hosted agents. @@ -502,14 +502,6 @@ Error responses: -

Instance shapes for Linux hosted agents

- -<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_linux' %> - -

Instance shapes for Mac hosted agents

- -<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> - ### Update a queue ```bash @@ -562,8 +554,8 @@ curl -H "Authorization: Bearer $TOKEN" \
instanceShape (required): The instance shape describes the machine type, architecture, CPU, and RAM to provision for hosted agent instances running jobs in this queue.
- The architecture (AMD64, ARM64) and machine type (MACOS, LINUX) of the instance shape must match the existing hosted agents on the queue.
- Learn more about the instance shapes available for Linux and Mac hosted agents. + The architecture (AMD64, ARM64) and machine type (macOS, Linux) of the instance shape must match the existing hosted agents on the queue.
+ Learn more about the instance shapes available for Linux and Mac Buildkite hosted agents. @@ -581,14 +573,6 @@ Error responses: -

Instance shapes for Linux hosted agents

- -<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_linux' %> - -

Instance shapes for Mac hosted agents

- -<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> - ### Delete a queue ```bash @@ -722,6 +706,18 @@ Error responses: +### 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). diff --git a/pages/pipelines/clusters.md b/pages/pipelines/clusters.md index 679b631ae6..244f99271b 100644 --- a/pages/pipelines/clusters.md +++ b/pages/pipelines/clusters.md @@ -40,7 +40,7 @@ Learn more about working with clusters in [Manage clusters](/docs/pipelines/clus The most common queue attributes are based on infrastructure set-ups, such as: - Architecture (x86, arm64, Apple silicon, etc.) -- Size of agents (small, medium, large) +- Size of agents (small, medium, large, extra large) - Type of machine (macOS, Linux, Windows, GPU, etc.) Therefore, an example queue would be `small_mac_silicon`. diff --git a/pages/pipelines/clusters/manage_clusters.md b/pages/pipelines/clusters/manage_clusters.md index de374cba9c..cf93bdf493 100644 --- a/pages/pipelines/clusters/manage_clusters.md +++ b/pages/pipelines/clusters/manage_clusters.md @@ -238,9 +238,9 @@ where: ## Manage maintainers on a cluster -Buildkite administrators or users with the [_change organization_ permission](/docs/platform/team-management/permissions) can create clusters. +A user who is a [_Buildkite organization administrator_](/docs/platform/team-management/permissions#manage-teams-and-permissions-organization-level-permissions) can create clusters. Learn more about user permissions in Buildkite from [User and team permissions](/docs/platform/team-management/permissions). -As one of these types of users, you can add and manage other users or teams in your Buildkite organization as _maintainers_ of a cluster in the organization. A cluster maintainer can: +As a Buildkite organization administrator, you can add and manage other users or teams in your Buildkite organization as _maintainers_ of a cluster in the organization. A cluster maintainer can: - Update or delete the cluster. - Manage [agent tokens](/docs/agent/v3/tokens) associated with the cluster. diff --git a/pages/pipelines/clusters/manage_queues.md b/pages/pipelines/clusters/manage_queues.md index cc477c32e8..2e0f4a0af4 100644 --- a/pages/pipelines/clusters/manage_queues.md +++ b/pages/pipelines/clusters/manage_queues.md @@ -6,30 +6,39 @@ This page provides details on how to manage queues within a [cluster](/docs/pipe When a new Buildkite organization is created, along with the automatically created [default cluster](/docs/pipelines/clusters/manage-clusters#setting-up-clusters) (named **Default cluster**), a default queue (named **default-queue**) within this cluster is also created. -A cluster can be configured with multiple queues, each of which can be used to represent a specific combination of your build/agent infrastructure, based on: +A cluster can be configured with multiple queues, each of which can be used to represent a specific combination of your [build/agent infrastructure](#agent-infrastructure), based on: - Architecture (x86-64, arm64, Apple silicon, etc.) -- Size of agents (small, medium, large) +- Size of agents (small, medium, large, extra large) - Type of machine (Mac, Linux, Windows, etc.) -Some example queues might be `mac_medium_x86`, `mac_large_silicon`, etc. +Some example queues might be `linux_medium_x86`, `mac_large_silicon`, etc. Having individual queues according to these breakdowns allows you to scale a set of similar agents, which Buildkite can then report on. -### Agent infrastructure +## Agent infrastructure -As part of setting up a queue, you can choose between setting up your agents using either [hosted](/docs/pipelines/hosted-agents) or self-hosted infrastructure. +Buildkite provides a [hosted infrastructure](/docs/pipelines/hosted-agents) for your [Buildkite Agents](/docs/agent/v3), as well as support for Buildkite Agents in your own self-hosted infrastructure. -Buildkite provides a hosted infrastructure for your [Buildkite Agents](/docs/agent/v3), as well as support for self-hosted infrastructure, where you provide the infrastructure that hosts Buildkite Agents. +As part of setting up a queue, you can choose between configuring your queue with agents running in either of these types of infrastructure. + +Learn more about how to set up and create a queue using either self-hosted agents (known as a [self-hosted queue](#create-a-self-hosted-queue)) or Buildkite hosted agents (known as a [Buildkite hosted queue](#create-a-buildkite-hosted-queue)). + +Be aware that it is not possible to create a queue that uses a mix of self-hosted and Buildkite hosted agents. If you do need to use a combination of these different agent types for your pipeline builds, create separate self-hosted and Buildkite hosted queues for these agents and use [agent or queue tags](/docs/agent/v3/queues#setting-an-agents-queue), or a combination of both, to target the appropriate queues. ## Create a self-hosted queue -Self-hosted queues use your own infrastructure to run your builds. New queues can be created by a [cluster maintainer](/docs/pipelines/clusters/manage-clusters#manage-maintainers-on-a-cluster) using the [**Queues** page of a cluster](#create-a-self-hosted-queue-using-the-buildkite-interface), as well as the [REST API's](#create-a-self-hosted-queue-using-the-rest-api) or [GraphQL API's](#create-a-self-hosted-queue-using-the-graphql-api) create a queue feature. +Self-hosted queues use your own infrastructure to run your pipeline builds. New self-hosted queues can be created by a [cluster maintainer](/docs/pipelines/clusters/manage-clusters#manage-maintainers-on-a-cluster) using the [Buildkite interface](#create-a-self-hosted-queue-using-the-buildkite-interface), as well as the [REST API's](#create-a-self-hosted-queue-using-the-rest-api) or [GraphQL API's](#create-a-self-hosted-queue-using-the-graphql-api) create a queue feature. For these API requests, the _cluster ID_ value submitted in the request is the target cluster the queue will be created in. When you [create a new cluster](/docs/pipelines/clusters/manage-clusters#create-a-cluster) through the [Buildkite interface](/docs/pipelines/clusters/manage-clusters#create-a-cluster-using-the-buildkite-interface), this cluster automatically has an initial **default** queue. +Multiple self-hosted agents can connect to your self-hosted queue by ensuring that the agent is configured to use both of the following: + +- The [cluster's agent token](/docs/agent/v3/tokens#using-and-storing-tokens) +- The [agent tag](/docs/agent/v3/queues#setting-an-agents-queue) targeting your self-hosted queue + ### Using the Buildkite interface To create a new queue using the Buildkite interface: @@ -53,8 +62,9 @@ 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": "mac_large_silicon", - "description": "The queue for powerful macOS agents running on Apple silicon architecture." + "key": "linux_small_amd", + "description": "A small self-hosted AMD64 Linux agent.", + "hosted": false }' ``` @@ -68,6 +78,8 @@ where: <%= render_markdown partial: 'apis/descriptions/common_create_queue_fields' %> +- `hosted` (optional) is explicitly set to `false` to ensure that this queue is a self-hosted one that only supports self-hosted agents. If this property is omitted, its value assumed to be `false`. + ### Using the GraphQL API To [create a new self-hosted agent queue](/docs/apis/graphql/schemas/mutation/clusterqueuecreate) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: @@ -78,8 +90,9 @@ mutation { input: { organizationId: "organization-id" clusterId: "cluster-id" - key: "mac_large_silicon" - description: "The queue for powerful macOS agents running on Apple silicon architecture." + key: "linux_small_amd" + description: "A small self-hosted AMD64 Linux agent." + hosted: false } ) { clusterQueue { @@ -110,22 +123,26 @@ where: <%= render_markdown partial: 'apis/descriptions/common_create_queue_fields' %> -## Create a hosted queue +- `hosted` (optional) is explicitly set to `false` to ensure that this queue is a self-hosted one that only supports self-hosted agents. If this property is omitted, its value assumed to be `false`. + +## Create a Buildkite hosted queue + +Buildkite hosted queues use [Buildkite's hosted agent infrastructure](/docs/pipelines/hosted-agents) to run your pipeline builds. New Buildkite hosted queues can be created by a [cluster maintainer](/docs/pipelines/clusters/manage-clusters#manage-maintainers-on-a-cluster) using the [Buildkite interface](#create-a-buildkite-hosted-queue-using-the-buildkite-interface), the [REST API](#create-a-buildkite-hosted-queue-using-the-rest-api), or the [GraphQL API](#create-a-buildkite-hosted-queue-using-the-graphql-api). -Hosted cluster queues use Buildkite's hosted agent infrastructure to run your builds. You can create a hosted queue using the [Buildkite interface](#create-a-hosted-queue-using-the-buildkite-interface), the [REST API](#create-a-hosted-queue-using-the-rest-api), or the [GraphQL API](#create-a-hosted-queue-using-the-graphql-api). +When you create a Buildkite hosted queue, you can choose the machine type (Linux or macOS) and the capacity (small, medium, large, or extra large), known as the _instance shape_, of the Buildkite hosted agents that will run your builds. -When you create a hosted queue, you can choose the machine type (Linux or macOS) and the capacity (small, medium, or large) of the hosted agents that will run your builds. +Only one instance shape can be configured on a Buildkite hosted queue. However, depending on your pipeline's requirements, multiple Buildkite hosted agents of the queue's configured instance shape can be spawned automatically by Buildkite. ### Using the Buildkite interface -To create a new hosted queue using the Buildkite interface: +To create a new Buildkite hosted queue using the Buildkite interface: 1. Select **Agents** in the global navigation to access the **Clusters** page. 1. Select the cluster in which to create the new queue. 1. On the **Queues** page, select **New Queue** to open the **Create a new Queue** page. 1. In the **Create a key** field, enter a unique _key_ for the queue, which can only contain letters, numbers, hyphens, and underscores, as valid characters. 1. Select the **Add description** checkbox to enter an optional longer description for the queue. This description appears under the queue's key, which is listed on the **Queues** page, as well as when viewing the queue's details. -1. In the **Select your agent infrastructure** section, select [**Hosted**](/docs/pipelines/hosted-agents) for your agent infrastructure. +1. In the **Select your agent infrastructure** section, select **Hosted** for your agent infrastructure. 1. In the new **Configure your hosted agent infrastructure** section, select your **Machine type** ([**Linux**](/docs/pipelines/hosted-agents/linux) or [**macOS**](/docs/pipelines/hosted-agents/mac)). 1. If you selected **Linux**, within **Architecture**, you can choose between **AMD64** (the default and recommended) or **ARM64** architectures for the Linux machines running as hosted agents. To switch to **ARM64**, select **Change**, followed by **ARM64 (AArch64)**. 1. Select the appropriate **Capacity** for your hosted agent machine type (**Small**, **Medium** or **Large**). Take note of the additional information provided in the new **Hosted agents trial** section, which changes based on your selected **Capacity**. @@ -135,18 +152,18 @@ To create a new hosted queue using the Buildkite interface: ### Using the REST API -To [create a new hosted agent queue](/docs/apis/rest-api/clusters#queues-create-a-hosted-queue) using the [REST API](/docs/apis/rest-api), run the following example `curl` command: +To [create a new Buildkite hosted queue](/docs/apis/rest-api/clusters#queues-create-a-buildkite-hosted-queue) using the [REST API](/docs/apis/rest-api), run the following example `curl` command: ```curl 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": "hosted_linux_small", - "description": "Small AMD64 Linux agents hosted by Buildkite.", + "key": "mac_xlarge_silicon", + "description": "Powerful macOS agents running on Apple silicon architecture.", "hosted": true, "hostedAgents": { - "instanceShape": "LINUX_AMD64_2X4" + "instanceShape": "MACOS_M4_12x56" } }' ``` @@ -161,20 +178,19 @@ where: <%= render_markdown partial: 'apis/descriptions/common_create_queue_fields' %> -- `hostedAgents` - The hosted agents configuration for this queue, setting this field will make this queue a hosted queue. - + `instanceShape` - The instance shape describes the machine type, architecture, CPU, and RAM to provision for hosted agent instances running jobs in this queue. +- `hosted` (optional) is explicitly set to `true` to ensure that this queue is a Buildkite hosted one that only supports Buildkite hosted agents. This property can be omitted when the `hostedAgents` property is specified. + +- `hostedAgents` (required) defines the instance shape (within its `instanceShape` object) for this queue's [Linux-](#create-a-buildkite-hosted-queue-instance-shape-values-for-linux) or [Mac-](#create-a-buildkite-hosted-queue-instance-shape-values-for-mac)based Buildkite hosted agent. Specifying `hostedAgents` automatically sets the `hosted` property on this request to `true`, which is why this property can be omitted. For example: - Example: ```json "hostedAgents": { "instanceShape": "LINUX_AMD64_2X4" } ``` - ### Using the GraphQL API -To [create a new hosted agent queue](/docs/apis/graphql/schemas/mutation/clusterqueuecreate) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: +To [create a new Buildkite hosted queue](/docs/apis/graphql/schemas/mutation/clusterqueuecreate) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: ```graphql mutation { @@ -182,10 +198,11 @@ mutation { input: { organizationId: "organization-id" clusterId: "cluster-id" - key: "hosted_linux_small" - description: "Small AMD64 Linux agents hosted by Buildkite." + key: "mac_xlarge_silicon" + description: "Powerful macOS agents running on Apple silicon architecture." + hosted: true hostedAgents: { - instanceShape: LINUX_AMD64_2X4 + instanceShape: MACOS_M4_12x56 } } ) { @@ -226,12 +243,9 @@ where: <%= render_markdown partial: 'apis/descriptions/common_create_queue_fields' %> -- `hosted` - Setting this field to `true` will make this queue a hosted queue. Setting this field to `false` will make this queue a self-hosted queue. Providing `hostedAgents` configuration is only valid for hosted queues and will implicitly set `hosted` to `true`. +- `hosted` (optional) is explicitly set to `true` to ensure that this queue is a Buildkite hosted one that only supports Buildkite hosted agents. This property can be omitted when the `hostedAgents` property is specified. -- `hostedAgents` - The hosted agents configuration for this queue, setting this field will make this queue a hosted queue. - `instanceShape` - The instance shape describes the machine type, architecture, CPU and RAM to provision for hosted agent instances running jobs in this queue. - - Example: +- `hostedAgents` (required) defines the instance shape (within its `instanceShape` object) for this queue's [Linux-](#create-a-buildkite-hosted-queue-instance-shape-values-for-linux) or [Mac-](#create-a-buildkite-hosted-queue-instance-shape-values-for-mac)based Buildkite hosted agent. Specifying `hostedAgents` automatically sets the `hosted` property on this request to `true`, which is why this property can be omitted. For example: ```graphql hostedAgents: { @@ -241,10 +255,14 @@ where: ### Instance shape values for Linux +Specify the appropriate **Instance shape** for the `instanceShape` value in your 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 API call. + <%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> ## Pause and resume a queue diff --git a/pages/pipelines/getting_started.md b/pages/pipelines/getting_started.md index f836dce977..cdf1277b19 100644 --- a/pages/pipelines/getting_started.md +++ b/pages/pipelines/getting_started.md @@ -53,11 +53,13 @@ You need at least one agent configured within its own queue and cluster to run b You can create the first [Buildkite hosted agent](/docs/pipelines/hosted-agents) within a Buildkite organization for a two-week free trial, after which a usage cost (based on the agent's capacity) is charged per minute. +Before creating your Buildkite hosted agent, ensure you have a [cluster](/docs/pipelines/clusters/manage-clusters) (for example, **Default cluster**) you can connect this agent to. + To create a hosted agent: 1. Navigate to the [cluster](/docs/pipelines/clusters/manage-clusters) you want to run your pipeline in. To do this, select **Agents** in the global navigation to access the **Clusters** page. 1. Select the cluster (for example, **Default cluster**) to which the hosted agent will be added. -1. Follow the [Create a queue](/docs/pipelines/clusters/manage-queues#create-a-hosted-queue) > [Using the Buildkite interface](/docs/pipelines/clusters/manage-queues#create-a-hosted-queue-using-the-buildkite-interface) instructions to begin creating your hosted agent within its own queue. +1. Follow the [Create a Buildkite hosted queue](/docs/pipelines/clusters/manage-queues#create-a-buildkite-hosted-queue) > [Using the Buildkite interface](/docs/pipelines/clusters/manage-queues#create-a-buildkite-hosted-queue-using-the-buildkite-interface) instructions to begin creating your hosted agent within its own queue. As part of this process: * In the **Select your agent infrastructure** section, choose **Hosted**. diff --git a/pages/pipelines/hosted_agents.md b/pages/pipelines/hosted_agents.md index 1a76641c58..bc92e9508c 100644 --- a/pages/pipelines/hosted_agents.md +++ b/pages/pipelines/hosted_agents.md @@ -8,21 +8,13 @@ With hosted agents, Buildkite handles infrastructure management tasks, such as p Buildkite offers both [Mac](/docs/pipelines/hosted-agents/mac) and [Linux](/docs/pipelines/hosted-agents/linux) hosted agents. -### Instance shapes for Linux hosted agents - -<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_linux' %> - -### Instance shapes for Mac hosted agents - -<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> - Usage of all instance types is billed on a per-minute basis. Every Buildkite hosted agent within a cluster benefits from hypervisor-level isolation, ensuring robust separation between each instance. -## Creating a hosted agent queue +## Creating a Buildkite hosted queue -You can set up distinct hosted agent queues, each configured with specific types and sizes to efficiently manage jobs with varying requirements. +You can set up distinct queues for your Buildkite hosted agents (known as _Buildkite hosted queues_), each configured with a specific type and size of hosted agent, to efficiently manage jobs with varying requirements. Learn more about how to do this in [Create a Buildkite hosted queue](/docs/pipelines/clusters/manage-queues#create-a-buildkite-hosted-queue). For example you may have two queues set up: @@ -31,8 +23,6 @@ For example you may have two queues set up: Learn more about: -- Creating hosted queues in [Create a hosted queue](/docs/pipelines/clusters/manage-queues#create-a-hosted-queue). - - Best practices for configuring queues in [How should I structure my queues](/docs/pipelines/clusters#clusters-and-queues-best-practices-how-should-i-structure-my-queues) of the [Clusters overview](/docs/pipelines/clusters). - Configuring queues in general, in [Manage queues](/docs/pipelines/clusters/manage-queues). diff --git a/pages/pipelines/hosted_agents/linux.md b/pages/pipelines/hosted_agents/linux.md index 2b3bf42888..4e77385bfb 100644 --- a/pages/pipelines/hosted_agents/linux.md +++ b/pages/pipelines/hosted_agents/linux.md @@ -5,11 +5,11 @@ Linux instances for Buildkite hosted agents are offered with two architectures: - AMD64 (x64_86) - ARM64 (AArch64) -To accommodate different workloads, instances are capable of running up to 8 hours. If you require longer running agents please contact support. +To accommodate different workloads, instances are capable of running up to 8 hours. If you require longer running agents, please contact support at support@buildkite.com. ## Sizes -Buildkite offers a selection of instance sizes, allowing you to tailor your hosted agents' resources to the demands of your jobs. Below is a breakdown of the available shapes. +Buildkite offers a selection of Linux instance types (each based on a different combination of size and architecture, known as an _instance shape_), allowing you to tailor your hosted agent resources to the demands of your jobs. <%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_linux' %> @@ -172,7 +172,7 @@ You can create an agent image: 1. Select **Agents** in the global navigation to access the **Clusters** page. 1. Select the cluster in which to create the new agent image. - **Note:** Before continuing, ensure you have created a hosted agent queue (based on Linux architecture) within this cluster. Learn more about how to do this in [Create a queue](/docs/pipelines/clusters/manage-queues#create-a-hosted-queue). + **Note:** Before continuing, ensure you have created a hosted agent queue (based on Linux architecture) within this cluster. Learn more about how to do this in [Create a Buildkite hosted queue](/docs/pipelines/clusters/manage-queues#create-a-buildkite-hosted-queue). 1. Select **Agent Images** to open the **Agent Images** page. 1. Select **New Image** to open the **New Agent Image** dialog. diff --git a/pages/pipelines/hosted_agents/mac.md b/pages/pipelines/hosted_agents/mac.md index fe7c6b65a2..175341e696 100644 --- a/pages/pipelines/hosted_agents/mac.md +++ b/pages/pipelines/hosted_agents/mac.md @@ -2,11 +2,11 @@ Mac instances for Buildkite hosted agents are only offered with [Apple silicon](https://en.wikipedia.org/wiki/Apple_silicon) architecture. Please contact support if you have specific needs for Intel machines. -To accommodate different workloads, instances are capable of running up to 4 hours. If you require longer running agents please contact support. +To accommodate different workloads, instances are capable of running up to 4 hours. If you require longer running agents, please contact support at support@buildkite.com. ## Sizes -We offer a selection of instance sizes, allowing you to tailor your hosted agent resources to the demands of your jobs. Below is a breakdown of the available shapes. +Buildkite offers a selection of Mac instance types (each based on a different size combination of virtual CPU power and memory capacity, known as an _instance shape_), allowing you to tailor your hosted agents' resources to the demands of your jobs. <%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> diff --git a/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_linux.md b/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_linux.md index 162800130c..eac132afaa 100644 --- a/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_linux.md +++ b/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_linux.md @@ -1,6 +1,6 @@ - + diff --git a/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_mac.md b/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_mac.md index b008b005df..51751425ec 100644 --- a/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_mac.md +++ b/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_mac.md @@ -1,6 +1,6 @@
Instance shape valueInstance shape Size Architecture vCPU
- + From f1af9907f5cdd3a5a26cb08c79c7cd92eca4f0fc Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 18 Dec 2024 11:45:37 +1100 Subject: [PATCH 10/22] Tweak explanations on manage queues page a tad. --- pages/pipelines/clusters/manage_queues.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pages/pipelines/clusters/manage_queues.md b/pages/pipelines/clusters/manage_queues.md index 2e0f4a0af4..54867d4b81 100644 --- a/pages/pipelines/clusters/manage_queues.md +++ b/pages/pipelines/clusters/manage_queues.md @@ -18,9 +18,9 @@ Having individual queues according to these breakdowns allows you to scale a set ## Agent infrastructure -Buildkite provides a [hosted infrastructure](/docs/pipelines/hosted-agents) for your [Buildkite Agents](/docs/agent/v3), as well as support for Buildkite Agents in your own self-hosted infrastructure. +Buildkite provides support for managing [Buildkite Agents](/docs/agent/v3) in your own self-hosted infrastructure, as well as a [Buildkite hosted infrastructure](/docs/pipelines/hosted-agents) for managing these agents. -As part of setting up a queue, you can choose between configuring your queue with agents running in either of these types of infrastructure. +When setting up a queue, you can choose between configuring it with Buidlkite Agents running in either of these types of infrastructure. Learn more about how to set up and create a queue using either self-hosted agents (known as a [self-hosted queue](#create-a-self-hosted-queue)) or Buildkite hosted agents (known as a [Buildkite hosted queue](#create-a-buildkite-hosted-queue)). @@ -28,7 +28,7 @@ Be aware that it is not possible to create a queue that uses a mix of self-hoste ## Create a self-hosted queue -Self-hosted queues use your own infrastructure to run your pipeline builds. New self-hosted queues can be created by a [cluster maintainer](/docs/pipelines/clusters/manage-clusters#manage-maintainers-on-a-cluster) using the [Buildkite interface](#create-a-self-hosted-queue-using-the-buildkite-interface), as well as the [REST API's](#create-a-self-hosted-queue-using-the-rest-api) or [GraphQL API's](#create-a-self-hosted-queue-using-the-graphql-api) create a queue feature. +Self-hosted queues use [Buildkite Agents installed in your own infrastructure](/docs/agent/v3/installation) to run your pipeline builds. New self-hosted queues can be created by a [cluster maintainer](/docs/pipelines/clusters/manage-clusters#manage-maintainers-on-a-cluster) using the [Buildkite interface](#create-a-self-hosted-queue-using-the-buildkite-interface), as well as the [REST API's](#create-a-self-hosted-queue-using-the-rest-api) or [GraphQL API's](#create-a-self-hosted-queue-using-the-graphql-api) create a queue feature. For these API requests, the _cluster ID_ value submitted in the request is the target cluster the queue will be created in. From c4c38add3b1a8ea5cda9980e8393455bed48e75f Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 18 Dec 2024 11:50:18 +1100 Subject: [PATCH 11/22] Fix typo. --- pages/pipelines/clusters/manage_queues.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/pipelines/clusters/manage_queues.md b/pages/pipelines/clusters/manage_queues.md index 54867d4b81..d191301636 100644 --- a/pages/pipelines/clusters/manage_queues.md +++ b/pages/pipelines/clusters/manage_queues.md @@ -20,7 +20,7 @@ Having individual queues according to these breakdowns allows you to scale a set Buildkite provides support for managing [Buildkite Agents](/docs/agent/v3) in your own self-hosted infrastructure, as well as a [Buildkite hosted infrastructure](/docs/pipelines/hosted-agents) for managing these agents. -When setting up a queue, you can choose between configuring it with Buidlkite Agents running in either of these types of infrastructure. +When setting up a queue, you can choose between configuring it with Buildkite Agents running in either of these types of infrastructure. Learn more about how to set up and create a queue using either self-hosted agents (known as a [self-hosted queue](#create-a-self-hosted-queue)) or Buildkite hosted agents (known as a [Buildkite hosted queue](#create-a-buildkite-hosted-queue)). From f1d5148e7bcdcbce722b29432f40c3b0d600b46f Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 18 Dec 2024 14:14:17 +1100 Subject: [PATCH 12/22] More wording tweaks and removal of 'hosted' from REST API calls. --- pages/apis/graphql/graphql_cookbook.md | 1 + pages/apis/rest_api/clusters.md | 15 +++++---------- 2 files changed, 6 insertions(+), 10 deletions(-) diff --git a/pages/apis/graphql/graphql_cookbook.md b/pages/apis/graphql/graphql_cookbook.md index 3f4e9f64cf..a781a881c9 100644 --- a/pages/apis/graphql/graphql_cookbook.md +++ b/pages/apis/graphql/graphql_cookbook.md @@ -12,6 +12,7 @@ There are recipes for a range of different topics, including: - [Builds](/docs/apis/graphql/cookbooks/builds) - [Clusters](/docs/apis/graphql/cookbooks/clusters) - [GitHub rate limits](/docs/apis/graphql/cookbooks/github-rate-limits) +- [Hosted agents](/docs/apis/graphql/cookbooks/hosted-agents) - [Jobs](/docs/apis/graphql/cookbooks/jobs) - [Pipelines](/docs/apis/graphql/cookbooks/pipelines) - [Pipeline templates](/docs/apis/graphql/cookbooks/pipeline-templates) diff --git a/pages/apis/rest_api/clusters.md b/pages/apis/rest_api/clusters.md index 77060c6f22..c383f45acf 100644 --- a/pages/apis/rest_api/clusters.md +++ b/pages/apis/rest_api/clusters.md @@ -466,23 +466,18 @@ Optional [request body properties](/docs/api#request-body-properties):
Instance shape valueInstance shape Size vCPU Memory
- - - @@ -544,7 +539,7 @@ curl -H "Authorization: Bearer $TOKEN" \ diff --git a/pages/pipelines/clusters/manage_queues.md b/pages/pipelines/clusters/manage_queues.md index d191301636..6629a5a315 100644 --- a/pages/pipelines/clusters/manage_queues.md +++ b/pages/pipelines/clusters/manage_queues.md @@ -64,7 +64,6 @@ curl -H "Authorization: Bearer $TOKEN" \ -d '{ "key": "linux_small_amd", "description": "A small self-hosted AMD64 Linux agent.", - "hosted": false }' ``` @@ -78,8 +77,6 @@ where: <%= render_markdown partial: 'apis/descriptions/common_create_queue_fields' %> -- `hosted` (optional) is explicitly set to `false` to ensure that this queue is a self-hosted one that only supports self-hosted agents. If this property is omitted, its value assumed to be `false`. - ### Using the GraphQL API To [create a new self-hosted agent queue](/docs/apis/graphql/schemas/mutation/clusterqueuecreate) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: @@ -92,7 +89,6 @@ mutation { clusterId: "cluster-id" key: "linux_small_amd" description: "A small self-hosted AMD64 Linux agent." - hosted: false } ) { clusterQueue { @@ -101,6 +97,7 @@ mutation { key description dispatchPaused + hosted createdBy { id uuid @@ -123,8 +120,6 @@ where: <%= render_markdown partial: 'apis/descriptions/common_create_queue_fields' %> -- `hosted` (optional) is explicitly set to `false` to ensure that this queue is a self-hosted one that only supports self-hosted agents. If this property is omitted, its value assumed to be `false`. - ## Create a Buildkite hosted queue Buildkite hosted queues use [Buildkite's hosted agent infrastructure](/docs/pipelines/hosted-agents) to run your pipeline builds. New Buildkite hosted queues can be created by a [cluster maintainer](/docs/pipelines/clusters/manage-clusters#manage-maintainers-on-a-cluster) using the [Buildkite interface](#create-a-buildkite-hosted-queue-using-the-buildkite-interface), the [REST API](#create-a-buildkite-hosted-queue-using-the-rest-api), or the [GraphQL API](#create-a-buildkite-hosted-queue-using-the-graphql-api). @@ -161,7 +156,6 @@ curl -H "Authorization: Bearer $TOKEN" \ -d '{ "key": "mac_xlarge_silicon", "description": "Powerful macOS agents running on Apple silicon architecture.", - "hosted": true, "hostedAgents": { "instanceShape": "MACOS_M4_12x56" } @@ -178,9 +172,7 @@ where: <%= render_markdown partial: 'apis/descriptions/common_create_queue_fields' %> -- `hosted` (optional) is explicitly set to `true` to ensure that this queue is a Buildkite hosted one that only supports Buildkite hosted agents. This property can be omitted when the `hostedAgents` property is specified. - -- `hostedAgents` (required) defines the instance shape (within its `instanceShape` object) for this queue's [Linux-](#create-a-buildkite-hosted-queue-instance-shape-values-for-linux) or [Mac-](#create-a-buildkite-hosted-queue-instance-shape-values-for-mac)based Buildkite hosted agent. Specifying `hostedAgents` automatically sets the `hosted` property on this request to `true`, which is why this property can be omitted. For example: +- `hostedAgents` (required) configures this queue to use [Buildkite hosted agents](/docs/pipelines/hosted-agents), which makes this a _Buildkite hosted queue_, and defines the instance shape (within its `instanceShape` object) for this queue's [Linux-](#create-a-buildkite-hosted-queue-instance-shape-values-for-linux) or [Mac-](#create-a-buildkite-hosted-queue-instance-shape-values-for-mac)based Buildkite hosted agent. For example: ```json "hostedAgents": { @@ -200,7 +192,6 @@ mutation { clusterId: "cluster-id" key: "mac_xlarge_silicon" description: "Powerful macOS agents running on Apple silicon architecture." - hosted: true hostedAgents: { instanceShape: MACOS_M4_12x56 } @@ -243,9 +234,7 @@ where: <%= render_markdown partial: 'apis/descriptions/common_create_queue_fields' %> -- `hosted` (optional) is explicitly set to `true` to ensure that this queue is a Buildkite hosted one that only supports Buildkite hosted agents. This property can be omitted when the `hostedAgents` property is specified. - -- `hostedAgents` (required) defines the instance shape (within its `instanceShape` object) for this queue's [Linux-](#create-a-buildkite-hosted-queue-instance-shape-values-for-linux) or [Mac-](#create-a-buildkite-hosted-queue-instance-shape-values-for-mac)based Buildkite hosted agent. Specifying `hostedAgents` automatically sets the `hosted` property on this request to `true`, which is why this property can be omitted. For example: +- `hostedAgents` (required) configures this queue to use [Buildkite hosted agents](/docs/pipelines/hosted-agents), which makes this a _Buildkite hosted queue_, and defines the instance shape (within its `instanceShape` object) for this queue's [Linux-](#create-a-buildkite-hosted-queue-instance-shape-values-for-linux) or [Mac-](#create-a-buildkite-hosted-queue-instance-shape-values-for-mac)based Buildkite hosted agent. For example: ```graphql hostedAgents: { From 608cb4eb1225ca935302e62af6ed29f37be599b8 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 18 Dec 2024 16:30:48 +1100 Subject: [PATCH 14/22] Please the pedantic linter! --- pages/apis/graphql/cookbooks/hosted_agents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/apis/graphql/cookbooks/hosted_agents.md b/pages/apis/graphql/cookbooks/hosted_agents.md index 2bbeff8d71..d91588d968 100644 --- a/pages/apis/graphql/cookbooks/hosted_agents.md +++ b/pages/apis/graphql/cookbooks/hosted_agents.md @@ -95,4 +95,4 @@ Specify the appropriate **Instance shape** for the `instanceShape` value in your 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' %> \ No newline at end of file +<%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> From 3e1d6cc59c20ac1197aee3cd2798c5590d4d8aa2 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 18 Dec 2024 16:39:08 +1100 Subject: [PATCH 15/22] Clarification about changing queue types. --- pages/pipelines/clusters/manage_queues.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pages/pipelines/clusters/manage_queues.md b/pages/pipelines/clusters/manage_queues.md index 6629a5a315..73b40d255d 100644 --- a/pages/pipelines/clusters/manage_queues.md +++ b/pages/pipelines/clusters/manage_queues.md @@ -26,6 +26,8 @@ Learn more about how to set up and create a queue using either self-hosted agent Be aware that it is not possible to create a queue that uses a mix of self-hosted and Buildkite hosted agents. If you do need to use a combination of these different agent types for your pipeline builds, create separate self-hosted and Buildkite hosted queues for these agents and use [agent or queue tags](/docs/agent/v3/queues#setting-an-agents-queue), or a combination of both, to target the appropriate queues. +Furthermore, once a queue has been created, it is not possible to change its type from a self-hosted to a Buildkite hosted queue, or vice versa. If you do need to change your type of agent infrastructure, use a queue with the appropriate hosted queue type, or create a new queue to suit your new agent infrastructure. + ## Create a self-hosted queue Self-hosted queues use [Buildkite Agents installed in your own infrastructure](/docs/agent/v3/installation) to run your pipeline builds. New self-hosted queues can be created by a [cluster maintainer](/docs/pipelines/clusters/manage-clusters#manage-maintainers-on-a-cluster) using the [Buildkite interface](#create-a-self-hosted-queue-using-the-buildkite-interface), as well as the [REST API's](#create-a-self-hosted-queue-using-the-rest-api) or [GraphQL API's](#create-a-self-hosted-queue-using-the-graphql-api) create a queue feature. From 6dc7963999c715d04558b0db371d6007a3d9a788 Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Thu, 19 Dec 2024 15:49:59 +1100 Subject: [PATCH 16/22] Correct instance size for medium linux amd64 --- pages/apis/graphql/cookbooks/hosted_agents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/apis/graphql/cookbooks/hosted_agents.md b/pages/apis/graphql/cookbooks/hosted_agents.md index d91588d968..1e8fdef938 100644 --- a/pages/apis/graphql/cookbooks/hosted_agents.md +++ b/pages/apis/graphql/cookbooks/hosted_agents.md @@ -59,7 +59,7 @@ mutation { organizationId: "organization-id" id: "cluster-queue-id" hostedAgents: { - instanceShape: LINUX_AMD64_4X8 + instanceShape: LINUX_AMD64_4X16 } } ) { From de333741fc59fbd1f37aa34a7f0f6f319670cf7d Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Thu, 19 Dec 2024 15:51:28 +1100 Subject: [PATCH 17/22] Update pages/apis/graphql/cookbooks/hosted_agents.md --- pages/apis/graphql/cookbooks/hosted_agents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/apis/graphql/cookbooks/hosted_agents.md b/pages/apis/graphql/cookbooks/hosted_agents.md index 1e8fdef938..4a4ac4cae3 100644 --- a/pages/apis/graphql/cookbooks/hosted_agents.md +++ b/pages/apis/graphql/cookbooks/hosted_agents.md @@ -46,7 +46,7 @@ mutation { } ``` -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 2 vCPU and 4 GB memory. +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. From 1833a707d25acc36bdddecb5c38d1c974b8df13f Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Thu, 19 Dec 2024 16:17:53 +1100 Subject: [PATCH 18/22] Remove `hosted` from REST API --- pages/apis/rest_api/clusters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/apis/rest_api/clusters.md b/pages/apis/rest_api/clusters.md index de310939c9..bc4765722c 100644 --- a/pages/apis/rest_api/clusters.md +++ b/pages/apis/rest_api/clusters.md @@ -410,7 +410,7 @@ Error responses: 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", "hosted": true, "hostedAgents": { "instanceShape": "LINUX_AMD64_2X4" } }' + -d '{ "key": "default", "description": "Queue of hosted Buildkite agents", "hostedAgents": { "instanceShape": "LINUX_AMD64_2X4" } }' ``` ```json From 354dc1229b9b6cd428c7da98244ea271eac814f7 Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Thu, 19 Dec 2024 16:26:56 +1100 Subject: [PATCH 19/22] Remove un-released fields from example API response. --- pages/apis/rest_api/clusters.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/pages/apis/rest_api/clusters.md b/pages/apis/rest_api/clusters.md index bc4765722c..8adeb76f82 100644 --- a/pages/apis/rest_api/clusters.md +++ b/pages/apis/rest_api/clusters.md @@ -443,11 +443,6 @@ curl -H "Authorization: Bearer $TOKEN" \ "cpu": 2, "memory": 4, "name": "LINUX_AMD64_2X4" - }, - "platform_settings": { - "linux": { - "agent_image_ref": null - } } } } From 8c816e21f286f580f6cb04b8ae0931853ff156c3 Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Thu, 19 Dec 2024 16:32:14 +1100 Subject: [PATCH 20/22] Use small instance sizes for examples They're the only size available for trials. --- pages/pipelines/clusters/manage_queues.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/pages/pipelines/clusters/manage_queues.md b/pages/pipelines/clusters/manage_queues.md index 73b40d255d..8b053ffc0b 100644 --- a/pages/pipelines/clusters/manage_queues.md +++ b/pages/pipelines/clusters/manage_queues.md @@ -156,10 +156,10 @@ 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": "mac_xlarge_silicon", - "description": "Powerful macOS agents running on Apple silicon architecture.", + "key": "mac_small_silicon", + "description": "macOS agents running on Apple silicon architecture.", "hostedAgents": { - "instanceShape": "MACOS_M4_12x56" + "instanceShape": "MACOS_M2_4X7" } }' ``` @@ -192,10 +192,10 @@ mutation { input: { organizationId: "organization-id" clusterId: "cluster-id" - key: "mac_xlarge_silicon" - description: "Powerful macOS agents running on Apple silicon architecture." + key: "mac_small_silicon" + description: "macOS agents running on Apple silicon architecture." hostedAgents: { - instanceShape: MACOS_M4_12x56 + instanceShape: MACOS_M2_4X7 } } ) { @@ -236,7 +236,7 @@ where: <%= render_markdown partial: 'apis/descriptions/common_create_queue_fields' %> -- `hostedAgents` (required) configures this queue to use [Buildkite hosted agents](/docs/pipelines/hosted-agents), which makes this a _Buildkite hosted queue_, and defines the instance shape (within its `instanceShape` object) for this queue's [Linux-](#create-a-buildkite-hosted-queue-instance-shape-values-for-linux) or [Mac-](#create-a-buildkite-hosted-queue-instance-shape-values-for-mac)based Buildkite hosted agent. For example: +- `hostedAgents` (required) configures this queue to use [Buildkite hosted agents](/docs/pipelines/hosted-agents), which makes this a _Buildkite hosted queue_, and defines the instance shape (within its `instanceShape` object) for this queue's [Linux-](#create-a-buildkite-hosted-queue-instance-shape-values-for-linux) or [Mac-](#create-a-buildkite-hosted-queue-instance-shape-values-for-mac) based Buildkite hosted agent. For example: ```graphql hostedAgents: { From af93ea4583b4be1837512783157eb1dba4710f32 Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Thu, 19 Dec 2024 16:36:46 +1100 Subject: [PATCH 21/22] Update pages/pipelines/clusters/manage_queues.md --- pages/pipelines/clusters/manage_queues.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/pipelines/clusters/manage_queues.md b/pages/pipelines/clusters/manage_queues.md index 8b053ffc0b..a8dad7b35f 100644 --- a/pages/pipelines/clusters/manage_queues.md +++ b/pages/pipelines/clusters/manage_queues.md @@ -65,7 +65,7 @@ curl -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "key": "linux_small_amd", - "description": "A small self-hosted AMD64 Linux agent.", + "description": "A small self-hosted AMD64 Linux agent." }' ``` From c68dcb04ed70405f301d5fbbdc8bf4ee6a0b86f4 Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Thu, 19 Dec 2024 16:44:28 +1100 Subject: [PATCH 22/22] Note that extra large instances are available on request only --- pages/pipelines/hosted_agents/linux.md | 2 ++ pages/pipelines/hosted_agents/mac.md | 2 ++ .../hosted_agents/_hosted_agents_instance_shape_table_mac.md | 2 +- 3 files changed, 5 insertions(+), 1 deletion(-) diff --git a/pages/pipelines/hosted_agents/linux.md b/pages/pipelines/hosted_agents/linux.md index 4e77385bfb..e08d1a10e5 100644 --- a/pages/pipelines/hosted_agents/linux.md +++ b/pages/pipelines/hosted_agents/linux.md @@ -13,6 +13,8 @@ Buildkite offers a selection of Linux instance types (each based on a different <%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_linux' %> +Extra large instances are available on request. Please contact support@buildkite.com to have them enabled for your account. + ## Cache volumes _Cache volumes_ are external volumes attached to hosted agent instances. These volumes are attached on a best-effort basis depending on their locality, expiration and current usage, and therefore, should not be relied upon as durable data storage. diff --git a/pages/pipelines/hosted_agents/mac.md b/pages/pipelines/hosted_agents/mac.md index 175341e696..6a8188ade7 100644 --- a/pages/pipelines/hosted_agents/mac.md +++ b/pages/pipelines/hosted_agents/mac.md @@ -10,6 +10,8 @@ Buildkite offers a selection of Mac instance types (each based on a different si <%= render_markdown partial: 'shared/hosted_agents/hosted_agents_instance_shape_table_mac' %> +Extra large instances are available on request. Please contact support@buildkite.com to have them enabled for your account. + ## Mac instances software support The following software will be made available by default on all standard Mac instances during the trial. If you have specific requirements for software that is not listed here, please contact support. diff --git a/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_mac.md b/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_mac.md index 51751425ec..e8fd4dd12a 100644 --- a/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_mac.md +++ b/pages/shared/hosted_agents/_hosted_agents_instance_shape_table_mac.md @@ -32,7 +32,7 @@
descriptionDescription for the queue.
Example: "The default queue for this cluster" -
- hostedConfigure the queue to use Hosted agents.
Example: true -
hostedAgents - Configuration for hosted agents on this queue. + Configures this queue to use Buildkite hosted agents, along with its instance shape. This makes the queue a Buildkite hosted queue.
Example:
{ "instanceShape": "LINUX_AMD64_2X4" } - instanceShape (required): The instance shape to provision hosted agent machines on this queue. +
+ instanceShape (required when hostedAgents is specified): Describes the machine type, architecture, CPU, and RAM to provision for Buildkite hosted agent instances running jobs in this queue.
Learn more about the instance shapes available for Linux and Mac hosted agents.
hostedAgents - Configuration for hosted agents on this queue. + Configures this queue to use Buildkite hosted agents, along with its instance shape. This makes the queue a Buildkite hosted queue.
Example:
@@ -552,7 +547,7 @@ curl -H "Authorization: Bearer $TOKEN" \ { "instanceShape": "LINUX_AMD64_2X4" }
- instanceShape (required): The instance shape describes the machine type, architecture, CPU, and RAM to provision for hosted agent instances running jobs in this queue. + instanceShape (required when hostedAgents is specified): Describes the machine type, architecture, CPU, and RAM to provision for Buildkite hosted agent instances running jobs in this queue.
The architecture (AMD64, ARM64) and machine type (macOS, Linux) of the instance shape must match the existing hosted agents on the queue.
Learn more about the instance shapes available for Linux and Mac Buildkite hosted agents. From 07f36ac44e45c2ba591521cc31aa89b8e44a2b50 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 18 Dec 2024 16:28:08 +1100 Subject: [PATCH 13/22] Remove references to 'hosted' in main manage queues page and review and clarify the API page docs, as well as extending the GraphQL cookbook page. --- pages/apis/graphql/cookbooks/hosted_agents.md | 28 +++++++++++++++---- pages/apis/rest_api/clusters.md | 2 +- pages/pipelines/clusters/manage_queues.md | 17 ++--------- 3 files changed, 27 insertions(+), 20 deletions(-) diff --git a/pages/apis/graphql/cookbooks/hosted_agents.md b/pages/apis/graphql/cookbooks/hosted_agents.md index 9b6632670b..2bbeff8d71 100644 --- a/pages/apis/graphql/cookbooks/hosted_agents.md +++ b/pages/apis/graphql/cookbooks/hosted_agents.md @@ -2,7 +2,7 @@ A collection of common tasks with [Hosted agents](/docs/pipelines/hosted-agents) using the GraphQL API. -## Creating a hosted cluster queue +## Create a Buildkite hosted queue ```graphql mutation { @@ -12,7 +12,6 @@ mutation { clusterId: "cluster-id" key: "hosted_linux_small" description: "Small AMD64 Linux agents hosted by Buildkite." - hosted: true hostedAgents: { instanceShape: LINUX_AMD64_2X4 } @@ -47,9 +46,11 @@ mutation { } ``` -Create a small AMD64 Linux hosted agent cluster queue, which is hosted by Buildkite. 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 2 vCPU and 4 GB memory. +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 2 vCPU and 4 GB memory. -## Changing the instance shape of a hosted agent cluster 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. + +## Change the instance shape of a Buildkite hosted queue's agents ```graphql mutation { @@ -77,4 +78,21 @@ mutation { } ``` -To increase the size of the agent instances for a hosted agent cluster queue, update the `instanceShape` value to `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 a hosted queue. +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' %> \ No newline at end of file diff --git a/pages/apis/rest_api/clusters.md b/pages/apis/rest_api/clusters.md index c383f45acf..de310939c9 100644 --- a/pages/apis/rest_api/clusters.md +++ b/pages/apis/rest_api/clusters.md @@ -549,7 +549,7 @@ curl -H "Authorization: Bearer $TOKEN" \
instanceShape (required when hostedAgents is specified): Describes the machine type, architecture, CPU, and RAM to provision for Buildkite hosted agent instances running jobs in this queue.
- The architecture (AMD64, ARM64) and machine type (macOS, Linux) of the instance shape must match the existing hosted agents on the queue.
+ 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).
Learn more about the instance shapes available for Linux and Mac Buildkite hosted agents.
- MACOS_M4_12x56 + MACOS_M4_12X56 Extra Large 12