# Dashboard 참조

import { Tabs, TabItem } from '@astrojs/starlight/components';

Kubetail Dashboard는 Dashboard 웹 UI를 호스팅하고, 웹 UI가 Kubernetes 클러스터와 상호작용하는 데 사용하는 백엔드 API를 제공하는 Go 기반 HTTP 서버입니다. 서버 실행 파일은 Kubetail 저장소의 [modules/dashboard](https://github.com/kubetail-org/kubetail/tree/main/modules/dashboard)에 있는 소스 코드에서 빌드되며, 일반적으로 `kubetail-dashboard` Docker 이미지로 배포됩니다(아래 참조). `kubetail-dashboard`를 독립 실행형 컨테이너로 실행할 수도 있지만, 공식 Kubetail [Helm 차트](/ko/reference/helm-chart)로 배포하는 방식을 권장합니다.

## Docker 이미지

`kubetail-dashboard` Docker 이미지는 각 릴리스마다 Docker Hub와 GitHub Container Registry에 게시됩니다.

| Registry | Image |
|----------|-------|
| Docker Hub | `kubetail/kubetail-dashboard` |
| GHCR | `ghcr.io/kubetail-org/kubetail-dashboard` |

두 가지 변형이 제공됩니다.

| 태그 접미사 | 베이스 이미지 | 설명 |
|-------------|---------------|------|
| _(없음)_ | `scratch` | 가장 작은 크기의 최소 이미지 |
| `-alpine` | `alpine` | 셸과 표준 유틸리티 포함 |

## 엔트리포인트

기본 컨테이너 엔트리포인트는 `/dashboard/dashboard` 입니다.

```sh
dashboard [flags]
```

## 플래그

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--config` | `-c` | | 설정 파일 경로(예: `/etc/kubetail/dashboard.yaml`) |
| `--addr` | `-a` | `:8080` | 바인딩할 호스트 주소 |
| `--gin-mode` | | `release` | Gin 프레임워크 모드 (`release`, `debug`) |

## 설정

Dashboard는 YAML, JSON 또는 TOML 설정 파일로 구성할 수 있습니다. 파일 경로는 `-c` / `--config`로 전달합니다. 설정 파일에서는 `${VARIABLE_NAME}` 구문을 사용해 환경 변수를 참조할 수 있습니다.

```sh
dashboard --config /etc/kubetail/dashboard.yaml
```

<Tabs>
  <TabItem label="YAML">
    ```yaml
    ## Kubetail Dashboard Configuration File
    #
    # 이 파일은 kubetail dashboard server의 동작을 정의합니다.
    # 웹 UI를 제공하고 dashboard용 백엔드 API를 제공합니다.
    #

    ## allowed-namespaces ##
    #
    # dashboard가 접근할 수 있는 namespace 목록입니다.
    # 비어 있으면 모든 namespace에 접근할 수 있습니다.
    #
    # 기본값: []
    #
    allowed-namespaces: []

    ## kubeconfig ##
    #
    # Kubernetes API 요청에 사용할 kubeconfig 파일 경로입니다.
    # 비어 있으면 기본 경로(~/.kube/config) 또는 KUBECONFIG 환경 변수를 사용합니다.
    #
    # 기본값: ""
    #
    kubeconfig: ""

    ## addr ##
    #
    # HTTP 서버가 바인딩할 네트워크 주소와 포트입니다.
    #
    # 기본값: :8080
    #
    addr: ":8080"

    ## auth-mode ##
    #
    # dashboard의 인증 모드입니다.
    # 유효한 값: auto, token
    #
    # 기본값: auto
    #
    auth-mode: auto

    ## base-path ##
    #
    # 모든 dashboard 엔드포인트의 기본 URL 경로입니다.
    #
    # 기본값: /
    #
    base-path: /

    ## cluster-api-endpoint ##
    #
    # Cluster API 서버의 URL입니다.
    # 비어 있으면 Cluster API 통합이 비활성화됩니다.
    #
    # 기본값: ""
    #
    cluster-api-endpoint: ""

    ## environment ##
    #
    # dashboard가 실행되는 환경입니다.
    # 유효한 값: desktop, cluster
    #
    # 기본값: cluster
    #
    environment: cluster

    ## gin-mode ##
    #
    # Gin 프레임워크 모드입니다.
    # 유효한 값: debug, release
    #
    # 기본값: release
    #
    gin-mode: release

    ## csrf ##
    #
    # CSRF 보호 설정
    #
    csrf:

      ## enabled ##
      #
      # CSRF 보호를 활성화할지 여부입니다.
      #
      # 기본값: true
      #
      enabled: true

    ## logging ##
    #
    # dashboard server 로그 출력 설정
    #
    logging:

      ## enabled ##
      #
      # 서버에서 logging을 활성화할지 여부입니다.
      #
      # 기본값: true
      #
      enabled: true

      ## level ##
      #
      # 출력할 최소 로그 레벨입니다.
      # 유효한 값: debug, info, warn, error, disabled
      #
      # 기본값: info
      #
      level: info

      ## format ##
      #
      # 로그 출력 형식입니다.
      # 유효한 값: json, pretty
      #
      # 기본값: json
      #
      format: json

      ## access-log ##
      #
      # HTTP 액세스 로그 설정
      #
      access-log:

        ## enabled ##
        #
        # 액세스 로그를 활성화할지 여부입니다.
        #
        # 기본값: true
        #
        enabled: true

        ## hide-health-checks ##
        #
        # 액세스 로그에서 health check 요청(/healthz)을 숨길지 여부입니다.
        #
        # 기본값: false
        #
        hide-health-checks: false

    ## session ##
    #
    # 세션 관리 설정
    #
    session:

      ## secret ##
      #
      # 세션 토큰 서명에 사용하는 비밀 키입니다.
      # 비어 있으면 시작 시 임의의 secret이 생성되며(세션은
      # 재시작 후 유지되지 않습니다).
      #
      # 기본값: ""
      #
      secret: ""

      ## cookie ##
      #
      # 세션 쿠키 설정
      #
      cookie:

        ## name ##
        #
        # 세션 쿠키 이름입니다.
        #
        # 기본값: kubetail_dashboard_session
        #
        name: kubetail_dashboard_session

        ## path ##
        #
        # 쿠키가 유효한 URL 경로입니다.
        #
        # 기본값: /
        #
        path: /

        ## domain ##
        #
        # 쿠키가 유효한 도메인입니다.
        # 비어 있으면 현재 도메인에서만 유효합니다.
        #
        # 기본값: ""
        #
        domain: ""

        ## max-age ##
        #
        # 쿠키의 최대 수명(초)입니다.
        #
        # 기본값: 2592000 (30 days)
        #
        max-age: 2592000

        ## secure ##
        #
        # 쿠키를 HTTPS를 통해서만 전송할지 여부입니다.
        #
        # 기본값: false
        #
        secure: false

        ## http-only ##
        #
        # 쿠키를 JavaScript에서 접근할 수 없게 할지 여부입니다.
        #
        # 기본값: true
        #
        http-only: true

        ## same-site ##
        #
        # 쿠키의 SameSite 속성입니다.
        # 유효한 값: strict, lax, none
        #
        # 기본값: lax
        #
        same-site: lax

    ## tls ##
    #
    # HTTP 서버용 TLS 설정
    #
    tls:

      ## enabled ##
      #
      # TLS를 활성화할지 여부입니다.
      #
      # 기본값: false
      #
      enabled: false

      ## cert-file ##
      #
      # TLS 인증서 파일 경로입니다.
      #
      # 기본값: ""
      #
      cert-file: ""

      ## key-file ##
      #
      # TLS 개인 키 파일 경로입니다.
      #
      # 기본값: ""
      #
      key-file: ""

    ## ui ##
    #
    # UI 전용 설정 옵션
    #
    ui:

      ## cluster-api-enabled ##
      #
      # UI에서 Cluster API 통합을 활성화할지 여부입니다.
      #
      # 기본값: true
      #
      cluster-api-enabled: true
    ```
  </TabItem>
</Tabs>