독립형 Kubernetes Operator
Teleport v18.9이 가이드에서는 원격 Teleport 클러스터에 대해 Teleport Kubernetes Operator를 실행하는 방법을 설명합니다. Teleport Kubernetes Operator는 teleport-operator Helm 차트를 사용하여 설치하는 Teleport Auth Service 클라이언트입니다.
이 가이드에서는 원격 Teleport 클러스터에 대해 Teleport Kubernetes Operator를 실행하는 방법을 설명합니다. Teleport 클러스터가 teleport-cluster Helm 차트를 사용하여 배포된 경우 대신 Helm 배포 클러스터 가이드를 따를 수 있습니다.
작동 방식#
Teleport Kubernetes Operator는 teleport-operator Helm 차트를 사용하여 설치하는 Teleport Auth Service 클라이언트입니다.
Operator가 클러스터에서 Teleport 리소스를 관리하려면 Teleport 클러스터로 인증하고 Teleport 리소스를 관리할 권한을 부여해야 합니다. 이를 위해 이 가이드에서 생성 방법을 알려드리는 다음 추가 리소스가 필요합니다:
- Teleport 역할
- 조인 토큰(join token)
- 머신 & 워크로드 아이덴티티 봇
그런 다음 teleport-operator 차트를 설치하여 Operator를 배포할 수 있습니다.
사전 요구사항#
-
실행 중인 Teleport 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 구성하세요.
-
tctlandtshclients.Installing `tctl` and `tsh` clients
-
Teleport 클러스터의 버전을 확인합니다.
tctlandtshclients는 Teleport 클러스터 버전보다 최대 한 개의 메이저 버전까지만 뒤처질 수 있습니다. Proxy Service의/v1/webapi/find로 GET 요청을 보내고 JSON 쿼리 도구를 사용하여 클러스터 버전을 확인합니다.teleport.example.com:443를 Teleport Proxy Service의 웹 주소로 바꿉니다:$ TELEPORT_DOMAIN=teleport.example.com:443 $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" -
사용 중인 플랫폼에 대한 지침에 따라
tctlandtshclients를 설치합니다:
-
Mac
`tctl` and `tsh` clients가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
```code
$ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
```
Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.
Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
보장할 수 없습니다.
Windows - Powershell
```code
$ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
# Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
# NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
# Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
```
Linux
Linux 설치판의 모든 Teleport 바이너리에는 `tctl` and `tsh` clients가 포함되어 있습니다. RPM/DEB
패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
[설치 페이지](../installation/installation.mdx)를 참조하세요.
```code
$ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
$ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
$ cd teleport
$ sudo ./install
# Teleport binaries have been copied to /usr/local/bin
```
- Kubernetes 클러스터. Namespace, ServiceAccount, Deployment, Secret, Role, RoleBinding 및 CustomResourceDefinition 리소스를 생성/읽을 수 있어야 합니다.
- 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단계/4단계: 운영자 역할 생성#
이 단계에서는 운영자가 Teleport 리소스와 상호작용하는 데 사용하는 역할을 생성합니다.
운영자 역할 매니페스트를 다운로드하고 적용합니다:
$ curl -L https://raw.githubusercontent.com/gravitational/teleport/v(=teleport.version=)/integrations/operator/hack/fixture-operator-role.yaml -o operator-role.yaml
$ tctl create -f operator-role.yaml
참고: 새 Teleport 리소스에 대한 지원을 추가하는 새 버전으로 운영자를 업그레이드하는 경우 운영자 역할 매니페스트를 다시 적용해야 합니다. 이렇게 하면 운영자에게 새 리소스에 대한 접근 권한이 부여됩니다.
2단계/4단계: 운영자 조인 토큰 생성#
조인 토큰은 시작 시마다 운영자가 Teleport 클러스터에 조인하고 클라이언트 인증서를 검색하는 데 사용됩니다.
연결하는 운영자와 Teleport 간의 신뢰를 설정하기 위해 인증을 Kubernetes에 위임합니다. Kubernetes는 파드에 마운트된 ServiceAccount 토큰에 서명하는 자체 내부 CA를 가지고 있습니다. 다음 설정에서 Teleport는 Kubernetes가 서명한 SA 토큰을 신뢰하여 클러스터에 조인합니다.
- Kubernetes JWKS 검색(Teleport가 Kubernetes SA 토큰을 검증하는 데 사용할 수 있는 키)
$ export JWKS="$(kubectl get --raw /openid/v1/jwks)" - 네임스페이스 teleport-iac의 서비스 계정 teleport-iac-operator가 운영자로 클러스터에 조인할 수 있는 토큰 매니페스트를 생성합니다.
$ cat < operator-token.yaml kind: token version: v2 metadata: name: operator-bot spec: roles: [Bot] # bot_name will match the name of the bot created later in this guide. bot_name: operator join_method: kubernetes kubernetes: type: static_jwks static_jwks: jwks: | $JWKS allow: - service_account: "teleport-iac:teleport-operator" # namespace:serviceaccount EOF - 그런 다음 토큰 매니페스트를 적용합니다:
$ tctl create -f operator-token.yaml - 마지막으로 토큰을 사용하는 데 필요한 Teleport 클러스터 이름을 검색합니다:
$ export CLUSTER_NAME="$(tctl status | awk '/Cluster/ {print $2}')"
3단계/4단계: 운영자 봇 생성#
Teleport에서 봇(bot)은 머신이 Teleport에 접근할 수 있게 하는 리소스입니다. 다음 명령으로 운영자를 위한 봇을 생성합니다:
$ tctl bots add operator --token operator-bot --roles operator
4단계/4단계: Kubernetes 클러스터에 운영자 배포#
이 시점에서 운영자를 구성하고 실행할 수 있습니다:
Teleport Helm 리포지토리에서 Teleport 차트를 가져오도록 Helm을 구성하십시오.
$ helm repo add teleport (=teleport.helm_repo_url=)
최신 차트를 가져와 로컬 Helm 캐시를 새로 고치십시오.
$ helm repo update
- Teleport 클러스터 버전 검색
export TELEPORT_VERSION="$(tsh version | awk '/Proxy[[:space:]]version/ {print $3}')" echo "$TELEPORT_VERSION" - 운영자 파드와 Teleport를 구성할 CustomResources 모두를 포함할 Kubernetes 네임스페이스를 생성합니다:
$ kubectl create namespace teleport-iac - 네임스페이스에 가장 엄격한 Pod Security Standard를 적용합니다:
$ 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 차트 매개변수는 teleport-operator 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가 없음#
- CR이 operator와 동일한 namespace에 있는지 확인하십시오. operator는 자체 namespace의 리소스만 감시합니다.
- operator pod가 실행 중이고 정상 상태인지 확인하십시오:
kubectl get pods -n "$OPERATOR_NAMESPACE"` - 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