diff options
author | Kamil Trzciński <ayufan@ayufan.eu> | 2019-01-10 17:22:58 +0300 |
---|---|---|
committer | Kamil Trzciński <ayufan@ayufan.eu> | 2019-01-25 15:13:48 +0300 |
commit | 045d07bab37df2020f650f7354157f5267f57c8a (patch) | |
tree | e99aad48ed248daa02ff1d7fe9250b327ffa77bb /doc | |
parent | 267ce96e36ecec169b02410bfea85e6d31715910 (diff) |
Add Container Registry API
This includes a set of APIs to manipulate container registry.
This includes also an ability to delete tags based on requested
criteria, like keep-last-n, matching-name, older-than.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/README.md | 1 | ||||
-rw-r--r-- | doc/api/container_registry.md | 198 |
2 files changed, 199 insertions, 0 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index 6c5bb1c0940..46fedd0f86d 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -16,6 +16,7 @@ The following API resources are available: - [Broadcast messages](broadcast_messages.md) - [Code snippets](snippets.md) - [Commits](commits.md) +- [Container Registry](container_registry.md) - [Custom attributes](custom_attributes.md) - [Deploy keys](deploy_keys.md), and [deploy keys for multiple projects](deploy_key_multiple_projects.md) - [Deployments](deployments.md) diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md new file mode 100644 index 00000000000..18afe903c70 --- /dev/null +++ b/doc/api/container_registry.md @@ -0,0 +1,198 @@ +# Container Registry API + +## List registry repositories + +Get a list of registry repositories in a project. + +``` +GET /projects/:id/registry/repositories +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user + + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories" +``` + +Example response: + +```json +[ + { + "id": 1, + "name": "", + "path": "group/project", + "location": "gitlab.example.com:5000/group/project", + "created_at": "2019-01-10T13:38:57.391Z" + }, + { + "id": 2, + "name": "releases", + "path": "group/project/releases", + "location": "gitlab.example.com:5000/group/project/releases", + "created_at": "2019-01-10T13:39:08.229Z" + } +] +``` + +## Delete registry repository + +Get a list of repository commits in a project. + +This operation is executed asynchronously and it might take +time to get executed. + +``` +DELETE /projects/:id/registry/repositories/:repository_id +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +| `repository_id` | integer | yes | The ID of registry repository + +```bash +curl -X DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2" +``` + +## List repository tags + +Get a list of tags for given registry repository. + +``` +GET /projects/:id/registry/repositories/:repository_id/tags +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +| `repository_id` | integer | yes | The ID of registry repository + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" +``` + +Example response: + +```json +[ + { + "name": "A", + "path": "group/project:A", + "location": "gitlab.example.com:5000/group/project:A" + }, + { + "name": "latest", + "path": "group/project:latest", + "location": "gitlab.example.com:5000/group/project:latest" + } +] +``` + +## Delete repository tags (in bulk) + +Delete repository tags in bulk based on given criteria. + +This API performs a following set of the operations: + +1. It schedules asynchronous job executed in background, +1. It never removes tag named `latest`, +1. It removes the tags matching given `name_regex` only, +1. It orders all tags by creation date. The creation date is time of the manifest creation. It is not a time of tag push, +1. It keeps N latest matching tags (if specified), +1. It only removes tags that are older than (if specified). + +These operations are executed asynchronously and it might +take time to get executed. This API can be run at most +once an hour for given container repository. + +Due to [Docker Distribution deficiency](ce-21405) it does +not remove tags whose manifest is shared by multiple tags + +``` +DELETE /projects/:id/registry/repositories/:repository_id/tags +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +| `repository_id` | integer | yes | The ID of registry repository +| `name_regex` | string | yes | The regex of the name to delete. To delete all tags specify `.*` +| `keep_n` | integer | no | The amount of latest tags of given name to keep +| `older_than` | string | no | Tags to delete that are older than given timespec, written in human readable form `1h`, `1d`, `1month` | + +Examples: + +1. Remove tag names that are matching GIT SHA, keep always at least 5, and remove ones that are older than 2 days: + + ```bash + curl -X DELETE -F 'name_regex=[0-9a-z]{40}' -F 'keep_n=5' -F 'older_than=2d' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" + ``` + +2. Remove all tags, but keep always latest 5: + + ```bash + curl -X DELETE -F 'name_regex=.*' -F 'keep_n=5' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" + ``` + +3. Remove all tags that are older than 1 month: + + ```bash + curl -X DELETE -F 'name_regex=.*' -F 'older_than=1month' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" + ``` + +## Get a details repository tag + +Get a details of registry repository tag + +``` +GET /projects/:id/registry/repositories/:repository_id/tags/:tag_name +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +| `repository_id` | integer | yes | The ID of registry repository +| `tag_name` | string | yes | The name of tag + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0" +``` + +Example response: + +```json +{ + "name": "v10.0.0", + "path": "group/project:latest", + "location": "gitlab.example.com:5000/group/project:latest", + "revision": "e9ed9d87c881d8c2fd3a31b41904d01ba0b836e7fd15240d774d811a1c248181", + "short_revision": "e9ed9d87c", + "digest": "sha256:c3490dcf10ffb6530c1303522a1405dfaf7daecd8f38d3e6a1ba19ea1f8a1751", + "created_at": "2019-01-06T16:49:51.272+00:00", + "total_size": 350224384 +} +``` + +## Delete a repository tag + +Delete a registry repository tag + +``` +DELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_name +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +| `repository_id` | integer | yes | The ID of registry repository +| `tag_name` | string | yes | The name of tag + +```bash +curl -X DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0" +``` + +[ce-21405]: https://gitlab.com/gitlab-org/gitlab-ce/issues/21405 |