排查与工作负载到工作负载身份验证相关的问题

本文档介绍如何排查与通过 mTLS 向其他工作负载验证工作负载的身份相关的常见错误。

准备工作

设置身份验证（如果尚未设置）。身份验证是通过其进行身份验证以访问 Google Cloud 服务和 API 的过程。如需从本地开发环境运行代码或示例，您可以按如下方式向 Compute Engine 进行身份验证。
1. Install the Google Cloud CLI, then initialize it by running the following command:
```
gcloud init
```
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.

生成的凭据目录不存在

如果出现 /var/run/secrets/workload-spiffe-credentials 目录不存在的错误，请执行以下操作：

通过从虚拟机内运行以下命令，确保您的虚拟机支持工作负载到工作负载的身份验证。
```
curl  "http://metadata.google.internal/computeMetadata/v1/instance/gce-workload-certificates/config-status" -H "Metadata-Flavor: Google"
```
1. 如果响应是 HTTP 404 错误代码，并显示以下错误消息，则表示此虚拟机不支持此功能。
```
The requested URL /computeMetadata/v1/instance/gce-workload-certificates/config-status
was not found on this server.  That's all we know.
```
  如需解决此问题，请使用以下方法之一创建一个支持工作负载到工作负载身份验证的新虚拟机：
  - 为 MIG 启用托管式工作负载身份。
  - 为单个虚拟机启用托管式工作负载身份。
2. 如果响应为 HTTP 404 错误代码并显示错误消息 workload certificate feature not enabled，则表示虚拟机支持托管式工作负载身份，但该功能未启用。如需在虚拟机上启用该功能，请参阅在现有虚拟机上启用托管式工作负载身份。
确保虚拟机运行的是使用 Compute Engine 客机代理版本 20231103.01 或更高版本的客机操作系统。使用 gcloud CLI 查看串行端口输出以确定当前的 Compute Engine 客机代理版本：
```
gcloud compute instances get-serial-port-output VM_NAME | grep "GCE Agent Started"
```
将 VM_NAME 替换为虚拟机名称。

如需更新 Compute Engine 客机代理，请参阅更新客机环境。

检查服务日志以验证 gce-workload-cert-refresh.timer 是否能够成功提取工作负载凭据和信任软件包。

# View timer logs to see when the gce-workload-cert-refresh.timer last ran
journalctl -u gce-workload-cert-refresh.timer

# View service logs from gce-workload-cert-refresh.service
journalctl -u gce-workload-cert-refresh.service

生成的凭据目录仅包含 config_status 文件

由于各种原因，生成的凭据目录 /var/run/secrets/workload-spiffe-credentials 可能仅包含 config_status。请按照以下步骤排查此问题。

检查 config_status 文件的内容，确保已启用托管式工作负载身份功能。如果未使用适当的虚拟机元数据启用该功能，则日志文件会包含错误消息 workload certificate feature not enabled。

如需解决此问题，请使用以下方法之一创建一个支持工作负载到工作负载身份验证的新虚拟机：
- 为 MIG 启用托管式工作负载身份。
- 为单个虚拟机启用托管式工作负载身份。
检查 config_status 文件的内容，确保没有因缺少属性值或者证书颁发或信任配置无效而导致的错误。如果存在此类错误，请按照更新证书颁发和信任配置中的步骤更新配置值。
确保向工作负载身份池中的托管式工作负载身份授予正确的权限，以便访问从属 CA 池。使用以下命令：
```
gcloud privateca pools get-iam-policy SUBORDINATE_CA_POOL_ID \
   --location=SUBORDINATE_CA_POOL_REGION \
```
替换以下内容：
- SUBORDINATE_CA_POOL_ID：从属 CA 池的 ID。
- SUBORDINATE_CA_POOL_REGION：从属 CA 池的区域。
此命令的输出应包含以下内容：
```
bindings:
- members:
  - principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*
  -
  role: roles/privateca.poolReader
- members:
  - principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*
  role: roles/privateca.workloadCertificateRequester
```
在上述示例中：
- PROJECT_NUMBER 是您的 Cloud 项目的项目编号。
- POOL_ID 是工作负载身份池的 ID。
如果您没有看到与上述示例类似的输出，请按照授权托管式工作负载身份向 CA 池请求证书中所述授予所需的权限。
如果 config_status 文件不包含错误消息，请检查该文件中 iam.googleapis.com/workload-identity 的值。该值应与以下内容相匹配：
```
spiffe://POOL_ID.global.PROJECT_NUMBER.workload.id.goog/ns/NAMESPACE_ID/sa/MANAGED_IDENTITY_ID
```
在上述示例中：
- PROJECT_NUMBER 是包含托管式工作负载身份池的项目的编号。
- POOL_ID 是工作负载身份池的 ID。
- NAMESPACE_ID 是工作负载身份池中命名空间的 ID。
- MANAGED_IDENTITY_ID 是托管式工作负载身份的 ID。
如果 iam.googleapis.com/workload-identity 的值不正确，您必须使用正确的值创建新虚拟机，因为只能在创建虚拟机期间更新托管式身份值。
如果 config_status 文件不包含错误消息，请确保信任配置包含 SPIFFE 信任网域 POOL_ID.global.PROJECT_NUMBER.workload.id.goog 的有效条目，该条目对应于分配给虚拟机的托管式身份上的 SPIFFE 信任网域。如需了解详情，请参阅定义信任配置。
如果 config_status 文件包含任何带有错误代码 INTERNAL_ERROR 的错误消息，请联系 Cloud Customer Care 团队或您的 Google Cloud 联系人，并提供错误消息。

查询元数据服务器端点时返回 404 错误

如果您在查询 workload-identities 或 trust-anchors 端点时收到 404 响应，请从虚拟机内运行以下命令来确保虚拟机支持托管式工作负载身份：

curl  "http://metadata.google.internal/computeMetadata/v1/instance/gce-workload-certificates/config-status" -H "Metadata-Flavor: Google"

如果响应是 HTTP 404 错误代码，并显示以下错误消息：
```
  The requested URL /computeMetadata/v1/instance/gce-workload-certificates/config-status
  was not found on this server.  That's all we know.
```
虚拟机不支持托管式工作负载身份。如需解决此问题，请执行以下某项操作：
- 为 MIG 启用托管式工作负载身份。
- 为单个虚拟机启用托管式工作负载身份。
如果响应为 HTTP 404 错误代码并出现错误消息 workload certificate feature not enabled，则表示此虚拟机支持托管式工作负载身份，但该功能未启用。创建启用了该功能的新虚拟机，或创建新的实例模板和托管式实例组。
通过运行以下命令，确保向工作负载身份池授予了正确的权限，以便访问从属 CA 池：
```
gcloud privateca pools get-iam-policy SUBORDINATE_CA_POOL_ID \
  --location=SUBORDINATE_CA_POOL_REGION
```
替换以下内容：
- SUBORDINATE_CA_POOL_ID：从属 CA 池的 ID。
- SUBORDINATE_CA_POOL_REGION：从属 CA 池的区域。
此命令的输出应包含以下内容，其中 PROJECT_NUMBER 是您的项目编号，POOL_ID 是工作负载身份池的 ID。
```
bindings:
- members:
- principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*
- role: roles/privateca.poolReader
- members:
- principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*
- role: roles/privateca.workloadCertificateRequester
```
如果输出不包含这些值，请授予正确的权限，如授权托管式工作负载身份向 CA 池请求证书中所述。
确保 iam.googleapis.com/workload-identity 值正确且与以下内容匹配：
```
spiffe://POOL_ID.global.PROJECT_NUMBER.workload.id.goog/ns/NAMESPACE_ID/sa/MANAGED_IDENTITY_ID
```
如果值不匹配，则必须创建新的虚拟机，因为在创建虚拟机后无法更新托管式身份值。
确保信任配置包含 SPIFFE 信任网域 POOL_ID.global.PROJECT_NUMBER.workload.id.goog 的有效条目，该条目对应于分配给虚拟机的托管式身份上的 SPIFFE 信任网域。