LogBamboo 다운로드 및 배포¶
이 가이드에서는 LogBamboo 컨테이너 이미지 패키지를 다운로드하고, 설정을 준비하며, 서비스 시작 및 로그인 검증을 완료하는 방법을 설명합니다. 아래에서는 새 단일 노드 Kubernetes 배포를 예로 들며 S3 기본 스토리지를 사용합니다. 설명에 따라 로컬 스토리지 또는 OSS로 교체할 수도 있습니다.
배포 흐름: 이미지 패키지 다운로드 → 이미지 로드 → 설정 준비 → 서비스 시작 → 로그인 및 검증.
도메인, 이미지 주소, 스토리지 주소 및 모든 REPLACE_WITH_ 내용은 모두 교체해야 합니다. 기존 배포를 업그레이드할 때는 기존 설정, 스토리지 접두사 및 ID를 유지하고 먼저 변경 로그를 읽으세요.
1단계: 이미지 패키지 다운로드¶
Kubernetes 노드의 CPU 아키텍처에 따라 Linux 컨테이너 이미지 패키지를 선택합니다.
| CPU 아키텍처 | 다운로드 주소 |
|---|---|
| AMD64(x86_64) | AMD64 이미지 패키지 다운로드 |
| ARM64(aarch64) | ARM64 이미지 패키지 다운로드 |
파일 이름의 latest는 버전 릴리스에 따라 업데이트되며, 패키지 내 실제 이미지 이름과 버전은 로드 결과를 기준으로 합니다. 다운로드 후 이미지 로드를 계속 진행하고 Kubernetes에서 접근 가능한 이미지 주소를 준비하세요. 버전 변경 사항은 LogBamboo 변경 로그를 참조하세요.
2단계: 이미지 로드¶
LogBamboo 다운로드에서 대상 노드 아키텍처와 일치하는 이미지 패키지를 선택합니다. Docker가 설치된 이미지 준비 머신에서 로드를 실행합니다. 아래 예시는 AMD64 기준이며 ARM64는 해당 파일 이름을 사용하세요:
로드가 완료되면 출력에서 전체 이미지 이름 및 버전을 기록합니다. 이미지 패키지는 직접 로드할 수 있으며, 명령 파라미터는 Docker 이미지 로드 설명을 참조하세요.
클러스터에서 접근 가능한 이미지 주소 준비¶
로드한 이미지를 Kubernetes 클러스터에서 접근 가능한 이미지 레지스트리에 푸시합니다. 인증이 필요한 경우 먼저 레지스트리 요구 사항에 따라 로그인합니다. 아래의 소스 이미지 이름, 대상 레지스트리 주소 및 버전 번호를 교체하세요:
docker image tag REPLACE_WITH_LOADED_IMAGE REPLACE_WITH_REGISTRY/logbamboo:REPLACE_WITH_VERSION
docker image push REPLACE_WITH_REGISTRY/logbamboo:REPLACE_WITH_VERSION
REPLACE_WITH_LOADED_IMAGE에는 로드 출력의 전체 이미지 이름을 사용합니다. 푸시한 대상 이미지 주소(버전 포함)를 아래 Kubernetes 매니페스트의 Deployment image: REPLACE_WITH_IMAGE에 입력합니다. Kubernetes 노드는 해당 레지스트리에서 이미지를 가져올 수 있어야 합니다. 배포에는 고정 버전 번호를 사용하여 이후 확인 및 업그레이드를 용이하게 합니다.
3단계: 설정 준비¶
먼저 대상 클러스터, 노드 아키텍처 및 사용 가능한 리소스를 확인합니다:
kubectl config current-context
kubectl get nodes -L kubernetes.io/arch
kubectl get storageclass
kubectl get ingressclass
kubectl get namespace utils
다음 설정 및 리소스를 준비합니다:
| 준비 항목 | 요구 사항 |
|---|---|
| Kubernetes 클러스터 | 네임스페이스, 사용 가능한 노드, CSI / StorageClass를 준비합니다. Ingress를 사용하는 경우 클러스터에 사용 가능한 인그레스 컨트롤러가 이미 배포되어 있어야 합니다. |
| 컨테이너 이미지 | 노드 CPU 아키텍처와 일치하는 이미지 패키지를 다운로드하고, 로드 후 클러스터에서 접근 가능한 이미지 레지스트리에 푸시합니다. 레지스트리 인증이 필요한 경우 해당 pull 자격 증명을 준비합니다. |
| 이미지 준비 도구 | 이미지 로드 및 푸시에 사용할 머신에 Docker를 설치하고 대상 이미지 레지스트리에 접근할 수 있는지 확인합니다. |
| 영구 스토리지 | 이 문서의 예시는 200 GiB PVC를 사용하여 state, WAL 및 임시 빌드 데이터를 저장합니다. 로컬 기본 스토리지를 사용하는 경우 최종 로그 데이터도 수용해야 합니다. 용량은 쓰기량, 장애 캐시 시간 및 보존 정책에 따라 계획해야 합니다. |
| 오브젝트 스토리지(선택 사항) | S3를 사용하는 경우 Endpoint, Region, Bucket, 현재 배포 전용의 새 Prefix, AK/SK 및 해당 접두사에 필요한 목록 조회, 읽기, 쓰기, 멀티파트 업로드 및 정리 권한을 준비합니다. Pod는 Endpoint에 접근할 수 있어야 합니다. |
| 로그인 및 인터페이스 자격 증명 | 관리자 비밀번호, 쓰기 Token, 조회 Token을 각각 준비합니다. 관리자 비밀번호는 12–128 UTF-8 바이트이고, 두 Token은 각각 최소 16바이트이며 서로 달라야 합니다. |
| HTTPS 인그레스 | 도메인 DNS 확인, 해당 도메인을 포함하는 유효한 인증서 및 개인 키를 준비하며, 기존 Ingress 컨트롤러가 TLS를 종료합니다. |
| 네트워크 액세스 | 관리자와 데이터 전송 서비스 모두 운영 HTTPS 도메인에 접근할 수 있어야 하며, 백엔드 8080은 통제된 네트워크 내에서만 접근할 수 있습니다. |
이미지 패키지는 이 페이지에서 직접 다운로드할 수 있습니다. 프로덕션 리소스 사양이나 배포 방안을 확인해야 하는 경우 배포 지원에 문의하세요.
단일 노드에는 Redis를 추가로 배포할 필요가 없습니다. S3를 사용하더라도 PVC는 반드시 유지해야 합니다. 원격에는 로그 오브젝트가 저장되고, PVC의 state_dir에는 WAL, 노드 ID 및 단일 노드 제어 상태가 저장되며, 두 저장소는 서로를 대체할 수 없습니다. 로컬 기본 스토리지는 단일 노드만 지원합니다. 다중 노드에는 공유 오브젝트 스토리지, Redis 제어 플레인 및 관련 권한을 별도로 계획해야 하며, 이 문서의 복제본 수를 그대로 2로 변경할 수 없습니다.
이 문서에서는 utils 네임스페이스를 예로 사용합니다. CPU/메모리 상한 2 CPU / 4 GiB, PVC 200 GiB는 예시 사양이며, 실제 리소스는 쓰기량, 장애 캐시 시간 및 보존 정책에 따라 계획합니다.
Kubernetes 배포 설정¶
아래 매니페스트를 펼쳐 앞에서 준비한 정보에 따라 스토리지, 계정 자격 증명, 영구 볼륨 및 HTTPS 인그레스를 입력하고 logbamboo.yaml로 저장합니다.
S3 기본 스토리지 전체 설정 및 파라미터 설명 보기
S3 연결 파라미터¶
다음 연결 파라미터를 ConfigMap/logbamboo-config의 logbamboo.toml에 있는 [storage] 섹션에 작성합니다. AK/SK의 값은 Secret/logbamboo-object-storage에 두고 Deployment가 환경 변수로 주입하며, TOML에는 환경 변수 이름만 작성합니다.
| 정보 | TOML 필드 | 작성 설명 |
|---|---|---|
| S3 API 주소 | endpoint |
전체 URL(예: https://s3.ap-southeast-1.amazonaws.com). 콘솔 URL이 아닌 서비스 API 주소를 사용하며, URL에 Bucket 또는 Prefix를 연결하지 않습니다. |
| 리전 | region |
Bucket이 위치한 리전 및 서명 요구 사항과 일치해야 합니다(예: ap-southeast-1). |
| 버킷 | bucket |
이미 생성된 버킷 이름입니다. 배포 템플릿은 Bucket을 생성하지 않습니다. |
| 데이터 디렉터리 접두사 | prefix |
이 배포에 사용되지 않은 접두사를 할당합니다(예: logbamboo/prod-a). 이후 업그레이드 시 반드시 기존 접두사를 재사용해야 합니다. |
| Access Key | access_key_env |
LOGLAKE_OBJECT_ACCESS_KEY를 고정 참조하며, 실제 값은 Secret에 둡니다. |
| Secret Key | secret_key_env |
LOGLAKE_OBJECT_SECRET_KEY를 고정 참조하며, 실제 값은 Secret에 둡니다. |
| 주소 지정 방식 | path_style |
예시 false는 virtual-hosted style을 의미합니다. S3 호환 서비스에서 path-style을 요구하는 경우 true로 변경하고 DNS, 인증서 및 서버 측 지원 여부를 검증하세요. |
| 데이터 보호 방식 | protection_mode |
예시는 application_only이며, 애플리케이션 측 보호를 의미하고 클라우드 WORM이 활성화되었음을 의미하지 않습니다. |
S3 호환성은 Endpoint에 연결할 수 있는 것뿐만 아니라 프로그램이 사용하는 조건부 쓰기, 멀티파트 업로드, 읽기 및 정리 기능도 검증해야 합니다. 내부 네트워크 Endpoint는 해당 내부 네트워크에 접근할 수 있는 노드에만 적용됩니다. 클라우드 간 배포에서는 그대로 재사용할 수 없습니다. 기본 스토리지, 콜드 아카이브 및 독립 재해 복구는 서로 다른 구성입니다. 이 문서에서는 기본 스토리지만 구성하며, 이후 데이터 전송 규칙에서 S3 파라미터를 다시 입력할 필요가 없습니다.
전체 배포 매니페스트¶
아래는 단일 Pod + S3 + PVC + HTTPS Ingress의 전체 매니페스트입니다. logbamboo.yaml로 저장하고 모든 자리 표시자와 logbamboo.example.com을 교체하세요. Ingress 어노테이션은 기존 ingress-nginx 컨트롤러에 적용됩니다. 다른 컨트롤러는 해당 구성 방식을 사용해야 합니다. Ingress 리소스를 생성하는 것만으로는 인그레스 컨트롤러가 설치되지 않으며 인증서나 DNS 레코드도 자동 생성되지 않습니다.
자격 증명은 Secret.stringData를 통해 입력합니다. 설정 파일에 평문 자격 증명이 포함되므로 로컬 파일 권한을 제한하고 자격 증명 관리 요구 사항에 따라 안전하게 보관하세요. 템플릿의 AK/SK 및 Token은 모두 교체해야 할 자리 표시자 값입니다.
apiVersion: v1
kind: Namespace
metadata:
name: utils
---
apiVersion: v1
kind: Secret
metadata:
name: logbamboo-auth
namespace: utils
type: Opaque
stringData:
admin-password: "REPLACE_WITH_ADMIN_PASSWORD"
ingest-token: "REPLACE_WITH_UNIQUE_INGEST_TOKEN"
search-token: "REPLACE_WITH_DIFFERENT_SEARCH_TOKEN"
---
apiVersion: v1
kind: Secret
metadata:
name: logbamboo-object-storage
namespace: utils
type: Opaque
stringData:
access-key: "REPLACE_WITH_OBJECT_ACCESS_KEY"
secret-key: "REPLACE_WITH_OBJECT_SECRET_KEY"
---
apiVersion: v1
kind: ConfigMap
metadata:
name: logbamboo-config
namespace: utils
data:
logbamboo.toml: |
listen = "0.0.0.0:8080"
allow_insecure_http = true
state_dir = "/var/lib/logbamboo/state"
require_state_dir_fsync = true
# 예시는 200 GiB 영구 디스크를 기준으로 예약한 것이며, 비즈니스 용량 보장이 아닙니다.
state_max_bytes = 85899345920
wal_max_bytes = 42949672960
staging_max_bytes = 34359738368
state_reserved_free_bytes = 10737418240
staging_min_free_bytes = 5368709120
wal_high_watermark_bytes = 32212254720
wal_low_watermark_bytes = 21474836480
# 단일 인스턴스 예시 예산이며, 실제 쓰기 및 조회 부하에서 RSS를 관찰한 후 조정해야 합니다.
max_request_bytes = 67108864
max_records_per_request = 1000000
max_ingest_inflight_bytes = 268435456
segment_build_concurrency = 1
segment_index_workers = 1
build_memory_max_bytes = 1073741824
max_concurrent_queries = 1
query_memory_max_bytes = 1073741824
[cluster]
maintenance_enabled = true
[storage]
type = "s3"
endpoint = "https://REPLACE_WITH_S3_ENDPOINT"
region = "REPLACE_WITH_REGION"
bucket = "REPLACE_WITH_BUCKET"
prefix = "REPLACE_WITH_NEW_DEDICATED_PREFIX"
access_key_env = "LOGLAKE_OBJECT_ACCESS_KEY"
secret_key_env = "LOGLAKE_OBJECT_SECRET_KEY"
path_style = false
protection_mode = "application_only"
[[tenants]]
id = "default"
ingest_token_env = "LOGLAKE_TOKEN"
search_token_env = "LOGLAKE_SEARCH_TOKEN"
[[tenants.indexes]]
name = "app"
retention = "7d"
retention_policy_revision = 1
[web_ui]
public_url = "https://logbamboo.example.com"
# 현장에서 X-Real-IP를 덮어쓰는 신뢰할 수 있는 프록시의 정확한 IP를 입력하세요. 루프백 주소를 그대로 복사하지 마세요.
trusted_proxy_ips = []
[web_ui.auth_state]
mode = "memory"
single_replica = true
[web_ui.auth]
mode = "local"
admin_username = "admin"
admin_password_env = "LOGLAKE_ADMIN_PASSWORD"
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: logbamboo-data
namespace: utils
spec:
accessModes:
- ReadWriteOnce
storageClassName: REPLACE_WITH_STORAGE_CLASS
resources:
requests:
storage: 200Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: logbamboo
namespace: utils
spec:
replicas: 1
strategy:
type: Recreate
selector:
matchLabels:
app: logbamboo
template:
metadata:
labels:
app: logbamboo
spec:
terminationGracePeriodSeconds: 120
securityContext:
runAsNonRoot: true
runAsUser: 10001
runAsGroup: 10001
fsGroup: 10001
fsGroupChangePolicy: OnRootMismatch
# 프라이빗 이미지 레지스트리를 사용하려면 이 네임스페이스에 자격 증명을 준비한 후 활성화하세요:
# imagePullSecrets:
# - name: YOUR_IMAGE_PULL_SECRET
containers:
- name: logbamboo
image: REPLACE_WITH_IMAGE
imagePullPolicy: IfNotPresent
command: ["/usr/local/bin/logbamboo"]
args: ["--config", "/etc/logbamboo/logbamboo.toml"]
ports:
- name: http
containerPort: 8080
env:
- name: LOGLAKE_UI_DIR
value: /usr/share/logbamboo/ui
- name: LOGLAKE_ADMIN_PASSWORD
valueFrom:
secretKeyRef:
name: logbamboo-auth
key: admin-password
- name: LOGLAKE_TOKEN
valueFrom:
secretKeyRef:
name: logbamboo-auth
key: ingest-token
- name: LOGLAKE_SEARCH_TOKEN
valueFrom:
secretKeyRef:
name: logbamboo-auth
key: search-token
- name: LOGLAKE_OBJECT_ACCESS_KEY
valueFrom:
secretKeyRef:
name: logbamboo-object-storage
key: access-key
- name: LOGLAKE_OBJECT_SECRET_KEY
valueFrom:
secretKeyRef:
name: logbamboo-object-storage
key: secret-key
resources:
requests:
cpu: "1"
memory: 2Gi
limits:
cpu: "2"
memory: 4Gi
startupProbe:
httpGet:
path: /livez
port: http
periodSeconds: 10
failureThreshold: 30
livenessProbe:
httpGet:
path: /livez
port: http
periodSeconds: 20
failureThreshold: 3
readinessProbe:
httpGet:
path: /readyz
port: http
periodSeconds: 10
failureThreshold: 3
volumeMounts:
- name: config
mountPath: /etc/logbamboo/logbamboo.toml
subPath: logbamboo.toml
readOnly: true
- name: data
mountPath: /var/lib/logbamboo
volumes:
- name: config
configMap:
name: logbamboo-config
- name: data
persistentVolumeClaim:
claimName: logbamboo-data
---
apiVersion: v1
kind: Service
metadata:
name: logbamboo
namespace: utils
spec:
type: ClusterIP
selector:
app: logbamboo
ports:
- name: http
port: 8080
targetPort: http
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: logbamboo
namespace: utils
annotations:
nginx.ingress.kubernetes.io/ssl-redirect: "true"
nginx.ingress.kubernetes.io/proxy-body-size: "64m"
nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
spec:
ingressClassName: REPLACE_WITH_INGRESS_CLASS
tls:
- hosts:
- logbamboo.example.com
secretName: logbamboo-tls
rules:
- host: logbamboo.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: logbamboo
port:
number: 8080
PVC, 설정, 자격 증명 및 인그레스의 대응 관계:
| 항목 | 이 매니페스트의 설정 및 역할 |
|---|---|
| PVC 선언 | PersistentVolumeClaim/logbamboo-data가 지정된 StorageClass에 200 GiB 볼륨을 요청합니다. 동적 프로비저닝을 지원하는 StorageClass를 사용하는 경우 PV를 직접 작성할 필요가 없습니다. 지원하지 않는 경우 클러스터 관리자가 먼저 일치하는 PV를 준비해야 합니다. |
| Deployment의 PVC 참조 | volumes[].persistentVolumeClaim.claimName: logbamboo-data가 위 PVC를 참조하며, volumeMounts가 /var/lib/logbamboo에 마운트됩니다. TOML의 state_dir는 이 마운트 내에 위치합니다. |
| S3를 사용하는데도 PVC가 필요한 이유 | S3에는 기본 로그 오브젝트가 저장되고, PVC에는 아직 게시되지 않은 WAL, 노드 ID, 단일 노드 제어 상태 및 임시 파일이 저장됩니다. PVC를 삭제한 후 Pod를 재생성해도 원래 배포가 복구된다고 보장할 수 없습니다. |
| 단일 인스턴스 업데이트 | replicas: 1과 Recreate를 함께 사용하여 일반적인 롤링 업데이트 시 두 인스턴스가 동시에 동일한 상태 디렉터리를 사용하지 않도록 합니다. HPA는 구성하지 않습니다. ReadWriteOnce는 단일 Pod 잠금이 아니라 노드 마운트를 제한합니다. |
| 디스크 쓰기 권한 | 이미지는 UID/GID 10001로 실행되며, fsGroup: 10001은 CSI 지원이 필요합니다. 쓸 수 없는 경우 먼저 스토리지 드라이버와 디렉터리 권한을 확인하세요. |
| TOML 마운트 | ConfigMap 파일이 /etc/logbamboo/logbamboo.toml에 마운트되고, 컨테이너는 --config로 명시적으로 읽습니다. 데이터 디렉터리에 마운트되지 않으며 최초 설정 마법사에도 들어가지 않습니다. |
| 환경 변수 주입 | logbamboo-auth는 관리자 비밀번호와 두 Token을 주입하고, logbamboo-object-storage는 S3 AK/SK를 주입합니다. 이름은 TOML의 *_env 참조와 정확히 대응합니다. |
| 서비스 및 도메인 | Ingress / → Service/logbamboo:8080 → Pod 8080. Service는 ClusterIP이며 공인 8080을 별도로 개방하지 않습니다. |
| TLS | utils/logbamboo-tls에는 인증서와 개인 키가 저장됩니다. spec.tls.hosts, rules.host, 인증서 도메인 및 web_ui.public_url은 서로 대응해야 합니다. |
| 실제 소스 IP | 예시에서는 Ingress 소스 IP를 추정하지 않으므로 trusted_proxy_ips = []입니다. 배포 후에는 X-Real-IP를 덮어쓰는 신뢰할 수 있는 프록시의 정확한 IP로 구성해야 합니다. 그렇지 않으면 프록시 뒤의 사용자가 소스 IP 로그인 속도 제한을 공유하게 됩니다. |
PVC 액세스 모드 및 동적 프로비저닝 설명은 Kubernetes 영구 볼륨 문서를, HTTPS 리디렉션 및 요청 본문 크기 어노테이션은 ingress-nginx 공식 설명을 참조하세요.
로컬 디스크, OSS 또는 기타 오브젝트 스토리지로 전환
기본 스토리지는 하나만 선택합니다. ConfigMap에서 [storage] 블록 전체를 교체하고, 원래 블록 뒤에 같은 이름의 두 번째 블록을 추가하지 마세요. 이미 데이터가 기록된 배포에서 스토리지를 전환하는 것은 마이그레이션에 해당하며, 새 배포 템플릿으로 바로 전환하는 것이 아닙니다.
로컬 기본 스토리지를 사용하는 경우:
이 경우 동일한 PVC에 state와 최종 로그가 함께 저장되므로 용량을 다시 산정해야 합니다. 매니페스트에서 logbamboo-object-storage Secret 및 해당하는 두 환경 변수 참조를 삭제할 수 있지만 PVC는 계속 유지해야 합니다.
Alibaba Cloud OSS 네이티브 인터페이스를 사용하는 경우:
[storage]
type = "oss"
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
bucket = "REPLACE_WITH_OSS_BUCKET"
prefix = "REPLACE_WITH_NEW_DEDICATED_PREFIX"
access_key_env = "LOGLAKE_OBJECT_ACCESS_KEY"
secret_key_env = "LOGLAKE_OBJECT_SECRET_KEY"
protection_mode = "application_only"
OSS에는 S3 전용 region, path_style 필드를 추가하지 않으며, AK/SK 주입 방식은 변경되지 않습니다. Volcengine TOS는 해당 S3 API를 통해 type = "s3"를 사용할 수 있으며, 실제 Region과 S3 Endpoint를 입력합니다. 이 문서에서는 현장 검증되지 않은 다른 S3 호환 서비스를 검증된 프로덕션 방안으로 간주하지 않습니다.
4단계: 서비스 시작¶
배포 설정 완료 후 네임스페이스를 생성하거나 확인하고, 인증서 파일 경로를 실제 경로로 교체합니다. 해당 도메인을 포함하는 TLS Secret이 이미 있으면 Ingress에서 직접 참조하고 다시 생성할 필요가 없습니다.
kubectl create namespace utils --dry-run=client -o yaml | kubectl apply -f -
kubectl -n utils create secret tls logbamboo-tls \
--cert=/path/to/fullchain.pem \
--key=/path/to/privkey.pem
DNS를 실제 Ingress 외부 IP 또는 로드 밸런서 주소로 지정합니다. 입력 완료 후 자리 표시자를 확인합니다. 출력이 남아 있으면 먼저 보완하고 적용하지 마세요:
대상 환경의 변경 프로세스에 따라 검증, 검토 및 배포를 수행합니다:
kubectl apply --dry-run=server -f logbamboo.yaml
kubectl diff -f logbamboo.yaml
# diff가 1을 반환하면 일반적으로 적용할 차이가 있음을 의미합니다. 차이를 확인한 후 계속하세요.
kubectl apply -f logbamboo.yaml
kubectl -n utils rollout status deployment/logbamboo --timeout=300s
kubectl -n utils get pvc/logbamboo-data
kubectl -n utils get pods -l app=logbamboo
kubectl -n utils get service/logbamboo ingress/logbamboo
kubectl -n utils logs deployment/logbamboo --tail=100
PVC가 Bound, Pod가 1/1 Ready인지 확인합니다. 지연 바인딩 StorageClass는 Pod 스케줄링 후에 PVC가 바인딩될 수 있습니다. 계속 Pending 상태인 경우 PVC / Pod 이벤트 및 CSI를 확인하세요. 이미지 가져오기 실패 시 먼저 실제 버전, 아키텍처 및 레지스트리 인증을 확인합니다. 여기의 dry-run은 API 수용 여부만 검증하며 스토리지 및 서비스 실행 검증을 대체할 수 없습니다.
5단계: 로그인 및 서비스 검증¶
운영 인그레스에 접근할 수 있는 네트워크에서 실행하고 도메인을 실제 값으로 교체합니다. 엔터프라이즈 내부 CA 또는 자체 서명 인증서를 사용하는 경우 --cacert로 신뢰할 수 있는 CA 파일을 지정해야 합니다:
curl --fail --show-error https://logbamboo.example.com/readyz
curl --fail --show-error https://logbamboo.example.com/ingest-readyz
두 요청 모두 2xx(본문 없음 가능)를 정상 반환해야 합니다. 이어서 페이지 검증을 완료합니다:
- 브라우저에서 구성된 HTTPS 도메인을 엽니다.
- 최초 로그인 시
admin및 Secretlogbamboo-auth에 설정한 관리자 비밀번호를 사용합니다. - 왼쪽 로그 인덱스에서 구성된 인덱스(예:
app)가 표시되는지 확인합니다. - LogBamboo 사용의 온보딩 안내에 따라 실제 쓰기 및 조회를 검증합니다.
플랫폼 데이터 전송을 사용하는 경우 전송 서비스가 위치한 네트워크에서 접근 가능 여부를 검증하고, 전송 규칙을 통해 전송된 데이터를 확인해야 합니다. 자세한 내용은 전송 결과 검증을 참조하세요.
데이터 전송 연결 정보 준비¶
인덱스 확인 또는 추가¶
위 설정에는 테넌트 default와 인덱스 app이 정의되어 있으며, 보존 정책은 7d입니다. 인덱스는 서버 측 TOML에서 정의하며, 현재 관리 페이지에서는 인덱스 생성 및 삭제 기능을 제공하지 않습니다. 로그인 후 먼저 왼쪽 목록에 app이 있는지 확인하고, 보존 기간은 비즈니스 요구 사항에 따라 수정합니다.
Standalone은 하나의 테넌트를 사용하며, 해당 테넌트 아래에 여러 인덱스를 구성할 수 있습니다. 여러 인덱스는 기본 스토리지, 테넌트 수준 Token 및 총 용량을 공유하지만 데이터는 각각 저장하고 자체 보존 정책을 적용합니다. 인덱스를 추가할 때 기존 블록은 유지하고 동일한 테넌트 아래에 추가합니다. 예:
수정 전에 현재 설정을 내보내 검토하고, 해당 환경의 변경 프로세스에 따라 설정을 업데이트한 뒤 서비스를 재시작합니다.
Kubernetes의 TOML은 subPath로 마운트되고 서비스 시작 시 읽힙니다. ConfigMap 업데이트 후 새 인덱스를 로드하려면 통제된 방식으로 Deployment를 재시작해야 합니다.
단일 인스턴스를 재시작하는 동안 서비스가 일시적으로 사용할 수 없습니다. memory 모드를 사용하는 경우 브라우저 세션에서 다시 로그인해야 합니다.
재시작 후 준비 상태와 인덱스 목록을 확인한 다음 새 인덱스로 전송합니다. 인덱스 이름은 ASCII 문자, 숫자, ., _, -만 허용하며 길이는 128자를 초과할 수 없고 . 또는 ..일 수 없습니다. 로컬 읽기 전용 계정 및 SSO의 새 인덱스 권한 부여는 별도로 확인해야 합니다.
관리자 및 데이터 플레인 자격 증명 준비¶
관리자 로그인 비밀번호는 관리 페이지에 사용하고, 쓰기 Token과 조회 Token은 데이터 인터페이스에 사용합니다. 세 가지는 각각 보관하며, 관리자 비밀번호나 Guance 워크스페이스 Token을 인터페이스 Token 대신 사용하지 않습니다.
| 자격 증명 | 이 문서의 초기 출처 | 용도 |
|---|---|---|
| 관리자 비밀번호 | Secret logbamboo-auth의 admin-password |
관리 페이지 로그인 |
| 쓰기 Token | Secret logbamboo-auth의 ingest-token |
현재 테넌트의 각 인덱스에 데이터 쓰기 |
| 조회 Token | Secret logbamboo-auth의 search-token |
현재 테넌트의 각 인덱스 데이터 조회 인터페이스 |
환경 변수 이름은 Token 실제 값이 아닙니다. 관리자는 설정 > 쓰기 Token에서 새 값을 생성하거나 입력하여 교체할 수 있습니다. 페이지는 이전 값을 다시 표시하지 않으며, 저장 후 즉시 교체되어 이중 Token 전환 기간이 없습니다. 먼저 새 값을 안전하게 저장한 다음 모든 전송 규칙을 동기화하여 업데이트하세요. UI에서 이미 교체한 경우 최초 Secret의 값이 더 이상 유효하지 않을 수 있으므로 실제로 적용된 Token을 인계해야 합니다.
연결 정보 인계¶
| 정보 | 제공 내용 |
|---|---|
| 서비스 주소 | 데이터 전송 서비스가 접근할 수 있는 루트 주소(예: https://logbamboo.example.com). /v1/indexes/.../logs 등의 인터페이스 경로를 붙이지 않습니다. |
| 대상 인덱스 | 구성 및 로드가 완료된 인덱스 이름(예: app). |
| 쓰기 Token | 현재 유효하며 대상 테넌트에 쓰기를 허용하는 자격 증명. |
| 조회 Token(선택 사항) | 콘솔에서 기록 데이터를 조회할 때 사용하며 쓰기 Token과 달라야 합니다. 전송만 수행하는 경우 제공하지 않아도 됩니다. |
| 신뢰 인증서(선택 사항) | 자체 서명 또는 기업 내부 HTTPS 인증서를 사용하는 경우 PEM 형식의 신뢰 인증서 내용을 제공합니다. |
동일한 Kubernetes 클러스터 내에서는 실제 Service에 따라 http://logbamboo.utils.svc.cluster.local:8080을 사용할 수 있습니다. 다른 클러스터 또는 공인 인터넷 호출자는 접근 가능성이 검증된 HTTPS 인그레스를 사용해야 합니다. 전체 Token은 통제된 채널을 통해 전달하며 공유 문서, 스크린샷 또는 로그에 기록하지 않습니다.
데이터 전송 연결 및 검증¶
- 콘솔의 데이터 전송 페이지로 이동하여 새 규칙을 만들고 LogBamboo 대상을 선택합니다.
- 이전 단계에서 준비한 연결 정보를 입력하고 연결 테스트 후 규칙을 저장한 뒤 활성화합니다. 자세한 내용은 LogBamboo로 데이터 전송을 참조하세요.
- 전송 조건에 맞는 데이터가 규칙으로 유입되도록 한 뒤 LogBamboo의 실행 상태에서 수신 및 처리 상황을 확인합니다.
- 데이터 처리가 완료될 때까지 기다린 후 서버 수신 시간을 기준으로 조회하여 예상 데이터가 포함되어 있는지 확인합니다. 자세한 단계는 전송 결과 검증을 참조하세요.
수신 성공과 조회 가능은 서로 다른 단계입니다. 프로덕션 기본 저트래픽 시나리오에서는 약 1시간 이상 기다려야 할 수 있습니다. 잠시 조회되지 않을 때는 먼저 시간 범위와 처리 상태를 확인하고 전체 배치를 반복 전송하지 마세요.
용량 및 상용 라이선스¶
커뮤니티 에디션은 라이선스가 필요하지 않으며 기본적으로 5 TB 데이터 보존 용량을 제공하고, 비압축 콘텐츠 기준으로 계산합니다. 상한에 도달하면 이전에 처리된 데이터가 자동으로 정리됩니다. 사용 전에 비즈니스 요구 사항에 따라 보존 기간과 용량을 확인하세요. 5 TB는 압축 후 디스크 사용량을 의미하지 않습니다.
라이선스 구매 및 활성화¶
더 큰 용량이 필요하면 영업 담당자에게 문의하여 상용 라이선스를 구매하세요. 라이선스는 현재 배포의 클러스터 ID에 바인딩되며, 절차는 다음과 같습니다:
- 관리자 계정으로 LogBamboo에 로그인하고 설정 > 라이선스로 이동합니다.
- 현재 클러스터 ID를 확인하고 복사한 뒤, 필요한 라이선스 용량 및 라이선스 기간과 함께 영업 담당자에게 제공하여 해당 클러스터에 바인딩된 오프라인 라이선스 파일을 받습니다.
- 설정 > 라이선스로 돌아가 오프라인 라이선스 파일에서 파일 선택을 클릭하고 받은 라이선스 파일을 업로드합니다.
- 라이선스 활성화를 클릭하고 페이지에 작업 완료 안내가 표시될 때까지 기다립니다.
- 실행 모드가 상용 플랜으로 변경되었는지, 용량 및 만료 시간이 구매한 라이선스와 일치하는지 확인합니다. 새로 고쳐야 하는 경우 상태 다시 로드를 클릭합니다.
라이선스 파일은 현재 클러스터에 바인딩되어야 하며 크기는 64 KiB를 초과할 수 없습니다. 오프라인 활성화에는 네트워크 연결이 필요하지 않습니다. 라이선스를 지원하는 통합 설치 패키지를 사용하는 경우 라이선스 활성화에 재설치나 서비스 재시작이 필요하지 않습니다. 다른 설치 패키지는 먼저 배포 지원에 호환성을 확인하세요.
갱신 및 라이선스 만료¶
갱신 시 영업 담당자에게 문의하여 현재 클러스터에 바인딩된 새 라이선스를 받고, 동일한 페이지에서 업로드 및 활성화한 뒤 업데이트된 만료 시간을 확인합니다. 배포를 교체하거나 서비스를 마이그레이션하기 전에 배포 지원과 클러스터 ID 및 라이선스 처리 방식을 확인하세요.
라이선스가 만료되었고 현재 사용량이 5 TB를 초과한 경우 신규 쓰기가 일시 중지되고 기존 데이터는 유지됩니다. 영업 담당자에게 갱신을 문의하고 새 라이선스를 업로드한 후 용량 및 만료 상태를 확인하거나, 관리자가 구성된 보존 정책에 따라 사용량을 5 TB 이내로 줄이세요.
아래 그림은 기존 라이선스가 만료된 후의 페이지 예시입니다. 그림의 실행 모드, 용량, 만료 시간 및 클러스터 ID는 페이지만 보여 주기 위한 것이며 현재 배포의 실제 상태를 기준으로 합니다. 커뮤니티 에디션을 처음 사용하는 경우 라이선스가 필요하지 않습니다.
자주 묻는 질문¶
| 문제 | 확인 및 처리 |
|---|---|
| 관리 페이지 로그인 방법을 모르는 경우 | 이 문서에서는 TOML로 서비스를 직접 구성하므로 최초 초기화 마법사가 필요하지 않습니다. 배포 완료 후 구성된 HTTPS 도메인에 접속하세요. 최초 로그인 시 admin 및 Secret logbamboo-auth에 설정한 관리자 비밀번호를 사용합니다. 접속할 수 없는 경우 Pod, Service, Ingress, 도메인 DNS 확인 및 TLS 인증서를 점검하세요. |
| 관리 페이지를 열 수 없음 | 서비스 실행 상태, 수신 주소, 포트 및 네트워크 액세스 규칙을 확인하세요. |
| 스토리지 설정 검증 실패 | 스토리지 디렉터리 권한 또는 오브젝트 스토리지의 주소, 버킷 및 액세스 자격 증명을 확인하고, 서버에서 스토리지 서비스로의 네트워크를 점검하세요. |
| 연결 테스트 실패 | 서비스 주소, 대상 인덱스, Token 및 HTTPS 인증서를 확인하고, 전송 서비스가 위치한 네트워크에서 검증 중인지 확인하세요. |
| 수신되었지만 일시적으로 조회되지 않음 | 처리 상태를 확인하고 서버 수신 시간을 기준으로 조회 범위를 선택한 뒤 처리가 완료될 때까지 기다리세요. |
| 라이선스 활성화 실패 | 라이선스가 현재 페이지에 표시된 클러스터 ID에 바인딩되어 있는지 확인하고, 배포 지원에 설치 패키지와 라이선스가 일치하는지 점검을 요청하세요. |
유지 관리¶
- 서비스 실행 상태, 사용 가능한 디스크 공간, 용량 증가 및 데이터 보존 범위를 정기적으로 확인합니다.
- 쓰기 또는 조회 Token을 교체한 후 해당 Token을 사용하는 전송 규칙을 동기화하여 업데이트합니다.
- 업그레이드 전에 설정과 로컬 실행 데이터를 보존하고 해당 버전의 업그레이드 설명을 읽으세요.
- 재해 복구 요구 사항이 있는 경우 복구 리포지토리와 복구 지점을 별도로 계획합니다. 콜드 아카이브 스토리지와 조회 내보내기는 재해 복구 백업을 대체할 수 없습니다.
다음 단계¶
서비스 배포 및 준비가 완료되면 LogBamboo 사용을 계속 읽고 로그인, 인덱스 확인, 데이터 연결 및 조회 결과 검증을 차례로 완료하세요.
