はじめに

本記事は3部構成のPart 1です。

Part 1（本記事）: 環境構築とHelmチャート作成
Part 2: ArgoCD設定とGitOps実装
Part 3: 実行・動作確認・トラブルシューティング

概要

本記事では、M1 Mac（メモリ16GB）のノートPCで快適に動作するKubernetes + OpenTelemetry検証環境を構築します。コマンド一発で環境構築が可能で、Helmチャートを使用し、GitLab + ArgoCDによるGitOps自動デプロイに対応しています。すべての設定はコード管理され、k6による負荷テストで疎通確認まで行います。

本記事では、以下の要件を満たす検証環境を構築します。

✅ コマンド一発で構築可能
✅ Helmチャートを使用
✅ GitLab + ArgoCDによるGitOps自動デプロイ
✅ すべての設定がコード管理可能
✅ k6による負荷テストで疎通確認

環境要件: M1 Mac、メモリ16GB、Docker Desktop（Kubernetes有効化）

前提条件

環境: M1 Mac（メモリ16GB）
OS: macOS 13以降
必要なツール: Homebrew、Docker Desktop、Git

構築する構成

┌─────────────────────────────────────────────────────┐
│  Local Development (M1 Mac 16GB)                    │
├─────────────────────────────────────────────────────┤
│  Docker Desktop (Kubernetes)                        │
│  ├─ ArgoCD (GitOps)                                 │
│  ├─ OpenTelemetry Collector                         │
│  ├─ Prometheus + Grafana                            │
│  ├─ Jaeger                                          │
│  └─ サンプルアプリケーション                            │
├─────────────────────────────────────────────────────┤
│  GitLab Repository                                  │
│  └─ Helm Charts + ArgoCD Manifests                  │
└─────────────────────────────────────────────────────┘

全体の流れ（重要）

本記事の手順は以下の順序で実行してください：

Part 1（本記事）: 必要なツールのインストールとHelmチャートの準備
Part 2: ArgoCDのインストールとGitOps実装
Part 3: セットアップ実行と動作確認

ステップ1: 必要なツールのインストール

1.1 基本ツールのインストール

# Homebrewがインストールされていることを確認
which brew

# 必要なツールを一括インストール
brew install kubectl helm k6 argocd docker docker-compose git

# Docker Desktopをインストール（GUIアプリ）
brew install --cask docker

1.2 Docker Desktopの設定

Docker Desktopを起動
Settings → Kubernetes → "Enable Kubernetes" を有効化
Resources → Advanced → メモリを8GB程度に設定（16GB環境に最適化）

# Kubernetesクラスターの確認
kubectl cluster-info
kubectl get nodes

1.3 名前空間の作成

# 必要な名前空間を作成
kubectl create namespace argocd
kubectl create namespace observability
kubectl create namespace demo-app

# 確認
kubectl get namespaces

ステップ2: GitLabリポジトリの準備

2.1 ローカルリポジトリの初期化

# プロジェクトディレクトリを作成
mkdir -p ~/k8s-otel-gitops
cd ~/k8s-otel-gitops

# Gitリポジトリを初期化
git init
git branch -M main

2.2 ディレクトリ構造の作成

# ディレクトリ構造を作成
mkdir -p {helm-charts/{otel-collector,prometheus,grafana,jaeger},argocd/apps,demo-app,scripts}

# 構造を確認
tree -L 2

2.3 GitLabリポジトリの作成（Web UIまたはCLI）

方法A: GitLab Web UIから作成

GitLabにログイン
"New project" → "Create blank project"
Project name: k8s-otel-gitops
Visibility: Private（検証環境のため）
"Create project"

方法B: GitLab CLIを使用（glabが必要な場合）

# GitLab CLIのインストール（必要に応じて）
brew install glab

# GitLab CLIでリポジトリ作成
glab repo create k8s-otel-gitops --private

2.4 リモートリポジトリの接続

# リモートリポジトリを追加（URLは実際のGitLabリポジトリに置き換え）
git remote add origin https://gitlab.com/YOUR_USERNAME/k8s-otel-gitops.git

# またはSSHを使用する場合
# git remote add origin git@gitlab.com:YOUR_USERNAME/k8s-otel-gitops.git

# 確認
git remote -v

ステップ3: Helmチャートの作成

3.1 OpenTelemetry Collector Helmチャート

# Helmチャートのディレクトリに移動
cd helm-charts/otel-collector

# Helmチャートを作成
helm create otel-collector
cd otel-collector

values.yamlを編集:

# helm-charts/otel-collector/otel-collector/values.yaml
replicaCount: 1

image:
  repository: otel/opentelemetry-collector
  tag: "0.89.0"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  ports:
    otlp:
      port: 4317
      targetPort: 4317
      protocol: TCP
    otlp-http:
      port: 4318
      targetPort: 4318
      protocol: TCP

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 100m
    memory: 128Mi

serviceAccount:
  create: true
  automount: true

ingress:
  enabled: false

httpRoute:
  enabled: false

autoscaling:
  enabled: false

config:
  receivers:
    otlp:
      protocols:
        grpc:
          endpoint: 0.0.0.0:4317
        http:
          endpoint: 0.0.0.0:4318

  processors:
    batch:
      timeout: 10s
      send_batch_size: 1024

  exporters:
    logging:
      loglevel: info
    zipkin:
      endpoint: http://jaeger-collector.observability.svc.cluster.local:14268/api/v2/spans
    prometheus:
      endpoint: "0.0.0.0:8889"
      const_labels:
        label1: value1

  service:
    pipelines:
      traces:
        receivers: [otlp]
        processors: [batch]
        exporters: [logging, zipkin]
      metrics:
        receivers: [otlp]
        processors: [batch]
        exporters: [logging, prometheus]

Chart.yamlを確認:

# helm-charts/otel-collector/otel-collector/Chart.yaml
apiVersion: v2
name: otel-collector
description: OpenTelemetry Collector for local Kubernetes
type: application
version: 0.1.0
appVersion: "0.89.0"

テンプレートファイルの修正が必要です:

Helmチャートをhelm createで作成した場合、デフォルトのテンプレートが生成されますが、OpenTelemetry Collector用に修正が必要です。

1. ConfigMapテンプレートの作成

# ConfigMapテンプレートを作成
cat > templates/configmap.yaml <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "otel-collector.fullname" . }}
  labels:
    {{- include "otel-collector.labels" . | nindent 4 }}
data:
  otel-collector-config.yaml: |
    {{- toYaml .Values.config | nindent 4 }}
EOF

2. Serviceテンプレートの修正

templates/service.yamlを以下のように修正:

# helm-charts/otel-collector/otel-collector/templates/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: {{ include "otel-collector.fullname" . }}
  labels:
    {{- include "otel-collector.labels" . | nindent 4 }}
spec:
  type: {{ .Values.service.type }}
  ports:
    {{- range $name, $port := .Values.service.ports }}
    - name: {{ $name }}
      port: {{ $port.port }}
      targetPort: {{ $port.targetPort }}
      protocol: {{ $port.protocol }}
    {{- end }}
  selector:
    {{- include "otel-collector.selectorLabels" . | nindent 4 }}

3. Deploymentテンプレートの修正

templates/deployment.yamlのコンテナ部分を以下のように修正:

# helm-charts/otel-collector/otel-collector/templates/deployment.yaml の一部
containers:
  - name: {{ .Chart.Name }}
    {{- with .Values.securityContext }}
    securityContext:
      {{- toYaml . | nindent 12 }}
    {{- end }}
    image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
    imagePullPolicy: {{ .Values.image.pullPolicy }}
    args:
      - "--config=/etc/otel-collector-config/otel-collector-config.yaml"
    ports:
      {{- range $name, $port := .Values.service.ports }}
      - name: {{ $name }}
        containerPort: {{ $port.targetPort }}
        protocol: {{ $port.protocol }}
      {{- end }}
    {{- with .Values.livenessProbe }}
    livenessProbe:
      {{- toYaml . | nindent 12 }}
    {{- end }}
    {{- with .Values.readinessProbe }}
    readinessProbe:
      {{- toYaml . | nindent 12 }}
    {{- end }}
    {{- with .Values.resources }}
    resources:
      {{- toYaml . | nindent 12 }}
    {{- end }}
    volumeMounts:
      - name: config
        mountPath: /etc/otel-collector-config
      {{- with .Values.volumeMounts }}
      {{- toYaml . | nindent 12 }}
      {{- end }}
volumes:
  - name: config
    configMap:
      name: {{ include "otel-collector.fullname" . }}
  {{- with .Values.volumes }}
  {{- toYaml . | nindent 8 }}
  {{- end }}

修正のポイント:

Serviceテンプレート: values.yamlのservice.ports構造に合わせて、rangeを使用して複数のポートを処理
Deploymentテンプレート:
- 起動コマンドに--configオプションを追加してConfigMapから設定ファイルを読み込む
- ポート設定をServiceと同様にrangeで処理
- ConfigMapをボリュームとしてマウント
ConfigMapテンプレート: OpenTelemetry Collectorの設定をConfigMapとして作成

3.2 Prometheus Helmチャート（公式チャートを使用）

# Prometheus用のディレクトリに移動
cd ../../prometheus

# Prometheusの公式Helmリポジトリを追加
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

# values.yamlを作成（M1 Mac 16GB環境に最適化）
cat > values.yaml <<EOF
prometheus:
  prometheusSpec:
    resources:
      limits:
        cpu: 1000m
        memory: 1Gi
      requests:
        cpu: 200m
        memory: 512Mi
    retention: 7d
    retentionSize: 5GB
    storageSpec:
      volumeClaimTemplate:
        spec:
          accessModes: ["ReadWriteOnce"]
          storageClassName: ""  # 空文字でデフォルトのStorageClassを使用
          resources:
            requests:
              storage: 5Gi

server:
  resources:
    limits:
      cpu: 500m
      memory: 512Mi
    requests:
      cpu: 100m
      memory: 128Mi
EOF

3.3 Grafana Helmチャート（公式チャートを使用）

cd ../grafana

# Grafanaの公式Helmリポジトリを追加
helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

# values.yamlを作成
cat > values.yaml <<EOF
adminUser: admin
adminPassword: admin

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 100m
    memory: 128Mi

persistence:
  enabled: true
  storageClassName: ""  # 空文字でデフォルトのStorageClassを使用（Docker Desktop対応）
  accessModes:
    - ReadWriteOnce
  size: 2Gi

service:
  type: NodePort
  nodePort: 30000
EOF

StorageClassについて:

Docker Desktopの場合、デフォルトのStorageClassが自動的に使用されます
storageClassName: ""（空文字）を指定することで、デフォルトのStorageClassが使用されます
もしpersistenceが必要ない場合（データ永続化が不要な検証環境）、persistence.enabled: falseに設定することも可能です

3.4 Jaeger Helmチャート（公式チャートを使用）

cd ../jaeger

# Jaegerの公式Helmリポジトリを追加
helm repo add jaegertracing https://jaegertracing.github.io/helm-charts
helm repo update

# values.yamlを作成
cat > values.yaml <<EOF
agent:
  enabled: false

collector:
  resources:
    limits:
      cpu: 500m
      memory: 512Mi
    requests:
      cpu: 100m
      memory: 128Mi

query:
  resources:
    limits:
      cpu: 500m
      memory: 512Mi
    requests:
      cpu: 100m
      memory: 128Mi
  service:
    type: NodePort
    nodePort: 30686

# M1 Mac 16GB環境向け: メモリストレージを使用（Cassandraを無効化）
storage:
  type: memory
  # Cassandraを完全に無効化（メモリストレージ使用時は不要）
  cassandra:
    enabled: false
EOF

Jaeger Storage設定について:

storage.type: memory: インメモリストレージを使用（データはPod再起動で失われます）
cassandra.enabled: false: Cassandraを無効化してリソース使用量を削減
検証環境では、メモリストレージで十分です
本番環境では、CassandraやElasticsearchなどの永続ストレージが必要です

まとめ（Part 1）

Part 1では、以下の作業を完了しました：

✅ 必要なツールのインストール: kubectl、helm、k6、argocdなど
✅ GitLabリポジトリの準備: ローカルリポジトリの初期化とリモート接続
✅ Helmチャートの作成: OpenTelemetry Collector、Prometheus、Grafana、Jaeger

次のステップ: Part 2では、ArgoCDのインストールと設定、セットアップスクリプトの作成、GitOps実装を行います。

参考資料