升级AWS PHP SDK至v3后实例元数据凭证获取及缓存异常排查

将AWS PHP SDK从v2升级到v3后，服务无法从实例元数据服务器获取凭证，报cURL错误28（超时）。原v2版本通过YAML配置从实例元数据获取凭证并缓存到文件可正常运行，升级v3后调整了缓存配置仍报错。

v2版本配置 #

my_app.infrastructure.s3.client.credentials_cache.adapter:
        class: Doctrine\Common\Cache\FilesystemCache
        public: false
        arguments:
            - '%kernel.cache_dir%/aws_credentials'

my_app.infrastructure.s3.client.credentials_cache:
        class: Guzzle\Cache\DoctrineCacheAdapter
        public: false
        arguments:
            - '@my_app.infrastructure.s3.client.credentials_cache.adapter'

my_app.infrastructure.s3.client:
        class: Aws\S3\S3Client
        factory: [ 'Aws\S3\S3Client', 'factory' ]
        arguments:
            - region: "%my_app_organization_dictionary_aws_s3_region%"
              credentials.cache: '@my_app.infrastructure.s3.client.credentials_cache'

v3版本配置 #

my_app.infrastructure.s3.client.credentials_cache.adapter:
        class: Doctrine\Common\Cache\FilesystemCache
        public: false
        arguments:
            - '%kernel.cache_dir%/aws_credentials'

my_app.infrastructure.s3.client.credentials_cache:
        class: Aws\DoctrineCacheAdapter
        public: false
        arguments:
            - '@my_app.infrastructure.s3.client.credentials_cache.adapter'

my_app.infrastructure.s3.client.credentials_provider:
        class: Aws\Credentials\CredentialProvider
        factory: [ 'Aws\Credentials\CredentialProvider', 'defaultProvider' ]
        public: false

my_app.infrastructure.s3.client.cached_credentials_provider:
        class: Aws\Credentials\CredentialProvider
        factory: [ 'Aws\Credentials\CredentialProvider', 'cache' ]
        arguments:
            - '@my_app.infrastructure.s3.client.credentials_provider'
            - '@my_app.infrastructure.s3.client.credentials_cache'
        public: false

my_app.infrastructure.s3.client:
        class: Aws\S3\S3Client
        factory: [ 'Aws\S3\S3Client', 'factory' ]
        arguments:
            - region: "%my_app_organization_dictionary_aws_s3_region%"
              version: 'latest'
              credentials: '@my_app.infrastructure.s3.client.cached_credentials_provider'

错误信息 #

FAIL AWS S3: Fail check the AWS S3 with bucket "my_app_bucket". 
Reason: [Aws\Exception\CredentialsException] 
Error retrieving credentials from the instance profile metadata server. 
(cURL error 28: Operation timed out after 1001 milliseconds with 0 bytes received for http://169.254.169.254/latest/api/token).

排查与解决方案 #

1. 检查元数据服务器访问权限 #

• 确认运行服务的环境（EC2实例、EKS Pod等）能正常访问169.254.169.254：
  • 执行curl -v http://169.254.169.254/latest/api/token测试连通性，看是否能获取到临时token
  • 检查实例是否关联了正确的IAM角色，且角色具备S3访问权限
  • 容器环境下，确认网络策略未阻止对元数据服务器的访问

2. 调整v3凭证提供者的超时配置 #

AWS SDK v3的defaultProvider默认超时较短，可手动调整元数据请求的超时时间：
修改credentials_provider的定义，添加超时参数：

my_app.infrastructure.s3.client.credentials_provider:
        class: Aws\Credentials\CredentialProvider
        factory: [ 'Aws\Credentials\CredentialProvider', 'defaultProvider' ]
        public: false
        arguments:
            - { timeout: 5 } # 调整为5秒超时，按需修改

3. 确认缓存配置生效 #

• 检查%kernel.cache_dir%/aws_credentials目录是否存在，且服务进程有读写权限
• 手动清空缓存目录，测试是否能重新获取并缓存凭证
• 验证Aws\DoctrineCacheAdapter是否正确包装了Doctrine的FilesystemCache，确保缓存逻辑正常

4. 简化凭证配置（临时测试） #

暂时跳过缓存，直接使用默认提供者测试，确认是否是缓存逻辑问题：

my_app.infrastructure.s3.client:
        class: Aws\S3\S3Client
        factory: [ 'Aws\S3\S3Client', 'factory' ]
        arguments:
            - region: "%my_app_organization_dictionary_aws_s3_region%"
              version: 'latest'
              # 直接使用默认提供者，跳过自定义缓存
              credentials: '@my_app.infrastructure.s3.client.credentials_provider'

如果此配置正常，说明问题出在缓存包装环节，需检查cached_credentials_provider的参数传递是否正确。

5. 检查SDK版本兼容性 #

确认使用的AWS PHP SDK v3版本与Doctrine Cache版本兼容，避免依赖冲突：

• 查看composer.lock中aws/aws-sdk-php和doctrine/cache的版本，确保无版本不匹配问题
• 尝试更新到最新稳定版SDK，修复已知的凭证获取bug

内容的提问来源于stack exchange，提问作者Konstantin Soroka