Skip to content

G
gitlab-ce
Commit 3ca9f3e7 authored by Pedro Pombeiro's avatar Pedro Pombeiro
Browse files
Options

REST API: Deprecate ‘active’ property for Runners 

Changelog: deprecated
parent bf33d5e5
Hide whitespace changes
Inline Side-by-side
Showing with 144 additions and 45 deletions
data/deprecations/14-5-runner-api-status-does-contain-paused.yml
View file @ 3ca9f3e7
......@@ -11,7 +11,7 @@
`online`, `offline`, or `not_connected`. Status `paused` or `active` will no longer appear.
When checking if a runner is `paused`, API users are advised to check the boolean attribute
`active` to be `false` instead. When checking if a runner is `active`, check if `active` is `true`.
`paused` to be `true` instead. When checking if a runner is `active`, check if `paused` is `false`.
stage: Verify
tiers: [Core, Premium, Ultimate]
issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/344648
......
doc/api/runners.md
View file @ 3ca9f3e7
......@@ -54,12 +54,17 @@ GET /runners?tag_list=tag1,tag2
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
```
NOTE:
The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211).
and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
Example response:
```json
[
{
"active": true,
"paused": false,
"description": "test-1-20150125",
"id": 6,
"ip_address": "127.0.0.1",
......@@ -71,6 +76,7 @@ Example response:
},
{
"active": true,
"paused": false,
"description": "test-2-20150125",
"id": 8,
"ip_address": "127.0.0.1",
......@@ -107,12 +113,17 @@ GET /runners/all?tag_list=tag1,tag2
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"
```
NOTE:
The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211).
and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
Example response:
```json
[
{
"active": true,
"paused": false,
"description": "shared-runner-1",
"id": 1,
"ip_address": "127.0.0.1",
......@@ -124,6 +135,7 @@ Example response:
},
{
"active": true,
"paused": false,
"description": "shared-runner-2",
"id": 3,
"ip_address": "127.0.0.1",
......@@ -135,6 +147,7 @@ Example response:
},
{
"active": true,
"paused": false,
"description": "test-1-20150125",
"id": 6,
"ip_address": "127.0.0.1",
......@@ -146,6 +159,7 @@ Example response:
},
{
"active": true,
"paused": false,
"description": "test-2-20150125",
"id": 8,
"ip_address": "127.0.0.1",
......@@ -185,11 +199,16 @@ NOTE:
The `token` attribute in the response was deprecated [in GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/214320).
and removed in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/214322).
NOTE:
The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211).
and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
Example response:
```json
{
"active": true,
"paused": false,
"architecture": null,
"description": "test-1-20150125",
"id": 6,
......@@ -229,16 +248,17 @@ Update details of a runner.
PUT /runners/:id
```
| Attribute | Type | Required | Description |
|---------------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a runner |
| `description` | string | no | The description of a runner |
| `active` | boolean | no | The state of a runner; can be set to `true` or `false` |
| `tag_list` | array | no | The list of tags for a runner; put array of tags, that should be finally assigned to a runner |
| `run_untagged`| boolean | no | Flag indicating the runner can execute untagged jobs |
| `locked` | boolean | no | Flag indicating the runner is locked |
| `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` |
| `maximum_timeout` | integer | no | Maximum timeout set when this runner handles the job |
| Attribute | Type | Required | Description |
|-------------------|---------|----------|--------------------------------------------------------------------------------------------------|
| `id` | integer | yes | The ID of a runner |
| `description` | string | no | The description of a runner |
| `active` | boolean | no | Deprecated: Use `:paused` instead. Flag indicating whether the runner is allowed to receive jobs |
| `paused` | boolean | no | Flag indicating whether the runner should ignore new jobs |
| `tag_list` | array | no | The list of tags for a runner; put array of tags, that should be finally assigned to a runner |
| `run_untagged` | boolean | no | Flag indicating the runner can execute untagged jobs |
| `locked` | boolean | no | Flag indicating the runner is locked |
| `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` |
| `maximum_timeout` | integer | no | Maximum timeout set when this runner handles the job |
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" \
......@@ -249,6 +269,10 @@ NOTE:
The `token` attribute in the response was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/214320) in GitLab 12.10.
and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/214322) in GitLab 13.0.
NOTE:
The `active` query parameter was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211).
and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
Example response:
```json
......@@ -292,7 +316,12 @@ Example response:
Pause a specific runner.
```plaintext
PUT --form "active=false" /runners/:runner_id
PUT --form "paused=true" /runners/:runner_id
# --or--
# Deprecated: removal planned in 15.0
PUT --form "active=false" /runners/:runner_id
```
| Attribute | Type | Required | Description |
......@@ -300,10 +329,20 @@ PUT --form "active=false" /runners/:runner_id
| `runner_id` | integer | yes | The ID of a runner |
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--form "paused=true" "https://gitlab.example.com/api/v4/runners/6"
# --or--
# Deprecated: removal planned in 15.0
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--form "active=false" "https://gitlab.example.com/api/v4/runners/6"
```
NOTE:
The `active` form attribute was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211).
and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
## List runner's jobs
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15432) in GitLab 10.3.
......@@ -420,12 +459,17 @@ GET /projects/:id/runners?tag_list=tag1,tag2
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners"
```
NOTE:
The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211).
and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
Example response:
```json
[
{
"active": true,
"paused": false,
"description": "test-2-20150125",
"id": 8,
"ip_address": "127.0.0.1",
......@@ -437,6 +481,7 @@ Example response:
},
{
"active": true,
"paused": false,
"description": "development_runner",
"id": 5,
"ip_address": "127.0.0.1",
......@@ -444,7 +489,7 @@ Example response:
"runner_type": "instance_type",
"name": null,
"online": true,
"status": "paused"
"status": "online"
}
]
```
......@@ -525,6 +570,10 @@ GET /groups/:id/runners?tag_list=tag1,tag2
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/9/runners"
```
NOTE:
The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211).
and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
Example response:
```json
......@@ -534,6 +583,7 @@ Example response:
"description": "Shared",
"ip_address": "127.0.0.1",
"active": true,
"paused": false,
"is_shared": true,
"runner_type": "instance_type",
"name": "gitlab-runner",
......@@ -545,6 +595,7 @@ Example response:
"description": "Test",
"ip_address": "127.0.0.1",
"active": true,
"paused": false,
"is_shared": true,
"runner_type": "instance_type",
"name": "gitlab-runner",
......@@ -556,6 +607,7 @@ Example response:
"description": "Test 2",
"ip_address": "127.0.0.1",
"active": true,
"paused": false,
"is_shared": false,
"runner_type": "group_type",
"name": "gitlab-runner",
......@@ -573,19 +625,20 @@ Register a new runner for the instance.
POST /runners
```
| Attribute | Type | Required | Description |
|--------------------|--------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `token` | string | yes | [Registration token](#registration-and-authentication-tokens). |
| `description` | string | no | Runner's description |
| `info` | hash | no | Runner's metadata. You can include `name`, `version`, `revision`, `platform`, and `architecture`, but only `version` is displayed in the Admin area of the UI. |
| `active` | boolean | no | Whether the runner is active |
| `locked` | boolean | no | Whether the runner should be locked for current project |
| `run_untagged` | boolean | no | Whether the runner should handle untagged jobs |
| `tag_list` | string array | no | List of runner's tags |
| `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` |
| `maximum_timeout` | integer | no | Maximum timeout set when this runner handles the job |
| `maintainer_note` | string | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/350730), see `maintenance_note`. |
| `maintenance_note` | string | no | Free-form maintenance notes for the runner (255 characters) |
| Attribute | Type | Required | Description |
|--------------------|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `token` | string | yes | [Registration token](#registration-and-authentication-tokens) |
| `description` | string | no | Runner's description |
| `info` | hash | no | Runner's metadata. You can include `name`, `version`, `revision`, `platform`, and `architecture`, but only `version` is displayed in the Admin area of the UI |
| `active` | boolean | no | Deprecated: Use `:paused` instead. Whether the runner is allowed to receive jobs |
| `paused` | boolean | no | Whether the runner should ignore new jobs |
| `locked` | boolean | no | Whether the runner should be locked for current project |
| `run_untagged` | boolean | no | Whether the runner should handle untagged jobs |
| `tag_list` | string array | no | List of runner's tags |
| `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` |
| `maximum_timeout` | integer | no | Maximum timeout set when this runner handles the job |
| `maintainer_note` | string | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/350730), see `maintenance_note` |
| `maintenance_note` | string | no | Free-form maintenance notes for the runner (255 characters) |
```shell
curl --request POST "https://gitlab.example.com/api/v4/runners" \
......
doc/update/deprecations.md
View file @ 3ca9f3e7
......@@ -240,7 +240,7 @@ A runner's status will only relate to runner contact status, such as:
`online`, `offline`, or `not_connected`. Status `paused` or `active` will no longer appear.
When checking if a runner is `paused`, API users are advised to check the boolean attribute
`active` to be `false` instead. When checking if a runner is `active`, check if `active` is `true`.
`paused` to be `true` instead. When checking if a runner is `active`, check if `paused` is `false`.
**Planned removal milestone: 15.0 (2022-05-22)**
......
lib/api/ci/runner.rb
View file @ 3ca9f3e7
......@@ -18,21 +18,25 @@ module API
optional :maintainer_note, type: String, desc: %q(Deprecated: Use :maintenance_note instead. Runner's maintenance notes)
optional :maintenance_note, type: String, desc: %q(Runner's maintenance notes)
optional :info, type: Hash, desc: %q(Runner's metadata)
optional :active, type: Boolean, desc: 'Should Runner be active'
optional :locked, type: Boolean, desc: 'Should Runner be locked for current project'
optional :active, type: Boolean, desc: 'Deprecated: Use `:paused` instead. Should runner be active'
optional :paused, type: Boolean, desc: 'Whether the runner should ignore new jobs'
optional :locked, type: Boolean, desc: 'Whether the runner should be locked for current project'
optional :access_level, type: String, values: ::Ci::Runner.access_levels.keys,
desc: 'The access_level of the runner'
optional :run_untagged, type: Boolean, desc: 'Should Runner handle untagged jobs'
desc: 'The access_level of the runner; `not_protected` or `ref_protected`'
optional :run_untagged, type: Boolean, desc: 'Whether the runner should handle untagged jobs'
optional :tag_list, type: Array[String], coerce_with: ::API::Validations::Types::CommaSeparatedToArray.coerce, desc: %q(List of Runner's tags)
optional :maximum_timeout, type: Integer, desc: 'Maximum timeout set when this Runner will handle the job'
optional :maximum_timeout, type: Integer, desc: 'Maximum timeout set when this runner handles the job'
mutually_exclusive :maintainer_note, :maintainer_note
mutually_exclusive :active, :paused
end
post '/', feature_category: :runner do
attributes = attributes_for_keys(%i[description maintainer_note maintenance_note active locked run_untagged tag_list access_level maximum_timeout])
attributes = attributes_for_keys(%i[description maintainer_note maintenance_note active paused locked run_untagged tag_list access_level maximum_timeout])
.merge(get_runner_details_from_request)
# Pull in deprecated maintainer_note if that's the only note value available
deprecated_note = attributes.delete(:maintainer_note)
attributes[:maintenance_note] ||= deprecated_note if deprecated_note
attributes[:active] = !attributes.delete(:paused) if attributes.include?(:paused)
@runner = ::Ci::RegisterRunnerService.new.execute(params[:token], attributes)
forbidden! unless @runner
......
lib/api/ci/runners.rb
View file @ 3ca9f3e7
......@@ -77,18 +77,21 @@ module API
params do
requires :id, type: Integer, desc: 'The ID of the runner'
optional :description, type: String, desc: 'The description of the runner'
optional :active, type: Boolean, desc: 'The state of a runner'
optional :active, type: Boolean, desc: 'Deprecated: Use `:paused` instead. Flag indicating whether the runner is allowed to receive jobs'
optional :paused, type: Boolean, desc: 'Flag indicating whether the runner should ignore new jobs'
optional :tag_list, type: Array[String], coerce_with: ::API::Validations::Types::CommaSeparatedToArray.coerce, desc: 'The list of tags for a runner'
optional :run_untagged, type: Boolean, desc: 'Flag indicating the runner can execute untagged jobs'
optional :run_untagged, type: Boolean, desc: 'Flag indicating whether the runner can execute untagged jobs'
optional :locked, type: Boolean, desc: 'Flag indicating the runner is locked'
optional :access_level, type: String, values: ::Ci::Runner.access_levels.keys,
desc: 'The access_level of the runner'
optional :maximum_timeout, type: Integer, desc: 'Maximum timeout set when this Runner will handle the job'
at_least_one_of :description, :active, :tag_list, :run_untagged, :locked, :access_level, :maximum_timeout
at_least_one_of :description, :active, :paused, :tag_list, :run_untagged, :locked, :access_level, :maximum_timeout
mutually_exclusive :active, :paused
end
put ':id' do
runner = get_runner(params.delete(:id))
authenticate_update_runner!(runner)
params[:active] = !params.delete(:paused) if params.include?(:paused)
update_service = ::Ci::UpdateRunnerService.new(runner)
if update_service.update(declared_params(include_missing: false))
......
lib/api/entities/ci/runner.rb
View file @ 3ca9f3e7
......@@ -7,7 +7,10 @@ module API
expose :id
expose :description
expose :ip_address
expose :active
expose :active # TODO Remove in %15.0 in favor of `paused` for REST calls, see https://gitlab.com/gitlab-org/gitlab/-/issues/351109
expose :paused do |runner|
!runner.active
end
expose :instance_type?, as: :is_shared
expose :runner_type
expose :name
......
spec/requests/api/ci/runner/runners_post_spec.rb
View file @ 3ca9f3e7
......@@ -34,7 +34,7 @@ RSpec.describe API::Ci::Runner, :clean_gitlab_redis_shared_state do
run_untagged: false,
tag_list: 'tag1, tag2',
locked: true,
active: true,
paused: false,
access_level: 'ref_protected',
maximum_timeout: 9000
}
......@@ -55,7 +55,7 @@ RSpec.describe API::Ci::Runner, :clean_gitlab_redis_shared_state do
maximum_timeout: 9000
}.stringify_keys
allow(service).to receive(:execute)
expect(service).to receive(:execute)
.once
.with('valid token', a_hash_including(expected_params))
.and_return(new_runner)
......@@ -108,6 +108,32 @@ RSpec.describe API::Ci::Runner, :clean_gitlab_redis_shared_state do
end
end
context 'when deprecated active parameter is provided' do
def request
post api('/runners'), params: {
token: 'valid token',
active: false
}
end
let_it_be(:new_runner) { create(:ci_runner) }
it 'uses active value in registration' do
expect_next_instance_of(::Ci::RegisterRunnerService) do |service|
expected_params = { active: false }.stringify_keys
expect(service).to receive(:execute)
.once
.with('valid token', a_hash_including(expected_params))
.and_return(new_runner)
end
request
expect(response).to have_gitlab_http_status(:created)
end
end
context 'calling actual register service' do
include StubGitlabCalls
......
spec/requests/api/ci/runners_spec.rb
View file @ 3ca9f3e7
......@@ -109,7 +109,7 @@ RSpec.describe API::Ci::Runners do
get api('/runners?tag_list=tag1,tag2', user)
expect(json_response).to match_array [
a_hash_including('description' => 'Runner tagged with tag1 and tag2')
a_hash_including('description' => 'Runner tagged with tag1 and tag2', 'active' => true, 'paused' => false)
]
end
end
......@@ -137,7 +137,7 @@ RSpec.describe API::Ci::Runners do
get api('/runners/all', admin)
expect(json_response).to match_array [
a_hash_including('description' => 'Project runner', 'is_shared' => false, 'runner_type' => 'project_type'),
a_hash_including('description' => 'Project runner', 'is_shared' => false, 'active' => true, 'paused' => false, 'runner_type' => 'project_type'),
a_hash_including('description' => 'Two projects runner', 'is_shared' => false, 'runner_type' => 'project_type'),
a_hash_including('description' => 'Group runner A', 'is_shared' => false, 'runner_type' => 'group_type'),
a_hash_including('description' => 'Group runner B', 'is_shared' => false, 'runner_type' => 'group_type'),
......@@ -255,6 +255,8 @@ RSpec.describe API::Ci::Runners do
expect(json_response['description']).to eq(shared_runner.description)
expect(json_response['maximum_timeout']).to be_nil
expect(json_response['status']).to eq("not_connected")
expect(json_response['active']).to eq(true)
expect(json_response['paused']).to eq(false)
end
end
......@@ -359,6 +361,14 @@ RSpec.describe API::Ci::Runners do
expect(shared_runner.reload.active).to eq(!active)
end
it 'runner paused state' do
active = shared_runner.active
update_runner(shared_runner.id, admin, paused: active)
expect(response).to have_gitlab_http_status(:ok)
expect(shared_runner.reload.active).to eq(!active)
end
it 'runner tag list' do
update_runner(shared_runner.id, admin, tag_list: ['ruby2.1', 'pgsql', 'mysql'])
......@@ -908,9 +918,9 @@ RSpec.describe API::Ci::Runners do
get api("/projects/#{project.id}/runners", user)
expect(json_response).to match_array [
a_hash_including('description' => 'Project runner'),
a_hash_including('description' => 'Two projects runner'),
a_hash_including('description' => 'Shared runner')
a_hash_including('description' => 'Project runner', 'active' => true, 'paused' => false),
a_hash_including('description' => 'Two projects runner', 'active' => true, 'paused' => false),
a_hash_including('description' => 'Shared runner', 'active' => true, 'paused' => false)
]
end
......@@ -986,7 +996,7 @@ RSpec.describe API::Ci::Runners do
get api("/groups/#{group.id}/runners", user)
expect(json_response).to match_array([
a_hash_including('description' => 'Group runner A')
a_hash_including('description' => 'Group runner A', 'active' => true, 'paused' => false)
])
end
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7