Firebase Extensions를 직접 만든 함수 키트로 마이그레이션

마이그레이션 경로 선택: npm의 함수 키트로 마이그레이션 직접 만든 함수 키트로 마이그레이션

게시자가 npm에 배포된 공식 대체 키트를 만들지 않은 경우 이 가이드에서는 확장 프로그램을 포크하고 로컬 함수 키트로 설정하는 단계를 안내합니다.

알려진 이전 제한사항 확인

확장 프로그램 인스턴스 마이그레이션을 시작하기 전에 설정에서 해결 방법이 필요하거나 아직 함수 키트에서 지원되지 않는 다음 기능을 사용하는지 확인하세요.

  • 커스텀 Docker 저장소 및 KMS 키에는 수동 해결 방법이 필요함 Cloud Functions for Firebase는 커스텀 Docker 저장소 또는 고객 관리 암호화 키 (KMS 키)를 구성하기 위한 대체 시스템 매개변수를 지원하지 않습니다. 확장 프로그램이 이러한 매개변수 중 하나를 구성하는 경우 FAQ 해결 방법을 참고하세요.

시작하기 전에

Firebase CLI를 설정하고 Firebase 프로젝트를 초기화해야 합니다. CLI를 사용할 때는 새 이전 및 함수 키트 명령어가 있는 firebase-tools 버전 >= 15.32.0을 사용해야 합니다.

필수 계정 권한 및 역할

마이그레이션 중에 Firebase CLI에서 만들어야 하고 구성해야 하는 항목에 따라 Firebase 및 Google Cloud로 인증하는 데 사용하는 계정에 다음 역할이 있어야 합니다.

  • roles/firebaseextensions.editor
  • roles/cloudbuild.builds.editor
  • roles/artifactregistry.writer
  • roles/run.developer
  • roles/iam.serviceAccountUser
  • roles/iam.serviceAccountCreator
  • roles/cloudfunctions.admin (공개 엔드포인트에 setIamPermissions를 실행해야 하는 경우)
  • roles/secretmanager.admin (보안 비밀을 사용하는 경우)
  • roles/serviceusage.serviceUsageAdmin (새 API를 사용 설정해야 하는 경우)

이러한 권한 대부분이 이미 부여되어 있으므로 이전에 확장 프로그램을 설치하고 함수를 배포한 계정을 사용하는 것이 좋습니다. 이전하는 계정에 역할이 더 필요한 경우 Google Cloud IAM 안내에 따라 역할을 추가하세요.

확장 프로그램 인스턴스를 최신 버전으로 업그레이드

확장 프로그램 인스턴스와 교체 키트 간의 차이를 최소화하려면 확장 프로그램을 최신 버전으로 업데이트해야 합니다. 확장 프로그램이 업그레이드되지 않으면 확장 프로그램 인스턴스와 키트 대체 사이에 중요한 브레이킹 체인지가 있을 수 있습니다. 버전 간 매개변수 변경으로 인해 내보낸 구성이 키트에서 예상하는 것과 일치하지 않을 수 있습니다.

확장 프로그램이 설치된 위치에 따라 다음 옵션 중 하나를 사용하여 확장 프로그램을 업데이트합니다.

  • Firebase 콘솔에서
  • Firebase CLI에서 다음을 사용하여 실행합니다.
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

이 단계를 건너뛰면 확장 프로그램이 최신 버전이 아닌 경우 구성을 내보낼 때 CLI에서 업그레이드하라는 메시지가 표시됩니다.

확장 프로그램을 로컬 함수 키트로 포크

확장 프로그램을 로컬 함수 키트로 변환하기 전에 확장 프로그램 소스 코드가 Firebase 프로젝트 내에 있는지 확인하세요. 이렇게 하려면 GitHub에서 확장 프로그램 저장소를 클론하고 Firebase 프로젝트 루트 내에 디렉터리를 만든 후 확장 프로그램의 functions/ 폴더와 extension.yaml를 복사합니다.

mkdir -p path/to/kit
cp -r /path/to/extension-source/functions/* path/to/kit/
cp /path/to/extension-source/extension.yaml path/to/kit/.

게시자 이전 가이드의 1~8단계를 따라 확장 프로그램 소스 코드를 2세대 함수로 이전합니다. 그런 다음 다음 단계를 계속 진행합니다.

내 로컬 키트가 내보낸 함수 리전 및 고급 매개변수를 지원하도록 설정

로컬 함수 키트에서 Firebase CLI는 패키지를 설정하고 이전된 시스템 매개변수를 사용하도록 구성하는 index.ts 파일을 생성하지 않습니다. 확장 프로그램에 구성된 함수 리전 및 고급 매개변수를 사용하려면 firebase ext:export --mode functions에서 내보낸 형식을 환경 변수 파일로 읽도록 index.ts 파일을 설정하세요.

특히 함수를 내보내는 최상위 index.ts 파일에서 FUNCTION_DEFAULT_REGION의 매개변수를 정의하고 CLI에서 사용하는 index-kit-migration.ts 템플릿과 유사한 EXT_MIGRATED_SYSTEM_<GLOBAL_OPTION> 형식의 환경 변수를 사용하여 setGlobalOptions를 호출합니다.

import { setGlobalOptions } from "firebase-functions";
import { MemoryOption, VpcEgressSetting, IngressSetting } from "firebase-functions/v2/options";
import { defineString } from "firebase-functions/params";

export const regionParam = defineString("FUNCTION_DEFAULT_REGION", {
  input: { text: { nonEmpty: true } },
  description: "Global default region where functions should be deployed. Can be overridden per-function.",
});

setGlobalOptions({
  region: regionParam,
  memory: (process.env.EXT_MIGRATED_SYSTEM_MEMORY as MemoryOption) ?? undefined,
  timeoutSeconds: process.env.EXT_MIGRATED_SYSTEM_TIMEOUTSECONDS
    ? Number(process.env.EXT_MIGRATED_SYSTEM_TIMEOUTSECONDS)
    : undefined,
  vpcConnectorEgressSettings:
    process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS &&
    process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS !== "VPC_CONNECTOR_EGRESS_SETTINGS_UNSPECIFIED"
      ? (process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS as VpcEgressSetting)
      : undefined,
  vpcConnector: process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOR ?? undefined,
  maxInstances: process.env.EXT_MIGRATED_SYSTEM_MAXINSTANCES
    ? Number(process.env.EXT_MIGRATED_SYSTEM_MAXINSTANCES)
    : undefined,
  minInstances: process.env.EXT_MIGRATED_SYSTEM_MININSTANCES
    ? Number(process.env.EXT_MIGRATED_SYSTEM_MININSTANCES)
    : undefined,
  ingressSettings: (process.env.EXT_MIGRATED_SYSTEM_INGRESSSETTINGS as IngressSetting) ?? undefined,
  // Parses a comma-separated string of key:value pairs into a key-value object
  // (for example, "key1:value1,key2:value2" -> { key1: "value1", key2: "value2" }).
  labels: process.env.EXT_MIGRATED_SYSTEM_LABELS
    ? process.env.EXT_MIGRATED_SYSTEM_LABELS.split(",").reduce<Record<string, string> | undefined>(
        (acc, curr) => {
          const [key, value] = curr.split(":");
          const trimmedKey = key?.trim();
          const trimmedValue = value?.trim();
          if (!trimmedKey || !trimmedValue) {
            return acc;
          }
          acc = acc ?? {};
          acc[trimmedKey] = trimmedValue;
          return acc;
        },
        undefined,
      )
    : undefined,
});

// Re-export all functions so the Firebase CLI can deploy them
export * from "./your-functions";

이전하기 전에 키트 테스트

이제 배포 시 확장 프로그램의 새 설치와 동일하게 작동하는 로컬 함수 키트가 있습니다. 다음 단계는 프로덕션 확장 프로그램 인스턴스를 새 버전으로 마이그레이션하기 전에 실수로 발생한 문제를 확인하고 수정하는 것입니다.

먼저 포크를 로컬 키트로 추가하고 구성한 후 테스트 프로젝트에 배포합니다. 로컬 함수 키트는 Firebase 프로젝트 내에 있어야 하므로 클론된 확장 프로그램 저장소가 Firebase 프로젝트 외부에 있는 경우 프로젝트 디렉터리 내부로 이동합니다. 그런 다음 다음 키트 설치 명령어를 실행하여 로컬 키트로 설치합니다.

firebase functions:kits:install --directory <path-to-your-fork> --project <test-project-id>

이 명령어는 첫 번째 테스트 인스턴스의 키트 ID, 인스턴스 ID, 구성을 선택하는 과정을 안내합니다. 그런 다음 firebase.json 파일을 수정하여 포크된 디렉터리를 가리키는 로컬 키트를 등록합니다. 각 인스턴스의 구성은 function-kits/<kit-id>/config-<instance-id>의 .env 파일에 저장됩니다.

동작을 테스트할 적절한 리소스가 있는 테스트 프로젝트에 로컬 키트를 배포합니다. 확장 프로그램 테스트에서 이미 테스트 프로젝트를 설정한 경우 다음 명령어를 실행합니다.

firebase deploy --only functions:<kit-instance-id> --project <test-project-id>

작동 예: Cloud Firestore를 BigQuery(firestore-bigquery-export)로 스트리밍

Cloud Firestore에서 BigQuery로의 동기화가 엔드 투 엔드로 이루어지는지 확인합니다.

  1. Firebase 콘솔의 Cloud Firestore 페이지에서 COLLECTION_PATH (users)로 설정한 컬렉션이 아직 없는 경우 컬렉션을 만듭니다.
  2. 필드와 값이 포함된 bigquery-mirror-test이라는 문서를 만듭니다.

  3. Google Cloud 콘솔의 BigQuery 페이지에서 원시 변경 로그 테이블을 쿼리합니다. 문서 생성을 로깅하는 단일 행이 포함되어야 합니다.

    SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog`

  4. 최신 보기를 쿼리합니다. 그러면 존재하는 유일한 문서 (bigquery-mirror-test)의 최신 변경 이벤트가 반환됩니다.

    SELECT * FROM `PROJECT_ID.analytics.users_raw_latest`

  5. Cloud Firestore에서 bigquery-mirror-test 문서를 삭제합니다. 최신 뷰에서 사라지고 DELETE 이벤트가 원시 변경 로그 표에 추가됩니다.

    다음 명령어를 사용하여 단일 문서의 전체 기록을 검사할 수 있습니다.

    SELECT *
   FROM `PROJECT_ID.analytics.users_raw_changelog`
   WHERE document_name = "bigquery-mirror-test"
   ORDER BY timestamp ASC

확장 프로그램 테스트와의 차이점:

  • 트리거는 ext-<instanceId>-fsexportbigquery이 아닌 kit-<kit-instance-id>-fsexportbigquery로 배포됩니다. Cloud Functions 대시보드와 로그에서 해당 이름을 찾습니다.
  • 코드는 Firebase Local Emulator Suite에서 표준 함수로 실행됩니다. .env.local를 사용하여 에뮬레이터에서 사용할 매개변수 값을 설정할 수 있습니다. Cloud Functions 단위 테스트에 설명된 대로 firebase-functions-test SDK를 사용하여 코드를 단위 테스트할 수도 있습니다.
  • 프로비저닝이 더 이상 확장 프로그램 런타임에 의해 실행되지 않습니다. 배포 후 변경사항 로그 테이블이 누락된 경우 설정 작업을 수동으로 다시 실행합니다(firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>). 이 작업은 동일한 결과를 반환하므로 다시 실행하면 데이터 세트, 테이블, 뷰가 조정됩니다.
  • 매개변수 값은 설치 양식이 아닌 .env에서 가져오므로 .env가 완료되면 firebase deploy의 재실행은 비대화형입니다.

(선택사항) 테스트 후 정리

테스트 후 이 테스트 인스턴스를 삭제하려면 제거하세요.

firebase functions:kits:uninstall --instance <kit-instance-id> --project <test-project-id>

이렇게 하면 키트를 배포하여 생성된 모든 클라우드 리소스가 삭제되고 인스턴스 구성이 삭제됩니다. 키트 인스턴스가 하나만 있는 경우 firebase.json에서 키트 항목도 삭제됩니다. 로컬 소스 코드 디렉터리는 삭제되지 않습니다. 프로덕션 이전용 키트를 설치할 때 키트 ID를 다시 선택할 수 있습니다.

확장 프로그램에서 로컬 키트로 마이그레이션

로컬 키트가 테스트되었으므로 라이브로 배포된 확장 프로그램 인스턴스를 마이그레이션할 수 있습니다.

1. 교체 함수 키트 인스턴스 설치

--no-configure를 전달하여 수동 구성을 건너뛰고 다음 단계에서 기존 확장 프로그램 구성을 이 키트 인스턴스로 직접 내보낼 수 있도록 로컬 함수 키트를 설치합니다.

firebase functions:kits:install --no-configure --directory <path-to-your-fork> --project <project-id>

2. 확장 프로그램과 동일하게 함수 키트 인스턴스 구성

이 키트 인스턴스를 대체하는 확장 프로그램과 동일한 구성으로 맞춤설정해야 합니다. 확장 프로그램 인스턴스 구성을 .env 파일로 내보낼 수 있습니다. 이 파일에는 키트를 포함한 모든 Cloud Functions의 매개변수, 환경 변수, 비밀 참조 구성 데이터가 저장됩니다. 키트의 구성 파일로 직접 내보내려면 다음을 실행하세요.

firebase ext:export --mode functions --instance <extension-instance-id> --kit-instance <kit-instance-id> --project <project-id>

이 단계가 끝나면 이 인스턴스의 구성 정보가 인스턴스 구성 디렉터리의 프로젝트별 .env 파일에 저장됩니다(예: function-kits/<kit-name>/config-<instance-id>/.env.<project-id>).

3. 키트 교체 배포 및 확인

이제 키트가 설치되고 함수 집합으로 사용할 수 있으므로 키트 교체를 배포할 수 있습니다. 함수 키트는 표준 함수와 마찬가지로 작동하며, 각 키트 인스턴스는 함수를 정리하기 위한 별도의 코드베이스 역할을 합니다. 모든 함수를 배포하거나 특정 키트 인스턴스만 배포할 수 있습니다. 단일 확장 프로그램 인스턴스를 이전하는 동안 해당 키트 인스턴스만 배포합니다.

키트에서 이전한 확장 프로그램 인스턴스에 없던 새 매개변수를 사용하는 경우 Firebase CLI는 배포 프로세스 시작 시 이러한 매개변수를 묻는 메시지를 표시합니다. 최신 firestore-bigquery-export 확장 프로그램의 이 예에서는 예상되지 않지만 많은 키트에서 키트에서 사용하는 모든 이벤트 트리거 소스에 대한 새 매개변수를 묻는 메시지를 표시합니다. 이 이전의 일환으로, 업데이트된 키트는 확장 프로그램이 이전에 1세대 함수를 사용한 경우 2세대 함수를 사용합니다. 2세대에서는 함수가 이벤트 소스 근처에 있으며 추가 매개변수로 추가됩니다. 향후 업데이트에서 새 매개변수가 추가되면 CLI에서 다음 배포 시 메시지를 표시합니다.

작업 예시:

firebase deploy --only functions:firestore-bigquery-export --project my-project

출력:

=== Deploying to 'my-project'...
i  deploying functions
i  functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
i  functions: ensuring required API bigquery.googleapis.com is enabled...
i  functions: ensuring required API cloudtasks.googleapis.com is enabled...
✔  functions: required APIs are enabled
i  functions: granting declarative IAM roles to managed service account:
   - BigQuery Data Editor
   - BigQuery User
   - Cloud Datastore User
   - Eventarc Event Receiver
   - roles/run.invoker
✔  functions: successfully granted IAM roles
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-fsexportbigquery(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-initBigQuerySync(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-setupBigQuerySync(us-central1)...
✔  functions[kit-firestore-bigquery-export-fsexportbigquery(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-initBigQuerySync(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-setupBigQuerySync(us-central1)] Successful create operation.
i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/us-central1/queues/kit-firestore-bigquery-export-initBigQuerySync.
✔  Deploy complete!

키트의 firebase deploy에 오류가 없는지 확인하려면 배포 로그를 확인하여 수명 주기 후크가 트리거되었는지 확인합니다. 스트림 Cloud Firestore에서 BigQuery로와 같은 인기 확장 프로그램은 수명 주기 후크를 사용합니다. 다음은 트리거될 때 수명 주기 후크가 표시되는 방식의 예시입니다.

i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i  functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project

이러한 로그 메시지는 다음을 확인합니다.

  • 수명 주기 후크가 발견되어 실행되었습니다.
  • 태스크가 수명 주기 후크의 연결된 태스크 큐에 대기열에 추가되었습니다.
  • 오류 없이 작업이 완료되었는지 확인할 수 있도록 Cloud Logging 링크가 제공되었습니다.

로그 링크를 따라 Google Cloud 콘솔로 이동하여 로그에 오류가 없고 태스크 큐 이벤트가 성공적으로 처리되었는지 확인합니다. 수명 주기 이벤트가 성공적으로 실행되지 않은 경우 다음을 실행하여 다시 트리거할 수 있습니다.

firebase functions:lifecycle:run <hook-name> <codebase>

함수 키트 인스턴스를 처음 배포하는 경우 다음을 실행합니다.

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

유효성 검사 중에 언제든지 이 이전을 중지하거나 실행취소하려면 확장 프로그램 제거의 안내에 따라 키트를 제거하면 됩니다.

4. 확장 프로그램 제거

배포된 함수 키트를 확인한 후에는 키트에서 한 번, 확장 프로그램에서 한 번 동작이 중복되지 않도록 확장 프로그램을 제거할 수 있습니다. --immediate 플래그를 전달하면 설치 방법에 관계없이 Firebase CLI에서 모든 확장 프로그램을 제거할 수 있습니다.

firebase ext:uninstall <extension-instance-id> --project <project-id> --immediate

작업 예시:

firebase ext:uninstall firestore-bigquery-export --project my-project --immediate

출력:

i  extensions: uninstalling firestore-bigquery-export...
i  extensions: deleting extension instance resources in project my-project...
✔  extensions: successfully uninstalled firestore-bigquery-export

고급 마이그레이션

단일 코드베이스로 관리하려는 여러 Firebase 프로젝트에 확장 프로그램을 포함할 수 있습니다. 예를 들어 testing 환경과 production 환경에 동일한 인프라를 배포하고 각 환경에는 BigQuery로 내보내는 documents Cloud Firestore 인스턴스가 있는 경우 firestore-bigquery-export 확장 프로그램의 인스턴스가 두 개 설치될 수 있습니다.

  • export-documents-testing
  • export-documents-production

Firebase CLI로 작업할 때 이러한 두 확장 프로그램 인스턴스를 단일 코드베이스의 두 함수 키트 인스턴스로 마이그레이션하고 firebase deploy --project testing 및 firebase deploy --project production를 사용하여 배포한 경우 각 배포는 testing 및 production 환경 모두에서 두 인스턴스를 생성합니다.

대신 두 확장 프로그램 인스턴스를 여러 프로젝트에 배포된 firestore-bigquery-export의 함수 키트 인스턴스 하나로 대체합니다. 각 프로젝트에는 자체 구성이 있습니다. 인스턴스의 구성 디렉터리는 다음과 같이 표시됩니다.

  • config-export-documents/
    • .env.testing
    • .env.production

testing 및 production에 대한 각 배포는 해당 구성으로 키트의 인스턴스를 하나 만듭니다. ext:migrate 또는 functions:kits:install 호출마다 --project 플래그를 전달하면 기존 CLI 명령어에서 이 설정을 만듭니다.

작업 예시:

firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project testing --no-configure --template migration

✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? export-documents
✔  Wrote function-kits/firestore-bigquery-export/source/package.json
✔  Wrote function-kits/firestore-bigquery-export/source/tsconfig.json
✔  Wrote function-kits/firestore-bigquery-export/source/.gitignore
✔  Wrote function-kits/firestore-bigquery-export/source/src/index.ts
i  functions: Running npm install
✔  Wrote configuration info to firebase.json
✔  functions: Function kit firestore-bigquery-export successfully installed.

# This creates the export-documents instance with an empty .env.testing file
# for the testing project. Now populate it via export:
firebase ext:export --mode functions --instance export-documents-testing \
  --kit-instance export-documents --project testing

# Repeat the export for production into the same kit instance to create
# .env.production from the export-documents-prod instance:
firebase ext:export --mode functions --instance export-documents-prod \
  --kit-instance export-documents --project production

이제 각 구성으로 testing 및 production 프로젝트에 배포하도록 구성된 단일 키트 인스턴스가 있습니다. testing 프로젝트에서 인스턴스를 만들고 production 프로젝트에서 동일한 패키지에 대해 functions:kits:install 명령어를 실행하면 testing에 구성된 인스턴스를 재사용하거나 두 번째 인스턴스를 설치하는 옵션이 표시됩니다.