Kubernetes

O ClickStack usa o OTel collector do OpenTelemetry para coletar logs, métricas e eventos do Kubernetes em clusters Kubernetes e encaminhá-los ao ClickStack. Oferecemos suporte ao formato nativo de logs do OTel e não exigimos nenhuma configuração adicional específica de fornecedor. Este guia integra o seguinte:

Logs
Métricas de infraestrutura

Para enviar métricas no nível da aplicação ou APM/traces, você também precisará adicionar à aplicação a integração de linguagem correspondente.

O guia a seguir pressupõe que você implantou um ClickStack OTel collector como gateway, protegido com uma API key de ingestão.

Criando os arquivos de configuração do Chart do Helm do OTel

Para coletar logs e métricas de cada nó e também do próprio cluster, precisaremos implantar dois coletores OpenTelemetry separados. Um será implantado como um Conjunto de Daemon para coletar logs e métricas de cada nó, e o outro será implantado como uma Implantação para coletar logs e métricas do próprio cluster.

Criando um Secret com a API key

Crie um novo Secret do Kubernetes com a API key de ingestão do HyperDX. Ela será usada pelos componentes instalados abaixo para fazer a ingestão com segurança no seu ClickStack OTel collector:

kubectl create secret generic hyperdx-secret \
--from-literal=HYPERDX_API_KEY=<ingestion_api_key> \

Além disso, crie um ConfigMap com a localização do seu ClickStack OTel collector:

kubectl create configmap -n=otel-demo otel-config-vars --from-literal=YOUR_OTEL_COLLECTOR_ENDPOINT=<OTEL_COLLECTOR_ENDPOINT>
# ex.: kubectl create configmap -n=otel-demo otel-config-vars --from-literal=YOUR_OTEL_COLLECTOR_ENDPOINT=http://my-hyperdx-hdx-oss-v2-otel-collector:4318

Criando a configuração do Conjunto de Daemon

O Conjunto de Daemon coletará logs e métricas de cada nó do cluster, mas não coletará eventos do Kubernetes nem métricas de todo o cluster. Baixe o manifesto do Conjunto de Daemon:

curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_daemonset.yaml

ClickStack Gerenciado
ClickStack Open Source

k8s_daemonset.yaml

# daemonset.yaml
mode: daemonset

# Necessário para usar as métricas de utilização de CPU/memória do kubeletstats
clusterRole:
  create: true
  rules:
    - apiGroups:
        - ''
      resources:
        - nodes/proxy
      verbs:
        - get

presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  # Configura o processador do Kubernetes para adicionar metadados do Kubernetes.
  # Adiciona o processador k8sattributes a todos os pipelines e inclui as regras necessárias na Função de cluster.
  # Mais informações: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-attributes-processor
  kubernetesAttributes:
    enabled: true
    # Quando habilitado, o processador extrairá todos os rótulos de um pod do Kubernetes associado e os adicionará como atributos de recurso.
    # O nome exato do rótulo será a chave.
    extractAllPodLabels: true
    # Quando habilitado, o processador extrairá todas as anotações de um pod do Kubernetes associado e as adicionará como atributos de recurso.
    # O nome exato da anotação será a chave.
    extractAllPodAnnotations: true
  # Configura o coletor para coletar métricas de nó, pod do Kubernetes e contêiner do servidor de API no agente de nó do Kubernetes.
  # Adiciona o receiver kubeletstats ao pipeline de métricas e inclui as regras necessárias na Função de cluster.
  # Mais informações: https://opentelemetry.io/docs/kubernetes/collector/components/#kubeletstats-receiver
  kubeletMetrics:
    enabled: true

extraEnvs:
  - name: YOUR_OTEL_COLLECTOR_ENDPOINT
    valueFrom:
      configMapKeyRef:
        name: otel-config-vars
        key: YOUR_OTEL_COLLECTOR_ENDPOINT

config:
  receivers:
    # Configura métricas adicionais do agente de nó do Kubernetes
    kubeletstats:
      collection_interval: 20s
      auth_type: 'serviceAccount'
      endpoint: '${env:K8S_NODE_NAME}:10250'
      insecure_skip_verify: true
      metrics:
        k8s.pod.cpu_limit_utilization:
          enabled: true
        k8s.pod.cpu_request_utilization:
          enabled: true
        k8s.pod.memory_limit_utilization:
          enabled: true
        k8s.pod.memory_request_utilization:
          enabled: true
        k8s.pod.uptime:
          enabled: true
        k8s.node.uptime:
          enabled: true
        k8s.container.cpu_limit_utilization:
          enabled: true
        k8s.container.cpu_request_utilization:
          enabled: true
        k8s.container.memory_limit_utilization:
          enabled: true
        k8s.container.memory_request_utilization:
          enabled: true
        container.uptime:
          enabled: true

  exporters:
    otlphttp:
      endpoint: "${env:YOUR_OTEL_COLLECTOR_ENDPOINT}"
      compression: gzip

  service:
    pipelines:
      logs:
        exporters:
          - otlphttp
      metrics:
        exporters:
          - otlphttp

k8s_daemonset.yaml

# daemonset.yaml
mode: daemonset

# Necessário para usar as métricas de utilização de CPU/memória do kubeletstats
clusterRole:
  create: true
  rules:
    - apiGroups:
        - ''
      resources:
        - nodes/proxy
      verbs:
        - get

presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  # Configura o Processador do Kubernetes para adicionar metadados do Kubernetes.
  # Adiciona o processador k8sattributes a todos os pipelines e as regras necessárias à Função de cluster.
  # Mais informações: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-attributes-processor
  kubernetesAttributes:
    enabled: true
    # Quando habilitado, o processador extrairá todos os labels de um pod associado e os adicionará como atributos de resource.
    # O nome exato do label será a chave.
    extractAllPodLabels: true
    # Quando habilitado, o processador extrairá todas as annotations de um pod associado e as adicionará como atributos de resource.
    # O nome exato da annotation será a chave.
    extractAllPodAnnotations: true
  # Configura o collector para coletar métricas de nó, pod e contêiner do servidor de API em um agente de nó do Kubernetes.
  # Adiciona o receiver kubeletstats ao pipeline de métricas e as regras necessárias à Função de cluster.
  # Mais informações: https://opentelemetry.io/docs/kubernetes/collector/components/#kubeletstats-receiver
  kubeletMetrics:
    enabled: true

extraEnvs:
  - name: HYPERDX_API_KEY
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: HYPERDX_API_KEY
        optional: true
  - name: YOUR_OTEL_COLLECTOR_ENDPOINT
    valueFrom:
      configMapKeyRef:
        name: otel-config-vars
        key: YOUR_OTEL_COLLECTOR_ENDPOINT

config:
  receivers:
    # Configura métricas adicionais do agente de nó do Kubernetes
    kubeletstats:
      collection_interval: 20s
      auth_type: 'serviceAccount'
      endpoint: '${env:K8S_NODE_NAME}:10250'
      insecure_skip_verify: true
      metrics:
        k8s.pod.cpu_limit_utilization:
          enabled: true
        k8s.pod.cpu_request_utilization:
          enabled: true
        k8s.pod.memory_limit_utilization:
          enabled: true
        k8s.pod.memory_request_utilization:
          enabled: true
        k8s.pod.uptime:
          enabled: true
        k8s.node.uptime:
          enabled: true
        k8s.container.cpu_limit_utilization:
          enabled: true
        k8s.container.cpu_request_utilization:
          enabled: true
        k8s.container.memory_limit_utilization:
          enabled: true
        k8s.container.memory_request_utilization:
          enabled: true
        container.uptime:
          enabled: true

  exporters:
    otlphttp:
      endpoint: "${env:YOUR_OTEL_COLLECTOR_ENDPOINT}"
      headers:
        authorization: "${env:HYPERDX_API_KEY}"
      compression: gzip

  service:
    pipelines:
      logs:
        exporters:
          - otlphttp
      metrics:
        exporters:
          - otlphttp

Criando a configuração da implantação

Para coletar eventos do Kubernetes e métricas em todo o cluster, precisaremos implantar um coletor OpenTelemetry separado na forma de uma implantação. Baixe o manifesto da implantação:

curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_deployment.yaml

Managed ClickStack
ClickStack Open Source

k8s_deployment.yaml

# deployment.yaml
mode: deployment

image:
  repository: otel/opentelemetry-collector-contrib
  tag: 0.123.0
 
# Queremos apenas um desses coletores — mais do que isso geraria dados duplicados
replicaCount: 1
 
presets:
  kubernetesAttributes:
    enabled: true
    # Quando habilitado, o processador extrairá todos os labels de um pod do Kubernetes associado e os adicionará como atributos de recurso.
    # O nome exato do label será a chave.
    extractAllPodLabels: true
    # Quando habilitado, o processador extrairá todas as annotations de um pod do Kubernetes associado e as adicionará como atributos de recurso.
    # O nome exato da annotation será a chave.
    extractAllPodAnnotations: true
  # Configura o coletor para coletar eventos do Kubernetes.
  # Adiciona o k8sobject receiver ao pipeline de logs e coleta eventos do Kubernetes por padrão.
  # Mais informações: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-objects-receiver
  kubernetesEvents:
    enabled: true
  # Configura o Kubernetes Cluster Receiver para coletar métricas em nível de cluster.
  # Adiciona o k8s_cluster receiver ao pipeline de métricas e adiciona as regras necessárias ao ClusterRole.
  # Mais informações: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-cluster-receiver
  clusterMetrics:
    enabled: true

extraEnvs:
  - name: YOUR_OTEL_COLLECTOR_ENDPOINT
    valueFrom:
      configMapKeyRef:
        name: otel-config-vars
        key: YOUR_OTEL_COLLECTOR_ENDPOINT

config:
  exporters:
    otlphttp:
      endpoint: "${env:YOUR_OTEL_COLLECTOR_ENDPOINT}"
      compression: gzip
  service:
    pipelines:
      logs:
        exporters:
          - otlphttp
      metrics:
        exporters:
          - otlphttp

k8s_deployment.yaml

# deployment.yaml
mode: deployment

image:
  repository: otel/opentelemetry-collector-contrib
  tag: 0.123.0
 
# Queremos apenas um desses coletores — mais do que isso geraria dados duplicados
replicaCount: 1
 
presets:
  kubernetesAttributes:
    enabled: true
    # Quando habilitado, o processador extrairá todos os labels de um pod do Kubernetes associado e os adicionará como atributos de recurso.
    # O nome exato do label será a chave.
    extractAllPodLabels: true
    # Quando habilitado, o processador extrairá todas as annotations de um pod do Kubernetes associado e as adicionará como atributos de recurso.
    # O nome exato da annotation será a chave.
    extractAllPodAnnotations: true
  # Configura o coletor para coletar eventos do Kubernetes.
  # Adiciona o k8sobject receiver ao pipeline de logs e coleta eventos do Kubernetes por padrão.
  # Mais informações: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-objects-receiver
  kubernetesEvents:
    enabled: true
  # Configura o Kubernetes Cluster Receiver para coletar métricas em nível de cluster.
  # Adiciona o k8s_cluster receiver ao pipeline de métricas e adiciona as regras necessárias ao ClusterRole.
  # Mais informações: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-cluster-receiver
  clusterMetrics:
    enabled: true

extraEnvs:
  - name: HYPERDX_API_KEY
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: HYPERDX_API_KEY
        optional: true
  - name: YOUR_OTEL_COLLECTOR_ENDPOINT
    valueFrom:
      configMapKeyRef:
        name: otel-config-vars
        key: YOUR_OTEL_COLLECTOR_ENDPOINT

config:
  exporters:
    otlphttp:
      endpoint: "${env:YOUR_OTEL_COLLECTOR_ENDPOINT}"
      compression: gzip
      headers:
        authorization: "${env:HYPERDX_API_KEY}"
  service:
    pipelines:
      logs:
        exporters:
          - otlphttp
      metrics:
        exporters:
          - otlphttp

Implantando o coletor OpenTelemetry

Agora, o coletor OpenTelemetry pode ser implantado no seu cluster do Kubernetes usando o Chart do Helm do OpenTelemetry. Adicione o repositório Helm do OpenTelemetry:

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts # Adicionar repositório Helm do OTel

Instale o chart usando a configuração acima:

copy

helm install my-opentelemetry-collector-deployment open-telemetry/opentelemetry-collector -f k8s_deployment.yaml
helm install my-opentelemetry-collector-daemonset open-telemetry/opentelemetry-collector -f k8s_daemonset.yaml

Agora, as métricas, os logs e os eventos do Kubernetes do seu cluster já devem aparecer no HyperDX.

Encaminhando tags de recurso para pods do Kubernetes (Recomendado)

Para correlacionar logs, métricas e traces da aplicação com metadados do Kubernetes (ex.: nome do pod do Kubernetes, espaço de nomes etc.), é recomendável encaminhar os metadados do Kubernetes para sua aplicação usando a variável de ambiente OTEL_RESOURCE_ATTRIBUTES. Veja um exemplo de implantação que encaminha os metadados do Kubernetes para a aplicação usando variáveis de ambiente:

# my_app_deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: app
  template:
    metadata:
      labels:
        app: app
        # Combinado com o Kubernetes Attribute Processor, isso garante
        # que os logs e métricas do pod do Kubernetes sejam associados a um nome de serviço.
        service.name: <MY_APP_NAME>
    spec:
      containers:
        - name: app-container
          image: my-image
          env:
            # ... outras variáveis de ambiente
            # Coleta metadados do K8s via downward API para encaminhar ao app
            - name: POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: POD_UID
              valueFrom:
                fieldRef:
                  fieldPath: metadata.uid
            - name: POD_NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
            - name: NODE_NAME
              valueFrom:
                fieldRef:
                  fieldPath: spec.nodeName
            - name: DEPLOYMENT_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.labels['deployment']
            # Encaminha os metadados do K8s para o app via OTEL_RESOURCE_ATTRIBUTES
            - name: OTEL_RESOURCE_ATTRIBUTES
              value: k8s.pod.name=$(POD_NAME),k8s.pod.uid=$(POD_UID),k8s.namespace.name=$(POD_NAMESPACE),k8s.node.name=$(NODE_NAME),k8s.deployment.name=$(DEPLOYMENT_NAME)

Recursos

Guias

Criando os arquivos de configuração do Chart do Helm do OTel

Criando um Secret com a API key

Criando a configuração do Conjunto de Daemon

Criando a configuração da implantação

Implantando o coletor OpenTelemetry

Encaminhando tags de recurso para pods do Kubernetes (Recomendado)

​Criando os arquivos de configuração do Chart do Helm do OTel

​Criando um Secret com a API key

​Criando a configuração do Conjunto de Daemon

​Criando a configuração da implantação

​Implantando o coletor OpenTelemetry

​Encaminhando tags de recurso para pods do Kubernetes (Recomendado)

Criando os arquivos de configuração do Chart do Helm do OTel

Criando um Secret com a API key

Criando a configuração do Conjunto de Daemon

Criando a configuração da implantação

Implantando o coletor OpenTelemetry

Encaminhando tags de recurso para pods do Kubernetes (Recomendado)