기능 플래그 문제 해결

미리보기

이 제품 또는 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제품 또는 서비스 약관'이 적용됩니다. GA 이전 제품 및 기능은 '현재 상태 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

이 가이드에서는 App Lifecycle Manager 기능 플래그의 일반적인 문제를 진단하고 해결하는 단계를 설명합니다.

SDK 및 런타임 평가

OpenFeature API는 플래그 평가 호출이 처리되지 않은 예외를 발생시키지 않고 평가 오류가 발생하면 기본값을 반환하도록 설계되었습니다.

증상: 플래그가 안전한 기본값을 반환함

플래그 서비스에 연결할 수 없거나, 제공자를 사용할 수 없거나, 플래그가 잘못 구성된 경우 SDK는 코드에 제공된 필수 기본값을 반환합니다.

해결 방법:

1. OpenFeature 제공업체와 saasconfig.googleapis.com 엔드포인트 간의 연결을 확인합니다.
2. 인증 오류를 확인합니다. 애플리케이션의 런타임 서비스 계정에 roles/saasconfig.viewer 역할이 있는지 확인합니다.
3. FLAGD_SOURCE_PROVIDER_ID이 올바른지 확인합니다.

증상: 예상치 못한 평가 결과

플래그가 예상 대안을 반환하지 않는 경우:

해결 방법:

1. CEL 조건 및 평가 컨텍스트를 확인하세요.
2. 조건 확인 중에 컨텍스트에서 필수 속성이 누락되면 평가 엔진은 해당 규칙을 건너뜁니다.
3. 비율 기반 할당 중에 속성이 누락되면 평가에서 INVALID_CONTEXT를 반환합니다.

앱 중심 템플릿 동기화 및 콘솔 출시 문제 해결

Application Design Center 복합 템플릿과 Google Cloud 콘솔을 사용하여 기능 플래그를 온보딩하는 경우 다음 단계를 사용하여 템플릿 동기화 및 출시 문제를 해결하세요.

증상: App Design Center 복합 템플릿을 연결한 후 단위 종류가 생성되지 않음

복합 템플릿을 연결한 후에도 SaaS 제품의 단위 종류 탭이 비어 있는 경우 다음을 수행합니다.

해결 방법:

1. 복합 템플릿을 SaaS 제품으로 가져오기 전에 각 삽입된 표준 애플리케이션 템플릿과 상위 복합 애플리케이션 템플릿이 Application Design Center의 카탈로그에 추가되었는지 확인합니다.
2. App Lifecycle Manager 서비스 에이전트(service-PROJECT_NUMBER@gcp-sa-saasservicemgmt.)에 프로젝트의 roles/saasservicemgmt.serviceAgent 역할이 있는지 확인합니다.
3. Google Cloud 콘솔에서 SaaS 제품 세부정보 페이지를 확인하거나 gcloud beta app-lifecycle-manager saas describe SAAS_OFFERING_ID --location=global를 실행하여 템플릿 동기화 상태를 검사하세요.

다음을 바꿉니다.

• PROJECT_NUMBER: Google Cloud 프로젝트 번호입니다.
• SAAS_OFFERING_ID: SaaS 솔루션의 ID입니다.

증상: 콘솔의 플래그 출시가 표준 템플릿에서 생성된 단위를 업데이트하지 않음

Google Cloud 콘솔에서 플래그 출시가 완료되었지만 표준 템플릿에서 생성된 단위가 업데이트된 플래그 구성을 수신하지 않는 경우:

해결 방법:

1. 단위가 타겟팅된 단위 종류에 속하고, 출시에 포함된 리전에 있으며, 출시 종류에 구성된 unitFilter와 일치하는지 확인합니다.
2. 애플리케이션의 FLAGD_SOURCE_PROVIDER_ID가 단위의 전체 기능 플래그 구성 리소스 경로(projects/PROJECT_ID/locations/LOCATION/featureFlagsConfigs/UNIT_ID)와 일치하는지 확인합니다.

다음을 바꿉니다.

• PROJECT_ID: Google Cloud 프로젝트 ID입니다.
• LOCATION: 단위의 리전입니다.
• UNIT_ID: 단위의 ID입니다.

출시 모니터링

기능 플래그 출시를 모니터링하려면 조정 상태(출시가 완료되었는지 여부)와 애플리케이션 상태(바이너리가 플래그를 선택했는지 여부)를 모두 확인해야 합니다.

출시 조정 상태

시스템은 작업의 성공률을 실시간으로 모니터링합니다.

자동 일시중지

잘못된 구성이 전체 Fleet에 적용되지 않도록, 위치의 실패율이 출시 유형에 구성된 오류 예산(errorBudget.allowedCount 또는 errorBudget.allowedPercentage, 예를 들어 위치당 기준점 10%)을 초과하면 시스템에서 출시를 자동으로 일시중지합니다.

요약 통계 확인

describe 명령어를 사용하여 집계된 실패 횟수를 확인하고 출시가 PAUSED인지 FAILED인지 확인합니다.

gcloud beta app-lifecycle-manager rollouts describe ROLLOUT_ID --location=global

실패한 단위 업데이트 필터링

실패가 있는지 확인한 후 업데이트를 놓친 특정 단위를 찾아야 합니다. 이 필터를 사용하여 특정 리전에서 실패한 플래그 업데이트만 격리합니다.

gcloud beta app-lifecycle-manager unit-operations list \
    --location=LOCATION \
    --filter="state:UNIT_OPERATION_STATE_FAILED AND flag_update:*"

근본 원인 진단

실패한 각 작업에 대해 conditions 필드(message 및 reason)와 errorCategory에서 작동 엔진이 제공하는 자세한 오류 메시지를 검색하거나 출시 리소스에서 stateMessage를 검사할 수 있습니다.

gcloud beta app-lifecycle-manager unit-operations describe OPERATION_ID --location=LOCATION

다음을 바꿉니다.

• ROLLOUT_ID: 출시 ID입니다.
• LOCATION: 단위 작업의 리전입니다.
• OPERATION_ID: 단위 작업의 ID입니다.

단위 구성 누락

이 섹션에서는 단위 고정으로 인해 단위가 기능 플래그 구성을 수신하지 못하는 경우와 단위를 복구하는 방법을 설명합니다.

단위 고정 이해하기

고정하면 단위가 현재 출시 버전으로 고정되어 자동 또는 수동 출시로 업데이트되지 않습니다. 고정된 단위는 고정 기간이 만료되거나 수동으로 고정이 해제될 때까지 출시 작업에서 명시적으로 제외됩니다.

고정된 단위의 구성이 누락됨

기능 플래그 출시 중에 단위가 고정되면 심각한 시나리오가 발생합니다. 고정하면 모든 업데이트가 차단되므로 기기가 구성을 수신하는 데 필요한 FlagUpdate 작업을 건너뜁니다.

증상: 단위가 고정 해제되고 기능 플래그가 필요한 바이너리로 업그레이드되면 애플리케이션이 초기화되지 않거나 무한 재시도 루프에 들어가 준비 프로브가 실패하고 컨테이너가 계속 다시 시작됩니다.

근본 원인: 단위가 고정된 동안 출시에서 상위 단위 종류 리소스의 defaultFlagRevisions 필드를 업데이트했지만 고정된 단위가 FlagUpdate 작업을 건너뛰고 활성 구성을 수신하지 못했습니다.

진단 명령어

다음 명령어를 사용하여 실패한 플래그 업데이트 작업과 단위 상태를 검사합니다.

1. 실패한 플래그 작업 나열

업데이트를 놓친 단위를 찾으려면 UNIT_OPERATION_STATE_FAILED 상태 및 flag_update 유형에 대한 단위 작업을 필터링합니다.

gcloud beta app-lifecycle-manager unit-operations list \
    --location="LOCATION" \
    --filter="state:UNIT_OPERATION_STATE_FAILED AND flag_update:*"

2. 실패한 플래그 출시를 구체적으로 필터링

전체 Fleet 또는 특정 단위에서 실패한 플래그 업데이트를 정확히 파악하려면 UNIT_OPERATION_STATE_FAILED 상태에 대한 조건을 추가하세요.

gcloud beta app-lifecycle-manager unit-operations list \
    --location="LOCATION" \
    --filter="unit:UNIT_ID AND state:UNIT_OPERATION_STATE_FAILED AND flag_update:*"

3. 실패 원인 검사

describe 명령어를 사용하여 conditions 필드(message 및 reason)와 errorCategory를 검사합니다.

gcloud beta app-lifecycle-manager unit-operations describe "OPERATION_ID" --location="LOCATION"

4. 기기 상태 확인

단위의 현재 상태를 직접 확인할 수도 있습니다. 플래그 출시가 실패하거나 마지막 작업으로 인해 오류가 발생하면 단위의 conditions 목록에 type: TYPE_OPERATION_ERROR가 포함된 항목이 있습니다.

gcloud beta app-lifecycle-manager units describe "UNIT_ID" --location="LOCATION"

다음을 바꿉니다.

• LOCATION: 단위 또는 단위 작업의 리전입니다.
• UNIT_ID: 단위의 ID입니다.
• OPERATION_ID: 단위 작업의 ID입니다.

수동 완화

플래그 업데이트를 놓친 고정된 단위를 복구하려면 상위 단위 종류의 기본 플래그 버전을 적용하세요.

단위 종류 기본 플래그 버전 적용

하나 이상의 출시 중에 고정되어 구성이 누락된 단위가 있는 경우, 해당 단위 종류에 정의된 현재 기준값으로 단위를 수동으로 재설정하여 복구할 수 있습니다.

1. 단원 고정 해제(고정된 경우):

   gcloud beta app-lifecycle-manager units update "UNIT_ID" \
       --location="LOCATION" \
       --maintenance-pinned-until-time=""
   

2. 상위 단위 종류에서 기본 버전 가져오기:

   gcloud beta app-lifecycle-manager unit-kinds describe "UNIT_KIND_ID" \
       --location="LOCATION" \
       --format="value(defaultFlagRevisions.join(','))"
   

3. 해당 버전이 포함된 새 FlagRelease를 만듭니다.

   gcloud beta app-lifecycle-manager flags releases create "recovery-release-1" \
       --location="LOCATION" \
       --unit-kind="UNIT_KIND_ID" \
       --revisions="REVISIONS"
   

4. FlagUpdate 단위 작업을 수동으로 시작하여 복구 버전을 적용합니다.

   gcloud beta app-lifecycle-manager unit-operations create "recovery-op" \
       --unit="UNIT_ID" \
       --flag-update="projects/PROJECT_ID/locations/LOCATION/flagReleases/recovery-release-1" \
       --location="LOCATION"
   

다음을 바꿉니다.

• UNIT_ID: 복구할 단위의 ID입니다.
• LOCATION: 단위의 리전입니다.
• UNIT_KIND_ID: 상위 단위 종류의 ID입니다.
• REVISIONS: 2단계에서 반환된 쉼표로 구분된 기본 플래그 버전 리소스 이름 목록입니다.
• PROJECT_ID: Google Cloud 프로젝트 ID입니다.