배포 오류 구성 실패

Apigee Edge 문서입니다.
Go to the Apigee X 문서로 이동합니다. info

증상

Edge UI 또는 Management API를 통한 API 프록시 또는 공유 흐름 버전 배포가 구성 실패 오류와 함께 실패합니다.

오류 메시지

아래와 같이 Edge UI에 오류 메시지가 표시됩니다.

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

다음은 Edge UI에서 관찰된 샘플 오류 메시지의 스크린샷입니다.

가능한 원인

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)를 배포하는 중에 메시지 "JavaCallout 클래스를 인스턴스화하지 못했습니다"와 함께 예외가 메시지 프로세서 로그에 표시되면 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"의 오류 메시지는 equal to (=), not equal to (!=) 또는 Stats with (=|) 연산자가 포함된 조건에 문제가 있음을 나타냅니다.

  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 프록시 또는 공유 흐름을 배포하는 중에 메시지 "호스트 이름이 잘못됨" 과 함께 예외가 메시지 프로세서 로그에 표시되면 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 정책에 사용된 호스트 이름이 잘못된 호스트 이름임을 나타냅니다.

  3. 메시지 프로세서 로그의 예외를 주의 깊게 살펴보면 호스트 이름 '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>'이 잘못됨"으로 인해 배포가 실패함을 보여줍니다.

  3. 예외 위의 줄을 읽어보면 메시지 프로세서가 MessageLogging 정책에 제공된 호스트 이름 'input-prd.cloud.splunk.com'을 확인할 수 없음을 알 수 있습니다.

  4. 이를 확인하려면 Message Logging 정책에 사용된 호스트 이름과 포트 번호에 텔넷을 시도해 보세요.

    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 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 이름이 잘못됨"과 함께 예외가 메시지 프로세서 로그에 표시되면 2단계로 진행합니다. 그렇지 않은 경우 진단 정보를 수집해야 함으로 이동합니다.

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

  2. 이 문제를 해결하는 방법을 이해하려면 다음 예를 살펴보세요.

  3. API 프록시 배포 중에 오류를 일으키는 'KeyValueMap 이름이 잘못됨' 메시지와 함께 예외를 보여주는 메시지 프로세서 로그 예시

    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. 이 플레이북에서 시도한 섹션과 이 문제의 해결을 신속하게 처리하는 데 도움이 될 만한 기타 통찰정보에 관한 세부정보