Trino 배포

Trino 배포 (Deploying Trino)

Trino 서버를 실제 운영 머신에 설치하고 설정하는 전체 과정을 설명해요. 요구 사항부터 설치, 구성 파일 작성, 실행까지 순서대로 다룹니다.

출처: 문서

본문

요구 사항 (Requirements)

Linux 운영체제

64비트 필요
특히 컨테이너에서 실행할 때는 최신 릴리스 권장
Trino 프로세스를 실행하는 사용자에 대한 충분한 ulimit. 이 한도는 사용 중인 Linux 배포판에 따라 다를 수 있어요. 특정 Trino 인스턴스가 필요한 열린 파일 디스크립터 수는 클러스터의 머신 수에 워크로드에 따른 계수를 곱한 값과 대략 비례해요. nofile 한도는 프로세스가 가질 수 있는 최대 파일 디스크립터 수를, nproc 한도는 사용자가 만들 수 있는 프로세스(따라서 JVM의 스레드) 수를 제한해요. 최소한 다음 값으로 한도를 설정할 것을 권장해요. 보통 이 설정은 /etc/security/limits.conf에 있어요.
```
trino soft nofile 131072
trino hard nofile 131072
trino soft nproc 128000
trino hard nproc 128000
```

Java 런타임 환경 Trino는 64비트 Java 25가 필요하며, 최소 25.0.1 이상이고 최신 패치 버전을 권장해요. Java 8, Java 11, Java 17, Java 21, Java 24 같은 이전 버전은 동작하지 않아요. Java 26 같은 최신 버전은 지원되지 않아요. 동작할 수도 있지만 테스트되지 않았어요.

Trino는 그 배포판으로 테스트되므로 Adoptium의 Eclipse Temurin OpenJDK 배포판을 Trino의 JDK로 권장해요. Eclipse Temurin은 Trino Docker 이미지에서도 사용하는 JDK예요.

Trino 설치 (Installing Trino)

Trino 서버 tarball인 trino-server-483.tar.gz를 다운로드하고 압축을 풀어요. tarball에는 trino-server-483이라는 단일 최상위 디렉토리가 있고, 이것을 설치 디렉토리(installation directory)라고 불러요.

기본 tarball은 모든 플러그인을 포함하며 사용을 위해 구성해야 해요. 최소 server-core tarball인 trino-server-core-483.tar.gz는 필수 플러그인만 최소한으로 담고 있어 커스텀 tarball 제작의 베이스로 적합해요.

trino-packages 프로젝트에는 예제 설정이 포함된 완전히 구성된 tarball을 만드는 모듈이 있어요. 그 커스텀 tarball은 바로 사용 가능하며 원하는 대로 더 구성하고 조정할 수 있어요.

Trino는 로그 등을 저장할 데이터 디렉토리가 필요해요. 기본적으로 tarball에서 설치하면 설치 디렉토리와 데이터 디렉토리가 같은 위치를 사용해요.

설치 디렉토리 밖에 데이터 디렉토리를 만드는 것을 권장해요. 그러면 Trino 업그레이드 시 쉽게 보존할 수 있어요. 이 디렉토리 경로는 Node properties로 구성해야 해요.

Trino 프로세스를 실행하는 사용자는 설치 디렉토리에 대한 전체 읽기 접근, 데이터 디렉토리에 대한 읽기·쓰기 접근을 가져야 해요.

Trino 구성 (Configuring Trino)

설치 디렉토리 안에 etc 디렉토리를 만들어요. 이곳에 다음 구성을 둬요.

Node Properties: 각 노드에 특화된 환경 구성
JVM Config: Java Virtual Machine용 커맨드라인 옵션
Config Properties: Trino 서버 구성. 사용 가능한 구성 프로퍼티는 Properties reference를 참고하세요.
Catalog Properties: 커넥터(데이터 소스) 구성. 커넥터의 사용 가능한 카탈로그 구성 프로퍼티는 해당 커넥터 문서에 설명돼 있어요.

노드 프로퍼티 (Node properties)

노드 프로퍼티 파일 etc/node.properties는 각 노드에 특화된 구성을 담아요. 노드는 머신에 설치된 단일 Trino 인스턴스예요. 이 파일은 보통 Trino를 처음 설치할 때 배포 시스템이 만들어요. 다음은 최소한의 etc/node.properties예요.

node.environment=production
node.id=ffffffff-ffff-ffff-ffff-ffffffffffff
node.data-dir=/var/trino/data

위 프로퍼티들은 다음과 같아요.

node.environment: 환경의 이름. 클러스터의 모든 Trino 노드는 같은 환경 이름을 가져야 해요. 이름은 소문자 영숫자 문자로 시작해야 하고, 소문자 영숫자 또는 밑줄(_) 문자만 포함해야 해요.
node.id: 이 Trino 설치의 고유 식별자. 모든 노드마다 고유해야 해요. 이 식별자는 Trino를 재부팅하거나 업그레이드해도 일관되게 유지되어야 해요. 한 머신에 Trino를 여러 번 설치해 실행한다면(같은 머신에 여러 노드), 각 설치마다 고유한 식별자를 가져야 해요. 식별자는 영숫자 문자로 시작하고 영숫자, -, _ 문자만 포함해야 해요.
node.data-dir: 데이터 디렉토리의 위치(파일시스템 경로). Trino가 로그와 다른 데이터를 여기에 저장해요.

JVM 구성 (JVM config)

JVM 구성 파일 etc/jvm.config는 Java Virtual Machine을 시작할 때 사용하는 커맨드라인 옵션 목록을 담아요. 파일 형식은 한 줄에 하나씩 옵션을 나열하는 거예요. 이 옵션들은 셸이 해석하지 않으므로 공백이나 다른 특수 문자가 있는 옵션은 따옴표로 감싸면 안 돼요.

etc/jvm.config를 만들 때 좋은 출발점은 다음과 같아요.

-server
-Xmx16G
-XX:InitialRAMPercentage=80
-XX:MaxRAMPercentage=80
-XX:G1HeapRegionSize=32M
-XX:+ExplicitGCInvokesConcurrent
-XX:+ExitOnOutOfMemoryError
-XX:+HeapDumpOnOutOfMemoryError
-XX:-OmitStackTraceInFastThrow
-XX:ReservedCodeCacheSize=512M
-XX:PerMethodRecompilationCutoff=10000
-XX:PerBytecodeRecompilationCutoff=10000
-Djdk.attach.allowAttachSelf=true
-Djdk.nio.maxCachedBufferSize=2000000
--add-modules=jdk.incubator.vector

Trino가 사용하는 메모리 값(-Xmx로 지정)은 노드의 가용 메모리에 맞게 조정해야 해요. 보통 전체 가용 메모리의 70~85%를 나타내는 값을 권장해요. 예를 들어 모든 워커와 코디네이터가 64GB RAM의 노드를 사용한다면 -Xmx54G를 쓸 수 있어요. Trino는 할당된 메모리의 대부분을 처리에 사용하고, 소량은 가비지 컬렉션 같은 JVM 내부 프로세스가 사용해요.

나머지 노드 메모리는 운영체제와 실행 중인 다른 서비스, 그리고 JVM 프로세스가 시작한 네이티브 코드에 쓰이는 off-heap 메모리에 충분해야 해요.

더 큰 노드에서는 백분율 값을 낮출 수 있어요. 모든 메모리를 JVM에 할당하거나 스왑 공간을 사용하는 것은 지원되지 않으며, 운영체제 수준에서 스왑 공간을 비활성화하는 것이 권장돼요.

프로덕션 클러스터에는 32GB를 넘는 큰 메모리 할당이 권장돼요.

OutOfMemoryError는 보통 JVM을 일관되지 않은 상태로 남기므로, 그런 경우 디버깅용 힙 덤프를 작성하고 프로세스를 강제 종료해요.

임시 디렉토리 (Temporary directory)

JVM이 사용하는 임시 디렉토리는 코드 실행을 허용해야 해요. Trino가 파일 압축·해제 같은 용도로 공유 라이브러리 바이너리에 접근하고 사용하기 때문이에요. 구체적으로 파티션이 noexec로 마운트되어 있으면(코드 실행 불가) 동작하지 않아요. 이 문제는 JVM 옵션 목록에 -Djava.io.tmpdir=/path/to/other/tmpdir을 추가해 임시 디렉토리를 재정의하면 해결할 수 있어요.

구성 프로퍼티 (Config properties)

구성 프로퍼티 파일 etc/config.properties는 Trino 서버 구성을 담아요. 모든 Trino 서버는 코디네이터와 워커로 모두 기능할 수 있어요. 클러스터는 코디네이터 하나를 포함해야 하며, 더 큰 클러스터에서는 한 머신을 코디네이션 작업 전용으로 하는 것이 최상의 성능을 제공해요. 확장과 병렬화는 많은 워커로 달성돼요.

다음은 코디네이터의 최소 구성이에요.

coordinator=true
node-scheduler.include-coordinator=false
http-server.http.port=8080
discovery.uri=http://example.net:8080

그리고 워커의 최소 구성이에요.

coordinator=false
http-server.http.port=8080
discovery.uri=http://example.net:8080

또는 코디네이터와 워커를 모두 수행하는 테스트용 단일 머신을 설정하려면 이 구성을 사용해요.

coordinator=true
node-scheduler.include-coordinator=true
http-server.http.port=8080
discovery.uri=http://example.net:8080

이 프로퍼티들은 설명이 필요해요.

coordinator: 이 Trino 인스턴스가 코디네이터로 기능하도록 허용해, 클라이언트의 쿼리를 받아들여 쿼리 실행을 관리하게 해요.
node-scheduler.include-coordinator: 코디네이터에서 작업 스케줄링을 허용해요. 더 큰 클러스터에서는 코디네이터에서 처리 작업을 수행하면 쿼리 성능에 영향을 줄 수 있어요. 머신의 자원이 쿼리 실행의 스케줄링·관리·모니터링이라는 중요한 작업에 사용되지 못하거든요.
http-server.http.port: HTTP 서버의 포트를 지정해요. Trino는 내부·외부 모든 통신에 HTTP를 사용해요.
discovery.uri: Trino 코디네이터에는 모든 노드가 서로를 찾는 데 사용하는 디스커버리 서비스가 있어요. 모든 Trino 인스턴스는 시작 시 디스커버리 서비스에 자신을 등록하고, 지속적으로 하트비트를 보내 등록을 유지해요. 디스커버리 서비스는 Trino와 HTTP 서버를 공유하므로 같은 포트를 사용해요. Trino 코디네이터의 호스트와 포트에 맞게 example.net:8080을 바꿔요. 코디네이터에서 HTTP를 비활성화했다면 URI 스킴은 http가 아니라 https여야 해요.

위 구성 프로퍼티는 시작을 돕는 최소한의 집합이에요. 추가 구성은 모두 선택이며 특정 클러스터와 지원되는 사용 사례에 따라 크게 달라져요. Administration과 Security 섹션에는 큐잉 정책을 구성하는 Resource groups, Fault-tolerant execution 등 많은 측면에 대한 문서가 있어요. Properties reference는 General properties, Resource management properties, Query management properties, Web UI properties 등 주제에 대한 지원 프로퍼티의 종합적인 목록을 제공해요.

추가 구성에는 Logging, Observability with OpenTelemetry, Monitoring with JMX, Trino metrics with OpenMetrics 등 Administration 섹션에 설명된 기능이 포함될 수 있어요.

카탈로그 프로퍼티 (Catalog properties)

Trino는 커넥터로 데이터 소스의 데이터에 접근하며, 커넥터는 카탈로그에 구성돼요. 커넥터는 카탈로그 안의 모든 스키마와 테이블을 제공해요.

예를 들어 Hive 커넥터는 각 Hive 데이터베이스를 스키마에 매핑해요. Hive 커넥터가 example 카탈로그에 구성되어 있고, Hive에 web 데이터베이스의 clicks 테이블이 있다면, 그 테이블은 Trino에서 example.web.clicks로 접근할 수 있어요.

카탈로그는 etc/catalog 디렉토리에 카탈로그 프로퍼티 파일을 만들어 등록해요. 예를 들어 jmx 커넥터를 jmx 카탈로그로 마운트하려면 다음 내용으로 etc/catalog/jmx.properties를 만들어요.

connector.name=jmx

카탈로그 구성 방법은 Connectors 문서를 참고하세요.

Trino 실행 (Running Trino)

설치는 bin/launcher 스크립트를 제공해요. 이 스크립트를 수동으로 또는 데몬 시작 스크립트로 사용할 수 있어요. 다음 명령을 지원해요.

명령	동작
`run`	서버를 포그라운드에서 시작하고 계속 실행해요. 종료하려면 이 터미널에서 Ctrl+C를 누르거나 다른 터미널에서 `stop` 명령을 사용해요.
`start`	서버를 데몬으로 시작하고 프로세스 ID를 반환해요.
`stop`	`start` 또는 `run`으로 시작한 서버를 종료해요. SIGTERM 신호를 보내요.
`restart`	실행 중인 서버를 중지 후 재시작하거나, 중지된 서버를 새 프로세스 ID로 시작해요.
`kill`	SIGKILL 신호를 보내 응답하지 않는 서버를 종료해요.
`status`	`Stopped pid` 또는 `Running as pid` 형태의 상태 줄을 출력해요.

추가 옵션으로 설정 파일과 디렉토리 위치, Java 옵션을 지정할 수 있어요. 지원되는 명령·옵션·기본값은 bin/launcher --help로 확인할 수 있어요. 각 명령에 -v/--verbose 옵션을 붙이면 평소 출력 앞에 서버의 현재 설정을 함께 보여 줘요.

daemon으로 시작하려면 다음을 실행해요.

bin/launcher start

상태 명령에 verbose 옵션을 붙이면 PID와 설정 목록을 확인할 수 있어요.

bin/launcher -v status

또는 로그와 다른 출력이 stdout/stderr로 쓰이는 포그라운드로 실행할 수도 있어요. daemontools 같은 감독(supervision) 시스템을 쓴다면 두 스트림을 모두 캡처해야 해요.

bin/launcher run

launcher는 구성 디렉토리 etc, etc 안의 구성 파일, 설치 디렉토리와 같은 데이터 디렉토리, PID 파일 var/run/launcher.pid, var/log 디렉토리 안의 로그 파일에 대한 기본값을 설정해요. 이 값을 바꿔 요구 사항에 맞출 수 있어요(설치 디렉토리 밖 디렉토리 사용, 특정 마운트 지점·위치, 다른 파일명 등). 예를 들어 Trino RPM은 Linux Filesystem Hierarchy Standard(FHS)를 더 잘 따르도록 사용 디렉토리를 조정해요.

Trino를 시작하면 데이터 디렉토리 var 안의 log 디렉토리에서 로그 파일을 찾을 수 있어요.

launcher.log: launcher가 만들며 서버의 stdout/stderr 스트림에 연결돼요. 서버 로깅이 초기화되는 동안 발생하는 몇몇 로그 메시지와 JVM이 생성한 오류·진단 정보를 담아요.
server.log: Trino가 사용하는 메인 로그 파일이에요. 서버가 초기화 중 실패하면 관련 정보가 여기 담겨요. 자동으로 로테이션·압축돼요.
http-request.log: 서버가 받은 모든 HTTP 요청을 담는 HTTP 요청 로그예요. 자동으로 로테이션·압축돼요.

배포를 마친 뒤에는 사용할 클라이언트(CLI, JDBC 등)를 구성하고, 필요하면 커넥터 카탈로그를 추가로 등록해서 실제 데이터 소스에 연결하면 돼요.

더 알아보기 (Learn more)

Trino를 배포하고 구성하는 방법을 배웠어요. 이어서 더 현실적인 운영을 돕는 Trino in a Docker container 문서를 살펴보면 좋아요.