排查 Apigee Hybrid 卡在正在创建或正在发布状态的问题

您正在查看 Apigee 和 Apigee Hybrid 文档。
此主题没有等效的 Apigee Edge 文档。

本文档介绍如何在 Apigee Hybrid 组件卡在 creating 或 releasing 状态时进行重置。

运行以下命令可列出 Apigee Hybrid 安装主要组件：

kubectl get crd | grep apigee

apigeeorganization (apigeeorganizations.apigee.cloud.google.com)
apigeeenvironment (apigeeenvironments.apigee.cloud.google.com)
apigeedatastore (apigeedatastores.apigee.cloud.google.com)
apigeetelemetries (apigeetelemetries.apigee.cloud.google.com)
apigeeredis (apigeeredis.apigee.cloud.google.com)

运行以下命令可显示当前状态：

kubectl get apigeedatastore -n NAMESPACE

当这些组件完全正常运行时，每个组件都将处于 running 状态。例如：

NAME      STATE     AGE
default   running   5d6h

如果安装失败，组件可能会卡在 creating（或 releasing）状态。例如：

NAME      STATE     AGE
default   creating   5d6h

确定问题

如需确定问题的原因，请先描述每个组件。这些组件的结构如下：

每个 ApigeeOrganization 自定义资源都由以下层次结构表示：

ApigeeOrganization/HASHED_VALUE
├─ApigeeDeployment/apigee-connect-agent-HASHED_VALUE
│ ├─HorizontalPodAutoscaler/apigee-connect-agent-HASHED_VALUE-VER-xxxx
│ ├─PodDisruptionBudget/apigee-connect-agent-HASHED_VALUE
│ ├─ReplicaSet/apigee-connect-agent-HASHED_VALUE-VER-xxxx
│ │ └─Pod/apigee-connect-agent-HASHED_VALUE-VER-xxxx
├─ApigeeDeployment/apigee-mart-HASHED_VALUE
│ ├─HorizontalPodAutoscaler/apigee-mart-HASHED_VALUE-VER-xxxx
│ ├─PodDisruptionBudget/apigee-mart-HASHED_VALUE
│ ├─ReplicaSet/apigee-mart-HASHED_VALUE-VER-xxxx
│ │ └─Pod/apigee-mart-HASHED_VALUE-VER-xxxx
├─ApigeeDeployment/apigee-watcher-HASHED_VALUE
│ ├─HorizontalPodAutoscaler/apigee-watcher-HASHED_VALUE-VER-xxxx
│ ├─PodDisruptionBudget/apigee-watcher-HASHED_VALUE
│ ├─ReplicaSet/apigee-watcher-HASHED_VALUE-VER-xxxx
│ │ └─Pod/apigee-watcher-HASHED_VALUE-VER-xxxx

每个 ApigeeEnvironment 自定义资源都由以下层次结构表示：

ApigeeEnvironment/HASHED_VALUE
├─ApigeeDeployment/apigee-runtime-HASHED_VALUE
│ ├─HorizontalPodAutoscaler/apigee-runtime-HASHED_VALUE-VER-xxxx
│ ├─PodDisruptionBudget/apigee-runtime-HASHED_VALUE
│ ├─ReplicaSet/apigee-runtime-HASHED_VALUE-VER-xxxx
│ │ └─Pod/apigee-runtime-HASHED_VALUE-VER-xxxx
├─ApigeeDeployment/apigee-synchronizer-HASHED_VALUE
│ ├─HorizontalPodAutoscaler/apigee-synchronizer-HASHED_VALUE-VER-xxxx
│ ├─PodDisruptionBudget/apigee-synchronizer-HASHED_VALUE
│ ├─ReplicaSet/apigee-synchronizer-HASHED_VALUE-VER-xxxx
│ │ └─Pod/apigee-synchronizer-HASHED_VALUE-VER-xxxx
├─ApigeeDeployment/apigee-udca-HASHED_VALUE
│ ├─HorizontalPodAutoscaler/apigee-udca-HASHED_VALUE-VER-xxxx
│ ├─PodDisruptionBudget/apigee-udca-HASHED_VALUE
│ ├─ReplicaSet/apigee-udca-HASHED_VALUE-VER-xxxx
│ │ └─Pod/apigee-udca-HASHED_VALUE-VER-xxxx

通过描述根组件开始问题识别。例如：

kubectl describe apigeeorganization -n NAMESPACE COMPONENT_NAME

检查组件的 State 是否为 running：

      Replicas:
        Available:  1
        Ready:      1
        Total:      1
        Updated:    1
      State:        running
  State:            running
Events:             <none>

如果此级别没有记录任何事件，请使用 apigeedeployments 后跟 ReplicaSet 重复此过程。例如：

kubectl get apigeedeployment -n NAMESPACE AD_NAME>

如果 apigeedeployments 和 ReplicaSet 未显示任何错误，请专注于尚未准备就绪的 pod：

kubectl get pods -n NAMESPACE

NAME                                                              READY   STATUS
apigee-cassandra-default-0                                        1/1     Running
apigee-connect-agent-apigee-b56a362-150rc2-42gax-dbrrn            1/1     Running
apigee-logger-apigee-telemetry-s48kb                              1/1     Running
apigee-mart-apigee-b56a362-150rc2-bcizm-7jv6w                     0/2     Running
apigee-runtime-apigee-test-0d59273-150rc2-a5mov-dfb29             0/1     Running

在本示例中，mart 和 runtime 尚未准备就绪。检查 pod 日志以确定错误：

kubectl logs -n NAMESPACE POD_NAME

删除组件

如果上述任一组件出错，请删除该组件并使用 Helm 重新创建环境：

kubectl delete -n apigee apigeeenv HASHED_ENV_NAME

接着创建环境（进行必要的更正后）：

helm upgrade ENV_NAME apigee-env/ \
--install \
--namespace APIGEE_NAMESPACE \
--set env=ENV_NAME \
--atomic \
-f OVERRIDES_FILE \
--dry-run=server

请务必包含显示的所有设置，包括 --atomic，以便在操作失败时进行回滚。

安装图表：

helm upgrade ENV_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set env=ENV_NAME \
  --atomic \
  -f OVERRIDES_FILE

检查控制器

如果 pod 中没有明显的错误消息，但组件尚未转换为 running 状态，请检查 apigee-controller 以获取错误消息。

kubectl logs -n NAMESPACE $(k get pods -n NAMESPACE | sed -n '2p' | awk '{print $1}') | grep -i error

这使用户可以了解控制器无法处理请求的原因（属于 create/delete/update 等）。

Apigee 数据存储区

Apache Cassandra 是作为 StatefulSet 实现的。每个 Cassandra 实例都包含以下内容：

ApigeeDatastore/default
├─Certificate/apigee-cassandra-default
│ └─CertificateRequest/apigee-cassandra-default-wnd7s
├─Secret/config-cassandra-default
├─Service/apigee-cassandra-default
│ ├─EndpointSlice/apigee-cassandra-default-7m9kx
│ └─EndpointSlice/apigee-cassandra-default-gzqpr
└─StatefulSet/apigee-cassandra-default
  ├─ControllerRevision/apigee-cassandra-default-6976b77bd
  ├─ControllerRevision/apigee-cassandra-default-7fc76588cb
  └─Pod/apigee-cassandra-default-0

此示例展示一个 pod；但是，典型的生产安装包含三个或更多 pod。

如果 Cassandra 的状态为 creating 或 releasing，则必须重置状态。某些问题（例如 Cassandra 密码更改）和与网络无关的问题可能需要您删除组件。在这些情况下，您很有可能无法删除实例（即 kubectl delete apigeedatastore -n NAMESPACE default）。使用 --force 或 --grace-period=0 也不起作用。

reset 的目标是将组件 (apigeedatastore) 的状态从 creating 或 releasing 更改回 running。以这种方式更改状态通常不能解决根本问题。在大多数情况下，该组件会在重置后被删除。

警告：删除 apigeedatastore 还会删除永久性卷。Cassandra 中的所有数据都将丢失。建议您备份 Cassandra 数据。

尝试删除（不会成功）：
```
kubectl delete -n NAMESPACE apigeedatastore default
```
此命令通常无法完成。使用 Ctrl+C 并终止调用。

重置状态：

在窗口 1 上：

kubectl proxy

在窗口 2 上：

curl -X PATCH -H "Accept: application/json" -H "Content-Type: application/json-patch+json" --data '[{"op": "replace", "path": "/status/nestedState", "value": ""},{"op": "replace", "path": "/status/state", "value": "running"}]' 'http://127.0.0.1:8001/apis/apigee.cloud.google.com/v1alpha1/namespaces/apigee/apigeedatastores/default/status'

移除终结器（窗口 2）：

kubectl edit -n NAMESPACE apigeedatastore default

查找以下两行并删除它们：

finalizers:
- apigeedatastore.apigee.cloud.google.com

常见错误场景

代理配置不适用于运行时

此错误可能会通过以下两种方式之一出现：

runtime 未处于 ready 状态。
runtime 尚未收到最新版本的 API。

从 synchronizer pod 开始。

检查 synchronizer 的日志。常见错误如下：
- 缺少网络连接（指向 *.googleapi.com）
- IAM 访问权限不正确（服务账号不可用或 Synchronizer Manager 权限未提供）
- 未调用 setSyncAuthorization API
检查 runtime pod。

检查 runtime pod 中的日志会显示 runtime 未加载配置的原因。控制平面会尝试阻止大多数配置错误到达数据平面。如果无法验证或未正确实现，runtime 将无法加载配置。

控制平面中“无运行时 pod”

从 synchronizer pod 开始。

检查 synchronizer 的日志。常见错误如下：
- 缺少网络连接（指向 *.googleapi.com）
- IAM 访问权限不正确（服务账号不可用或 Synchronizer Manager 权限未提供）
- 未调用 setSyncAuthorization API。配置可能从未到达数据平面。
检查 runtime pod。

检查 runtime pod 中的日志会显示 runtime 未加载配置的原因。
检查 watcher pod。

它是配置入站流量（路由）和向控制平面报告代理和入站流量部署状态的 watcher 组件。检查这些日志以了解 watcher 未报告状态的原因。常见原因包括 overrides.yaml 文件中的名称与环境名称和/或环境组名称的控制平面不匹配。

控制平面中未显示调试会话

从 synchronizer pod 开始。

检查 synchronizer 的日志。常见错误如下：
- 缺少网络连接（指向 *.googleapi.com）
- IAM 访问权限不正确（服务账号不可用或 Synchronizer Manager 权限未提供）
- 未调用 setSyncAuthorization API。
检查 runtime pod。
检查 runtime pod 中的日志将显示 runtime 未将调试日志发送到 UDCA 的原因。
检查 UDCA pod。
检查来自 UDCA 的日志显示 UDCA 为什么不向控制平面发送调试会话信息的原因。

Cassandra 返回大型缓存响应

以下警告消息表示 Cassandra 正在接收具有较大载荷的读取或写入请求，可以放心地忽略该警告消息，因为此警告阈值已设置为较低的值以指示响应载荷大小。

Batch for [cache_ahg_gap_prod_hybrid.cache_map_keys_descriptor, cache_ahg_gap_prod_hybrid.cache_map_entry] is of size 79.465KiB, exceeding specified threshold of 50.000KiB by 29.465KiB