Skip to content
This repository has been archived by the owner on May 24, 2023. It is now read-only.

Commit

Permalink
Merge b302692 into 1977b71
Browse files Browse the repository at this point in the history
  • Loading branch information
@MartinBasti
MartinBasti committed Mar 28, 2019
2 parents 1977b71 + b302692 commit 998569a
Show file tree
Hide file tree
Showing 16 changed files with 1,107 additions and 296 deletions.
299 changes: 4 additions & 295 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ docker run --rm -p 8080:8080 -e WORKERS_NUM=6 omps:latest

## Usage

## Authorization
### Authorization

Users are expected to use quay.io token that can be acquired by the following
command:
Expand All @@ -100,301 +100,10 @@ curl -H "Authorization: ${TOKEN}" ...
Is recommended to use [robot accounts](https://docs.quay.io/glossary/robot-accounts.html).


### REST API

### 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.

#### Replies

**OK**

HTTP code: 200

```json
{
"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>",
}
```


| 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| OMPSInvalidVersionFormat | Invalid version format in URL |
|403| OMPSAuthorizationHeaderRequired| No `Authorization` header found in request|
|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
```bash
curl \
-H "Authorization: ${TOKEN}" \
-X POST https://example.com/v1/myorg/myrepo/zipfile \
-F "file=@manifests.zip"
```
or with explicit release version
```bash
curl \
-H "Authorization: ${TOKEN}" \
-X POST https://example.com/v1/myorg/myrepo/zipfile/1.1.5 \
-F "file=@manifests.zip"
```

### Uploading operators manifests from koji

Downloads operator manifest archive from koji build specified by N-V-R.
Build must be done by [OSBS](https://osbs.readthedocs.io)
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.

#### Replies

**OK**

HTTP code: 200

```json
{
"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>",
}
```


| 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 |
|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 |


#### Example
```bash
curl \
-H "Authorization: ${TOKEN}" \
-X POST https://example.com/v1/myorg/myrepo/koji/image-1.2-5
```
or with explicit release version
```bash
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

```json
{
"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
```bash
curl \
-H "Authorization: ${TOKEN}" \
-X DELETE https://example.com/v1/myorg/myrepo
```
or with explicit release version
```bash
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

```json
{
"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:

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


#### Examples
```bash
curl https://example.com/v1/health/ping
```

### Telling the current version of OMPS

#### Endpoint

* [GET] `/v1/about`

#### Replies

**OK**

HTTP code: 200

```json
{
"version": "2.0"
}
```

#### Examples

```bash
curl https://example.com/v1/about
```
* **Under development** [REST API Version 2](docs/usage/v2.md)
* [REST API Version 1](docs/usage/v1.md)


## Development
Expand Down
Loading

0 comments on commit 998569a

Please sign in to comment.