업그레이드 가이드

이 가이드에서는 Terraform을 사용하여 기존 Manufacturing Data Engine (MDE) 설치를 업그레이드하는 방법에 관한 일반적인 안내를 제공합니다.

Terraform 스크립트를 수정한 경우 추가 단계가 필요할 수 있습니다. 이 가이드는 일반적인 업그레이드 가이드이므로 항상 배포하는 특정 버전의 전체 출시 노트도 읽어보세요. 고려해야 할 정보가 포함되어 있을 수 있습니다.

시작하기 전에

업그레이드하기 전에 일부 Dataflow 작업을 수동으로 중지해야 합니다. 출시 노트에는 업그레이드할 특정 버전에서 수동으로 중지해야 하는 작업이 나열되어 있습니다.

이 가이드에는 다음 기본 요건이 필요합니다.

기본 배포 패키지를 사용하고 있습니다.
클라이언트 환경에 필요한 CLI 도구가 최신 버전으로 설치되어 있습니다.
- 다음 추가 구성요소가 설치된 Google Cloud CLI
  - kubectl
  - cbt
  - Terraform CLI(1.9.x 이상)
  - Helm CLI (3.9.x 이상)
클라이언트 환경을 사용하여 MDE를 배포할 수 있지만, 필요한 도구가 대부분 이미 설치되어 있는 Cloud Shell에서 배포하면 시간을 절약할 수 있습니다.
Cloud Shell 활성화
MDE Google Cloud 프로젝트에 대한 전체 액세스 권한과 원래 배포에 사용된 구성 파일에 대한 액세스 권한이 있습니다.
- 서비스 계정 JSON 키 파일: mde-imgs-service-account-key.json
- Terraform: input.tfvars
- Terraform: backend.conf
참고: MDE v1.5에는 서비스 계정 JSON 키 파일이 필요하지 않습니다.

이 가이드의 모든 gcloud 명령어는 기본 프로젝트가 MDE 배포 프로젝트로 설정되어 있다고 가정합니다. 다음 명령어를 사용하여 기본 프로젝트를 설정할 수 있습니다.
```
gcloud config set project PROJECT_ID
```
PROJECT_ID를 MDE 배포 프로젝트 ID로 바꿉니다.

MDE GKE 클러스터의 사용자 인증 정보를 획득했습니다. 아직 사용하지 않은 경우 다음 명령어를 사용하세요.

export CLUSTER_NAME="mde-gke"
export CLUSTER_LOCATION=$(gcloud container clusters list --filter="name:$CLUSTER_NAME" --format="value(LOCATION)" )

# when upgrading to 1.5.2 we need to enable DNS endpoint on GKE cluster to allow Terraform connect to it
gcloud container clusters update $CLUSTER_NAME --region $CLUSTER_LOCATION --enable-dns-access

export KUBE_CONFIG_PATH=~/.kube/config
gcloud container clusters get-credentials $CLUSTER_NAME --region $CLUSTER_LOCATION --dns-endpoint

기본 이름 (mde-gke)을 변경한 경우 CLUSTER_NAME를 클러스터 이름으로 바꿉니다. kubeconfig가 기본 경로에 없는 경우 KUBE_CONFIG_PATH를 변경합니다.

업그레이드

이 섹션에서는 Terraform을 사용하여 업그레이드를 실행하는 방법을 안내합니다.

MDE 1.4.0 이상에서 새로 필요한 권한을 추가하도록 Terraform 서비스 계정 권한을 업데이트합니다. 다음 명령어를 사용하여 추가할 수 있습니다.

export PROJECT_ID=$(gcloud config get-value project)
export SA_TERRAFORM="mde-tf"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SA_TERRAFORM@$PROJECT_ID.iam.gserviceaccount.com" \
--role='roles/file.editor'

다음 명령어를 사용하여 이전 배포 폴더를 백업합니다.
```
cp -r MDE_FOLDER MDE_FOLDER_BACKUP
```
MDE_FOLDER 및 MDE_FOLDER_BACKUP을 MDE 폴더 및 백업 폴더의 이름으로 바꿉니다.
최신 MDE 솔루션 출시 버전 패키지를 다운로드하고 압축을 풉니다.

참고: MDE 배포 애셋에 액세스하려면 Google Cloud 팀의 승인이 필요합니다. MDE 테스트 또는 배포에 관심이 있다면 최대한 빨리 문의하는 것이 좋습니다. Google Cloud 계정 팀을 모르는 경우 화면 오른쪽 상단의 Contact Us 버튼을 사용해 주세요. 곧 연락드리겠습니다.
1. 솔루션 패키지를 다운로드합니다.
2. 패키지를 클라이언트 환경에 추출합니다.
3. cd 명령어를 사용하여 새 출시 폴더로 이동합니다.

v1.4.x로 업그레이드하는 경우 다음 명령어를 사용하여 백업에서 새 폴더로 다음 파일을 복사합니다 (파일 경로는 다를 수 있음).

cp ../MDE_FOLDER_BACKUP/mde-imgs-service-account-key.json .
cd deployment/terraform
cp ../../../MDE_FOLDER_BACKUP/deployment/terraform/input.tfvars .
cp ../../../MDE_FOLDER_BACKUP/deployment/terraform/backend.conf .

v1.5.1로 업그레이드하는 경우 다음 파일만 복사하세요.

cd deployment/terraform
cp ../../../MDE_FOLDER_BACKUP/deployment/terraform/input.tfvars .
cp ../../../MDE_FOLDER_BACKUP/deployment/terraform/backend.conf .

MDE_FOLDER_BACKUP을 MDE 백업 폴더 이름으로 바꿉니다.

v1.4.x에서 v1.5.x로 또는 v1.5.0에서 v1.5.1로 업그레이드하는 경우 출시 패키지에 포함된 업그레이드 전 스크립트를 실행합니다.

참고: 모든 Pub/Sub 구독이 드레인된 후에 이 스크립트를 실행해야 합니다. '/configuration/v1/processing:stop' API를 사용하거나 MDE UI에서 Messages processing 스위치를 전환하여 처리를 중지하고 시스템이 드레인되도록 한 후 이 스크립트를 실행할 수 있습니다.
```
# Execute script from the upgrade/1.5 directory and return to the terraform directory
cd ../../upgrade/1.5
export BQ_PROJECT_ID=$(gcloud config get-value project)
export PUBSUB_PROJECT_ID=$(gcloud config get-value project)
sh migrate-metadata-instance-bq-table.sh "$BQ_PROJECT_ID" "$PUBSUB_PROJECT_ID"
cd ../../deployment/terraform
```

1.5.2로 업그레이드하는 경우 다음 명령어를 사용하여 Kubernetes 제공자를 전환하여 providers.tf 파일에서 로컬 kubeconfig를 사용해야 합니다.

provider "kubernetes" {
config_path            = "~/.kube/config"
# host                   = "https://${local.gke_host}"
# token                  = data...
# cluster_ca_certificate = local.gke_ca_cert
}

provider "helm" {
kubernetes {
    config_path            = "~/.kube/config"
    # host                   = "https://${local.gke_host}"
    # token                  = data...
    # cluster_ca_certificate = local.gke_ca_cert
}
}

다음 명령어를 사용하여 Terraform 상태를 다시 로드합니다.
```
terraform init -backend-config=backend.conf -reconfigure
```
Terraform 계획을 만듭니다.

입력 매개변수가 준비되면 다음 명령어를 사용하여 Terraform 계획을 만들어야 합니다. 계획을 사용하여 프로젝트에 생성될 아티팩트와 구성을 확인할 수 있습니다.

참고: v1.5.x 이후에는 서비스 계정 키가 더 이상 필요하지 않으므로 mde_artifact_registry_sa_path에 관한 Terraform 경고가 표시될 수 있습니다. 이 경고는 무시해도 되며 input.tfvars 파일에서 이 변수를 주석 처리하거나 삭제해도 됩니다.
```
terraform plan -var-file=./input.tfvars -out=./tfplan
```
다음 명령어를 사용하여 계획된 변경사항을 탐색할 수 있습니다.
```
terraform show -no-color ./tfplan > tfplan.txt
more tfplan.txt
```
중요: 계획 단계에서 lifecycle.prevent_destroy 플래그가 있어 -materialization 접미사로 끝나는 특정 Pub/Sub 구독을 삭제할 수 없다는 오류가 Terraform에 표시되면 -materialization 접미사로 끝나는 모든 Pub/Sub 주제와 이에 연결된 구독을 수동으로 삭제해야 합니다. 배포를 시작하기 전에 이 단계를 실행해야 배포 후 MDE에서 주제가 자동으로 생성됩니다.
다음 명령어를 사용하여 Terraform 계획을 적용합니다.
```
terraform apply ./tfplan
```
배포가 성공했는지 확인합니다.

terraform apply 명령어 실행이 완료되면 다음과 비슷한 성공 메시지가 표시됩니다. 실제 숫자는 특정 배포 옵션과 버전에 따라 달라집니다.
```
Apply complete! Resources: 1 added, 34 changed, 0 destroyed.
```

업그레이드 후

업그레이드가 완료되면 이전 MDE 배포 상태에 따라 다음 단계 중 하나 이상을 수행해야 합니다.

기존 유형의 BigQuery 뷰

1.4.x 이전 버전에서 업그레이드하는 경우 이 기능이 1.4.0에서 도입되었으므로 생성된 유형에 대해 애널리틱스 뷰가 생성되지 않습니다. 분석 보기 재생성을 트리거하려면 기존 유형을 다시 활성화해야 합니다. 출시와 함께 제공되는 Postman 키트에서 /activate 엔드포인트를 확인할 수 있습니다.

GKE 클러스터 Filestore 드라이버

GKE 클러스터 포드가 ContainerCreating에서 시작되거나 멈추는 문제가 발생하면 Filestore 드라이버가 사용 설정되지 않았기 때문일 수 있습니다. 배포 가이드의 단계에 따라 사용 설정할 수 있습니다.