From 4df63a83c93ba0f591eb78110e184bfef0f76535 Mon Sep 17 00:00:00 2001 From: Dan Duvall Date: Wed, 19 Sep 2018 11:06:46 -0700 Subject: Provide OpenAPI spec for Blubberoid Wrote an OpenAPI 3.0 spec for Blubberoid that provides `x-amples` entries compatible with service-checker. The written spec includes basic schema for Blubber config objects that may be later factored out for use in validation. Note that OpenAPI 3.0 supports only the v4 draft of the JSON Schema standard, so some parts of the configuration could not be fully described. Specifically, v4 does not include the `patternProperties` definition introduced in the JSON Schema v6 draft that would allow us to describe `variants` and `runs.environment` and everything beneath. Blubberoid was refactored slightly to incorporate the new spec as well as assume JSON as the canonical and default configuration format. It was also refactored to include a versioned namespace ("v1") after the server endpoint. Bug: T205920 Change-Id: I28a341aa503b8920d802715660d4c4d62be45475 --- api/openapi-spec/blubberoid.yaml | 217 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 api/openapi-spec/blubberoid.yaml (limited to 'api') diff --git a/api/openapi-spec/blubberoid.yaml b/api/openapi-spec/blubberoid.yaml new file mode 100644 index 0000000..b0ee9ae --- /dev/null +++ b/api/openapi-spec/blubberoid.yaml @@ -0,0 +1,217 @@ +--- +openapi: '3.0.0' +info: + title: Blubberoid + description: > + Blubber is a highly opinionated abstraction for container build + configurations. + version: {{ .Version }} +paths: + /v1/{variant}: + post: + summary: > + Generates a valid Dockerfile based on Blubber YAML configuration + provided in the request body and the given variant name. + requestBody: + description: A valid Blubber configuration. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/v3.Config' + application/yaml: + schema: + type: string + application/x-yaml: + schema: + type: string + responses: + '200': + description: OK. Response body should be a valid Dockerfile. + content: + text/plain: + schema: + type: string + '400': + description: Bad request. The YAML request body failed to parse. + '404': + description: No variant name was provided in the request path. + '422': + description: Provided Blubber config parsed correctly but failed validation. + '5XX': + description: An unexpected service-side error. + + x-amples: + - title: Mathoid test variant + request: + params: + variant: test + headers: + Content-Type: application/json + body: { + "version": "v3", + "base": "docker-registry.wikimedia.org/nodejs-slim", + "apt": { "packages": ["librsvg2-2"] }, + "lives": { "in": "/srv/service" }, + "variants": { + "build": { + "base": "docker-registry.wikimedia.org/nodejs-devel", + "apt": { + "packages": ["librsvg2-dev", "git", "pkg-config", "build-essential"] + }, + "node": { "requirements": ["package.json"] }, + "runs": { "environment": { "LINK": "g++" } } + }, + "test": { "includes": ["build"], "entrypoint": ["npm", "test"] } + } + } + response: + status: 200 + headers: + content-type: text/plain + body: /^FROM docker-registry.wikimedia.org\/nodejs-devel/ + +components: + schemas: + v3.Config: + title: Top-level blubber configuration (version v3) + allOf: + - $ref: '#/components/schemas/v3.CommonConfig' + - type: object + properties: + required: [version, variants] + version: + type: string + description: Blubber configuration version + variants: + type: object + description: Configuration variants (e.g. development, test, production) + additionalProperties: true + # OpenAPI 3.0 supports only v4 of the JSON Schema draft spec and + # cannot define schema for object properties with arbitrary + # names, but the following commented section is included to be + # useful to humans for the time being. It patiently awaits v6 + # json schema draft support before its uncommenting. + # + # patternProperties: + # "^[a-zA-Z][a-zA-Z0-9\-\.]+[a-zA-Z0-9]$": + # $ref: '#/components/schemas/v3.VariantConfig' + + v3.CommonConfig: + type: object + properties: + base: + type: string + description: Base image reference + apt: + type: object + properties: + packages: + type: array + description: Packages to install from APT sources of base image + items: + type: string + node: + type: object + properties: + env: + type: string + description: Node environment (e.g. production, etc.) + requirements: + type: array + description: Files needed for Node package installation (e.g. package.json, package-lock.json) + items: + type: string + python: + type: object + properties: + version: + type: string + description: Python binary present in the system (e.g. python3) + requirements: + type: array + description: Files needed for Python package installation (e.g. requirements.txt, etc.) + items: + type: string + builder: + type: object + properties: + command: + type: array + description: Command and arguments of an arbitrary build command + items: + type: string + requirements: + type: array + description: Files needed by the build command (e.g. Makefile, ./src/, etc.) + items: + type: string + lives: + type: object + properties: + as: + type: string + description: Owner (name) of application files within the container + uid: + type: integer + description: Owner (UID) of application files within the container + gid: + type: integer + description: Group owner (GID) of application files within the container + in: + type: string + description: Application working directory within the container + runs: + type: object + properties: + as: + type: string + description: Runtime process owner (name) of application entrypoint + uid: + type: integer + description: Runtime process owner (UID) of application entrypoint + gid: + type: integer + description: Runtime process group (GID) of application entrypoint + environment: + type: object + description: Environment variables and values to be set before entrypoint execution + additionalProperties: true + insecurely: + type: boolean + description: Skip dropping of priviledge to the runtime process owner before entrypoint execution + entrypoint: + type: array + description: Runtime entry point command and arguments + items: + type: string + v3.VariantConfig: + allOf: + - $ref: '#/components/schemas/v3.CommonConfig' + - type: object + properties: + includes: + type: array + description: Names of other variants to inherit configuration from + items: + description: Variant name + type: string + copies: + type: string + description: Name of variant from which to copy application files, resulting in a multi-stage build + artifacts: + type: array + items: + type: object + description: Artifacts to copy from another variant, resulting in a multi-stage build + required: [from, source, destination] + properties: + from: + type: string + description: Variant name + source: + type: string + description: Path of files/directories to copy + destination: + type: string + description: Destination path -- cgit v1.2.1