openapi: 3.0.2
info:
description:
RESTful public-facing management API. The API is accessible through
HTTP calls on specific URLs carrying JSON modeled data.
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
title: Nydus-rs API
version: 0.1.0
servers:
- url: http://localhost/api/v1
paths:
/daemon:
summary: Returns general information about a nydus-rs daemon
get:
operationId: describeDaemon
responses:
"200":
description: Daemon information
content:
application/json:
schema:
$ref: "#/components/schemas/DaemonInfo"
"500":
description: Internal Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMsg"
put:
operationId: configureDaemon
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/DaemonConf"
responses:
"204":
description: "Successfully configure the daemon!"
"500":
description: "Can't configure the daemon!"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMsg"
/daemon/events:
get:
operationId: getEvents
responses:
"200":
description: "Get events happened to nydusd"
content:
application/json:
schema:
$ref: "#/components/schemas/Events"
"500":
description: Nydus api server can't process this request.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMsg"
/daemon/backend:
get:
operationId: queryFsBackend
responses:
"200":
description: "Query mounted file system backend"
content:
application/json:
schema:
$ref: "#/components/schemas/DaemonFsBackend"
"500":
description: Nydus api server can't process this request.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMsg"
/daemon/exit:
put:
operationId: exitDaemon
responses:
"204":
description: "Let nydusd process exit"
"500":
description: Nydus api server can't process this request.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMsg"
/mount:
post:
operationId: mountFsBackend
summary: Operations on nydus file system instances.
parameters:
- name: mountpoint
in: query
description: Which directory(mountpoint) in pseudo fs hierarchy to mount to
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/MountCmd"
required: true
responses:
"204":
description: The fs backend has already been successfully mounted
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMsg"
description: Failed in mounting fs backend due to bad request
put:
operationId: remountFsBackend
parameters:
- name: mountpoint
in: query
description: Which directory(mountpoint) in pseudo fs hierarchy to mount to
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/MountCmd"
required: true
responses:
"204":
description: The mount update was successful
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMsg"
description: The mount update action cannot be executed due to bad input
summary: Updates a mount.
delete:
summary: Umount the specified file system backend
operationId: umountFsBackend
parameters:
- name: mountpoint
in: query
description: Which directory(mountpoint) in pseudo fs hierarchy to umount from
required: true
schema:
type: string
responses:
"204":
description: Operation - umount - is successful
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMsg"
description: Umount operation is not done successfully.
/metrics:
get:
operationId: exportRafsMetrics
summary: Rafs filesystem level global metrics.
parameters:
- name: id
in: query
description: "Specify rafs id to get its metrics"
required: false
schema:
type: string
responses:
"200":
description: Rafs metrics export
content:
application/json:
schema:
$ref: "#/components/schemas/RafsMetrics"
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMsg"
description: Perhaps no counter is found
/metrics/files:
get:
summary: Returns Rafs files' fop stats
operationId: exportRafsFilesMetrics
parameters:
- name: id
in: query
description: "Specify rafs id to get its all files metrics"
required: false
schema:
type: string
- name: latest
description: "The returned list represents all files that are ever read ignoring the frequency. The metics of each file will be cleared after this request."
in: query
required: false
schema:
type: boolean
responses:
"200":
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/RafsLatestReadFiles"
- $ref: "#/components/schemas/RafsFilesMetrics"
description: Rafs all opened files metrics export
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMsg"
description: Internal Server Error
/metrics/pattern:
get:
operationId: exportRafsFilesAccessPattern
summary: Rafs files' access patterns
parameters:
- name: id
in: query
description: "Specify rafs id to get its all files access patterns"
required: false
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/RafsFilesAccessPatterns"
description: Rafs access pattern exporting
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMsg"
description: Internal Server Error
/metrics/backend:
get:
parameters:
- name: id
in: query
description: It is equal to ID of rafs, the ID is also the mountpoint of backend fs.
required: false
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/RafsBackend"
description: Rafs storage backend metrics
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMsg"
description: Internal Server Error
/metrics/blobcache:
get:
parameters:
- name: id
in: query
description: It is equal to ID of rafs, the ID is also the mountpoint of backend fs.
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Blobcache"
description: Blobcache metrics
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMsg"
description: Internal Server Error
/metrics/inflight:
get:
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FuseInflight"
description: A set including what fuse requests are being handled. External manager can query this info to judge if request is hang
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMsg"
description: Internal Server Error
components:
schemas:
DaemonInfo:
properties:
version:
type: object
properties:
package_ver:
type: string
git_commit:
type: string
build_time:
type: string
profile:
type: string
rustc:
type: string
id:
type: string
supervisor:
type: string
state:
type: string
enum:
- INIT
- RUNNING
- UPGRADING
- INTERRUPTED
- STOPPED
- UNKNOWN
backend_collection:
type: object
type: object
DaemonConf:
type: object
properties:
log_level:
type: string
enum: [trace, debug, info, warn, error]
DaemonFsBackend:
type: object
MountCmd:
type: object
properties:
fs_type:
type: string
source:
description: usually to be the metadata source
type: string
prefetch_files:
description: local file path which recorded files/directories to be prefetched and separated by newlines
type: string
config:
description: inline request, use to configure fs backend.
type: string
ErrorMsg:
type: object
properties:
code:
description: Nydus defined error code indicating certain error type
type: string
message:
description: Details about the error
type: string
RafsMetrics:
type: object
properties:
files_account_enabled:
type: boolean
measure_latency:
type: boolean
data_read:
type: integer
block_count_read:
type: array
items:
type: integer
fop_hits:
type: array
items:
type: integer
fop_errors:
type: array
items:
type: integer
fop_cumulative_latency_total:
type: array
items:
type: integer
read_latency_dist:
type: array
items:
type: integer
nr_opens:
type: integer
RafsFilesMetrics:
type: object
properties:
nr_open:
type: integer
total_fops:
type: integer
data_read:
type: integer
block_count_read:
type: array
items:
type: integer
fop_hits:
type: array
items:
type: integer
fop_errors:
type: array
items:
type: integer
RafsLatestReadFiles:
type: array
description: File ino array, [start,end] -- include inode from start to end, [ino] -- include inode ino
items:
type: array
items:
type: integer
RafsFilesAccessPatterns:
properties:
ino:
type: integer
description: File inode number to identify which file is against
nr_read:
type: integer
description: How many times a file is read regardless of io block size and request offset
first_access_time_secs:
type: integer
description: First time point at which this file is read. It's wall-time in unit of seconds
RafsBackend:
type: object
properties:
id:
type: string
backend_type:
type: string
read_count:
type: string
read_errors:
type: integer
read_amount_total:
type: integer
read_latency_dist:
type: array
items:
type: array
items:
type: integer
Blobcache:
type: object
properties:
id:
type: string
underlying_files:
type: string
store_path:
type: string
partial_hits:
type: integer
whole_hits:
type: integer
total:
type: integer
entries_count:
type: integer
prefetch_data_amount:
type: integer
prefetch_workers:
type: integer
prefetch_mr_count:
type: integer
prefetch_unmerged_chunks:
type: integer
FuseInflight:
type: array
items:
required:
- inode
- opcode
- unique
- timestamp_secs
type: object
properties:
inode:
type: integer
opcode:
type: integer
unique:
type: integer
timestamp_secs:
type: integer
Events:
type: object
properties:
max_errors:
type: integer
total_errors:
type: integer
max_size:
type: integer
errors:
type: array
items:
type: string