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

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

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

이 가이드에서는 Teleport 사용자가 Amazon RDS 데이터베이스를 Teleport 클러스터에 등록할 수 있도록 권한을 부여한 다음, Teleport Web UI를 사용하여 데이터베이스를 등록하기 위해 AWS OIDC 통합을 활성화합니다.

작동 방식#

AWS OIDC 통합#

RDS 등록 마법사는 AWS OIDC 통합에 의존합니다. AWS OIDC 통합은 AWS IAM OpenID Connect ID 공급자(OIDC IdP)와, Teleport 클러스터가 수임(assume)할 수 있는 AWS IAM 역할을 생성하고 구성합니다.

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

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

동적 데이터베이스 등록#

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

$ tctl get db/<database name>

Teleport Database Service 배포#

"Deploy Database Service" 단계에서 마법사는 ECS Fargate 배포를 생성하고 구성하는 과정을 안내합니다.

마법사는 실행할 스크립트를 생성하며, 이 스크립트는 Teleport Database Service 인스턴스가 사용할 IAM 역할을 생성합니다. 이 IAM 역할에는 ECS에서 로그를 출력하고, RDS 데이터베이스를 설명(describe)하며, RDS 데이터베이스에 연결할 수 있는 권한이 있습니다.

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

"Deploy Teleport Service"를 클릭하면 마법사는 Teleport Database Service 인스턴스를 구성하고 시작하기 위한 다양한 설정을 포함하는 ECS 작업 정의(task definition)를 생성합니다. 이 작업 정의는 첫 번째 단계에서 생성된 IAM 역할을 ECS 작업 실행 역할(ECS task execution role)과 ECS 작업 역할(ECS task role) 모두로 사용합니다.

이후 마법사는 RDS 데이터베이스와 동일한 AWS VPC 내에 ECS 배포를 생성하며, 선택한 서브넷과 보안 그룹을 사용하도록 구성합니다. 이 ECS 배포는 HA 구성을 위해 Teleport Database Service 작업 정의의 복제본(replica) 2개를 실행하도록 구성됩니다. Teleport Database Service 인스턴스를 RDS 데이터베이스와 동일한 VPC에 배포함으로써, 해당 인스턴스는 프라이빗 서브넷에 있는 데이터베이스에도 연결할 수 있습니다. 데이터베이스 보안 그룹 규칙 역시 ECS 작업으로부터의 인바운드 트래픽을 허용해야 한다는 점에 유의하세요.

ECS 작업이 시작되면 Teleport 이미지를 가져와 teleport를 시작합니다. 이후 Teleport Database Service 인스턴스는 Teleport 클러스터로 터널 연결을 설정하고, 프록시 대상 데이터베이스에 연결하려는 인가된 Teleport 사용자의 연결을 수락하기 시작합니다.

이는 Teleport Database Service를 배포하는 서버리스 HA 방식입니다. 인터넷으로부터의 인바운드 트래픽 허용이 전혀 필요하지 않으며, 에이전트 자동 업그레이드를 지원합니다.

Teleport Database Service 인스턴스는 동적 데이터베이스 등록을 사용하도록 구성되어 있으므로, 배포를 다시 시작하거나 수정하지 않고도 데이터베이스를 등록하거나 등록 해제할 수 있습니다. 이 인스턴스는 다음 라벨을 가진 Teleport 내 모든 동적 db 리소스와 일치시켜 해당 연결을 프록시합니다.

account-id: ""
region: ""
vpc-id: ""

마법사가 생성한 db 객체는 이러한 라벨을 갖게 되므로, Teleport Database Service 인스턴스가 이를 매칭하여 연결을 프록시합니다.

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 리소스를 검색할 수 있습니다. us-west-1를 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 ID 공급자와 역할을 생성할 수 있는 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단계. Web UI 접속#

RDS 등록 마법사는 Teleport Web UI의 "Add new resource" 패널에서 사용할 수 있습니다.

Teleport Web 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 서비스로 구성됩니다. 등록 마법사에서 선택한 VPC의 이름을 딴 서비스를 클릭하세요. VPC ID는 해당 ECS 서비스 이름의 접미사로 사용됩니다. 예를 들어 database-service-vpc-123456789abcdefgh와 같습니다.

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

작업이 보이지 않는다면, ECS 작업이 실행되지 않는 경우로 진행하세요.

Teleport Database Service 로그를 찾는 방법#

각 ECS 작업은 Teleport Database Service 작업 정의의 복제본입니다. ECS 서비스 작업 페이지로 이동하여 실행 중인 작업 중 하나를 클릭하세요. 작업 개요 페이지에서 "Logs" 패널을 클릭하면 Amazon CloudWatch로 전송되는 로그를 확인할 수 있습니다.

이 페이지에서는 새 출력을 보려면 로그를 새로고침해야 합니다. "View in CloudWatch"를 클릭한 다음 해당 페이지에서 로그 추적(tailing)을 시작하면 새 로그 출력을 자동으로 확인할 수 있습니다.

ECS 작업이 실행되지 않는 경우#

배포 내 작업이 "pending" 상태로 머물러 있거나 중지된 것을 발견하면, 개별 작업을 확인하여 무엇이 작업 시작을 막고 있는지 확인해야 합니다.

ECS 배포 작업 패널로 이동하여 "Filter desired status" 드롭다운을 선택하고 "Any desired status"를 선택하세요. 실행 중이지 않은 작업을 포함하여 모든 작업이 표시되어야 합니다.

중지된 작업을 클릭하여 중지된 이유를 확인하세요. AWS는 무엇이 잘못되었는지 설명하는 오류 메시지를 표시합니다.

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

가장 흔한 실패 원인은 작업이 Teleport 이미지를 가져오지(pull) 못하는 것입니다.

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 배포 롤아웃이 트리거되며, 이 롤아웃은 새 작업이 시작된 후에만 이전 배포의 실행 중인 작업을 종료합니다.

"Configuration and networking" 아래에 있는 ECS 서비스 네트워크 설정으로 이동하세요.

ECS 서비스의 보안 그룹이 아웃바운드 인터넷 접근을 허용하는지 확인하세요. AWS 보안 그룹 규칙은 추가적(additive)이라는 점을 기억하세요. 즉, 여러 보안 그룹을 선택한 경우 다음과 같은 아웃바운드 규칙이 그중 하나에만 있어도 Teleport 이미지 리포지터리로의 아웃바운드 연결을 설정할 수 있습니다.

다음으로, ECS 작업 서브넷이 인터넷에 접근할 수 있는지 확인하세요. 인터넷 게이트웨이 또는 NAT 게이트웨이로의 네트워크 경로가 있어야 합니다. 서브넷 목록을 메모해 둔 뒤 VPC 개요 페이지로 이동하여 각각을 확인하세요.

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

마지막으로, ECS 서비스의 서브넷과 연결된 네트워크 액세스 제어 목록(ACL)도 인터넷으로의 아웃바운드 트래픽을 허용하는지 확인하세요. 네트워크 ACL은 기본적으로 모든 인바운드 및 아웃바운드 트래픽을 허용하므로, 네트워크 ACL을 커스터마이즈한 경우에만 네트워크 문제의 잠재적 원인이 될 수 있습니다.

ECS 서비스에서 Teleport 이미지 리포지터리로의 네트워크 연결이 확립되면, ECS 작업은 얼마 후 자동으로 정상적으로 시작되어야 합니다.

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

데이터베이스 연결을 테스트했을 때 연결이 시간 초과되면, ECS 배포에서 해당 데이터베이스로의 네트워크 연결 문제를 해결해야 합니다.

예를 들어, AWS 보안 그룹이 연결을 차단하여 ECS 배포 작업이 RDS postgres 데이터베이스에 도달할 수 없을 때의 모습은 다음과 같습니다.

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

이 문제를 해결하는 가장 쉬운 방법은 RDS 데이터베이스의 보안 그룹 중 하나에, ECS 서비스와 연결된 보안 그룹 중 하나로부터의 트래픽을 허용하는 인바운드 규칙을 추가하는 것입니다. AWS에서는 다음과 같은 모습일 수 있습니다.

또한 AWS reachability analyzer를 실행하여 네트워크 문제를 진단할 수도 있습니다. ECS 서비스로 이동하여 작업 중 하나를 클릭한 다음, "Networking" 탭을 선택하고 "Run Reachability Analyzer"를 클릭하세요.

analyzer 경로 생성 페이지에서 "Path Source"는 ECS 작업의 AWS Elastic Network Interface(ENI)로 자동 채워집니다.

"Path destination"을 데이터베이스와 연결된 ENI로 설정하세요. 데이터베이스 ENI를 찾으려면 ENI 개요 페이지로 이동하여(올바른 AWS 리전이 선택되어 있는지 확인하세요) "RDS"를 검색하세요.

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

예를 들어, 데이터베이스 보안 그룹이 ECS 서비스 작업으로부터의 인바운드 트래픽을 허용하지 않을 때의 모습은 다음과 같습니다.

다음 단계#

• 특정 사용자 및 데이터베이스에 대한 접근을 제한하는 방법을 알아보십시오.

• 고가용성 (HA) 가이드를 확인하십시오.

• YAML 구성 레퍼런스를 살펴보십시오.

• 전체 CLI 레퍼런스를 참조하십시오.

• 자동 데이터베이스 사용자 프로비저닝 설정하기.