mcpField
P
push-to-registry

push-to-registry

github.com/hashicorp云与 DevOps9093.0k 次安装今天更新
代码仓库

关于 push-to-registry

这项技能介绍如何配置 Packer 构建，将构建元数据发布到 HCP Packer Registry。它帮助团队标记镜像构建、配置注册表身份验证，并将发布流程纳入 CI/CD 工作流。

主要功能

  1. 01HCP Packer Registry 配置
  2. 02存储桶与构建标签
  3. 03服务主体身份验证
  4. 04GitHub Actions CI/CD 示例
  5. 05通过 Terraform 查询制品

适用场景

  1. 01向 HCP Packer 发布构建元数据
  2. 02使用标签跟踪镜像构建
  3. 03在 CI/CD 中自动推送注册表
  4. 04通过 Terraform 查询注册表制品

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/hashicorp/agent-skills --skill push-to-registry

安装后在 Claude Code 中输入/push-to-registry确认已加载。

详细介绍

推送到 HCP Packer Registry

配置 Packer 模板，将构建元数据推送到 HCP Packer Registry。

参考： HCP Packer Registry

注意： HCP Packer 基础使用免费。构建只会推送元数据（不包含实际镜像），开销极小（不到 1 分钟）。

基本 Registry 配置

packer {
  required_version = ">= 1.7.7"
}

variable "image_name" {
  type    = string
  default = "web-server"
}

locals {
  timestamp = regex_replace(timestamp(), "[- TZ:]", "")
}

source "amazon-ebs" "ubuntu" {
  region        = "us-west-2"
  instance_type = "t3.micro"

  source_ami_filter {
    filters = {
      name = "ubuntu/images/*ubuntu-jammy-22.04-amd64-server-*"
    }
    most_recent = true
    owners      = ["099720109477"]
  }

  ssh_username = "ubuntu"
  ami_name     = "${var.image_name}-${local.timestamp}"
}

build {
  sources = ["source.amazon-ebs.ubuntu"]

  hcp_packer_registry {
    bucket_name = var.image_name
    description = "Ubuntu 22.04 base image for web servers"

    bucket_labels = {
      "os"   = "ubuntu"
      "team" = "platform"
    }

    build_labels = {
      "build-time" = local.timestamp
    }
  }

  provisioner "shell" {
    inline = [
      "sudo apt-get update",
      "sudo apt-get upgrade -y",
    ]
  }
}

身份验证

构建前设置环境变量：

export HCP_CLIENT_ID="your-service-principal-client-id"
export HCP_CLIENT_SECRET="your-service-principal-secret"
export HCP_ORGANIZATION_ID="your-org-id"
export HCP_PROJECT_ID="your-project-id"

packer build .
创建 HCP 服务主体
  1. 前往 HCP → Access Control (IAM)
  2. 创建服务主体
  3. 为项目授予 "Contributor" 角色
  4. 生成客户端密钥
  5. 保存客户端 ID 和密钥

Registry 配置选项

bucket_name（必填）

镜像标识符。必须在各次构建中保持一致！

bucket_name = "web-server"  # Keep this constant
bucket_labels（可选）

存储桶级别的元数据。每次构建时都会更新。

bucket_labels = {
  "os"        = "ubuntu"
  "team"      = "platform"
  "component" = "web"
}
build_labels（可选）

每次迭代的元数据。构建完成后不可更改。

build_labels = {
  "build-time" = local.timestamp
  "git-commit" = var.git_commit
}

CI/CD 集成

GitHub Actions
name: Build and Push to HCP Packer

on:
  push:
    branches: [main]

env:
  HCP_CLIENT_ID: ${{ secrets.HCP_CLIENT_ID }}
  HCP_CLIENT_SECRET: ${{ secrets.HCP_CLIENT_SECRET }}
  HCP_ORGANIZATION_ID: ${{ secrets.HCP_ORGANIZATION_ID }}
  HCP_PROJECT_ID: ${{ secrets.HCP_PROJECT_ID }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-packer@main

      - name: Build and push
        run: |
          packer init .
          packer build \
            -var "git_commit=${{ github.sha }}" \
            .

在 Terraform 中查询

data "hcp_packer_artifact" "ubuntu" {
  bucket_name  = "web-server"
  channel_name = "production"
  platform     = "aws"
  region       = "us-west-2"
}

resource "aws_instance" "web" {
  ami           = data.hcp_packer_artifact.ubuntu.external_identifier
  instance_type = "t3.micro"

  tags = {
    PackerBucket = data.hcp_packer_artifact.ubuntu.bucket_name
  }
}

常见问题

身份验证失败

  • 验证 HCP_CLIENT_ID 和 HCP_CLIENT_SECRET
  • 确保服务主体具有 Contributor 角色
  • 检查组织和项目 ID

存储桶名称不匹配

  • 确保各次构建中的 bucket_name 保持一致
  • 不要在 bucket_name 中包含时间戳
  • 名称更改时会创建新的存储桶

构建失败

  • 如果无法推送元数据，Packer 会立即失败
  • 防止制品与 Registry 之间出现偏差
  • 检查与 HCP API 的网络连接

最佳实践

  • 保持存储桶名称一致 - 同一镜像类型绝不更改名称
  • 使用有意义的标签 - 用于版本、团队和合规信息
  • 自动化 CI/CD - 自动执行构建并推送到 Registry
  • 使用不可变的构建标签 - 将变化的数据（git SHA、日期）放入 build_labels

参考资料

评论

支持 Markdown