CREATE GATEWAY

현재 스키마에 새 게이트웨이(gateway)를 만드는 명령이에요. 게이트웨이는 여러 서비스 엔드포인트에 걸쳐 트래픽 분할(traffic splitting) 또는 섀도 트래픽(shadow traffic)을 활성화해요.

출처: 문서

본문

현재 스키마에 새 게이트웨이를 만들어요. 게이트웨이는 여러 서비스 엔드포인트에 걸쳐 트래픽 분할 또는 섀도 트래픽을 활성화해요.

함께 보기: ALTER GATEWAY, DESCRIBE GATEWAY, DROP GATEWAY, SHOW GATEWAYS

구문 (Syntax)

CREATE [ OR REPLACE ] GATEWAY [ IF NOT EXISTS ] <name>
  FROM SPECIFICATION <specification_text>

필수 매개변수 (Required parameters)

name 게이트웨이의 식별자를 지정하는 문자열로, 게이트웨이가 만들어지는 스키마 안에서 고유해야 해요.

FROM SPECIFICATION 게이트웨이 사양(specification)을 인라인으로 지정해요. 사양은 트래픽 분할 또는 섀도 트래픽 구성을 정의해요.

트래픽 분할 게이트웨이 사양은 다음 형식을 사용해요.

spec:
  type: traffic_split
  split_type: custom
  targets:
  - type: endpoint
    value: <db>.<schema>.<service>!<endpoint>
    weight: <weight>
  - type: endpoint
    value: <db>.<schema>.<service>!<endpoint>
    weight: <weight>

섀도 트래픽 게이트웨이 사양은 다음 형식을 사용해요.

spec:
  type: shadow_traffic
  primary:
  - type: endpoint
    value: <db>.<schema>.<service>!<endpoint>
  shadow:
  - type: endpoint
    value: <db>.<schema>.<service>!<endpoint>
    weight: <weight>

사양 매개변수 (Specification parameters)

type 게이트웨이 구성 유형이에요. 지원되는 값:

traffic_split: 가중치에 따라 대상 엔드포인트들 사이에 요청을 라우팅해요.
shadow_traffic: 모든 요청을 하나의 기본(primary) 엔드포인트로 라우팅하고, 요청의 일정 비율을 하나 이상의 섀도 엔드포인트에 미러링해요.

split_type traffic_split 게이트웨이의 경우 고정 값 custom이에요. shadow_traffic 게이트웨이에는 이 매개변수를 지정하지 마세요.

targets traffic_split 게이트웨이의 경우, 트래픽을 라우팅할 대상 엔드포인트 목록이에요. 각 대상은 다음을 지정해야 해요.

type: 고정 값. 반드시 endpoint로 설정해야 해요.
value: db.schema.service!endpoint 형식의 정규화된 엔드포인트 이름. 각 대상 엔드포인트는 존재해야 해요.
weight: 이 엔드포인트의 트래픽 가중치로, 정수로 지정해요. 모든 가중치의 합은 100이 되어야 해요.

primary shadow_traffic 게이트웨이의 경우, 정확히 하나의 기본 엔드포인트를 포함하는 목록이에요. 기본 엔드포인트는 모든 요청을 받고 클라이언트에 응답을 반환해요.

기본 엔드포인트에는 weight를 지정하지 마세요.

shadow shadow_traffic 게이트웨이의 경우, 하나 이상의 섀도 엔드포인트 목록이에요. 각 섀도 엔드포인트는 weight로 지정된 비율의 요청 복사본을 받아요. 섀도 엔드포인트의 응답은 클라이언트에 반환되지 않아요.

각 섀도 대상은 트래픽 분할 대상과 동일한 type과 value 필드를 사용해요. weight를 0~100의 정수로 설정해요. 여러 섀도 대상의 가중치는 합이 100일 필요가 없어요.

참고: 게이트웨이당 최대 엔드포인트 수는 기본적으로 5개예요.

접근 제어 요구 사항 (Access control requirements)

이 작업을 실행하는 데 사용하는 역할(role)은 최소한 다음 권한을 가져야 해요.

권한 (Privilege)	객체 (Object)	비고
CREATE GATEWAY	Schema	스키마에 게이트웨이를 만드는 데 필요해요.
BIND SERVICE ENDPOINT	Account	서비스 엔드포인트를 게이트웨이에 바인딩하는 데 필요해요.
USAGE	Database	게이트웨이를 포함하는 데이터베이스에 필요해요.
USAGE	Schema	게이트웨이를 포함하는 스키마에 필요해요.
USAGE	Service endpoints	대상 서비스 엔드포인트에 필요해요. 접근을 제공하려면 서비스 역할에 `ALL_ENDPOINTS_USAGE`를 부여해요.

필요한 권한을 부여하려면 다음 명령을 사용해요.

-- Grant CREATE GATEWAY privilege in the schema
GRANT CREATE GATEWAY ON SCHEMA <schema_name> TO ROLE <role_name>;

-- Grant BIND SERVICE ENDPOINT privilege on the account
GRANT BIND SERVICE ENDPOINT ON ACCOUNT TO ROLE <role_name>;

-- Grant USAGE on target endpoints via service role
GRANT SERVICE ROLE <db_name>.<schema_name>.<service_name>!ALL_ENDPOINTS_USAGE TO ROLE <role_name>;

지정된 권한 집합으로 사용자 지정 역할을 만드는 방법은 사용자 지정 역할 만들기(Creating custom roles)를 참고해요. 보호 가능한 객체에 대해 SQL 작업을 수행하기 위한 역할과 권한 부여의 일반적인 내용은 접근 제어 개요(Overview of Access Control)를 참고해요.

사용 메모 (Usage notes)

메타데이터에 관해서는 다음 사항에 주의해요.

⚠️ 주의: 고객은 Snowflake 서비스를 사용할 때 (User 객체를 제외하고) 개인 데이터·민감 데이터·수출 통제 데이터·기타 규제 데이터를 메타데이터로 입력하지 않도록 해야 해요. 자세한 내용은 Snowflake의 메타데이터 필드를 참고해요.

예시 (Examples)

두 서비스 엔드포인트 사이에 트래픽을 분할하는 게이트웨이를 만들어요.

CREATE GATEWAY split_gateway
  FROM SPECIFICATION $$
spec:
  type: traffic_split
  split_type: custom
  targets:
  - type: endpoint
    value: db.schema.s2!ep1
    weight: 60
  - type: endpoint
    value: db.schema.s1!ep1
    weight: 40
$$;

새 트래픽 분할 구성으로 게이트웨이를 만들거나 교체해요.

CREATE OR REPLACE GATEWAY split_gateway
  FROM SPECIFICATION $$
spec:
  type: traffic_split
  split_type: custom
  targets:
  - type: endpoint
    value: db.schema.service1!endpoint1
    weight: 70
  - type: endpoint
    value: db.schema.service2!endpoint1
    weight: 30
$$;

모든 요청을 기본 엔드포인트로 보내고 요청의 10%를 섀도 엔드포인트로 미러링하는 섀도 트래픽 게이트웨이를 만들어요.

CREATE GATEWAY shadow_gateway
  FROM SPECIFICATION $$
spec:
  type: shadow_traffic
  primary:
  - type: endpoint
    value: db.schema.production_service!inference
  shadow:
  - type: endpoint
    value: db.schema.challenger_service!inference
    weight: 10
$$;

더 알아보기 (Learn more)

ALTER GATEWAY — 게이트웨이 수정
DROP GATEWAY — 게이트웨이 삭제
SHOW GATEWAYS — 게이트웨이 조회