{"id":30047578,"url":"https://github.com/tmax-cloud/install-loki","last_synced_at":"2025-08-07T09:56:37.382Z","repository":{"id":45207133,"uuid":"513410999","full_name":"tmax-cloud/install-loki","owner":"tmax-cloud","description":null,"archived":false,"fork":false,"pushed_at":"2023-03-08T09:10:41.000Z","size":2694,"stargazers_count":0,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-19T10:10:08.867Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tmax-cloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-07-13T06:46:29.000Z","updated_at":"2022-07-14T01:19:57.000Z","dependencies_parsed_at":"2023-02-03T17:16:20.776Z","dependency_job_id":null,"html_url":"https://github.com/tmax-cloud/install-loki","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tmax-cloud/install-loki","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmax-cloud%2Finstall-loki","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmax-cloud%2Finstall-loki/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmax-cloud%2Finstall-loki/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmax-cloud%2Finstall-loki/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tmax-cloud","download_url":"https://codeload.github.com/tmax-cloud/install-loki/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmax-cloud%2Finstall-loki/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269236777,"owners_count":24383241,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-07T02:00:09.698Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-07T09:56:32.207Z","updated_at":"2025-08-07T09:56:37.362Z","avatar_url":"https://github.com/tmax-cloud.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Loki 기능 가이드\n* [Grafana-Loki 로그 조회 가이드](doc/README_basic.md)\n* [Loki Alert 설정 가이드](doc/README_alert.md)\n* [Loki Log Dashboard 권한 설정 가이드](doc/README_dashboardrole.md)\n* [Opensearch-Loki 마이그레이션 가이드](doc/README_lokimigration.md)\n\n# Loki 설치 가이드\n\n## 개요\n* Loki Stack은 loki, promtail, grafana로 구성된 플랫폼 조합이다.\n* K8S 클러스터로부터 promtail 수집한 로그를 loki에 적재하면, loki는 수집된 로그를 저장하고 요청에 따라 검색 기능을 제공한다. 그리고 Grafana를 통해 loki에 적재된 데이터를 시각화한다.\n\n## 구성 요소 및 버전\n* Grafana Loki ([grafana/loki:2.7.1(https://hub.docker.com/layers/grafana/loki/2.7.1/images/sha256-d69f377ecfdbb3f72086a180dcd7c2f02c795cf1867bbeb61606b42a8d41a557?context=explore))\n* Grafana Promtail ([grafana/promtail:2.7.1(https://hub.docker.com/layers/grafana/promtail/2.7.1/images/sha256-38a955569ede670e3e91673cce00bf41990b4a3e88b011d1e6cb2b186e6a78fc?context=explore))\n\n## Prerequisites\n* 필수 모듈\n  * [RookCeph](https://github.com/tmax-cloud/hypersds-wiki/)\n  * [Grafana 8.2.2](https://github.com/tmax-cloud/install-grafana/tree/5.1) 또는 [Grafana-Operator](https://github.com/tmax-cloud/install-grafana-operator)\n\n## 폐쇄망 설치 가이드\n* 설치를 진행하기 전 아래의 과정을 통해 필요한 이미지 및 yaml 파일을 준비한다.\n* 그 후, Install Step을 진행하면 된다.\n1. 사용하는 image repository에 Loki stack 설치 시 필요한 이미지를 push한다. \n\n    * 작업 디렉토리 생성 및 환경 설정\n    ```bash\n    $ mkdir -p ~/loki-install\n    $ export OS_HOME=~/loki-install\n    $ cd $OS_HOME\n    $ export LOKI_VERSION=2.7.1\n    $ export PROMTAIL_VERSION=2.7.1\n    $ export REGISTRY={ImageRegistryIP:Port}\n    ```\n    * 외부 네트워크 통신이 가능한 환경에서 필요한 이미지를 다운받는다.\n    ```bash\n    $ sudo docker pull grafana/loki:${LOKI_VERSION}\n    $ sudo docker save grafana/loki:${LOKI_VERSION} \u003e loki_${LOKI_VERSION}.tar\n    $ sudo docker pull grafana/promtail:${PROMTAIL_VERSION}\n    $ sudo docker save grafana/promtail:${PROMTAIL_VERSION} \u003e promtail_${PROMTAIL_VERSION}.tar\n    ```\n  \n2. 위의 과정에서 생성한 tar 파일들을 폐쇄망 환경으로 이동시킨 뒤 사용하려는 registry에 이미지를 push한다.\n    ```bash\n    $ sudo docker load \u003c loki_${LOKI_VERSION}.tar\n    $ sudo docker load \u003c promtail_${PROMTAIL_VERSION}.tar\n    \n    $ sudo docker tag grafana/loki:${LOKI_VERSION} ${REGISTRY}/grafana/loki:${LOKI_VERSION}\n    $ sudo docker tag grafana/promtail:${PROMTAIL_VERSION} ${REGISTRY}/grafana/promtail:${PROMTAIL_VERSION}\n    \n    $ sudo docker push ${REGISTRY}/grafana/loki:${LOKI_VERSION}\n    $ sudo docker push ${REGISTRY}/grafana/promtail:${PROMTAIL_VERSION}\n    ```\n\n## Step 0. loki.config 설정\n* 목적 : `yaml/loki.config 파일에 설치를 위한 정보 기입`\n* 순서: \n\t* 환경에 맞는 config 내용 작성\n\t\t* LOKI_VERSION\n\t\t\t* Loki 의 버전\n\t\t\t* ex) 2.7.1\n\t    * PROMTAIL_VERSION \n\t        * Promtail 의 버전\n\t\t\t* ex) 2.7.1\n\t\t* STORAGECLASS_NAME\n\t\t\t* Loki가 사용할 StorageClass 의 이름\n            * {STORAGECLASS_NAME} 그대로 유지시 default storageclass 사용\n\t\t\t* ex) csi-cephfs-sc\n\t\t* REGISTRY\n\t\t\t* 폐쇄망 사용시 image repository의 주소\n\t\t\t* 폐쇄망 아닐시 {REGISTRY} 그대로 유지\n\t\t\t* ex) 192.168.171:5000\n\n## Step 1. installer 실행\n* 목적 : `설치를 위한 shell script 실행`\n* 순서: \n\t* 권한 부여 및 실행\n\t``` bash\n\t$ sudo chmod +x yaml/install.sh\n\t$ sudo chmod +x yaml/uninstall.sh\n\t$ ./yaml/install.sh\n\t```\n\n## 삭제 가이드\n* 목적 : `삭제를 위한 shell script 실행`\n* 순서: \n\t* 실행\n\t``` bash\n\t$ ./yaml/uninstall.sh\n\t```\n\n## 수동 설치 가이드\n## Prerequisites\n1. Namespace 생성\n    * loki stack을 설치할 namespace를 생성한다.\n    ```bash\n    $ kubectl create ns monitoring\n    ```\n    \n2. 변수 export\n    * 다운 받을 버전을 export한다. \n    ```bash\n    $ export LOKI_VERSION=2.7.1\n    $ export PROMTAIL_VERSION=2.7.1\n    $ export STORAGECLASS_NAME=csi-cephfs-sc\n    ```\n\n* 비고  \n    * 이하 인스톨 가이드는 StorageClass 이름이 csi-cephfs-sc 라는 가정하에 진행한다.\n\n## Install Steps\n0. [Loki-stack yaml 수정](https://github.com/tmax-cloud/install-loki#step-0-loki-stack-yaml-%EC%88%98%EC%A0%95)\n1. [Loki 설치](https://github.com/tmax-cloud/install-loki#step-1-loki-%EC%84%A4%EC%B9%98)\n2. [Promtail 설치](https://github.com/tmax-cloud/install-loki#step-2-promtail-%EC%84%A4%EC%B9%98)\n\n## Step 0. loki-stack yaml 수정\n* 목적 : `loki-stack yaml에 이미지 registry, 버전 및 노드 정보를 수정`\n* 생성 순서 : \n    * 아래의 command를 사용하여 사용하고자 하는 image 버전을 입력한다.\n\t```bash\n\t$ sed -i 's/{LOKI_VERSION}/'${LOKI_VERSION}'/g' 01_loki.yaml\n\t$ sed -i 's/{STORAGECLASS_NAME}/'${STORAGECLASS_NAME}'/g' 01_loki.yaml\n    $ sed -i 's/{PROMTAIL_VERSION}/'${PROMTAIL_VERSION}'/g' 02_promtail.yaml\n    \n\t```\n* 비고 :\n    * `폐쇄망에서 설치를 진행하여 별도의 image registry를 사용하는 경우 registry 정보를 추가로 설정해준다.`\n\t```bash\n\t$ sed -i 's/docker.io\\/grafana\\/loki/'${REGISTRY}'\\/grafana\\/loki/g' 01_loki.yaml\n\t$ sed -i 's/docker.io\\/grafana\\/promtail/'${REGISTRY}'\\/grafana\\/promtail/g' 02_promtail.yaml\n\t```    \n    \n## Step 1. Loki 설치\n* 목적 : `Loki 설치`\n* 생성 순서 : \n    * [01_loki.yaml](yaml/01_loki.yaml) 실행\n\t```bash\n\t$ kubectl apply -f 01_loki.yaml\n\t```     \n* 비고 :\n    * StorageClass 이름이 csi-cephfs-sc가 아니라면 환경에 맞게 수정해야 한다.\n\n## Step 2. Promtail 설치\n* 목적 : `loki stack의 daemon 역할을 수행하는 promtail을 설치`\n* 생성 순서 : [02_promtail.yaml](yaml/02_promtail.yaml) 실행 \n    ```bash\n    $ kubectl apply -f 02_promtail.yaml\n    ```\n\n## Loki-Grafana 연동\n* 목적: loki에 적재된 log data를 Grafana UI를 통해 조회\n* 순서: \n    * Admin 권한을 가진 유저로 Grafana UI에 접속하여 Configuration \u003e DataSource를 클릭한다.\n![image](figure/grafana-ui.png)\n    \n    * Datasource 화면에서 Add data source 버튼을 클릭 후, data source type 목록에서 loki를 클릭한다.\n![image](figure/grafana-ui2.png)\n    \n    * Loki 설정에서 HTTP URI에 \"http://loki.monitoring.svc:3100\" 을 추가한 뒤 Save \u0026 Test를 클릭한다.\n![image](figure/grafana-ui3.png)\n\n* Grafana의 Explore 화면에서 Loki에 적재된 로그 내용을 확인할 수 있다.\n    * ex) namespace가 kafka인 로그 조회 시, namespace label에서 kafka를 클릭 후, show logs 버튼을 클릭한다.\n![image](figure/grafana-ui4.png)\n\n![image](figure/grafana-ui5.png)\n\n\n## 비고\n\n### 1. Loki와 Promtail 모듈의 log level 설정\n* Loki: logger class는 DEBUG, INFO, WARN, ERROR 총 4단계로 지원, default로 설정된 log level은 INFO\n* loki-config ConfigMap에서 원하는 log level로 설정한다.\n\nex) loki-config ConfigMap 적용 예시\n    \n    loki.yaml: |\n      server:\n        http_listen_port: 3100\n        log_level: error ## 원하는 log level로 설정한다.\n\n* Promtail: loki와 동일하게 DEBUG, INFO, WARN, ERROR 총 4단계로 지원, default로 설정된 log level은 INFO\n* promtail-config ConfigMap에서 원하는 log level로 설정한다.\n\nex) loki-config ConfigMap 적용 예시\n    \n    promtail-config.yaml: |\n      server:\n        http_listen_port: 9080\n\t    grpc_listen_port: 0\n        log_level: error ## 원하는 log level로 설정한다.\n\n### 2. Loki HA 구성 가이드\n* 목적: Loki 파드에 대하여 Active-Active 방식으로 기동하기 위한 설정이다.\n* Loki 구성: Loki Statefulset의 replica를 2로 수정한다.\n    * ex) [01_loki.yaml](yaml/01_loki.yaml)의 statefulset 예시\n\n    ```\n    apiVersion: apps/v1\n    kind: StatefulSet\n    metadata:\n      name: loki\n      namespace: monitoring\n    labels:\n      app: loki\n    spec:\n      replicas: 2 ## 1에서 2로 수정\n      selector:\n        matchLabels:\n          app: loki \n    ```\n\n### 3. Loki에서 조회할 수 있는 Label Filter 설정\n* 목적: Promtail에서 로그 수집 시, 원하는 label만 볼 수 있도록 whitelist를 기반으로 필터링하기 위함.\n* Promtail config에서 job_name 별로 pipeline_stages 설정을 추가하여 조회를 원하는 label 이름을 기입한다.\n    * 비고: 현재 promtail config에 설정된 job_name은 총 5개이며, 각 pipeline_stages 설정도 5번 추가해야 한다\n    * ex) [02_promtail.yaml](yaml/02_promtail.yaml)의 configmap 예시\n    \n    ```\n    promtail-config.yaml: |\n    \n    scrape_configs:\n    - job_name: kubernetes-pods-name\n      kubernetes_sd_configs:\n      - role: pod\n      pipeline_stages:\n      - labelallow:            ## app, job, filename, namespace, pod_name, container_name label만 loki에서 조회할 수 있다.\n        - app\n        - job\n        - filename\n        - namespace\n        - pod_name\n        - container_name\n      relabel_configs:\n      - source_labels:\n        - __meta_kubernetes_pod_label_name\n      target_label: __service__\n      \n      ...\n      \n    ```\n### 4. Loki 로그 보관 주기(Retention) 설정\n* 목적: 로키에 적재된 로그 데이터의 보관 주기를 설정하고 특정 label에 대한 custom retention을 적용할 수 있다.\n* loki-config의 limits_config에서 retention_period를 원하는 기간으로 설정하여 전체 로그 데이터의 보관주기를 설정할 수 있다.\n* 특정 라벨만 별도의 retention 기간을 설정할 경우, retention_stream을 통해 설정할 수 있다.\n* 기존 설정에서 configmap 설정을 변경한 후에는 loki statefulset을 재기동해야한다.\n\n* ex) [01_loki.yaml](yaml/01_loki.yaml)의 configmap인 loki-config에서 limits_config retention 설정 예시\n\n ```\n   limits_config:\n      retention_period: 168h                ### default로 설정한 retention 기간은 7일이며, 최소 설정 가능 기간은 24h이다.\n      retention_stream:\n      - selector: '{namespace=\"\"}' or '{pod_name=\"\"}'     ### 특정 네임스페이스 또는 특정 파드만 별도의 기간으로 설정하고자 할 경우\n        priority: 1                                       ### selector에 해당 라벨을 지정한 후, period에서 원하는 기간으로 설정한다.\n        period: 24h                                       ### 최소 설정 가능 기간은 24h이다.\n      enforce_metric_name: false\n      ingestion_rate_mb: 16\n      ingestion_burst_size_mb: 32\n      per_stream_rate_limit: 10mb\n      per_stream_rate_limit_burst: 50mb\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmax-cloud%2Finstall-loki","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftmax-cloud%2Finstall-loki","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmax-cloud%2Finstall-loki/lists"}