Skip to main content

A restful web service for querying the image sizes of a GitLab registry.

Project description

Introduction

GitLab-Registry-Usage-REST is a package that periodically collects image information (name, tags, sizes) of a GitLab registry server and offers the data via a secured RESTful HAL 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:

pip install gitlab-registry-usage-rest
gitlab-registry-usage-rest --help

or from DockerHub:

docker run sciapp/gitlab-registry-usage-rest:latest --help

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

gitlab-registry-usage-rest --print-default-config

and edit this default configuration to fit your environment.

If you would like to use the docker image, you can bind mount a local configuration file with the -v switch:

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:

    Authorization: Bearer <token>
  • /images: Lists attributes of the images collection. Currently, only the timestamp of the last data refresh is contained:

    {
        "timestamp": 1521796487.7021387
    }
  • /images/<image_name>: Queries attributes of a specific image:

    {
        "name": "scientific-it-systems/administration/gitlab-registry-usage-rest",
        "size": 39899199,
        "disk_size": 39898911
    }
  • /images/<image_name>/tags: Endpoint for the collection of image tags, currently without any content.

  • /images/<image_name>/tags/<tag_name>: Lists attributes of an image tag:

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

/images?embed=true

returns all resources at once.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gitlab-registry-usage-rest-0.1.12.tar.gz (10.4 kB view hashes)

Uploaded Source

Built Distribution

gitlab_registry_usage_rest-0.1.12-py3-none-any.whl (13.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page