Teleport Kubernetes Operator

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 리스를 사용하여 클러스터 내에서 여러 복제본을 지원하여 리더를 선출합니다.

Warning

하나의 운영자 배포만 Teleport 클러스터에서 실행되어야 합니다. 그렇지 않으면, 서로 다른 운영자가 불안정성과 비결정적 행동을 초래할 수 있습니다.

현재 지원되는 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"입니다(이는 문자열로, Boolean은 Kubernetes에서 유효한 레이블 값이 아닙니다).

`teleport.dev/ignore`

이 주석은 운영자에게 조정 시 CR을 무시하도록 지시합니다. 즉, Teleport에서 해당 리소스가 생성, 업데이트 또는 삭제되지 않습니다.

또한, 무시된 CR을 삭제하려고 할 때 운영자가 최종자를 제거하지 않습니다. 최종자는 유지되며, 리소스에 대한 패치를 통해 최종자를 제거하거나 무시 주석을 제거할 때까지 삭제가 차단됩니다.

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

문제 해결

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가 반환한 오류: 역할 my-non-existing-role이(가) 발견되지 않음'
    reason: TeleportError
    status: "False"
    type: SuccessfullyReconciled

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

상태가 존재하지 않거나 문제를 해결할 충분한 정보를 제공하지 않는 경우,
운영자 로그를 확인하세요:

CR에 상태가 없음

CR이 운영자와 동일한 네임스페이스에 있는지 확인하세요. 운영자는 자신의 네임스페이스의 리소스만 감시합니다.
운영자 포드가 실행되고 있는지 및 건강한지 확인하세요:
```
kubectl get pods -n "$OPERATOR_NAMESPACE"
```
운영자 로그를 확인하세요:
```
kubectl logs deploy/<OPERATOR_DEPLOYMENT_NAME> -n "$OPERATOR_NAMESPACE"
```
Note
다중 복제 배포의 경우, 하나의 운영자 인스턴스만이 조정 루프를 실행하고 있습니다. 이 운영자를 리더라고 하며 조정 로그를 생성하는 유일한 인스턴스입니다. 다른 운영자 인스턴스는 다음 로그와 함께 대기하고 있습니다:
leaderelection.go:248] attempting to acquire leader lease teleport/431e83f4.teleport.dev...
조정 문제를 진단하려면 모든 포드를 검사하여 리소스를 조정하는 포드를 찾아야 합니다.

Kubernetes CR을 삭제할 수 없습니다

운영자는 최종기로 인해 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로 사용자 및 역할 관리" 가이드를 따르세요.
액세스 제어 문서를 확인하세요.

Teleport 원문 보기