독립형 Kubernetes 운영자 | Teleport 공식 기술 문서 한국판 by 인포그랩

독립형 Kubernetes 운영자

이 가이드는 Teleport Kubernetes 운영자를 원격 Teleport 클러스터에 대해 실행하는 방법을 설명합니다.
teleport-cluster Helm 차트를 사용하여 Teleport 클러스터를 배포한 경우,
Helm 배포 클러스터에 대한 가이드를 대신 따르는 것이 좋습니다.

필수 조건

실행 중인 Teleport 클러스터 버전 17.0.0-dev 이상. Teleport를 시작하려면 가입하여 무료 평가판을 이용하거나 데모 환경 설정 방법을 확인하십시오.
tctl 관리자 도구와 tsh 클라이언트 도구.

tctl 및 tsh 다운로드 방법에 대한 지침은 설치를 방문하십시오.

Kubernetes 클러스터. Namespace, ServiceAccount, Deployment, Secret, Role, RoleBinding 및 CustomResourceDefinition 리소스를 생성/읽을 수 있어야 합니다.
Helm
kubectl
최소 버전 15에서 실행 중인 Teleport 클러스터.

Kubernetes 연결을 확인하려면 다음 명령을 실행하십시오:

kubectl cluster-info
Kubernetes 제어 플레인은 https://127.0.0.1:6443 에서 실행 중입니다.
CoreDNS는 https://127.0.0.1:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy 에서 실행 중입니다.
Metrics-server는 https://127.0.0.1:6443/api/v1/namespaces/kube-system/services/https:metrics-server:https/proxy 에서 실행 중입니다.

Tip

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

minikube start

1/4단계. 운영자 역할 생성

이 단계에서는 운영자가 Teleport 리소스와 상호 작용하는 데 사용하는 역할을 생성합니다.

운영자 역할 매니페스트를 다운로드하고 적용합니다:

curl -L https://raw.githubusercontent.com/gravitational/teleport/v17.0.0-dev/integrations/operator/hack/fixture-operator-role.yaml -o operator-role.yaml
tctl create -f operator-role.yaml

Note

운영자를 새로운 버전으로 업그레이드하여 새로운 Teleport 리소스에 대한 지원을 추가하는 경우, 운영자 역할 매니페스트를 다시 적용해야 합니다. 이렇게 하면 운영자가 새로운 리소스에 대한 액세스 권한을 부여받습니다.

2/4단계. 운영자 조인 토큰 생성

조인 토큰은 운영자가 각 시작 시 Teleport 클러스터에 조인하고 클라이언트 인증서를 검색하는 데 사용됩니다.

연결된 운영자와 Teleport 간의 신뢰를 설정하기 위해 Kubernetes에 인증을 위임하고 있습니다. Kubernetes에는 내부 CA가 있으며, 이 CA는 팟에 마운트된 ServiceAccount 토큰에 서명합니다. 다음 설정에서, Teleport는 클러스터에 조인하기 위해 Kubernetes가 서명한 SA 토큰을 신뢰합니다.

Kubernetes JWKS(예약한 Teleport가 Kubernetes SA 토큰을 검증하는 데 사용할 수 있는 키)를 검색합니다.
```
export JWKS="$(kubectl get --raw /openid/v1/jwks)"
```

namespace teleport-iac에서 serviceaccount teleport-iac-operator가 운영자로서 클러스터에 조인할 수 있도록 허용하는 토큰 매니페스트를 생성합니다.

cat <<EOF > operator-token.yamlkind: tokenversion: v2metadata:  name: operator-botspec:  roles: [Bot]  # bot_name은 이 가이드에서 나중에 생성될 봇의 이름과 일치해야 합니다.  bot_name: operator  join_method: kubernetes  kubernetes:    type: static_jwks    static_jwks:      jwks: |        $JWKS    allow:    - service_account: "teleport-iac:teleport-operator" # namespace:serviceaccountEOF

그런 다음 토큰 매니페스트를 적용합니다:
```
tctl create -f operator-token.yaml
```
마지막으로 토큰 사용에 필요한 Teleport 클러스터 이름을 검색합니다:
```
export CLUSTER_NAME="$(tctl status | awk '/Cluster/ {print $2}')"
```

3/4단계. 운영자 봇 생성

Teleport에서 봇은 머신이 Teleport에 접근할 수 있도록 허용하는 자원입니다. 다음 명령어로 운영자 봇을 생성합니다:

tctl bots add operator --token operator-bot --roles operator

4/4단계. Kubernetes 클러스터에 운영자 배포

이 시점에서 운영자를 구성하고 실행할 수 있습니다:

Teleport Helm 저장소를 설정합니다.

Helm이 Teleport Helm 저장소에서 호스팅되는 차트를 설치할 수 있도록 허용합니다:

helm repo add teleport https://charts.releases.teleport.dev

원격 저장소의 차트 캐시를 업데이트하여 모든 사용 가능한 릴리스로 업그레이드할 수 있습니다:

helm repo update

Teleport 클러스터의 버전을 확인합니다.

export TELEPORT_VERSION="$(tsh version | awk '/Proxy[[:space:]]version/ {print $3}')"echo "$TELEPORT_VERSION"

운영자 Pods와 Teleport를 구성할 CustomResources를 포함할 Kubernetes 네임스페이스를 생성합니다:
```
kubectl create namespace teleport-iac
```

네임스페이스에 가장 엄격한 Pod 보안 표준을 적용합니다:

kubectl label namespace teleport-iac 'pod-security.kubernetes.io/enforce=restricted'

Helm을 사용하여 운영자를 배포합니다:

helm install teleport-operator teleport/teleport-operator -n teleport-iac --version "$TELEPORT_VERSION" --set teleportAddress=teleport.example.com:443 --set "teleportClusterName=$CLUSTER_NAME" --set token=operator-bot

운영자가 제대로 실행되고 있는지 확인합니다 (운영자가 시작되는데 몇 초가 걸릴 수 있습니다):
```
kubectl get pods -n teleport-iac
```

다음 단계

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

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

문제 해결

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에 상태가 없습니다

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을 삭제할 수 없습니다

운영자는 최종자(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
```

Teleport 원문 보기