包注册表

ENTERPRISE

使用 Web 界面或 CLI 管理包资源库

DC/OS 预配置了 Mesosphere Catalog 包资源库作为 DC/OS 包的提供程序。但这是假设有互联网接入,而这这种假设并非总是可能的。对于气隙环境,DC/OS Enterprise 提供包注册表,以便对包进行灵活无缝的管理。

有关 DC/OS 包注册表可用配置选项的完整列表,请运行以下命令:

dcos package describe package-registry --config

您可以在 [CLI 文档] (/mesosphere/dcos/cn/1.13/cli/command-reference/dcos-package/)中找到有关 dcos package 命令的更多信息。

有关如何配置和部署 DC/OS 服务的详细说明,请参阅 [配置 Catalog 服务] (/mesosphere/dcos/cn/2.0/deploying-services/config-universe-service/)。

默认安装

包注册表可以通过执行以下命令来激活启用:

# Install the package-registry CLI
dcos package install package-registry --cli --yes

# Activate the package-registry with default options
dcos registry activate

registry activate 命令使用默认选项,如果您在生产环境中安装,则 不推荐 使用。阅读其余部分以创建选项文件,然后通过执行以下命令激活包注册表:

dcos registry activate --options=<custom-options-file>

配置

如果您具有先前安装之一的配置文件,则可以跳过本部分,然后继续进行安装包注册表的下一部分。

在部署期间,可以使用以下选项来配置包注册表:

  1. 存储选项(本地存储或挂载卷或 S3 兼容存储)
  2. [服务命名空间和密钥](#service-namespacing and-secrets)

如果您具有先前安装之一的配置文件,则可以跳过本部分,然后继续进行安装包注册表的下一部分。

存储选项

包注册表可配置为使用以下内容之一:

  1. 本地存储
  2. 挂载卷
  3. S3 兼容存储

本地存储

包注册表默认使用本地存储,这 不推荐 用于生产用途。配置用于生产用途的持久卷或 S3 兼容存储。如果您将此用于开发目的并希望使用本地存储,请跳至下一部分。

挂载卷选项

在 DC/OS 上创建挂载卷,请参阅挂载卷文档,其中包括创建回送设备的示例。本指南的其余部分假设在 /dcos/package-registry 处创建了挂载卷。您必须指定 container-pathpinned-hostname,它是指挂载卷的代理的主机名。可以使用以下选项配置 package-registry 以使用挂载卷:

{
    "registry": {
        "mount-volume": {
            "container-path": "package-registry",
            "pinned-hostname": "a.specific.node.com"
        }
    }
}

S3 存储选项

如果是 DC/OS 包注册表的默认配置,则 DC/OS 包存储在主机文件系统的本地持久卷中。使用此默认存储配置时,您仅限使用注册表的一个实例。包注册表还可通过在 S3 兼容存储上存储 DC/OS 包来支持高可用性配置,这支持部署多个注册表实例。

要配置 DC/OS 包注册表以使用 S3 存储来存储 DC/OS 包,您必须提供以下详细信息:

  1. 特定的 S3 端点。
  2. S3 bucket 名称和路径。
  3. S3 访问密钥和秘密密钥。

S3 端点详细信息

使用 Amazon S3 时,参考 Amazon S3 分域和端点,获取有关潜在端点的详细信息。包注册表已经过测试,并且已知可与 Amazon S3 和 Minio 存储配合使用。它可以与任何其他 S3 兼容存储配合使用。如果您遇到与其他 S3 兼容存储连接的问题,请联系 Mesosphere 服务支持。

S3 bucket 名称和路径

S3 bucket 名称和 bucket 内路径的组合对于包注册表的每个部署都应该是唯一的。每个部署的多个实例都将确保同步访问此 bucket。

将 S3 凭据上传到 DC/OS 密钥存储库

创建(或使用现有文件)S3 凭据文件,并用它在 DC/OS 中创建基于文件的密钥。

dcos security secrets create -f ~/.aws/credentials dcos-registry-s3-credential-file

有关如何创建 AWS 凭据文件的信息,请参阅 AWS CLI 用户指南

最终 s3 配置应该如下所示:

{
    "registry": {
        "s3": {
            "credential-secret-path" : "dcos-registry-s3-credential-file",
            "credential-profile-name" : "default",
            "bucket" : "my-bucket",
            "path" : "my-path-in-bucket",
            "endpoint" : "https://s3.us-east-1.amazonaws.com"
        }
    }
}

注意:您必须覆盖 bucket路径端点等属性的值才能匹配 S3 配置。

服务命名空间和密匙

默认情况下,包注册表作为 Marathon 应用程序安装,dcos-registry 作为其 ID。该名称具有独特的重要性,因为代理上的 dockerd 已配置为信任位于 dcos-registry.marathon.l4lb.thisdcos.directory:443 的包注册表实例。如果您决定更改该名称,您需要配置 dockerd 以信任注册表部署在 <your-custom-name>.marathon.l4lb.thisdcos.directory:443 的自定义名称。例如,如果您在 /my/custom/dcos-registry 命名空间下安装包注册表,则确保注册表在 https://mycustomdcos-registry.marathon.l4lb.thisdcos.directory(群集内部)处是可访问的:

curl -k https://mycustomdcos-registry.marathon.l4lb.thisdcos.directory
{"checks":{"/repo":{"Healthy":{"message":"Able to find 0 package(s)."}}}}

您还必须要求 dockerd 信任上述域名。要配置 dockerd 以信任在 mycustomdcos-registry.marathon.l4lb.thisdcos.directory 处的包注册表 ,请执行以下命令:

sudo mkdir -p /etc/docker/certs.d/mycustomdcos-registry.marathon.l4lb.thisdcos.directory
sudo cp /run/dcos/pki/CA/ca-bundle.crt /etc/docker/certs.d/mycustomdcos-registry.marathon.l4lb.thisdcos.directory/ca.crt
sudo systemctl restart docker

设置服务帐户和密匙

DC/OS 包注册表需要通过一个服务帐户在 DC/OS Enterprise 中运行。使用以下步骤创建具有基本权限的服务帐户。

  1. 使用 DC/OS Enterprise CLI:

    dcos package install dcos-enterprise-cli --yes
    
  2. 为服务帐户创建专用/公共密钥对:

    dcos security org service-accounts keypair private-key.pem public-key.pem
    
  3. 创建服务帐户:

    dcos security org service-accounts create -p public-key.pem -d "dcos_registry service account" registry-account
    
  4. 在密钥存储库存储专用钥匙:

    dcos security secrets create-sa-secret --strict private-key.pem registry-account registry-private-key
    
  5. 对服务帐户进行全面授权:

    dcos security org users grant registry-account dcos:adminrouter:ops:ca:rw full
    

重要信息:与服务帐户相关联的密钥信息存储在 DC/OS 密钥存储库中名为 registry-private-key 的路径中。如要使用不同的文件名,请用它替换 registry-private-key

警告:这些指令在本地文件系统上创建两个敏感文件:private-key.pempublic-key.pem。务必将这些文件保存在安全的地方或将其删除。在 DC/OS 密钥存储库中存储之后就不需要再保留它们了。

服务 instancescpusmemdisk 也可根据需要进行配置。执行以下命令以查看所有配置选项的详尽列表:

dcos package describe package-registry --config

以下是服务的示例配置文件:

> cat package-registry-options.json
{
    "registry": {
        "s3": {
            "credential-secret-path" : "dcos-registry-s3-credential-file",
            "credential-profile-name" : "default",
            "bucket" : "my-bucket",
            "path" : "my-path-in-bucket",
            "endpoint" : "https://s3.us-east-1.amazonaws.com"
        },
        "service-account-secret-path" : "dcos-registry-secret"
    },
    "service": {
        "mem" : 2048,
        "instances" : 2
    }
    "
}

安装

现在您已成功创建配置文件(从此处开始被称为 package-registry-options.json),您已准备好安装包注册表。这可以通过以下方式实现:

dcos package install package-registry --options=package-registry-options.json

这将为 package-registry 启动 Marathon 应用程序。这通常需要几分钟时间。一旦 package-registry 运行状态良好,便可以将其添加作为 DC/OS 中的包资源库之一。这可以通过以下方式完成:

# Change the repo name and URL if you need to customize
dcos package repo add --index=0 "Registry" https://dcos-registry.marathon.l4lb.thisdcos.directory/repo

如果在执行上述命令时发生错误,请等几分钟(以考虑 package-registry 良好运行状态的延迟以及其 DNS 条目传播到所有管理节点的情况)并重试。

使用包注册表

在安装 package-registry 后,您可以开始向其添加包。使用包注册表的两步过程如下:

  1. 构建包文件(.dcos 文件)
  2. 将包上传至 package-registry

构建包

Mesosphere 将其所有已认证包在 downloads.mesosphere.com/universe/packages/packages.html 处托管。如果您需要的包可用,您可以下载并跳转至下一个部分,将这些 .dcos 文件上传到您的群集。当 Catalog 包正在开发中并且您希望在创建拉取请求前对其进行测试,或者如果您希望构建非认证(社区)包,此部分非常有用。

要求

  1. 确保您拥有有效的 Catalog 包定义文件 (Schema)。请注意,package-registry 仅支持使用 Catalog 打包系统 v4 或更高模式打包的包。请参阅 创建包,了解更多详细信息。 1.您的系统安装了 docker如果 您的包使用 Docker 镜像)。
  2. 还需要安装包注册表 CLI。实现这一点有两种方法。
    1. 从 DC/OS 群集安装 package-registry CLI。

      # Install CLI subcommand "registry"
      dcos package install --cli package-registry
      # Make sure the subcommand works
      dcos registry --help
      
    2. 如果您无权访问 DC/OS 群集(例如在 CI/CD 中),请下载 LinuxmacOSWindows 系统用的 package-registryCLI

      # Change the URL based on macOS, linux or windows accordingly.
      curl -o dcos-registry https://downloads.mesosphere.io/package-registry/binaries/cli/darwin/x86-64/latest/dcos-registry-darwin
      # Give executable permissions to downloaded binary
      chmod +x dcos-registry
      # Make sure the executable works
      ./dcos-registry registry --help
      

      在本页的其余指令中,我们假设您已从附加的 DC/OS 群集下载了子命令。如果不是这样,请在指令中将 dcos 替换为 ./dcos-registry

生成 .dcos 捆绑包的说明

package-registry CLI 可用于将包捆绑到 .dcos 文件,该文件可以被 package-registry 使用。假设 Catalog 包文件在名为 /path/to/package/ 的目录中。它应包含以下包定义文件:

➜ tree
.
├── config.json
├── marathon.json.mustache
├── package.json
└── resource.json

注意:resource.json 中的所有资产 URI 必须能访问才可以从您的环境中下载。也接受相对文件路径。

# Create a temporary work directory to store the build definition and other files necessary to create the bundle.
mkdir /path/to/output

# `migrate` the unvierse package defintion to create a build defintion for the `.dcos` file.
dcos registry migrate --package-directory=/path/to/package --output-directory=/path/to/output

# `build` to download all the requrired assets and generate a `.dcos` file. This may take a while.
dcos registry build --build-definition-file=/path/to/output/<json-build-defintion-generated-above> --output-directory=/path/to/output

如果所有这些步骤都已成功完成,则您的 /path/to/output 目录应类似于以下内容:

➜ tree
.
├── <package-name>-<package-version>.dcos
└── <package-name>-<package-version>.json

您可以清除构建定义 .json 文件,因为不再需要它。buildmigrate 子命令均接受可选的 --json 标记,以支持自动化。

执行上述所有步骤后,您应该拥有一个全新的 .dcos 文件。

将包上传至包注册表

现在您已经拥有所需的全部 .dcos 文件,您可以继续执行:

dcos registry add --dcos-file <your-file>.dcos

这是不同步的,需要几分钟时间才能在 Catalog 中看到该包。即使上述命令出错(即使在网络连接缓慢的情况下成功上传时也可能发生),您可以通过执行以下步骤跟踪上传状态:

dcos registry describe --package-name=<package-name> --package-version=<package-version>

请耐心等待几分钟,以便包得以上传、处理以及在 Catalog 中可见。

请参阅 dcos registry --help,了解可用于管理包注册表中包的操作的详尽列表。registry 子命令允许您 addremovedescribe 包。

警告:在仍在部署服务时移除一个包可能会导致服务停止工作。

执行上述指令后,其余流程与从 Catalog 获取的包相同。唯一的区别就是您不需要互联网接入(对于具有气隙环境的客户)就可从 package-registry 安装包。