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에서 민감한 값을 검색할 수 있습니다.

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

문제 해결#

The CustomResources (CRs) are not reconciled#

The Teleport Operator watches for new resources or changes in Kubernetes. When a change happens, it triggers the reconciliation loop. This loop is in charge of validating the resource, checking if it already exists in Teleport and making calls to the Teleport API to create/update/delete the resource. The reconciliation loop also adds a status field on the Kubernetes resource.

If an error happens and the reconciliation loop is not successful, an item in status.conditions will describe what went wrong. This allows users to diagnose errors by inspecting Kubernetes resources with kubectl:

$ kubectl describe teleportusers myuser

For example, if a user has been granted a nonexistent role the status will look like:

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

Here SuccessfullyReconciled is False and the error is role my-non-existing-role is not found.

If the status is not present or does not give sufficient information to solve the issue, check the operator logs:

The CR doesn't have a status#

1. Check if the CR is in the same namespace as the operator. The operator only watches for resource in its own namespace.

2. Check if the operator pods are running and healthy:

   kubectl get pods -n "$OPERATOR_NAMESPACE"`
   

3. Check the operator logs:

   $ kubectl logs deploy/
   
   

I cannot delete the Kubernetes CR#

The operator protects Kubernetes CRs from deletion with a finalizer. It will not allow the CR to be deleted until the Teleport resource is deleted as well, this is a safety to avoid leaving dangling resources and potentially grant unintentional access.

There might be some reasons causing Teleport to refuse a resource deletion, the most frequent one is if another resource depends on it. For example: you cannot delete a role if it is still assigned to a user.

If this happens, the operator will report the error sent by Teleport in its log.

To resolve this lock, you can either:

• resolve the dependency issue so the resource gets successfully deleted in Teleport. In the role example, this would imply removing any mention of the role from the various users who had it.

• patch the Kubernetes CR to remove the finalizers. This will tell Kubernetes to stop waiting for the operator deletion and remove the CR. If you do this, the CR will be removed but the Teleport resource will remain. The operator will never attempt to remove it again.

  For example, if the role is named my-role:

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

다음 단계#

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