构建器和镜像自动化

Red Hat Quay 3.15

构建器和镜像自动化

摘要

了解构建程序及其在自动化镜像构建方面的角色。

前言
复制链接

要从 {product-title} 中的 Dockerfile 自动执行容器镜像构建，您可以在裸机和虚拟机上配置构建器。配置构建触发器，以便在代码更改时自动启动构建，或者在需要时手动启动构建。

第 1 章 Red Hat Quay 构建概述
复制链接

{product-title} 构建功能使用 worker 节点自动从 Dockerfile 构建容器镜像。您可以手动触发构建或自动通过 Webhook 将 CI/CD 管道集成到工作流中。

OpenShift Container Platform 和 Kubernetes 集群上的 Red Hat Quay 支持构建功能。对于基于 Operator 的部署和 Kubernetes 集群，构建是使用协调和处理 构建作业的构建 管理器 创建的。构建支持在裸机平台和使用虚拟 构建器在虚拟 平台上构建 Dockerfile。这种通用性使组织能够适应现有基础架构，同时利用 Red Hat Quay 的容器镜像构建功能。

Red Hat Quay 构建 功能的主要功能包括：

由代码提交或版本控制事件触发的自动化构建
支持 Docker 和 Podman 容器镜像
对构建环境和资源的精细控制
与 Kubernetes 和 OpenShift Container Platform 集成以实现可扩展构建
与裸机和虚拟化基础架构的兼容性

注意

直接在裸机平台上的容器中运行构建与使用虚拟机时没有同样的隔离，但它仍然提供良好的保护。

构建非常复杂，建议管理员审查构建自动化架构指南，然后再继续。

1.1. 构建容器镜像
复制链接

{product-title} 构建功能支持从 Dockerfile 构建 Docker 和 Podman 容器镜像。您可以通过定义构建上下文并使用公共存储库中的基础镜像来创建容器化应用程序。

Red Hat Quay 支持构建 Docker 和 Podman 容器镜像。此功能对于依赖容器和容器编排的开发人员和组织而言非常宝贵。

1.1.1. 构建上下文
复制链接

使用 Docker 或 Podman 构建镜像时，将指定目录成为 构建上下文。对于手动构建和构建触发器，这是正确的，因为由创建的构建与在本地机器上运行 docker build 或 podman build 不同。

从 Build 设置的 子目录中 始终指定构建上下文，如果未指定目录，则回退到 Build 源的根目录。

触发构建时，Build worker 会将 Git 存储库克隆到 worker 机器，然后在执行构建前输入构建上下文。

对于基于 .tar 归档的构建，构建工作程序提取存档并输入构建上下文。例如：

提取的构建存档

example
├── .git
├── Dockerfile
├── file
└── subdir
    └── Dockerfile

假设 Extracted Build 归档 是目录结构，它有一个 Github 存储库，名为 example。如果在 Build 触发器设置中没有指定子目录，或者在手动启动构建时指定，则构建在示例目录中运行。

如果在 Build 触发器设置中指定子目录，如 subdir，则构建中只有其中的 Dockerfile 才可以看到。这意味着您不能使用 Dockerfile 中的 ADD 命令来添加文件，因为它不在构建上下文之外。

与 Docker Hub 不同，Dockerfile 是构建上下文的一部分，因此它不能出现在 .dockerignore 文件中。

第 2 章为构建配置 OpenShift Container Platform TLS 组件
复制链接

要在 {product-title} 中启用带有非受管 TLS 的构建功能，您可以将构建器路由名称添加到 SSL/TLS 证书配置中的 Subject Alternative Name (SAN)字段中。

QuayRegistry 自定义资源定义(CRD)的 tls 组件允许您控制 SSL/TLS 是否由 Red Hat Quay Operator 管理，还是自我管理。在其当前状态中，当 tls 组件由 Red Hat Quay Operator 管理时，Red Hat Quay 不支持构建功能或 构建器 worker。

当将 tls 组件设置为 非受管 时，您必须提供自己的 ssl.cert 和 ssl.key 文件。另外，如果您希望集群支持 构建器 （或负责构建镜像的 worker 节点），您必须将 Quay 路由和 构建器 路由名称添加到证书中的 SAN 列表中。或者，您可以使用通配符。

先决条件

您已将 tls 组件设置为 非受管 组件，并将自定义 SSL/TLS 证书上传到 Red Hat Quay Operator。如需更多信息，请参阅 Red Hat Quay 的 SSL 和 TLS。

流程

在定义 SSL/TLS 证书参数的配置文件中，如 openssl.cnf，将以下信息添加到证书的 Subject Alternative Name (SAN)字段中。例如：

# ...
[alt_names]
<quay_registry_name>-quay-builder-<namespace>.<domain-name>:443
# ...

例如：

# ...
[alt_names]
example-registry-quay-builder-quay-enterprise.apps.cluster-new.gcp.quaydev.org:443
# ...

第 3 章在 OpenShift Container Platform 上使用 Red Hat Quay 构建裸机
复制链接

裸机构建可让您在 OpenShift Container Platform 上使用带有 Red Hat Quay 的 {product-title} 在物理基础架构上构建容器镜像。您可以为裸机构建创建一个环境，以利用您的现有硬件资源。

3.1. 在 OpenShift Container Platform 上为 Red Hat Quay 配置裸机构建
复制链接

要使用 {product-title} 为 OpenShift Container Platform 上的 Red Hat Quay 配置裸机构建，您可以创建一个构建项目、配置服务帐户和更新您的配置文件。

注意

如果您在 OpenShift Container Platform 上使用带有 QuayRegistry CRD 中的受管 路由 组件的 Red Hat Quay Operator，请参阅 "Red Hat Quay on OpenShift Container Platform build limitations with self-managed routes"。

先决条件

您已在运行 Red Hat Quay Operator 时置备了 OpenShift Container Platform 集群。
您已将 tls 组件设置为 非受管 组件，并将自定义 SSL/TLS 证书上传到 Red Hat Quay Operator。如需更多信息，请参阅 Red Hat Quay 的 SSL 和 TLS。
以集群管理员身份登录 OpenShift Container Platform。

流程

输入以下命令创建一个运行构建的项目，如 bare-metal-builder ：
```
$ oc new-project bare-metal-builder
```
输入以下命令在 bare-metal-builder 命名空间中创建一个新 ServiceAccount ：
```
$ oc create sa -n bare-metal-builder quay-builder
```

输入以下命令在 bare-metal-builder 命名空间中授予用户 edit 角色：

$ oc policy add-role-to-user -n bare-metal-builder edit system:serviceaccount:bare-metal-builder:quay-builder

输入以下命令检索与 bare-metal-builder 命名空间中的 quay-builder 服务帐户关联的令牌。此令牌用于对 OpenShift Container Platform 集群的 API 服务器进行身份验证并与之交互。
1. 如果您的 OpenShift Container Platform 集群是 4.11+ 版本，请输入以下命令：
  oc create token quay-builder -n bare-metal-builder --duration 24h
2. 如果您的 OpenShift Container Platform 集群早于 4.11 版本，例如版本 4.10，请输入以下命令：
  $ oc sa get-token -n bare-metal-builder quay-builder
识别 OpenShift Container Platform 集群的 API 服务器的 URL。这可在 OpenShift Container Platform Web 控制台中找到。
识别调度 构建作业时使用的 worker 节点标签。由于 构建 pod 必须在裸机 worker 节点上运行，因此通常使用特定标签来标识这些 pod。
使用集群管理员检查，确定应该使用哪个节点标签。
获取 Kube API 服务器的证书颁发机构(CA)以添加到 Red Hat Quay 的额外证书。
1. 在 OpenShift Container Platform 版本 4.15+ 中，输入以下命令获取包含 CA 的 secret 名称：
  $ oc extract cm/kube-root-ca.crt -n openshift-apiserver
  $ mv ca.crt build_cluster.crt
2. 在早于 4.15 的 OpenShift Container Platform 版本中，如 4.14，输入以下命令：
  $ oc get sa openshift-apiserver-sa --namespace=openshift-apiserver -o json | jq '.secrets[] | select(.name | contains("openshift-apiserver-sa-token"))'.name
3. 从 OpenShift Container Platform Web 控制台中的 secret 获取 ca.crt 键值。该值以 "-----BEGIN CERTIFICATE-----"' 开头。
4. 将 CA 导入到 Red Hat Quay。确保此文件的名称与第 9 步中使用的 K8S_API_TLS_CA 字段匹配。

为 ServiceAccount 创建以下 SecurityContextConstraints 资源：

apiVersion: security.openshift.io/v1
kind: SecurityContextConstraints
metadata:
  name: quay-builder
priority: null
readOnlyRootFilesystem: false
requiredDropCapabilities: null
runAsUser:
  type: RunAsAny
seLinuxContext:
  type: RunAsAny
seccompProfiles:
- '*'
supplementalGroups:
  type: RunAsAny
volumes:
- '*'
allowHostDirVolumePlugin: true
allowHostIPC: true
allowHostNetwork: true
allowHostPID: true
allowHostPorts: true
allowPrivilegeEscalation: true
allowPrivilegedContainer: true
allowedCapabilities:
- '*'
allowedUnsafeSysctls:
- '*'
defaultAddCapabilities: null
fsGroup:
  type: RunAsAny
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: quay-builder-scc
  namespace: bare-metal-builder
rules:
- apiGroups:
  - security.openshift.io
  resourceNames:
  - quay-builder
  resources:
  - securitycontextconstraints
  verbs:
  - use
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: quay-builder-scc
  namespace: bare-metal-builder
subjects:
- kind: ServiceAccount
  name: quay-builder
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: quay-builder-scc

使用 OpenShift Container Platform Web 控制台更新 OpenShift Container Platform 部署上的 Red Hat Quay 的 config.yaml 文件，使其包含适当的裸机构建配置。
1. 点 Operators → Installed Operators → Red Hat Quay → Quay Registry。
2. 点 registry 的名称，如 example-registry。
3. 在 Config Bundle Secret 下，单击配置捆绑包的名称，如 extra-ca-certificate-config-bundle-secret。
4. 点 Actions → Edit Secret。
5. 在您的 Red Hat Quay config.yaml 文件中添加以下信息，将每个值替换为与您特定安装相关的信息：
  FEATURE_USER_INITIALIZE: true BROWSER_API_CALLS_XHR_ONLY: false SUPER_USERS: - <superusername> FEATURE_USER_CREATION: false FEATURE_QUOTA_MANAGEMENT: true FEATURE_BUILD_SUPPORT: True BUILDMAN_HOSTNAME: ${BUILDMAN_HOSTNAME}:443 BUILD_MANAGER: - ephemeral - ALLOWED_WORKER_COUNT: 10 ORCHESTRATOR_PREFIX: buildman/production/ ORCHESTRATOR: REDIS_HOST: <sample_redis_hostname> REDIS_PASSWORD: "" REDIS_SSL: false REDIS_SKIP_KEYSPACE_EVENT_SETUP: false EXECUTORS: - EXECUTOR: kubernetes BUILDER_NAMESPACE: <sample_builder_namespace> K8S_API_SERVER: <sample_k8s_api_server> K8S_API_TLS_CA: <sample_crt_file> VOLUME_SIZE: 8G KUBERNETES_DISTRIBUTION: openshift CONTAINER_MEMORY_LIMITS: 1G CONTAINER_CPU_LIMITS: 300m CONTAINER_MEMORY_REQUEST: 1G CONTAINER_CPU_REQUEST: 300m NODE_SELECTOR_LABEL_KEY: beta.kubernetes.io/instance-type NODE_SELECTOR_LABEL_VALUE: n1-standard-4 CONTAINER_RUNTIME: podman SERVICE_ACCOUNT_NAME: <sample_service_account_name> SERVICE_ACCOUNT_TOKEN: <sample_account_token> QUAY_USERNAME: <quay_username> QUAY_PASSWORD: <quay_password> WORKER_IMAGE: <registry>/quay-quay-builder WORKER_TAG: <some_tag> BUILDER_VM_CONTAINER_IMAGE: registry.redhat.io/quay/quay-builder-qemu-rhcos-rhel8:v3.9.10-4 SETUP_TIME: 180 MINIMUM_RETRY_THRESHOLD: 0 SSH_AUTHORIZED_KEYS: - <ssh-rsa 12345 someuser@email.com> - <ssh-rsa 67890 someuser2@email.com> HTTP_PROXY: <http://10.0.0.1:80> HTTPS_PROXY: <http://10.0.0.1:80> NO_PROXY: <hostname.example.com>
  其中：
  BUILDMAN_HOSTNAME:: 指定 Red Hat Quay registry 的主机名。运行以下命令 ：$ oc get route quayregistry-quay-builder -n ${QUAY_PROJECT} -o jsonpath='{.spec.host}'.
  REDIS_HOST:: 指定 Redis 服务的主机名。
  BUILDER_NAMESPACE:: 指定 裸机构建 命名空间的名称。本例使用 bare-metal-builder。
  K8S_API_SERVER:: 通过运行 $ oc cluster-info 来指定 K8S_API_SERVER 获取。
  K8S_API_TLS_CA:: 指定自定义 CA 证书的名称，例如 K8S_API_TLS_CA: /conf/stack/extra_ca_certs/build-cluster.crt。
  CONTAINER_MEMORY_LIMITS:: 指定容器的内存限值。如果未指定，则默认为 5120Mi。
  CONTAINER_CPU_LIMITS:: 指定容器的 CPU 限值。如果未指定，则默认为 1000m。
  CONTAINER_MEMORY_REQUEST:: 指定容器的内存请求。如果未指定，则默认为 3968Mi。
  CONTAINER_CPU_REQUEST:: 指定容器的 CPU 请求。如果未指定，则默认为 500m。
  service_account_TOKEN:: 指定服务帐户的令牌。运行 $ oc create sa 来获得此目的。
  SSH_AUTHORIZED_KEYS:: 指定构建环境的 SSH 授权密钥。此密钥或密钥应当与管理员或开发人员用来 SSH 到构建工作程序的私钥对应，用于调试目的。此密钥可以通过使用特定的 SSH 密钥和端口建立与远程主机的 SSH 连接来获取。例如 ：$ ssh -i /path/to/ssh/key/set/in/ssh_authorized_keys -p 9999 core@localhost.
重启 Red Hat Quay registry 以启用 构建功能。

3.1.1. OpenShift Container Platform 上的 Red Hat Quay 增加了自我管理的路由的限制
复制链接

当在 OpenShift Container Platform 上使用受管路由时，{product-title} 构建功能具有特定的网络限制。了解这些限制可帮助您确保构建 executor 和构建管理器之间成功通信。

OpenShift Container Platform 路由通常仅限于为单个端口提供流量。因为 Red Hat Quay 构建需要 gRPC 通信，所以 Operator 会创建一个特定的 Route 资源来将此流量定向到构建管理器服务器。

这个架构的关键考虑包括：

不安全与.安全流量： OpenShift ingress 必须启用 HTTP/2 以支持构建管理器使用的 gRPC 协议。
身份和信任： 构建管理器需要构建集群的 CA 证书存在于 Red Hat Quay 配置中，以建立安全连接。
主机名解析： 构建作业必须能够解析构建管理器的主机名。如果使用自定义子域，则需要特定的 DNS 映射以指向 OpenShift 路由器。

如需更多信息，请参阅"为受管路由配置 Red Hat Quay 构建"。

3.1.2. 为受管路由配置 Red Hat Quay 构建
复制链接

要将 {product-title} 构建与受管路由和自定义主机名搭配使用，您可以配置 DNS 记录并更新 registry 配置。这可启用构建 executor 和构建管理器之间的 gRPC 通信。

先决条件

已安装 Red Hat Quay Operator，并存在一个 QuayRegistry。
为目标集群配置了 kubectl 或 oc CLI 工具。

流程

在 OpenShift Container Platform 集群中启用 HTTP/2 入口来支持 gRPC。

检索生成的 build-manager 路由的主机地址：

$ kubectl get -n <namespace> route <quayregistry-name>-quay-builder -o jsonpath={.status.ingress[0].host}

使用您的 DNS 供应商创建 CNAME 记录，将自定义主机名（如 builder-registry.example.com）指向上一步中检索的路由主机。
更新 QuayRegistry 中 spec.configBundle Secret 引用的 Secret，使其包含构建集群 CA 证书。密钥必须命名为 extra_ca_cert_build_cluster.cert。

在您的 config.yaml 中添加 BUILDMAN_HOSTNAME 字段，并包含端口号：

BUILDMAN_HOSTNAME: builder-registry.example.com:443
BUILD_MANAGER:
- ephemeral
  ALLOWED_WORKER_COUNT: 1
  ...

第 4 章在 OpenShift Container Platform 上使用 Red Hat Quay 进行虚拟构建
复制链接

要在 OpenShift Container Platform 上的 Red Hat Quay 上使用 {product-title} 在虚拟化环境中构建容器镜像，您可以使用虚拟构建。虚拟构建在非特权容器中运行，并为构建过程提供隔离。

使用虚拟构建时，构建管理器首先创建 作业对象 资源。然后，作业对象 使用 quay-builder-image 创建一个 pod。quay-builder-image 包含 quay-builder 二进制文件和 Podman 服务。创建的 pod 作为非特权 运行。然后，quay-builder 二进制文件会在通信状态并从构建管理器检索构建信息时构建镜像。

4.1. 虚拟构建限制
复制链接

以下限制适用于 虚拟构建功能 ：

在非特权上下文中使用 Red Hat Quay 运行 虚拟构建 可能会导致在上一个构建策略下工作的一些命令失败。尝试更改构建策略可能会导致构建出现性能问题和可靠性。
直接在容器中运行虚拟 构建与使用虚拟机没有相同的隔离。更改构建环境也可能会导致之前正常工作的构建失败。

4.2. 在 OpenShift Container Platform 上为 Red Hat Quay 配置虚拟构建
复制链接

要使用 {product-title} 为 Red Hat Quay 配置虚拟构建，您可以创建一个构建项目、配置服务帐户并更新您的配置文件。

注意

如果使用 Amazon Web Service (AWS) S3 存储，则必须在运行构建器前在 AWS 控制台中修改存储桶。有关所需参数，请参阅以下部分"修改 AWS S3 存储桶"。
如果使用 Google Cloud Platform (GCP)对象存储桶，您必须配置跨原始资源共享(CORS)以启用 虚拟构建。

先决条件

您已在运行 Red Hat Quay Operator 时置备了 OpenShift Container Platform 集群。
您已将 tls 组件设置为 非受管 组件，并将自定义 SSL/TLS 证书上传到 Red Hat Quay Operator。如需更多信息，请参阅 Red Hat Quay 的 SSL 和 TLS。
您已为构建配置了 OpenShift Container Platform TLS 组件。
以集群管理员身份登录 OpenShift Container Platform。

流程

运行以下命令，创建一个运行虚拟构建器的新项目，如 virtual-builders ：
```
$ oc new-project virtual-builders
```
输入以下命令在项目中创建一个 ServiceAccount，用于运行构建：
```
$ oc create sa -n virtual-builders quay-builder
```
输出示例
```
serviceaccount/quay-builder created
```

为创建的服务帐户提供编辑权限，使其可以 运行构建 ：

$ oc adm policy -n virtual-builders add-role-to-user edit system:serviceaccount:virtual-builders:quay-builder

输出示例

clusterrole.rbac.authorization.k8s.io/edit added: "system:serviceaccount:virtual-builders:quay-builder"

输入以下命令，授予 构建器 worker anyuid scc 权限。这要求集群管理员特权，因为 构建器 必须以 Podman 用户身份运行，才能使非特权或无根构建正常工作。
```
$ oc adm policy -n virtual-builders add-scc-to-user anyuid -z quay-builder
```
输出示例
```
clusterrole.rbac.authorization.k8s.io/system:openshift:scc:anyuid added: "quay-builder"
```
输入以下命令来获取 builder 服务帐户的令牌：
```
$ oc create token quay-builder -n virtual-builders
```
注意
当令牌过期时，您需要请求新令牌。另外，您还可以添加自定义过期。例如，使用 specify-duration 20160m 来保留令牌两周。
输出示例
```
eyJhbGciOiJSUzI1NiIsImtpZCI6IldfQUJkaDVmb3ltTHZ0dGZMYjhIWnYxZTQzN2dJVEJxcDJscldSdEUtYWsifQ...
```

输入以下命令确定 构建器 路由：

$ oc get route -n quay-enterprise

输出示例

NAME: example-registry-quay-builder
HOST/PORT: example-registry-quay-builder-quay-enterprise.apps.stevsmit-cluster-new.gcp.quaydev.org
PATH:
SERVICES: example-registry-quay-app
PORT: grpc
TERMINATION: passthrough/Redirect
WILDCARD: None

输入以下命令，使用 .crt 扩展生成自签名 SSL/TlS 证书：
```
$ oc extract cm/kube-root-ca.crt -n openshift-apiserver
```
输出示例
```
ca.crt
```
输入以下命令将 ca.crt 文件重命名为 build-cluster.crt ：
```
$ mv ca.crt build-cluster.crt
```

使用 OpenShift Container Platform Web 控制台更新 OpenShift Container Platform 部署上的 Red Hat Quay 的 config.yaml 文件，使其包含适当的虚拟构建配置。

点 Operators → Installed Operators → Red Hat Quay → Quay Registry。
点 registry 的名称，如 example-registry。
在 Config Bundle Secret 下，单击配置捆绑包的名称，如 extra-ca-certificate-config-bundle-secret。
点 Actions → Edit Secret。

使用以下内容 添加适当的虚拟 构建配置作为参考：

FEATURE_USER_INITIALIZE: true
BROWSER_API_CALLS_XHR_ONLY: false
SUPER_USERS:
- <superusername>
FEATURE_USER_CREATION: false
FEATURE_QUOTA_MANAGEMENT: true
FEATURE_BUILD_SUPPORT: True
BUILDMAN_HOSTNAME: <sample_build_route>
BUILD_MANAGER:
  - ephemeral
  - ALLOWED_WORKER_COUNT: 1
    ORCHESTRATOR_PREFIX: buildman/production/
    JOB_REGISTRATION_TIMEOUT: 3600
    ORCHESTRATOR:
      REDIS_HOST: <sample_redis_hostname>
      REDIS_PASSWORD: ""
      REDIS_SSL: false
      REDIS_SKIP_KEYSPACE_EVENT_SETUP: false
    EXECUTORS:
      - EXECUTOR: kubernetesPodman
        NAME: openshift
        BUILDER_NAMESPACE: <sample_builder_namespace>
        SETUP_TIME: 180
        MINIMUM_RETRY_THRESHOLD: 0
        BUILDER_CONTAINER_IMAGE: quay.io/projectquay/quay-builder:{producty}
        # Kubernetes resource options
        K8S_API_SERVER: <sample_k8s_api_server>
        K8S_API_TLS_CA: <sample_crt_file>
        VOLUME_SIZE: 8G
        KUBERNETES_DISTRIBUTION: openshift
        CONTAINER_MEMORY_LIMITS: 1G
        CONTAINER_CPU_LIMITS: 300m
        CONTAINER_MEMORY_REQUEST: 1G
        CONTAINER_CPU_REQUEST: 300m
        NODE_SELECTOR_LABEL_KEY: ""
        NODE_SELECTOR_LABEL_VALUE: ""
        SERVICE_ACCOUNT_NAME: <sample_service_account_name>
        SERVICE_ACCOUNT_TOKEN: <sample_account_token>
        HTTP_PROXY: <http://10.0.0.1:80>
        HTTPS_PROXY: <http://10.0.0.1:80>
        NO_PROXY: <hostname.example.com>

其中：

BUILDMAN_HOSTNAME:: 指定 Red Hat Quay registry 的主机名。运行以下命令 ：$ oc get route quayregistry-quay-builder -n ${QUAY_PROJECT} -o jsonpath='{.spec.host}'.

REDIS_HOST:: 指定 Redis 服务的主机名。

BUILDER_NAMESPACE:: 指定 裸机构建 命名空间的名称。本例使用 bare-metal-builder。

K8S_API_SERVER:: 通过运行 $ oc cluster-info 来指定 K8S_API_SERVER 获取。

K8S_API_TLS_CA:: 指定自定义 CA 证书的名称，例如 K8S_API_TLS_CA: /conf/stack/extra_ca_certs/build-cluster.crt。

CONTAINER_MEMORY_LIMITS:: 指定容器的内存限值。如果未指定，则默认为 5120Mi。

CONTAINER_CPU_LIMITS:: 指定容器的 CPU 限值。如果未指定，则默认为 1000m。

CONTAINER_MEMORY_REQUEST:: 指定容器的内存请求。如果未指定，则默认为 3968Mi。

CONTAINER_CPU_REQUEST:: 指定容器的 CPU 请求。如果未指定，则默认为 500m。

service_account_TOKEN:: 指定服务帐户的令牌。运行 $ oc create sa 来获得此目的。

SSH_AUTHORIZED_KEYS:: 指定构建环境的 SSH 授权密钥。此密钥或密钥应当与管理员或开发人员用来 SSH 到构建工作程序的私钥对应，用于调试目的。此密钥可以通过使用特定的 SSH 密钥和端口建立与远程主机的 SSH 连接来获取。例如 ：$ ssh -i /path/to/ssh/key/set/in/ssh_authorized_keys -p 9999 core@localhost.

虚拟构建配置 示例

FEATURE_USER_INITIALIZE: true
BROWSER_API_CALLS_XHR_ONLY: false
SUPER_USERS:
- quayadmin
FEATURE_USER_CREATION: false
FEATURE_QUOTA_MANAGEMENT: true
FEATURE_BUILD_SUPPORT: True
BUILDMAN_HOSTNAME: example-registry-quay-builder-quay-enterprise.apps.docs.quayteam.org:443
BUILD_MANAGER:
  - ephemeral
  - ALLOWED_WORKER_COUNT: 1
    ORCHESTRATOR_PREFIX: buildman/production/
    JOB_REGISTRATION_TIMEOUT: 3600
    ORCHESTRATOR:
      REDIS_HOST: example-registry-quay-redis
      REDIS_PASSWORD: ""
      REDIS_SSL: false
      REDIS_SKIP_KEYSPACE_EVENT_SETUP: false
    EXECUTORS:
      - EXECUTOR: kubernetesPodman
        NAME: openshift
        BUILDER_NAMESPACE: virtual-builders
        SETUP_TIME: 180
        MINIMUM_RETRY_THRESHOLD: 0
        BUILDER_CONTAINER_IMAGE: quay.io/projectquay/quay-builder:{producty}
        # Kubernetes resource options
        K8S_API_SERVER: api.docs.quayteam.org:6443
        K8S_API_TLS_CA: /conf/stack/extra_ca_certs/build-cluster.crt
        VOLUME_SIZE: 8G
        KUBERNETES_DISTRIBUTION: openshift
        CONTAINER_MEMORY_LIMITS: 1G
        CONTAINER_CPU_LIMITS: 300m
        CONTAINER_MEMORY_REQUEST: 1G
        CONTAINER_CPU_REQUEST: 300m
        NODE_SELECTOR_LABEL_KEY: ""
        NODE_SELECTOR_LABEL_VALUE: ""
        SERVICE_ACCOUNT_NAME: quay-builder
        SERVICE_ACCOUNT_TOKEN: "eyJhbGciOiJSUzI1NiIsImtpZCI6IldfQUJkaDVmb3ltTHZ0dGZMYjhIWnYxZTQzN2dJVEJxcDJscldSdEUtYWsifQ"
        HTTP_PROXY: <http://10.0.0.1:80>
        HTTPS_PROXY: <http://10.0.0.1:80>
        NO_PROXY: <hostname.example.com>

在 Edit Secret 页面上点 Save。

使用新配置重启 OpenShift Container Platform registry 上的 Red Hat Quay。

4.2.1. 修改 AWS S3 存储桶
复制链接

要在 {product-title} 中使用 AWS S3 存储启用构建，您可以在 S3 存储桶中配置跨原始资源共享(CORS)设置。这允许构建 worker 访问和存储 S3 存储桶中的构建工件。

流程

登录到位于 s3.console.aws.com 的 AWS 控制台。
在搜索栏中，搜索 S3，然后单击 S3。
单击存储桶的名称，如 myawsbucket。
单击权限选项卡。

在 Cross-origin 资源共享(CORS) 下，包括以下参数：

  [
      {
          "AllowedHeaders": [
              "Authorization"
          ],
          "AllowedMethods": [
              "GET"
          ],
          "AllowedOrigins": [
              "*"
          ],
          "ExposeHeaders": [],
          "MaxAgeSeconds": 3000
      },
      {
          "AllowedHeaders": [
              "Content-Type",
              "x-amz-acl",
              "origin"
          ],
          "AllowedMethods": [
              "PUT"
          ],
          "AllowedOrigins": [
              "*"
          ],
          "ExposeHeaders": [],
          "MaxAgeSeconds": 3000
      }
  ]

4.2.2. 修改 Google Cloud Platform 对象存储桶
复制链接

要在 {product-title} 中使用 Google Cloud Platform 存储启用虚拟构建，您可以在 GCP 存储桶中配置跨原始资源共享(CORS)设置。这允许构建 worker 上传 Dockerfile 并访问构建工件。

注意

目前，IBM Power 和 IBM Z 不支持修改 Google Cloud Platform 对象存储桶。

流程

使用以下参考来为您的特定 CORS 需要创建一个 JSON 文件。例如：

$ cat gcp_cors.json

输出示例

[
    {
      "origin": ["*"],
      "method": ["GET"],
      "responseHeader": ["Authorization"],
      "maxAgeSeconds": 3600
    },
    {
      "origin": ["*"],
      "method": ["PUT"],
      "responseHeader": [
              "Content-Type",
              "x-goog-acl",
              "origin"],
      "maxAgeSeconds": 3600
    }
]

输入以下命令更新 GCP 存储桶：

$ gcloud storage buckets update gs://<bucket_name> --cors-file=./gcp_cors.json

输出示例

Updating
  Completed 1

您可以运行以下命令来显示 GCP 存储桶的更新 CORS 配置：

$ gcloud storage buckets describe gs://<bucket_name>  --format="default(cors)"

输出示例

cors:
- maxAgeSeconds: 3600
  method:
  - GET
  origin:
  - '*'
  responseHeader:
  - Authorization
- maxAgeSeconds: 3600
  method:
  - PUT
  origin:
  - '*'
  responseHeader:
  - Content-Type
  - x-goog-acl
  - origin

第 5 章启动新构建
复制链接

启动构建会从 {product-title} 中的 Dockerfile 创建容器镜像。您可以通过上传 Dockerfile 或使用构建触发器来手动启动构建。

先决条件

您已导航到存储库的 Builds 页面。

流程

在 Builds 页面上，单击 Start New Build。
出现提示时，单击 Upload Dockerfile 以上传 Dockerfile 或在根目录中包含 Dockerfile 的存档。
单击 Start Build。
注意
- 目前，在手动启动构建时，用户无法指定 Docker 构建上下文。
- 目前，BitBucket 在 Red Hat Quay v2 UI 上不支持。
您将被重定向到构建，可实时查看。等待 Dockerfile 构建完成 并推送。
可选。您可以点 Download Logs 下载日志，或 Copy Logs 来复制日志。
单击 back 按钮，以返回到 Repository Builds 页面，您可以在其中查看 构建历史记录。

您可以点击 Build History 页面中的提交或运行以下命令来检查构建的状态：

$ oc get pods -n virtual-builders

输出示例

NAME                                               READY   STATUS    RESTARTS   AGE
f192fe4a-c802-4275-bcce-d2031e635126-9l2b5-25lg2   1/1     Running   0          7s

构建完成后，oc get pods -n virtual-builders 命令不会返回任何资源：
```
$ oc get pods -n virtual-builders
```
输出示例
```
No resources found in virtual-builders namespace.
```

第 6 章构建触发器
复制链接

6.1. 创建构建触发器
复制链接

要从 Git 存储库自动执行容器镜像构建，您可以在 {product-title} 中创建自定义 Git 构建触发器。当您将代码推送到 Git 存储库时，构建触发器会自动构建和推送镜像。

但是，可以复制以下步骤，以使用 Github、Gitlab 或 Bitbucket 创建 构建触发器，但在 config.yaml 文件中为这些服务配置凭证。

注意

如果要使用 Github 创建 构建触发器，则必须通过创建 OAuth 应用程序将 Github 配置为与 Red Hat Quay 搭配使用。如需更多信息，请参阅"创建 OAuth 应用程序 Github"。

先决条件

对于 OpenShift Container Platform 部署上的 Red Hat Quay，您必须为裸机构建或虚拟构建配置了 OpenShift Container Platform 环境。

流程

登录到您的 Red Hat Quay registry。
在导航窗格中，单击 Repositories。
单击 Create Repository。
点 Builds 选项卡。
在 Builds 页面上，单击 Create Build Trigger。
选择所需的平台，如 Github、Bitbucket、Gitlab 或使用自定义 Git 存储库。在本例中，单击 Custom Git Repository Push。
输入自定义 Git 存储库名称，例如 git@github.com:<username>/<repo>.git。然后，单击 Next。
提示时，通过选择其中一个或两个选项来配置标记选项：
- 使用分支或标签名称标记清单。在选择此选项时，构建的清单会标记 git commit 的分支或标签名称。
- 如果在默认分支上添加 latest 标签。在选择此选项时，如果构建在存储库的默认分支中进行了标记，则构建的清单具有 latest。
  另外，您可以添加自定义标记模板。您可以在这里输入多个标签模板，包括使用提交中的简短 SHA ID、时间戳、作者名称、提交者和分支名称作为标签。如需更多信息，请参阅 "Tag naming for build triggers"。
  配置标记后，点 Next。
出现提示时，选择调用触发器时要构建的 Dockerfile 的位置。如果 Dockerfile 位于 git 存储库的根目录并命名为 Dockerfile，请输入 /Dockerfile 作为 Dockerfile 路径。然后，单击 Next。
出现提示时，选择 Docker 构建的上下文。如果 Dockerfile 位于 Git 存储库的根目录中，请输入 / 作为构建上下文目录。然后，单击 Next。
可选。选择可选的机器人帐户。这可让您在构建过程中拉取私有基础镜像。如果您知道不使用私有基础镜像，您可以跳过这一步。
点 Next。检查任何验证警告。如有必要，请在单击 Finish 前修复问题。
您会被警报，该触发器已被成功激活。请注意，使用这个触发器需要以下操作：
- 您必须授予以下对 git 存储库的读取访问权限。
- 您必须将存储库设置为 POST 到以下 URL，才能触发构建。
  保存 SSH Public Key，然后单击 return to <organization_name>/<repository_name>。您将被重定向到存储库的 Builds 页面。
在 Builds 页面中，您现在有一个 构建触发器。例如：

创建自定义 Git 触发器后，需要额外的步骤。继续继续"设置自定义 Git 触发器"。
如果您要为 Github、Gitlab 或 Bitbucket 设置构建触发器，请继续" 手动触发构建 "。

6.1.1. 设置自定义 Git 触发器
复制链接

要在 {product-title} 中完成自定义 Git 构建触发器的设置，您必须提供对 SSH 公钥的读取访问权限并配置 webhook 端点。这些步骤可让 Git 存储库在推送代码时自动触发构建。

只有在使用 自定义 Git 触发器 时，才需要这些步骤。

6.1.1.1. 获取构建触发器凭证
复制链接

要配置自定义 Git 触发器，您可以从 {product-title} 用户界面获取 SSH 公钥和 webhook 端点 URL。这些凭据位于存储库的 Builds 页面中。

先决条件

您已创建了自定义 Git 触发器。

流程

在存储库的 Builds 页面中，单击 自定义 Git 触发器 菜单 kebab。
单击 View Credentials。
保存 SSH 公钥和 Webhook 端点 URL。
通过从 Settings 或 gear 图标选择 View Credentials，可以使用密钥和 URL。

6.1.1.2. SSH 公钥访问
复制链接

{product-title} 中的 SSH 公钥访问使构建器实例能够克隆 Git 存储库以进行自定义构建触发器。通过将 {product-title} 添加到 authorized_keys 文件或使用 Deploy Keys 来安装 {product-title} 生成的 SSH 公钥。

根据 Git 服务器配置，可以通过多种方法安装 Quay 为自定义 Git 触发器生成的 SSH 公钥。

例如，服务器上获取 Git 的文档描述了如何在基于 Linux 的机器上设置 Git 服务器，专注于通过 SSH 管理存储库和访问控制。在此过程中，将小服务器设置为将密钥添加到 $HOME/.ssh/authorize_keys 文件夹，它为 构建器 提供克隆存储库的访问权限。

对于任何未正式支持的 Git 存储库管理软件，通常有一个位置来输入通常标记为 Deploy Keys 的密钥。

6.1.1.3. Webhook 参考
复制链接

Webhook 引用提供了在 {product-title} 中触发构建所需的 JSON 有效负载格式。您必须通过 提交,ref, 和 default_branch 字段来 POST JSON 有效负载，才能自动启动构建。

注意

此请求需要一个包含 application/json 的 Content-Type 标头才能有效。

Webhook 示例

{
  "commit": "1c002dd",                                   // required
  "ref": "refs/heads/master",                            // required
  "default_branch": "master",                            // required
  "commit_info": {                                       // optional
    "url": "gitsoftware.com/repository/commits/1234567", // required
    "message": "initial commit",                         // required
    "date": "timestamp",                                 // required
    "author": {                                          // optional
      "username": "user",                                // required
      "avatar_url": "gravatar.com/user.png",             // required
      "url": "gitsoftware.com/users/user"                // required
    },
    "committer": {                                       // optional
      "username": "user",                                // required
      "avatar_url": "gravatar.com/user.png",             // required
      "url": "gitsoftware.com/users/user"                // required
    }
  }
}

这通常可以通过 post-receive Git hook 来完成，但它取决于服务器设置。

6.1.2. 构建触发器的标签命名
复制链接

在 {product-title} 中构建触发器的标签命名可让您使用包含提交信息（如 SHA、分支名称、作者和日期）的模板创建自定义标签。您可以使用这些模板根据触发构建的 Git 提交，使用有意义的标识符自动标记构建的镜像。

一个选项是包括分配给每个构建镜像标签的任何字符字符串。或者，您可以使用构建触发器的 Configure Tagging 部分中的以下标签模板来标记带有每个提交信息的镜像：

Configure Tagging

${commit} ：已发布的提交的完全 SHA
${parsed_ref.branch}: 分支信息（如果可用）
${parsed_ref.tag}: 标签信息（如果可用）
${parsed_ref.remote} ：远程名称
${commit_info.date}: 签发提交的日期
${commit_info.author.username}: 提交作者的用户名
${commit_info.short_sha}: 提交 SHA 的前 7 个字符
${committer.properties.username}: committer 的 Username

此列表未完成，但包含用于标记目的的最有用的选项。您可以在此页面中找到完整的标签模板模式。https://github.com/quay/quay/blob/abfde5b9d2cf7d7145e68a00c9274011b4fe0661/buildtrigger/basehandler.py#L96-L195

6.1.3. 跳过源 control-triggered 构建
复制链接

您可以通过在提交消息中添加 [skip build] 或 [build skip] 来跳过 {product-title} 中的源控制构建。这可防止构建系统自动为不需要新构建的提交构建镜像。

6.2. 手动触发构建
复制链接

在 {product-title} 中手动构建触发可让您按需启动构建，而无需等待源控制中的自动触发器。您可以通过选择构建触发器并指定提交 ID，从 Builds 页面中手动触发构建。

流程

在 Builds 页面中，启动新构建。
出现提示时，选择 Invoke Build Trigger。
点 Run Trigger Now 来手动启动此过程。
输入要启动构建的提交 ID，例如 1c002dd。
构建启动后，您可以在 Repository Builds 页面上看到 构建 ID。

您可以点击 Build History 页面中的提交或运行以下命令来检查构建的状态：

$ oc get pods -n virtual-builders

输出示例

NAME                                               READY   STATUS    RESTARTS   AGE
f192fe4a-c802-4275-bcce-d2031e635126-9l2b5-25lg2   1/1     Running   0          7s

构建完成后，oc get pods -n virtual-builders 命令不会返回任何资源：
```
$ oc get pods -n virtual-builders
```
输出示例
```
No resources found in virtual-builders namespace.
```

第 7 章在 GitHub 中创建 OAuth 应用程序
复制链接

要在 {product-title} 中为自动构建启用 GitHub 集成，您可以在 GitHub 中创建 OAuth 应用程序。这允许 {product-title} 访问 GitHub 存储库，并在提交或拉取请求时触发容器镜像构建。

流程

登录 GitHub Enterprise。
在导航窗格中，选择 您的用户名 → 您的机构。
在导航窗格中，选择 Applications → Developer Settings。
在导航窗格中，点击 OAuth Apps → New OAuth App。您可以进入以下页面：
在 Application name 文本框中输入应用程序的名称。
在 Homepage URL 文本框中，输入您的 Red Hat Quay URL。
注意
如果您使用公共 GitHub，则输入的 Homepage URL 必须可以被您的用户访问。它仍然可能是一个内部 URL。
在 Authorization 回调 URL 中，输入 https://<RED_HAT_QUAY_URL>/oauth2/github/callback。
点 Register application 保存您的设置。
显示新应用的摘要时，记录新应用显示的客户端 ID 和客户端 Secret。

第 8 章构建故障排除
复制链接

{product-title} 中的构建程序实例是临时的，并在构建完成或失败后自动关闭。若要对构建问题进行故障排除，您必须在构建运行时捕获日志。

8.1. 调试配置标志
复制链接

{product-title} 中的 DEBUG 配置标志可防止构建器实例在构建完成或失败后自动关闭。将此标志设置为 True 以调试构建器节点问题。

  EXECUTORS:
    - EXECUTOR: ec2
      DEBUG: true
      ...
    - EXECUTOR: kubernetes
      DEBUG: true
      ...

当设置为 True 时，debug 功能可防止 构建节点在 quay-builder 服务完成或失败后关闭。它还可防止 构建管理器 通过终止 EC2 实例或删除 Kubernetes 作业来清理实例。这允许调试 构建器节点 问题。

不应在产品周期中设置调试。生命周期服务仍然存在；例如，实例仍然会在大约 2 小时后关闭。发生这种情况时，EC2 实例将终止并完成 Kubernetes 作业。

启用 debug 也会影响 ALLOWED_WORKER_COUNT，因为未确定的实例和作业仍计算为运行 worker 的总数。因此，如果达到 ALLOWED_WORKER_COUNT，则必须手动删除现有的 构建器 worker 才能调度 新构建。

8.2. OpenShift Container Platform 和 Kubernetes 构建故障排除
复制链接

要对 {product-title} 中的 OpenShift Container Platform 和 Kubernetes 构建进行故障排除，您可以创建一个端口转发隧道到构建器 pod 并通过 SSH 访问它。检查 quay-builder 服务日志以诊断构建问题。

流程

输入以下命令在本地机器和使用 OpenShift Container Platform 集群或 Kubernetes 集群运行的 pod 之间创建端口转发隧道：
```
$ oc port-forward <builder_pod> 9999:2222
```
使用指定的 SSH 密钥和端口建立到远程主机的 SSH 连接，例如：
```
$ ssh -i /path/to/ssh/key/set/in/ssh_authorized_keys -p 9999 core@localhost
```

输入以下命令来获取 quay-builder 服务日志：

$ systemctl status quay-builder

$ journalctl -f -u quay-builder

构建器和镜像自动化