1. 소개
이 문서에서는 WIF를 사용하여 AgentSpace에 액세스하도록 커스텀 도메인을 구성하기 위한 참조 아키텍처를 제공합니다. 사용자는 Agentspace 앱 생성 중에 할당된 Google 관리 URL 대신 맞춤 도메인을 사용할 수 있습니다. 이 Codelab에서는 nip.io 도메인을 사용하여 Agentspace Calendar 및 Drive 애플리케이션에 액세스하는 방법을 보여줍니다. nip.io는 모든 IP 주소에 와일드 카드 DNS를 제공하는 무료 오픈소스 서비스입니다. 기본적으로 자체 DNS 서버를 설정하거나 /etc/hosts 파일을 수정하지 않고도 특정 IP 주소로 변환되는 호스트 이름을 만들 수 있습니다.
자체 도메인을 사용하는 것이 좋지만, 이 튜토리얼에서는 데모 목적으로 nip.io를 사용합니다.
아래에 묘사된 배포 시나리오 (그림 1)에서 AgentSpace는 공개 Google 관리 URL을 통해 액세스되는 Calendar Application이 포함된 데이터 저장소를 게시했습니다.
그림 1
데이터 저장소와 후속 애플리케이션이 계속 증가하면 아래 배포 시나리오(그림 2)에 표시된 대로 공개 Google 관리 URL을 추가로 관리하게 되어 에이전트 공간 애플리케이션과 URL이 1:1로 매핑됩니다.
그림 2.
커스텀 도메인을 사용하면 다양한 AgentSpace 애플리케이션을 단일 사용자 지정 고객 도메인에 매핑할 수 있습니다. 이 기능을 사용하면 각 Agentspace 애플리케이션을 특정 URL 경로와 연결할 수 있어 아래 배포 시나리오(그림 3)에 표시된 대로 유연성이 향상됩니다. 예를 들어 고객 관리 도메인 agentspace.cosmopup.com은 경로 규칙으로 분류되며 각 경로 규칙은 특정 Agentspace 애플리케이션에 매핑됩니다. 예를 들면 다음과 같습니다.
- Workspace Drive의 Agentspace 애플리케이션에 매핑되는 agentspace.cosmopup.com/drive-app
- Sharepoint용 Agentspace 애플리케이션에 매핑되는 agentspace.cosmopup.com/sharepoint-app
URL 맵을 통해 구성된 외부 애플리케이션 부하 분산기의 호스트 및 경로 규칙은 커스텀 도메인을 Google 관리 URL에 매핑하는 로직을 제어합니다. 예시 agentspace.cosmopup.com/drive-app을 사용하여 다음 기능을 실행합니다.
- 커스텀 도메인 호스트 경로 agentspace.cosmopup.com/drive-app이 부하 분산기에 수신됨
- 고급 호스트 및 경로 규칙 일치에 대해 URL 맵이 구성됨
- 호스트 agentspace.cosmopup.com은 경로 일치 및 리디렉션이 가능합니다.
- 커스텀 도메인 호스트 경로 agentspace.cosmopup.com/drive-app에 UrlRedirect가 적용됩니다.
- pathRedirect는 Agentspace 경로입니다. /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
- hostRedirect는 Agentspace 호스트입니다(vertexaisearch.cloud.google.com).
- 커스텀 도메인 호스트 경로 agentspace.cosmopup.com/sharepoint-app에 UrlRedirect가 적용됩니다.
- pathRedirect는 Agentspace 경로입니다. /signin/locations/global/workforcePools/your-pool-name/providers/your-provider-name?continueUrl=https://vertexaisearch.cloud.google/home/cid/f190000-0000-4d0a-0000-d08df6e3bef6
- hostRedirect는 Agentspace 호스트입니다(auth.cloud.google).
- 백엔드 서비스로 라우팅되기 전에 리디렉션 작업이 실행됩니다.
그림 3
학습할 내용
- 전역 외부 애플리케이션 부하 분산기 만들기
- 커스텀 도메인을 Agentspace 애플리케이션으로 리디렉션하는 라우팅 만들기
- nip.io와 Cloud DNS를 통합하여 커스텀 도메인을 만드는 방법
- Agentspace 커스텀 도메인에 대한 액세스 권한을 확인하는 방법
필요한 항목
- 소유자 권한이 있는 Google Cloud 프로젝트
- 기존 Agentspace 애플리케이션 URL
- 자체 소유자 맞춤 도메인 (선택사항)
- 인증서 - 자체 서명 또는 Google 관리
2. 빌드할 항목
호스트 및 경로 리디렉션을 사용하여 Agentspace 애플리케이션의 맞춤 도메인 경로 일치를 사용 설정하기 위해 고급 트래픽 관리 기능이 있는 전역 외부 애플리케이션 부하 분산기를 설정합니다. 배포가 완료되면 다음 작업을 실행하여 Agentspace 애플리케이션에 대한 액세스를 검증합니다.
- 웹브라우저를 열고 커스텀 도메인과 지정된 경로로 이동하여 Agentspace 애플리케이션에 액세스합니다.
3. 네트워크 요구사항
아래는 네트워크 요구사항의 세부사항입니다.
구성요소 | 설명 |
VPC (agentspace-vpc) | 커스텀 모드 VPC |
인터넷 NEG | 에이전트 스페이스 Google 관리 FQDN (vertexaisearch.cloud.google.com)을 나타내는 FQDN으로 구성된 부하 분산기의 외부 백엔드를 정의하는 데 사용되는 리소스입니다. 인터넷 FQDN은 확인을 위해 VPC 내에서 DNS 조회를 실행합니다. |
백엔드 서비스 | 백엔드 서비스는 부하 분산기와 백엔드 리소스 간의 브리지 역할을 합니다. 튜토리얼에서 백엔드 서비스는 인터넷 NEG와 연결됩니다. |
인증서 | Google Cloud에서 애플리케이션 부하 분산기의 인증서를 구성하려면 인증서 관리자 서비스와 Google 관리형 또는 자체 관리형 SSL 인증서를 사용합니다. |
Cloud DNS | Cloud DNS 공개 영역은 외부 애플리케이션 부하 분산기 외부 IP를 nip.io (agentspace.externalip.nip.io)로 확인하는 데 사용됩니다. 또는 부하 분산기의 IP 주소로 구성된 맞춤 도메인과 A 레코드를 사용합니다. |
4. Codelab 토폴로지
5. 설정 및 요구사항
자습형 환경 설정
- Google Cloud Console에 로그인하여 새 프로젝트를 만들거나 기존 프로젝트를 재사용합니다. 아직 Gmail이나 Google Workspace 계정이 없는 경우 계정을 만들어야 합니다.
- 프로젝트 이름은 이 프로젝트 참가자의 표시 이름입니다. 이는 Google API에서 사용하지 않는 문자열이며 언제든지 업데이트할 수 있습니다.
- 프로젝트 ID는 모든 Google Cloud 프로젝트에서 고유하며, 변경할 수 없습니다(설정된 후에는 변경할 수 없음). Cloud 콘솔은 고유한 문자열을 자동으로 생성합니다. 일반적으로는 신경 쓰지 않아도 됩니다. 대부분의 Codelab에서는 프로젝트 ID (일반적으로
PROJECT_ID로 식별됨)를 참조해야 합니다. 생성된 ID가 마음에 들지 않으면 다른 임의 ID를 생성할 수 있습니다. 또는 직접 시도해 보고 사용 가능한지 확인할 수도 있습니다. 이 단계 이후에는 변경할 수 없으며 프로젝트 기간 동안 유지됩니다. - 참고로 세 번째 값은 일부 API에서 사용하는 프로젝트 번호입니다. 이 세 가지 값에 대한 자세한 내용은 문서를 참고하세요.
- 다음으로 Cloud 리소스/API를 사용하려면 Cloud 콘솔에서 결제를 사용 설정해야 합니다. 이 Codelab 실행에는 많은 비용이 들지 않습니다. 이 튜토리얼이 끝난 후에 요금이 청구되지 않도록 리소스를 종료하려면 만든 리소스 또는 프로젝트를 삭제하면 됩니다. Google Cloud 신규 사용자는 300달러(USD) 상당의 무료 체험판 프로그램에 참여할 수 있습니다.
Cloud Shell 시작
Google Cloud를 노트북에서 원격으로 실행할 수 있지만, 이 Codelab에서는 Cloud에서 실행되는 명령줄 환경인 Google Cloud Shell을 사용합니다.
Google Cloud Console의 오른쪽 상단 툴바에 있는 Cloud Shell 아이콘을 클릭합니다.
환경을 프로비저닝하고 연결하는 데 몇 분 정도 소요됩니다. 완료되면 다음과 같이 표시됩니다.
가상 머신에는 필요한 개발 도구가 모두 들어있습니다. 영구적인 5GB 홈 디렉터리를 제공하고 Google Cloud에서 실행되므로 네트워크 성능과 인증이 크게 개선됩니다. 이 Codelab의 모든 작업은 브라우저 내에서 수행할 수 있습니다. 아무것도 설치할 필요가 없습니다.
6. 시작하기 전에
API 사용 설정
Cloud Shell 내에 프로젝트 ID가 설정되어 있는지 확인합니다.
gcloud config list project
gcloud config set project [YOUR-PROJECT-ID]
project=[YOUR-PROJECT-ID]
region=[YOUR-REGION]
echo $project
echo $region
필요한 모든 서비스를 사용 설정합니다.
gcloud services enable compute.googleapis.com
gcloud services enable dns.googleapis.com
7. 부하 분산기 구성요소 설정
부하 분산기의 외부 IP 주소 예약
Cloud Shell에서 부하 분산기의 외부 IP 주소를 예약합니다.
gcloud compute addresses create external-ip \
--network-tier=PREMIUM \
--ip-version=IPV4 \
--global
Cloud Shell에서 예약된 IP 주소를 확인합니다.
gcloud compute addresses describe external-ip \
--global | grep -i address:
출력 예시:
user@cloudshell$ gcloud compute addresses describe external-ip \
--global | grep -i address:
address: 34.54.158.206
인터넷 NEG 설정
인터넷 NEG를 만들고 –network-endpoint-type을 internet-fqdn-port (호스트 이름과 외부 백엔드에 연결할 수 있는 포트)로 설정합니다. Agentspace를 확인하기 위해 FQDN vertexaisearch.cloud.google.com 및 포트 443이 사용됩니다.
gcloud compute network-endpoint-groups create agentspace-ineg \
--network-endpoint-type="internet-fqdn-port" \
--global
gcloud compute network-endpoint-groups update agentspace-ineg \
--add-endpoint="fqdn=vertexaisearch.cloud.google.com,port=443" \
--global
부하 분산기 만들기
Cloud Shell 내에서 다음을 실행합니다.
gcloud compute backend-services create agentspace-ineg-bes \
--load-balancing-scheme=EXTERNAL_MANAGED \
--protocol=HTTPS \
--global
gcloud compute backend-services add-backend agentspace-ineg-bes \
--network-endpoint-group=agentspace-ineg \
--global-network-endpoint-group \
--global
인증서 만들기
이제 인터넷 NEG와 백엔드 서비스를 만들었습니다. 다음 섹션에서는 HTTPS 대상 프록시에서 사용할 인증서 리소스를 만들어야 합니다. Google 관리형 SSL 인증서 또는 자체 관리형 SSL 인증서를 사용하여 SSL 인증서 리소스를 만들 수 있습니다. Google Cloud는 이러한 인증서를 자동으로 가져오고 관리하며 갱신하므로 Google 관리형 인증서를 사용하는 것이 좋습니다.
이 튜토리얼에서 사용되는 전역 외부 애플리케이션 부하 분산기의 지원되는 인증서에 대해 자세히 알아보려면 다음을 참고하세요.
SSL 인증서 개요 | 부하 분산 | Google Cloud
다음 섹션에서는 일반 이름과 정규화된 도메인 이름 (agentspace.YOUR-EXTERNAL-IP.nip.io)의 매핑이 이전에 생성된 부하 분산기의 외부 IP 주소에 해당하는 자체 서명된 인증서를 만듭니다 (Google 관리 인증서를 대신 사용할 수 있음). 아래 예를 참고하세요.
일반 이름: agentspace.34.54.158.206.nip.io
Cloud Shell 내에서 비공개 키 만들기
openssl genrsa -out private-key-file.pem 2048
Cloud Shell 내에서 pem 파일을 생성하는 데 사용되는 config.txt 파일을 만듭니다. 아래 구성에서 DNS 1 항목 agentspace.YOUR-EXTERNAL-IP.nip.io(예: agentspace.34.54.158.206.nip.io)에 정규화된 도메인 이름을 지정합니다.
cat <<'EOF' >config.txt
[req]
default_bits = 2048
req_extensions = extension_requirements
distinguished_name = dn_requirements
[extension_requirements]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName = @sans_list
[dn_requirements]
countryName = Country Name (2 letter code)
stateOrProvinceName = State or Province Name (full name)
localityName = Locality Name (eg, city)
organizationName = Organization Name (eg, company)
organizationalUnitName = Organizational Unit Name (eg, section)
commonName = Common Name (e.g. server FQDN or YOUR name)
emailAddress = Email Address
[sans_list]
DNS.1 = agentspace.YOUR-EXTERNAL-IP.nip.io
EOF
Cloud Shell에서 config.txt와 private-key-file.pem이 생성되었는지 확인합니다.
user@cloudshell:$ ls
config.txt private-key-file.pem
Cloud Shell 내에서 다음을 실행합니다.
sudo openssl req -new -key private-key-file.pem \
-out csr.pem \
-config config.txt
예:
user@cloudshell:$ sudo openssl req -new -key private-key-file.pem \
-out csr.pem \
-config config.txt
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) []:
State or Province Name (full name) []:
Locality Name (eg, city) []:
Organization Name (eg, company) []:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name)[]:agentspace.34.54.158.206.nip.io
Email Address []:
Cloud Shell 내에서 필요한 인증서 서명 pem이 생성되었는지 확인합니다.
user@cloudshell:$ ls
config.txt csr.pem private-key-file.pem
Cloud Shell 내에서 인증서를 생성합니다.
sudo openssl x509 -req \
-signkey private-key-file.pem \
-in csr.pem \
-out cert.cert \
-extfile config.txt \
-extensions extension_requirements \
-days 365
명령어 결과
user@cloudshell:$ sudo openssl x509 -req \
-signkey private-key-file.pem \
-in csr.pem \
-out cert.cert \
-extfile config.txt \
-extensions extension_requirements \
-days 365
Certificate request self-signature ok
subject=CN = agentspace.34.54.158.206.nip.io
Cloud Shell 내에서 cert.cert 파일이 생성되었는지 확인합니다.
user@cloudshell:$ ls
cert.cert config.txt csr.pem private-key-file.pem
외부 부하 분산기와 연결할 인증서 리소스를 만듭니다. 인증서 및 비공개 키 매개변수를 특정 파일 이름으로 바꿉니다.
Cloud Shell에서 다음을 실행합니다.
gcloud compute ssl-certificates create agentspace-self-signed-cert \
--certificate=cert.cert \
--private-key=private-key-file.pem \
--global
Cloud Shell에서 다음을 실행합니다.
gcloud compute url-maps create agentspace-lb \
--default-service=agentspace-ineg-bes \
--global
Cloud Shell에서 다음을 실행합니다.
gcloud compute target-https-proxies create https-proxy \
--ssl-certificates=agentspace-self-signed-cert \
--url-map=agentspace-lb \
--global
Cloud Shell에서 다음을 실행합니다.
gcloud compute forwarding-rules create agentspace-fr \
--load-balancing-scheme=EXTERNAL_MANAGED \
--network-tier=PREMIUM \
--address=external-ip \
--target-https-proxy=https-proxy \
--global \
--ports=443
8. 공개 DNS 영역 만들기
다음 섹션에서는 nip.io가 외부 부하 분산기 IP 주소에 대해 확인하는 데 사용되는 공개 DNS 영역을 만듭니다.
Cloud Shell에서 다음을 실행하여 외부 부하 분산기 IP 주소의 변수를 만듭니다.
externalip=<YOUR-EXTERNAL-IP>
echo $externalip
Cloud Shell에서 다음을 실행합니다.
gcloud dns --project=$project managed-zones create agentspace-dns --description="Agentspace public dns" --dns-name="$externalip.nip.io." --visibility="public"
Cloud Shell에서 다음을 실행합니다.
gcloud dns --project=$project record-sets create agentspace.$externalip.nip.io. --zone="agentspace-dns" --type="A" --ttl="300" --rrdatas="$externalip"
9. Agentspace 애플리케이션 URL 식별
다음 절차에서는 각 애플리케이션의 Agentspace에 매핑된 Google에서 생성한 Google 관리 Agentspace 공개 URL을 식별합니다. URL 출력은 참조 아키텍처를 기반으로 한 예이므로 URL이 정확해야 합니다.
애플리케이션별로 웹 앱 링크를 저장해야 합니다.
Drive 애플리케이션
Agentspace 웹 URL:
https://vertexaisearch.cloud.google.com/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
Sharepoint 애플리케이션
Agentspace 웹 URL: https://auth.cloud.google/signin/locations/global/workforcePools/your-pool-name/providers/your-provider-name?continueUrl=https://vertexaisearch.cloud.google/home/cid/f190000-0000-4d0a-0000-d08df6e3bef6
10. 고급 호스트 및 경로 규칙 만들기
다음 섹션에서는 클라우드 콘솔을 사용하여 호스트 및 경로 규칙을 정의하는 옵션을 사용 설정하도록 부하 분산기 라우팅 규칙을 업데이트합니다. 아래 표에는 환경에 따라 업데이트되는 맞춤 값이 위에서 아래 순서로 나와 있습니다.
커스텀 값 | 튜토리얼 기반 예 | |
호스트 | agentspace.YOUR-EXTERNAL-IP.nip.io | agentspace.34.54.158.206.nip.io |
defaultService | projects/<projectid>/global/backendServices/agentspace-ineg-bes | projects/your-project-id/global/backendServices/agentspace-ineg-bes |
prefixMatch | /<에이전트 스페이스 앱#1 이름> | /drive-app |
pathRedirect | /<Agentspace URL path of app#1> | /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd |
hostRedirect | vertexaisearch.cloud.google.com | vertexaisearch.cloud.google.com |
prefixMatch | /<두 번째 Agentspace 앱 이름> | /sharepoint-app |
pathRedirect | /<Agentspace URL path of app#2> | //signin/locations/global/workforcePools/your-pool-name/providers/your-provider-name?continueUrl=https://vertexaisearch.cloud.google/home/cid/f190000-0000-4d0a-0000-d08df6e3bef6 |
hostRedirect | auth.cloud.google | vertexaisearch.cloud.google.com |
다음으로 이동하여 호스트 및 경로 규칙에 액세스합니다.
부하 분산 → agentspace-lb → 수정 선택
라우팅 규칙 → 고급 호스트 및 경로 규칙을 선택합니다.
호스트 및 경로 규칙 추가 선택
이제 새 호스트 및 경로 규칙을 만들 수 있습니다. 호스트 섹션에 agentspace.YOUR-EXTERNAL-IP.nip.io 또는 커스텀 도메인을 삽입합니다.
경로 일치자 필드 (일치, 작업, 서비스)에서 아래 콘텐츠를 환경 구성으로 업데이트한 다음 업데이트를 선택합니다.
defaultService: projects/<projectid>/global/backendServices/agentspace-ineg-bes
name: matcher1
routeRules:
- matchRules:
- prefixMatch: /<name of Agentspace app#1>
priority: 1
urlRedirect:
pathRedirect: /<Agentspace URL path of app#1>
hostRedirect: vertexaisearch.cloud.google.com
redirectResponseCode: FOUND
- matchRules:
- prefixMatch: /<name of Agentspace app#2>
priority: 2
urlRedirect:
pathRedirect: /<Agentspace URL path of app#2>
hostRedirect: auth.cloud.google
redirectResponseCode: FOUND
스크린샷 예:
11. 유효성 검사
배포가 완료되었습니다. 웹브라우저 또는 터미널을 통해 커스텀 도메인을 사용하여 Agentspace 애플리케이션에 액세스할 수 있습니다. agentspace.YOUR-EXTERNAL-IP.nip.io/path(예: agentspace.34.54.158.206.nip.io)를 지정하세요. 아래 예시를 참고하세요.
Agentspace 애플리케이션: drive-app
경로: agentspace.34.54.158.206.nip.io/drive-app
Agentspace 애플리케이션: sharepoint-app
경로: agentspace.34.54.158.206.nip.io/sharepoint-app
12. 삭제
OAuth 사용자 인증 정보를 삭제하려면 다음 단계를 따르세요.
API 및 서비스 → 사용자 인증 정보로 이동합니다.
OAuth 2.0 클라이언트 ID에서 사용자 인증 정보를 선택한 다음 삭제합니다.
단일 Cloud Shell 터미널에서 실습 구성요소를 삭제합니다.
gcloud compute forwarding-rules delete agentspace-fr --global -q
gcloud compute target-https-proxies delete https-proxy --global -q
gcloud compute url-maps delete agentspace-lb --global -q
cloud compute ssl-certificates delete agentspace-self-signed-cert --global -q
gcloud compute backend-services delete agentspace-ineg-bes --global -q
gcloud compute network-endpoint-groups delete agentspace-ineg --global -q
gcloud dns --project=$projectid record-sets delete agentspace.$externalip.nip.io --zone="agentspace-dns" --type="A"
gcloud dns --project=$projectid managed-zones delete agentspace-dns
gcloud compute addresses delete external-ip --global -q
gcloud compute networks delete agentspace-vpc -q
13. 축하합니다
수고하셨습니다. 고급 트래픽 관리가 적용된 외부 애플리케이션 부하 분산기를 사용하여 커스텀 도메인을 통해 Agentspace에 대한 연결을 구성하고 검증했습니다.
부하 분산기 인프라를 만들고, 맞춤 도메인을 사용하여 Agentspace에 연결할 수 있는 호스트 및 경로 리디렉션을 사용 설정하는 인터넷 NEG, Cloud DNS, 고급 트래픽 관리를 만드는 방법을 알아봤습니다.
Cosmopup은 Codelab이 멋지다고 생각합니다.
