이 페이지는 Cloud Translation API를 통해 번역되었습니다.

수동 설정 가이드

자동 프로비저닝 흐름을 사용하여 클릭 몇 번으로 Cloud Run에 태그 관리 서버를 배포할 수 있습니다. 다른 환경에서 태그 관리 서버를 프로비저닝하려면 수동으로 프로비저닝하면 됩니다. 태그 관리 서버는 Docker 이미지 내부의 Node.js 서버입니다.

태그 관리 서버를 수동으로 프로비저닝하려면 서버 측 태그 지정(SST) 클러스터와 미리보기 서버를 별도로 프로비저닝해야 합니다. SST 클러스터는 태그 관리 서버에 대한 모든 요청의 진입점이며, 서버 측 태그 지정 소개에 설명된 대로 요청을 처리합니다. 미리보기 서버는 컨테이너를 미리 보는 데 필요합니다.

태그 관리 서버와 미리보기 서버 간의 데이터 상호작용을 보여주는 그림 1을 참고하세요.

태그 관리 서버 및 미리보기 서버 데이터 흐름을 보여주는 다이어그램

그림 1: 태그 관리 서버 및 미리보기 서버 데이터 흐름을 보여주는 다이어그램

이 가이드에서는 다음을 수행하는 방법을 설명합니다.

Docker 이미지에 사용 가능한 모든 설정 보기
(선택사항) BigQuery 사용자 인증 정보 포함
SST Docker 이미지를 사용하여 미리보기 서버를 수동으로 프로비저닝
SST Docker 이미지를 사용하여 SST 클러스터를 수동으로 프로비저닝
미리보기 서버 및 SST 클러스터가 올바르게 구성되었는지 확인
서버를 프로비저닝한 후 태그 관리 서버 버전을 업데이트

이 가이드에 나온 Docker 명령어를 실행하려면 먼저 컴퓨터에 Docker를 설치해야 합니다.

Docker 이미지에 사용 가능한 모든 설정 보기

태그 관리 서버 Docker 이미지는 다음 URL에서 찾을 수 있습니다.

gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

태그 관리 서버와 미리보기 서버는 동일한 Docker 이미지를 다양한 플래그와 함께 사용합니다. 이 섹션에서는 Docker 이미지에서 사용할 수 있는 모든 설정을 찾는 방법을 살펴봅니다.

사용 가능한 모든 설정을 보려면 Docker 명령줄 도구를 사용하여 다음을 실행합니다.

docker run gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable server_bin.js --help

(선택사항) Google Cloud 사용자 인증 정보 포함

Google Cloud 외부에서 BigQuery 또는 Firestore API를 사용하려면 이러한 리소스에 액세스하도록 승인된 서비스 계정 사용자 인증 정보를 제공해야 합니다.

이 가이드에 따라 BigQuery 액세스를 위한 BigQuery 데이터 편집자 역할 또는 Firestore 액세스를 위한 Cloud Datastore 사용자 역할로 서비스 계정을 만들고 local_service_account_key.json 파일 이름을 사용하여 JSON 사용자 인증 정보를 내보냅니다.
이미지에서 액세스할 수 있는 볼륨에 JSON 사용자 인증 정보를 마운트합니다. docker run을 사용하면 -v local_service_account_key.json:/app/service_account_key.json을 지정하여 이미지에서 사용자 인증 정보를 마운트할 수 있습니다.
GOOGLE_APPLICATION_CREDENTIALS 환경 변수가 사용자 인증 정보를 가리키도록 지정합니다.
원하는 경우 태그 관리 서버가 프로젝트를 암시적으로 선택할 수 있도록 GOOGLE_CLOUD_PROJECT 환경 변수에 Google Cloud 프로젝트 ID를 지정합니다.

서버를 실행합니다. 다음 명령어는 사용자 인증 정보를 포함하여 태그 관리 서버를 실행합니다.

docker run -v local_service_account_key.json:/app/service_account_key.json \
-p 8080:8080 \
-e GOOGLE_APPLICATION_CREDENTIALS='/app/service_account_key.json' \
-e GOOGLE_CLOUD_PROJECT='<your project id>' \
-e CONTAINER_CONFIG='<config string>' \
gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

태그 관리 서버가 배포되는 시스템에 따라 사용자 인증 정보를 마운트하는 방식에는 여러 가지가 있을 수 있습니다. 예를 들어 Kubernetes 및 Docker Swarm에서는 보안 비밀 관리에 관한 가이드를 제공합니다. 자세한 내용은 해당 시스템의 가이드를 참고하세요.

사용자 인증 정보를 보호하려면 권장사항을 따라야 합니다.

수동으로 미리보기 서버 프로비저닝

미리보기 서버를 사용하면 서버 컨테이너를 미리 볼 수 있습니다. 미리보기 서버를 실행하려면 Docker 환경으로 전달된 다음과 같은 환경 변수를 사용하여 Docker 이미지를 실행합니다.

필수 설정

CONTAINER_CONFIG - 서버 컨테이너의 구성 문자열입니다. 태그 관리자에서 서버 컨테이너 작업공간으로 이동한 후 페이지 오른쪽 상단에 있는 컨테이너 ID를 클릭합니다. 태그 관리 서버 수동 프로비저닝을 클릭하여 컨테이너 구성 값을 찾습니다.
RUN_AS_PREVIEW_SERVER - 이를 true로 설정하여 서버를 미리보기 서버로 프로비저닝합니다.

Docker 명령줄 도구 사용 예시

미리보기 서버를 로컬에서 프로비저닝하려면 다음을 실행합니다.

docker run -p 8080:8080 -e CONTAINER_CONFIG='<config string>' -e RUN_AS_PREVIEW_SERVER=true gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

http://localhost:8080/healthz에 대한 요청에서 200 응답이 표시되어야 합니다. 원하는 경우 PORT 환경 변수를 사용하여 포트를 변경합니다.

권장사항

정확히 1개의 미리보기 서버를 배포해야 합니다. 인스턴스 1개를 초과하여 자동 확장을 구성하면 안 됩니다.
Docker를 사용하여 미리보기 서버를 설정했으면 HTTPS URL을 구성하여 미리보기 서버를 가리키도록 지정합니다. SST 클러스터를 설정하려면 이 작업을 거쳐야 합니다.
부하 분산기 또는 CDN의 시간 제한이 20초보다 길어야 하며, 그렇지 않으면 미리보기 모드가 제대로 작동하지 않습니다.

수동으로 서버 측 태그 지정 클러스터 프로비저닝

SST 클러스터는 진입점 역할을 하고, 미리보기 서버에 대한 미리보기 요청을 프록시하고, 서버 측 태그 지정 소개에 설명된 대로 다른 모든 요청을 처리합니다. 태그 관리 서버 Docker 이미지에 다음과 같은 필수 설정을 사용하여 Docker를 지원하는 모든 환경에서 SST 클러스터를 프로비저닝합니다.

필수 설정

CONTAINER_CONFIG - 서버 컨테이너의 구성 문자열입니다. 태그 관리자에서 서버 컨테이너 작업공간으로 이동한 후 페이지 오른쪽 상단에 있는 컨테이너 ID를 클릭합니다. 태그 관리 서버 수동 프로비저닝을 클릭하여 컨테이너 구성 값을 찾습니다.
PREVIEW_SERVER_URL - 미리보기 서버의 HTTPS URL입니다. 이 설정은 태그 관리 서버를 프로비저닝하기 위해서만 구성되어야 하며 미리보기 서버를 프로비저닝하는 데는 필요하지 않습니다. 미리보기 서버 설정에 관한 가이드는 위 섹션을 참고하세요.

Docker 명령줄 도구 사용 예시

단일 태그 관리 서버를 로컬에서 프로비저닝하려면 다음을 실행합니다.

docker run -p 8080:8080 -e CONTAINER_CONFIG='<config string>' -e PREVIEW_SERVER_URL='<HTTPS preview server url>' gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

http://localhost:8080/healthz에 대한 요청에서 200 응답이 표시되어야 합니다. 원하는 경우 PORT 환경 변수를 사용하여 포트를 변경합니다.

권장사항

서버 측 태그 관리 서버를 단일 서버나 클러스터로 프로비저닝할 수 있습니다. 가용성, 확장성, 성능을 향상하려면 이를 클러스터로 프로비저닝하는 것이 좋습니다. 클러스터로 프로비저닝할 때 각 서버 인스턴스는 동일한 CONTAINER_CONFIG 및 PREVIEW_SERVER_URL 환경 변수로 구성되어야 합니다.
태그 관리 서버를 동일한 출처 (권장사항) 또는 현재 웹사이트의 하위 도메인으로 호스팅해야 합니다. 예를 들어 애플리케이션이 example.com에서 웹 트래픽을 제공하는 경우 태그 관리 서버에 example.com/analytics와 같은 경로를 사용하세요. 커스텀 도메인 구성에 대해 자세히 알아보기
Docker를 사용하여 SST 클러스터를 설정한 후에는 HTTPS URL을 구성하여 SST 클러스터를 가리키도록 지정하세요.
서버가 SST에 대해 최신 코드 업데이트를 포함하도록 주기적으로 서버를 다시 시작해야 합니다. 그렇지 않으면 새 SST 기능과 호환되지 않는 기능이 있을 수도 있습니다. 서버를 다시 시작해야 하는 시점을 알 수 있는 한 가지 방법은 활성 확인을 설정하는 것이며, 이에 대한 설명은 아래에 나와 있습니다. 또한 서버 컨테이너에 대한 모든 게시된 업데이트는 다시 시작하지 않아도 계속해서 적용됩니다.
태그 관리 서버에서 기존 /healthz 엔드포인트(예: https://analytics.example.com/healthz)를 활용하여 활성 확인을 설정합니다. 비정상 응답은 서버를 다시 시작해야 함을 나타냅니다.
Docker 컨테이너에는 /healthz 엔드포인트를 주기적으로 쿼리하는 기본 상태 점검 명령어 HEALTHCHECK CMD ["/nodejs/bin/node", "/app/health_checker_bin.js"]가 포함되어 있습니다. Docker 상태 점검에 의존하는 경우, Docker 지침에 따라 설정을 변경할 수 있습니다.
미리보기 서버와 태그 관리 서버가 동일한 원본에 있는 경우 미리보기 서버를 태그 관리 서버와 다른 경로에서 호스팅합니다. 경로를 포함하여 PREVIEW_SERVER_URL을 지정합니다.
프로비저닝된 서버의 vCPU는 최대 1개여야 합니다. 추가 vCPU는 활용되지 않으며 자동 확장에 부정적인 영향을 미칩니다.

유효성 검사

서버 컨테이너 URL 구성

태그 관리자에서 서버 컨테이너로 이동합니다. 관리자 > 컨테이너 설정에서 태그 관리 서버의 URL을 서버 컨테이너 URL 필드에 입력하고 저장을 클릭합니다.

미리보기 모드를 통한 확인

태그 관리자 작업공간에서 미리보기를 클릭하여 컨테이너를 미리 보고 미리보기 페이지가 로드되는지 확인합니다. 다른 브라우저 탭에서 서버 컨테이너 URL의 경로로 이동합니다. 전송된 요청이 미리보기 페이지에 표시되면, 모든 항목이 제대로 설정된 것입니다.

여러 하위 도메인을 단일 태그 관리 서버에 매핑하고 각 하위 도메인에서 미리 보려면 관리 > 컨테이너 설정에서 서버 컨테이너 URL을 추가합니다. 여러 URL이 제공되는 경우 모든 URL 경로 (도메인 이름 뒤에 오는 정보 문자열)가 일치해야 합니다. 예를 들어, example.com/abc 및 example2.com/abc에서 미리 볼 수 있지만 example.com/abc 및 example2.com/def에서는 미리 볼 수 없습니다. 여러 URL이 추가된 경우 미리보기 버튼 옆에 미리 볼 URL을 선택할 수 있는 아이콘이 표시됩니다.

태그 관리 서버 버전 업데이트

gtm-cloud-image 이미지에는 Node.js 및 태그 관리 서버가 작동하는 데 필요한 라이브러리가 포함되어 있습니다. Docker 이미지는 보안 수정 및 새로운 기능을 반영하기 위해 주기적으로 업데이트됩니다. 최소한 메이저 버전이 출시될 때만이라도 태그 관리 서버를 업데이트하는 것이 좋습니다(예: 버전 1.x.x에서 2.x.x로 업그레이드).

Docker 이미지를 업데이트하는 방법은 다음과 같습니다.

gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable에서 현재 이미지 버전을 가져옵니다.
이전 배포와 동일한 설정으로 서버를 배포합니다.
단일 미리보기 서버와 클러스터의 태그 관리 서버를 모두 업데이트합니다.
이전 서버를 모두 종료합니다.

업데이트가 성공했는지 확인하는 방법은 다음과 같습니다.

서버 컨테이너에서 미리보기 버튼을 클릭하여 새 디버그 세션을 시작하고 별도의 탭에서 요청을 보냅니다.
요약에서 콘솔 탭을 선택하고 태그 관리 서버를 업데이트하라는 메시지가 없는지 확인합니다.

서버가 성공적으로 업데이트된 후에도 최대 하루 동안 태그 관리 서버를 업데이트하라는 메시지가 표시될 수 있습니다. 그러나 미리보기 페이지에는 태그 관리 서버 버전에 대한 최신 메시지가 표시됩니다.