Harbor制品仓库资源配额的使用

本文节选自《 Harbor权威指南》 一书第8章，作者为 Harbor 开源项目维护者王岩。

在日常运维过程中，为避免一个项目占用过多的系统存储资源，Harbor提供了资源配额（Quota）管理功能实现对项目资源的管控。本文从基本原理、基本设置及客户端交互等方面详细介绍 Harbor 的资源配额管理功能。

基本原理

在 Harbor 系统中，资源配额指的是项目的存储总量。资源配额计算基于项目而非用户。资源配额管理一直是 Artifact (制品）仓库的痛点之一，主要原因是，Artifact 的层文件存储有共享性，不同项目下的不同 Artifact 可以共享一个或者多个层文件，资源配额管理亟待解决的问题包括：如何为共享的资源分配配额，应该将共享的资源配额计入哪个项目。

在详细介绍 Harbor 的资源配额管理功能的基本原理之前，这里先讲解几个基本概念，理解这些概念有助于理解 Harbor 实现资源配额管理功能的原理。

1．OCI Artifact 的组成

OCI Artifact 是依照 OCI 镜像规范打包的数据，一个基本的 OCI Artifact 包括以下几部分。

◎Configuration（配置）：OCI Artifact的配置文件，包含了该镜像的元数据，如镜像的架构、配置信息、构建镜像的容器的配置信息。

◎Layers（层文件）：OCI Artifact的层文件，一般一个镜像包含一组层文件。

◎Manifest（清单）：OCI Artifact的Manifest文件。该文件是一个JSON格式的OCI Artifact描述文件，包含了层文件和配置文件的digest（摘要）信息。

2．推送 Artifact 到 Artifact 仓库

当客户端推送一个Artifact到Artifact仓库时，会按照顺序依次执行以下几个步骤。

（1）推送Configuration配置文件。

（2）依次推送层文件。客户端会根据层文件的 digest 判断层文件在仓库中是否存在，如果不存在就会推送。对于较大的层文件，客户端通过 PATCH Blob 请求分块推送。在所有块文件都推送成功后，客户端会发起 PUT Blob 请求，让 Artifact 仓库知道该层文件推送完成。

（3）推送 Manifest 描述文件。在客户端没有推送 Manifest 文件时，仓库端不知道上一步推送的层文件属于哪一个 Artifact。在 PUT Manifest 请求成功后，仓库端会依据 Manifest 文件的信息为 Artifact 建立层文件的索引关系。

3．Docker Distribution 的分层管理及层共享

在执行 “docker pull” 命令从镜像仓库中拉取镜像时，用户可能会注意到 Docker 是分层拉取的，而且每一层都是独立的，如图所示。

镜像层中的数据使用哈希算法（SHA256）生成ID，这个ID是层的唯一标识，也是Manifest 描述文件的 digest 值。Manifest 文件包含了该 Artifact 的一组层文件，并指明了每一个层文件的 ID。这样一来，当 Docker 客户端发起pull请求时，只需要根据 Manifest 文件中的 digest 去指定拉取相应的层文件，就可实现分层拉取。

Docker Distribution为了优化存储结构以提升存储效率，将Artifact分层化管理。同一个digest的镜像层在Artifact仓库中仅保存一份，这样就做到了存储空间的优化。层文件存储共享的确节省了存储空间，但对配额管理造成了很多困扰。首当其冲的问题是，当一个层文件被多个项目下的不同Artifact引用时，因其只在存储中复制了一份，所以该层文件的存储应被计算在哪一个项目的配额中。

下面将通过一个例子来讲解 Harbor 如何获取一个 OCI Artifact 的大小，并为其分配配额。通过客户端推送 Artifact 到 Harbor 时，Harbor 将针对不同的请求进行流量拦截和数据持久化。

4．PATCH Blob

Harbor 接收到 PATCH Blob 请求时，会将写入存储的字节数记录在 Redis 数据库中。Docker Distribution 为每一个层文件都分配一个 Session ID，当上传的一个层文件被划分为多个 PATCH Blob 请求时，这些 PATCH 请求共享同一个 Session ID。在 Redis 中将该 Session ID 作为键值。Harbor 从每个 PATCH 请求中获取块的大小，并将其更新为该 Session ID 对应的值。在所有的 PATCH 请求都结束后，在 Redis 中存放的就是该层文件的大小，如图所示。

5．PUT Blob

Harbor 接收到 PUT Blob 请求，意味着该层文件全部上传完毕。此时 Harbor 用在 Redis 存储中记录的层文件的大小去申请项目对应的配额。如果可以申请到足够的配额，那么项目的配额被更新，并持久化 Blob 数据；如果无法申请到足够的配额，那么拒绝 PUT Blob 请求，如图所示。

6．PUT Manifest

Harbor 接收到 PUT Manifest 请求时，将用请求的数据大小去申请项目对应的配额。如果可以申请到足够的配额，那么项目配额被更新，并持久化 Manifest和Blob 数据；如果无法申请到足够的配额，那么将拒绝该 PUT Manifest 请求，如图所示。

通过上面的讲解，读者可大体了解 Harbor 是如何获取 Artifact 的大小并为其申请配额的。Harbor 的配额限制在项目级别，而 Docker Distribution 的层文件是系统级别共享的。这里 Harbor 变更了层文件的存储共享概念，对于配额而言，层文件的存储共享被缩小至项目级别。也就是说，当不同项目下的 Artifact 都引用了同一个层文件时，该层文件的大小会被计算到所有引用它的项目配额上。而当同一个项目下的不同 Artifact 引用了同一个层文件时，该层文件的大小不会被多次计算到该项目的可用配额上。所以，Harbor 的所有项目配额总和可能大于实际存储的使用量。

设置项目配额

在了解 Harbor 如何计算资源的配额后，下面就要使用配额对资源进行管理了。本节详细介绍如何在Harbor中设置项目配额，并且对项目资源进行管控。

在创建一个新的项目时，用户可以指定其项目所需的存储容量，如图所示。

存储容量是一个必选值，一般使用了系统的配额默认值，其中“-1”代表容量无限制。在填写容量值和选择容量单位后，单击“确定”按钮即可成功创建一个项目，并且为该项目分配配额资源。

在成功创建项目后，可以通过概要页面查看容量的使用情况，如图所示。

设置系统配额

Harbor系统管理员可以设置系统级的默认配额值，也就是每一个新建项目的配额默认值。此外，最为重要的是可以为任意一个项目增加或减少配额，以达到系统配额管理的目的。

在配额管理页单击“系统管理”→“项目定额”→“修改”按钮便可弹出“修改项目默认配额”对话框，其中“-1”代表配额无限制，如图所示。

输入默认存储值及选择对应的存储单位，单击“确认”按钮即可设置成功。在更改成功后，新建的项目将使用该默认值，但已经创建的项目不受影响。

系统管理员需要对系统资源进行调整时，可以在“项目定额”页总览配额使用情况，并针对某一个项目进行设置，如图所示。

在总览页面，系统管理员可以清晰地了解当前系统的存储使用情况。在选中其中任意一个项目并单击“修改”按钮时，便可弹出“修改项目容量”对话框，如图所示。

输入需要修改的容量值和对应的单位，单击“确定”按钮即可修改成功。在修改成功后，该项目将获得对应的配额。注意：如果修改的值小于当前已使用的值，那么该项目将无法接收任何新的镜像。

配额的使用

一个项目在被创建后，会获得一定的配额。那么在Harbor系统里有哪些操作会影响到可用配额呢？下面将详细讲解。

1．Artifact的推送

在用户推送Artifact到项目中后，Harbor 会对项目扣除该 Artifact 对应大小的配额。

这里以 Docker 镜像为例，在用户推送镜像 hello-world:latest 到 Harbor 项目 library 后，项目的配额被更新为 hello-world:latest 的大小，如图所示。

注意：当用户推送的 Artifact 与同处于一个项目的已有 Artifact 共享层文件时，该层文件对应的配额并不会被扣除。

2．Artifact的删除

当项目用户将任意 Artifact 从项目中删除时，如图所示。Harbor 将把该 Artifact 的大小增加到项目的可用配额上。注意：当该 Artifact 与同处于一个项目的其他 Artifact 共享层文件时，该层文件对应的配额并不会被回收。

3．Artifact的远程复制

系统管理员创建远程复制策略时，会从其他镜像仓库复制 Artifact 到当前 Harbor，对应项目的配额被相应地扣除。

4．无 Tag 的 Artifact 操作

在 Harbor 系统中，没有关联任何 Tag 的 Artifact 都被称作无 Tag 的 Artifact，它的产生有以下几种方式。

◎用户将Artifact的所有Tag删除后，该Artifact就是无Tag的Artifact。

◎用户推送新Artifact覆盖已有的同名Artifact。当新推送的Artifact的digest值不同于已有Artifact的digest值时，已有Artifact变为无Tag的Artifact。

◎在用户推送Artifact索引的过程中，客户端会先推送其子 Artifact，等到所有子Artifact都推送成功后，再推送索引本身。在索引没有被完全推送成功前，这些先被推送的子Artifact就是无Tag的Artifact。

对无 Tag 的Artifact 的处理，在 Harbor 系统中有 Tag 保留和垃圾回收两种操作。

当用户执行 Tag 保留策略时，可选中无 Tag 的 Artifact 选项。Harbor 会依据保留策略，决定是否删除无 Tag 的 Artifact。当删除时，无 Tag 的 Artifact 对应的配额会被回收。

当用户执行垃圾回收任务，选中删除无 Tag 的 Artifacts 时，Harbor 的垃圾回收任务会删除无 Tag 的 Artifacts，并且回收对应的配额。

配额超限的提示

在用户推送 Artifact 后，如果此时配额已达上限，那么 Harbor 系统如何提示用户相应的信息呢？

1．Docker 客户端推送时配额不足

在推送层文件的过程中，如果某个层文件的推送请求无法申请到足够的配额，那么将被提示相应的错误信息。Docker 客户端接收到错误码为 412 的申请配额无效错误信息，表明当前项目配额已经接近或超过上限，无法为当前请求申请足够的配额。用户可通知系统管理员为该项目设置更多配额。

2．其他项目配额不足

当用户在 Harbor 中将 Artifact 从一个项目复制到另一个项目时，如果目标项目没有足够的配额，则用户将收到系统提示。