Wasm Envoy 확장 구성 참조

Wasm Envoy 확장 구성 참조

이 주제는 Consul이 Envoy 프록시에서 WebAssembly(Wasm) 플러그인을 실행하도록 지시하는 wasm 확장을 구성하는 방법을 설명해요. 사용법은 Run WebAssembly plug-ins in Envoy proxy을 참조하세요.

출처: 문서

본문

이 주제는 Consul이 Envoy 프록시에서 WebAssembly(Wasm) 플러그인을 실행하도록 지시하는 wasm 확장을 구성하는 방법을 설명합니다. 사용법은 Run WebAssembly plug-ins in Envoy proxy을 참조하세요.

구성 모델 (Configuration model)

다음 목록은 wasm 구성의 필드 계층, 데이터 유형, 요구 사항을 간략히 설명합니다. 구성을 proxy defaults 또는 service defaults 구성 항목의 EnvoyExtension.Arguments 필드 안에 배치하세요. 추가 정보는 다음 문서를 참조하세요.

속성 이름을 클릭하면 기본값을 포함한 추가 세부 정보를 볼 수 있습니다.

전체 구성 (Complete configuration)

확장에 대한 모든 매개변수가 설정되면 구성은 다음 형식을 갖습니다.

Protocol = "<tcp or http>"
ListenerType = "<inbound or outbound>"
ProxyType = "connect-proxy"
PluginConfig = {
   Name = "<name for the filter>"
   RootID = "<ID for the set of filters on a VM>"
   VmConfig = {
      VmID = "<ID of the VM>"
      Runtime = "v8"
      Code = {
         Local = {      # Set either `Local` or `Remote`, not both
            Filename = "</path/to/plugin>"
         }
         Remote = {     # Set either `Local` or `Remote`, not both
            HttpURI =  {
               Service = {
                  Name = "<name of the upstream service>"
                  Namespace = "<Consul namespace containing the upstream service>"
                  Partition = "<Consul partition containing the upstream service>"
               }
               URI = "<URI of the plugin data>"
               Timeout = "1s"
            SHA256 = "<SHA256 for verifying the remote data>"
            RetryPolicy = {
                  RetryBackOff = {
                     BaseInterval = "1s"
                     MaxInterval = "10s"
                  }
                  NumRetries = -1
               }
            }
      Configuration = "<configuration passed to plugin on VM startup>"
      EnvironmentVariables = {
         HostEnvKeys = [
            <"keys">
         ]
         KeyValues = {
            [
               <"key = value">
            ]
         }
      }
   Configuration = "<configuration passed to plugin on plugin startup>"
   CapabilityRestrictionConfiguration = {
      AllowedCapabilities = {
         "fd_read"        = {}
         "fd_seek"        = {}
         "environ_get"    = {}
         "clock_get_time" = {}
      }
   }
}

사양 (Specification)

이 섹션은 wasm 확장에 대해 구성할 수 있는 필드에 대한 세부 정보를 제공합니다.

Protocol

적용할 Wasm 필터의 유형을 지정합니다. tcp 또는 http를 설정할 수 있습니다. Protocol을 필터가 로드될 때 Wasm 플러그인이 구현하는 프로토콜로 설정하세요. Consul이 필터를 적용하려면 프로토콜이 서비스의 프로토콜과 일치해야 합니다.

값

  • 기본값: 없음
  • 이 필드는 필수입니다.
  • 다음 문자열 값 중 하나입니다.

ListenerType

확장이 적용되는 리스너 유형을 지정합니다. 리스너 유형은 inbound 또는 outbound입니다. 리스너 유형이 inbound이면 Consul은 메시의 다른 서비스가 프록시에 연결된 서비스로 메시지를 보낼 때 Wasm 플러그인이 실행되도록 확장을 적용합니다. 리스너 유형이 outbound이면 Consul은 연결된 프록시가 메시의 다른 서비스로 메시지를 보낼 때 Wasm 플러그인이 실행되도록 확장을 적용합니다.

값

  • 기본값: 없음
  • 이 필드는 필수입니다.
  • 다음 문자열 값 중 하나입니다.

ProxyType

확장이 적용되는 Envoy 프록시의 유형을 지정합니다. 지원되는 유일한 값은 connect-proxy입니다.

값

  • 기본값: connect-proxy
  • 이 필드는 필수입니다.
  • 데이터 유형: 문자열

PluginConfig{}

Wasm 플러그인에 대한 다음 구성 매개변수를 포함하는 맵:

값

  • 기본값: 없음
  • 이 필드는 필수입니다.
  • 데이터 유형: 맵

PluginConfig{}.Name

VM의 필터에 대한 고유 이름을 지정합니다. Envoy는 같은 VmID와 RootID로 VM에서 여러 필터가 처리되는 경우 특정 필터를 식별하기 위해 이름을 사용합니다. 이름은 디버깅 목적으로 로그에도 나타납니다.

값

  • 기본값: 없음
  • 데이터 유형: 문자열

PluginConfig{}.RootID

RootContext와 Contexts를 공유하는 VM의 필터 집합에 대한 고유 ID를 지정합니다. 예를 들어 Wasm HttpFilter와 Wasm AccessLog가 해당됩니다(적용 가능한 경우). 같은 RootID와 VmID를 가진 모든 필터는 Contexts를 공유합니다.

값

  • 기본값: 없음
  • 데이터 유형: 문자열

PluginConfig{}.VmConfig{}

Wasm 플러그인을 실행하는 VM에 대한 다음 구성 매개변수를 포함하는 맵:

값

  • 기본값: 없음
  • 데이터 유형: 맵

PluginConfig{}.VmConfig{}.VmID

Envoy가 Wasm 코드의 해시와 함께 사용하여 플러그인을 실행할 VM을 결정하는 ID를 지정합니다. 같은 VmID와 Code를 가진 모든 플러그인은 같은 VM을 사용합니다. 지정하지 않으면 같은 코드를 가진 모든 플러그인이 같은 VM에서 실행됩니다. 플러그인 간 VM 공유는 보안 영향이 있을 수 있지만 메모리 사용량을 줄이고 데이터 공유를 더 쉽게 만들 수 있습니다.

값

  • 기본값: 없음
  • 데이터 유형: 문자열

PluginConfig{}.VmConfig{}.Runtime

Wasm 런타임의 유형을 지정합니다.

값

PluginConfig{}.VmConfig{}.Code{}

다음 구성 매개변수 중 하나를 포함하는 맵:

Local 또는 Remote 중 하나를 구성할 수 있지만 둘 다는 안 됩니다. Code 블록은 Envoy가 실행할 Wasm 플러그인 코드를 찾는 방법을 Consul에 지시합니다.

값

  • 기본값: 없음
  • 이 필드는 필수입니다.
  • 다음 구성 중 하나를 포함하는 맵입니다.

PluginConfig{}.VmConfig{}.Code{}.Local{}

Envoy가 로컬 볼륨에서 플러그인 코드를 로드하도록 지시합니다. 플러그인 코드가 원격 서버에 있으면 Local 매개변수를 구성하지 마세요.

Local 필드는 Filename 매개변수를 포함하는 맵입니다. Filename 매개변수는 로컬 파일 시스템의 플러그인 경로를 지정하는 문자열 값을 사용합니다.

로컬 플러그인은 Kubernetes 오케스트레이션 환경에서 지원되지 않습니다.

값

  • 기본값: 없음
  • 로컬 파일 시스템의 플러그인 경로를 지정하는 문자열 값을 취하는 Filename 매개변수를 포함하는 맵입니다.

PluginConfig{}.VmConfig{}.Code{}.Remote{}

Envoy가 원격 서버에서 플러그인 코드를 로드하도록 지시합니다. 플러그인 코드가 로컬 VM에 있으면 Remote 매개변수를 구성하지 마세요.

Remote 필드는 다음 매개변수를 포함하는 맵입니다.

값

  • 기본값: 없음
  • 데이터 유형: 맵

PluginConfig{}.VmConfig{}.Code{}.Remote{}.HttpURI{}

원격 데이터를 가져오기 위한 구성을 지정합니다. HttpURI 필드는 다음 매개변수를 포함하는 맵입니다.

값

  • 기본값: 없음
  • 데이터 유형: 맵

PluginConfig{}.VmConfig{}.Code{}.Remote{}.HttpURI{}.Service

원격 플러그인을 가져올 업스트림 서비스를 지정합니다.

값

  • 기본값: 없음
  • 데이터 유형: 맵

다음 표는 Service 맵에서 지정할 수 있는 필드를 설명합니다.

| 매개변수 | 설명 | 데이터 유형 | 기본값 | | Name | 업스트림 서비스의 이름을 지정합니다. | String | None | | Namespace | Enterprise. 업스트림 서비스가 속한 Consul 네임스페이스를 지정합니다. | String | default | | Partition | Enterprise. 업스트림 서비스가 속한 Consul 관리 파티션을 지정합니다. | String | default |

PluginConfig{}.VmConfig{}.Code{}.Remote{}.HttpURI{}.URI

Envoy가 업스트림에서 플러그인 파일을 가져오는 데 사용하는 URI를 지정합니다. 이 필드는 Envoy가 원격 위치에서 플러그인 코드를 검색하는 데 필요합니다. 프로토콜, 호스트, 경로를 포함하는 원격 URI의 완전한 정규화된 도메인 이름(FQDN)을 지정해야 합니다.

값

  • 기본값: 없음
  • 이 필드는 필수입니다.
  • FQDN을 지정하는 문자열 값.

PluginConfig{}.VmConfig{}.Code{}.Remote{}.HttpURI{}.Timeout

플러그인 데이터에 대한 요청을 완료하는 데 응답이 걸릴 수 있는 최대 기간을 지정합니다.

값

  • 기본값: 1s
  • 데이터 유형: 문자열

PluginConfig{}.VmConfig{}.Code{}.Remote{}.SHA256

원격 데이터를 검증하기 위해 필요한 SHA256 문자열을 지정합니다.

값

  • 기본값: 없음
  • 이 필드는 필수입니다.
  • 데이터 유형: 문자열

PluginConfig{}.VmConfig{}.Code{}.Remote{}.RetryPolicy{}

플러그인 데이터를 가져올 때 업스트림 서비스에 대한 요청을 재시도하는 정책을 정의합니다. RetryPolicy 필드는 다음 매개변수를 포함하는 맵입니다.

값

  • 기본값: 없음
  • 데이터 유형: 맵

PluginConfig{}.VmConfig{}.Code{}.Remote{}.RetryPolicy{}.RetryBackOff{}

재시도 백오프 전략을 제어하는 매개변수를 지정합니다.

값

  • 기본값: 없음
  • 데이터 유형: 맵

다음 표는 RetryBackOff 맵에서 지정할 수 있는 필드를 설명합니다.

| 매개변수 | 설명 | 데이터 유형 | 기본값 | | BaseInterval | 다음 백오프 계산을 결정하는 기본 간격을 지정합니다. 0보다 크고 MaxInterval 값보다 작거나 같은 값을 설정하세요. | String | 1s | | MaxInterval | 재시도 사이의 최대 간격을 지정합니다. BaseInterval 값보다 크거나 같은 값을 설정하세요. | String | 10s |

PluginConfig{}.VmConfig{}.Code{}.Remote{}.RetryPolicy{}.NumRetries

초기 시도가 실패할 경우 Envoy가 플러그인 데이터를 가져오기 위해 재시도하는 횟수를 지정합니다.

값

  • 기본값: 1
  • 데이터 유형: 정수

PluginConfig{}.VmConfig{}.Configuration

Envoy가 바이트로 인코딩하여 VM 시작 중에 플러그인에 전달하는 구성을 지정합니다. 추가 정보는 Proxy Wasm ABI 문서의 proxy_on_vm_start을 참조하세요.

값

  • 기본값: 없음
  • 이 필드는 필수입니다.
  • 데이터 유형: 문자열

PluginConfig{}.VmConfig{}.EnvironmentVariables{}

Envoy가 이 VM에 주입하여 WASI의 environ_get 및 environ_get_sizes 시스템 호출을 통해 사용할 수 있게 하는 환경 변수를 지정합니다.

대부분의 경우 WASI는 언어의 표준 라이브러리에서 함수를 암시적으로 호출합니다. 결과적으로 직접 호출할 필요가 없습니다. 네이티브 플랫폼에서와 같이 환경 변수에도 액세스할 수 있습니다.

키 공간 충돌이 있으면 Envoy는 구성을 거부합니다.

EnvironmentVariables 필드는 키와 값을 설정하기 위한 매개변수를 포함하는 맵입니다.

값

  • 기본값: 없음
  • 데이터 유형: 맵

다음 표는 EnvironmentVariables 맵에 포함된 매개변수를 설명합니다.

| 매개변수 | 설명 | 데이터 유형 | 기본값 | | HostEnvKeys | VM에 노출할 Envoy 환경 변수 키 목록을 지정합니다. 키가 Envoy의 환경 변수에 존재하면 키-값 쌍이 주입됩니다. Envoy는 환경 변수에 존재하지 않는 HostEnvKeys는 무시합니다. | List | None | | KeyValues | VM에 주입할 명시적 키-값 쌍의 맵을 지정합니다. | 문자열 키와 값의 맵 | None |

PluginConfig{}.Configuration

Consul이 바이트로 인코딩하여 플러그인 시작 중에 플러그인에 전달하는 구성을 지정합니다. 추가 정보는 Envoy 문서의 proxy_on_configure을 참조하세요.

값

  • 기본값: 없음
  • 데이터 유형: 문자열

PluginConfig{}.CapabilityRestrictionConfiguration{}

모듈에서 사용할 수 있는 proxy-Wasm 기능을 제한하는 구성을 지정합니다.

CapabilityRestrictionConfiguration 필드는 AllowedCapabilities 매개변수를 포함하는 맵입니다. AllowedCapabilities 매개변수는 Envoy 기능 이름에 해당하는 문자열 값의 맵을 취합니다. 추가 정보는 Envoy documentation을 참조하세요.

보안 경고: Consul은 각 기능이 매핑되는 값을 무시합니다. AllowedCapabilities를 비워두면 모든 기능을 허용할 수 있지만, 그러면 구성된 플러그인이 Wasm VM이 제공하는 런타임 API에 대해 완전한 무제한 액세스를 갖게 됩니다. Wasm 런타임 API가 제공하는 특정 기능에 대한 액세스를 제한하려면 이 값을 비어 있지 않은 맵으로 설정해야 합니다.

값

  • 기본값: ""
  • AllowedCapabilities 매개변수를 포함하는 맵입니다. AllowedCapabilities 매개변수는 Envoy 기능 이름에 해당하는 문자열 값의 맵을 취합니다. 추가 정보는 Envoy documentation을 참조하세요.

예시 (Examples)

다음 예시는 구성을 모델링할 수 있는 패턴을 보여줍니다.

로컬 파일에서 Wasm 플러그인 실행

다음 예시에서 Consul은 로컬 /consul/extensions/sqli.wasm 파일의 플러그인 코드를 사용하는 인바운드 TCP Wasm 필터로 db 서비스의 Envoy 프록시를 구성합니다.

Kind = "service-defaults"
Name = "db"
Protocol = "tcp"
EnvoyExtensions = [
  {
    Name      = "builtin/wasm"
    Required  = true
    Arguments = {
      Protocol = "tcp"
      ListenerType = "inbound"
      PluginConfig = {
        VmConfig = {
          Code = {
            Local = {
              Filename = "file:///consul/extensions/sqli.wasm"
            }
          }
        }
        Configuration = <<EOF
{
  "key": "value"
}
EOF
      }
    }
  }
]

원격 파일에서 Wasm 플러그인 실행

다음 예시에서 Consul은 HTTP Wasm 필터로 모든 HTTP 서비스의 Envoy 프록시를 구성합니다. 필터는 원격 https://extension-server/waf.wasm 파일의 플러그인 코드를 사용합니다. 각 서비스의 Envoy 프록시는 원격 파일을 가져오고 SHA256 체크섬을 검증합니다. Consul이 3초 후에도 원격 플러그인을 가져올 수 없으면 프록시가 타임아웃됩니다.

Kind   = "proxy-defaults"
Name   = "global"
EnvoyExtensions = [
  {
    Name      = "builtin/wasm"
    Arguments = {
      Protocol = "http"
      ListenerType = "inbound"
      PluginConfig = {
        VmConfig = {
          Code = {
            Remote = {
              HttpURI = {
                URI     = "https://extension-server/waf.wasm"
                Timeout = "3s"
              }
              SHA256 = "ef57657e..."
            }
          }
        }
        Configuration = "..."
      }
    }
  }
]

더 알아보기 (Learn more)