Fleet 로그 보기

이 페이지에서는 Fleet의 로그를 사용 설정하고 열람하는 방법에 대해 설명합니다. Fleet 로깅을 사용하면 여러 로그가 집계되고 범위가 지정되므로 하나의 통합 뷰에서 애플리케이션 상태를 분석할 수 있습니다. 이 페이지는 다음과 같은 사용자를 대상으로 작성되었습니다.

모든 네임스페이스에서 Fleet 로깅을 사용 설정하고 로그를 보려는 플랫폼 관리자.
액세스 권한이 있는 특정 네임스페이스의 로그를 보려는 서비스 운영자.

개요

Fleet 로그를 사용하면 전체 Fleet 수준 또는 특정 팀 범위에 대한 로그를 볼 수 있습니다. 범위는 팀별로 Fleet 로그 및 기타 리소스의 하위 집합을 정의할 수 있게 해주는 팀 관리 기능으로, 각 범위는 하나 이상의 Fleet 구성원 클러스터와 연결되어 있습니다. 범위에 대한 자세한 내용은 Fleet 팀 관리를 참조하세요.

다음 두 가지 유형의 Fleet 로그를 볼 수 있습니다.

기본 로그: 다음 리소스 유형의 특정 Fleet 범위에 속하지 않는 모든 Kubernetes 로그(감사 로그 제외)
- k8s_container
- k8s_pod
- k8s_node
- k8s_cluster
- k8s_control_plane_components
Fleet 범위 로그: 여러 Fleet 수준 네임스페이스가 있는 특정 Fleet 범위에 배포된 팀에서 소유한 애플리케이션의 컨테이너 및 포드 로그

Fleet 범위 로그 보기는 선택사항입니다. 팀 관리를 설정하지 않으려면 Fleet 로깅을 사용하여 기본 로그를 볼 수 있습니다.

로그는 액세스 제어를 위해 서로 다른 뷰를 사용하여 Fleet 호스트 프로젝트의 다양한 로그 버킷으로 라우팅될 수 있습니다. 로그 버킷의 기본 보관 기간은 30일입니다. 필요한 경우 이 기간을 구성할 수 있습니다.

Fleet에 여러 프로젝트(프로젝트 간 등록)의 클러스터가 포함된 로그 라우팅에는 두 가지 모드가 지원됩니다.

MOVE: 모든 로그는 Fleet 호스트 프로젝트로 이동합니다. Fleet의 클러스터가 다른 프로젝트에 속하면 로그가 원래 Google Cloud 프로젝트에 보관되지 않습니다.
COPY: 모든 로그가 Fleet 호스트 프로젝트로 전송됩니다. Fleet의 클러스터가 다른 프로젝트에 속하는 경우 해당 로그는 원래 Google Cloud 프로젝트에도 보관됩니다.

시작하기 전에

이미 Cloud Logging 버킷, 싱크, 제외 필터 설정을 수동으로 만든 경우, 해당 객체에 지정한 이름이 Fleet 로깅 이름 지정 제한사항과 충돌하지 않도록 유의하세요. 이름 충돌이 있는 경우 계속하기 전에 지원팀에 문의하세요.
로그를 보려는 클러스터가 선택한 Fleet에 등록되었는지 확인하세요.
Google Cloud CLI를 아직 설치하지 않았으면 설치 안내에 따라 설치합니다. Fleet 로그를 보려면 버전 424.0.0 이상이 필요합니다.
Fleet 호스트 프로젝트에 Anthos API를 포함하여 모든 필수 API가 사용 설정되었는지 확인합니다.
```
gcloud services enable --project=FLEET_HOST_PROJECT_ID  \
gkehub.googleapis.com \
container.googleapis.com \
connectgateway.googleapis.com \
cloudresourcemanager.googleapis.com \
iam.googleapis.com \
anthos.googleapis.com
```
각 항목의 의미는 다음과 같습니다.
- FLEET_HOST_PROJECT_ID: Fleet 호스트 프로젝트의 프로젝트 ID 이 값을 찾는 방법에 대해 알아보세요.

범위, 네임스페이스 및 워크로드 준비

Fleet 범위 로그를 보려면 로그 수집을 위해 워크로드를 준비하는 것 외에도 Fleet 범위와 Fleet 네임스페이스를 만들어야 합니다.

계속하기 전에 다음 명령어를 실행하여 Google Cloud CLI의 기본 프로젝트를 설정하세요.

gcloud config set project FLEET_HOST_PROJECT_ID

범위 및 네임스페이스 만들기

아직 범위를 설정하지 않고 범위 수준에서 로그를 보려는 경우 Fleet 팀 관리의 안내에 따라 범위를 만들고 범위에 클러스터를 추가하고 Fleet 네임스페이스를 설정합니다.

워크로드 준비

애플리케이션에서 로그 데이터를 보려면 클러스터의 워크로드를 이전 단계에서 구성한 Fleet 네임스페이스에 배포해야 합니다. 이 단계는 기본 로그, Fleet 범위 로그 또는 둘 다를 표시할지 여부에 관계없이 적용됩니다. 다음은 워크로드를 구성하는 예시입니다.

  apiVersion: v1
  kind: Pod
  metadata:
    name: fleet-example-pod
    namespace: NAMESPACE_NAME
  spec:
    containers:
    - name: count
      image: ubuntu:14.04
      args: [bash, -c,
           'for ((i = 0; ; i++)); do echo "$i: $(date)"; sleep 1; done']

리소스를 배포한 후 Fleet 네임스페이스가 어떤 이유로 생성되지 못한 경우 오류가 표시될 수 있습니다. 이 경우 다음 명령어를 실행하여 네임스페이스를 다시 생성하고 워크로드 배포 명령어를 다시 실행합니다.

  kubectl create namespace NAMESPACE_NAME

Fleet 로깅 사용 설정

이 섹션에서는 Fleet 로깅 기능을 사용 설정하고 팀에 로그를 볼 수 있는 액세스 권한을 부여하는 방법을 설명합니다.

gcloud

JSON 또는 YAML 파일에서 기능에 대한 구성 필드를 지정하여 Google Cloud CLI를 사용하여 Fleet 로깅을 사용 설정할 수 있습니다. 다음은 JSON 형식의 Fleet 로깅에 대한 구성 예시입니다.
```
{
  "loggingConfig": {
      "defaultConfig": {
          "mode": "COPY"
      },
      "fleetScopeLogsConfig": {
          "mode": "MOVE"
      }
  }
}
```

이 기능에 구성할 수 있는 모든 필드를 보려면 API 참조를 확인하세요.

이전 예시에 표시된 것처럼 defaultConfig 또는 fleetScopeLogsConfig 필드가 COPY 또는 MOVE 모드로 사용 설정된 경우 로그 싱크가 fleet-o11y- 프리픽스로 생성됩니다. 이 로그 싱크는 클러스터 프로젝트의 대상 로그를 Fleet 호스트 프로젝트에 라우팅하도록 Google Cloud 프로젝트 아래에 생성됩니다.

fleetScopeLogsConfig가 사용 설정되면 이름이 fleet-o11y-scope-$SCOPE_NAME인 로그 버킷이 Fleet 호스트 프로젝트 아래의 global 리전에도 생성됩니다(아직 없는 경우). 버킷 리전은 변경할 수 없습니다.

이 예시에서 기본 로그는 Fleet 호스트 프로젝트에 전송되고 원래 Google Cloud 프로젝트에 보관되며 Fleet 범위 로그는 Fleet 호스트 프로젝트에 전송되고 Google Cloud 프로젝트에 보관되지 않습니다.

선택한 구성을 JSON 파일에 추가하고 Fleet을 업데이트하세요.

gcloud container fleet fleetobservability update \
        --logging-config=JSON_FILE

JSON_FILE을 파일 이름으로 바꿉니다.

Terraform

Fleet 관측 가능성 기능은 기본적으로 사용 설정됩니다. Terraform을 사용해서 Fleet 관측 가능성 기능을 관리하는 것이 처음인 경우에는 다음 명령어를 실행하여 Terraform으로 기능을 가져옵니다.

terraform import google_gke_hub_feature.feature projects/FLEET_HOST_PROJECT_ID/locations/global/features/fleetobservability

Terraform 모듈을 사용해서 Terraform으로 Fleet 로깅을 사용 설정할 수 있습니다.

예를 들어 Terraform 구성에 다음 블록을 추가할 수 있습니다.

  resource "google_gke_hub_feature" "feature" {
    name = "fleetobservability"
    location = "global"
    spec {
      fleetobservability {
        logging_config {
          default_config {
            mode = "COPY"
          }
          fleet_scope_logs_config {
            mode = "MOVE"
          }
        }
      }
    }
  }

이전 예시에 표시된 것처럼 default_config 또는 fleet_scope_logs_config 필드가 COPY 또는 MOVE 모드로 사용 설정된 경우 로그 싱크가 fleet-o11y- 프리픽스로 생성됩니다. 이 로그 싱크는 클러스터 프로젝트의 대상 로그를 Fleet 호스트 프로젝트에 라우팅하도록 Google Cloud 프로젝트 아래에 생성됩니다.

fleet_scope_logs_config가 사용 설정되면 fleet-o11y-scope-$SCOPE_NAME이라는 로그 버킷이 (아직 없는 경우) Fleet 호스트 프로젝트 아래에 생성됩니다.

기능 사양이 업데이트되었는지 확인합니다.

   gcloud container fleet fleetobservability describe

출력에는 다음 예시와 같이 구성으로 업데이트된 fleetobservability 사양이 표시됩니다.

createTime: '2022-09-30T16:05:02.222568564Z'
membershipStates:
  projects/123456/locations/us-central1/memberships/cluster-1:
    state:
      code: OK
      description: Fleet monitoring enabled.
      updateTime: '2023-04-03T20:22:51.436047872Z'
name:
projects/123456/locations/global/features/fleetobservability
resourceState:
  state: ACTIVE
spec:
  fleetobservability:
    loggingConfig:
      defaultConfig:
        mode: COPY
      fleetScopeLogsConfig:
        mode: MOVE
state:
  state: {}
updateTime: '2023-04-03T20:38:17.719596966Z'

fleetobservability 사양의 변경사항이 적용되는 데 몇 분 정도 걸릴 수 있습니다.

프로젝트 간 로깅 권한 설정

이 섹션은 다른 프로젝트의 Fleet에 클러스터를 등록하는 경우에만 필요합니다(교차 프로젝트 등록이라고도 함). 클러스터 프로젝트에서 Fleet 호스트 프로젝트로 로그를 라우팅하려면 각 클러스터 프로젝트의 로깅 서비스 계정에 roles/logging.bucketWriter 역할을 부여해야 합니다.

클러스터 프로젝트의 싱크에서 서비스 계정 사용자 인증 정보를 가져오려면 다음 명령어를 실행합니다.

FLEET_HOST_PROJECT_ID=FLEET_HOST_PROJECT_ID
FLEET_HOST_PROJECT_NUMBER=$(gcloud projects describe "${FLEET_HOST_PROJECT_ID}" --format "value(projectNumber)")
gcloud logging sinks --project=GKE_PROJECT_ID describe fleet-o11y-${FLEET_HOST_PROJECT_NUMBER}-default

명령어가 로그 싱크를 찾을 수 없다는 오류를 반환하면 1~2분 후에 명령어를 다시 실행해 봅니다. 다음 예시와 같이 싱크 설명의 writerIdentity 필드에서 서비스 계정을 볼 수 있습니다.

createTime: '2023-04-06T02:26:54.716195307Z'
destination:
logging.googleapis.com/projects/123456/locations/global/buckets/_Default
filter: xxx
name: fleet-o11y-default
updateTime: '2023-04-06T19:03:51.598668462Z'
writerIdentity:
serviceAccount:service-123456@gcp-sa-logging.iam.gserviceaccount.com

검색된 서비스 계정에 roles/logging.bucketWriter 역할을 부여합니다.

gcloud projects add-iam-policy-binding FLEET_HOST_PROJECT_ID \
    --member "SERVICE_ACCOUNT" \
    --role "roles/logging.bucketWriter"

각 항목의 의미는 다음과 같습니다.

SERVICE_ACCOUNT는 이전 단계에서 가져온 서비스 계정의 이름입니다. 예를 들면 다음과 같습니다.

gcloud projects add-iam-policy-binding FLEET_HOST_PROJECT_ID \
    --member "serviceAccount:service-123456@gcp-sa-logging.iam.gserviceaccount.com" \
    --role "roles/logging.bucketWriter"

로그에 대한 액세스 권한을 팀에 부여

이 섹션에서는 사용자에게 컨테이너 로그 및 포드 로그를 볼 수 있는 액세스 권한을 부여하는 방법을 설명합니다.

Fleet 프로젝트의 IAM 정책을 가져 와 JSON 형식으로 로컬 파일에 씁니다.
```
gcloud projects get-iam-policy FLEET_HOST_PROJECT_ID --format json > output.json
```

사용자 계정에서 생성된 로그 버킷의 데이터를 볼 수 있도록 IAM 조건을 추가합니다. 다음은 컨테이너 로그 및 포드 로그를 보는 예시입니다.

{
  "bindings": [
    {
      "members": [
        "user:USER_ACCOUNT_EMAIL"
      ],
      "role": "roles/logging.viewAccessor",
      "condition": {
          "title": "Bucket reader condition example",
          "description": "Grants logging.viewAccessor role to user USER_ACCOUNT_EMAIL for the fleet-o11y-scope-SCOPE_NAME-k8s_container and fleet-o11y-scope-SCOPE_NAME-k8s_pod log view.",
          "expression":
            "resource.name == \"projects/FLEET_HOST_PROJECT_ID/locations/global/buckets/fleet-o11y-scope-SCOPE_NAME/views/fleet-o11y-scope-SCOPE_NAME-k8s_container\" || resource.name == \"projects/FLEET_HOST_PROJECT_ID/locations/global/buckets/fleet-o11y-scope-SCOPE_NAME/views/fleet-o11y-scope-SCOPE_NAME-k8s_pod\""
      }
    }
  ],
}

IAM 정책을 업데이트합니다.

gcloud projects set-iam-policy FLEET_HOST_PROJECT_ID output.json

액세스 권한 부여에 대한 추가 옵션은 로그 뷰에 액세스 권한 부여를 참조하세요.

Fleet 로그 보기

플랫폼 관리자는 모든 네임스페이스의 모든 로그를 볼 수 있는 액세스 권한이 있습니다.

기본 로그

Fleet 호스트 프로젝트에서 _Default 버킷의 모든 기본 로그를 보려면 다음 URL에서 변수를 입력하고 이를 브라우저에 복사하여 붙여넣습니다.

https://console.cloud.google.com/logs/query;query=;storageScope=storage,projects%2FFLEET_HOST_PROJECT_ID%2Flocations%2Fglobal%2Fbuckets%2F_Default%2Fviews%2F_Default?jsmode=O&mods=pan_ng2&project=FLEET_HOST_PROJECT_ID

Fleet 범위 컨테이너 로그 및 포드 로그

서비스 운영자는 자신이 액세스할 수 있는 네임스페이스에서 로그를 볼 수 있습니다. 특정 Fleet 범위에서 모든 네임스페이스의 로그를 보려면 다음 단계를 완료합니다.

Fleet 호스트 프로젝트가 선택된 상태에서 Google Cloud 콘솔의 팀 섹션으로 이동합니다.

팀으로 이동
로그를 보려는 팀 범위를 클릭하고 로그 탭을 클릭합니다.
컨테이너 로그 또는 포드 로그를 선택하여 로그 보기를 필터링합니다.

범위 내 특정 네임스페이스의 로그를 보려면 다음 안내를 따르세요.

팀 페이지에서 팀 범위를 선택한 상태로 네임스페이스 탭을 클릭합니다.
로그를 보려는 네임스페이스를 클릭하고 로그 탭을 클릭합니다.
컨테이너 로그 또는 포드 로그를 선택하여 로그 보기를 필터링합니다.

또는 컨테이너 로그를 보려면 다음 URL에서 변수를 입력하고 이를 브라우저에 복사하여 붙여넣습니다.

https://console.cloud.google.com/logs/query;query=;storageScope=storage,projects%2FFLEET_HOST_PROJECT_ID%2Flocations%2Fglobal%2Fbuckets%2Ffleet-o11y-scope-SCOPE_NAME%2Fviews%2Ffleet-o11y-scope-SCOPE_NAME-k8s_container?jsmode=O&mods=pan_ng2&project=FLEET_HOST_PROJECT_ID

특정 Fleet 범위에서 포드 로그를 보려면 다음 URL에서 변수를 작성하고 이를 브라우저에 복사하여 붙여넣습니다.

https://console.cloud.google.com/logs/query;query=;storageScope=storage,projects%2FFLEET_HOST_PROJECT_ID%2Flocations%2Fglobal%2Fbuckets%2Ffleet-o11y-scope-SCOPE_NAME%2Fviews%2Ffleet-o11y-scope-SCOPE_NAME-k8s_pod?jsmode=O&mods=pan_ng2&project=FLEET_HOST_PROJECT_ID

로그 데이터를 분석하는 방법에 대한 자세한 내용은 로그 탐색기 인터페이스를 참조하세요.

Fleet 로깅 사용 중지

Fleet 로깅 기능을 사용 중지하려면 다음 단계를 완료합니다.

gcloud

다음 구성을 disable_logging_config.json이라는 파일에 저장합니다.
```
{
  "loggingConfig": {}
}
```

fleetobservability 기능 사양을 업데이트합니다.

gcloud container fleet fleetobservability update \
        --logging-config=disable_logging_config.json

Terraform

Terraform 구성에서 로그 라우팅의 모든 모드를 MODE_UNSPECIFIED로 업데이트합니다. 예를 들면 다음과 같습니다.

  resource "google_gke_hub_feature" "feature" {
    name = "fleetobservability"
    location = "global"
    spec {
      fleetobservability {
        logging_config {
          default_config {
            mode = "MODE_UNSPECIFIED"
          }
          fleet_scope_logs_config {
            mode = "MODE_UNSPECIFIED"
          }
        }
      }
    }
  }

기능 사양이 업데이트되었는지 확인합니다.

   gcloud container fleet fleetobservability describe

출력에는 구성으로 업데이트된 fleetobservability 사양이 표시됩니다.

  createTime: '2022-09-30T16:05:02.222568564Z'
  membershipStates:
    projects/123456/locations/global/memberships/cluster-1:
      state:
        code: OK
        description: Fleet monitoring enabled.
        updateTime: '2023-04-03T20:22:51.436047872Z'
  name:
  projects/123456/locations/global/features/fleetobservability
  resourceState:
    state: ACTIVE
  spec:
    fleetobservability:
      loggingConfig: {}
  state:
    state: {}
  updateTime: '2023-04-03T20:38:17.719596966Z'

fleetobservability 사양의 변경사항이 적용되는 데 몇 분 정도 걸릴 수 있습니다.

Fleet 로깅을 사용 중지하면 프로젝트에서 로그 싱크 및 제외 필터가 삭제됩니다. 하지만 범위에 대해 생성된 모든 로그 버킷과 로그 버킷 아래 생성된 로그 뷰는 보존됩니다. Fleet 호스트 프로젝트에서 로그 버킷을 삭제하려면 버킷 삭제를 참조하세요.

로그 버킷의 보관 기간 업데이트

로그 버킷의 기본 보관 기간은 30일입니다. 이 기간을 업데이트하려면 다음 명령어를 실행하세요.

gcloud logging buckets update fleet-o11y-scope-SCOPE_NAME --location=global --retention-days=RETENTION_DAYS

각 항목의 의미는 다음과 같습니다.

SCOPE_NAME: Fleet 범위의 이름
RETENTION_DAYS: 새 보관 기간의 일 수 로그 버킷 구성에 대한 추가 옵션은 버킷 관리를 참조하세요.

버킷의 보관 기간을 연장하면 보관 규칙이 소급 적용되지 않고 향후에만 적용됩니다. 적용 가능한 보관 기간이 종료된 후에는 로그를 복구할 수 없습니다.

API 참조

이 섹션에서는 fleetobservability 객체에 추가할 수 있는 필드에 대한 정보를 제공합니다.

fleetobservability

fleetobservability는 Fleet 관측 가능성 구성을 정의합니다.

필드	설명	스키마	선택사항
loggingConfig	전체 Fleet에 Fleet 로깅 기능이 사용 설정된 경우 지정됩니다. 지정하지 않으면 전체 Fleet에 대해 Fleet 로깅 기능이 사용 중지됩니다.	loggingConfig	예

필드

설명

스키마

선택사항

loggingConfig

전체 Fleet에 Fleet 로깅 기능이 사용 설정된 경우 지정됩니다.

지정하지 않으면 전체 Fleet에 대해 Fleet 로깅 기능이 사용 중지됩니다.

loggingConfig

예

loggingConfig

loggingConfig는 Fleet 관측 가능성에서 Fleet 로깅 기능의 구성을 정의합니다.

필드	설명	스키마	선택사항
defaultConfig	Fleet의 기본 로그에 대한 로그 라우팅 동작을 설정합니다.	routingConfig	예
fleetScopeLogsConfig	Fleet 범위 로그에 대한 로그 라우팅 동작을 설정합니다.	routingConfig	예

routingConfig

routingConfig는 Fleet 로깅 기능에서 로그 라우팅 모드의 구성을 정의합니다.

필드	설명	스키마	선택사항
mode	로그 라우팅을 사용하도록 지정. 로그 라우팅을 사용 중지하려면 지정하지 않거나 MODE_UNSPECIFIED를 지정 COPY로 설정하면 로그가 대상 프로젝트에 복사됩니다. MOVE로 설정하면 로그가 대상 프로젝트로 이동합니다.	문자열; MOVE, COPY, MODE_UNSPECIFIED 중 하나	예

필드

설명

스키마

선택사항

mode

로그 라우팅을 사용하도록 지정. 로그 라우팅을 사용 중지하려면 지정하지 않거나 MODE_UNSPECIFIED를 지정

COPY로 설정하면 로그가 대상 프로젝트에 복사됩니다.

MOVE로 설정하면 로그가 대상 프로젝트로 이동합니다.

문자열; MOVE, COPY, MODE_UNSPECIFIED 중 하나

예

이름 지정 제한사항

Fleet 관측 가능성이 사용 설정되었으면 Fleet 관측 가능성 컨트롤러가 생성하는 로그 객체에 대해 다음 이름을 예약합니다. 원치 않는 동작이나 예상치 않은 동작을 방지하려면 자체 로그 버킷, 싱크를 만들고 제외 필터를 설정할 때 이러한 이름을 사용하지 않아야 합니다.

사용 설정된 기능	생성된 객체	Fleet 관측 가능성에 사용되는 이름
`defaultConfig`	싱크	`fleet-o11y-FLEET_PROJECT_NUMBER-default`
`defaultConfig`	제외 필터	`fleet-o11y-FLEET_PROJECT_NUMBER-default-exclusion`. 이 이름은 클러스터 프로젝트의 `_Default` 싱크용으로 예약된 이름입니다.
`fleetScopeLogsConfig`	로그 버킷	`fleet-o11y-scope-SCOPE_NAME`
	버킷에 있는 컨테이너 로그의 로그 뷰	`fleet-o11y-scope-SCOPE_NAME-k8s_container`
	버킷에 있는 포드 로그의 로그 뷰	`fleet-o11y-scope-SCOPE_NAME-k8s_pod`
	싱크	`fleet-o11y-FLEET_PROJECT_NUMBER-scope-SCOPE_NAME`
	제외 필터	`fleet-o11y-FLEET_PROJECT_NUMBER-scope-exclusion`

문제 해결

이 섹션에서는 Fleet 로깅 관련 문제를 해결하는 방법을 설명합니다.

싱크 구성 오류에 대한 이메일 알림

[ACTION REQUIRED] Cloud Logging sink configuration error in <Your GCP Project>라는 제목의 이메일이 수신되면 로그 싱크의 서비스 계정에 싱크 대상에 로그 쓰기 권한이 없는 것입니다. 이 문제를 해결하려면 프로젝트 간 로깅 권한의 단계를 따르세요.

Cloud Logging UI의 알 수 없는 오류 메시지

Cloud Logging UI에 다음 오류가 표시되면 URL에 입력한 project_id 및 scope 변수가 올바른지 다시 확인하세요.

Error: There is an unknown error while executing this operation.

멤버십을 찾을 수 없음 오류

다음 오류가 표시될 수 있습니다.

ERROR: (gcloud.alpha.container.fleet.memberships.bindings.create) NOT_FOUND: Resource 'parent resource not found for projects/...' was not found

Fleet에 클러스터를 등록했는지 확인하세요.