Skip to content
Yagra

Turn acceptance of remote-site pollers on or off.

PUT
/api/v1/settings/bus/remote
curl --request PUT \
  --url https://example.com/api/v1/settings/bus/remote \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "enabled": true, "names": [ "example" ] }'

The bus, this core and the co-located poller are all recreated, so monitoring stops for as long as that takes. A fleet-wide maintenance window is opened first.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Turn acceptance of remote-site pollers on or off.

object
enabled
required

true encrypts and authenticates the bus and publishes its port; false returns it to the internal-only plaintext bus and stops every remote poller from connecting.

boolean
names

Hostnames and IP addresses remote pollers will dial. Used to reissue the certificate before the bus restarts, so the names are already right when it comes back. Ignored when disabling.

Array<string>
Examplegenerated
{
  "enabled": true,
  "names": [
    "example"
  ]
}

Responses

Section titled “Responses”

202

Section titled “202”

Accepted; the bus is being recreated and this core will restart

Media typeapplication/json

What the switch returns. The poller secret appears once.

object
ca_certificate

The certificate a remote poller must pin as its YAGRA_BUS_CA_FILE, in PEM. null when disabling.

string | null
id
required

Identifier for this change, matching the run reported by the upgrade status endpoint.

string
maintenance_window_id

The fleet-wide maintenance window opened for the duration, or null if one could not be opened. Monitoring stops for as long as the bus is being recreated.

string | null
poller_secret

The bootstrap secret a remote poller presents when it connects, shown once. Store it now — it is written into the deployment’s environment and is never returned again.

string | null
Examplegenerated
{
  "ca_certificate": "example",
  "id": "example",
  "maintenance_window_id": "example",
  "poller_secret": "example"
}

400

Section titled “400”

Enabling without an address remote pollers can dial

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

401

Section titled “401”

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Section titled “403”

Role lacks ManageSystem

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

409

Section titled “409”

An upgrade or another bus change is already running

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Section titled “503”

No updater is deployed, or it is switched off

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}