部署错误配置失败

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

问题

通过 Edge 界面或管理 API 部署 API 代理或共享流修订版本失败，并显示“配置失败”错误。

错误消息

您会在 Edge 界面中收到如下所示的错误消息：

The revision is deployed, but traffic cannot flow.
com.apigee.kernel.exceptions.spi.UncheckedException{ code = application.bootstrap.FailedToConfigure, message = Configuration failed, associated contexts = []}

以下是在 Edge 界面中观察到的示例错误消息的屏幕截图：

可能的原因

API 代理的部署可能会因多种不同原因而失败，并显示“配置失败”错误。下表列出了一些导致此错误的常见原因：

原因 说明 适用的问题排查说明
JavaCallout 政策中缺少 Java 类 JavaCallout 政策引用的 JAR 文件中缺少某个 Java 类。 Edge Private Cloud 用户
在条件流的条件中使用了错误的运算对象 条件中运算符的一侧或两侧使用的操作数/表达式无效。
消息日志记录政策中的主机名无效 MessageLogging 政策中使用的主机名无法解析，或者可能包含某些不需要的特殊字符。
KeyValueMap 名称无效 API 代理中的 KeyValueMapOperations 政策中的 KeyValueMap 无效或为空。

常见诊断步骤

  1. 使用以下 API 获取您正在观察部署错误的 API 代理的特定修订版本的部署状态：

    curl -v <management-server-host>:<port#>/v1/runtime/organizations/<org-name>/environments/<env-name>/apis/<apiproxy-name>/revisions/deployments -u <user>

  2. 以下是上述 API 的输出示例；

    "server" : [ { 
"error" : "com.apigee.kernel.exceptions.spi.UncheckedException{ code = application.bootstrap.FailedToConfigure, message = Configuration failed, associated contexts = []}", 
"status" : "error", 
"type" : [ "message-processor" ], 
"uUID" : "0a20926c-f4bf-401b-af84-05fd84b9f492" 
}, { 
"error" : "com.apigee.kernel.exceptions.spi.UncheckedException{ code = application.bootstrap.FailedToConfigure, message = Configuration failed, associated contexts = []}", 
"status" : "error", 
"type" : [ "message-processor" ], 
"uUID" : "f2ee6ab4-a108-4465-a7ba-b56530d8e3fc" 
}, { 
"error" : "com.apigee.kernel.exceptions.spi.UncheckedException{ code = application.bootstrap.FailedToConfigure, message = Configuration failed, associated contexts = []}", 
"status" : "error", 
"type" : [ "message-processor" ], 
"uUID" : "0f41991e-b310-4e77-aac5-5fdb150ef9f6" 
},

  3. 您会在部署状态输出中看到每个消息处理器的错误消息“配置失败”。

  4. 登录其中一个消息处理器，然后检查日志 /opt/apigee/var/log/edge-message-processor/logs/system.log。查看 API 代理部署期间是否存在任何错误。

  5. 根据在消息处理器日志中观察到的错误/异常，您需要按照相应的问题排查步骤和解决方案操作。

  6. 以下部分介绍了一些最常导致“配置失败”部署错误的异常，并提供了排查和解决这些异常的步骤。

原因：JavaCallout 政策中缺少 Java 类

诊断

  1. 在消息处理器日志中，如果您在部署 API 代理 (DeployEvent) 期间看到任何包含消息 "Failed to instantiate the JavaCallout Class" 的异常（如下所示），请继续执行第 2 步。如果不是，请参阅条件流中的条件中使用了不正确的操作数。

  2. 在部署 API 代理期间，消息处理器显示以下异常：

    2017-10-10 05:02:42,330 Apigee-Main-5 ERROR MESSAGING.CONFIGURATION - MessageProcessorServiceImpl.configure() : error configuring config events [DeployEvent{organization='myorg', application='oauth2', applicationRevision='14', deploymentSpec=basepath=/;env=dev;, deploymentID=null}] 
com.apigee.kernel.exceptions.spi.UncheckedException: Failed to instantiate the JavaCallout Class com.something.apigee.callout.crypto.main.SecretCallout 
at com.apigee.steps.javacallout.JavaCalloutStepDefinition.newInstance(JavaCalloutStepDefinition.java:89) ~[javacallout-1.0.0.jar:na] 
at com.apigee.messaging.runtime.StepDefinition.getStepDefinitionExecution(StepDefinition.java:230) ~[message-processor-1.0.0.jar:na] 
…
<snipped>

  3. 上述异常中的错误消息表明 JavaCallout 类 com.something.apigee.callout.crypto.main.SecretCallout 无法实例化。如果 JavaCallout 政策中指定的 JAR 文件或其任何相关 JAR 文件中没有特定类，通常会发生此错误。

  4. 检查包含与软件包 com.something.apigee.callout.crypto.main 相关的所有类的 JAR 文件，并确认缺少特定类 com.something.apigee.callout.crypto.main.SecretCallout。

分辨率

  1. 将缺少的类添加到特定 JAR 文件，然后上传该 JAR 文件。
  2. 重新部署 API 代理。
  3. 在上述示例中，我们通过以下方式解决了问题：
    1. 将缺少的类 com.something.apigee.callout.crypto.main.SecretCallout 添加到 JAR 文件。
    2. 上传更新后的 JAR 文件并重新部署 API 代理。

原因：在条件流中使用了错误的运算符操作数

诊断

  1. 在消息处理器日志中，如果您在部署 API 代理或共享流期间看到 com.apigee.expressions.parser.ParseException ，如以下示例消息所示，请继续执行第 2 步。如果不是，请参阅下一个原因：消息记录政策中的主机名无效。

    错误消息示例

    com.apigee.expressions.parser.ParseException: Both the operands for EQUALS expression should be data expressions

  2. 下面我们来看一个示例，了解如何诊断此问题。

    示例：<Operator> 表达式的操作数应为数据表达式

  3. 在部署共享流期间，消息处理器显示以下异常：

    2017-11-23 09:11:04,498  Apigee-Main-6 ERROR MESSAGING.RUNTIME - AbstractConfigurator.loadXMLConfigurations() : Unable to Load default for path /organizations/myorg/apiproxies/Introspection/revisions/12/sharedflows/default
2017-11-23 09:11:04,499  Apigee-Main-6 ERROR MESSAGING.RUNTIME - Application.sync() :  sync error for Introspection and revision 12
2017-11-23 09:11:04,499  Apigee-Main-6 ERROR MESSAGING.RUNTIME - Application.sync() :  Actual Error
com.apigee.expressions.parser.ParseException: Both the operands for EQUALS expression should be data expressions
    at com.apigee.expressions.parser.ExpressionParser.buildExpressionTree(ExpressionParser.java:337) ~[expressions-1.0.0.jar:na]
    at com.apigee.expressions.parser.ExpressionParser.parse(ExpressionParser.java:24) ~[expressions-1.0.0.jar:na]
    at com.apigee.expressions.parser.ExpressionParser.parseLogicExpression(ExpressionParser.java:28) ~[expressions-1.0.0.jar:na]
    at com.apigee.messaging.runtime.Step.getExpression(Step.java:67) ~[message-processor-1.0.0.jar:na]
    at com.apigee.messaging.runtime.Step.handleAdd(Step.java:58) ~[message-processor-1.0.0.jar:na]
    at com.apigee.messaging.runtime.SharedFlowRuntime.addStep(SharedFlowRuntime.java:81) ~[message-processor-1.0.0.jar:na] … <snipped>

  4. ParseException 中的错误消息“Both the operands for EQUALS expression should be data expressions”表示涉及等于 (=)、不等于 (!=) 或带有 (=|) 运算符的统计信息的条件存在问题。

  5. 查看涉及错误消息中提及的特定运算符的所有条件流中的条件，看看是否存在以下任何问题：

    1. 运算符两侧的表达式具有相同的类型。例如，如果运算符左侧是字符串变量，则右侧也需要是字符串变量或字符串值。
    2. 运算符之间使用了有效的变量。
    3. 运算符与每个表达式之间都有一个空格。

  6. 如果不满足上述任何条件，您将收到 ParseException -“Both the operands for EQUALS expression should be data expressions”。

  7. 我们来看一个示例，以便更好地理解这个问题。以下是一个示例错误条件，

    <Condition>
           (fault.name = "invalid_access_token") or(fault.name = "ApiKeyNotApproved")
</Condition>

  8. 在此示例中，您会发现“or”运算符与下一个条件之间没有空格。因此，在解析第二个条件时，第一个表达式会被视为 EQUALS 运算符的 "or(fault.name"。这不是有效的变量名称，因此不会被视为有效的数据表达式。因此，您会收到以下异常：

    com.apigee.expressions.parser.ParseException: Both the operands for EQUALS expression should be data expressions

分辨率

  1. 确保运算符两侧始终有适当的数据表达式。

  2. 在上述示例中，解决方案是确保“or”运算符后有空格，如代码段中所述：

    <Condition>
           (fault.name = "invalid_access_token") or (fault.name = "ApiKeyNotApproved")
</Condition>

MessageLogging 政策中的主机名无效

诊断

  1. 在消息处理器日志中，如果您在部署 API 代理或共享流期间看到任何包含“Invalid HostName”消息的异常（如下所示），请继续执行第 2 步。如果不是，请前往下一个原因：KeyValueMap 名称无效。

    com.apigee.rest.framework.ValidationException: Invalid syslog config: Invalid HostName 'splunkprod.myorg.com/' for Syslog handler

  2. 下面我们来看两个示例，了解如何排查和解决此问题。

示例 1：主机名包含不需要的特殊字符

  1. 在部署 API 代理期间，消息处理器显示以下异常：

      2018-01-20 02:12:13,535 Apigee-Main-3 ERROR MESSAGING.CONFIGURATION - MessageProcessorServiceImpl.configure() : error configuring config events [DeployEvent{organization='myorg', application='providersearch', applicationRevision='4', deploymentSpec=basepath=/;env=prod;, deploymentID=null}] 
  com.apigee.rest.framework.ValidationException: Invalid syslog config: Invalid HostName 'splunkprod.myorg.com/' for Syslog handler 
  at com.apigee.messaging.runtime.destinations.SyslogDestination.<init>(SyslogDestination.java:44) ~[message-processor-1.0.0.jar:na] 
  at com.apigee.messaging.runtime.destinations.SysLoggerFactory.getInstance(SysLoggerFactory.java:39) ~[message-processor-1.0.0.jar:na]
  at com.apigee.messaging.runtime.destinations.DestinationRegistry.newDestination(DestinationRegistry.java:44) ~[message-processor-1.0.0.jar:na] 
  ...<snipped>

  2. 上述异常表明，部署失败的原因是 Syslog 处理程序的“主机名 <hostname> 无效”。这表示 MessageLogging 政策中使用的 HostName 是无效的主机名。

  3. 仔细检查消息处理器日志中的异常，发现 HostName 'splunkprod.myorg.com/'. 的末尾有一个不需要的特殊字符“/”

  4. 此多余的特殊字符是导致部署错误的原因。

分辨率

  1. 修改 MessageLogging 政策以移除任何不需要的特殊字符，从而解决此问题。
  2. 在上面的示例中，已从 MessageLogging 政策中移除特殊字符“/”。此问题已解决。

示例 2：无法解析的主机名

  1. 消息处理器日志中有几行显示了 API 代理的部署事件被触发，随后在 API 代理的部署过程中发生异常：

    2017-12-22 00:13:49,057 Apigee-Main-87446 INFO MESSAGING.CONFIGURATION - MessageProcessorServiceImpl.configure() : configuring [DeployEvent{organization='myorg', application='myapi', applicationRevision='42', deploymentSpec=basepath=/;env=dev;, deploymentID=null}] 

2017-12-22 00:13:49,318 Apigee-Main-87446 ERROR c.a.p.h.d.DNSCachedAddress - DNSCachedAddress.refresh() : Unable to resolve host : input-prd.cloud.splunk.com: Name or service not known 

2017-12-22 00:13:49,323 Apigee-Main-87446 ERROR MESSAGING.RUNTIME - AbstractConfigurator.handleUpdate() : Fatal error deploying proxy: {} 
com.apigee.rest.framework.ValidationException: Invalid syslog config: Invalid HostName 'input-prd.cloud.splunk.com' for Syslog handler 
at com.apigee.messaging.runtime.destinations.SyslogDestination.<init>(SyslogDestination.java:44) ~[message-processor-1.0.0.jar:na] 
at com.apigee.messaging.runtime.destinations.SysLoggerFactory.getInstance(SysLoggerFactory.java:39) ~[message-processor-1.0.0.jar:na] 
at com.apigee.messaging.runtime.destinations.DestinationRegistry.newDestination(DestinationRegistry.java:44) ~[message-processor-1.0.0.jar:na] 
at com.apigee.steps.messagelogging.MessageLoggingStepDefinition.populateDestinations(MessageLoggingStepDefinition.java:118) ~[message-logging-1.0.0.jar:na] 
at com.apigee.steps.messagelogging.MessageLoggingStepDefinition.handleAdd(MessageLoggingStepDefinition.java:99) ~[message-logging-1.0.0.jar:na] 
…
<snipped>

  2. 上述异常表明，部署失败的原因是 “Syslog 处理程序的 HostName '<hostname>' 无效”。

  3. 如果您仔细阅读异常上方的行，就会发现消息处理器无法解析 MessageLogging 政策中提供的主机名 'input-prd.cloud.splunk.com'。

  4. 如需确认这一点，您可以尝试通过 telnet 连接到消息日志记录政策中使用的主机名和端口号。

    1. 检查 API 代理的特定修订版本中的 MessageLogging 政策，并验证所用的主机名和端口号。在上面的示例中，API 代理名称为 myapi，修订版本为 42。

      MessageLogging 政策

        <MessageLogging async="false" continueOnError="false" enabled="true" name="Log-To-Splunk">
      <DisplayName>Log-To-Splunk</DisplayName>
      <Syslog>
          <Message>Message.id = {request.header.id}</Message>
          <Host>input-prd.cloud.splunk.com</Host>
          <Port>2900</Port>
          <Protocol>TCP</Protocol>
          <SSLInfo>
              <Enabled>true</Enabled>
          </SSLInfo>
      </Syslog>
  </MessageLogging>

    2. 使用特定端口通过 Telnet 连接到主机。在此示例中，我们尝试了 telnet，并获得了与消息处理器日志中相同的错误：

      telnet input-prd.cloud.splunk.com 2900 
telnet: input-prd.cloud.splunk.com: Name or service not known 
input-prd.cloud.splunk.com: Host name lookup failure

  5. 这清楚地证明了主机名无法解析。

分辨率

  1. 修改 MessageLogging 政策以使用有效的主机名。

如果问题仍然存在，请前往必须收集的诊断信息。

原因：KeyValueMap 名称无效

诊断

  1. 在消息处理器日志中，如果您在部署 API 代理或共享流期间看到一条消息为 "KeyValueMap name is invalid" 的异常（如下所示），请继续执行第 2 步。如果不是，请前往必须收集的诊断信息。

    com.apigee.rest.framework.ValidationException: Invalid syslog config: Invalid HostName 'splunkprod.myorg.com/' for Syslog handler

  2. 下面我们来看一个示例，了解如何排查和解决此问题。

  3. 消息处理器日志示例，显示了“KeyValueMap name is invalid”消息的异常，导致 API 代理部署期间出现错误

    2018-02-27 14:14:50,318  Apigee-Main-6 ERROR MESSAGING.RUNTIME - AbstractConfigurator.handleUpdate() : Fatal error deploying proxy: {}
com.apigee.keyvaluemap.KeyValueMapApiException: KeyValueMap name  is invalid
        at com.apigee.keyvaluemap.service.legacy.KeyValueMapServiceImpl.validateMapName(KeyValueMapServiceImpl.java:125) ~[keyvaluemap-1.0.0.jar:na]
        at com.apigee.keyvaluemap.service.legacy.KeyValueMapServiceImpl.createOrUpdateKeyValueMap(KeyValueMapServiceImpl.java:185) ~[keyvaluemap-1.0.0.jar:na]
        at com.apigee.steps.keyvaluemapoperations.KeyValueMapOperationsStepDefinition.digest(KeyValueMapOperationsStepDefinition.java:180) ~[keyvaluemap-operations-1.0.0.jar:na]
        at com.apigee.steps.keyvaluemapoperations.KeyValueMapOperationsStepDefinition.handleAdd(KeyValueMapOperationsStepDefinition.java:197) ~[keyvaluemap-operations-1.0.0.jar:na]
        at com.apigee.entities.AbstractConfigurator.handleUpdate(AbstractConfigurator.java:130) [config-entities-1.0.0.jar:na]
        at com.apigee.messaging.runtime.Application.handleUpdate(Application.java:229) [message-processor-1.0.0.jar:na]

2018-02-27 14:14:50,344  Apigee-Main-6 ERROR BOOTSTRAP - RuntimeConfigurationServiceImpl.dispatchToListeners() : RuntimeConfigurationServiceImpl.dispatchToListeners : Error occurred while dispatching the request DeployEvent{organization='myorg', application='CustomerAPI', applicationRevision='1', deploymentSpec=basepath=/;env=test;, deploymentID=null} to com.apigee.application.bootstrap.listeners.MessageProcessorBootstrapListener@5009d06e
com.apigee.keyvaluemap.KeyValueMapApiException: KeyValueMap name  is invalid
        at com.apigee.keyvaluemap.service.legacy.KeyValueMapServiceImpl.validateMapName(KeyValueMapServiceImpl.java:125) ~[keyvaluemap-1.0.0.jar:na]
        at com.apigee.keyvaluemap.service.legacy.KeyValueMapServiceImpl.createOrUpdateKeyValueMap(KeyValueMapServiceImpl.java:185) ~[keyvaluemap-1.0.0.jar:na]
        at com.apigee.steps.keyvaluemapoperations.KeyValueMapOperationsStepDefinition.digest(KeyValueMapOperationsStepDefinition.java:180) ~[keyvaluemap-operations-1.0.0.jar:na]
        at com.apigee.steps.keyvaluemapoperations.KeyValueMapOperationsStepDefinition.handleAdd(KeyValueMapOperationsStepDefinition.java:197) ~[keyvaluemap-operations-1.0.0.jar:na]
        at com.apigee.entities.AbstractConfigurator.handleUpdate(AbstractConfigurator.java:130) ~[config-entities-1.0.0.jar:na]
        at com.apigee.messaging.runtime.Application.handleUpdate(Application.java:229) ~[message-processor-1.0.0.jar:na]

  4. 上述第二个异常表示 API 代理：CustomerAPI，修订版本：1 的部署出错。

  5. 检查堆栈轨迹，您会发现错误是在执行 KeyValuMapOperations 政策时抛出的。

  6. 查看 API 代理软件包，您会发现其中包含一个 KeyValuMapOperations 政策，其代码如下所示：

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Pulling-Keys" mapIdentifier="">
 <DisplayName>Pulling Keys</DisplayName>
 <Properties/>
 <ExclusiveCache>false</ExclusiveCache>

  7. 如上所示，表示 KeyValueMap 名称的 mapIdentifier 具有空字符串。KeyValueMap 名称不能为空字符串。这是导致部署错误的原因。

分辨率

  1. 修改 KeyValueMapOperations 政策，使 KeyValueMap 具有适当的有效名称。

  2. 在上述示例中，我们通过修改 KeyValueMapOperations 使其 KeyValueMap 名称为“MyKeyValueMap”来解决此问题，如下所示：

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Pulling-Keys" mapIdentifier="MyKeyValueMap">
    <DisplayName>Pulling Keys</DisplayName>
    <Properties/>
    <ExclusiveCache>false</ExclusiveCache>

必须收集的诊断信息

如果按照上述说明操作后问题仍然存在，请收集以下诊断信息。请与 Apigee Edge 支持团队联系，并向他们提供收集到的信息。

  1. 命令的输出

    curl -v <management-server-host>:<port #>/v1/runtime/organizations/<org-name>/environments/<env-name>/apis/<apiproxy-name>/revisions/deployments -u <user>

  2. 消息处理器日志

    /opt/apigee/var/log/edge-message-processor/logs/system.log

  3. 有关您已尝试过本 Playbook 中的哪些部分的详细信息，以及有助于我们快速解决此问题的任何其他数据分析。