Teleport Kubernetes Operator는 Kubernetes 사용자가 Kubernetes를 통해 일부 Teleport 리소스를 관리할 수 있는 방법을 제공합니다. Operator Pattern을 따릅니다.

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

Teleport 버전 15부터는 오퍼레이터가 다음 두 가지 방법으로 배포될 수 있습니다:

• teleport-cluster Helm 차트를 사용하여 배포된 자체 호스팅 Teleport 클러스터와 함께 배포됩니다. 이 배포 방법은 버전 14와 다릅니다. 버전 15 이상에서는 오퍼레이터가 더 이상 사이드카로 배포되지 않습니다. 오퍼레이터의 중단은 Teleport의 가용성에 영향을 미치지 않습니다.
• 원격 Teleport 인스턴스에 대해 배포됩니다 (예: Teleport Cloud 또는 Terraform으로 배포된 인스턴스)

오퍼레이터는 Kubernetes 리스를 통해 리더를 선출하여 단일 클러스터 내에서 여러 복제본을 지원합니다.

현재 지원되는 Teleport 리소스는 다음과 같습니다:

• 사용자 (TeleportUser)
• 역할
  • TeleportRole 은 역할 v5를 생성합니다.
  • TeleportRoleV6 은 역할 v6을 생성합니다.
  • TeleportRoleV7 은 역할 v7을 생성합니다.
• OIDC 커넥터 (TeleportOIDCConnector )
• SAML 커넥터 (TeleportSAMLConnector )
• GitHub 커넥터 (TeleportGithubConnector )
• 프로비저닝 토큰 (TeleportProvisionToken )
• 로그인 규칙 (TeleportLoginRules )

오퍼레이터 설정

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"입니다 (이 값들은 문자열이며, Booleans는 Kubernetes에서 유효한 레이블 값이 아닙니다).

teleport.dev/ignore

이 주석은 오퍼레이터에게 조정할 때 CR을 무시하도록 지시합니다. 이는 리소스가 Teleport에서 생성, 업데이트 또는 삭제되지 않음을 의미합니다.

이렇게 되면 오퍼레이터는 무시된 CR을 삭제하려고 할 때 최종자를 제거하지 않습니다. 최종자는 남아 있으며, 최종자를 제거하거나 무시 주석을 제거할 때까지 삭제가 차단됩니다.

가능한 값은 "true" 또는 "false"입니다 (이 값들은 문자열이며, Booleans는 Kubernetes에서 유효한 레이블 값이 아닙니다).

비밀에서 값 조회

일부 Teleport 리소스는 민감한 값을 포함할 수 있습니다. 선택된 CR 필드는 기존 Kubernetes 비밀을 참조하고, 운영자는 조정할 때 비밀에서 값을 검색합니다.

민감한 값을 CR 외부에 저장하더라도, CR은 Kubernetes 비밀 자체만큼 중요하게 고려해야 합니다. 많은 CR이 Teleport RBAC을 구성합니다. CR 편집 권한이 있는 사람은 Teleport 관리자가 되어 민감한 값을 Teleport에서 검색할 수 있습니다.

자세한 내용은 전용 가이드를 참조하십시오.

문제 해결

CustomResources (CRs)는 조화되지 않습니다

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

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

kubectl describe teleportusers myuser

예를 들어, 사용자가 존재하지 않는 역할이 부여된 경우 상태는 다음과 같습니다:

apiVersion: resources.teleport.dev/v2
kind: TeleportUser
# [...]
status:
  conditions:
    - lastTransitionTime: "2022-07-25T16:15:52Z"
      message: Teleport 리소스는 Kubernetes 출처 레이블을 가지고 있습니다.
      reason: OriginLabelMatching
      status: "True"
      type: TeleportResourceOwned
    - lastTransitionTime: "2022-07-25T17:08:58Z"
      message: "Teleport가 오류를 반환했습니다: role my-non-existing-role이(가) 발견되지 않음"
      reason: TeleportError
      status: "False"
      type: SuccessfullyReconciled

여기서 SuccessfullyReconciled 는 False 이며, 오류는 role my-non-existing-role이(가) 발견되지 않d 입니다.

상태가 존재하지 않거나 문제를 해결하기에 충분한 정보를 제공하지 않으면,
운영자 로그를 확인하십시오:

CR에 상태가 없습니다

1. CR이 운영자와 동일한 네임스페이스에 있는지 확인하십시오. 운영자는
   자신의 네임스페이스 내의 리소스만 감시합니다.

2. 운영자 포드가 실행 중이고 정상인지 확인하십시오:

   kubectl get pods -n "$OPERATOR_NAMESPACE"`

3. 운영자 로그를 확인하십시오:

   kubectl logs deploy/<OPERATOR_DEPLOYMENT_NAME> -n "$OPERATOR_NAMESPACE"

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

Kubernetes CR을 삭제할 수 없습니다

운영자는 최종자(finalizer)를 통해 Kubernetes CR의 삭제를 방지합니다.
Teleport 리소스가 삭제될 때까지 CR이 삭제되는 것을 허용하지 않으며,
이는 떨러진 리소스를 남기거나 의도하지 않은 접근을 부여하지 않기 위한 안전 장치입니다.

Teleport가 리소스 삭제를 거부하는 몇 가지 이유가 있을 수 있으며,
가장 흔한 이유는 다른 리소스가 그것에 의존하고 있는 경우입니다.
예를 들어: 사용자가 여전히 할당된 역할을 삭제할 수 없습니다.

이 경우 운영자는 로그에서 Teleport가 보낸 오류를 보고합니다.

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

• 리소스가 Teleport에서 성공적으로 삭제되도록 의존성 문제를 해결하십시오.
  역할 예시의 경우, 이는 해당 역할을 가진 여러 사용자에서 역할 언급을 제거해야 함을 의미합니다.

• Kubernetes CR을 패치하여 최종자를 제거하십시오. 이는 Kubernetes에 운영자 삭제를 기다리지 않도록
  지시하고 CR을 제거합니다. 이 작업을 수행하면 CR은 제거되지만 Teleport 리소스는 남게 됩니다.
  운영자는 다시는 이를 제거하려고 시도하지 않습니다.

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

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

다음 단계

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