본문으로 바로가기
본문으로 바로가기

Helm 구성 (v1.x)

지원 중단 — v1.x 차트

이 페이지에서는 유지보수 모드인 v1.x 인라인 템플릿 Helm 차트의 구성 방법을 설명합니다. v2.x 차트는 Helm 구성을 참조하십시오. 마이그레이션하려면 업그레이드 가이드를 참조하십시오.

이 가이드는 ClickStack Helm 배포의 구성 옵션을 다룹니다. 기본 설치 방법은 기본 Helm 배포 가이드를 참조하십시오.

API 키 설정​

ClickStack을 성공적으로 배포한 후 텔레메트리 데이터 수집을 활성화하려면 API 키를 구성하십시오:

  1. 구성된 인그레스 또는 서비스 엔드포인트를 통해 HyperDX 인스턴스에 접속합니다
  2. HyperDX 대시보드에 로그인한 다음 Team settings로 이동하여 API 키를 생성하거나 확인합니다
  3. 다음 방법 중 하나를 사용하여 배포를 업데이트합니다:

방법 1: values 파일을 사용해 Helm upgrade로 업데이트​

values.yaml에 API 키를 추가합니다:

hyperdx:
  apiKey: "your-api-key-here"

그런 다음 배포를 업그레이드하세요:

helm upgrade my-clickstack clickstack/clickstack -f values.yaml

방법 2: --set 플래그를 사용해 Helm upgrade로 업데이트​

helm upgrade my-clickstack clickstack/clickstack --set hyperdx.apiKey="your-api-key-here"

변경 사항을 적용하려면 파드를 다시 시작하세요​

API 키를 업데이트한 후 새 구성이 적용되도록 파드를 다시 시작하세요:

kubectl rollout restart deployment my-clickstack-clickstack-app my-clickstack-clickstack-otel-collector
참고

차트는 API 키가 포함된 Kubernetes 시크릿(<release-name>-app-secrets)을 자동으로 생성합니다. 외부 시크릿을 사용하려는 경우가 아니라면 별도의 시크릿 구성은 필요하지 않습니다.

시크릿 관리​

API キー나 데이터베이스 자격 증명과 같은 민감한 데이터를 처리하려면 Kubernetes 시크릿을 사용하십시오.

미리 구성된 시크릿 사용​

Helm 차트에는 charts/clickstack/templates/secrets.yaml에 있는 기본 시크릿 템플릿이 포함되어 있습니다. 이 파일은 시크릿 관리를 위한 기본 구조를 제공합니다.

시크릿을 수동으로 적용해야 하는 경우에는 제공된 secrets.yaml 템플릿을 수정하여 적용하십시오:

apiVersion: v1
kind: Secret
metadata:
  name: hyperdx-secret
  annotations:
    "helm.sh/resource-policy": keep
type: Opaque
data:
  API_KEY: <base64-encoded-api-key>

클러스터에 시크릿을 적용하십시오:

kubectl apply -f secrets.yaml

사용자 지정 시크릿 생성하기​

사용자 지정 Kubernetes 시크릿을 직접 생성하세요:

kubectl create secret generic hyperdx-secret \
  --from-literal=API_KEY=my-secret-api-key

values.yaml에서 시크릿 참조하기​

hyperdx:
  apiKey:
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: API_KEY

인그레스 설정​

도메인 이름으로 HyperDX UI와 API를 노출하려면 values.yaml에서 인그레스를 활성화하세요.

일반적인 인그레스 구성​

hyperdx:
  frontendUrl: "https://hyperdx.yourdomain.com"  # Must match ingress host
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
중요 구성 관련 참고 사항

hyperdx.frontendUrl은 인그레스 호스트와 일치해야 하며, 프로토콜(예: https://hyperdx.yourdomain.com)도 포함해야 합니다. 이렇게 해야 생성되는 링크, 쿠키, 리디렉션이 모두 올바르게 작동합니다.

TLS (HTTPS) 활성화​

배포를 HTTPS로 보호하려면:

1. 인증서와 키를 사용해 TLS 시크릿 생성하기:

kubectl create secret tls hyperdx-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key

2. 인그레스 설정에서 TLS를 활성화하세요:

hyperdx:
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
    tls:
      enabled: true
      tlsSecretName: "hyperdx-tls"

예시 인그레스 구성​

참고용으로, 생성된 인그레스 리소스는 다음과 같습니다:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hyperdx-app-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$1
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: nginx
  rules:
    - host: hyperdx.yourdomain.com
      http:
        paths:
          - path: /(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: my-clickstack-clickstack-app
                port:
                  number: 3000
  tls:
    - hosts:
        - hyperdx.yourdomain.com
      secretName: hyperdx-tls

일반적인 인그레스 관련 문제​

경로 및 rewrite 구성:

  • Next.js 및 기타 SPA에서는 위에 표시된 것처럼 항상 Regex 경로와 rewrite 어노테이션을 사용하십시오
  • rewrite 없이 path: /만 사용하지 마십시오. 정적 에셋 제공이 중단될 수 있습니다

frontendUrl과 ingress.host 불일치:

  • 이 값이 서로 일치하지 않으면 쿠키, 리디렉션, 에셋 로딩에 문제가 발생할 수 있습니다

TLS 구성 오류:

  • TLS 시크릿이 유효한지, 그리고 인그레스에서 올바르게 참조되고 있는지 확인하십시오
  • TLS가 활성화된 상태에서 HTTP로 앱에 접근하면 브라우저가 안전하지 않은 콘텐츠를 차단할 수 있습니다

인그레스 컨트롤러 버전:

  • 일부 기능(예: Regex 경로 및 rewrite)은 최신 버전의 nginx ingress controller가 필요합니다
  • 다음 명령으로 버전을 확인하십시오:
kubectl -n ingress-nginx get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath="{.items[0].spec.containers[0].image}"

OTel collector 인그레스​

OTel collector 엔드포인트(트레이스, 메트릭, 로그)를 인그레스를 통해 노출해야 하는 경우 additionalIngresses 구성을 사용하십시오. 이 설정은 클러스터 외부에서 텔레메트리 데이터를 전송하거나 OTel collector에 사용자 지정 도메인을 사용할 때 유용합니다.

hyperdx:
  ingress:
    enabled: true
    additionalIngresses:
      - name: otel-collector
        annotations:
          nginx.ingress.kubernetes.io/ssl-redirect: "false"
          nginx.ingress.kubernetes.io/force-ssl-redirect: "false"
          nginx.ingress.kubernetes.io/use-regex: "true"
        ingressClassName: nginx
        hosts:
          - host: collector.yourdomain.com
            paths:
              - path: /v1/(traces|metrics|logs)
                pathType: Prefix
                port: 4318
                name: otel-collector
        tls:
          - hosts:
              - collector.yourdomain.com
            secretName: collector-tls
  • 이렇게 하면 OTel collector 엔드포인트용으로 별도의 인그레스 리소스가 생성됩니다
  • 다른 도메인을 사용하고, 특정 TLS 설정을 구성하고, 사용자 지정 어노테이션을 적용할 수 있습니다
  • Regex 경로 규칙을 사용하면 모든 OTLP 신호(트레이스, 메트릭, 로그)를 단일 규칙으로 라우팅할 수 있습니다
참고

OTel collector를 외부에 노출할 필요가 없다면 이 구성은 생략해도 됩니다. 대부분의 사용자에게는 일반 인그레스 설정으로 충분합니다.

인그레스 문제 해결​

인그레스 리소스를 확인합니다:

kubectl get ingress -A
kubectl describe ingress <ingress-name>

인그레스 컨트롤러 로그를 확인하세요:

kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx

정적 리소스 URL 테스트:

curl을 사용하여 정적 리소스가 HTML이 아니라 JS로 제공되는지 확인하십시오:

curl -I https://hyperdx.yourdomain.com/_next/static/chunks/main-xxxx.js
# Should return Content-Type: application/javascript

브라우저 DevTools:

  • Network 탭에서 404 오류가 발생하거나 JS 대신 HTML을 반환하는 에셋이 있는지 확인하세요
  • 콘솔에서 Unexpected token <와 같은 오류를 찾으세요(이는 JS 대신 HTML이 반환되었음을 의미합니다)

경로 재작성 확인:

  • 인그레스가 에셋 경로를 제거하거나 잘못 재작성하지 않는지 확인하세요

브라우저 및 CDN 캐시 지우기:

  • 변경 후에는 오래된 에셋이 계속 사용되지 않도록 브라우저 캐시와 CDN/프록시 캐시를 지우세요

설정값 사용자 지정​

--set 플래그로 설정값을 사용자 지정할 수 있습니다:

helm install my-clickstack clickstack/clickstack --set key=value

또는 사용자 지정 values.yaml을 생성하십시오. 기본값을 가져오려면 다음을 실행하십시오:

helm show values clickstack/clickstack > values.yaml

구성 예시:

replicaCount: 2

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi

hyperdx:
  ingress:
    enabled: true
    host: hyperdx.example.com

사용자 지정 값을 적용하세요:

helm install my-clickstack clickstack/clickstack -f values.yaml

다음 단계​