이 가이드에서는 teleport-cluster Helm 차트를 통해 배포된 Teleport 클러스터와 함께 Teleport Kubernetes Operator를 실행하는 방법을 설명합니다.

경고: Teleport 클러스터가 teleport-cluster Helm 차트를 사용하여 배포되지 않은 경우(Teleport Cloud, 수동 배포, Terraform을 통한 배포 등), 대신 독립형 운영자 가이드를 따라야 합니다.

작동 방식#

teleport-cluster Helm 차트에는 teleport-operator 차트가 종속성으로 포함되어 있습니다. operator.enabled 값 필드를 true로 설정하여 teleport-cluster 차트를 설치하면, 차트가 Teleport Kubernetes Operator에 대한 하나 이상의 파드를 실행합니다. 또한 Teleport Kubernetes Operator가 Teleport 클러스터와 신뢰를 설정할 수 있는 조인 토큰(join token)과 Operator를 위한 Teleport 역할 및 Kubernetes 서비스 계정을 생성합니다. 마지막으로 teleport-operator 차트는 Operator가 Teleport 리소스를 관리할 수 있도록 하는 사용자 정의 리소스 정의(CRD)를 설치합니다.

사전 요구사항#

• Kubernetes 클러스터 (teleport-cluster Helm 차트 배포 여부에 관계없음);
• Helm
• kubectl

다음 명령을 실행하여 Kubernetes 연결을 확인합니다:

$ kubectl cluster-info
# Kubernetes control plane is running at https://127.0.0.1:6443
# CoreDNS is running at https://127.0.0.1:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
# Metrics-server is running at https://127.0.0.1:6443/api/v1/namespaces/kube-system/services/https:metrics-server:https/proxy

운영자를 로컬에서 실험하려는 사용자는 minikube를 사용하여 로컬 Kubernetes 클러스터를 시작할 수 있습니다:

$ minikube start

1단계/2단계: 운영자와 함께 teleport-cluster Helm 차트 설치#

Teleport Helm 리포지토리에서 Teleport 차트를 가져오도록 Helm을 구성하십시오.

$ helm repo add teleport (=teleport.helm_repo_url=)

최신 차트를 가져와 로컬 Helm 캐시를 새로 고치십시오.

$ helm repo update

teleport-cluster 네임스페이스에 operator.enabled=true로 Teleport 클러스터용 Helm 차트를 설치합니다:

Teleport Community Edition:

$ helm install teleport-cluster teleport/teleport-cluster \
        --create-namespace --namespace teleport-cluster \
        --set clusterName=teleport-cluster.teleport-cluster.svc.cluster.local \
        --set operator.enabled=true \
        --version (=teleport.version=)

Teleport Enterprise:

Teleport 클러스터 리소스를 위한 네임스페이스를 생성합니다:

$ kubectl create namespace teleport-cluster

Teleport Auth Service는 Teleport Enterprise 계정을 인증하기 위해 라이선스 파일을 읽습니다.

라이선스 파일을 얻으려면 Teleport 계정 대시보드로 이동하여 로그인하십시오. teleport.sh에서 시작하여 Teleport 계정 이름 (예: my-company)을 입력할 수 있습니다. 로그인한 후에는 "GENERATE LICENSE KEY" 버튼이 표시되며, 이 버튼을 클릭하면 새 라이선스 파일이 생성되어 다운로드할 수 있습니다.

생성한 네임스페이스에서 "license"라는 시크릿을 생성합니다:

$ kubectl -n teleport-cluster create secret generic license --from-file=license.pem

Teleport 클러스터와 Teleport Kubernetes Operator를 배포합니다:

$ helm install teleport-cluster teleport/teleport-cluster \
        --namespace teleport-cluster \
        --set enterprise=true \
        --set clusterName=teleport-cluster.teleport-cluster.svc.cluster.local \
        --set operator.enabled=true \
        --version (=teleport.version=)

이 명령은 필요한 Kubernetes CRD를 설치하고 Teleport 클러스터 옆에 Teleport Kubernetes Operator를 배포합니다. teleport-cluster 네임스페이스에 모든 리소스(클러스터 범위인 CRD 제외)가 생성됩니다.

2단계/2단계: 클러스터와 운영자가 실행 중이고 정상인지 확인#

$ kubectl get deployments -n teleport-cluster
#

$ kubectl get pods -n teleport-cluster
#

다음 단계#

새로 배포된 Teleport Kubernetes Operator를 사용하여 Teleport 사용자를 생성하고 역할을 부여하려면 사용자 및 역할 IaC 가이드를 따르세요.

Helm 차트 매개변수는 teleport-cluster Helm 차트 참조에 문서화되어 있습니다.

AWS 또는 GCP에서 Teleport 실행과 같은 특정 설정을 자세히 설명하는 Helm 배포 가이드를 참조하세요.

문제 해결#

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