access key option is required for cleaning up s3 repository - 如何解决此 Elasticsearch 异常 | Easysearch | 分布式搜索引擎

适用版本： 7.4-7.17+

1. 错误异常的基本描述 #

access_key option is required for cleaning up s3 repository 是 Elasticsearch 在执行 **S3 仓库清理（cleanup）**时抛出的凭证验证错误。当你尝试清理 S3 仓库（snapshot repository）的旧快照数据，但配置中缺少 access_key 参数时，就会触发此错误。S3 仓库的清理操作需要完整的 AWS 凭证（access_key 和 secret_key）才能进行身份验证和对象删除。

常见现象 #

Elasticsearch 返回 HTTP 400 Bad Request 状态码，响应体中包含 ElasticsearchException。
S3 仓库清理任务（POST _snapshot/<repo>/_cleanup）立即失败。
在 Elasticsearch 服务端日志中会记录详细的异常信息。
如果是通过定时任务或自动化脚本执行清理，会导致清理任务失败。
可能导致 S3 仓库中积累大量旧快照数据，占用存储空间。

典型报错与异常栈 #

该异常的典型日志形态如下：

ElasticsearchException: access_key option is required for cleaning up s3 repository
    at org.elasticsearch.repositories.s3.S3Repositories.cleanup(S3Repositories.java:...)
    at org.elasticsearch.action.admin.cluster.SnapshotCleanupTransportAction.shardOperation(SnapshotCleanupTransportAction.java:...)

通过 API 请求的响应通常如下：

{
  "error": {
    "root_cause": [
      {
        "type": "snapshot_creation_exception",
        "reason": "access_key option is required for cleaning up s3 repository"
      }
    ],
    "type": "snapshot_creation_exception",
    "reason": "access_key option is required for cleaning up s3 repository",
    "status": 400
  }
}

另一种常见形态（secret_key 缺失）：

ElasticsearchException: secret_key option is required for cleaning up s3 repository

2. 为什么会发生这个错误 #

Elasticsearch 的 S3 仓库插件在执行清理操作时，需要完整的 AWS 凭证来进行身份验证。cleanup 操作会枚举并删除旧的快照数据，这需要访问 S3 bucket 中的对象。

源码中的验证逻辑是：

String accessKey = accessKeyOption.value(options);
if (Strings.isNullOrEmpty(accessKey)) {
    throw new ElasticsearchException("access_key option is required for cleaning up s3 repository");
}

常见原因包括：

未传递 access_key 参数：cleanup 请求中没有包含 access_key 字段。
环境变量或 secret 注入失败：CI/CD 或脚本中引用环境变量失败，导致 access_key 为空。
仓库配置不完整：虽然仓库配置中可能已经有凭证，但 cleanup 操作要求显式传递。
模板配置遗漏：运维模板或 Terraform 配置中遗漏了 access_key 字段。
环境差异：不同环境（开发、测试、生产）的凭证管理方式不同，导致遗漏。
凭证轮换后未更新：AWS 凭证轮换后，cleanup 脚本中的凭证未同步更新。

3. 如何排查和解决这个异常和解决这个异常 #

排查步骤 #

建议按以下顺序进行排查：

第一步：确认错误是否来自 access_key 缺失 #

# 重现错误并查看完整响应
curl -X POST "localhost:9200/_snapshot/my_s3_repo/_cleanup" -H 'Content-Type: application/json' -d @cleanup.json 2>&1 | jq .

# 查看 Elasticsearch 日志中的详细错误
tail -n 200 /var/log/elasticsearch/elasticsearch.log | grep -A 20 "access_key option is required"

第二步：检查 cleanup 请求中的凭证参数 #

# 查看 cleanup 请求体
cat cleanup.json | jq '.'

# 检查是否包含 access_key 和 secret_key
cat cleanup.json | jq '.access_key, .secret_key'

第三步：检查仓库配置 #

# 查看仓库配置
curl -X GET "localhost:9200/_snapshot/my_s3_repo?pretty"

# 检查是否配置了 access_key
curl -X GET "localhost:9200/_snapshot/my_s3_repo?pretty" | jq '.settings.s3'

第四步：在测试环境验证 #

# 在测试环境使用完整凭证执行 cleanup
curl -X POST "localhost:9200/_snapshot/test_s3_repo/_cleanup" -H 'Content-Type: application/json' -d '
{
  "access_key": "AKIAIOSFODNN7EXAMPLE",
  "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}'

排查时需要注意的问题 #

区分仓库配置和 cleanup 参数：仓库配置中可能已经有凭证，但 cleanup 操作可能要求显式传递。
检查所有凭证字段：access_key 和 secret_key 是成对出现的，需要同时检查。
注意凭证安全：不要在日志、脚本或版本控制中明文存储凭证。
查看完整错误信息：错误信息会明确指出是缺少 access_key 还是 secret_key。

4. 如何解决这个错误 #

常用修复思路 #

方案一：在 cleanup 请求中补齐凭证（推荐） #

# 在 cleanup 请求中添加 access_key 和 secret_key
curl -X POST "localhost:9200/_snapshot/my_s3_repo/_cleanup" -H 'Content-Type: application/json' -d '
{
  "access_key": "AKIAIOSFODNN7EXAMPLE",
  "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}'

方案二：更新仓库配置，确保凭证正确 #

# 更新仓库配置，添加或更新凭证
curl -X PUT "localhost:9200/_snapshot/my_s3_repo" -H 'Content-Type: application/json' -d '
{
  "type": "s3",
  "settings": {
    "bucket": "my-elasticsearch-snapshots",
    "region": "us-east-1",
    "access_key": "AKIAIOSFODNN7EXAMPLE",
    "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }
}'

方案三：使用环境变量或 secret 管理 #

#!/bin/bash
# 从环境变量读取凭证
export AWS_ACCESS_KEY=$(cat /etc/secrets/aws_access_key)
export AWS_SECRET_KEY=$(cat /etc/secrets/aws_secret_key)

# 在 cleanup 请求中使用
curl -X POST "localhost:9200/_snapshot/my_s3_repo/_cleanup" \
  -H 'Content-Type: application/json' \
  -d "{
    \"access_key\": \"$AWS_ACCESS_KEY\",
    \"secret_key\": \"$AWS_SECRET_KEY\"
  }"

方案四：使用 IAM 角色代替静态凭证 #

# 如果 Elasticsearch 运行在 EC2 上，可以使用 IAM 角色
# 不需要在 cleanup 请求中传递 access_key 和 secret_key
curl -X PUT "localhost:9200/_snapshot/my_s3_repo" -H 'Content-Type: application/json' -d '
{
  "type": "s3",
  "settings": {
    "bucket": "my-elasticsearch-snapshots",
    "region": "us-east-1"
    # 不配置 access_key 和 secret_key，使用 IAM 角色
  }
}'

# cleanup 请求也不需传递凭证
curl -X POST "localhost:9200/_snapshot/my_s3_repo/_cleanup"

后续注意事项与推荐建议 #

建立 cleanup 任务规范：为 S3 仓库清理任务制定标准操作流程，确保凭证完整性检查。
使用 secret 管理工具：对于凭证管理，使用 AWS Secrets Manager、HashiCorp Vault 等工具，避免明文存储。
定期执行 cleanup：建立自动化的快照清理机制，避免 S3 bucket 中积累大量旧数据。
监控 cleanup 任务：通过 Elasticsearch 的监控功能或 INFINI Console 来监控 cleanup 任务执行状态。
测试环境验证：在测试环境先验证 cleanup 流程，确认凭证正确后再在生产环境执行。

借助 INFINI 产品提升排障效率 #

INFINI Console 提供快照仓库的可视化管理界面，可以直观地查看、管理和调试 S3 仓库配置。通过 Console 的仓库管理功能，可以快速发现缺少的凭证字段，并直接编辑修复。
INFINI Gateway 可以作为 Elasticsearch API 的代理层，在 cleanup 请求到达 Elasticsearch 之前进行拦截和检查。Gateway 可以自动检测缺少 access_key 的请求，并根据预定义的策略（如自动补充、拒绝请求、告警通知等）进行处理。
对于依赖 S3 进行快照备份的团队，建议结合 INFINI Console 的仓库管理功能和 INFINI Gateway 的请求治理能力，建立从仓库配置、清理、到监控的完整自动化流程，减少因凭证缺失导致的清理失败。

5. 小结 #

access_key option is required for cleaning up s3 repository 是一个典型的凭证验证错误，根源在于 S3 仓库 cleanup 操作缺少必要的 AWS 凭证。虽然报错信息直接指向 access_key 缺失，但解决思路需要根据实际情况来决定：是在请求中补齐凭证、更新仓库配置，还是使用 IAM 角色代替静态凭证。

在实际工作中，为避免此类问题，建议建立凭证管理机制、使用 secret 管理工具、并在 cleanup 脚本中添加凭证完整性检查。更重要的是，考虑使用 INFINI Console 来实现可视化的仓库管理，使用 INFINI Gateway 来拦截和预处理 cleanup 请求，从源头避免凭证缺失问题的发生。

参考文档 #

附：日志上下文 #

下面保留当前页面中的源码或日志片段，便于继续结合异常调用栈定位问题：

    throw new ElasticsearchException("you must not specify both region and endpoint");
}
String accessKey = accessKeyOption.value(options);
if (Strings.isNullOrEmpty(accessKey)) {
    throw new ElasticsearchException("access_key option is required for cleaning up s3 repository");
}
String secretKey = secretKeyOption.value(options);
if (Strings.isNullOrEmpty(secretKey)) {
    throw new ElasticsearchException("secret_key option is required for cleaning up s3 repository");
}

标签

Elasticsearch异常 S3仓库访问密钥存储库清理对象存储

access key option is required for cleaning up s3 repository - 如何解决此 Elasticsearch 异常