Skip to content

Latest commit

 

History

History
322 lines (238 loc) · 7.88 KB

v1.md

File metadata and controls

322 lines (238 loc) · 7.88 KB
Raw

REST API Version 1 - DEPRECATED

Uploading operators manifests from zipfile

Operator manifests files must be added to zip archive

Endpoints

  • [POST] /v1/<organization>/<repository>/zipfile/<version>
  • [POST] /v1/<organization>/<repository>/zipfile

Zip file must be attached as content_type='multipart/form-data' assigned to field file. See curl examples bellow.

If <version> is omitted:

  • the latest release version will be incremented and used (for example from 2.5.1 to 3.0.0)
  • for new repository a default initial version will be used (DEFAULT_RELEASE_VERSION config option)

<version> must be unique for repository. Quay doesn't support overwriting of releases.

Note: if configured, registry URLs will be replaced during push.

Replies

OK

HTTP code: 200

{
  "organization": "organization name",
  "repo": "repository name",
  "version": "0.0.1",
  "extracted_files": ["packages.yml", "..."]
}

Failures

Error messages have following format:

{
  "status": <http numeric code>,
  "error": "<error ID string>",
  "message": "<detailed error description>",
}

For the following errors, the response will contain extra fields:
  PackageValidationError:
    "validation_info": <json with validation warnings and errors, empty if unavailable>

  QuayAuthorizationError, QuayCourierError:
    "quay_response": <json response from quay.io, empty if unavailable>
HTTP Code / status error Explanation
400 OMPSUploadedFileError Uploaded file didn't meet expectations (not a zip file, too big after unzip, corrupted zip file)
400 OMPSExpectedFileError Expected file hasn't been attached
400 PackageValidationError Package failed validation (e.g. invalid yaml, missing required fields...)
400 OMPSInvalidVersionFormat Invalid version format in URL
403 OMPSAuthorizationHeaderRequired No Authorization header found in request
403 QuayAuthorizationError Unauthorized access to quay
500 QuayCourierError operator-courier module raised exception during building and pushing manifests to quay
500 QuayPackageError Failed to get information about application packages from quay

Example

curl \
  -H "Authorization: ${TOKEN}" \
  -X POST https://example.com/v1/myorg/myrepo/zipfile \
  -F "[email protected]"

or with explicit release version

curl \
  -H "Authorization: ${TOKEN}" \
  -X POST https://example.com/v1/myorg/myrepo/zipfile/1.1.5 \
  -F "[email protected]"

Uploading operators manifests from koji

Downloads operator manifest archive from koji build specified by N-V-R. Build must be done by OSBS service which extracts operator manifests from images and stores them as a zip archive in koji.

Endpoints

  • [POST] /v1/<organization>/<repository>/koji/<nvr>/<version>
  • [POST] /v1/<organization>/<repository>/koji/<nvr>

Operator image build must be specified by N-V-R value from koji.

If <version> is omitted:

  • the latest release version will be incremented and used (for example from 2.5.1 to 3.0.0)
  • for new repository a default initial version will be used (DEFAULT_RELEASE_VERSION config option)

<version> must be unique for repository. Quay doesn't support overwriting of releases.

Note: if configured, registry URLs will be replaced during push.

Replies

OK

HTTP code: 200

{
  "organization": "organization name",
  "repo": "repository name",
  "version": "0.0.1",
  "nvr": "n-v-r",
  "extracted_files": ["packages.yml", "..."]
}

Failures

Error messages have following format:

{
  "status": <http numeric code>,
  "error": "<error ID string>",
  "message": "<detailed error description>",
}

For the following errors, the response will contain extra fields:
  PackageValidationError:
    "validation_info": <json with validation warnings and errors, empty if unavailable>

  QuayAuthorizationError, QuayCourierError:
    "quay_response": <json response from quay.io, empty if unavailable>

  GreenwaveUnsatisfiedError, GreenwaveError:
    "greenwave_response": <json with details from Greenwave (may be empty object)>
HTTP Code / status error Explanation
400 OMPSUploadedFileError Uploaded file didn't meet expectations (not a zip file, too big after unzip, corrupted zip file)
400 OMPSInvalidVersionFormat Invalid version format in URL
400 KojiNotAnOperatorImage Requested build is not an operator image
400 GreenwaveUnsatisfiedError Build doesn't satisfy Greenwave policies
403 OMPSAuthorizationHeaderRequired No Authorization header found in request
404 KojiNVRBuildNotFound Requested build not found in koji
500 KojiManifestsArchiveNotFound Manifest archive not found in koji build
500 KojiError Koji generic error (connection failures, etc.)
500 QuayCourierError operator-courier module raised exception during building and pushing manifests to quay
500 QuayPackageError Failed to get information about application packages from quay
500 GreenwaveError Failed to get information about koji build from Greenwave

Example

curl \
  -H "Authorization: ${TOKEN}" \
  -X POST https://example.com/v1/myorg/myrepo/koji/image-1.2-5

or with explicit release version

curl \
  -H "Authorization: ${TOKEN}" \
  -X POST https://example.com/v1/myorg/myrepo/koji/image-1.2-5/1.1.5

Removing released operators manifests

Endpoints

  • [DELETE] /v1/<organization>/<repository>/<version>
  • [DELETE] /v1/<organization>/<repository>

If <version> is omitted then all released operator manifests are removed from the specified application repository, but the repository itself will not be deleted (the feature is out of scope, for now).

Replies

OK

HTTP code: 200

{
  "organization": "organization name",
  "repo": "repository name",
  "deleted": ["version", "..."]
}

Failures

Error messages have following format:

{
  "status": <http numeric code>,
  "error": "<error ID string>",
  "message": "<detailed error description>",
}
HTTP Code / status error Explanation
403 OMPSAuthorizationHeaderRequired No Authorization header found in request
404 QuayPackageNotFound Requested package doesn't exist in quay
500 QuayPackageError Getting information about released packages or deleting failed

Examples

curl \
  -H "Authorization: ${TOKEN}" \
  -X DELETE https://example.com/v1/myorg/myrepo

or with explicit release version

curl \
   -H "Authorization: ${TOKEN}" \
   -X DELETE https://example.com/v1/myorg/myrepo/1.1.5

Health status

Check status of OMPS service and accessibility of:

  • quay service
  • koji service

If HTTP status is not 200, consider service as not working.

Endpoints

  • [GET] /v1/health/ping

Replies

OK

HTTP code: 200

{
  "ok": true,
  "services": {
    "koji": {
      "details": "It works!",
      "ok": true
    },
    "quay": {
      "details": "It works!",
      "ok": true
    }
  },
  "status": 200
}

Failure

HTTP code: other than 200

Format of message cannot be guaranteed. However service will try to answer with the same format as is listed above, for example:

{
  "ok": false,
  "services": {
    "koji": {
      "details": "Cannot connect!",
      "ok": false
    },
    "quay": {
      "details": "It works!",
      "ok": true
    }
  },
  "status": 503
}

Examples

curl https://example.com/v1/health/ping

Telling the current version of OMPS

Endpoint

  • [GET] /v1/about

Replies

OK

HTTP code: 200

{
  "operatorcourier": "1.3.0",
  "version": "2.0"
}

Examples

curl https://example.com/v1/about