Skip to content

Commit

Permalink
docs(nx-cloud): clean up assignment rules docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@lourw
lourw committed Jan 16, 2025
1 parent 3ec949e commit 66e357b
Showing 1 changed file with 42 additions and 23 deletions.
65 changes: 42 additions & 23 deletions docs/nx-cloud/reference/assignment-rules.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Assignment Rules (beta)

Assignment rules allow you to control which tasks can run on which agents. Save on agent costs by provisioning different sizes of agents all with the confidence that your tasks will be run on the agents that are best suited for them. You can ensure resource intensive targets like `e2e-ci` and `build` have what they need by using larger agents. Lighter tasks like `lint` and `test` can run on smaller agents.
Assignment rules allow you to control which tasks can run on which agents. Save on agent costs by provisioning different sizes of agents to suite the individual needs of your tasks. You can ensure resource intensive targets like `e2e-ci` and `build` have what they need by using larger agents. Lighter tasks like `lint` and `test` can run on smaller agents.

Assignment rules are defined in `yaml` files within your workspace's `.nx/workflows` directory. You can use assignment rules with self-hosted agents or with [dynamic Nx agents](/ci/features/dynamic-agents). Note that the additional configuration is required when using self-hosted agents.
Assignment rules are defined in `yaml` files within your workspace's `.nx/workflows` directory. You can use assignment rules with self-hosted agents or with [dynamic Nx agents](/ci/features/dynamic-agents). Note that additional configuration is required when using self-hosted agents.

## How to Define an Assignment Rule

Expand All @@ -14,17 +14,22 @@ assignment-rules:
target: build
configuration: production
runs-on:
- linux-large-js
- linux-medium-js
- linux-large-js
```
The above rule will match any task that has a project named `app1`, a target named `build`, and a configuration named `production`. Any tasks that match this rule will only be allowed to run on agents with the `linux-large-js` and `linux-medium-js` launch templates.

You can mix and match any of the criteria in an assignment rule provided that you follow the constraints:

- At least one of the following properties is defined: `project`, `target`, `configuration`.
- There is at least one [agent type](/ci/reference/launch-templates) specified in the `run-on` field.
- Every changeset in your `distribute-on` field must include at **least one agent** that matches each agent type specified in the run-on field across all assignment rules. For example, if your rules distribute tasks on `linux-small-js`, `linux-medium-js`, and `linux-large-js`, then at least one agent of each type must be available; otherwise, tasks associated with those rules cannot be executed.
- There is at least one [agent type](/ci/reference/launch-templates) specified in the `runs-on` field.
- Every changeset in your `distribute-on` field must include at **least one agent** that matches each agent type specified in the `runs-on` field across all assignment rules. For example, if your rules distribute tasks on `linux-small-js`, `linux-medium-js`, and `linux-large-js`, then at least one agent of each type must be available; otherwise, tasks associated with those rules cannot be executed.

{% callout type="note" title="If you are using self-hosted agents, you must define your own agent types" %}
You can define your own agent types and attach them to your self-hosted agents using the `NX_AGENT_LAUNCH_TEMPLATE` environment variable. Ensure that for each `runs-on` field in your assignment rules, you have corresponding agents in your agent pool that have the same agent type.
See below for an [example](#using-assignment-rules-with-selfhosted-agents) of how to define your own agent types when using self-hosted agents.
{% /callout %}

## Assignment Rule Precedence

Expand All @@ -42,7 +47,7 @@ Having multiple assignment rules means that often rules may overlap or apply to

### Rule Precedence Example

In this example, the task defined below can match multiple assignment rules. However, since the second rule specifies all three properties (`project`, `target`, and `configuration`) rather than just two (`project` and `target`), it takes precedence, and we apply the second rule when distributing the task.
In this example, the task defined below can match multiple assignment rules. However, since the second rule specifies all three properties (`project`, `target`, and `configuration`) rather than just two (`project` and `target`), it takes precedence, and we automatically apply the second rule when distributing the task.

```json {% fileName="A task from your workspace" %}
{
Expand All @@ -54,6 +59,7 @@ In this example, the task defined below can match multiple assignment rules. How

```yaml {% fileName=".nx/workflows/distribution-config.yaml" %}
assignment-rules:
# A task for app1:build:production will use this rule because it is more specific (matches all three properties instead of just two)
- project: app1
target: build
configuration: production
Expand All @@ -76,8 +82,8 @@ assignment-rules:
target: build
configuration: production
runs-on:
- linux-large
- linux-medium
- linux-large
- target: lint
runs-on:
Expand All @@ -89,26 +95,29 @@ assignment-rules:
- linux-large
```

Note that the labels supplied in the `runs-ons` property will be used to determine which agents will have rules applied to them. When using self-hosted agents, you must supply these labels to your agents via an environment variable: `NX_AGENT_LAUNCH_TEMPLATE`.
Note that the agent types supplied in the `runs-ons` property will be used to determine which agents will have rules applied to them.
You can choose to name your agent types anything you want, but they must be set on your agents via the `NX_AGENT_LAUNCH_TEMPLATE` environment variable.

You can then reference your assignment rules file within your `start-ci-run` command:

```shell
npx nx-cloud start-ci-run --assignment-rules=".nx/workflows/assignment-rules.yaml"
npx nx-cloud start-ci-run --distribute-on="manual" --assignment-rules=".nx/workflows/assignment-rules.yaml"
```

The following is an example of what this looks like within a github actions pipeline:
The following is an example of what this looks like within a Github Actions pipeline:

```yaml {% fileName=".github/workflows/ci.yaml" %}
...
---
jobs:
main:
name: Main Job
...
runs-on: ubuntu-latest
steps:
...
- run: npx nx-cloud start-ci-run --assignment-rules=".nx/workflows/assignment-rules.yaml" --stop-agents-after="e2e-ci"
- ..
- ... # setup steps for your main job
- run: npx nx-cloud start-ci-run --distribute-on="manual" --assignment-rules=".nx/workflows/assignment-rules.yaml" --stop-agents-after="e2e-ci"
- ... # Nx commands you want to distribute
medium-agents:
name: Agents ${{ matrix.agent }}
Expand All @@ -121,16 +130,21 @@ jobs:
- name: Checkout
uses: actions/checkout@v4
- name: Install dependencies
run: npm ci
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'npm'
...
- ... # other setup steps you may need
- name: Install dependencies
run: npm ci --legacy-peer-deps
- name: Start Agent ${{ matrix.agent }}
run: npx nx-cloud start-agent
env:
NX_AGENT_NAME: ${{ matrix.agent }}
NX_AGENT_LAUNCH_TEMPLATE: "linux-medium" # This value needs to match one of the 'runs-on' values defined in the assignment rules
NX_AGENT_LAUNCH_TEMPLATE: 'linux-medium' # This value needs to match one of the 'runs-on' values defined in the assignment rules
large-agents:
name: Agents ${{ matrix.agent }}
Expand All @@ -144,16 +158,21 @@ jobs:
- name: Checkout
uses: actions/checkout@v4
- name: Install dependencies
run: npm ci
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'npm'
... # other setup steps
- ... # other setup steps you may need
- name: Install dependencies
run: npm ci --legacy-peer-deps
- name: Start Agent ${{ matrix.agent }}
run: npx nx-cloud start-agent
env:
NX_AGENT_NAME: ${{ matrix.agent }}
NX_AGENT_LAUNCH_TEMPLATE: "linux-large" # This value needs to match one of the 'runs-on' values defined in the assignment rules
NX_AGENT_LAUNCH_TEMPLATE: 'linux-large' # This value needs to match one of the 'runs-on' values defined in the assignment rules
```

## Using Assignment Rules with Dynamic Nx Agents
Expand Down

0 comments on commit 66e357b

Please sign in to comment.