Skip to content
StratumStratum Docs

Deploy the Ceph RADOS Gateway — S3 object storage (bootstrap-admin).

POST
/v1/admin/storage/ceph/rgw
Code sample: Shell / cURL
curl --request POST \
  --url https://stratum.example.com/v1/admin/storage/ceph/rgw \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "enabled": true, "serviceId": "example", "placementCount": 1, "frontendPort": 1 }'

Records the desired RADOS Gateway (S3 object storage) state on the existing Ceph cluster and returns 202; the reconciler runs ceph orch apply rgw asynchronously (a stateless cephadm daemon — no host-root). RGW auto-creates its default realm/zonegroup/zone + pools on first start (single region at v1). Deploying requires a Ceph cluster that exists (exists on GET…/ceph/cluster): before that, or over a failed bootstrap, it is 409. Turning it off (enabled:false) is always accepted. Idempotent — re-requesting updates the desired counts. Install-scope; gates on storage:ManageCephRGW.

Authorizations

Section titled “Authorizations”

Request Body

Section titled “Request Body”
Media typeapplication/json

Deploy (or update) the RADOS Gateway (S3 object storage) on the existing Ceph cluster. All fields optional; enabled defaults to true.

object
enabled

Deploy RGW when true; record disabled desired state when false. Default true.

boolean
serviceId

Cephadm rgw service name (short alphanumeric/hyphen); empty = ‘stratum’.

string
placementCount

Radosgw daemon count; 0 = default to the mon count.

integer
frontendPort

Radosgw beast frontend port; 0 = default 7480.

integer

Example generated

{
  "enabled": true,
  "serviceId": "example",
  "placementCount": 1,
  "frontendPort": 1
}

Responses

Section titled “Responses”

202

Section titled “202”

RGW deploy requested; desired state recorded.

Media typeapplication/json

Desired + observed Ceph cluster. configured=false before any bootstrap. exists, bootstrapFailed and rgwDeployed are the platform’s own answers, derived from the observed status, never from the desired row.

object
configured
required
boolean
desired

The operator’s desired Ceph cluster (singleton).

object
desiredEnabled
required
boolean
image
required
string
publicNetwork
string
clusterNetwork
string
monCount
required
integer
mgrCount
required
integer
pgNum
integer
osdDeviceSelector

“” = the members’ hardware-plan ceph-osd disks | all-available | model: | size:. What it resolves to is the view’s osdSelection.

string
osdPaths
Array<object>

One host’s explicit OSD device contribution.

object
host
required

Cephadm hostname (as reported by GET /ceph/hosts).

string
devices
required

Absolute /dev paths on that host to consume as OSDs.

Array<string>
rgwEnabled

Desired RADOS Gateway (S3 object storage) deployment. When true, the reconciler runs ceph orch apply rgw.

boolean
rgwServiceId

Cephadm rgw service name; empty = ‘stratum’.

string
rgwPlacementCount

Radosgw daemon count; 0 = default to mon count.

integer
rgwFrontendPort

Radosgw beast frontend port; 0 = default 7480.

integer
placement

The per-daemon-kind placement in effect, keyed by kind. Absent means bare counts: cephadm’s scheduler chooses the hosts.

object
key
additional properties

Where one Ceph daemon kind may run.

Set exactly one of hosts or label. Both empty is rejected rather than treated as “anywhere”: an empty entry would render as a bare count, which is the opposite of what asking for a placement means.

The daemon COUNT still comes from monCount / mgrCount and is combined with this constraint, so a label matching five hosts still yields mgrCount managers rather than five.

object
hosts

Explicit cephadm host names. Validated against the enrolled member set — an unknown name is a 400, because cephadm itself accepts one and then simply never schedules the daemon, which is indistinguishable from “still converging”.

Array<string>
label

Cephadm host label to place on (ceph orch host label add <host> <label>). Mutually exclusive with hosts.

string
createdAt
string format: date-time
updatedAt
string format: date-time
createdBy
string
status

The reconciler’s observed Ceph cluster state (singleton).

object
fsid
string
phase
required
string
Allowed values: unconfigured bootstrapping ready degraded error tearing-down
health
string
message
string
reportedAt
string format: date-time
reportedBy

The control plane (node id) that wrote this status.

string
rgwDaemonsRunning

The radosgw daemons the reconciler observed running at its last probe. Absent when not observed (no cluster answered, or the gateway listing failed): unknown, not zero.

integer
exists
required

A Ceph cluster runs, as last observed: an fsid, and a cluster that answered (phase ready or degraded, or error from a converge step on a cluster that answered). What S3, readiness and the RGW deploy act on.

boolean
bootstrapFailed
required

A requested bootstrap failed before any cluster existed (phase error, no fsid). Readiness raises CephBootstrapFailed and the ceph-bootstrap-failed alarm fires on it. Request the bootstrap again to retry.

boolean
rgwDeployed

The object gateway is deployed: the cluster exists, RGW is requested, and a radosgw daemon was observed running. Absent while unknown.

boolean
osdSelection

The disks the reconciler makes OSDs, and where they come from: the same selection it converges. Absent before any bootstrap request.

object
source
required

Hardware-plan: each member’s ceph-osd disks (the default); osd-paths: the request’s osdPaths; all-available: every blank disk, asked for by name; selector: a model:/size: filter on every host.

string
Allowed values: hardware-plan osd-paths all-available selector
selector

The model:/size: filter, for source selector.

string
paths
required

The per-host devices the OSD services name, for the hardware-plan and osd-paths sources (empty for the others). A member with no ceph-osd disk, or whose plan could not be read, has no entry.

Array<object>

One host’s explicit OSD device contribution.

object
host
required

Cephadm hostname (as reported by GET /ceph/hosts).

string
devices
required

Absolute /dev paths on that host to consume as OSDs.

Array<string>
refused

OsdPaths devices left out because the hardware plan gives the disk another role, as “host:device: role”.

Array<string>
bootstrapNode

The node that holds the bootstrap claim: the one node that runs cephadm bootstrap for this request. Absent before a reconcile pass has claimed it and after a teardown. It moves to another node only on a new request while it is not active.

string

Example 

{
  "status": {
    "phase": "unconfigured"
  },
  "osdSelection": {
    "source": "hardware-plan"
  }
}

400

Section titled “400”

Bad request.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
string
instance
string format: uri-reference
requestId
required
string
code
required
string
issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object
code
required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string
statement
required

Index of the statement at fault; -1 for the document as a whole.

integer
>= -1
detail
required
string
action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string
errors

Field errors, for codes that carry them: each problem at its field (see FieldError). Documented on the responses that set it, e.g. approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED. Absent otherwise.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object
field
required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string
message
required
string
details

Structured facts about the refusal, for codes that carry them. The shape is fixed per code and documented on the response that answers it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and IMAGE_IN_USE. Absent for codes that carry none.

object
key
additional properties
any

Example 

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}

403

Section titled “403”

Authenticated but not authorized.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
string
instance
string format: uri-reference
requestId
required
string
code
required
string
issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object
code
required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string
statement
required

Index of the statement at fault; -1 for the document as a whole.

integer
>= -1
detail
required
string
action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string
errors

Field errors, for codes that carry them: each problem at its field (see FieldError). Documented on the responses that set it, e.g. approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED. Absent otherwise.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object
field
required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string
message
required
string
details

Structured facts about the refusal, for codes that carry them. The shape is fixed per code and documented on the response that answers it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and IMAGE_IN_USE. Absent for codes that carry none.

object
key
additional properties
any

Example 

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}

409

Section titled “409”

Conflicting state.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
string
instance
string format: uri-reference
requestId
required
string
code
required
string
issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object
code
required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string
statement
required

Index of the statement at fault; -1 for the document as a whole.

integer
>= -1
detail
required
string
action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string
errors

Field errors, for codes that carry them: each problem at its field (see FieldError). Documented on the responses that set it, e.g. approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED. Absent otherwise.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object
field
required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string
message
required
string
details

Structured facts about the refusal, for codes that carry them. The shape is fixed per code and documented on the response that answers it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and IMAGE_IN_USE. Absent for codes that carry none.

object
key
additional properties
any

Example 

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}