서비스 스플리터 구성 항목 참조

서비스 스플리터 구성 항목 참조 (Service Splitter Configuration Entry Reference)

이 참조 페이지는 서비스 스플리터 구성 항목의 구조와 내용을 설명해요. 서비스 스플리터를 구성하고 적용해 서비스에 대한 수신 트래픽 요청의 일정 비율을 하나 이상의 특정 서비스 인스턴스로 리디렉션할 수 있어요.

출처: 문서

본문

구성 모델 (Configuration model)

다음 목록은 서비스 스플리터 구성 항목의 필드 계층, 언어별 데이터 유형 및 요구 사항을 설명해요. 기본값을 포함한 추가 세부 정보를 보려면 속성 이름을 클릭해요.

HCL 및 JSON:

Kind: string | required
Name: string | required
Namespace: string \n\nEnterprise
Partition: string \n\nEnterprise
Meta: map
Splits: map | required
- Weight: number | required
- Service: string | required
- ServiceSubset: string
- Namespace: string \n\nEnterprise
- Partition: string \n\nEnterprise
- RequestHeaders: map
  - Add: map
  - Set: map
  - Remove: map
- ResponseHeaders: map
  - Add: map
  - Set: map
  - Remove: map

YAML:

apiVersion: string | required
kind: string | required
metadata: object | required
- name: string | required
- namespace: string | optional \n\nEnterprise
spec: object | required
- splits: list | required
  - weight: float32 | required
  - service: string | required
  - serviceSubset: string
  - namespace: string \n\nEnterprise
  - partition: string \n\nEnterprise
  - requestHeaders: HTTPHeaderModifiers
    - add: map
    - set: map
    - remove: map
  - responseHeaders: HTTPHeaderModifiers
    - add: map
    - set: map
    - remove: map

전체 구성 (Complete configuration)

모든 필드가 정의되면 서비스 스플리터 구성 항목은 다음 형식을 가져요.

HCL:

Kind      = "service-splitter"           ## string  | required
Name      = "config-entry-name"          ## string  | required
Namespace = "main"                       ## string
Partition = "partition"                  ## string 
Meta = {                                 ## map
  key = "value"
}
Splits = [                               ## list    | required
  {                                      ## map
    Weight        = 90                   ## number  | required
    Service       = "service"            ## string
    ServiceSubset = "v1"                 ## string
    Namespace     = "target-namespace"   ## string
    Partition     = "target-partition"   ## string
    RequestHeaders = {                   ## map
      Set = {
        "X-Web-Version" : "from-v1"
      }
    }
    ResponseHeaders = {                  ## map
      Set = {
        "X-Web-Version" : "to-v1"
      }
    }
  },
  {
    Weight        = 10
    Service       = "service"
    ServiceSubset = "v2"
    Namespace     = "target-namespace"
    Partition     = "target-partition"
    RequestHeaders = {
      Set = {
        "X-Web-Version" : "from-v2"
      }
    }
    ResponseHeaders = {
      Set = {
        "X-Web-Version" : "to-v2"
      }
    }
  }
]

JSON:

{
  "Kind" : "service-splitter",           ## string  | required
  "Name" : "config-entry-name",          ## string  | required
  "Namespace" : "main",                  ## string
  "Partition" : "partition",             ## string 
  "Meta" : {                             ## map
    "_key_" : "_value_"            
  },
  "Splits" : [                           ## list    | required
    {                                    ## map     
      "Weight" : 90,                     ## number  | required
      "Service" : "service",             ## string     
      "ServiceSubset" : "v1",            ## string
      "Namespace" : "target-namespace",  ## string
      "Partition" : "target-partition",  ## string
      "RequestHeaders" : {               ## map
        "Set" : {
          "X-Web-Version": "from-v1"
          }
      },
      "ResponseHeaders" : {              ## map
        "Set" : {
          "X-Web-Version": "to-v1"
          }
      }
    },
    {
      "Weight" : 10,            
      "Service" : "service",    
      "ServiceSubset" : "v2",          
      "Namespace" : "target-namespace",  
      "Partition" : "target-partition",  
      "RequestHeaders" : {
        "Set" : {
          "X-Web-Version": "from-v2"
          }
      },
      "ResponseHeaders" : {
        "Set" : {
          "X-Web-Version": "to-v2"
        }
      }
    }
  ]
}

YAML:

apiVersion: consul.hashicorp.com/v1alpha1         # string | required
kind: ServiceSplitter                             # string | required
metadata:                                         # object | required
  name: config-entry-name                         # string | required
  namespace: main                                 # string
spec:
  splits:                                         # list
    - weight: 90                                  # floating point | required
      service: service                            # string 
      serviceSubset: v1                           # string 
      namespace: target-namespace                 # string 
      partition: target-partition                 # string 
      requestHeaders:  
        set:
          x-web-version: from-v1                  # string 
      responseHeaders:
        set:
          x-web-version: to-v1                    # string 
    - weight: 10
      service: service
      serviceSubset: v2
      namespace: target-namespace
      partition: target-partition
      requestHeaders:
        set:
          x-web-version: from-v2
      responseHeaders:
        set:
          x-web-version: to-v2

사양 (Specification)

이 섹션은 서비스 스플리터 구성 항목에서 구성할 수 있는 필드에 대한 세부 정보를 제공해요.

HCL:

`Kind`

구현할 구성 항목의 유형을 지정해요.

값 (Values)

기본값: 없음
이 필드는 필수예요.
데이터 유형: service-splitter로 설정해야 하는 문자열 값.

`Name`

구성 항목의 이름을 지정해요. 이름은 특정 클러스터에 구성 항목을 적용하는 것 같은 Consul 작업을 수행할 때 구성 항목을 참조하는 데 사용할 수 있는 메타데이터예요.

값 (Values)

기본값: 항목을 Consul 서버에 기록한 후 노드의 이름을 기본값으로 사용해요.
이 필드는 필수예요.
데이터 유형: String

`Namespace`

Enterprise

구성 항목을 적용할 네임스페이스를 지정해요.

값 (Values)

기본값: 없음
데이터 유형: String

`Partition`

Enterprise

구성 항목을 적용할 admin partition을 지정해요.

값 (Values)

기본값: Default
데이터 유형: String

`Meta`

KV 저장소에 추가할 키-값 쌍을 지정해요.

값 (Values)

기본값: none
데이터 유형: 하나 이상의 키-값 쌍의 맵
- keys: String
- values: String, integer 또는 float

`Splits`

트래픽 분할 중 서비스 인스턴스 집합에 보낼 트래픽 양을 정의해요.

값 (Values)

기본값: 없음
이 필드는 필수예요.
데이터 유형: 다음 필드를 포함할 수 있는 객체 목록:
- Weight: 서비스 인스턴스 집합에 대한 가중치의 합은 100이 되어야 해요.
- Service: 이 필드는 필수예요.
- ServiceSubset
- Namespace
- Partition
- RequestHeaders
- ResponseHeaders

`Splits[].Weight`

Service 필드에 지정된 서비스 인스턴스 집합으로 보내는 트래픽의 백분율을 지정해요. 각 가중치는 0과 100 사이의 부동 정수여야 해요. 나타낼 수 있는 가장 작은 값은 .01이에요. 모든 분할의 가중치 합은 100이 되어야 해요.

값 (Values)

기본값: null
이 필드는 필수예요.
데이터 유형: .01에서 100 사이의 부동 숫자.

`Splits[].Service`

해석할 서비스의 이름을 지정해요.

값 (Values)

기본값: Name 필드의 값을 상속해요.
데이터 유형: String

`Splits[].ServiceSubset`

해석할 서비스의 일부 하위 집합을 지정해요. 서비스 하위 집합은 데이터 센터 내의 검색 가능한 서비스 인스턴스의 특정 하위 집합에 이름을 할당해요(예: version2 또는 canary). 모든 서비스에는 모든 정상 인스턴스를 반환하는 이름 없는 기본 하위 집합이 있어요.

service resolver 구성 항목에서 서비스 하위 집합을 정의할 수 있으며, 다른 구성 항목 전반에서 이름으로 참조돼요. 이 필드는 service resolver 구성 항목의 기본 하위 집합 값을 재정의해요.

값 (Values)

기본값: 비어 있으면 split은 기본 하위 집합을 사용해요.
데이터 유형: String

`Splits[].Namespace`

Enterprise

서비스를 해석할 때 FQDN에 사용할 네임스페이스를 지정해요.

값 (Values)

기본값: 구성 항목의 최상위에서 Namespace 값을 상속해요.
데이터 유형: String

`Splits[].Partition`

Enterprise

서비스를 해석할 때 FQDN에 사용할 admin partition을 지정해요.

값 (Values)

기본값: 기본적으로 service-splitter는 최상위 구성 항목에 지정된 admin partition을 사용해요.
데이터 유형: String

`Splits[].RequestHeaders`

서비스 분할로 라우팅된 요청에 적용되는 HTTP 전용 헤더 수정 규칙 집합을 지정해요. 리스너 프로토콜이 tcp로 설정된 경우 요청 헤더를 구성할 수 없어요. 예시 구성은 Set HTTP Headers를 참고해요.

값 (Values)

기본값: 없음
값: 헤더 수정 규칙을 정의하는 하나 이상의 필드를 포함하는 객체
- Add: 하나 이상의 키-값 쌍의 맵
- Set: 하나 이상의 키-값 쌍의 맵
- Remove: 하나 이상의 키-값 쌍의 맵

다음 표는 요청 헤더 값 구성 방법을 설명해요:

규칙	설명	유형
`Add`	헤더에 추가할 키-값 쌍 집합을 정의해요. 키로 헤더 이름을 사용해요. 헤더 이름은 대소문자를 구분하지 않아요. 같은 이름의 헤더 값이 이미 있으면 값이 추가되고 Consul은 두 헤더를 모두 적용해요. 변수 자리 표시자를 사용할 수 있어요.	맵 of strings
`Set`	요청 헤더에 추가하거나 기존 헤더 값을 대체할 키-값 쌍 집합을 정의해요. 키로 헤더 이름을 사용해요. 헤더 이름은 대소문자를 구분하지 않아요. 같은 이름의 헤더 값이 이미 있으면 Consul은 헤더 값을 대체해요. 변수 자리 표시자를 사용할 수 있어요.	맵 of strings
`Remove`	제거할 헤더 목록을 정의해요. Consul은 정확히 일치하는 헤더만 제거해요. 헤더 이름은 대소문자를 구분하지 않아요.	list of strings

변수 자리 표시자 사용 (Use variable placeholders)

Add 및 Set의 경우 서비스가 프록시로 Envoy를 사용하도록 구성된 경우 값에 동적 메타데이터를 값으로 보간하는 변수가 포함될 수 있어요. 예를 들어 구성 항목에서 %DOWNSTREAM_REMOTE_ADDRESS% 변수를 사용하면 분할이 발생할 때 생성되는 값을 전달할 수 있어요.

`Splits[].ResponseHeaders`

서비스 분할로 라우팅된 응답에 적용되는 HTTP 전용 헤더 수정 규칙 집합을 지정해요. 리스너 프로토콜이 tcp로 설정된 경우 요청 헤더를 구성할 수 없어요. 예시 구성은 Set HTTP Headers를 참고해요.

값 (Values)

기본값: 없음
값: 헤더 수정 규칙을 정의하는 하나 이상의 필드를 포함하는 객체
- Add: 하나 이상의 문자열 키-값 쌍의 맵
- Set: 하나 이상의 문자열 키-값 쌍의 맵
- Remove: 하나 이상의 문자열 키-값 쌍의 맵

다음 표는 응답 헤더 값 구성 방법을 설명해요:

규칙	설명	유형
`Add`	헤더에 추가할 키-값 쌍 집합을 정의해요. 키로 헤더 이름을 사용해요. 헤더 이름은 대소문자를 구분하지 않아요. 같은 이름의 헤더 값이 이미 있으면 값이 추가되고 Consul은 두 헤더를 모두 적용해요. 변수 자리 표시자를 사용할 수 있어요.	맵 of strings
`Set`	요청 헤더에 추가하거나 기존 헤더 값을 대체할 키-값 쌍 집합을 정의해요. 키로 헤더 이름을 사용해요. 헤더 이름은 대소문자를 구분하지 않아요. 같은 이름의 헤더 값이 이미 있으면 Consul은 헤더 값을 대체해요. 변수 자리 표시자를 사용할 수 있어요.	맵 of strings
`Remove`	제거할 헤더 목록을 정의해요. Consul은 정확히 일치하는 헤더만 제거해요. 헤더 이름은 대소문자를 구분하지 않아요.	list of strings

변수 자리 표시자 사용 (Use variable placeholders)

YAML:

`apiVersion`

구성 항목을 Kubernetes 구성에 매핑하는 Consul API 버전을 지정하는 Kubernetes 전용 매개변수. 값은 consul.hashicorp.com/v1alpha1이어야 해요.

`kind`

구현할 구성 항목의 유형을 지정해요.

값 (Values)

기본값: 없음
이 필드는 필수예요.
데이터 유형: serviceSplitter로 설정해야 하는 문자열 값.

`metadata.name`

값 (Values)

기본값: 호스트 노드에서 이름 상속
이 필드는 필수예요.
데이터 유형: String

`metadata.namespace`

Enterprise

서비스를 해석하는 데 사용할 Consul 네임스페이스를 지정해요. Consul 네임스페이스를 Kubernetes 네임스페이스에 다양한 방식으로 매핑할 수 있어요. 추가 정보는 Custom Resource Definitions (CRDs) for Consul on Kubernetes를 참고해요.

값 (Values)

기본값: 없음
데이터 유형: String

`spec`

서비스 스플리터 pod에 대한 모든 구성을 포함하는 Kubernetes 전용 필드.

값 (Values)

기본값: none
이 필드는 필수예요.
데이터 유형: spec.splits 구성을 포함하는 객체

`spec.meta`

KV 저장소에 추가할 키-값 쌍을 지정해요.

값 (Values)

기본값: none
데이터 유형: 하나 이상의 키-값 쌍의 맵
- keys: String
- values: String, integer 또는 float

`spec.splits`

트래픽 분할 중 서비스 인스턴스 집합에 보낼 트래픽 양을 정의해요.

값 (Values)

기본값: 없음
이 필드는 필수예요.
데이터 유형: 다음 필드를 포함할 수 있는 객체 목록:
- weight: 서비스 인스턴스 집합에 대한 가중치의 합. 정의된 총 값은 100이 되어야 해요.
- service: 이 필드는 필수예요.
- serviceSubset
- namespace
- partition
- requestHeaders
- responseHeaders

`spec.splits[].weight`

spec.splits.service 필드에 지정된 서비스 인스턴스 집합으로 보내는 트래픽의 백분율을 지정해요. 각 가중치는 0과 100 사이의 부동 정수여야 해요. 나타낼 수 있는 가장 작은 값은 .01이에요. 모든 분할의 가중치 합은 100이 되어야 해요.

값 (Values)

기본값: null
이 필드는 필수예요.
데이터 유형: .01에서 100 사이의 부동 정수

`spec.splits[].service`

해석할 서비스의 이름을 지정해요.

값 (Values)

기본값: 구성 항목 meta.name 필드와 일치하는 서비스.
데이터 유형: String

`spec.splits[].serviceSubset`

해석할 서비스의 일부 하위 집합을 지정해요. 이 필드는 DefaultSubset를 재정의해요.

값 (Values)

기본값: 기본 하위 집합의 이름을 상속해요.
데이터 유형: String

`spec.splits[].namespace`

Enterprise

서비스를 해석할 때 사용할 네임스페이스를 지정해요.

값 (Values)

기본값: 최상위 구성 항목에 지정된 네임스페이스.
데이터 유형: String

`spec.splits[].partition`

Enterprise

서비스를 해석할 때 FQDN에 사용할 admin partition을 지정해요.

값 (Values)

기본값: default
데이터 유형: String

`spec.splits[].requestHeaders`

값 (Values)

기본값: 없음
값: 헤더 수정 규칙을 정의하는 하나 이상의 필드를 포함하는 객체
- add: 하나 이상의 키-값 쌍의 맵
- set: 하나 이상의 키-값 쌍의 맵
- remove: 하나 이상의 키-값 쌍의 맵

다음 표는 요청 헤더 값 구성 방법을 설명해요:

규칙	설명	유형
`add`	헤더에 추가할 키-값 쌍 집합을 정의해요. 키로 헤더 이름을 사용해요. 헤더 이름은 대소문자를 구분하지 않아요. 같은 이름의 헤더 값이 이미 있으면 값이 추가되고 Consul은 두 헤더를 모두 적용해요. 변수 자리 표시자를 사용할 수 있어요.	맵 of strings
`set`	요청 헤더에 추가하거나 기존 헤더 값을 대체할 키-값 쌍 집합을 정의해요. 키로 헤더 이름을 사용해요. 헤더 이름은 대소문자를 구분하지 않아요. 같은 이름의 헤더 값이 이미 있으면 Consul은 헤더 값을 대체해요. 변수 자리 표시자를 사용할 수 있어요.	맵 of strings
`remove`	제거할 헤더 목록을 정의해요. Consul은 정확히 일치하는 헤더만 제거해요. 헤더 이름은 대소문자를 구분하지 않아요.	list of strings

변수 자리 표시자 사용 (Use variable placeholders)

add 및 set의 경우 서비스가 프록시로 Envoy를 사용하도록 구성된 경우 값에 동적 메타데이터를 값으로 보간하는 변수가 포함될 수 있어요. 예를 들어 구성 항목에서 %DOWNSTREAM_REMOTE_ADDRESS% 변수를 사용하면 분할이 발생할 때 생성되는 값을 전달할 수 있어요.

`spec.splits[].responseHeaders`

값 (Values)

기본값: 없음
값: 헤더 수정 규칙을 정의하는 하나 이상의 필드를 포함하는 객체
- add: 하나 이상의 문자열 키-값 쌍의 맵
- set: 하나 이상의 문자열 키-값 쌍의 맵
- remove: 하나 이상의 문자열 키-값 쌍의 맵

다음 표는 응답 헤더 값 구성 방법을 설명해요:

규칙	설명	유형
`add`	헤더에 추가할 키-값 쌍 집합을 정의해요. 키로 헤더 이름을 사용해요. 헤더 이름은 대소문자를 구분하지 않아요. 같은 이름의 헤더 값이 이미 있으면 값이 추가되고 Consul은 두 헤더를 모두 적용해요. 변수 자리 표시자를 사용할 수 있어요.	맵 of strings
`set`	요청 헤더에 추가하거나 기존 헤더 값을 대체할 키-값 쌍 집합을 정의해요. 키로 헤더 이름을 사용해요. 헤더 이름은 대소문자를 구분하지 않아요. 같은 이름의 헤더 값이 이미 있으면 Consul은 헤더 값을 대체해요. 변수 자리 표시자를 사용할 수 있어요.	맵 of strings
`remove`	제거할 헤더 목록을 정의해요. Consul은 정확히 일치하는 헤더만 제거해요. 헤더 이름은 대소문자를 구분하지 않아요.	list of strings

변수 자리 표시자 사용 (Use variable placeholders)

예시 (Examples)

다음 예시는 특정 사용 사례에 대한 일반적인 서비스 스플리터 구성 패턴을 보여줘요.

동일 서비스의 두 하위 집합 (Two subsets of same service)

동일 서비스의 두 하위 집합 간에 트래픽을 분할:

HCL:

Kind = "service-splitter"
Name = "web"
Splits = [
  {
    Weight        = 90
    ServiceSubset = "v1"
  },
  {
    Weight        = 10
    ServiceSubset = "v2"
  },
]

JSON:

{
  "Kind": "service-splitter",
  "Name": "web",
  "Splits": [
    {
      "Weight": 90,
      "ServiceSubset": "v1"
    },
    {
      "Weight": 10,
      "ServiceSubset": "v2"
    }
  ]
}

YAML:

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceSplitter
metadata:
  name: web
spec:
  splits:
    - weight: 90
      serviceSubset: v1
    - weight: 10
      serviceSubset: v2

두 개의 다른 서비스 (Two different services)

두 서비스 간에 트래픽 분할:

HCL:

Kind = "service-splitter"
Name = "web"
Splits = [
  {
    Weight  = 50
    # will default to service with same name as config entry ("web")
  },
  {
    Weight  = 50
    Service = "web-rewrite"
  },
]

JSON:

{
  "Kind": "service-splitter",
  "Name": "web",
  "Splits": [
    {
      "Weight": 50
    },
    {
      "Weight": 50,
      "Service": "web-rewrite"
    }
  ]
}

YAML:

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceSplitter
metadata:
  name: web
spec:
  splits:
    - weight: 50
      # defaults to the service with same name as the configuration entry ("web")
    - weight: 50
      service: web-rewrite

HTTP 헤더 설정 (Set HTTP Headers)

클라이언트가 어느 버전인지 알 수 있도록 추가 헤더가 있는 두 하위 집합 간에 트래픽 분할:

HCL:

Kind = "service-splitter"
Name = "web"
Splits = [
  {
    Weight        = 90
    ServiceSubset = "v1"
    ResponseHeaders {
      Set {
        "X-Web-Version": "v1"
      }
    }
  },
  {
    Weight        = 10
    ServiceSubset = "v2"
    ResponseHeaders {
      Set {
        "X-Web-Version": "v2"
      }
    }
  },
]

JSON:

{
  "Kind": "service-splitter",
  "Name": "web",
  "Splits": [
    {
      "Weight": 90,
      "ServiceSubset": "v1",
      "ResponseHeaders": {
        "Set": {
          "X-Web-Version": "v1"
        }
      }
    },
    {
      "Weight": 10,
      "ServiceSubset": "v2",
      "ResponseHeaders": {
        "Set": {
          "X-Web-Version": "v2"
        }
      }
    }
  ]
}

YAML:

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceSplitter
metadata:
  name: web
spec:
  splits:
    - weight: 90
      serviceSubset: v1
      responseHeaders:
        set:
          x-web-version: v1
    - weight: 10
      serviceSubset: v2
      responseHeaders:
        set:
          x-web-version: v2

서비스 스플리터 구성 항목 참조