# GitLab-Registry-Usage-REST
## Introduction
*GitLab-Registry-Usage-REST* is a package that periodically collects repository information (names, tags, sizes) of a
GitLab registry server and offers the data via a secured [RESTful HAL](http://stateless.co/hal_specification.html) api.
For the initial authentication a LDAP server is needed. Subsequent queries are secured by *JSON Web Tokens* (JWT).
## Installation
The latest version can be obtained from PyPI:
```bash
pip install gitlab-registry-usage-rest
gitlab-registry-usage-rest --help
```
or from DockerHub:
```bash
docker run sciapp/gitlab-registry-usage-rest:latest --help
```
or from the AUR for Arch Linux based systems:
```bash
yay -S gitlab-registry-usage-rest
```
## Usage
*Gitlab-Registry-Usage-REST* needs a configuration file in order to run. The default path is
`/etc/gitlab_registry_usage_rest.conf` but can be altered with the `-c` command line switch. To get started, you can run
```bash
gitlab-registry-usage-rest --print-default-config
```
and edit this default configuration to fit your environment.
If you would like to use the docker repository, you can bind mount a local configuration file with the `-v` switch:
```bash
docker run -v "$(pwd)/gitlab_registry_usage_rest.conf:/etc/gitlab_registry_usage_rest.conf" sciapp/gitlab-registry-usage-rest:latest
```
**Note**: Docker expects an absolute path for the local configuration file.
The server offers these api endpoints:
- `/auth_token`: Accepts a request with basic auth (and valid LDAP credentials) and returns an auth token for further
api usage. All other endpoints only accept requests with a valid `Bearer` authorization header:
```http
Authorization: Bearer <token>
```
- `/repositories`: Lists attributes of the *repositories* collection. Currently, only the timestamp of the last data
refresh is contained:
```json
{
"timestamp": 1521796487.7021387
}
```
- `/repositories/<repository_name>`: Queries attributes of a specific repository:
```json
{
"name": "scientific-it-systems/administration/gitlab-registry-usage-rest",
"size": 39899199,
"disk_size": 39898911
}
```
- `/repositories/<repository_name>/tags`: Endpoint for the collection of repository tags, currently without any content.
- `/repositories/<repository_name>/tags/<tag_name>`: Lists attributes of a tagged image stored in a repository:
```json
{
"name": "latest",
"size": 39899199,
"disk_size": 39898911
}
```
Additionally, all api endpoints (except `/auth_token`) offer an `_embedded` and a `_links` attribute if requested with
the query string:
```
?embed=true&links=true
```
Instead of a boolean value, the embed key can also take an integer number to only request a specific level of embedded
resources.
Links can be used to easily navigate between related resources. Embedded resources are convenient to query a complete
hierarchy of resources with one GET request. Accordingly, the request
```
/repositories?embed=true
```
returns all resources at once.
Raw data
{
"_id": null,
"home_page": "https://github.com/sciapp/gitlab-registry-usage-rest",
"name": "gitlab-registry-usage-rest",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.6",
"maintainer_email": "",
"keywords": "Git,GitLab,Docker,Registry,disk capacity,RESTful",
"author": "Ingo Meyer",
"author_email": "i.meyer@fz-juelich.de",
"download_url": "https://files.pythonhosted.org/packages/15/e2/9b16d0a63e375e10e2f801487302ee3dd9fae93446a99a7c437aa208ed9a/gitlab-registry-usage-rest-0.3.3.tar.gz",
"platform": null,
"description": "# GitLab-Registry-Usage-REST\n\n## Introduction\n\n*GitLab-Registry-Usage-REST* is a package that periodically collects repository information (names, tags, sizes) of a\nGitLab registry server and offers the data via a secured [RESTful HAL](http://stateless.co/hal_specification.html) api.\nFor the initial authentication a LDAP server is needed. Subsequent queries are secured by *JSON Web Tokens* (JWT).\n\n## Installation\n\nThe latest version can be obtained from PyPI:\n\n```bash\npip install gitlab-registry-usage-rest\ngitlab-registry-usage-rest --help\n```\n\nor from DockerHub:\n\n```bash\ndocker run sciapp/gitlab-registry-usage-rest:latest --help\n```\n\nor from the AUR for Arch Linux based systems:\n\n```bash\nyay -S gitlab-registry-usage-rest\n```\n\n## Usage\n\n*Gitlab-Registry-Usage-REST* needs a configuration file in order to run. The default path is\n`/etc/gitlab_registry_usage_rest.conf` but can be altered with the `-c` command line switch. To get started, you can run\n\n```bash\ngitlab-registry-usage-rest --print-default-config\n```\n\nand edit this default configuration to fit your environment.\n\nIf you would like to use the docker repository, you can bind mount a local configuration file with the `-v` switch:\n\n```bash\ndocker run -v \"$(pwd)/gitlab_registry_usage_rest.conf:/etc/gitlab_registry_usage_rest.conf\" sciapp/gitlab-registry-usage-rest:latest\n```\n\n**Note**: Docker expects an absolute path for the local configuration file.\n\nThe server offers these api endpoints:\n\n- `/auth_token`: Accepts a request with basic auth (and valid LDAP credentials) and returns an auth token for further\n api usage. All other endpoints only accept requests with a valid `Bearer` authorization header:\n\n ```http\n Authorization: Bearer <token>\n ```\n\n- `/repositories`: Lists attributes of the *repositories* collection. Currently, only the timestamp of the last data\n refresh is contained:\n\n ```json\n {\n \"timestamp\": 1521796487.7021387\n }\n ```\n\n- `/repositories/<repository_name>`: Queries attributes of a specific repository:\n\n ```json\n {\n \"name\": \"scientific-it-systems/administration/gitlab-registry-usage-rest\",\n \"size\": 39899199,\n \"disk_size\": 39898911\n }\n ```\n\n- `/repositories/<repository_name>/tags`: Endpoint for the collection of repository tags, currently without any content.\n\n- `/repositories/<repository_name>/tags/<tag_name>`: Lists attributes of a tagged image stored in a repository:\n\n ```json\n {\n \"name\": \"latest\",\n \"size\": 39899199,\n \"disk_size\": 39898911\n }\n ```\n\nAdditionally, all api endpoints (except `/auth_token`) offer an `_embedded` and a `_links` attribute if requested with\nthe query string:\n\n```\n?embed=true&links=true\n```\n\nInstead of a boolean value, the embed key can also take an integer number to only request a specific level of embedded\nresources.\n\nLinks can be used to easily navigate between related resources. Embedded resources are convenient to query a complete\nhierarchy of resources with one GET request. Accordingly, the request\n\n```\n/repositories?embed=true\n```\n\nreturns all resources at once.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A restful web service for querying the repository sizes of a GitLab registry.",
"version": "0.3.3",
"project_urls": {
"Homepage": "https://github.com/sciapp/gitlab-registry-usage-rest"
},
"split_keywords": [
"git",
"gitlab",
"docker",
"registry",
"disk capacity",
"restful"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "698e9a9cc4130ccbb9e9824a273989be01e2005bc2fff0fc23e36a7e39229b8a",
"md5": "ee542d2e2f56ee70f4509113e12796a9",
"sha256": "8310130d49744c89f208920c5b380be2271368866fe9a874c847ce0ddaf4f777"
},
"downloads": -1,
"filename": "gitlab_registry_usage_rest-0.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ee542d2e2f56ee70f4509113e12796a9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.6",
"size": 11514,
"upload_time": "2024-01-16T16:17:32",
"upload_time_iso_8601": "2024-01-16T16:17:32.397259Z",
"url": "https://files.pythonhosted.org/packages/69/8e/9a9cc4130ccbb9e9824a273989be01e2005bc2fff0fc23e36a7e39229b8a/gitlab_registry_usage_rest-0.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "15e29b16d0a63e375e10e2f801487302ee3dd9fae93446a99a7c437aa208ed9a",
"md5": "c8d40ee4f82ad5fcde21b66b3597cd82",
"sha256": "c7a0d124474cadd7a4d7c9fdd96c2869907ab0f691740e358b1bb9385e85b090"
},
"downloads": -1,
"filename": "gitlab-registry-usage-rest-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "c8d40ee4f82ad5fcde21b66b3597cd82",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.6",
"size": 10921,
"upload_time": "2024-01-16T16:17:34",
"upload_time_iso_8601": "2024-01-16T16:17:34.420734Z",
"url": "https://files.pythonhosted.org/packages/15/e2/9b16d0a63e375e10e2f801487302ee3dd9fae93446a99a7c437aa208ed9a/gitlab-registry-usage-rest-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-16 16:17:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sciapp",
"github_project": "gitlab-registry-usage-rest",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gitlab-registry-usage-rest"
}
JSON
