From 436427d3b6ee32a8714f1f509af47d29ab4d01d9 Mon Sep 17 00:00:00 2001 From: Keirthana T S Date: Wed, 18 Sep 2024 10:51:53 +0530 Subject: [PATCH] Automate loading of AMS and Gateway API spec from swagger --- .gitignore | 2 + .sphinx/_extra/ams-api.yaml | 1 + .sphinx/_extra/gateway-api.yaml | 1 + .sphinx/_static/swagger-override.css | 15 + custom_conf.py | 38 + reference/api-reference/ams-api.md | 29 + reference/api-reference/ams-api.yaml | 5500 +++++++++++++++++ .../{ => api-reference}/anbox-https-api.md | 0 reference/api-reference/gateway-api.md | 29 + reference/api-reference/gateway-api.yaml | 1129 ++++ .../landing.md} | 16 +- reference/landing.md | 2 +- 12 files changed, 6750 insertions(+), 12 deletions(-) create mode 120000 .sphinx/_extra/ams-api.yaml create mode 120000 .sphinx/_extra/gateway-api.yaml create mode 100644 .sphinx/_static/swagger-override.css create mode 100644 reference/api-reference/ams-api.md create mode 100644 reference/api-reference/ams-api.yaml rename reference/{ => api-reference}/anbox-https-api.md (100%) create mode 100644 reference/api-reference/gateway-api.md create mode 100644 reference/api-reference/gateway-api.yaml rename reference/{api-reference.md => api-reference/landing.md} (67%) diff --git a/.gitignore b/.gitignore index 04bf99a1..2c4ea2f0 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,5 @@ __pycache__ .vscode/ .sphinx/styles/* .sphinx/vale.ini +.sphinx/deps/ +.sphinx/_static/swagger-ui/ diff --git a/.sphinx/_extra/ams-api.yaml b/.sphinx/_extra/ams-api.yaml new file mode 120000 index 00000000..b6c0ce6a --- /dev/null +++ b/.sphinx/_extra/ams-api.yaml @@ -0,0 +1 @@ +../../reference/api-reference/ams-api.yaml \ No newline at end of file diff --git a/.sphinx/_extra/gateway-api.yaml b/.sphinx/_extra/gateway-api.yaml new file mode 120000 index 00000000..4889b835 --- /dev/null +++ b/.sphinx/_extra/gateway-api.yaml @@ -0,0 +1 @@ +../../reference/api-reference/gateway-api.yaml \ No newline at end of file diff --git a/.sphinx/_static/swagger-override.css b/.sphinx/_static/swagger-override.css new file mode 100644 index 00000000..8dc1efea --- /dev/null +++ b/.sphinx/_static/swagger-override.css @@ -0,0 +1,15 @@ +.swagger-ui .markdown p, .swagger-ui .markdown pre, .swagger-ui .renderedMarkdown p, .swagger-ui .renderedMarkdown pre { + margin-left: 0em; +} + +.swagger-ui, .swagger-ui textarea, .swagger-ui .info li, .swagger-ui .info a, .swagger-ui .info p, .swagger-ui .info table, .swagger-ui .info .title .swagger-ui .opblock-tag, .swagger-ui .opblock .opblock-summary-description, .swagger-ui .opblock-description-wrapper p, .swagger-ui .opblock-external-docs-wrapper p, .swagger-ui .opblock-title_normal p, .swagger-ui .opblock .opblock-section-header h4, .swagger-ui .opblock-tag:hover, .swagger-ui .opblock-tag small, .swagger-ui .opblock .opblock-section-header>label, .swagger-ui .opblock .opblock-summary-method, .swagger-ui .tab li, .swagger-ui .opblock-description-wrapper,.swagger-ui .opblock-external-docs-wrapper,.swagger-ui .opblock-title_normal, .swagger-ui .opblock-description-wrapper h4,.swagger-ui .opblock-external-docs-wrapper h4,.swagger-ui .opblock-title_normal h4, .swagger-ui .responses-inner h4,.swagger-ui .responses-inner h5, .swagger-ui .response-col_status, .swagger-ui .response-col_links, .swagger-ui .download-contents, .swagger-ui .scheme-container .schemes>label, .swagger-ui .loading-container .loading:after, .swagger-ui section h3, .swagger-ui .btn, .swagger-ui .btn.cancel, .swagger-ui select, .swagger-ui label, .swagger-ui .dialog-ux .modal-ux-content p, .swagger-ui .dialog-ux .modal-ux-content p, .swagger-ui .dialog-ux .modal-ux-content h4, .swagger-ui .dialog-ux .modal-ux-header h3, .swagger-ui section.models h4, .swagger-ui section.models h5, .swagger-ui .model-title, .swagger-ui .servers>label, .swagger-ui .model-deprecated-warning, .swagger-ui table thead tr td,.swagger-ui table thead tr th, .swagger-ui .parameter__name, .swagger-ui .topbar a, .swagger-ui .topbar .download-url-wrapper .download-url-button, .swagger-ui .info h1,.swagger-ui .info h2,.swagger-ui .info h3,.swagger-ui .info h4,.swagger-ui .info h5, .swagger-ui .info .title small pre, .swagger-ui .errors-wrapper hgroup h4 { + font-family: "Ubuntu", -apple-system, "Segoe UI", "Roboto", "Oxygen", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif; +} + +.swagger-ui .response-col_description, .swagger-ui .parameters-col_description { + width: 85% +} + +.swagger-ui .information-container .url { + display: none; +} diff --git a/custom_conf.py b/custom_conf.py index 47e482c0..5a00b5ea 100644 --- a/custom_conf.py +++ b/custom_conf.py @@ -1,4 +1,7 @@ import datetime +import os +import subprocess + # Custom configuration for the Sphinx documentation builder. # All configuration specific to your project should be done in this file. @@ -216,3 +219,38 @@ .. role:: center :class: align-center ''' + +## Generate dynamic configuration using scripts +# Inject AMS configuration valuues and Node configuration values from the swagger +# specification hosted on Github. +def generate_ams_configuration(): + from scripts.ams_configuration import get_swagger_from_url, parse_swagger + + with open("scripts/requirements.txt", "r") as f: + for req in f.readlines(): + custom_required_modules.append(req) + ams_configuration_file = "reference/ams-configuration.md" + parse_swagger(get_swagger_from_url(), ams_configuration_file) + +## The following code is to automatically load the API from swagger into documentation. + +# Path to copy the YAML files during build +html_extra_path = ['.sphinx/_extra'] + +# The swagger-ui repository is required to be able to render the swagger YAML +# file as browseable API documentation. The below variable specifies which +# git repository to fetch it from. +swagger_ui_repository = "https://github.com/swagger-api/swagger-ui" + +# Download and link swagger-ui files +if not os.path.isdir('.sphinx/deps/swagger-ui'): + subprocess.check_call(["git", "clone", "--depth=1", swagger_ui_repository, ".sphinx/deps/swagger-ui"]) + +os.makedirs('.sphinx/_static/swagger-ui/', exist_ok=True) + +if not os.path.islink('.sphinx/_static/swagger-ui/swagger-ui-bundle.js'): + os.symlink('../../deps/swagger-ui/dist/swagger-ui-bundle.js', '.sphinx/_static/swagger-ui/swagger-ui-bundle.js') +if not os.path.islink('.sphinx/_static/swagger-ui/swagger-ui-standalone-preset.js'): + os.symlink('../../deps/swagger-ui/dist/swagger-ui-standalone-preset.js', '.sphinx/_static/swagger-ui/swagger-ui-standalone-preset.js') +if not os.path.islink('.sphinx/_static/swagger-ui/swagger-ui.css'): + os.symlink('../../deps/swagger-ui/dist/swagger-ui.css', '.sphinx/_static/swagger-ui/swagger-ui.css') diff --git a/reference/api-reference/ams-api.md b/reference/api-reference/ams-api.md new file mode 100644 index 00000000..134381f4 --- /dev/null +++ b/reference/api-reference/ams-api.md @@ -0,0 +1,29 @@ +# AMS HTTP API + + + +
+ + + + diff --git a/reference/api-reference/ams-api.yaml b/reference/api-reference/ams-api.yaml new file mode 100644 index 00000000..9a2dd966 --- /dev/null +++ b/reference/api-reference/ams-api.yaml @@ -0,0 +1,5500 @@ +definitions: + Addon: + description: Addon describes a package with additional functionality to be added to containers + properties: + name: + description: Name of the addon + example: my-addon + type: string + used_by: + description: List of applications using this addon + example: + - app1 + - app2 + items: + type: string + type: array + versions: + description: List of versions of the addon + items: + $ref: '#/definitions/AddonVersion' + type: array + type: object + AddonPatch: + description: AddonPatch allows updating an existing addon with a new version + type: object + AddonVersion: + description: AddonVersion describes a single version of an addon + properties: + created_at: + description: Creation timestamp of the addon + example: 1610641117 + format: int64 + type: integer + fingerprint: + description: SHA-256 fingerprint of the addon version + example: 0791cfc011f67c60b7bd0f852ddb686b79fa46083d9d43ef9845c9235c67b261 + type: string + size: + description: Size (in bytes) of the addon payload + example: 529887868 + format: int64 + type: integer + version: + description: Version for the addon + example: 0 + format: int64 + type: integer + type: object + AddonsPost: + description: AddonsPost is used to create a new addon + properties: + name: + description: Name of the addon + example: my-addon + type: string + type: object + Application: + description: Application represents an AMS application + properties: + abi: + description: ABI supported by the application + example: x86_64 + type: string + addons: + description: List of addons enabled for the application + example: + - ssh + - gms + items: + type: string + type: array + boot_package: + description: Name of the boot package for the application + example: com.foo.bar + type: string + created_at: + description: Creation UTC timestamp of the application + example: 1532150640 + format: int64 + type: integer + id: + description: ID of the application + example: btavtegj1qm58qg7ru50 + type: string + immutable: + description: Flag to show whether the application can be edited + example: false + type: boolean + inhibit_auto_updates: + description: Whether or not to auto update the application's base image + example: false + type: boolean + instance_type: + description: Instance type required by the application + example: a2.3 + type: string + name: + description: Name of the application + example: my-app + type: string + node_selector: + description: List of tags for filtering the nodes to run the application on + example: + - gpu=nvidia + - cpu=intel + items: + type: string + type: array + parent_image_id: + description: Parent image used for the application + example: btavtegj1qm58qg7ru50 + type: string + published: + description: Whether or not the application is published + example: false + type: boolean + resources: + $ref: '#/definitions/ApplicationResources' + status: + description: Current status of the application + enum: + - initializing + - unknown + - ready + - deleted + - error + example: deleted + type: string + status_code: + $ref: '#/definitions/ApplicationStatus' + tags: + description: Tags to attach to the application + example: + - created_by=anbox + items: + type: string + type: array + versions: + description: List of versions for the application + items: + $ref: '#/definitions/ApplicationVersion' + type: array + vm: + description: Whether the application is based on virtual machines or containers + type: boolean + type: object + ApplicationAddon: + description: ApplicationAddon describes a specific version of an addon an application version uses + properties: + name: + description: Name of the application addon + example: ssh + type: string + version: + description: Version of the application addon + example: 0 + format: int64 + type: integer + type: object + ApplicationBootstrap: + description: ApplicationBootstrap describes the fields used to configure the application bootstrap + properties: + keep: + description: List of files to keep after the bootstrap + example: + - app.apk + items: + type: string + type: array + type: object + ApplicationDelete: + description: ApplicationDelete represents the fields used to delete an application + properties: + force: + description: Whether deletion of the application should be forced + example: false + type: boolean + type: object + ApplicationExtraData: + description: ApplicationExtraData represents an extra application data + properties: + owner: + description: Owner and group for the files + example: root:root + type: string + permissions: + description: Unix permissions for the files + example: "0644" + type: string + target: + description: Path to the target file on the android filesystem + example: /sdcard/Android/obb/com.foo.bar/ + type: string + type: object + ApplicationHooks: + description: ApplicationHooks describes the fields used to configure the hooks of an application + properties: + timeout: + description: Time limit to wait for the hook to complete before timing out + example: 10m + type: string + type: object + ApplicationPatch: + description: ApplicationPatch represents the fields a user can modify + properties: + addons: + description: List of addons enabled for the application + example: + - ssh + - gms + items: + type: string + type: array + boot_activity: + description: Name of the boot package for the version + example: com.foo.bar.MainActivity + type: string + bootstrap: + $ref: '#/definitions/ApplicationBootstrap' + features: + description: List of features supported by the application + example: + - feature1 + - feature2 + items: + type: string + type: array + hooks: + $ref: '#/definitions/ApplicationHooks' + image: + description: Base image id or name to use for the applicaiton + example: btavtegj1qm58qg7ru50 + type: string + inhibit_auto_updates: + description: Whether or not to auto update the application's base image + example: false + type: boolean + instance-type: + description: Instance type to use for the application + example: a3.4 + type: string + manifest_version: + description: Version of the manifest used to create the application + example: "0.1" + type: string + node_selector: + description: List of tags for filtering the nodes to run the application on + example: + - gpu=nvidia + - cpu=intel + items: + type: string + type: array + required_permissions: + description: Required android application permissions + example: + - android.permission.WRITE_EXTERNAL_STORAGE + - android.permission.READ_EXTERNAL_STORAGE + items: + type: string + type: array + resources: + $ref: '#/definitions/ApplicationResourcesPost' + services: + description: |- + List of services exposed by the application that should be expose on the instance + For application version update, changing those values would trigger a new application version creation + items: + $ref: '#/definitions/NetworkServiceSpec' + type: array + tags: + description: Tags to attach to the application + example: + - created_by=anbox + items: + type: string + type: array + video_encoder: + $ref: '#/definitions/VideoEncoderType' + watchdog: + $ref: '#/definitions/ApplicationWatchdog' + type: object + ApplicationResources: + description: ApplicationResources describes resources allocated for an application + properties: + cpus: + description: Number of CPUs required by the application + example: 2 + format: int64 + type: integer + disk-size: + description: Storage size required by the application + example: 3GB + type: string + gpu-slots: + description: Number of GPU slots required by the application + example: 2 + format: int64 + type: integer + memory: + description: Memory to be assigned to the application + example: 3GB + type: string + vpu-slots: + description: Number of VPU slots required by the application + example: 1 + format: int64 + type: integer + type: object + ApplicationResourcesPost: + description: ApplicationResourcesPost represents the fields used to update an application resource + properties: + cpus: + description: Number of CPUs required by the application + example: 2 + format: int64 + type: integer + disk-size: + description: Storage size required by the application + example: 3GB + type: string + gpu-slots: + description: Number of GPU slots required by the application + example: 2 + format: int64 + type: integer + memory: + description: Memory to be assigned to the application + example: 3GB + type: string + vpu-slots: + description: Number of VPU slots required by the application + example: 1 + format: int64 + type: integer + type: object + ApplicationStatus: + description: ApplicationStatus represents the status an application can be in + format: int64 + type: integer + ApplicationVersion: + description: ApplicationVersion describes a single version of an application + properties: + addons: + description: List of addons enabled for the version + items: + $ref: '#/definitions/ApplicationAddon' + type: array + boot_activity: + description: Name of the boot package for the version + example: com.foo.bar.MainActivity + type: string + bootstrap: + $ref: '#/definitions/ApplicationBootstrap' + created_at: + description: Creation UTC timestamp of the version + example: 1532150640 + format: int64 + type: integer + error_message: + description: Error message in case the application ran into an error + example: '{}' + type: string + extra_data: + additionalProperties: + $ref: '#/definitions/ApplicationExtraData' + description: Extra data to be setup on the instance on application creation + example: {} + type: object + features: + description: List of features supported by the application + example: + - feature1 + - feature2 + items: + type: string + type: array + hooks: + $ref: '#/definitions/ApplicationHooks' + manifest_version: + description: Version of the manifest used to create the application + example: "0.1" + type: string + number: + description: Version of the application + example: 0 + format: int64 + type: integer + parent_image_id: + description: Parent image used for the application version + example: btavtegj1qm58qg7ru50 + type: string + parent_image_version: + description: Parent image version to use for the application version + example: 0 + format: int64 + type: integer + published: + description: Whether or not the version is published + example: false + type: boolean + required_permissions: + description: Required android application permissions + example: + - android.permission.WRITE_EXTERNAL_STORAGE + - android.permission.READ_EXTERNAL_STORAGE + items: + type: string + type: array + services: + description: List of services exposed by the application that should be exposed on the instance + items: + $ref: '#/definitions/NetworkServiceSpec' + type: array + status: + description: Current status of the version + enum: + - initializing + - unknown + - ready + - deleted + - error + example: deleted + type: string + status_code: + $ref: '#/definitions/ImageStatus' + video_encoder: + $ref: '#/definitions/VideoEncoderType' + watchdog: + $ref: '#/definitions/ApplicationWatchdog' + type: object + ApplicationVersionDelete: + description: ApplicationVersionDelete represents the fields used to delete an application version + properties: + force: + description: Whether deletion of the application version should be forced + example: false + type: boolean + type: object + ApplicationVersionPatch: + description: ApplicationVersionPatch represents the fields used to update an application version + properties: + published: + description: Used to publish a specific version of the application + example: true + type: boolean + type: object + ApplicationWatchdog: + description: ApplicationWatchdog describes the fields used to update an application watchdog + properties: + allowed-packages: + description: List of android packages to enable the watchdog for + example: + - com.android.settings + items: + type: string + type: array + disabled: + description: Whether or not to enable the watchdog for the application + example: true + type: boolean + type: object + ApplicationsDelete: + description: ApplicationsDelete represents a list of application to delete together + properties: + force: + description: Whether deletion of the applications should be forced + example: false + type: boolean + ids: + description: IDs or names of the applications to delete + example: + - cilsreunfpfec9b1ktg0 + - cilsreunfpfec9b1ktg1 + - myapp + items: + type: string + type: array + type: object + Certificate: + description: Certificate represents an available client certificate + properties: + certificate: + description: Base64 encoded certificate content without the header or the footer + example: MIIFUTCCAzmgAw...xjKoUEEQOzJ9 + type: string + fingerprint: + description: SHA-256 fingerprint of the certificate + example: b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 + type: string + type: object + CertificatesPost: + description: CertificatesPost represents the fields of a new auth provided certificate + properties: + certificate: + description: Base64 encoded certificate content without the header or the footer + example: MIIFUTCCAzmgAw...xjKoUEEQOzJ9 + type: string + trust-password: + description: TrustPassword is used to register a new client with the service + example: sUp3rs3cr3t + type: string + type: object + CollectionResponse: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + - properties: + total_size: + description: Total Count of the collection + example: 99 + format: int64 + type: integer + type: object + description: Collection Response + ConfigItem: + description: ConfigItem represents a single configuration item + properties: + name: + type: string + value: + type: string + type: object + ConfigPost: + description: ConfigPost contains the field necessary to set or update a config item + properties: + name: + example: application.auto_publish + type: string + value: + example: "false" + type: string + type: object + Container: + description: Container represents a single container + properties: + address: + description: Address is the IP address of the container + example: 192.168.1.74 + type: string + app_id: + description: |- + AppID is the ID of the application the container is created from. Empty if the + container has not been created from an application. + example: cilsiomnfpfec9b1kteg + type: string + app_name: + description: |- + AppName is the name of the application the container is created from. Empty if the + container has not been created from an application. + example: myapp + type: string + app_version: + description: |- + AppVersion is the version of the application the container is created from. Empty if the + container has not been created from an application. + example: 0 + format: int64 + type: integer + architecture: + description: Architecture describes the CPU archtitecture the container is using + example: aarch64 + type: string + config: + description: Config summarizes the configuration the container uses + properties: + boot_activity: + description: BootActivity specifies the Android activity which is started by default + example: com.android.settings/.DevSettings + type: string + boot_package: + description: BootPackage specifies the Android application package name which is started by default + example: com.android.settings + type: string + devmode: + description: DevMode specifies if development mode has been turned on for the container + type: boolean + disable_watchdog: + description: DisableWatchdog defines whether the watchdog is disabled + type: boolean + metrics_server: + description: MetricsServer specifies a metrics server the container will use + example: 10.0.0.45:8086 + type: string + platform: + description: Platform specifies the Anbox platform the container is running with + example: webrtc + type: string + type: object + created_at: + description: CreatedAt specifies the time at which the container was created + example: 1689604498 + format: int64 + type: integer + error_message: + description: ErrorMessage provides an error message when the container status is set to error. + example: container failed to boot + type: string + id: + description: ID of the container + example: cilsreunfpfec9b1ktg0 + type: string + image_id: + description: |- + ImageID is the ID of the image the container is created from. Empty if the + container has not been created from an image. + example: cilshrmnfpfec9b1kte0 + type: string + image_version: + description: |- + ImageVersion is the version of the image the container is created from. Empty if the + container has not been created from an image. + example: 0 + format: int64 + type: integer + name: + description: Name of the container. Typically in the format "ams-". + example: ams-cilsreunfpfec9b1ktg0 + type: string + node: + description: Node the container is running on + example: lxd0 + type: string + public_address: + description: |- + PublicAddress is the external IP address the container is accessible on (in most + cases the IP of the node it is running on) + example: 1.2.3.4 + type: string + resources: + description: Resources specifies the resources allocated for the container + properties: + cpus: + description: CPUs cores assigned to the container + example: 2 + format: int64 + type: integer + disk-size: + description: DiskSize specifies the amount of storage assigned to the container + example: 3GB + type: string + gpu-slots: + description: GPUSlots specifies the number of GPU slots the container got allocated + example: 1 + format: int64 + type: integer + memory: + description: Memory assigned to the container + example: 3GB + type: string + vpu-slots: + description: VPUSlots specifies the number of VPU slots the container + format: int64 + type: integer + type: object + services: + description: Services the container exposes + items: + $ref: '#/definitions/ContainerService' + type: array + status: + description: Status of the container + example: running + type: string + status_code: + $ref: '#/definitions/ContainerStatus' + stored_logs: + description: StoredLogs lists log files AMS stores for the container. + example: + - android.log + - system.log + items: + type: string + type: array + tags: + description: Tags specifies the tags the container has assigned + example: + - foo + - bar + items: + type: string + type: array + type: + $ref: '#/definitions/ContainerType' + type: object + ContainerDelete: + description: ContainerDelete describes a request used to delete a container + properties: + force: + description: Whether deletion of the container should be forced + type: boolean + type: object + ContainerExecControl: + description: ContainerExecControl represents a message on the container shell "control" socket + properties: + args: + additionalProperties: + type: string + description: Arguments to pass to the command + example: + height: 720 + width: 1280 + type: object + command: + description: 'Command to execute. Possible values are: window-resize, signal' + example: window-resize + type: string + signal: + description: Signal to send + format: int64 + type: integer + type: object + ContainerExecPost: + description: ContainerExecPost represents an container execution request + properties: + command: + description: Command inside the container to execute + example: /bin/ls + items: + type: string + type: array + environment: + additionalProperties: + type: string + description: Environment to setup when the command is executed. + example: + FOO: bar + type: object + height: + description: Height of the terminal. Only required when `interactive` is set to `true`. + format: int64 + type: integer + interactive: + description: Whether the command is executed interactively or not + type: boolean + width: + description: Width of the terminal. Only required when `interactive` is set to `true`. + format: int64 + type: integer + type: object + ContainerPatch: + description: ContainerPatch describes the fields which can be changed for an existing container + properties: + desired_status: + description: Desired status of the container + type: string + type: object + ContainerService: + description: |- + While NetworkServiceSpec defines what the user requests, ContainerService is what is actually + opened on the container. + properties: + expose: + description: |- + Expose defines wether the service is exposed on the public endpoint of the node + or if it is only available on the private endpoint. To expose the service set to + true and to false otherwise. + type: boolean + name: + description: |- + Name gives the container a hint what the exposed port is being used for. This + allows further tweaks inside the container to expose the service correctly. + example: myservice + type: string + node_port: + description: |- + NodePort is the port used on the LXD node to map to the service port + If left empty the node port is automatically selected. + example: 4000 + format: int64 + type: integer + node_port_end: + description: |- + NodePortEnd, if specified, denotes the end of the port range on the node starting + at NodePort + example: 4010 + format: int64 + type: integer + port: + description: Port is the port the container provides a service on + example: 3000 + format: int64 + type: integer + port_end: + description: PortEnd, if specified, denotes the end of the port range starting at Port + example: 3010 + format: int64 + type: integer + protocols: + description: List of network protocols (tcp, udp) the port should be exposed for + example: + - tcp + - udp + items: + $ref: '#/definitions/NetworkProtocol' + type: array + title: ContainerService describes a single service the container exposes to the outside world. + type: object + ContainerStatus: + description: ContainerStatus represents the status a container can be in + format: int64 + type: integer + ContainerType: + description: 'Possible values are: regular, base, unknown' + title: ContainerType describes the type of a container. + type: string + ContainersDelete: + description: ContainersDelete represents a list of containers to delete together + properties: + force: + description: Whether deletion of the containers should be forced + type: boolean + ids: + description: IDs of the containers to delete + example: + - cilsreunfpfec9b1ktg0 + - cilsreunfpfec9b1ktg1 + items: + type: string + type: array + type: object + ContainersPost: + description: |- + ContainersPost represents the fields required to launch a new container for + a specific application + properties: + addons: + description: Addons to enable for the container + example: + - addon0 + - addon1 + items: + type: string + type: array + app_id: + description: ID of the application to use. Can be empty if an image ID is specified instead + example: cilsiomnfpfec9b1kteg + type: string + app_version: + description: Version of the application to use. If not specified, the latest version is used. + example: 0 + format: int64 + type: integer + config: + properties: + boot_activity: + description: BootActivity specifies the Android activity which is started by default + example: com.android.settings/.DevSettings + type: string + boot_package: + description: BootPackage specifies the Android application package name which is started by default + example: com.android.settings + type: string + devmode: + description: DevMode specifies if development mode has been turned on for the container + type: boolean + disable_watchdog: + description: DisableWatchdog defines whether the watchdog is disabled + type: boolean + features: + description: Feature flags to enable for the container. + example: feature0, feature1 + type: string + metrics_server: + description: MetricsServer specifies a metrics server the container will use + example: 10.0.0.45:8086 + type: string + platform: + description: Platform specifies the Anbox platform the container is running with + example: webrtc + type: string + type: object + cpus: + description: Number of CPU cores the container should get assigned. + example: 4 + format: int64 + type: integer + disk_size: + description: Disk size the container should get allocated in bytes + example: 3221225472 + format: int64 + type: integer + gpu-slots: + description: Number of GPU slots the container should get assigned. + example: 1 + format: int64 + type: integer + image_id: + description: ID of the image to use. Can be empty if an application ID is specified instead. + example: cilshrmnfpfec9b1kte0 + type: string + image_version: + description: Version of the image to use. If not specified, the latest version is used. + example: 0 + format: int64 + type: integer + instance_type: + description: |- + Instance type to use for the container. + Example a2.3 + type: string + memory: + description: Memory the container should get assigned in bytes. + example: 3221225472 + format: int64 + type: integer + no_start: + description: Do not start the container after creation. + type: boolean + node: + description: Node to start the container on. If empty node will be automatically selected. + example: lxd0 + type: string + services: + description: Services to enable for the container + items: + $ref: '#/definitions/NetworkServiceSpec' + type: array + tags: + description: Tags which will be assigned to the container + example: + - tag0 + - tag1 + items: + type: string + type: array + user_data: + description: User data to pass to the container. + example: '{\"key\":\"value\"}' + type: string + vpu-slots: + description: Number of VPU slots the container should get assigned + example: 1 + format: int64 + type: integer + type: object + Event: + description: Event defines the structure of an event sent on the events API endpoint + properties: + metadata: + description: Metadata represents the actual event data + example: '{ "class": "task", "created_at": "2017-07-28T05:02:22.92201407Z", "description": "Deleting container", "err": "", "id": "bc85137b-b20d-470a-a6ea-daa9a2b8506a", "may_cancel": false, "metadata": null, "resources": { "containers": [ "/1.0/containers/c0946voj1qm6t2783db0" ] }, "server_address": "", "status": "Success", "status_code": 200, "updated_at": "2017-07-28T05:02:22.92201407Z" }' + timestamp: + description: Timestamp (in ISO8601 format) is filled when sending the event if empty + example: "2017-07-28T05:02:22.92201407Z" + type: + description: |- + Type defines the type of event. Listeners can watch specific + event types + enum: + - operation + - lifecycle + type: string + type: object + Image: + description: Image represents an image available in AMS + properties: + architecture: + description: CPU architecture supported by the image + example: x86_64 + type: string + default: + description: Flag to show whether the image is used by default if no image name is provided + example: false + type: boolean + id: + description: ID of the image + example: btavtegj1qm58qg7ru50 + type: string + immutable: + description: Flag to show whether the image can be edited by an AMS instance or not + example: false + type: boolean + name: + description: Name of the image + example: my-image + type: string + status: + description: Current status of the image + enum: + - error + - created + - active + - initializing + - unknown + example: active + type: string + status_code: + $ref: '#/definitions/ImageStatus' + type: + $ref: '#/definitions/ImageType' + used_by: + description: List of application ids using the image as a base + example: + - btavtegj1qm58asf123 + items: + type: string + type: array + versions: + description: List of versions for the image + items: + $ref: '#/definitions/ImageVersion' + type: array + type: object + ImageDelete: + description: ImageDelete describes a request used to delete an image + properties: + force: + type: boolean + type: object + ImagePatch: + description: ImagePatch represents the fields to update an existing image + properties: + default: + description: Make the image as default + example: true + type: boolean + force_sync: + description: |- + ForceSync forces synchronization of the image from the remote image server + Examle: true + type: boolean + type: object + ImageStatus: + description: ImageStatus represents the status of an image + format: int64 + type: integer + ImageType: + description: ImageType specifies the type of an image + type: string + ImageVersion: + description: ImageVersion describes a single version of an image + properties: + created_at: + description: Creation UTC timestamp of the image + example: 1610641117 + format: int64 + type: integer + fingerprint: + description: Fingerprint of the image version + example: 0791cfc011f67c60b7bd0f852ddb686b79fa46083d9d43ef9845c9235c67b261 + type: string + remote_id: + description: Version of the image in the remote server + example: 1.2.3 + type: string + size: + description: Size (in bytes) of the image version + example: 529887868 + format: int64 + type: integer + status: + description: Current status of the image + enum: + - error + - created + - active + - initializing + - unknown + example: active + type: string + status_code: + $ref: '#/definitions/ImageStatus' + version: + description: Version for the image + example: 0 + format: int64 + type: integer + type: object + ImagesGet: + description: ImagesGet represents a list of images + properties: + images: + items: + $ref: '#/definitions/Image' + type: array + type: object + ImagesPost: + description: ImagesPost represents the fields to upload a new image + properties: + default: + description: Make the image as default + example: false + type: boolean + name: + description: Name of the image + example: my-image + type: string + path: + description: Path to store the image + example: /save/image + type: string + type: + $ref: '#/definitions/ImageType' + type: object + Instance: + description: Instance represents a single instance + properties: + address: + description: Address is the IP address of the instance + example: 192.168.1.74 + type: string + app_id: + description: |- + AppID is the ID of the application the instance is created from. Empty if the + instance has not been created from an application. + example: cilsiomnfpfec9b1kteg + type: string + app_name: + description: |- + AppName is the name of the application the instance is created from. Empty if the + instance has not been created from an application. + example: myapp + type: string + app_version: + description: |- + AppVersion is the version of the application the instance is created from. Empty if the + instance has not been created from an application. + example: 0 + format: int64 + type: integer + architecture: + description: Architecture describes the CPU archtitecture the instance is using + example: aarch64 + type: string + base: + description: If this is a base instance or not + type: boolean + config: + description: Config summarizes the configuration the instance uses + properties: + boot_activity: + description: BootActivity specifies the Android activity which is started by default + example: com.android.settings/.DevSettings + type: string + boot_package: + description: BootPackage specifies the Android application package name which is started by default + example: com.android.settings + type: string + devmode: + description: DevMode specifies if development mode has been turned on for the instance + type: boolean + disable_watchdog: + description: DisableWatchdog defines whether the watchdog is disabled + type: boolean + display: + properties: + density: + description: Density is the piel density of the virtual display + format: int64 + type: integer + fps: + description: FPS is the frame rate of the virtual display + format: int64 + type: integer + height: + description: Height is the height of the virtual display + format: int64 + type: integer + width: + description: Width is the width of the virtual display + format: int64 + type: integer + type: object + enable_streaming: + description: EnableStreaming specifies if streaming should be enabled for the instance or not + type: boolean + metrics_server: + description: MetricsServer specifies a metrics server the instance will use + example: 10.0.0.45:8086 + type: string + platform: + description: Platform specifies the Anbox platform the instance is running with + example: webrtc + type: string + type: object + created_at: + description: CreatedAt specifies the time at which the instance was created + example: 1689604498 + format: int64 + type: integer + error_message: + description: ErrorMessage provides an error message when the instance status is set to error. + example: instance failed to boot + type: string + id: + description: ID of the instance + example: cilsreunfpfec9b1ktg0 + type: string + image_id: + description: |- + ImageID is the ID of the image the instance is created from. Empty if the + instance has not been created from an image. + example: cilshrmnfpfec9b1kte0 + type: string + image_version: + description: |- + ImageVersion is the version of the image the instance is created from. Empty if the + instance has not been created from an image. + example: 0 + format: int64 + type: integer + name: + description: Name of the instance. Typically in the format "ams-". + example: ams-cilsreunfpfec9b1ktg0 + type: string + node: + description: Node the instance is running on + example: lxd0 + type: string + public_address: + description: |- + PublicAddress is the external IP address the instance is accessible on (in most + cases the IP of the node it is running on) + example: 1.2.3.4 + type: string + resources: + $ref: '#/definitions/InstanceResources' + services: + description: Services the instance exposes + items: + $ref: '#/definitions/InstanceService' + type: array + status: + description: Status of the instance + example: running + type: string + status_code: + $ref: '#/definitions/InstanceStatus' + status_message: + description: StatusMessage describes the current status of the instance + example: '"Waiting for image download"' + type: string + stored_logs: + description: StoredLogs lists log files AMS stores for the instance. + example: + - android.log + - system.log + items: + type: string + type: array + tags: + description: Tags specifies the tags the instance has assigned + example: + - foo + - bar + items: + type: string + type: array + type: + $ref: '#/definitions/InstanceType' + type: object + InstanceDelete: + description: InstanceDelete describes a request used to delete a instance + properties: + force: + description: Whether deletion of the instance should be forced + type: boolean + type: object + InstanceExecControl: + description: InstanceExecControl represents a message on the instance shell "control" socket + properties: + args: + additionalProperties: + type: string + description: Arguments to pass to the command + example: + height: 720 + width: 1280 + type: object + command: + description: 'Command to execute. Possible values are: window-resize, signal' + example: window-resize + type: string + signal: + description: Signal to send + format: int64 + type: integer + type: object + InstanceExecPost: + description: InstanceExecPost represents an instance execution request + properties: + command: + description: Command inside the instance to execute + example: /bin/ls + items: + type: string + type: array + environment: + additionalProperties: + type: string + description: Environment to setup when the command is executed. + example: + FOO: bar + type: object + height: + description: Height of the terminal. Only required when `interactive` is set to `true`. + format: int64 + type: integer + interactive: + description: Whether the command is executed interactively or not + type: boolean + width: + description: Width of the terminal. Only required when `interactive` is set to `true`. + format: int64 + type: integer + type: object + InstancePatch: + description: InstancePatch describes the fields which can be changed for an existing instance + properties: + desired_status: + description: Desired status of the instance + type: string + type: object + InstanceResources: + description: InstanceResources represents resources assigned to an instance + properties: + cpus: + description: CPUs cores assigned to the instance + example: 2 + format: int64 + type: integer + disk-size: + description: DiskSize specifies the amount of storage assigned to the instance in bytes + example: 3221225472 + format: int64 + type: integer + gpu-slots: + description: GPUSlots specifies the number of GPU slots the instance got allocated + example: 1 + format: int64 + type: integer + memory: + description: Memory assigned to the instance in bytes + example: 3221225472 + format: int64 + type: integer + vpu-slots: + description: VPUSlots specifies the number of VPU slots the instance + format: int64 + type: integer + type: object + InstanceService: + description: |- + While NetworkServiceSpec defines what the user requests, InstanceService is what is actually + opened on the instance. + properties: + expose: + description: |- + Expose defines wether the service is exposed on the public endpoint of the node + or if it is only available on the private endpoint. To expose the service set to + true and to false otherwise. + type: boolean + name: + description: |- + Name gives the instance a hint what the exposed port is being used for. This + allows further tweaks inside the instance to expose the service correctly. + example: myservice + type: string + node_port: + description: |- + NodePort is the port used on the LXD node to map to the service port + If left empty the node port is automatically selected. + example: 4000 + format: int64 + type: integer + node_port_end: + description: |- + NodePortEnd, if specified, denotes the end of the port range on the node starting + at NodePort + example: 4010 + format: int64 + type: integer + port: + description: Port is the port the instance provides a service on + example: 3000 + format: int64 + type: integer + port_end: + description: PortEnd, if specified, denotes the end of the port range starting at Port + example: 3010 + format: int64 + type: integer + protocols: + description: List of network protocols (tcp, udp) the port should be exposed for + example: + - tcp + - udp + items: + $ref: '#/definitions/NetworkProtocol' + type: array + title: InstanceService describes a single service the instance exposes to the outside world. + type: object + InstanceStatus: + description: InstanceStatus represents the status a instance can be in + format: int64 + type: integer + InstanceType: + description: InstanceType describes the type of an instance (container, vm) + type: string + InstancesDelete: + description: InstancesDelete represents a list of instances to delete together + properties: + force: + description: Whether deletion of the instances should be forced + type: boolean + ids: + description: IDs of the instances to delete + example: + - cilsreunfpfec9b1ktg0 + - cilsreunfpfec9b1ktg1 + items: + type: string + type: array + type: object + InstancesPost: + description: |- + InstancesPost represents the fields required to launch a new instance for + a specific application + properties: + addons: + description: Addons to enable for the instance + example: + - addon0 + - addon1 + items: + type: string + type: array + app_id: + description: ID of the application to use. Can be empty if an image ID is specified instead + example: cilsiomnfpfec9b1kteg + type: string + app_version: + description: Version of the application to use. If not specified, the latest version is used. + example: 0 + format: int64 + type: integer + config: + properties: + boot_activity: + description: BootActivity specifies the Android activity which is started by default + example: com.android.settings/.DevSettings + type: string + boot_package: + description: BootPackage specifies the Android application package name which is started by default + example: com.android.settings + type: string + devmode: + description: DevMode specifies if development mode has been turned on for the instance + type: boolean + disable_watchdog: + description: DisableWatchdog defines whether the watchdog is disabled + type: boolean + display: + description: Display specifies the configuration of the virutal display of the instance + properties: + density: + description: Density is the piel density of the virtual display + format: int64 + type: integer + fps: + description: FPS is the frame rate of the virtual display + format: int64 + type: integer + height: + description: Height is the height of the virtual display + format: int64 + type: integer + width: + description: Width is the width of the virtual display + format: int64 + type: integer + type: object + enable_streaming: + description: EnableStreaming specifies if streaming should be enabled for the instance or not + type: boolean + features: + description: Feature flags to enable for the instance. + example: feature0, feature1 + type: string + metrics_server: + description: MetricsServer specifies a metrics server the instance will use + example: 10.0.0.45:8086 + type: string + platform: + description: Platform specifies the Anbox platform the instance is running with + example: webrtc + type: string + type: object + image_id: + description: ID of the image to use. Can be empty if an application ID is specified instead. + example: cilshrmnfpfec9b1kte0 + type: string + image_version: + description: Version of the image to use. If not specified, the latest version is used. + example: 0 + format: int64 + type: integer + name: + description: |- + Name of the instance. Will be automatically assigned if not specified. Names + must be unique. + type: string + no_start: + description: Do not start the instance after creation. + type: boolean + node: + description: Node to start the instance on. If empty node will be automatically selected. + example: lxd0 + type: string + resources: + description: Resources specifies the resources allocated for the instance + properties: + cpus: + description: Number of CPU cores the instance should get assigned. + example: 4 + format: int64 + type: integer + disk_size: + description: Disk size the instance should get allocated in bytes + example: 3221225472 + format: int64 + type: integer + gpu-slots: + description: Number of GPU slots the instance should get assigned. + example: 1 + format: int64 + type: integer + memory: + description: Memory the instance should get assigned in bytes. + example: 3221225472 + format: int64 + type: integer + vpu-slots: + description: Number of VPU slots the instance should get assigned + example: 1 + format: int64 + type: integer + type: object + services: + description: Services to enable for the instance + items: + $ref: '#/definitions/NetworkServiceSpec' + type: array + tags: + description: Tags which will be assigned to the instance + example: + - tag0 + - tag1 + items: + type: string + type: array + type: + $ref: '#/definitions/InstanceType' + user_data: + description: User data to pass to the instance. + example: '{\"key\":\"value\"}' + type: string + type: object + NetworkProtocol: + description: NetworkProtocol describes a specific network protocol like TCP or UDP a ContainerService can use + type: string + NetworkServiceSpec: + description: NetworkServiceSpec is used to define the user defined network services that should be opened on a container + properties: + expose: + description: |- + Expose defines wether the service is exposed on the public endpoint of the node + or if it is only available on the private endpoint. To expose the service set to + true and to false otherwise. + type: boolean + name: + description: |- + Name gives the container a hint what the exposed port is being used for. This + allows further tweaks inside the container to expose the service correctly. + Exampe: ssh + type: string + port: + description: Port is the port the container provides a service on + example: 3000 + format: int64 + type: integer + port_end: + description: |- + PortEnd is the end of the port range set for a service. If empty, only a + single port is opened + example: 3010 + format: int64 + type: integer + protocols: + description: List of network protocols (tcp, udp) the port should be exposed for + example: + - tcp + - udp + items: + $ref: '#/definitions/NetworkProtocol' + type: array + type: object + NoMetaSyncResponse: + description: Swagger Synchronous response without metadata field + properties: + error_code: + description: Error code for the operation + example: 0 + format: int64 + type: integer + status: + description: Status of requested operation + example: Success + type: string + status_code: + description: Status code of the request + example: 200 + format: int64 + type: integer + type: + description: Type of operation response + example: sync + type: string + type: object + Node: + description: Node describes a single node of the underlying LXD cluster AMS manages + properties: + address: + description: Internal IP address of the node + example: 10.0.0.1 + format: ipv4 + type: string + architecture: + description: CPU architecture of the node + example: aarch64 + type: string + cpu_allocation_rate: + description: CPU allocation rate for the node + example: 4 + format: float + type: number + cpus: + description: Number of CPUs on the node + example: 4 + format: int64 + type: integer + disk_size: + description: Disk size for the node + example: "true" + type: string + gpu_encoder_slots: + description: Number of GPU encoder slots present on the node + example: 0 + format: int64 + type: integer + gpu_slots: + description: Number of GPU slots present on the node + example: 0 + format: int64 + type: integer + gpus: + description: GPU information for the node + items: + $ref: '#/definitions/NodeGPU' + type: array + is_master: + description: Flag to represent the master node for the AMS cluster + example: true + type: boolean + managed: + description: Flag used to control if AMS can manage the LXD node + example: false + type: boolean + memory: + description: Memory (in GB) of the LXD node + example: 8GB + type: string + memory_allocation_rate: + description: Memory allocation rate for the node + example: 2 + format: float + type: number + name: + description: Name of the node + example: lxd0 + type: string + network_bridge_mtu: + description: MTU for the configured network bridge on LXD + example: 1500 + format: int64 + type: integer + public_address: + description: Public IP address of the node + example: 10.0.0.1 + format: ipv4 + type: string + status: + description: Current status of the node + example: online + type: string + status_code: + $ref: '#/definitions/NodeStatus' + storage_pool: + description: Name of the storage pool configured for the node + example: default + type: string + tags: + description: Tags attached to the node + example: + - created_by=anbox + - gpu=nvidia + items: + type: string + type: array + unscheduable: + description: DEPRECATED Flag in favour of `unschedulable` flag + example: false + type: boolean + unschedulable: + description: Flag used to see if the node is available to schedule containers + example: false + type: boolean + vpus: + description: VPU information for the node + items: + $ref: '#/definitions/NodeVPU' + type: array + type: object + NodeDelete: + description: NodeDelete describes a request used to delete a node + properties: + force: + description: Use this to force deletion of a node from AMS and LXD cluster + example: true + type: boolean + keep_in_cluster: + description: Use this to remove the node from the LXD cluster as well + example: true + type: boolean + type: object + NodeGPU: + description: NodeGPU describes a single GPU available on a node + properties: + allocations: + additionalProperties: + $ref: '#/definitions/NodeGPUAllocation' + description: Map of current allocations and containers on the GPU + type: object + encoder_slots: + description: Number of the encoder slots available on the GPU + example: 20 + format: int64 + type: integer + id: + description: ID of the GPU configured on the node + example: 0 + format: uint64 + type: integer + numa_node: + description: NUMA Node number for the GPU + example: 0 + format: uint64 + type: integer + pci_address: + description: PCI Bus Address used by the GPU + example: "00:08.0" + type: string + render_name: + description: PCI Bus Address used by the GPU + example: D129 + type: string + slots: + description: Number of the GPU slots available + example: 20 + format: int64 + type: integer + type: object + NodeGPUAllocation: + description: NodeGPUAllocation describes a single allocation on a GPU + properties: + encoder_slots: + description: Number of Encoder Slots allocated to the container + example: 1 + format: int64 + type: integer + gpus: + description: List of GPU IDs allocated to the container + example: + - 0 + - 1 + items: + format: uint64 + type: integer + type: array + slots: + description: Number of GPU Slots allocated to the container + example: 1 + format: int64 + type: integer + type: object + NodeGPUPatch: + description: NodeGPUPatch allows changing configuration for individual GPUs + properties: + encoder_slots: + description: Update the number of GPU encoder slots + example: 4 + format: int64 + type: integer + id: + description: ID of the GPU configured on the node + example: 0 + format: uint64 + type: integer + slots: + description: Update the number of the GPU slots available on the Node + example: 20 + format: int64 + type: integer + type: object + NodePatch: + description: NodePatch describes a request to update an existing node + properties: + cpu_allocation_rate: + description: Update the CPU allocation rate for the node + example: 4 + format: float + type: number + cpus: + description: Update the number of CPUs for the node + example: 4 + format: int64 + type: integer + gpu_encoder_slots: + description: Update the number of GPU encoder slots to configure on the node + example: 4 + format: int64 + type: integer + gpu_slots: + description: Update the number of GPU slots to configure on the node + example: 2 + format: int64 + type: integer + gpus: + items: + $ref: '#/definitions/NodeGPUPatch' + type: array + memory: + description: Update the memory (in GB) for the node + example: 2GB + type: string + memory_allocation_rate: + description: Update the memory allocation rate for the node + example: 2 + format: float + type: number + public_address: + description: Update the public IP Address of the node + example: 10.0.0.1 + format: ipv4 + type: string + subnet: + description: Update the subnet info of the node if the subnet of a node is changed + example: 10.0.0.1/24 + format: ipv4 + type: string + tags: + description: Update the tags of the node + example: + - created_by=anbox + - gpu=nvidia + items: + type: string + type: array + unscheduable: + description: DEPRECATED Flag in favour of `unschedulable` flag + example: false + type: boolean + unschedulable: + description: Flag used to remove the node from scheduler and not schedule containers on it + example: true + type: boolean + type: object + NodeStatus: + description: NodeStatus describes the current status of a node + format: int64 + type: integer + NodeVPU: + description: NodeVPU describes a single independent VPU available on a node + properties: + allocations: + additionalProperties: + $ref: '#/definitions/NodeVPUAllocation' + description: Map of current allocations on the VPU + type: object + id: + description: ID of the VPU + format: uint64 + type: integer + model: + description: Model name of the VPU + type: string + numa_node: + description: NUMA node the card sits on + format: uint64 + type: integer + slots: + description: Number of slots available on the VPU + format: int64 + type: integer + type: + description: 'Type of the VPU. Valid values are: unknown, netint' + type: string + type: object + NodeVPUAllocation: + description: NodeVPUAllocation describes a single allocation for a VPU + properties: + ids: + description: VPU IDs the allocation is for + items: + format: uint64 + type: integer + type: array + slots: + description: Number of slots used by this allocation + format: int64 + type: integer + type: object + NodesPost: + description: NodesPost describes a request to create a new node on AMS + properties: + address: + description: Internal IP address of the node + example: 10.0.0.1 + format: ipv4 + type: string + cpu_allocation_rate: + description: CPU allocation rate for the node + example: 4 + format: float + type: number + cpus: + description: Number of CPUs on the node + example: 4 + format: int64 + type: integer + gpu_encoder_slots: + description: Number of GPU encoder slots to configure on the node + example: 4 + format: int64 + type: integer + gpu_slots: + description: Number of GPU slots to configure on the node + example: 2 + format: int64 + type: integer + memory: + description: Memory (in GB) of the node + example: 8GB + type: string + memory_allocation_rate: + description: Memory allocation rate for the node + example: 2 + format: float + type: number + name: + description: Name of the node + example: lxd0 + type: string + network_acl_name: + description: Name of the network ACL to create on the LXD node + example: ams0 + type: string + network_bridge_mtu: + description: MTU for the configured network bridge on LXD + example: 1500 + format: int64 + type: integer + network_name: + description: Name of the network bridge to create on the LXD node + example: amsbr0 + type: string + network_subnet: + description: CIDR of the subnet to configure for the network bridge on LXD + example: 10.0.0.0/24 + format: ipv4 + type: string + public_address: + description: Public IP address of the node + example: 10.0.0.1 + format: ipv4 + type: string + storage_device: + description: Storage device to use for configuring LXD storage pools + example: /dev/sdb + type: string + storage_pool: + description: Name of the storage pool to use for configuring the LXD node + example: default + type: string + tags: + description: Tags to attach to the node + example: + - created_by=anbox + - gpu=nvidia + items: + type: string + type: array + trust_password: + description: Trust password for the LXD instance + example: sUp3rs3cr3t + type: string + unmanaged: + description: Flag used to control if AMS can manage the LXD node + example: false + type: boolean + type: object + Operation: + description: Operation represents a background operation + properties: + class: + description: Class of the operation + enum: + - task + - websocket + - token + example: task + type: string + created_at: + description: When the operation was created + format: date-time + type: string + description: + description: Human readable description of the operation + example: updating addon 3apqo5te + type: string + err: + description: The error string if the operation failed + type: string + id: + description: UUID of the operation + example: c6832c58-0867-467e-b245-2962d6527876 + type: string + may_cancel: + description: Whether this operation can be canceled (DELETE over REST) + example: false + type: boolean + metadata: + additionalProperties: {} + description: Metadata related to the operation and affected resources + example: {} + type: object + resources: + additionalProperties: + items: + type: string + type: array + description: |- + Dictionnary of resource types (containers, snapshots, images) + and affected resources + example: + applications: + - /1.0/applications/my-app + type: object + server_address: + description: The address of the server where the operation ran + format: ipv4 + type: string + status: + description: String version of the operation status + example: Running + type: string + status_code: + $ref: '#/definitions/StatusCode' + updated_at: + description: When the operation was updated + format: date-time + type: string + type: object + OperationResponse: + description: Operation + properties: + metadata: + $ref: '#/definitions/Operation' + operation: + example: /1.0/operations/66e83638-9dd7-4a26-aef2-5462814869a1 + type: string + status: + example: Operation created + type: string + status_code: + example: 100 + format: int64 + type: integer + type: + example: async + type: string + type: object + ServiceStatus: + description: ServiceStatus represents the status of the AMS service + properties: + api_extensions: + description: List of supported features for the service version running + example: + - addon_restore_hook + - container_logs + - registry + items: + type: string + type: array + api_status: + description: Shows the API stability status + example: stable + type: string + api_version: + description: API version for the service + example: "1.0" + type: string + auth: + description: Used to see if the client is trusted. Can be `trusted` or `untrusted`. + example: untrusted + type: string + auth_methods: + description: Authentication method used for the requests. + example: 2waySSL + items: + type: string + type: array + cluster_id: + description: ID of the subcluster the AMS instance is part of + example: cilsreunfpfec9b1ktg0 + type: string + cluster_name: + description: Name of the subcluster the AMS instance is part of + example: prod0 + type: string + type: object + StatusCode: + description: StatusCode represents a valid REST operation + format: int64 + type: integer + Task: + description: Task is the scheduling unit AMS uses for container launches + properties: + id: + description: ID of the task + example: c055dl0j1qm027422feg + type: string + object_id: + description: ID of the object that the task is operating on + example: c055dl0j1qm027422fe0 + type: string + object_type: + description: Type of the object that the task is operating on + example: container + type: string + status: + description: Status of the task + enum: + - created + - prepared + - started + - running + - stopped + - shutdown + - completed + - error + - deleted + - unknown + example: running + type: string + type: object + VersionGet: + description: VersionGet is the JSON response from the API version request method + properties: + version: + type: string + type: object + VersionResponse: + description: VersionResponse shows the version for the running service + properties: + version: + description: Version of the service + example: 1.18.2 + type: string + type: object + VideoEncoderType: + description: VideoEncoderType describes the type of a video encoder is used by an application + type: string +info: + description: |- + The Anbox Management Service (AMS) external REST API is the REST API used by + all AMS clients. Note that internal endpoints are not included in this + documentation. + + The AMS API is available over both a local unix+http and a remote https API. + Authentication for local users relies on group membership and access to the + unix socket. For remote users, the default authentication method is TLS client + certificates. + title: AMS external REST API + version: "1.0" +paths: + /1.0/: + get: + description: |- + This endpoint returns the service status and its supported API extensions. + It also returns whether the connection is trusted or not. + operationId: service_get + produces: + - application/json + responses: + "200": + description: Current config for the service + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + $ref: '#/definitions/ServiceStatus' + type: object + default: + $ref: '#/responses/InternalServerError' + summary: Get the status and features supported by the service + tags: + - service + /1.0/addons: + get: + description: This endpoint returns a list of addons in AMS. + operationId: addons_get + parameters: + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + allOf: + - $ref: '#/definitions/CollectionResponse' + properties: + metadata: + description: List of endpoints + example: |- + [ + "/1.0/addons/foo", + "/1.0/addons/bar" + ] + items: + type: string + type: array + type: object + default: + $ref: '#/responses/InternalServerError' + summary: Get a list of addons + tags: + - addons + post: + consumes: + - application/octet-stream + description: |- + This enpoint creates a new addon by uploading a package with the addon + manifest and hooks. The package format must be bzip2 or zip archive. + + Required Extensions: + `zip_archive_support`: To use the zip format, the server must have the extension. + operationId: addons_post + parameters: + - description: SHA-256 fingerprint of package e.g b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 + in: header + name: X-AMS-Fingerprint + type: string + - description: 'JSON encoded byte string of addon details e.g { "name": "my-addon" }' + in: header + name: X-AMS-Request + required: true + type: string + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "409": + $ref: '#/responses/ErrorAlreadyExists' + default: + $ref: '#/responses/InternalServerError' + summary: Create a new addon + tags: + - addons + /1.0/addons/{name}: + delete: + consumes: + - application/json + description: This endpoint deletes an addon stored in AMS. + operationId: addon_delete + parameters: + - description: Name of the addon to delete + in: path + name: name + required: true + type: string + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Delete an addon + tags: + - addons + get: + consumes: + - application/json + description: This endpoint gets the information of an addon stored in AMS. + operationId: addon_get + parameters: + - description: Name of the addon to retrieve + in: path + name: name + required: true + type: string + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + $ref: '#/definitions/Addon' + type: object + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Get an addon + tags: + - addons + patch: + consumes: + - application/octet-stream + description: |- + This endpoint updates an addon's metadata and creates a new addon version + for it. + operationId: addon_patch + parameters: + - description: SHA-256 fingerprint of addon payload e.g b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 + in: header + name: X-AMS-Fingerprint + type: string + - description: Json encoded byte string of addon details e.g {} + in: header + name: X-AMS-Request + required: true + type: string + - description: Name of the addon to update + in: path + name: name + required: true + type: string + produces: + - application/json + responses: + "202": + description: Success response of the service + headers: + Etag: + description: E-Tag of the resource + type: string + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Update an addon with a new package + tags: + - addons + /1.0/addons/{name}/{version}: + delete: + consumes: + - application/json + description: This endpoint deletes a specific version of an addon. + operationId: addon_version_delete + parameters: + - description: Name of the addon whose version needs to be deleted + in: path + name: name + required: true + type: string + - description: Version of the addon to delete + in: path + name: version + required: true + type: integer + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Delete an addon version + tags: + - addons + /1.0/addons?recursion=1: + get: + description: This endpoint returns a list of available addons in the cluster. + operationId: addons_get_recursion1 + parameters: + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + allOf: + - $ref: '#/definitions/CollectionResponse' + properties: + metadata: + items: + $ref: '#/definitions/Addon' + type: array + type: object + default: + $ref: '#/responses/InternalServerError' + summary: Get a list of addons expanded + tags: + - addons + /1.0/applications: + delete: + consumes: + - application/json + description: |- + This endpoint deletes multiple applications. If the deletion of a single application + fails the operation is aborted and an error is returned. + operationId: applications_delete + parameters: + - description: List of applications to delete + in: body + name: details + schema: + $ref: '#/definitions/ApplicationsDelete' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Delete multiple applications + tags: + - applications + get: + description: This endpoint returns a list of available applications. + operationId: applications_get + parameters: + - default: 0 + description: Index to start listing the records + in: query + name: offset + type: integer + - default: -1 + description: Limit the number of returned records + in: query + name: limit + type: integer + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + - description: Filter applications by id. This is an exact match for the string. + example: btavtegj1qm58qg7ru50 + in: query + name: id + type: string + - description: Filter applications by name. This is an exact match for the string. + example: my-app + in: query + name: name + type: string + - description: Filter applications by their instance_type. + example: a2.3 + in: query + name: instance_type + type: string + - description: Filter applications by status. + enum: + - initializing + - ready + - error + - deleted + example: initializing + in: query + name: status + type: string + - description: Filter applications by their boot package. + example: com.foo.bar + in: query + name: boot_package + type: string + - description: Filter immutable applications. + example: false + in: query + name: immutable + type: boolean + - description: Filter applications with automatic updates enabled. + example: false + in: query + name: inhibit_auto_updates + type: boolean + - description: Filter published applications. + example: false + in: query + name: published + type: boolean + - description: Filter applications by their attached addon names. + example: gms,ssh + in: query + name: addons + type: string + - description: Filter applications by their supported ABI architecture. + example: x86_64 + in: query + name: abi + type: string + - description: Filter applications by tags. + example: created_by=anbox,foo,bar + in: query + name: tags + type: string + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + allOf: + - $ref: '#/definitions/CollectionResponse' + properties: + metadata: + description: List of endpoints + example: |- + [ + "/1.0/applications/foo", + "/1.0/applications/bar" + ] + items: + type: string + type: array + type: object + default: + $ref: '#/responses/InternalServerError' + summary: Get a list of applications + tags: + - applications + post: + consumes: + - application/octet-stream + description: |- + This endpoint creates a new application in AMS using a manifest file. The + payload to upload must be a tarball compressed with bzip2 or a zip archive. + Also it must contain a **manifest.yaml** file which declares the basic + information for the creation of the application. + + Required Extensions: + `zip_archive_support`: To use the zip format, the server must have the extension. + To support the following syntax in the application **manifest.yaml** file, the + server requires the corresponding extensions: + Manifest Key | Required Extension | + ---------------- | -----------------------------------| + resources | application_resource_customization | + watchdog | application_watchdog_settings | + services | application_services_configuration | + version | application_manifest_version | + video-encoder | application_gpu_encoder | + operationId: application_post + parameters: + - default: false + description: Whether the application is based on a virtual machine or a container + in: query + name: vm + type: boolean + - description: SHA-256 fingerprint of the payload e.g b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 + in: header + name: X-AMS-Fingerprint + type: string + - description: A tarball or zip file + in: formData + name: upfile + required: true + type: file + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Create a new application + tags: + - applications + /1.0/applications/{id}: + delete: + consumes: + - application/json + description: This endpoint deletes an application and its versions from AMS. + operationId: application_delete + parameters: + - description: Id of the application + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "403": + $ref: '#/responses/ErrorForbidden' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Delete an application + tags: + - applications + get: + consumes: + - application/json + description: This endpoint gets the information about an application stored in AMS. + operationId: application_get + parameters: + - description: Id of the application + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: Success response of the service + headers: + Etag: + description: E-Tag of the resource + type: string + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + $ref: '#/definitions/Application' + type: object + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Get information about an application + tags: + - applications + patch: + consumes: + - application/octet-stream + description: |- + This endpoint updates an application with a new package of format bzip2 or + zip by uploading a new package to replace/update the existing package. + + Required Extensions: + `zip_archive_support`: To use the zip format, the server must have the extension. + operationId: application_patch_upload + parameters: + - description: Id of the application + in: path + name: id + required: true + type: string + - description: SHA-256 fingerprint of application e.g b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 + in: header + name: X-AMS-Fingerprint + type: string + - description: A tarball or zip file + in: formData + name: upfile + required: true + type: file + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Update an application with a new package + tags: + - applications + /1.0/applications/{id}/: + patch: + consumes: + - application/json + description: |- + This endpoint updates an applications's metadata only but not the package. + Changing the following fields will lead to the creation of a new application + version: + + SUPPORTED UPDATE FIELD | WILL CREATE A NEW APPLICATION VERSION | + ------------------------- | ----------------------------------------- | + image | no | + instance-type | no | + tags | no | + addons | no | + resources | no | + inhibit_auto_updates | no | + services | yes | + watchdog | yes | + boot_activity | yes | + required_permissions | yes | + video_encoder | yes | + manifest_version | yes | + + Required Extensions: + `application_partial_updates`: To use those fields that would create a new + application version on application update. + operationId: application_patch_meta + parameters: + - description: Id of the application to update + in: path + name: id + required: true + type: string + - description: Details of the attributes to update + in: body + name: details + schema: + $ref: '#/definitions/ApplicationPatch' + produces: + - application/json + responses: + "202": + description: Success response of the service + headers: + Etag: + description: E-Tag of the resource + type: string + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Update an applications's metadata + tags: + - applications + /1.0/applications/{id}/{version}: + delete: + consumes: + - application/json + description: This endpoint deletes a specific version of an application. + operationId: application_version_delete + parameters: + - description: Id of the application + in: path + name: id + required: true + type: string + - description: Version of the application + in: path + name: version + required: true + type: integer + - description: Details for the application version to delete + in: body + name: details + schema: + $ref: '#/definitions/ApplicationVersionDelete' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "403": + $ref: '#/responses/ErrorForbidden' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Delete a version of an application + tags: + - applications + get: + consumes: + - application/json + description: This endpoint gets the information of a specific version of an application. + operationId: application_version_get + parameters: + - description: Id of the application + in: path + name: id + required: true + type: string + - description: Version of the application + in: path + name: version + required: true + type: integer + produces: + - application/json + responses: + "200": + description: Success response of the service + headers: + X-AMS-ManifestSha256: + description: SHA-256 of the version manifest file + type: string + "400": + $ref: '#/responses/ErrorBadRequest' + "403": + $ref: '#/responses/ErrorForbidden' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Get information about an application's specific version + tags: + - applications + patch: + consumes: + - application/json + description: |- + This endpoint updates the information of a specific version of an application. + + Required Extensions: + `application_image_export`: The use of this API requires this extension + operationId: application_version_patch + parameters: + - description: Id of the application + in: path + name: id + required: true + type: string + - description: Version of the application + in: path + name: version + required: true + type: integer + - description: Details for the application version to update + in: body + name: details + schema: + $ref: '#/definitions/ApplicationVersionPatch' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "403": + $ref: '#/responses/ErrorForbidden' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Update a specific version of an application + tags: + - applications + /1.0/applications/{id}/{version}/manifest: + get: + consumes: + - application/json + description: |- + This endpoint gets the application manifest file of one specific application + version. + + Required Extensions: + `application_manifest_download`: The use of this API requires this extension + operationId: application_version_manifest_get + parameters: + - description: Id of the application to retrieve + in: path + name: id + required: true + type: string + - description: Version of the application to retrieve + in: path + name: version + required: true + type: integer + produces: + - application/json + responses: + "200": + description: Success response of the service + headers: + X-AMS-ManifestSha256: + description: SHA-256 of the manifest file + type: string + "400": + $ref: '#/responses/ErrorBadRequest' + "403": + $ref: '#/responses/ErrorForbidden' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Get the manifest for a specific version of an application + tags: + - applications + /1.0/applications/{id}/manifest: + get: + consumes: + - application/json + description: |- + This endpoint gets the latest application manifest file. + + Required Extensions: + `application_manifest_download`: The use of this API requires this extension + operationId: application_manifest_get + parameters: + - description: Id of the application to retrieve + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: Success response of the service + headers: + X-AMS-ManifestSha256: + description: SHA-256 of the manifest file + type: string + "400": + $ref: '#/responses/ErrorBadRequest' + "403": + $ref: '#/responses/ErrorForbidden' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Get an application's manifest + tags: + - applications + /1.0/applications?recursion=1: + get: + description: This endpoint returns a list of available applications in the cluster. + operationId: applications_get_recursion1 + parameters: + - default: 0 + description: Index to start listing the records + in: query + name: offset + type: integer + - default: -1 + description: Limit the number of returned records + in: query + name: limit + type: integer + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + - description: Filter applications by id. This is an exact match for the string. + example: btavtegj1qm58qg7ru50 + in: query + name: id + type: string + - description: Filter applications by name. This is an exact match for the string. + example: my-app + in: query + name: name + type: string + - description: Filter applications by their instance_type. + example: a2.3 + in: query + name: instance_type + type: string + - description: Filter applications by status. + enum: + - initializing + - ready + - error + - deleted + example: initializing + in: query + name: status + type: string + - description: Filter applications by their boot package. + example: com.foo.bar + in: query + name: boot_package + type: string + - description: Filter immutable applications. + example: false + in: query + name: immutable + type: boolean + - description: Filter applications with automatic updates enabled. + example: false + in: query + name: inhibit_auto_updates + type: boolean + - description: Filter published applications. + example: false + in: query + name: published + type: boolean + - description: Filter applications by their attached addon names. + example: gms,ssh + in: query + name: addons + type: string + - description: Filter applications by their supported ABI architecture. + example: x86_64 + in: query + name: abi + type: string + - description: Filter applications by tags. + example: created_by=anbox,foo,bar + in: query + name: tags + type: string + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + allOf: + - $ref: '#/definitions/CollectionResponse' + properties: + metadata: + description: List of endpoints + items: + $ref: '#/definitions/Application' + type: array + type: object + default: + $ref: '#/responses/InternalServerError' + summary: Get a list of applications with expanded object definitions + tags: + - applications + /1.0/certificates: + get: + description: This endpoint returns a list of certificates of trusted clients + operationId: certificates_get + parameters: + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + allOf: + - $ref: '#/definitions/CollectionResponse' + properties: + metadata: + description: List of endpoints + example: |- + [ + "/1.0/certificates/b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9", + "/1.0/certificates/a52c80e8337d3e08a52e52c6aa25ecfac473eae34a4880ed0088b9dbc2fagcd5" + ] + items: + type: string + type: array + type: object + default: + $ref: '#/responses/InternalServerError' + summary: Get a list of certificates + tags: + - certificates + post: + consumes: + - application/json + description: |- + This endpoint adds a new trusted client to the service by adding a new + client certificate. + operationId: certificates_post + parameters: + - description: Details of the certificate to create + in: body + name: details + required: true + schema: + $ref: '#/definitions/CertificatesPost' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "403": + $ref: '#/responses/ErrorForbidden' + "409": + $ref: '#/responses/ErrorAlreadyExists' + default: + $ref: '#/responses/InternalServerError' + summary: Add a new client certificate + tags: + - certificates + /1.0/certificates/{fingerprint}: + delete: + consumes: + - application/json + description: |- + This endpoint deletes a client's trusted certificate from the service's + trust store. + operationId: certificate_delete + parameters: + - description: SHA-256 fingerprint of the certificate + in: path + name: fingerprint + required: true + type: string + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Delete a client's trusted certificate + tags: + - certificates + get: + consumes: + - application/json + description: |- + The endpoint gets the information of a trusted client's certificate and its + fingerprint. + operationId: certificate_get + parameters: + - description: SHA-256 fingerprint of the certificate to retrieve + in: path + name: fingerprint + required: true + type: string + produces: + - application/json + responses: + "200": + description: Success response of the service + headers: + Etag: + description: E-Tag of the resource + type: string + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + $ref: '#/definitions/Certificate' + type: object + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Get the information about a certificate + tags: + - certificates + /1.0/certificates?recursion=1: + get: + description: This endpoint returns a list of certificates of trusted clients. + operationId: certificates_get_recursion1 + parameters: + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + allOf: + - $ref: '#/definitions/CollectionResponse' + properties: + metadata: + items: + $ref: '#/definitions/Certificate' + type: array + type: object + default: + $ref: '#/responses/InternalServerError' + summary: Get a list of expanded certificates + tags: + - certificates + /1.0/config: + get: + description: This endpoint shows the current configuration values for the service. + operationId: config_get + produces: + - application/json + responses: + "200": + description: Current config for the service + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + properties: + config: + description: Configuration of the service + properties: + agent.api.fingerprint: + default: "" + description: Fingerprint of certificate in the AMS trust store which is trusted when communicating with the stream agent + example: fd42316b32df + type: string + agent.api.token: + default: "" + description: Token to be used for API authentication with stream agent + example: foobar + type: string + agent.api.url: + default: "" + description: URL for stream agent API endpoint + example: https://foo.bar:9001 + type: string + application.addons: + default: "" + description: Enable addons globally for applications + example: my-addon + type: string + application.auto_publish: + default: true + description: Automatically publish the latest version for an application + type: boolean + application.auto_update: + default: true + description: Automatically update the images and applications to the latest versions + type: boolean + application.default_abi: + default: "" + description: Set a default support ABI architecture globally + example: arm64-v8a + type: string + application.max_published_versions: + default: 3 + description: Set the maximum number of application versions to publish + example: 3 + format: int32 + type: integer + container.apt_mirror: + default: "" + description: APT mirror to use for downloading dependencies inside the container + example: http://ports.ubuntu.com/ubuntu-ports + type: string + container.default_platform: + default: "null" + description: Platform to be forwarded to the container for running audio/video operations + enum: + - "null" + - webrtc + - swrast + example: webrtc + type: string + container.features: + default: "" + description: Enable additional android features + example: enable_virtual_keyboard,foo + type: string + container.security_updates: + default: true + description: Enable/disable security update for containers + type: boolean + core.debug_address: + default: "" + description: Address used to expose debug information on + example: https://127.0.0.1:9090 + type: string + core.proxy_http: + default: "" + description: Proxy variables inside container + example: http://my-proxy:8000 + type: string + core.proxy_https: + default: "" + description: Proxy variables inside container + example: http://my-proxy:8000 + type: string + core.proxy_ignore_hosts: + default: "" + description: Proxy variables inside container + example: localhost,127.0.0.1 + type: string + core.trust_password: + default: "" + description: |- + Trust password used to add remote clients. + AMS does not expose the actual password + but only the fact that it is set or not. + example: sUp3rS3cR3t + type: string + cpu.limit_mode: + default: scheduler + description: CPU limiting strategies used for a container + enum: + - scheduler + - pinning + example: scheduler + type: string + gpu.allocation_mode: + default: single + description: GPU allocation mode + enum: + - all + - single + example: single + type: string + gpu.type: + default: none + description: GPU type. Can be `none`, `nvidia`, `intel` or `amd` + enum: + - none + - nvidia + - amd + - intel + example: none + type: string + images.allow_insecure: + default: false + description: Allow insecure TLS for accessing image registry + type: boolean + images.auth: + default: "" + description: Auth token required to access the image registry + example: user:password + type: string + images.update_interval: + default: 5m + description: Interval used to check for image updates + example: 5m + type: string + images.url: + default: https://images.anbox-cloud.io/stable/ + description: Image registry URL + example: https://images.anbox-cloud.io/stable/ + type: string + images.version_lockstep: + default: true + description: Lock latest image version to align with latest AMS version + type: boolean + instance.apt_mirror: + default: "" + description: APT mirror to use for downloading dependencies inside the instance + example: http://ports.ubuntu.com/ubuntu-ports + type: string + instance.default_platform: + default: "null" + description: Platform to be forwarded to the instance for running audio/video operations + enum: + - "null" + - webrtc + - swrast + example: webrtc + type: string + instance.features: + default: "" + description: Enable additional android features + example: enable_virtual_keyboard,foo + type: string + instance.security_updates: + default: true + description: Enable/disable security update for instance + type: boolean + load_balancer.url: + default: "" + description: Set host URL for AMS to loadbalancer's URL + example: https://load-balanced-ams.com + type: string + node.queue_size: + default: 100 + description: Queue size for internal AMS workers + example: 100 + format: int32 + type: integer + node.workers_per_queue: + default: 4 + description: Number of internal workers for AMS + example: 4 + format: int32 + type: integer + registry.filter: + default: "" + description: Tag filters used for selecting applications when interacting with the registry + example: foo,bar + type: string + registry.fingerprint: + default: "" + description: Fingerprint used to verify the ceritifcate of the application registry + example: my-registry-fingerprint + type: string + registry.mode: + default: pull + description: Mode used to interact with the registry + enum: + - push + - pull + - manual + example: pull + type: string + registry.update_interval: + default: 1h + description: Interval used for checking for updates to applications + example: 1h + type: string + registry.url: + default: "" + description: Application registry URL + example: https://foo.bar/ + type: string + scheduler.strategy: + default: spread + description: Container scheduling startegy + enum: + - spread + - binpack + example: spread + type: string + type: object + type: object + type: object + default: + $ref: '#/responses/InternalServerError' + summary: Get the current configuration of the service + tags: + - config + patch: + consumes: + - application/json + description: This endpoint updates the configuration items for the service. + operationId: config_patch + parameters: + - description: Configuration items to change + in: body + name: details + schema: + $ref: '#/definitions/ConfigPost' + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "409": + $ref: '#/responses/ErrorAlreadyExists' + default: + $ref: '#/responses/InternalServerError' + summary: Update service configuration + tags: + - config + /1.0/containers: + delete: + consumes: + - application/json + description: |- + This endpoint deletes all specified containers. If the deletion of a single + container fails, the operation is aborted and an error is returned. + operationId: containers_delete + parameters: + - description: List of containers to delete + in: body + name: details + schema: + $ref: '#/definitions/ContainersDelete' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Delete multiple containers. + tags: + - containers + get: + description: This endpoint returns a list of container API endpoints. + operationId: containers_get + parameters: + - description: Maximum number of containers to provide + in: query + name: limit + type: integer + - description: Offset at which to start with listing containers + in: query + name: offset + type: integer + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + - description: Filter containers by id. This is an exact match for the string. + example: cilsreunfpfec9b1ktg0 + in: query + name: id + type: string + - description: Filter containers by name. This is an exact match for the string. + example: ams-cilsreunfpfec9b1ktg0 + in: query + name: name + type: string + - description: Filter containers by type. + enum: + - base + - regular + in: query + name: type + type: string + - description: Filter containers by status. + enum: + - created + - prepared + - stopped + - running + - error + - deleted + in: query + name: status + type: string + - description: Filter containers by the LXD node name. + example: lxd0 + in: query + name: node + type: string + - description: Filter containers by the application ID. This is an exact match for the string. + example: cilsiomnfpfec9b1kteg + in: query + name: app_id + type: string + - description: Filter containers by the application name. This is an exact match for the string. + example: my-app + in: query + name: app_name + type: string + - description: Filter containers by the application version. + example: 0 + in: query + name: app_version + type: integer + - description: Filter containers by the image ID. This is an exact match for the string. + example: cilsiomnfpfec9b1kteg + in: query + name: image_id + type: string + - description: Filter containers by the image version. + example: 0 + in: query + name: image_version + type: integer + - description: Filter containers by tags. + example: created_by=anbox,foo,bar + in: query + name: tags + type: string + produces: + - application/json + responses: + "200": + description: API endpoints + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + description: List of endpoints + example: |- + [ + "/1.0/containers/foo", + "/1.0/containers/bar" + ] + items: + type: string + type: array + type: object + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Get a list of containers + tags: + - containers + post: + consumes: + - application/json + description: |- + This endpoint creates a new container instance with the provided specification. + If AMS cannot fullfil the resource requirements for creating the instance, + the request will fail. + operationId: containers_post + parameters: + - description: Specification of the container to create + in: body + name: details + schema: + $ref: '#/definitions/ContainersPost' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Create a new container instance + tags: + - containers + /1.0/containers/{id}: + delete: + consumes: + - application/json + description: |- + This endpoint deletes a specific container. The deletion process happens + asynchronously. The operation progress can be checked via the returned + operation object. + operationId: container_delete + parameters: + - in: path + name: id + required: true + type: string + - description: Additional details for the delete operation. + in: body + name: details + schema: + $ref: '#/definitions/ContainerDelete' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Delete a specific container + tags: + - containers + get: + description: This endpoint returns information about a specific container instance. + operationId: container_get + parameters: + - in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: Container instance details + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + $ref: '#/definitions/Container' + type: object + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Get information about a specific container instance. + tags: + - containers + patch: + consumes: + - application/json + description: This endpoint allows changing the state of a specific container instance. + operationId: container_patch + parameters: + - in: path + name: id + required: true + type: string + - in: body + name: details + schema: + $ref: '#/definitions/ContainerPatch' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Update the state of a specific container instance + tags: + - containers + /1.0/containers/{id}/exec: + post: + consumes: + - application/json + description: |- + This endpoint is used to run a command in the container. The endpoint returns + an operation which will contain either 2 or 4 websockets. + In non-interactive mode, you'll get one websocket for each of stdin, stdout and stderr. + In interactive mode, a single bi-directional websocket is used for stdin and stdout/stderr. + + An additional "control" socket is always added on top which can be used for out of band + communication with LXD. This allows sending signals and window sizing information through. + operationId: container_exec_post + parameters: + - in: path + name: id + required: true + type: string + - description: Exec request + in: body + name: exec + schema: + $ref: '#/definitions/ContainerExecPost' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Execute a command in a container + tags: + - containers + /1.0/containers/{id}/logs: + get: + description: |- + This endpoint returns a container's collected log files. If a container has + been set to status "error" AMS will automatically collect, logs for further + inspection. + operationId: container_logs_get + parameters: + - in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: Collected log files + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + description: List of collected logs + example: |- + [ + "/1.0/containers/cilsiomnfpfec9b1kteg/logs/android.log", + "/1.0/containers/cilsiomnfpfec9b1kteg/logs/system.log" + ] + items: + type: string + type: array + type: object + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Get a list of collected log files for the container + tags: + - containers + /1.0/containers/{id}/logs/{name}: + get: + description: This endpoint returns the collected log file as a raw file. + operationId: container_logs_specific_get + parameters: + - in: path + name: id + required: true + type: string + - description: Name of the log to retrieve + in: path + name: name + required: true + type: string + produces: + - application/json + responses: + "200": + description: Raw file + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Retrieve a specific log file stored for the container + tags: + - containers + /1.0/containers?recursion=1: + get: + description: This endpoint returns a list of containers. + operationId: containers_get_recursion1 + parameters: + - description: Maximum number of containers to provide + in: query + name: limit + type: integer + - description: Offset at which to start with listing containers + in: query + name: offset + type: integer + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + - description: Filter containers by id. This is an exact match for the string. + example: cilsreunfpfec9b1ktg0 + in: query + name: id + type: string + - description: Filter containers by name. This is an exact match for the string. + example: ams-cilsreunfpfec9b1ktg0 + in: query + name: name + type: string + - description: Filter containers by type. + enum: + - base + - regular + in: query + name: type + type: string + - description: Filter containers by status. + enum: + - created + - prepared + - stopped + - running + - error + - deleted + in: query + name: status + type: string + - description: Filter containers by the LXD node name. + example: lxd0 + in: query + name: node + type: string + - description: Filter containers by the application ID. This is an exact match for the string. + example: cilsiomnfpfec9b1kteg + in: query + name: app_id + type: string + - description: Filter containers by the application name. This is an exact match for the string. + example: my-app + in: query + name: app_name + type: string + - description: Filter containers by the application version. + example: 0 + in: query + name: app_version + type: integer + - description: Filter containers by the image ID. This is an exact match for the string. + example: cilsiomnfpfec9b1kteg + in: query + name: image_id + type: string + - description: Filter containers by the image version. + example: 0 + in: query + name: image_version + type: integer + - description: Filter containers by tags. + example: created_by=anbox,foo,bar + in: query + name: tags + type: string + produces: + - application/json + responses: + "200": + description: API endpoints + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + description: List of containers + items: + $ref: '#/definitions/Container' + type: array + type: object + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Get a list of containers + tags: + - containers + /1.0/events: + get: + description: |- + This endpoint will upgrade the connection to a websocket on which + notifications will be sent. The client can subscribe to different types of + events or only listen to the required events. + operationId: events_get + parameters: + - default: all + description: Type of event. If left empty, the parameter corresponds to 'all' events. + enum: + - all + - operation + - lifecycle + in: formData + name: type + type: string + produces: + - application/json + responses: + "200": + description: |- + This api endpoint never returns. This websocket sends out JSON + dictionaries of the given format for events + schema: + $ref: '#/definitions/Event' + default: + $ref: '#/responses/InternalServerError' + summary: Listen to events for changes in AMS + tags: + - events + /1.0/images: + get: + description: This endpoint returns a list of images available in the cluster. + operationId: images_get + parameters: + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + allOf: + - $ref: '#/definitions/CollectionResponse' + properties: + metadata: + description: List of endpoints + example: |- + [ + "/1.0/images/foo", + "/1.0/images/bar" + ] + items: + type: string + type: array + type: object + default: + $ref: '#/responses/InternalServerError' + summary: Get a list of images + tags: + - images + post: + consumes: + - application/json + description: |- + This endpoint imports an image into AMS cluster from an image server using + its name. + operationId: image_post_import + parameters: + - description: Details of the image to create + in: body + name: details + required: true + schema: + $ref: '#/definitions/ImagesPost' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "409": + $ref: '#/responses/ErrorAlreadyExists' + default: + $ref: '#/responses/InternalServerError' + summary: Import an image + tags: + - images + /1.0/images/: + post: + consumes: + - application/octet-stream + description: |- + This endpoint allows the client to upload an image with a new package of + format gzip, bzip2 or xz. + operationId: image_post_upload + parameters: + - description: SHA-256 fingerprint of image e.g b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 + in: header + name: X-AMS-Fingerprint + type: string + - description: 'Json encoded byte string of image details for e.g { "name": "my-image", "default": false }' + in: header + name: X-AMS-Request + required: true + type: string + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "409": + $ref: '#/responses/ErrorAlreadyExists' + default: + $ref: '#/responses/InternalServerError' + summary: Upload a package to create an image + tags: + - images + /1.0/images/{id_or_name}: + get: + consumes: + - application/json + description: This endpoint gets the information about an image stored in AMS. + operationId: image_get + parameters: + - description: Id or name of the image to retrieve + in: path + name: id_or_name + required: true + type: string + - default: container + description: Type of the image variant to return could be `vm` or `container` + enum: + - container + - vm + in: query + name: type + type: string + produces: + - application/json + responses: + "200": + description: Success response of the service + headers: + Etag: + description: E-Tag of the resource + type: string + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + $ref: '#/definitions/Image' + type: object + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Get information about an image + tags: + - images + /1.0/images/{id}: + delete: + consumes: + - application/json + description: This endpoint deletes an image stored in AMS. + operationId: image_delete + parameters: + - description: Id of the image to delete + in: path + name: id + required: true + type: string + - description: details for deleting the image + in: body + name: details + schema: + $ref: '#/definitions/ImageDelete' + - default: container + description: Type of the image variant to return could be `vm` or `container` + enum: + - container + - vm + in: query + name: type + type: string + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Delete an image + tags: + - images + patch: + consumes: + - application/octet-stream + description: |- + This endpoint updates an existing image with a new package of format gzip, + bzip2 or xz. + operationId: image_patch_upload + parameters: + - description: SHA-256 fingerprint of image e.g b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 + in: header + name: X-AMS-Fingerprint + type: string + - description: 'Json encoded byte string of image details e.g { "name": "my-image", "default": false }' + in: header + name: X-AMS-Request + required: true + type: string + - description: Id of the image to update + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "202": + description: Success response of the service + headers: + Etag: + description: E-Tag of the resource + type: string + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Update an image with a new package to upload + tags: + - images + /1.0/images/{id}/: + patch: + consumes: + - application/json + description: This endpoint updates an image's metadata only but not the package. + operationId: image_patch_meta + parameters: + - description: Id of the image to update + in: path + name: id + required: true + type: string + - description: Details of the attributes to update + in: body + name: details + schema: + $ref: '#/definitions/ImagePatch' + produces: + - application/json + responses: + "202": + description: Success response of the service + headers: + Etag: + description: E-Tag of the resource + type: string + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Update an image's metadata + tags: + - images + /1.0/images/{id}/{version}: + delete: + consumes: + - application/json + description: This endpoint deletes a specific version of a stored image. + operationId: image_version_delete + parameters: + - description: Id or name of the image whose version needs to be deleted + in: path + name: id + required: true + type: string + - description: Version of the image to delete + in: path + name: version + required: true + type: integer + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Delete an image version + tags: + - images + /1.0/images?recursion=1: + get: + description: This endpoint returns a list of images available in the cluster. + operationId: images_get_recursion1 + parameters: + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + allOf: + - $ref: '#/definitions/CollectionResponse' + properties: + metadata: + items: + $ref: '#/definitions/Image' + type: array + type: object + default: + $ref: '#/responses/InternalServerError' + summary: Get the list of images expanded + tags: + - images + /1.0/instances: + delete: + consumes: + - application/json + description: |- + This endpoint deletes all specified instances. If the deletion of a single + instance fails, the operation is aborted and an error is returned. + operationId: instances_delete + parameters: + - description: List of instances to delete + in: body + name: details + schema: + $ref: '#/definitions/InstancesDelete' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Delete multiple instances. + tags: + - instances + get: + description: This endpoint returns a list of instance API endpoints. + operationId: instances_get + parameters: + - description: Maximum number of instances to provide + in: query + name: limit + type: integer + - description: Offset at which to start with listing instances + in: query + name: offset + type: integer + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + - description: Filter instances by id. This is an exact match for the string. + example: cilsreunfpfec9b1ktg0 + in: query + name: id + type: string + - description: Filter instances by name. This is an exact match for the string. + example: ams-cilsreunfpfec9b1ktg0 + in: query + name: name + type: string + - description: Filter base instances. The instances which are not base, are regular instances. + example: true + in: query + name: base + type: boolean + - description: Filter instances by type. + enum: + - vm + - container + in: query + name: type + type: string + - description: Filter instances by status. + enum: + - created + - prepared + - stopped + - running + - error + - deleted + in: query + name: status + type: string + - description: Filter instances by the LXD node name. + example: lxd0 + in: query + name: node + type: string + - description: Filter instances by the application ID. This is an exact match for the string. + example: cilsiomnfpfec9b1kteg + in: query + name: app_id + type: string + - description: Filter instances by the application name. This is an exact match for the string. + example: my-app + in: query + name: app_name + type: string + - description: Filter instances by the application version. + example: 0 + in: query + name: app_version + type: integer + - description: Filter instances by the image ID. This is an exact match for the string. + example: cilshrmnfpfec9b1kte0 + in: query + name: image_id + type: string + - description: Filter instances by the image version. + example: 0 + in: query + name: image_version + type: integer + - description: Filter instances by tags. + example: created_by=anbox,foo,bar + in: query + name: tags + type: string + produces: + - application/json + responses: + "200": + description: API endpoints + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + description: List of endpoints + example: |- + [ + "/1.0/instances/foo", + "/1.0/instances/bar" + ] + items: + type: string + type: array + type: object + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Get a list of instances + tags: + - instances + post: + consumes: + - application/json + description: |- + This endpoint creates a new instance instance with the provided specification. + If AMS cannot fullfil the resource requirements for creating the instance, + the request will fail. + operationId: instances_post + parameters: + - description: Specification of the instance to create + in: body + name: details + schema: + $ref: '#/definitions/InstancesPost' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Create a new instance + tags: + - instances + /1.0/instances/{id_or_name}: + delete: + consumes: + - application/json + description: |- + This endpoint deletes a specific instance. The deletion process happens + asynchronously. The operation progress can be checked via the returned + operation object. + operationId: instance_delete + parameters: + - in: path + name: id_or_name + required: true + type: string + - description: Additional details for the delete operation. + in: body + name: details + schema: + $ref: '#/definitions/InstanceDelete' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Delete a specific instance + tags: + - instances + get: + description: This endpoint returns information about a specific instance instance. + operationId: instance_get + parameters: + - in: path + name: id_or_name + required: true + type: string + produces: + - application/json + responses: + "200": + description: Instance instance details + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + $ref: '#/definitions/Instance' + type: object + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Get information about a specific instance instance. + tags: + - instances + patch: + consumes: + - application/json + description: This endpoint allows changing the state of a specific instance instance. + operationId: instance_patch + parameters: + - in: path + name: id_or_name + required: true + type: string + - in: body + name: details + schema: + $ref: '#/definitions/InstancePatch' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Update the state of a specific instance instance + tags: + - instances + /1.0/instances/{id_or_name}/exec: + post: + consumes: + - application/json + description: |- + This endpoint is used to run a command in the instance. The endpoint returns + an operation which will contain either 2 or 4 websockets. + In non-interactive mode, you'll get one websocket for each of stdin, stdout and stderr. + In interactive mode, a single bi-directional websocket is used for stdin and stdout/stderr. + + An additional "control" socket is always added on top which can be used for out of band + communication with LXD. This allows sending signals and window sizing information through. + operationId: instance_exec_post + parameters: + - in: path + name: id_or_name + required: true + type: string + - description: Exec request + in: body + name: exec + schema: + $ref: '#/definitions/InstanceExecPost' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Execute a command in a instance + tags: + - instances + /1.0/instances/{id_or_name}/logs: + get: + description: |- + This endpoint returns a instance's collected log files. If a instance has + been set to status "error" AMS will automatically collect, logs for further + inspection. + operationId: instance_logs_get + parameters: + - in: path + name: id_or_name + required: true + type: string + produces: + - application/json + responses: + "200": + description: Collected log files + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + description: List of collected logs + example: |- + [ + "/1.0/instances/cilsiomnfpfec9b1kteg/logs/android.log", + "/1.0/instances/cilsiomnfpfec9b1kteg/logs/system.log" + ] + items: + type: string + type: array + type: object + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Get a list of collected log files for the instance + tags: + - instances + /1.0/instances/{id_or_name}/logs/{name}: + get: + description: This endpoint returns the collected log file as a raw file. + operationId: instance_logs_specific_get + parameters: + - in: path + name: id_or_name + required: true + type: string + - description: Name of the log to retrieve + in: path + name: name + required: true + type: string + produces: + - application/json + responses: + "200": + description: Raw file + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Retrieve a specific log file stored for the instance + tags: + - instances + /1.0/instances?recursion=1: + get: + description: This endpoint returns a list of instances. + operationId: instances_get_recursion1 + parameters: + - description: Maximum number of instances to provide + in: query + name: limit + type: integer + - description: Offset at which to start with listing instances + in: query + name: offset + type: integer + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + - description: Filter instances by id. This is an exact match for the string. + example: cilsreunfpfec9b1ktg0 + in: query + name: id + type: string + - description: Filter instances by name. This is an exact match for the string. + example: ams-cilsreunfpfec9b1ktg0 + in: query + name: name + type: string + - description: Filter base instances. The instances which are not base, are regular instances. + example: true + in: query + name: base + type: boolean + - description: Filter instances by type. + enum: + - vm + - container + in: query + name: type + type: string + - description: Filter instances by status. + enum: + - created + - prepared + - stopped + - running + - error + - deleted + in: query + name: status + type: string + - description: Filter instances by the LXD node name. + example: lxd0 + in: query + name: node + type: string + - description: Filter instances by the application ID. This is an exact match for the string. + example: cilsiomnfpfec9b1kteg + in: query + name: app_id + type: string + - description: Filter instances by the application name. This is an exact match for the string. + example: my-app + in: query + name: app_name + type: string + - description: Filter instances by the application version. + example: 0 + in: query + name: app_version + type: integer + - description: Filter instances by the image ID. This is an exact match for the string. + example: cilshrmnfpfec9b1kte0 + in: query + name: image_id + type: string + - description: Filter instances by the image version. + example: 0 + in: query + name: image_version + type: integer + - description: Filter instances by tags. + example: created_by=anbox,foo,bar + in: query + name: tags + type: string + produces: + - application/json + responses: + "200": + description: API endpoints + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + description: List of instances + items: + $ref: '#/definitions/Instance' + type: array + type: object + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "500": + $ref: '#/responses/InternalServerError' + summary: Get a list of instances + tags: + - instances + /1.0/nodes: + get: + description: This endpoint returns a list of available nodes known to AMS. + operationId: nodes_get + parameters: + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + allOf: + - $ref: '#/definitions/CollectionResponse' + properties: + metadata: + description: List of endpoints + example: |- + [ + "/1.0/nodes/foo", + "/1.0/nodes/bar" + ] + items: + type: string + type: array + type: object + default: + $ref: '#/responses/InternalServerError' + summary: Get a list of nodes + tags: + - nodes + post: + consumes: + - application/json + description: |- + This endpoint creates a node in AMS which can be a precreated (unmanaged) + LXD node or a managed node created by AMS bootstrapping LXD. + operationId: node_post + parameters: + - description: AMS Node to create + in: body + name: details + schema: + $ref: '#/definitions/NodesPost' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "409": + $ref: '#/responses/ErrorAlreadyExists' + default: + $ref: '#/responses/InternalServerError' + summary: Create a node + tags: + - nodes + /1.0/nodes/{name}: + delete: + consumes: + - application/json + description: This endpoint deletes a node in AMS and its resources from the LXD cluster. + operationId: node_delete + parameters: + - description: Name of the node to delete + in: path + name: name + required: true + type: string + - description: Info required to delete the resource + in: body + name: details + schema: + $ref: '#/definitions/NodeDelete' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "409": + $ref: '#/responses/ErrorAlreadyExists' + default: + $ref: '#/responses/InternalServerError' + summary: Delete a node + tags: + - nodes + get: + consumes: + - application/json + description: |- + This endpoint returns information about a node in AMS and its resources from + the LXD cluster. + operationId: node_get + parameters: + - description: Name of the node to get + in: path + name: name + required: true + type: string + produces: + - application/json + responses: + "200": + description: Success response of the service + headers: + Etag: + description: E-Tag of the resource + type: string + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + $ref: '#/definitions/Node' + type: object + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "409": + $ref: '#/responses/ErrorAlreadyExists' + default: + $ref: '#/responses/InternalServerError' + summary: Get information about a node + tags: + - nodes + patch: + consumes: + - application/json + description: This endpoint updates a node and its resources in the cluster. + operationId: node_patch + parameters: + - description: Etag of the resource + in: header + name: Etag + type: string + - description: Name of the node to delete + in: path + name: name + required: true + type: string + - description: Info required to update the resource + in: body + name: details + schema: + $ref: '#/definitions/NodePatch' + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/definitions/OperationResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + "409": + $ref: '#/responses/ErrorAlreadyExists' + default: + $ref: '#/responses/InternalServerError' + summary: Update a node + tags: + - nodes + /1.0/nodes?recursion=1: + get: + description: This endpoint returns a list of available nodes known to AMS. + operationId: nodes_get_recursion1 + parameters: + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + allOf: + - $ref: '#/definitions/CollectionResponse' + properties: + metadata: + items: + $ref: '#/definitions/Node' + type: array + type: object + default: + $ref: '#/responses/InternalServerError' + summary: Get a list of nodes + tags: + - nodes + /1.0/operations: + get: + description: |- + This endpoint returns a list of URLs for operations that are currently in + progress or queued. + operationId: operations_get + parameters: + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + allOf: + - $ref: '#/definitions/CollectionResponse' + properties: + metadata: + description: List of endpoints + example: |- + [ + "/1.0/operations/foo", + "/1.0/operations/bar" + ] + items: + type: string + type: array + type: object + default: + $ref: '#/responses/InternalServerError' + summary: Get a list of operations + tags: + - operations + /1.0/operations/{uuid}: + delete: + consumes: + - application/json + description: |- + This endpoint is used to change the state of cancellable API to “cancelling” + rather than actually removing the operation entry. + operationId: operation_delete + parameters: + - description: uuid of the operation + in: path + name: uuid + required: true + type: string + produces: + - application/json + responses: + "202": + description: Success response of the service + schema: + $ref: '#/responses/EmptySyncResponse' + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Cancel an operation + tags: + - operations + get: + consumes: + - application/json + description: This endpoint gets the information about an operation. + operationId: operation_get + parameters: + - description: uuid of the operation + in: path + name: uuid + required: true + type: string + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + $ref: '#/definitions/Operation' + type: object + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Get the current status of an operation + tags: + - operations + /1.0/operations/{uuid}/wait: + get: + consumes: + - application/json + description: |- + This is a synchronous endpoint for a client to wait until an operation + reaches a final status. + operationId: operation_wait_get + parameters: + - description: uuid of the operation + in: path + name: uuid + required: true + type: string + - description: |- + The amount of time (in seconds) to wait until the operation is considered + to be timed out. If the value is assigned to -1, the operation will wait + infinitely until the monitored operation reaches a final status. + in: query + name: timeout + type: integer + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + $ref: '#/definitions/Operation' + type: object + "400": + $ref: '#/responses/ErrorBadRequest' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Wait for an operation to complete + tags: + - operations + /1.0/operations/{uuid}/websocket: + get: + description: |- + The connection to this endpoint is upgraded into a websocket connection, + speaking the protocol defined by the operation type. For example, in the + case of an exec operation, the websocket is the bidirectional pipe for + stdin/stdout/stderr to flow to and from the process inside the container. + In the case of migration, it will be the primary interface over which the + migration information is communicated. + operationId: operation_websocket_get + parameters: + - description: uuid of the operation + in: path + name: uuid + required: true + type: string + - description: |- + This is the secret that was provided when the operation was created. + Guests are allowed to connect only if they have the correct secret. + in: query + name: secret + type: string + responses: + "400": + $ref: '#/responses/ErrorBadRequest' + "401": + $ref: '#/responses/ErrorUnauthorized' + "403": + $ref: '#/responses/ErrorForbidden' + "404": + $ref: '#/responses/ErrorNotFound' + default: + $ref: '#/responses/InternalServerError' + summary: Get the websocket connection to monitor operation + tags: + - operations + /1.0/operations?recursion=1: + get: + description: |- + This endpoint returns a list of operations that are currently in progress + or queued. + operationId: operations_get_recursion1 + parameters: + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + allOf: + - $ref: '#/definitions/CollectionResponse' + properties: + metadata: + items: + $ref: '#/definitions/Operation' + type: array + type: object + default: + $ref: '#/responses/InternalServerError' + summary: Get a list of expanded operations + tags: + - operations + /1.0/tasks: + get: + description: This endpoint returns a list of tasks in AMS. + operationId: tasks_get + parameters: + - default: 0 + description: Expand the returned resource definition + enum: + - 0 + - 1 + in: query + name: recursion + type: integer + produces: + - application/json + responses: + "200": + description: Success response of the service + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + items: + $ref: '#/definitions/Task' + type: array + type: object + default: + $ref: '#/responses/InternalServerError' + summary: Get a list of tasks + tags: + - tasks + /1.0/version: + get: + description: This endpoint returns the current running version for the service. + operationId: version_get + produces: + - application/json + responses: + "200": + description: Current config for the service + schema: + allOf: + - $ref: '#/definitions/NoMetaSyncResponse' + properties: + metadata: + $ref: '#/definitions/VersionResponse' + type: object + default: + $ref: '#/responses/InternalServerError' + summary: Get the current version for the service + tags: + - service +responses: + EmptySyncResponse: + description: Empty sync response + schema: + properties: + metadata: + example: '{}' + status: + example: Success + type: string + status_code: + example: 200 + format: int64 + type: integer + type: + example: sync + type: string + type: object + ErrorAlreadyExists: + description: Already Exists + schema: + properties: + error: + example: already exists + type: string + error_code: + example: 409 + format: int64 + type: integer + type: + example: error + type: string + type: object + ErrorBadRequest: + description: Bad Request + schema: + properties: + error: + example: bad request + type: string + error_code: + example: 400 + format: int64 + type: integer + metadata: + example: '{}' + type: + example: error + type: string + type: object + ErrorForbidden: + description: Forbidden + schema: + properties: + error: + example: Not Authorized + type: string + error_code: + example: 403 + format: int64 + type: integer + type: + example: error + type: string + type: object + ErrorNotFound: + description: Not found + schema: + properties: + error: + example: not found + type: string + error_code: + example: 404 + format: int64 + type: integer + type: + example: error + type: string + type: object + ErrorServiceUnavailable: + description: Service Unavailable + schema: + properties: + error: + example: service unavailable + type: string + error_code: + example: 503 + format: int64 + type: integer + type: + example: error + type: string + type: object + ErrorUnauthorized: + description: Unauthorized + schema: + properties: + error: + example: missing secret + type: string + error_code: + example: 401 + format: int64 + type: integer + type: + example: error + type: string + type: object + InternalServerError: + description: Internal Server Error + schema: + properties: + error: + example: internal server error + type: string + error_code: + example: 500 + format: int64 + type: integer + metadata: + example: '{}' + type: + example: error + type: string + type: object +swagger: "2.0" \ No newline at end of file diff --git a/reference/anbox-https-api.md b/reference/api-reference/anbox-https-api.md similarity index 100% rename from reference/anbox-https-api.md rename to reference/api-reference/anbox-https-api.md diff --git a/reference/api-reference/gateway-api.md b/reference/api-reference/gateway-api.md new file mode 100644 index 00000000..f7578b11 --- /dev/null +++ b/reference/api-reference/gateway-api.md @@ -0,0 +1,29 @@ +# Stream Gateway API + + + +
+ + + + diff --git a/reference/api-reference/gateway-api.yaml b/reference/api-reference/gateway-api.yaml new file mode 100644 index 00000000..881be77c --- /dev/null +++ b/reference/api-reference/gateway-api.yaml @@ -0,0 +1,1129 @@ +basePath: /1.0/ +definitions: + api.ApplicationsGetResponse: + properties: + error: + description: Error is an optional error message + example: invalid body format + type: string + metadata: + items: + $ref: '#/definitions/api_gateway.Application' + type: array + status: + allOf: + - $ref: '#/definitions/api_gateway.ResponseStatus' + description: Status of the response + enum: + - success + - failed + - unknown + status_code: + description: StatusCode is the HTTP code of the response + type: integer + type: + allOf: + - $ref: '#/definitions/api_gateway.ResponseType' + description: Type of the operation + enum: + - sync + - async + - error + example: sync + type: object + api.Region: + properties: + name: + example: eu-west-1 + type: string + type: object + api.RegionsGetResponse: + properties: + error: + description: Error is an optional error message + example: invalid body format + type: string + metadata: + items: + $ref: '#/definitions/api.Region' + type: array + status: + allOf: + - $ref: '#/definitions/api_gateway.ResponseStatus' + description: Status of the response + enum: + - success + - failed + - unknown + status_code: + description: StatusCode is the HTTP code of the response + type: integer + type: + allOf: + - $ref: '#/definitions/api_gateway.ResponseType' + description: Type of the operation + enum: + - sync + - async + - error + example: sync + type: object + api.Screen: + properties: + density: + default: 240 + description: |- + Display density Android will be configured with. See https://developer.android.com/training/multiscreen/screendensities + for more details + example: 240 + minimum: 72 + type: integer + fps: + description: FPS the video stream will use + example: 25 + minimum: 1 + type: integer + height: + description: Height of the screen + example: 720 + minimum: 1 + type: integer + width: + description: Width of the screen + example: 1280 + minimum: 1 + type: integer + type: object + api.Session: + properties: + app: + description: |- + App that will be run in the session. + Applications are listed from AMS if they have been configured for streaming. + type: string + cluster_id: + description: ID of the cluster which the instance is deployed to + example: cluster0 + type: string + container_id: + description: |- + ID of the container powering the session. If no container was created yet + or the container is destroyed, the ID will be empty. + example: c05h1jj3pn6a8q46taug + type: string + id: + description: ID of the session. + example: e25f3e3bcead096461d89d8ab7043f14bdb1ecd39 + type: string + joinable: + description: Marks wether the session is joinable or not + type: boolean + region: + description: Region on which the instance is located. + example: eu-west-1 + type: string + status: + allOf: + - $ref: '#/definitions/api.SessionStatus' + description: |- + Status of the session. + created: sent creation request to an available agent. + active: container is up and running. + error: an error occurred and the container is stopped. + terminated: the container has stopped gracefully, either by manual command or timeout. + enum: + - created + - active + - error + - terminating + - terminated + status_message: + description: Message giving more information about the current status + example: Container failed to start + type: string + type: object + api.SessionConnectGetResponse: + properties: + error: + description: Error is an optional error message + example: invalid body format + type: string + metadata: + allOf: + - $ref: '#/definitions/api.SessionConnectGetResponseData' + description: Metadata contains session connection response data + status: + allOf: + - $ref: '#/definitions/api_gateway.ResponseStatus' + description: Status of the response + enum: + - success + - failed + - unknown + status_code: + description: StatusCode is the HTTP code of the response + type: integer + type: + allOf: + - $ref: '#/definitions/api_gateway.ResponseType' + description: Type of the operation + enum: + - sync + - async + - error + example: sync + type: object + api.SessionConnectGetResponseData: + properties: + stun_servers: + description: |- + StunServers is a list of STUN servers with their optional credentials. + They are passed to the client to figure out the best route to the + actual android instance. + They are used within the WebRTC protocol to negotiation a peer to peer transport + between the Anbox instance and the connecting client. + items: + $ref: '#/definitions/api_gateway.StunServer' + type: array + url: + description: URL is the endpoint to reach to start the WebRTC signaling process. + example: wss://api.example.com/1.0/session/e25fcd39/sockets/adb?token=foobar + type: string + type: object + api.SessionGetResponse: + properties: + error: + description: Error is an optional error message + example: invalid body format + type: string + metadata: + $ref: '#/definitions/api.Session' + status: + allOf: + - $ref: '#/definitions/api_gateway.ResponseStatus' + description: Status of the response + enum: + - success + - failed + - unknown + status_code: + description: StatusCode is the HTTP code of the response + type: integer + type: + allOf: + - $ref: '#/definitions/api_gateway.ResponseType' + description: Type of the operation + enum: + - sync + - async + - error + example: sync + type: object + api.SessionJoinPost: + properties: + screen: + allOf: + - $ref: '#/definitions/api.Screen' + description: |- + Definition of the screen dimensions. Allows changing the dimensions the containers are configured + with to match client expectation for the video stream. The maximum allowd screen resolution is + 4k (3840 x 2160). + type: object + api.SessionJoinResponse: + properties: + error: + description: Error is an optional error message + example: invalid body format + type: string + metadata: + $ref: '#/definitions/api.SessionJoinResponseData' + status: + allOf: + - $ref: '#/definitions/api_gateway.ResponseStatus' + description: Status of the response + enum: + - success + - failed + - unknown + status_code: + description: StatusCode is the HTTP code of the response + type: integer + type: + allOf: + - $ref: '#/definitions/api_gateway.ResponseType' + description: Type of the operation + enum: + - sync + - async + - error + example: sync + type: object + api.SessionJoinResponseData: + properties: + stun_servers: + description: |- + StunServers is a list of STUN servers with their optional credentials. + They are passed to the client to figure out the best route to the + actual android instance. + They are used within the WebRTC protocol to negotiation a peer to peer transport + between the Android instance and the connecting client. + items: + $ref: '#/definitions/api_gateway.StunServer' + type: array + url: + description: URL is the endpoint to reach to start the WebRTC signaling process. + example: https://api.example.com/1.0/session/e25fcd39/sockets/slave?token=foobar + type: string + type: object + api.SessionPost: + properties: + app: + description: Application the session should be created for + example: com.foo.bar + type: string + app_version: + description: |- + Which specific version of the application to launch for the session. If + not specified, the last published version is launched. + example: 0 + type: integer + ephemeral: + default: true + description: |- + Ephemeral controls whether the session should be deleted after the client + disconnects or not. If the containers runs into an error, the session is kept + if with Ephemeral set to true. + example: false + type: boolean + extra_data: + description: Extra data passed as part of the userdata to the container + example: userid=123 + type: string + idle_time_min: + description: |- + Time in minutes a session stays idle without any client connected. The + value "0" is special and causes the container to stay alive until the + session is terminated by an API call or the container decide on its own + to shutdown. + example: 5 + type: integer + joinable: + description: |- + Makes the session joinable by another client after the initial client left. + Requires idle_time_min to be set. + example: true + type: boolean + region: + description: |- + Region the session should be created in. If left empty a region is randomly + selected. + example: us-west-1 + type: string + screen: + allOf: + - $ref: '#/definitions/api.Screen' + description: |- + Definition of the screen dimensions. The maximum allowd screen resolution is + 4k (3840 x 2160). + type: object + api.SessionPostResponse: + properties: + error: + description: Error is an optional error message + example: invalid body format + type: string + metadata: + $ref: '#/definitions/api.SessionPostResponseData' + status: + allOf: + - $ref: '#/definitions/api_gateway.ResponseStatus' + description: Status of the response + enum: + - success + - failed + - unknown + status_code: + description: StatusCode is the HTTP code of the response + type: integer + type: + allOf: + - $ref: '#/definitions/api_gateway.ResponseType' + description: Type of the operation + enum: + - sync + - async + - error + example: sync + type: object + api.SessionPostResponseData: + properties: + id: + description: ID of the session. + example: e25f3e3bcead096461d89d8ab7043f14bdb1ecd39 + type: string + joinable: + description: Marks the session joinable after the initial client left + example: true + type: boolean + region: + description: |- + Region is a cloud region where the application will be launched. + Regions are registered dynamically by agents. + example: eu-west-2 + type: string + status: + allOf: + - $ref: '#/definitions/api.SessionStatus' + description: |- + Status of the session. + created: sent creation request to an available agent. + active: container is up and running. + error: an error occurred and the container is stopped. + terminated: the container has stopped gracefully, either by manual command or timeout. + enum: + - created + - active + - error + - terminating + - terminated + example: active + stun_servers: + description: |- + StunServers is a list of STUN servers with their optional credentials. + They are passed to the client to figure out the best route to the + actual android instance. + They are used within the WebRTC protocol to negotiation a peer to peer transport + between the Android instance and the connecting client. + items: + $ref: '#/definitions/api_gateway.StunServer' + type: array + url: + description: URL is the endpoint to reach to start the WebRTC signaling process. + type: string + type: object + api.SessionSharePost: + properties: + expiry_min: + default: 5 + description: ExpiryMin is the expiration time in minutes for the share URL + example: 5 + maximum: 1 + type: integer + type: + description: Type is the type of the session to be shared + example: adb + type: string + type: object + api.SessionSharePostResponse: + properties: + error: + description: Error is an optional error message + example: invalid body format + type: string + metadata: + allOf: + - $ref: '#/definitions/api.SessionSharePostResponseData' + description: Metadata contains a URL that a client can connect to interact + with a session + status: + allOf: + - $ref: '#/definitions/api_gateway.ResponseStatus' + description: Status of the response + enum: + - success + - failed + - unknown + status_code: + description: StatusCode is the HTTP code of the response + type: integer + type: + allOf: + - $ref: '#/definitions/api_gateway.ResponseType' + description: Type of the operation + enum: + - sync + - async + - error + example: sync + type: object + api.SessionSharePostResponseData: + properties: + expiry_min: + description: The expiration time in minutes for the share URL + example: 5 + type: integer + url: + description: URL is the endpoint to reach to start the WebRTC signaling process. + example: https://api.example.com/1.0/session/e25fcd39/connect?type=adb&token=foobar + type: string + type: object + api.SessionStatus: + enum: + - created + - active + - error + - terminating + - terminated + type: string + x-enum-varnames: + - SessionStatusCreated + - SessionStatusActive + - SessionStatusError + - SessionStatusTerminating + - SessionStatusTerminated + api.SessionsDelete: + properties: + ids: + items: + type: string + type: array + type: object + api.SessionsDeleteError: + properties: + error_message: + description: ErrorMessage contains information about the failure + type: string + session_id: + description: SessionID is the id of the session that failed to be deleted + type: string + status_code: + description: StatusCode relevant to the error + type: integer + type: object + api.SessionsDeleteResponse: + properties: + error: + description: Error is an optional error message + example: invalid body format + type: string + metadata: + properties: + deleted_sessions: + description: DeletedSessions is the list of sessions IDs that were successfully + deleted + items: + type: string + type: array + errors: + description: Errors, if not empty, contains the list of sessions that + failed to be deleted + items: + $ref: '#/definitions/api.SessionsDeleteError' + type: array + type: object + status: + allOf: + - $ref: '#/definitions/api_gateway.ResponseStatus' + description: Status of the response + enum: + - success + - failed + - unknown + status_code: + description: StatusCode is the HTTP code of the response + type: integer + type: + allOf: + - $ref: '#/definitions/api_gateway.ResponseType' + description: Type of the operation + enum: + - sync + - async + - error + example: sync + type: object + api.SessionsGetResponse: + properties: + error: + description: Error is an optional error message + example: invalid body format + type: string + metadata: + items: + type: string + type: array + status: + allOf: + - $ref: '#/definitions/api_gateway.ResponseStatus' + description: Status of the response + enum: + - success + - failed + - unknown + status_code: + description: StatusCode is the HTTP code of the response + type: integer + total_size: + description: TotalSize specifies how many session objects are available in + total + type: integer + type: + allOf: + - $ref: '#/definitions/api_gateway.ResponseType' + description: Type of the operation + enum: + - sync + - async + - error + example: sync + type: object + api.StatusGetResponseAuthenticated: + properties: + error: + description: Error is an optional error message + example: invalid body format + type: string + metadata: + $ref: '#/definitions/api.StatusGetResponseAuthenticatedData' + status: + allOf: + - $ref: '#/definitions/api_gateway.ResponseStatus' + description: Status of the response + enum: + - success + - failed + - unknown + status_code: + description: StatusCode is the HTTP code of the response + type: integer + type: + allOf: + - $ref: '#/definitions/api_gateway.ResponseType' + description: Type of the operation + enum: + - sync + - async + - error + example: sync + type: object + api.StatusGetResponseAuthenticatedData: + properties: + agents: + type: integer + database_nodes: + type: integer + status: + $ref: '#/definitions/api_gateway.ServiceStatus' + type: object + api_gateway.Application: + properties: + name: + example: com.foo.bar + type: string + type: object + api_gateway.Response: + properties: + error: + description: Error is an optional error message + example: invalid body format + type: string + status: + allOf: + - $ref: '#/definitions/api_gateway.ResponseStatus' + description: Status of the response + enum: + - success + - failed + - unknown + status_code: + description: StatusCode is the HTTP code of the response + type: integer + type: + allOf: + - $ref: '#/definitions/api_gateway.ResponseType' + description: Type of the operation + enum: + - sync + - async + - error + example: sync + type: object + api_gateway.ResponseStatus: + enum: + - success + - failed + - unknown + type: string + x-enum-varnames: + - ResponseStatusSuccess + - ResponseStatusFailed + - ResponseStatusUnknown + api_gateway.ResponseType: + enum: + - sync + - async + - error + type: string + x-enum-varnames: + - ResponseTypeSync + - ResponseTypeAsync + - ResponseTypeError + api_gateway.ServiceStatus: + enum: + - healthy + - unhealthy + type: string + x-enum-varnames: + - ServiceStatusHealthy + - ServiceStatusUnhealthy + api_gateway.StunServer: + properties: + password: + description: |- + Password is the optional password to authenticate on the STUN/TURN server. + It is usually unique to a session. + example: 3f14bdb1ecd3 + type: string + urls: + description: URLs is the list of endpoints the STUN/TURN server can be reached + on. + example: + - https://stun.foo.com + - https://turn.foo.com + items: + type: string + type: array + username: + description: |- + Username is the optional username to authenticate on the STUN/TURN server. + It is usually unique to a session. + example: f3e3bcead096461d8 + type: string + type: object +info: + contact: + email: indore@lists.canonical.com + name: Canonical + url: https://ubuntu.com/support + description: "The Anbox Stream Gateway provides federated access to Anbox Cloud + regions.\nIt's primary purpose is it to connect clients to individual Android + containers and enable WebRTC based streaming.\nTt does so via `sessions` which + are 'chatrooms' for clients and stream providers to communicate.\nWhen the communication + is established, the stream is sent directly from one peer to another.\n\nThe Anbox + Stream Gateway keeps things simple and only manages what is required to make streaming + happen.\nOther components can invoke its REST API to add other capabilities on + top such as user management, limiting, etc.\n\n## Authentication\n\nAll calls + to the Stream Gateway must be authenticated. Authentication takes the form of + a single\ntoken per client you must embed in your requests\n\n### 1. Creating + the token\n\nAn internal HTTP API is exposed for managing client tokens. This + API is only accessible via a Unix domain socket\nwhich resides at `/var/snap/anbox-stream-gateway/common/service/unix.socket` + by default. \nFor convenience, the Stream Gateway has a built-in client designed + to communicate to that API.\n\n**Creating a token**\n\n $ anbox-stream-gateway + account create my-client\n AgEUYW5ib3gtc3RyZWFtLWdhdGV3YXkCBGFzZGYAAhkyMDIwLTA2LTIzVDA5OjMyOjE5KzAyOjAwAAAGIDcZMdTrdNdJB6kzjoXyx1_T6s8-0C1AQSyzaA_GHLYQ\n\n**Deleting + a token**\n\n $ anbox-stream-gateway account delete my-client\n Account + my-client deleted successfully\n\nYou can type `anbox-stream-gateway --help` to + list all commands\n\n### 2. Using the token in your requests\n\nWhen making requests + to the Stream Gateway API you can either place the token in the request HTTP headers + or\nin the query parameters.\n\n**Request headers**\n\n $ curl -X GET https://20.234.75.29:4000/1.0/sessions + \\\n -H 'authorization=macaroon root=AgEUYW5ib3...QSyzaA_GHLYQ'\n\n**Query + parameters**\n\n $ curl -X GET https://20.234.75.29:4000/1.0/sessions?api_token=AgEUYW5ib3...QSyzaA_GHLYQ\n" + license: + name: Proprietary + title: Anbox Stream Gateway + version: "1.0" +paths: + /1.0/applications: + get: + description: Return all applications that were registered via AMS and that support + streaming. + operationId: handle-get-applications + responses: + "200": + description: List of applications + schema: + $ref: '#/definitions/api.ApplicationsGetResponse' + security: + - AuthToken: [] + summary: Get applications + tags: + - application + /1.0/regions: + get: + description: |- + Regions are cloud regions, allowing clients to be as close as possible + to the agent running the Android container. + + The list is dynamic and regions might change as agents are added or removed. + operationId: handle-get-regions + responses: + "200": + description: OK + schema: + $ref: '#/definitions/api.RegionsGetResponse' + security: + - AuthToken: [] + summary: Get regions + tags: + - region + /1.0/session/{id}/sockets/adb: + get: + description: |- + A websocket connection endpoint which initiates the signaling process with the adb role. + This URL is returned then joining a session along with its credentials. + operationId: handle-adb-connect-session + responses: {} + summary: Join session as ADB client + tags: + - session + /1.0/session/{id}/sockets/master: + get: + description: |- + A websocket connection endpoint which initiates the signaling process with the master role. + You MUST call /sessions/{id}/join beforehand to prepare the android container. + operationId: handle-master-connect-session + responses: {} + summary: Join session as master + tags: + - session + /1.0/session/{id}/sockets/slave: + get: + description: |- + A websocket connection endpoint which initiates the signaling process with the slave role. + This URL is returned then joining a session along with its credentials. + operationId: handle-slave-connect-session + responses: {} + summary: Join session as slave + tags: + - session + /1.0/sessions: + delete: + operationId: handle-delete-sessions + parameters: + - description: List of session IDs to delete + in: body + name: ids + required: true + schema: + $ref: '#/definitions/api.SessionsDelete' + - description: Force deletion even if agent is not available. This may leave + a container around on the agent. + in: query + name: force + type: boolean + - description: Set to true to wait for the response (can take a long time for + lots of sessions) or to false to return without waiting for all sessions + to be deleted. Defaults to false + in: query + name: sync + type: boolean + responses: + "200": + description: Contains an array of deleted sessions as well as potential + errors + schema: + $ref: '#/definitions/api.SessionsDeleteResponse' + "202": + description: Returned when sync=true. Watch the session list for progress + on the operation + schema: + $ref: '#/definitions/api_gateway.Response' + "207": + description: Some sessions could not be deleted + schema: + $ref: '#/definitions/api_gateway.Response' + "400": + description: Invalid request body + schema: + $ref: '#/definitions/api_gateway.Response' + "404": + description: Non-existent sessions + schema: + $ref: '#/definitions/api_gateway.Response' + "500": + description: Internal issue + schema: + $ref: '#/definitions/api_gateway.Response' + security: + - AuthToken: [] + summary: Batch delete sessions + tags: + - session + get: + operationId: handle-get-sessions + parameters: + - description: Filter returned sessions by given status + in: query + name: status + type: string + - description: Return full session objects rather than just their ID + in: query + name: recursive + type: boolean + - description: Limit number of results returned + in: query + name: limit + type: integer + - description: Offset to list results from + in: query + name: offset + type: integer + - description: Field of the session to sort results by + in: query + name: sort_by + type: string + - description: 'Sort order of the returned results. Possible values are: asc, + desc' + in: query + name: sort_order + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/api.SessionsGetResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api_gateway.Response' + security: + - AuthToken: [] + summary: Get all sessions + tags: + - session + post: + consumes: + - application/json + description: |- + Create a new session based on an application, application version, region + and screen details. The newly created session is started immediately after + being created. The returned session details can be used to immediately start + the signaling process. If an application version is not specified, the latest + application version will always be in use for a session creation. + operationId: handle-new-session + parameters: + - description: Session details + in: body + name: session + required: true + schema: + $ref: '#/definitions/api.SessionPost' + produces: + - application/json + responses: + "201": + description: Newly created session along with the information needed to + connect to it + schema: + $ref: '#/definitions/api.SessionPostResponse' + "400": + description: Invalid body or missing application + schema: + $ref: '#/definitions/api_gateway.Response' + "404": + description: No agent can host the container + schema: + $ref: '#/definitions/api_gateway.Response' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api_gateway.Response' + security: + - AuthToken: [] + summary: Create session + tags: + - session + /1.0/sessions/{id}: + delete: + operationId: handle-delete-session + parameters: + - description: Session ID + in: path + name: id + required: true + type: string + - description: Force deletion even if agent is not available. This may leave + a container around on the agent. + in: query + name: force + type: boolean + - description: Set to true to wait for the response or to false to return early + without waiting for the session to be deleted + in: query + name: sync + type: boolean + responses: + "200": + description: Empty response to indicate success + schema: + $ref: '#/definitions/api_gateway.Response' + "400": + description: Invalid session ID + schema: + $ref: '#/definitions/api_gateway.Response' + "404": + description: Non-existent session + schema: + $ref: '#/definitions/api_gateway.Response' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api_gateway.Response' + security: + - AuthToken: [] + summary: Delete a session + tags: + - session + get: + description: Returns a session from its ID. + operationId: handle-get-session + parameters: + - description: Session ID + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: The requested session + schema: + $ref: '#/definitions/api.SessionGetResponse' + "400": + description: Invalid session ID + schema: + $ref: '#/definitions/api_gateway.Response' + "404": + description: Non-existent session + schema: + $ref: '#/definitions/api_gateway.Response' + security: + - AuthToken: [] + summary: Get session + tags: + - session + /1.0/sessions/{id}/connect: + get: + description: |- + Connect an existing running session from a client. The returned + object contains a URL with the required credentials for a client + to connect to the remote Anbox instance. + operationId: handle-connect-session + responses: + "200": + description: Object containing a URL with the required credentials to connect + to the remote Anbox instance + schema: + $ref: '#/definitions/api.SessionConnectGetResponse' + "400": + description: Missing session ID, inactive session, invalid connection type + schema: + $ref: '#/definitions/api_gateway.Response' + "401": + description: Authorization failed + schema: + $ref: '#/definitions/api_gateway.Response' + "500": + description: Error when failing to generate auth token/STUN servers, or + setup connection + schema: + $ref: '#/definitions/api_gateway.Response' + summary: Connect a session + tags: + - session + /1.0/sessions/{id}/join: + post: + description: |- + Join an existing running session. The session must already be running. The + returned object contains a URL with the required credentials for a client + to join the signaling process. + operationId: handle-join-session + parameters: + - description: Additional information about the join request + in: body + name: session + required: true + schema: + $ref: '#/definitions/api.SessionJoinPost' + responses: + "200": + description: Object containing the slave URL as well as optional additional + STUN/TURN servers + schema: + $ref: '#/definitions/api.SessionJoinResponse' + "400": + description: Missing session ID or invalid session state + schema: + $ref: '#/definitions/api_gateway.Response' + "404": + description: The session does not exist + schema: + $ref: '#/definitions/api_gateway.Response' + "500": + description: Error when trying to generate session details + schema: + $ref: '#/definitions/api_gateway.Response' + security: + - AuthToken: [] + summary: Join session + tags: + - session + /1.0/sessions/{id}/share: + post: + description: |- + Share an existing running session with a client. The returned + object contains a URL for a client to interact with a session + operationId: handle-share-session + parameters: + - description: Required parameters to the share request + in: body + name: session + required: true + schema: + $ref: '#/definitions/api.SessionSharePost' + responses: + "200": + description: Object containing a URL for a client to interact with a session + schema: + $ref: '#/definitions/api.SessionSharePostResponse' + "400": + description: Missing session ID, invalid request content, share type or + expiration time + schema: + $ref: '#/definitions/api_gateway.Response' + "404": + description: The session does not exist + schema: + $ref: '#/definitions/api_gateway.Response' + "500": + description: Error when failing to generate auth token + schema: + $ref: '#/definitions/api_gateway.Response' + security: + - AuthToken: [] + summary: Share session + tags: + - session + /1.0/status: + get: + description: | + Returns the current status of the Gateway service along with some indicators that + can be helpful to determine larger issues. The Gateway can be either healthy or unhealthy. + Please note that a healthy status does not necessarily mean that a deployment is fully working. + Other issues can affect the Streaming Stack but a healthy status only guarantees that the Gateway itself + is not experiencing issues that would prevent it from working normally. + Checking for status can take up to 7 seconds. Note that this is the upper bound, in normal + circumstances, the timing will be much lower and timings higher than a couple seconds are usually + indicators or something wrong (network issue, node restarted, etc). + operationId: handle-get-status + produces: + - application/json + responses: + "200": + description: Only status is present if the request is not authenticated + schema: + $ref: '#/definitions/api.StatusGetResponseAuthenticated' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api_gateway.Response' + "503": + description: The Gateway is not fully started + schema: + $ref: '#/definitions/api_gateway.Response' + summary: Returns the Gateway service status. + tags: + - status +swagger: "2.0" \ No newline at end of file diff --git a/reference/api-reference.md b/reference/api-reference/landing.md similarity index 67% rename from reference/api-reference.md rename to reference/api-reference/landing.md index c966182f..84e55f12 100644 --- a/reference/api-reference.md +++ b/reference/api-reference/landing.md @@ -5,31 +5,25 @@ Anbox Cloud includes various APIs to help you build solutions with it. This page All these APIs except for the {ref}`anbox-https-api` have an auto-generated Open API specification describing its API endpoints. -## Available APIs - -### AMS HTTP API +## AMS HTTP API The AMS services provide an HTTP based API to help you manage all of its objects. Internally the `amc` client uses the same API to perform its operation. -You can find the OpenAPI specification [here](https://canonical.github.io/anbox-cloud.github.com/latest/ams/). - -### Anbox HTTP API +## Anbox HTTP API The Anbox runtime inside each instance managed by the AMS provides an HTTP API over a UNIX domain socket that helps interacting with various functionalities offered by Anbox. This includes the injection of position or sensor events into Android, among other things. You can find the API specification at {ref}`anbox-https-api`. -### Anbox Stream Gateway API +## Anbox Stream Gateway API The Anbox Stream Gateway service provides an API endpoint to help you to manage streaming sessions. -You can find the OpenAPI specification [here](https://canonical.github.io/anbox-cloud.github.com/latest/anbox-stream-gateway). - ```{toctree} :hidden: -AMS HTTP API +ams-api anbox-https-api Anbox Platform API -Stream gateway API +gateway-api ``` diff --git a/reference/landing.md b/reference/landing.md index b9b8e926..db6c29d7 100644 --- a/reference/landing.md +++ b/reference/landing.md @@ -77,7 +77,7 @@ Anbox Cloud images appliance-preseed appliance-configuration sdks -api-reference +api-reference/landing.md application-manifest cmd-ref/landing.md component-versions