teleport-relay Helm 차트는 Kubernetes 클러스터에 Teleport Relay 서비스 그룹을 배포하는 데 사용되며, 클라이언트와 리소스 간의 연결을 Teleport 컨트롤 플레인을 거치지 않고 제공합니다.

teleport-relay 차트는 Teleport v18.3.0 이상에서 사용할 수 있습니다.

GitHub에서 소스를 확인할 수 있습니다.

이 레퍼런스는 teleport-relay 차트에서 사용 가능한 값들을 상세히 설명합니다.

차트가 배포하는 항목#

teleport-relay 차트는 다음 Kubernetes 리소스를 배포합니다:

레퍼런스#

relayGroup#

relayGroup은 동일한 로드 밸런서를 통해 접근할 수 있는 Relay 인스턴스 그룹의 내부 식별자를 설정합니다. Teleport 클러스터 전체에서 고유해야 합니다.

publicHostnames#

publicHostnames는 이 Relay 그룹이 클라이언트에게 공개적으로 접근 가능한 호스트명 목록입니다.

publicHostnames:
  - relay.example.com

targetConnectionCount#

targetConnectionCount는 에이전트가 서로 다른 Relay 인스턴스에 개설하는 터널 연결의 수입니다. 이 값은 레플리카 수보다 크지 않아야 합니다.

proxyAddr#

proxyAddr는 클러스터에 조인하는 데 사용해야 하는 외부 공개용 Teleport Proxy Service 엔드포인트를 지정합니다. 이는 Teleport 클러스터의 웹 UI에 접속할 때 사용하는 URL과 동일합니다. 사용하는 포트는 일반적으로 3080 또는 443입니다.

다음은 몇 가지 예시입니다:

enterprise#

enterprise는 teleport-relay 차트가 컨테이너 이미지의 OSS 버전을 배포할지 엔터프라이즈 버전을 배포할지 제어합니다. Teleport Cloud 또는 자체 호스팅 Teleport Enterprise 클러스터에 연결할 때는 에이전트가 엔터프라이즈 기능을 활용할 수 있도록 이 값을 true로 설정해야 합니다.

joinParams#

joinParams는 Teleport Agent가 Teleport 클러스터에 조인하는 방식을 제어합니다. 에이전트가 클러스터에 연결하려면 이 하위 값들을 구성해야 합니다.

사용하는 토큰은 Relay 역할을 부여해야 하며, Helm 릴리스의 수명 동안 유효해야 합니다.

joinParams.method#

joinParams.method는 인스턴스가 Teleport 클러스터에 조인할 때 사용할 조인 방식을 제어합니다.

가능한 값 목록, 각 조인 방식의 의미, 그리고 각 방식을 설정하는 가이드는 조인 방식 레퍼런스를 참고하세요.

teleport-relay에서 일반적으로 사용하는 조인 방식은 다음과 같습니다:

• token: 가장 기본적인 방식으로, 일반적인 임시 시크릿 토큰을 사용합니다
• kubernetes: in-cluster 변형(에이전트가 teleport-cluster 차트와 동일한 Kubernetes 클러스터에서 실행되는 경우) 또는 JWKS/OIDC 변형(Teleport Auth Service의 위치와 관계없이 모든 Kubernetes 클러스터에서 동작)을 사용합니다.

joinParams.tokenName#

joinParams.tokenName은 에이전트가 Teleport 클러스터에 조인할 때 사용하는 토큰을 제어합니다.

joinParams.method가 위임 조인 방식인 경우, 이 값은 민감하지 않습니다.

joinParams.method가 token(기본값)인 경우, joinParams.tokenName은 시크릿 토큰 자체를 포함합니다. 이 경우 값이 민감하므로 에이전트 구성에 직접 포함되는 대신 자동으로 Kubernetes Secret에 저장됩니다.

method가 token인 경우, 토큰이 기존 Kubernetes Secret을 통해 제공된다면 joinParams.tokenName을 비워둘 수 있습니다. 자세한 내용과 지침은 joinTokenSecret을 참고하세요.

method가 kubernetes인 경우, teleportClusterName을 설정해야 합니다.

teleportClusterName#

teleportClusterName은 조인 대상 Teleport 클러스터의 이름입니다. Kubernetes JWKS 또는 OIDC 조인 방식을 통해 조인할 때는 이 값을 설정해야 합니다.

이 값이 설정되면 차트는 프로젝션된 볼륨을 통해 kubernetes 서비스 계정 토큰을 마운트하고 Teleport가 이를 조인에 사용하도록 구성합니다.

joinTokenSecret#

joinTokenSecret은 조인 토큰 시크릿의 생성과 이름을 관리합니다. 자세한 내용은 joinParams 섹션을 참고하세요.

joinTokenSecret.create#

joinTokenSecret.create는 차트가 Teleport 조인 토큰을 담은 Kubernetes Secret을 생성할지 제어합니다. false인 경우, Helm 릴리스 네임스페이스에 구성된 이름으로 Kubernetes Secret을 직접 생성해야 합니다.

joinTokenSecret.name#

joinTokenSecret.name은 차트가 사용하는 Teleport 조인 토큰을 담은 Kubernetes Secret의 이름입니다.

joinTokenSecret.create가 false인 경우, 차트는 시크릿을 직접 생성하지 않습니다. 대신 기존 시크릿에서 값을 읽어옵니다. joinTokenSecret.name은 이 시크릿의 이름을 지정합니다. 이를 통해 시크릿을 외부에서 구성하고 Teleport 차트 값에 평문 조인 토큰이 저장되는 것을 방지할 수 있습니다.

직접 조인 토큰 시크릿을 생성하려면 다음과 같은 명령을 사용할 수 있습니다:

$ kubectl --namespace teleport create secret generic my-token-secret --from-literal=auth-token=<replace-with-actual-token>

joinTokenSecret:
  create: false
  name: my-token-secret

joinParams:
  method: "token"
  tokenName: ""

proxyProtocol#

proxyProtocol은 로드 밸런서에서 들어오는 연결에 PROXY 프로토콜 v2 헤더를 포함할지 여부를 제어합니다.

log#

log는 에이전트 로깅을 제어합니다.

log.level#

log.level은 Teleport 프로세스의 로그 레벨입니다. 사용 가능한 로그 레벨은 DEBUG, INFO, WARNING, ERROR입니다.

기본값은 INFO이며, 프로덕션 환경에서 권장됩니다. DEBUG는 최초 설정 시 또는 디버깅을 위해 더 상세한 로그를 확인할 때 유용합니다.

log.format#

log.format은 Teleport 프로세스의 로그 출력 형식을 설정합니다. 가능한 값은 text 또는 json입니다.

preStopDelay#

preStopDelay는 파드가 Terminating 상태로 진입한 후 Teleport 인스턴스가 종료 광고(shutdown advertisement)를 시작하라는 시그널을 받기까지 경과하는 선택적 시간입니다. 로드 밸런서가 종료 중인 파드로 연결을 라우팅하는 것을 중단할 시간을 확보하는 데 유용합니다.

shutdownDelay#

shutdownDelay는 Teleport 인스턴스가 종료를 광고한 후 새로운 인바운드 연결의 서비스를 중단하기 전까지 대기하는 선택적 시간입니다.

terminationGracePeriodSeconds#

terminationGracePeriodSeconds는 Teleport 인스턴스 파드에 종료를 위해 할당되는 시간입니다. 이 값은 preStopDelay와 shutdownDelay의 합보다 길어야 합니다.

highAvailability#

highAvailability는 차트가 배포하는 Teleport Agent의 가용성을 제어하는 설정을 포함합니다.

가용성은 다음 방법으로 높일 수 있습니다:

• replicaCount로 더 많은 레플리카를 실행합니다
• requireAntiAffinity로 파드가 동일한 Kubernetes 노드에 스케줄링되지 않도록 요구합니다
• podDisruptionBudget로 Kubernetes가 모든 파드를 동시에 삭제하지 않도록 요청합니다.

highAvailability 설정을 사용하더라도 파드를 재시작하거나 롤아웃하면 여전히 장시간 유지되는 세션에 중단이 발생할 수 있습니다.

highAvailability.replicaCount#

highAvailability.replicaCount는 차트가 배포하는 에이전트 레플리카의 수입니다.

여러 Teleport 파드가 배포되는 고가용성 모드를 위해서는 1보다 큰 숫자로 설정하세요.

highAvailability.podDisruptionBudget#

highAvailability.podDisruptionBudget은 Kubernetes가 모든 에이전트 레플리카를 동시에 삭제하지 않도록 하기 위해 차트가 Kubernetes PodDisruptionBudget을 생성하고 구성하는 방식을 제어합니다.

highAvailability.podDisruptionBudget.enabled#

highAvailability.podDisruptionBudget.enabled는 차트가 에이전트 파드에 대한 Kubernetes PodDisruptionBudget을 생성하도록 합니다.

highAvailability.podDisruptionBudget.minAvailable#

highAvailability.podDisruptionBudget.minAvailable은 PodDisruptionBudget에 지정된 최소 사용 가능 파드 수입니다.

resources#

resources는 차트가 생성하는 파드에 대한 리소스 요청/제한을 설정합니다. 자세한 내용은 Kubernetes 문서를 참고하세요.

goMemLimitRatio#

goMemLimitRatio는 차트가 설정하는 GOMEMLIMIT 환경 변수를 구성합니다. GOMEMLIMIT은 go 가비지 컬렉터가 할당된 메모리를 주어진 임계값 아래로 유지하도록 지시합니다. 이는 최선의 노력(best-effort) 시도이지만, 버스트가 발생하는 경우 OOM을 방지하는 데 도움이 됩니다.

메모리 제한이 설정되고 goMemLimitRatio가 0이 아닌 경우, 차트는 GOMEMLIMIT을 resources.memory.limits * goMemLimitRatio로 설정합니다. 값은 0과 1 사이여야 합니다. GOMEMLIMIT을 해제하려면 0으로 설정하세요. GOMEMLIMIT이 이미 extraEnv를 통해 설정된 경우 이 설정은 효과가 없습니다.

service#

service는 Teleport Relay 인스턴스를 가리키는 Service에 대한 옵션입니다.

service.type#

service.type은 Service의 유형입니다. 특별한 요구 사항이 없다면 LoadBalancer로 설정하는 것이 좋습니다.

service.spec#

service.spec에 추가하는 항목은 모두 Service 스펙에 추가됩니다.

spec:
  loadBalancerIP: "1.2.3.4"
  loadBalancerClass: service.k8s.aws/nlb

serviceAccount#

serviceAccount는 파드가 사용하는 Kubernetes 서비스 계정과 관련된 설정을 포함합니다.

serviceAccount.create#

serviceAccount.create는 ServiceAccount를 생성할지 아니면 기존 것을 사용할지 지정합니다.

serviceAccount.name#

serviceAccount.name은 사용할 ServiceAccount의 이름입니다. 설정하지 않고 serviceAccount.create가 true이면, 릴리스 이름을 사용해 이름이 생성됩니다. create가 false이면, 이 이름은 기존 서비스 계정을 참조하는 데 사용됩니다.

extraLabels#

extraLabels는 차트가 생성하는 리소스에 적용할 추가 Kubernetes 레이블을 포함합니다. 자세한 내용은 Kubernetes 레이블 문서 를 참고하세요.

extraLabels.config#

extraLabels.config는 ConfigMap에 설정할 레이블입니다.

extraLabels.deployment#

extraLabels.deployment는 Deployment에 설정할 레이블입니다.

extraLabels.pod#

extraLabels.pod는 Pod에 설정할 레이블입니다.

extraLabels.podDisruptionBudget#

extraLabels.podDisruptionBudget은 PodDisruptionBudget에 설정할 레이블입니다.

extraLabels.secret#

extraLabels.secret은 Secret에 설정할 레이블입니다.

extraLabels.service#

extraLabels.service는 Service에 설정할 레이블입니다.

extraLabels.serviceAccount#

extraLabels.serviceAccount는 ServiceAccount에 설정할 레이블입니다.

annotations#

annotations는 차트가 생성하는 다양한 Kubernetes 오브젝트에 적용할 어노테이션을 포함합니다. 자세한 내용은 Kubernetes 어노테이션 문서를 참고하세요.

annotations.config#

annotations.config는 ConfigMap에 설정할 어노테이션입니다.

annotations.deployment#

annotations.deployment는 Deployment에 설정할 어노테이션입니다.

annotations.pod#

annotations.pod는 Pod에 설정할 어노테이션입니다.

annotations.podDisruptionBudget#

annotations.podDisruptionBudget은 podDisruptionBudget에 설정할 어노테이션입니다.

annotations.secret#

annotations.secret은 Secret에 설정할 어노테이션입니다.

annotations.service#

annotations.service는 Service에 설정할 어노테이션입니다.

annotations.serviceAccount#

annotations.serviceAccount는 ServiceAccount에 설정할 어노테이션입니다.

image#

image는 차트가 생성하는 Teleport Community Edition Agent 파드에 사용되는 컨테이너 이미지를 설정합니다.

Teleport에서 게시한 이미지 대신 직접 만든 Teleport 이미지를 사용하도록 이 값을 재정의할 수 있습니다.

기본적으로 이미지에는 Teleport 애플리케이션과 그 런타임 의존성만 포함되며, 셸은 포함되지 않습니다.

이 설정은 enterprise가 false일 때만 적용됩니다. 엔터프라이즈 버전을 실행할 때는 대신 enterpriseImage를 사용해야 합니다.

enterpriseImage#

enterpriseImage는 차트가 생성하는 Teleport Enterprise 에이전트 파드에 사용되는 컨테이너 이미지를 설정합니다.

Teleport에서 게시한 이미지 대신 직접 만든 Teleport 이미지를 사용하도록 이 값을 재정의할 수 있습니다.

기본적으로 이미지에는 Teleport 애플리케이션과 그 런타임 의존성만 포함되며, 셸은 포함되지 않습니다.

이 설정은 enterprise가 true일 때만 적용됩니다. OSS 버전을 실행할 때는 대신 image를 사용해야 합니다.

imagePullSecrets#

imagePullSecrets는 프라이빗 Docker 레지스트리에 접근하기 위해 선택적으로 사용할 수 있는 인증 토큰을 담은 시크릿 목록입니다.

자세한 내용은 Kubernetes 레퍼런스를 참고하세요.

imagePullPolicy#

imagePullPolicy는 차트가 생성하는 파드에 대한 풀 정책을 설정합니다. 자세한 내용은 Kubernetes 문서를 참고하세요.

topologySpreadConstraints#

topologySpreadConstraints는 차트가 생성하는 파드에 대한 토폴로지 분산 제약(topology spread constraints)을 설정합니다. 자세한 내용은 Kubernetes 문서를 참고하세요.

설정하지 않으면, 차트는 파드를 호스트와 영역 전체에 분산하려 시도하는 소프트 토폴로지 분산 제약을 기본값으로 사용합니다.

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: kubernetes.io/hostname
    whenUnsatisfiable: ScheduleAnyway
    labelSelector:
      matchLabels: # dynamically computed
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: ScheduleAnyway
    labelSelector:
      matchLabels: # dynamically computed

disableTopologySpreadConstraints#

disableTopologySpreadConstraints는 기본 토폴로지 분산 제약을 끕니다.

affinity#

affinity는 차트가 생성하는 파드에 대한 어피니티를 설정합니다. 자세한 내용은 Kubernetes 문서를 참고하세요.

tolerations#

tolerations는 차트가 생성하는 파드에 대한 톨러레이션을 설정합니다. 자세한 내용은 Kubernetes 문서를 참고하세요.

teleportConfig#

teleportConfig는 Teleport 파드에 전달할 YAML teleport 구성을 포함합니다. 이 구성은 차트가 생성한 구성과 병합되며, 충돌이 발생하는 경우 우선합니다.

지원되는 필드 목록은 Teleport 구성 레퍼런스를 참고하세요.

extraArgs#

extraArgs는 메인 Teleport 컨테이너의 teleport start에 전달할 추가 인수를 포함합니다.

extraEnv#

extraEnv는 메인 Teleport 컨테이너에 설정할 추가 환경 변수를 포함합니다.

예를 들어:

extraEnv:
  - name: HTTPS_PROXY
    value: "http://username:password@my.proxy.host:3128"

extraVolumes#

extraVolumes는 Teleport 파드에 마운트할 추가 볼륨을 포함합니다. 자세한 내용은 Kubernetes 볼륨 문서를 참고하세요.

예를 들어:

extraVolumes:
- name: myvolume
  secret:
    secretName: testSecret

extraVolumeMounts#

extraVolumeMounts는 메인 Teleport 컨테이너에 대한 추가 볼륨 마운트를 포함합니다. 자세한 내용은 Kubernetes 볼륨 문서를 참고하세요.

예를 들어:

extraVolumesMounts:
- name: myvolume
  mountPath: /path/on/host

dnsConfig#

dnsConfig는 에이전트 파드에 대한 커스텀 Pod DNS 구성을 포함합니다. 이 값은 DNS 부하를 줄여야 할 때 유용합니다: "ndots"를 0으로 설정하고 원격 호스트를 참조할 때는 FQDN만 사용하세요.

자세한 내용은 Kubernetes 파드 DNS 문서 를 참고하세요.

예를 들어:

 nameservers:
   - 1.2.3.4
 searches:
   - ns1.svc.cluster-domain.example
   - my.dns.search.suffix
 options:
   - name: ndots
     value: "2"

dnsPolicy#

dnsPolicy는 파드의 DNS 정책을 설정합니다

자세한 내용은 Kubernetes 파드 DNS 문서 를 참고하세요.

hostAliases#

hostAliases는 Teleport 파드에 호스트 별칭을 설정합니다. 자세한 내용은 Kubernetes 호스트 파일 문서를 참고하세요.

예를 들어:

hostAliases:
  - ip: "127.0.0.1"
    hostnames:
      - "foo.local"
      - "bar.local"
  - ip: "10.1.2.3"
    hostnames:
      - "foo.remote"
      - "bar.remote"

tls#

tls는 에이전트 파드에 직접 TLS 자료를 마운트하기 위한 설정을 포함합니다.

tls.existingCASecretName#

tls.existingCASecretName은 신뢰할 수 있는 CA 또는 PEM 형식의 번들을 Teleport 파드에 로드하기 위해 SSL_CERT_FILE 환경 변수를 설정합니다. 주입된 CA는 Proxy Service와의 TLS 통신을 검증하는 데 사용됩니다.

CA 인증서를 담은 시크릿을 Teleport와 동일한 네임스페이스에 다음과 같은 명령으로 생성해야 합니다:

$ kubectl create secret generic my-root-ca --from-file=ca.pem=/path/to/root-ca.pem

tls.existingCASecretKeyName#

tls.existingCASecretKeyName은 CA 시크릿의 어떤 키를 신뢰할 수 있는 CA 번들 파일로 사용할지 결정합니다.

insecureSkipProxyTLSVerify#

insecureSkipProxyTLSVerify는 Proxy Service가 제시하는 TLS 인증서의 TLS 검증을 비활성화합니다.

이는 테스트 목적으로 유효한 TLS 인증서가 없는 Teleport 클러스터에 Teleport 인스턴스를 조인할 때 사용할 수 있습니다.

securityContext#

securityContext는 차트가 생성하는 파드에 대한 컨테이너 보안 컨텍스트를 설정합니다. 자세한 내용은 Kubernetes 문서를 참고하세요.

기본값은 restricted PSS와 호환됩니다.

보안 컨텍스트를 해제하려면 null 또는 ~로 설정하세요.

podSecurityContext#

podSecurityContext는 차트가 생성하는 파드에 대한 파드 보안 컨텍스트를 설정합니다. 자세한 내용은 Kubernetes 문서를 참고하세요.

보안 컨텍스트를 해제하려면 null 또는 ~로 설정하세요.

priorityClassName#

priorityClassName은 차트가 생성하는 파드가 사용하는 우선순위 클래스를 설정합니다. 차트를 배포하기 전에 PriorityClass 리소스를 생성하는 것은 사용자의 책임입니다. 자세한 내용은 Kubernetes 문서를 참고하세요.

nameOverride#

nameOverride는 선택적으로 차트의 이름을 재정의하며, 리소스에 이름을 지정할 때 릴리스 이름과 함께 사용됩니다.

fullnameOverride#

fullnameOverride는 선택적으로 리소스의 전체 이름을 재정의합니다.

teleportVersionOverride#

teleportVersionOverride는 차트가 배포하는 Teleport Kubernetes Operator 이미지 버전을 제어합니다.

일반적으로 Teleport Kubernetes Operator의 버전은 차트의 버전과 일치합니다. 차트 버전 15.0.0을 설치하면 Teleport 버전 15.0.0을 사용하게 됩니다. 에이전트 업그레이드는 차트를 업그레이드하여 수행합니다.