📣 Teleport의 공식 파트너 인포그랩에서 OpenAI 기술 기반으로 자체 개발한 자동화 번역 프로그램을 통해 Teleport 공식 문서(v17.0.0)의 한글판을 국내 최초로 제공합니다.
Infograb logo
AWS RDS 등록 마법사

AWS RDS 등록 마법사는 AWS OIDC 통합의 일부로 Teleport 클러스터 웹 UI에서 사용할 수 있습니다.

등록 마법사는 AWS IAM 리소스를 구성하고 Amazon RDS 데이터베이스에 대한 연결을 프록시하기 위해 ECS Fargate에서 Teleport 데이터베이스 서비스 인스턴스를 배포합니다.

등록 마법사는 RDS 데이터베이스를 Teleport 클러스터에 등록하는 데 사용할 수 있습니다. 또한 ECS에서 서버리스 Teleport 데이터베이스 서비스 배포의 예로 유용합니다.

작동 방식

AWS OIDC 통합

RDS 등록 마법사는 AWS OIDC 통합에 의존합니다. AWS OIDC 통합은 Teleport 클러스터가 가정할 수 있는 AWS IAM OpenID Connect 신원 제공자 (OIDC IdP) 및 AWS IAM 역할을 생성하고 구성합니다.

RDS 등록 마법사는 RDS 데이터베이스 목록과 서브넷, 보안 그룹과 같은 VPC 리소스를 나열하고 Amazon ECS 서비스를 배포할 수 있는 권한을 AWS OIDC 통합 IAM 역할에 추가합니다.

통합 역할의 권한이 구성되면, 마법사는 데이터베이스를 등록하고 Amazon ECS에서 고가용성(HA) 설정으로 Teleport 데이터베이스 서비스를 배포하는 과정을 안내합니다.

동적 데이터베이스 등록

단일 데이터베이스를 등록하기로 선택하든 자동 검색을 사용하여 모든 데이터베이스를 등록하기로 선택하든, 마법사는 Teleport 클러스터에 db 개체를 생성하여 데이터베이스를 등록합니다. 자세한 정보는 tctl 을 사용하여 확인할 수 있습니다:

tctl get db/<데이터베이스 이름>

Teleport 데이터베이스 서비스 배포

"데이터베이스 서비스 배포" 단계에서, 마법사는 ECS Fargate 배포를 생성하고 구성하는 과정을 안내합니다.

마법사는 Teleport 데이터베이스 서비스 인스턴스가 사용할 IAM 역할을 생성하는 스크립트를 생성합니다. IAM 역할은 ECS에서 로그를 출력하고, RDS 데이터베이스를 설명하고, RDS 데이터베이스에 연결할 수 있는 권한을 가집니다.

그 후, ECS Fargate에서 배포를 위해 서브넷과 보안 그룹을 선택합니다.

"Teleport 서비스 배포"를 클릭하면 마법사는 Teleport 데이터베이스 서비스 인스턴스를 구성하고 시작하기 위한 다양한 설정을 포함하는 ECS 태스크 정의를 생성합니다. 태스크 정의는 첫 번째 단계에서 생성된 IAM 역할을 ECS 태스크 실행 역할 및 ECS 태스크 역할로 사용합니다.

마법사는 또한 RDS 데이터베이스와 동일한 AWS VPC에 ECS 배포를 생성하며, 선택한 서브넷과 보안 그룹을 사용하도록 구성됩니다. ECS 배포는 HA 설정을 위해 Teleport 데이터베이스 서비스 태스크 정의의 두 개 복제본을 실행하도록 구성됩니다. RDS 데이터베이스와 동일한 VPC에 Teleport 데이터베이스 서비스 인스턴스를 배포함으로써, 인스턴스는 프라이빗 서브넷의 데이터베이스에 연결할 수 있습니다. 데이터베이스 보안 그룹 규칙은 ECS 태스크에서의 수신 트래픽을 허용해야 합니다.

ECS 태스크가 시작되면 Teleport 이미지를 가져오고 teleport 를 시작합니다. Teleport 데이터베이스 서비스 인스턴스는 Teleport 클러스터에 터널 연결을 설정하고 데이터베이스에 연결하기 위해 권한이 있는 Teleport 사용자로부터의 연결을 수신하기 시작합니다.

이는 Teleport 데이터베이스 서비스를 배포하는 서버리스 HA 접근 방식입니다. 인터넷에서의 허용된 수신 트래픽이 필요하지 않으며, 자동 에이전트 업그레이드를 지원합니다.

Teleport 데이터베이스 서비스 인스턴스는 동적 데이터베이스 등록을 사용하도록 구성되어 있어, 배포를 재시작하거나 수정하지 않고도 데이터베이스를 등록하거나 등록 해제할 수 있습니다. 인스턴스는 다음 레이블을 가진 Teleport의 모든 동적 db 리소스에 대해 연결을 매칭하고 프록시합니다:

account-id: "<AWS 계정 ID>"
region: "<AWS 리전>"
vpc-id: "<AWS VPC ID>"

마법사에 의해 생성된 db 개체는 이러한 레이블을 가지므로, Teleport 데이터베이스 서비스 인스턴스는 이를 매칭하여 연결을 프록시합니다.

AWS 리소스 태그

RDS 등록 마법사에 의해 생성된 AWS 리소스는 AWS에 태그가 추가되어 있어 AWS Resource Groups / Tag Editor를 사용하여 검색하고 내보낼 수 있습니다. 아래의 태그가 적용됩니다:

teleport.dev/cluster: cluster-name
teleport.dev/origin: integration_awsoidc
teleport.dev/integration: my-integration

또한 aws CLI를 사용하여 마법사에 의해 생성된 AWS 리소스를 검색할 수 있습니다:

aws resourcegroupstaggingapi get-resources \--region us-west-1 \--tag-filters \Key=teleport.dev/cluster,Values=cluster-name \Key=teleport.dev/integration,Values=my-integration \Key=teleport.dev/origin,Values=integration_awsoidc

전제 조건

  • 실행 중인 Teleport 클러스터
  • IAM 신원 공급자 및 역할을 생성할 수 있는 권한이 있는 AWS 계정

1/2단계. RBAC 구성

RDS 등록 마법사는 AWS OIDC 통합의 일부입니다. 당신은 Teleport 역할 중 하나에서 다음의 허용 규칙이 필요합니다. 이 규칙은 기본적으로 'editor' 역할의 미리 설정된 규칙에서 사용할 수 있습니다:

kind: role
version: v7
metadata:
  name: example
spec:
  allow:
    rules:
      - resources:
          - integration
        verbs:
          - create
          - update
          - list
          - read

2/2단계. 웹 UI 방문

RDS 등록 마법사는 Teleport 웹 UI의 "새 리소스 추가" 패널에서 사용할 수 있습니다:

Teleport 웹 UI는 AWS OIDC 통합을 설정하는 단계를 안내합니다 (아직 없다면), IAM 권한을 구성하고, AWS 계정에서 ECS 배포를 생성하며, 데이터베이스 연결 테스트를 실행합니다.

문제 해결

등록 마법사는 ECS 배포 작업이 시작되어 Teleport 클러스터에 연결되기를 기다립니다. 이 작업이 발생하지 않으면 ECS 작업이 시작되지 않았거나 Teleport 클러스터와 네트워크 연결이 없을 수 있습니다. 문제를 더 자세히 조사하기 위해 ECS 배포를 점검해야 합니다.

아래의 문제 해결 단계는 이미 ECS 배포를 찾고 ECS에서 발생하고 있는 정보에 대해 알고 있다고 가정합니다. ECS 배포를 찾는 방법을 모른다면, 먼저 ECS 배포 찾는 방법에 대해 읽어보십시오.

ECS 배포 찾는 방법

AWS의 ECS 서비스로 이동하십시오: https://console.aws.amazon.com/ecs/v2/clusters. RDS 등록 마법사 시작 시 선택한 동일한 AWS 리전을 선택해야 합니다.

마법사가 생성한 ECS 클러스터는 Teleport 클러스터의 이름을 따르며 점 .은 언더스코어 _ 로 변환되고 추가 접미사 -teleport 가 붙습니다. 예를 들어, Teleport 클러스터의 이름이 example.teleport.sh 라면, 해당 ECS 클러스터의 이름은 example_teleport_sh-teleport 가 됩니다.

ECS 클러스터를 클릭하십시오:

ECS 클러스터 개요 스크린샷

ECS 클러스터는 하나 이상의 ECS 서비스로 구성됩니다. 등록 마법사에서 선택한 VPC의 이름을 가진 서비스를 클릭하십시오 - VPC ID가 해당 ECS 서비스 이름의 접미사로 사용됩니다, 예: database-service-vpc-123456789abcdefgh :

ECS 서비스 개요 스크린샷

ECS 서비스 개요 페이지에서 "작업" 패널을 클릭하여 배포 작업을 확인하십시오. 두 개의 작업이 실행 중이거나 대기 중이어야 합니다:

작업이 보이지 않으면 ECS 작업이 실행되지 않음으로 이동하십시오.

Teleport 데이터베이스 서비스 로그 찾는 방법

각 ECS 태스크는 Teleport 데이터베이스 서비스 태스크 정의의 복제본입니다.
ECS 서비스 태스크 페이지로 이동하기
실행 중인 태스크 중 하나를 클릭하십시오.
태스크 개요 페이지에서 "로그" 패널을 클릭하여 Amazon CloudWatch에 출력되는 로그를 확인하십시오:

이 페이지에서는 새 출력을 보려면 로그를 새로 고쳐야 합니다.
"CloudWatch에서 보기"를 클릭한 후 해당 페이지에서 로그를 수신하기 시작하여 새로운 로그 출력을 자동으로 감시할 수 있습니다.

실행 중이지 않은 ECS 태스크

배포의 태스크가 "보류 중" 상태로 남아 있거나 중지된 것을 보았다면, 개별 태스크를 확인하여 시작을 방해하는 것이 무엇인지 살펴보아야 합니다.

ECS 배포 태스크 패널로 이동하여, "원하는 상태 필터" 드롭다운을 선택하고 "원하는 상태 모두"를 선택합니다.
이제 실행 중이지 않은 태스크를 포함하여 모든 태스크를 볼 수 있어야 합니다:

중지된 태스크를 클릭하여 왜 중지되었는지 확인하십시오. AWS는 문제가 무엇인지 설명하는 오류 메시지를 표시합니다.

일반적으로 오류 메시지는 태스크가 ECS에 의해 중지된 후에만 나타나며, 이는 "보류 중" 상태에 진입한 후 몇 분이 걸릴 수 있습니다.

가장 일반적인 오류는 태스크가 Teleport 이미지를 가져올 수 없다는 것입니다:

CannotPullContainerError: pull image manifest has been retried 5 time(s): failed to resolve ref public.ecr.aws/gravitational/teleport-ent-distroless:16.4.3: failed to do request: Head "https://public.ecr.aws/v2/gravitational/teleport-ent-distroless/manifests/16.4.3": dial tcp 99.83.145.10:443: i/o timeout

이는 ECS 태스크가 공용 Teleport 이미지 리포지토리에 도달하는 것을 방해하는 네트워크 연결 문제로 인해 발생합니다.

배포를 위해 다른 보안 그룹이나 서브넷을 사용해야 할 수 있지만, AWS 콘솔에서 ECS 서비스 네트워킹 구성을 업데이트할 수는 없습니다.
다행히도, Teleport의 RDS 등록 마법사에서 ECS 서비스를 재배포하면 업데이트된 네트워크 설정으로 ECS 서비스를 다시 생성할 것입니다.
이렇게 하면 새로운 ECS 배포 롤아웃이 트리거되며, 이는 새 태스크가 시작된 후에만 이전 배포에서 실행 중인 태스크를 종료합니다.

"구성 및 네트워킹" 아래에 있는 ECS 서비스 네트워크 설정으로 이동합니다:

ECS 서비스의 보안 그룹이 아웃바운드 인터넷 액세스를 허용하는지 확인하십시오.
AWS 보안 그룹 규칙은 추가적이므로 여러 보안 그룹을 선택한 경우, 다음과 같은 아웃바운드 규칙이 있는 보안 그룹 중 하나만 필요합니다:

아웃바운드 인터넷 트래픽을 허용하는 보안 그룹 규칙 스크린샷

다음으로, ECS 태스크 서브넷이 인터넷에 접근할 수 있는지 확인하십시오.
인터넷 게이트웨이나 NAT 게이트웨이에 대한 네트워크 경로가 있어야 합니다.
서브넷 목록을 메모해 두고 VPC 개요 페이지로 이동하여 각 서브넷을 확인하십시오:

NAT 게이트웨이나 인터넷 게이트웨이를 생성하거나, 라우팅 테이블을 업데이트하거나, ECS 서비스에 다른 서브넷을 사용해야 할 수 있습니다.

마지막으로, ECS 서비스의 서브넷과 관련된 네트워크 접근 제어 목록(ACL)이 인터넷으로의 아웃바운드 트래픽을 허용하는지 확인하십시오.
네트워크 ACL은 기본적으로 모든 인바운드 및 아웃바운드 트래픽을 허용하므로, 네트워크 ACL을 사용자 지정한 경우에만 네트워크 문제의 잠재적 원인이 될 수 있습니다.

ECS 서비스에서 Teleport 이미지 리포지토리에 대한 네트워크 연결이 설정되면, ECS 태스크는 시간이 지나면서 성공적으로 자동으로 시작되어야 합니다.

데이터베이스 연결 테스트 시간 초과

데이터베이스에 대한 연결을 테스트하고 연결이 시간 초과되면, ECS 배포에서 데이터베이스로의 네트워크 연결을 수정해야 합니다.

예를 들어, AWS 보안 그룹이 연결을 차단하고 있을 때 ECS 배포 작업이 RDS postgres 데이터베이스에 도달하지 못하는 모습은 다음과 같습니다:

이 오류의 가장 흔한 원인은 RDS 데이터베이스에 연결된 보안 그룹 규칙이 ECS 작업으로부터의 수신 트래픽을 허용하지 않기 때문입니다.

이 문제를 간단히 해결하는 방법은 RDS 데이터베이스의 보안 그룹 중 하나에 ECS 서비스와 연결된 보안 그룹으로부터의 트래픽을 허용하는 수신 규칙을 추가하는 것입니다. AWS에서 이와 같은 모습일 수 있습니다:

또한 AWS 도달 가능성 분석기를 실행하여 네트워크 문제를 진단할 수 있습니다. ECS 서비스로 이동하여 작업 중 하나를 클릭한 다음, "네트워킹" 탭을 선택하고 "도달 가능성 분석기 실행"을 클릭하십시오:

분석기 경로 생성 페이지에서 "경로 소스"는 ECS 작업의 AWS Elastic Network Interface (ENI)로 자동으로 채워져야 합니다.

"경로 목적지"를 데이터베이스와 연결된 ENI로 설정하십시오. 데이터베이스 ENI를 찾으려면 ENI 개요로 이동하십시오 (올바른 AWS 지역이 선택되어 있는지 확인하십시오) 그리고 "RDS"를 검색하십시오.

네트워크 분석기 경로를 생성하고 실행하십시오. 잠시 후 분석 결과를 볼 수 있지만, 몇 번 새로 고침 아이콘을 클릭해야 할 수도 있습니다.

예를 들어, 데이터베이스 보안 그룹이 ECS 서비스 작업으로부터의 수신 트래픽을 허용하지 않을 때는 다음과 같이 보입니다:

예제 네트워크 분석기 결과 스크린샷

다음 단계

  • YAML 구성 참조를 살펴보십시오.
  • 전체 CLI 참조를 확인하십시오.
Teleport 원문 보기
인포레터에서 최신 DevOps 트렌드를 격주로 만나보세요!