Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/sapcc/keppel

Regionally federated multi-tenant container image registry
https://github.com/sapcc/keppel

container-registry kubernetes openstack

Last synced: 4 months ago
JSON representation

Regionally federated multi-tenant container image registry

Awesome Lists containing this project

README 

          



# Keppel, a multi-tenant container image registry



[![CI](https://github.com/sapcc/keppel/actions/workflows/ci.yaml/badge.svg)](https://github.com/sapcc/keppel/actions/workflows/ci.yaml)

[![Conformance Test](https://github.com/sapcc/keppel/actions/workflows/oci-distribution-conformance.yml/badge.svg)](https://github.com/sapcc/keppel/actions/workflows/oci-distribution-conformance.yml)

[![Coverage Status](https://coveralls.io/repos/github/sapcc/keppel/badge.svg?branch=master)](https://coveralls.io/github/sapcc/keppel?branch=master)

[![Go Report Card](https://goreportcard.com/badge/github.com/sapcc/keppel)](https://goreportcard.com/report/github.com/sapcc/keppel)



In this document:



- [Overview](#overview)

- [History](#history)

- [Terminology](#terminology)

- [Usage](#usage)



In other documents:



- [Operator guide](./docs/operator-guide.md)

- [API specification](./docs/api-spec.md)

- [Notes for developers/contributors](./CONTRIBUTING.md)



## Overview



When working with the container ecosystem (Docker, Kubernetes, etc.), you need a place to store your container images.

The default choice is the [Docker Registry](https://github.com/docker/distribution), but a Docker Registry alone is not

enough in productive deployments because you also need a compatible OAuth2 provider. A popular choice is

[Harbor](https://goharbor.io), which bundles a Docker Registry, an auth provider, and some other tools. Another choice

is [Quay](https://github.com/quay/quay), which implements the registry protocol itself, but is otherwise very similar to

Harbor.



However, Harbor's architecture is limited by its use of a single registry that is shared between all users. Most

importantly, by putting the images of all users in the same storage, quota and usage tracking gets unnecessarily

complicated. Keppel instead uses multi-tenant-aware storage drivers so that each customer gets their own separate

storage space. Storage quota and usage can therefore be tracked by the backing storage. This orchestration is completely

transparent to the user: A unified API endpoint is provided that multiplexes requests to their respective registry

instances.



Keppel fully implements the [OCI Distribution API][dist-api], the standard API for container image registries. It also

provides a [custom API](docs/api-spec.md) to control the multitenancy added by Keppel and to expose additional metadata

about repositories, manifests and tags. Other unique features of Keppel include:



- **cross-regional federation**: Keppel instances running in different geographical regions or different network

  segments can share their account name space and provide seamless replication between accounts of the same name on

  different instances.

- **online garbage collection**: Unlike Docker Registry, Keppel can perform all garbage collection tasks without

  scheduled downtime or any other form of operator intervention.

- **vulnerability scanning**: Keppel can use [Trivy](https://trivy.dev/) to perform vulnerability scans on its contents.



[dist-api]: https://github.com/opencontainers/distribution-spec



## History



In its first year, leading up to 1.0, Keppel used to orchestrate a fleet of docker-registry instances to provide the

OCI Distribution API. We hoped to save ourselves the work of reimplementing the full Distribution API, since Keppel

would only have to reverse-proxy customer requests into their respective docker-registry. Over time, as Keppel's feature

set grew, more and more API requests were intercepted to track metadata, validate requests and so forth. We ended up

scrapping the docker-registry fleet entirely to make Keppel much easier to deploy and manage. It's now conceptually more

similar to Quay than to Harbor, but retains its unique multi-tenant storage architecture.



## Terminology



Within Keppel, an **account** is a namespace that gets its own backing storage. The account name is the first path

element in the name of a repository. For example, consider the image `keppel.example.com/foo/bar:latest`. It's

repository name is `foo/bar`, which means it's located in the Keppel account `foo`.



Access is controlled by the account's **auth tenant** or just **tenant**. Note that tenants and accounts are separate

concepts: An account corresponds to one backing storage, and a tenant corresponds to an authentication/authorization

scope. Each account is linked to exactly one auth tenant, but there can be multiple accounts linked to the same auth

tenant.



Inside an account, you will find **repositories** containing **blobs**, **manifests** and **tags**. The meaning of those

terms is the same as for any other Docker registry or OCI image registry, and is defined in the [OCI Distribution API

specification][dist-api].



## Usage



Build with `make`, install with `make install` or `docker build`. The resulting `keppel` binary contains client commands

as well as server commands.



- For how to use the client commands, run `keppel --help`.

- For how to deploy the server components, please refer to the [operator guide](./docs/operator-guide.md).



## Support, Feedback, Contributing



This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-an-issue). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](./CONTRIBUTING.md).



## Security / Disclosure



If you find any bug that may be a security problem, please follow our instructions [in our security policy](https://github.com/SAP-cloud-infrastructure/.github/blob/main/SECURITY.md) on how to report it. Please do not create GitHub issues for security-related doubts or problems.



## Code of Conduct



We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](https://github.com/SAP-cloud-infrastructure/.github/blob/main/CODE_OF_CONDUCT.md) at all times.



## Licensing



Copyright 2018-2025 SAP SE or an SAP affiliate company and keppel contributors. Please see our [LICENSE](./LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/sapcc/keppel).