Teleport Kubernetes Operator는 Kubernetes 사용자가 Operator 패턴을 따라 Kubernetes에서 일부 Teleport 리소스를 관리하는 방법을 제공합니다.

Teleport Kubernetes Operator는 사용자 정의 리소스 정의(CRD)와 함께 배포됩니다. 배포된 후 사용자는 kubectl과 같은 Kubernetes 클라이언트나 기존 CI/CD Kubernetes 파이프라인을 사용하여 Teleport 사용자 정의 리소스를 생성할 수 있습니다. Teleport Kubernetes Operator는 이러한 리소스를 감시하고 원하는 상태에 도달하기 위해 Teleport에 API 호출을 수행합니다.

운영자는 다음 두 가지 방식으로 배포할 수 있습니다:

• teleport-cluster Helm 차트로 배포된 자체 호스팅 Teleport 클러스터와 함께. 운영자 중단이 Teleport의 가용성에 영향을 미칠 수 없습니다.
• 원격 Teleport 인스턴스(Teleport Cloud 또는 Terraform으로 배포된 경우)에 대해

운영자는 Kubernetes 임대(lease)로 리더를 선출하여 단일 클러스터 내에서 여러 복제본을 지원합니다.

경고: 단 하나의 운영자 배포만 Teleport 클러스터에 대해 실행되어야 합니다. 그렇지 않으면 다른 운영자들이 불안정성과 비결정적 동작을 유발할 수 있습니다.

지원되는 Teleport 리소스는 Operator 참조 페이지에 나열되어 있습니다.

운영자 설정#

teleport-cluster Helm 차트를 사용하여 Teleport를 자체 호스팅하는 경우 Helm 배포 클러스터 가이드를 따르세요.

Kubernetes 외부에서 Teleport를 호스팅하는 경우(Teleport Cloud, Terraform, ...), 독립형 운영자 가이드를 따르세요.

어노테이션으로 조정 제어#

운영자는 CR에서 두 가지 어노테이션을 지원합니다:

teleport.dev/keep#

이 어노테이션은 CR이 삭제될 때 Teleport 리소스를 유지하도록 운영자에게 지시합니다. 이는 두 리소스 버전 간에 마이그레이션하려는 경우에 유용합니다.

예를 들어, TeleportRoleV6에서 TeleportRoleV7로 마이그레이션하려면:

• 기존 TeleportRoleV6 리소스에 teleport.dev/keep: "true" 어노테이션을 추가합니다
• TeleportRoleV6 CR을 삭제하면 운영자는 관련 Teleport 역할을 삭제하지 않습니다
• 동일한 이름으로 TeleportRoleV7 CR을 생성하면 운영자는 기존 v6 역할을 찾아 채택합니다.

가능한 값은 "true" 또는 "false" (Kubernetes에서 Boolean은 유효한 레이블 값이 아니므로 문자열)입니다.

teleport.dev/ignore#

이 어노테이션은 조정 시 CR을 무시하도록 운영자에게 지시합니다. 이는 Teleport에서 리소스가 생성, 업데이트 또는 삭제되지 않음을 의미합니다.

또한 무시된 CR을 삭제하려고 하면 운영자가 finalizer를 제거하지 않는다는 것을 의미합니다. finalizer가 유지되고 finalizer를 제거하거나 ignore 어노테이션을 제거하도록 리소스를 패치할 때까지 삭제가 차단됩니다.

가능한 값은 "true" 또는 "false" (Kubernetes에서 Boolean은 유효한 레이블 값이 아니므로 문자열)입니다.

시크릿에서 값 조회#

일부 Teleport 리소스에는 민감한 값이 포함될 수 있습니다. 특정 CR 필드는 기존 Kubernetes 시크릿을 참조할 수 있으며, 운영자는 조정 시 시크릿에서 값을 검색합니다.

CR에서 민감한 값을 저장하더라도 CR은 Kubernetes 시크릿 자체만큼 중요하게 취급되어야 합니다. 많은 CR은 Teleport RBAC을 구성합니다. CR 편집 권한이 있는 사람은 Teleport 관리자가 되어 Teleport에서 민감한 값을 검색할 수 있습니다.

자세한 내용은 전용 가이드를 참조하세요.

문제 해결#

CustomResource(CR)가 조정되지 않음#

Teleport Operator는 Kubernetes에서 새 리소스나 변경 사항을 감시합니다. 변경이 발생하면 조정 루프(reconciliation loop)를 트리거합니다. 이 루프는 리소스를 검증하고, 해당 리소스가 Teleport에 이미 존재하는지 확인하며, 리소스를 생성/업데이트/삭제하기 위해 Teleport API를 호출하는 역할을 합니다. 조정 루프는 또한 Kubernetes 리소스에 status 필드를 추가합니다.

오류가 발생하여 조정 루프가 성공하지 못하면 status.conditions의 항목이 무엇이 잘못되었는지 설명합니다. 이를 통해 사용자는 kubectl로 Kubernetes 리소스를 검사하여 오류를 진단할 수 있습니다:

$ kubectl describe teleportusers myuser

예를 들어, 사용자에게 존재하지 않는 role이 부여된 경우 status는 다음과 같이 표시됩니다:

apiVersion: resources.teleport.dev/v2
kind: TeleportUser
# [...]
status:
  conditions:
  - lastTransitionTime: "2022-07-25T16:15:52Z"
    message: Teleport resource has the Kubernetes origin label.
    reason: OriginLabelMatching
    status: "True"
    type: TeleportResourceOwned
  - lastTransitionTime: "2022-07-25T17:08:58Z"
    message: 'Teleport returned the error: role my-non-existing-role is not found'
    reason: TeleportError
    status: "False"
    type: SuccessfullyReconciled

여기서 SuccessfullyReconciled는 False이고 오류는 role my-non-existing-role is not found입니다.

status가 존재하지 않거나 문제를 해결하기에 충분한 정보를 제공하지 않는 경우, operator 로그를 확인하십시오:

CR에 status가 없음#

1. CR이 operator와 동일한 namespace에 있는지 확인하십시오. operator는 자체 namespace의 리소스만 감시합니다.
2. operator pod가 실행 중이고 정상 상태인지 확인하십시오:

   kubectl get pods -n "$OPERATOR_NAMESPACE"`
   

3. operator 로그를 확인하십시오:

   $ kubectl logs deploy/ -n "$OPERATOR_NAMESPACE"
   

 다중 복제본(multi-replica) 배포의 경우, 하나의 operator 인스턴스만 조정
 루프를 실행합니다. 이 operator를 leader라고 하며 조정 로그를 생성하는
 유일한 인스턴스입니다. 다른 operator 인스턴스들은 다음 로그와 함께
 대기합니다:

 ```
 leaderelection.go:248] attempting to acquire leader lease teleport/431e83f4.teleport.dev...
 ```

 조정 문제를 진단하려면 리소스를 조정하는 pod를 찾기 위해 모든 pod를
 검사해야 합니다.

Kubernetes CR을 삭제할 수 없음#

operator는 finalizer를 사용하여 Kubernetes CR을 삭제로부터 보호합니다. Teleport 리소스도 함께 삭제될 때까지 CR 삭제를 허용하지 않으며, 이는 남겨진 리소스가 방치되어 의도치 않은 접근 권한이 부여되는 것을 방지하기 위한 안전장치입니다.

Teleport가 리소스 삭제를 거부하는 데에는 여러 가지 이유가 있을 수 있는데, 가장 흔한 경우는 다른 리소스가 해당 리소스에 의존하는 경우입니다. 예를 들어, role이 여전히 사용자에게 할당되어 있으면 해당 role을 삭제할 수 없습니다.

이런 경우 operator는 Teleport가 보낸 오류를 로그에 보고합니다.

이 잠금을 해결하려면 다음 중 하나를 수행할 수 있습니다:

• 의존성 문제를 해결하여 Teleport에서 리소스가 성공적으로 삭제되도록 합니다. role 예시의 경우, 해당 role을 가지고 있던 여러 사용자에서 role에 대한 모든 언급을 제거해야 함을 의미합니다.

• Kubernetes CR을 패치하여 finalizer를 제거합니다. 이렇게 하면 Kubernetes가 operator의 삭제를 기다리는 것을 중단하고 CR을 제거합니다. 이렇게 하면 CR은 제거되지만 Teleport 리소스는 그대로 남습니다. operator는 다시는 이를 제거하려 시도하지 않습니다.

  예를 들어, role 이름이 my-role인 경우:

  kubectl patch TeleportRole my-role -p '{"metadata":{"finalizers":null}}' --type=merge
  

다음 단계#

• "IaC로 사용자 및 역할 관리" 가이드를 따르세요.
• 접근 제어 문서를 확인하세요.