Fluentd는 통합 로깅 계층을 위한 오픈 소스 데이터 수집기입니다. 이 가이드에서는:

• Teleport의 이벤트 핸들러 플러그인을 설정합니다.
• Fluentd로 이벤트를 전달합니다.

이 가이드는 또한 Teleport 이벤트 핸들러 플러그인을 설명하는 역할을 하며, Fluentd를 대상 서비스로 사용합니다. 우리는 로컬 Docker 컨테이너를 이벤트 핸들러의 대상으로 생성할 것입니다:

아래 지침을 따라 로컬 개념 증명 데모를 진행하거나, 인프라에 통합할 수 있도록 Teleport 이벤트 핸들러를 구성하는 추가 설치 지침을 사용할 수 있습니다.

전제 조건

• 실행 중인 Teleport 클러스터 버전 이상. Teleport를 시작하려면, 가입하기 위해 무료 평가판에 등록하거나 데모 환경 설정하기를 참조하세요.

• tctl 관리 도구와 tsh 클라이언트 도구.

  tctl과 tsh 다운로드에 대한 지침은 설치를 방문하세요.

권장 사항: 짧은 수명의 Teleport 자격 증명을 플러그인에 제공하기 위해 머신 ID를 구성하십시오. 이 가이드를 따르기 전에 tbot 바이너리를 귀하의 인프라에서 실행하기 위해 머신 ID 배포 가이드를 따르십시오.

• Fluentd 버전 v1.12.4 이상.

• Docker 버전 v20.10.7.

• 당신의 Teleport 클러스터에 연결할 수 있는지 확인하려면, tsh login으로 로그인한 다음 현재 자격 증명을 사용하여 tctl 명령어를 실행할 수 있는지 확인하십시오.

  예를 들어:

  tsh login --proxy=teleport.example.com --user=email@example.com
  tctl status
  클러스터  teleport.example.com
  버전  16.2.0
  CA 핀   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

  클러스터에 연결하고 tctl status 명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 작업대에서 후속 tctl 명령어를 실행할 수 있습니다.

  자신의 Teleport 클러스터를 호스팅하는 경우, Teleport 인증 서비스를 호스팅하는 컴퓨터에서 전체 권한으로 tctl 명령어를 실행할 수도 있습니다.

• 작업 공간에 event-handler라는 폴더를 생성하여 구성 파일과 플러그인 상태를 저장합니다:

  mkdir -p event-handler
  cd event-handler

1단계/6. 이벤트 핸들러 플러그인 설치

Teleport 이벤트 핸들러는 Fluentd 포워더와 함께 실행되며, Teleport의 이벤트 API에서 이벤트를 수신하고 이를 Fluentd로 전달합니다.

curl -L -O https://cdn.teleport.dev/teleport-event-handler-v16.2.0-linux-ARCH-bin.tar.gz
tar -zxvf teleport-event-handler-v16.2.0-linux-ARCH-bin.tar.gz
sudo ./teleport-event-handler/install

curl -L -O https://cdn.teleport.dev/teleport-event-handler-v16.2.0-darwin-ARCH-bin.tar.gz
tar -zxvf teleport-event-handler-v16.2.0-darwin-ARCH-bin.tar.gz
sudo ./teleport-event-handler/install

docker pull public.ecr.aws/gravitational/teleport-plugin-event-handler:16.2.0

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

helm repo update

git clone https://github.com/gravitational/teleport.git --depth 1 -b branch/v16
cd teleport/integrations/event-handler
make build

2단계/6. 플러그인 구성 생성

teleport-event-handler configure . mytenant.teleport.sh:443

teleport-event-handler configure . teleport.example.com:443

TELEPORT_CLUSTER_ADDRESS=mytenant.teleport.sh:443
docker run -v `pwd`:/opt/teleport-plugin -w /opt/teleport-plugin public.ecr.aws/gravitational/teleport-plugin-event-handler:16.2.0 configure . ${TELEPORT_CLUSTER_ADDRESS?}

kubectl create secret generic teleport-event-handler-client-tls --from-file=ca.crt=ca.crt,client.crt=client.crt,client.key=client.key

docker run -v `pwd`:/opt/teleport-plugin -w /opt/teleport-plugin public.ecr.aws/gravitational/teleport-plugin-event-handler:16.2.0 configure .

다음 출력을 볼 수 있습니다:

Teleport event handler 16.2.0

[1] mTLS Fluentd 인증서가 생성되어 ca.crt, ca.key, server.crt, server.key, client.crt, client.key에 저장되었습니다.
[2] 샘플 teleport-event-handler 역할 및 사용자 파일 teleport-event-handler-role.yaml이 생성되었습니다.
[3] 샘플 fluentd 구성 파일 fluent.conf가 생성되었습니다.
[4] 플러그인 구성 파일 teleport-event-handler.toml이 생성되었습니다.

플러그인은 여러 설정 파일을 생성합니다:

ls -l
-rw------- 1 bob bob     1038 Jul  1 11:14 ca.crt
-rw------- 1 bob bob     1679 Jul  1 11:14 ca.key
-rw------- 1 bob bob     1042 Jul  1 11:14 client.crt
-rw------- 1 bob bob     1679 Jul  1 11:14 client.key
-rw------- 1 bob bob      541 Jul  1 11:14 fluent.conf
-rw------- 1 bob bob     1078 Jul  1 11:14 server.crt
-rw------- 1 bob bob     1766 Jul  1 11:14 server.key
-rw------- 1 bob bob      260 Jul  1 11:14 teleport-event-handler-role.yaml
-rw------- 1 bob bob      343 Jul  1 11:14 teleport-event-handler.toml

teleport-event-handler configure --cn=handler.example.com --dns-names=forwarder.example.com

TLS가 있는 기존 Fluentd 설치가 있는 경우, Teleport 이벤트 핸들러가 사용할 수 있도록 동일한 인증 기관에서 클라이언트 인증서 및 키를 발급합니다.

3단계/6. 감사 이벤트를 읽기 위한 사용자 및 역할 생성

teleport-event-handler configure 명령어는 teleport-event-handler-role.yaml이라는 파일을 생성했습니다. 이 파일은 teleport-event-handler 역할과 event API에 대한 읽기 전용 접근 권한을 가진 사용자를 정의합니다:

kind: role
metadata:
  name: teleport-event-handler
spec:
  allow:
    rules:
      - resources: ['event', 'session']
        verbs: ['list','read']
version: v5
---
kind: user
metadata:
  name: teleport-event-handler
spec:
  roles: ['teleport-event-handler']
version: v2

이 파일을 작업 공간으로 이동시키거나 (위의 스니펫을 붙여넣어) 재생성하고, 작업 공간에서 tctl을 사용하여 역할과 사용자를 생성하세요:

tctl create -f teleport-event-handler-role.yaml
사용자 "teleport-event-handler"가 생성되었습니다
역할 'teleport-event-handler'가 생성되었습니다

4단계/6. teleport-event-handler 자격 증명 생성

이벤트 핸들러 역할에 대한 자격 증명 발급 활성화

tctl bots update my-bot --add-roles teleport-event-handler

kind: role
version: v5
metadata:
  name: teleport-event-handler-impersonator
spec:
  options:
    # max_session_ttl은 이 역할을 가진 사용자에게 발급된 SSH 인증서의 TTL(유효 기간)을 정의합니다.
    max_session_ttl: 10h

  # 이 섹션은 이 역할의 사용자에게 허용되는 리소스/동작 조합 목록을 선언합니다.
  # 기본적으로 아무것도 허용되지 않습니다.
  allow:
    impersonate:
      users: ["teleport-event-handler"]
      roles: ["teleport-event-handler"]

tctl create teleport-event-handler-impersonator.yaml

Fluentd 플러그인 사용자에 대한 신원 파일 내보내기

플러그인에 Teleport 신원 파일에 대한 액세스를 부여합니다. 우리는 안전성을 위해 Machine ID를 사용하는 것을 권장하며, 유출 시 위험이 덜한 짧은 유효 기간의 신원 파일을 생성할 수 있지만, 데모 배포에서는 tctl로 장기 유효 신원 파일을 생성할 수 있습니다:

outputs:
- type: identity
  destination:
    type: directory
    # 이 가이드에서는 /opt/machine-id를 목적지 디렉토리로 사용합니다.
    # 필요에 따라 사용자 정의할 수 있습니다. 여러 출력은 동일한
    # 대상을 공유할 수 없습니다.
    path: /opt/machine-id

outputs:
  - type: identity
    destination:
      type: kubernetes_secret
      name: teleport-event-handler-identity

tctl auth sign --user=teleport-event-handler --out=identity

tsh login --proxy=teleport.example.com --ttl=60060

sudo mkdir -p /var/lib/teleport/api-credentials
sudo mv identity /var/lib/teleport/plugins/api-credentials

kubectl -n teleport create secret generic --from-file=identity teleport-event-handler-identity

5단계/6. Fluentd 포워더 시작

Fluentd 플러그인은 이전 단계에서 생성된 키를 사용하여 이벤트를 Fluentd 인스턴스에 전달합니다.

앞서 생성된 fluent.conf 파일은 TLS를 사용하여 이벤트를 수신하고 이를 출력하도록 Fluentd 인스턴스를 구성합니다:

<source>
    @type http
    port 8888

    <transport tls>
        client_cert_auth true

        # 우리는 Docker에서 fluentd를 실행할 것입니다. /keys는 호스트 파일 시스템에서 마운트됩니다.
        ca_path /keys/ca.crt
        cert_path /keys/server.crt
        private_key_path /keys/server.key
        private_key_passphrase ********** # 키와 함께 생성된 비밀번호
    </transport>

    <parse>
      @type json
      json_parser oj

      # 이 시간 형식은 플러그인에서 사용됩니다. 이 필드는 필수입니다.
      time_type string
      time_format %Y-%m-%dT%H:%M:%S
    </parse>

    # 이벤트 수가 많아지면 fluentd는 다음 오류 메시지와 함께 수집을 실패하기 시작합니다:
    # buffer space has too many data errors.
    # 다음 구성은 재시작 시 데이터 손실을 방지하고 기본 fluentd 버퍼 구성의 한계를 극복합니다.
    # 이 구성은 선택적입니다.
    # 자세한 내용은 https://docs.fluentd.org/configuration/buffer-section를 참고하세요.
    <buffer>
      @type file
      flush_thread_count 8
      flush_interval 1s
      chunk_limit_size 10M
      queue_limit_length 16
      retry_max_interval 30
      retry_forever true
    </buffer>
</source>

# test.log에 전송된 이벤트는 STDOUT에 출력됩니다.
<match test.log>
  @type stdout
</match>

이 Fluentd 구성을 사용해 보려면, fluentd 인스턴스를 시작하세요:

docker run -u $(id -u ${USER}):$(id -g ${USER}) -p 8888:8888 -v $(pwd):/keys -v $(pwd)/fluent.conf:/fluentd/etc/fluent.conf fluent/fluentd:edge

이것은 현재 터미널을 사용하게 되므로, 계속 진행하기 위해 새로운 터미널을 여는 것이 좋습니다.

6단계/6. 이벤트 핸들러 플러그인 실행

이벤트 핸들러 구성

이 섹션에서는 귀하의 환경에 맞게 Teleport 이벤트 핸들러를 구성할 것입니다.

storage = "./storage"
timeout = "10s"
batch = 20
namespace = "default"
# 창 크기는 이벤트 핸들러가 Teleport로부터 이벤트를 요청하는 
# 시간 창의 지속 시간을 구성합니다. 기본적으로, 이는 24시간으로 설정됩니다.
# 기본 창 크기에 대해 이벤트 볼륨을 관리할 수 없는 경우
# 창 크기를 줄이세요.
# 창 크기는 Go의 time.ParseDuration으로 구문 분석된 지속 시간 문자열로 지정해야 합니다.
window-size = "24h"

[forward.fluentd]
ca = "/home/bob/event-handler/ca.crt"
cert = "/home/bob/event-handler/client.crt"
key = "/home/bob/event-handler/client.key"
url = "https://fluentd.example.com:8888/test.log"
session-url = "https://fluentd.example.com:8888/session"

[teleport]
addr = "example.teleport.com:443"
identity = "identity"

eventHandler:
  storagePath: "./storage"
  timeout: "10s"
  batch: 20
  namespace: "default"
  # 창 크기는 이벤트 핸들러가 Teleport로부터 이벤트를 요청하는 
  # 시간 창의 지속 시간을 구성합니다. 기본적으로, 이는 24시간으로 설정됩니다.
  # 기본 창 크기에 대해 이벤트 볼륨을 관리할 수 없는 경우 
  # 창 크기를 줄이세요.
  # 창 크기는 Go의 time.ParseDuration으로 구문 분석된 지속 시간 문자열로 지정해야 합니다.
  windowSize: "24h"

teleport:
  address: "example.teleport.com:443"
  identitySecretName: teleport-event-handler-identity
  identitySecretPath: identity

fluentd:
  url: "https://fluentd.fluentd.svc.cluster.local/events.log"
  sessionUrl: "https://fluentd.fluentd.svc.cluster.local/session.log"
  certificate:
    secretName: "teleport-event-handler-client-tls"
    caPath: "ca.crt"
    certPath: "client.crt"
    keyPath: "client.key"

persistentVolumeClaim:
  enabled: true

다음으로, 구성 파일을 다음과 같이 수정합니다:

이벤트 핸들러에 tbot 바이너리를 사용하여 자격 증명을 제공하는 경우, 리눅스 서버에서 실행됩니다. 이벤트 핸들러 구성의 identity 값이 tbot이 생성하도록 구성한 아이덴티티 파일의 경로인 /opt/machine-id/identity와 동일한지 확인하세요.

Teleport 이벤트 핸들러 시작

Teleport 이벤트 핸들러를 시작하려면 아래 지침을 따르세요.

[Unit]
Description=Teleport Event Handler
After=network.target

[Service]
Type=simple
Restart=always
ExecStart=/usr/local/bin/teleport-event-handler start --config=/etc/teleport-event-handler.toml --teleport-refresh-enabled=true
ExecReload=/bin/kill -HUP $MAINPID
PIDFile=/run/teleport-event-handler.pid

[Install]
WantedBy=multi-user.target

sudo systemctl enable teleport-event-handler
sudo systemctl start teleport-event-handler

teleport-event-handler start --config /etc/teleport-event-handler.toml --start-time "2021-05-05T00:00:00Z"

sudo journalctl -u teleport-event-handler
DEBU   Event sent id:f19cf375-4da6-4338-bfdc-e38334c60fd1 index:0 ts:2022-09-2118:51:04.849 +0000 UTC type:cert.create event-handler/app.go:140...

helm install teleport-plugin-event-handler teleport/teleport-plugin-event-handler \  --values teleport-plugin-event-handler-values.yaml \  --version 16.2.0

docker run --network host -v `pwd`:/opt/teleport-plugin -w /opt/teleport-plugin public.ecr.aws/gravitational/teleport-plugin-event-handler:16.2.0 start --config=teleport-event-handler.toml

연결 문제 해결

Teleport 이벤트 핸들러가 Teleport 클러스터에 연결하는 동안 오류 로그를 표시한다면, 확인해야 할 사항은 다음과 같습니다:

• Teleport 이벤트 핸들러가 Teleport 클러스터에 연결하기 위해 사용하는 인증서가 만료되지 않았는지 확인하세요. 이는 tctl auth sign 명령에서 --ttl 플래그의 값으로, 기본적으로 12시간입니다.
• Teleport 이벤트 핸들러 구성 파일(teleport-event-handler.toml)에서 Teleport Proxy Service 또는 Auth Service에 대한 올바른 호스트와 포트를 제공했는지 확인하세요.

다음 단계

임시 대행에 대해 더 알아보세요.

이 가이드는 Teleport 이벤트 핸들러용 자격 증명을 발급하기 위해 tctl auth sign 명령을 사용하지만, 프로덕션 클러스터는 더 안전하고 신뢰할 수 있는 갱신을 위해 Machine ID 사용을 권장합니다. 우리의 가이드를 읽어 Machine ID를 시작하세요.

teleport-plugin-event-handler Helm 차트의 값 파일에 설정할 수 있는 모든 옵션을 보려면, 참조 가이드를 참조하세요.