배포 오류 구성 실패

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보

증상

Edge UI 또는 관리 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 프록시 배포가 실패할 수 있습니다. 아래 표에는 이 오류를 유발하는 몇 가지 자주 관찰된 원인이 나와 있습니다.

원인 설명 해당하는 문제 해결 안내
JavaDocs 정책에 Java 클래스 누락 Java콜아웃 정책에서 참조하는 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. 아래 섹션에서는 배포 오류 '구성 실패'로 이어지는 가장 자주 관찰되는 예외와 문제 해결 단계를 제공합니다.

원인: Java콜아웃 정책에 Java 클래스가 누락됨

진단

  1. 아래와 같이 API 프록시 (DeployEvent) 배포 중 메시지 프로세서 로그에서 'Failed to instantiate the Java callout 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. 위 예외의 오류 메시지는 JavaCall 클래스 com.something.apigee.callout.crypto.main.SecretCallout를 인스턴스화할 수 없음을 나타냅니다. 이 오류는 일반적으로 Java콜아웃 정책에 지정된 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 프록시 또는 공유 흐름을 배포하는 동안 메시지 프로세서 로그에서 '잘못된 HostName' 메시지와 함께 예외가 표시되면 2단계로 진행합니다. 그렇지 않은 경우 다음 원인인 잘못된 KeyValueMap 이름으로 이동합니다. 

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

  2. 이 문제를 해결하는 방법을 이해하기 위해 아래 두 가지 예를 살펴보겠습니다.

예 1: HostName에 원치 않는 특수문자가 있음

  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. 위의 예외는 'Invalid HostName '<hostname>' for Syslog 핸들러'로 인해 배포가 실패했음을 보여줍니다. 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. 위의 예외는 'Invalid HostName '<hostname>' for Syslog 핸들러'로 인해 배포가 실패했음을 보여줍니다.

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

  4. 이를 확인하려면 메시지 로깅 정책에서 사용되는 호스트 이름과 포트 번호로 텔넷에 접속해 보세요.

    1. API 프록시의 특정 버전에서 MessageLogging 정책을 확인하고 사용된 호스트 이름과 포트 번호를 확인합니다. 위 예에서 API 프록시 이름은 myapi, version: 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 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. API 프록시 배포 중에 오류가 발생하는 'KeyValueMap name is invalid' 메시지와 함께 예외를 보여주는 메시지 프로세서 로그 예

    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 Proxy: CustomerAPI, version: 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. KeyValueMap에 적절한 이름을 지정할 수 있도록 KeyValueMapOperations 정책을 수정합니다.

  2. 위의 예에서는 아래와 같이 KeyValueMap 이름을 'MyKeyValueMap'으로 하도록 KeyValueMapOperations를 수정하여 문제를 해결했습니다.

      <?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. 이 플레이북에서 시도해 본 섹션 및 이 문제를 빠르게 해결하는 데 도움이 될 기타 정보에 관한 세부정보