xDev Asia

Vault Agent の概要、自動認証、テンプレートレンダリング、ファイルシンク、エージェントキャッシュ、Vault プロキシ、API プロキシモード。エージェントとプロキシ、展開パターンを比較します。

HashiCorp Vault の基本から上級まで

Phần 5: Vault Agent, Proxy và Kubernetes Integration

xdev.asia

1. Vault Agent Overview

Vault Agent は、アプリケーションと並行して実行されるデーモンクライアントで、認証、トークンの更新、およびシークレットの取得を自動的に処理します。エージェントは「シークレットゼロ」問題を解決します。アプリケーションは Vault で認証する方法を知る必要がありません。

メイン関数

Auto-auth — トークンを自動的に認証および更新
テンプレートのレンダリング — シークレットを構成ファイルにレンダリング
Caching — Vault サーバーの負荷を軽減するために応答をキャッシュします
API Proxy — アプリケーションは Vault を直接呼び出す代わりにエージェントを呼び出します

アーキテクチャ

┌─────────────────────────────────────────────────┐
│                  Application Host               │
│                                                 │
│  ┌──────────┐                ┌───────────────┐ │
│  │   App    │  Read files    │  Vault Agent  │ │
│  │          │ ◀──────────── │               │ │
│  │          │  (rendered     │  Auto-auth    │ │
│  │          │   templates)   │  Templates    │ │
│  │          │                │  Caching      │ │
│  └──────────┘                └───────┬───────┘ │
│                                      │         │
└──────────────────────────────────────┼─────────┘
                                       │
                              Vault API (HTTPS)
                                       │
                                       ▼
                               ┌──────────────┐
                               │ Vault Server │
                               └──────────────┘

2. Auto-auth

Auto-auth は、Vault で自動的に認証し、トークンを更新します。 Supports all auth methods:

# vault-agent.hcl

vault {
  address = "https://vault.company.com:8200"
  tls_skip_verify = false
}

auto_auth {
  method "kubernetes" {
    mount_path = "auth/kubernetes"
    config = {
      role = "webapp"
    }
  }

  # Lưu token vào file
  sink "file" {
    config = {
      path = "/tmp/vault-token"
      mode = 0640
    }
  }

  # Lưu token vào file khác (wrapped)
  sink "file" {
    wrap_ttl = "5m"
    config = {
      path = "/tmp/vault-token-wrapped"
    }
  }
}

AppRole による自動認証

auto_auth {
  method "approle" {
    mount_path = "auth/approle"
    config = {
      role_id_file_path   = "/etc/vault/role-id"
      secret_id_file_path = "/etc/vault/secret-id"
      remove_secret_id_file_after_reading = true
    }
  }

  sink "file" {
    config = {
      path = "/tmp/vault-token"
    }
  }
}

AWS IAM による自動認証

auto_auth {
  method "aws" {
    mount_path = "auth/aws"
    config = {
      type = "iam"
      role = "webapp"
      header_value = "vault.company.com"
    }
  }

  sink "file" {
    config = {
      path = "/tmp/vault-token"
    }
  }
}

3. Template Rendering

Vault Agent は、Consul テンプレート構文 を使用して、シークレットを構成ファイルにレンダリングします。シークレットが変更されると、テンプレートは自動的に再レンダリングされます。

テンプレート構成

# vault-agent.hcl (tiếp)

template {
  source      = "/etc/vault/templates/app.conf.tpl"
  destination = "/etc/app/app.conf"
  perms       = 0640
  command     = "systemctl reload app"  # Chạy sau khi render
  error_on_missing_key = true
}

template {
  source      = "/etc/vault/templates/db.env.tpl"
  destination = "/etc/app/db.env"
  perms       = 0600
}

# Inline template (không cần file tpl)
template {
  contents    = "{{ with secret \"secret/data/app/config\" }}DB_HOST={{ .Data.data.host }}{{ end }}"
  destination = "/etc/app/db-host"
}

Template Syntax

# /etc/vault/templates/app.conf.tpl

# KV v2 secret
{{ with secret "secret/data/production/db" }}
DB_HOST={{ .Data.data.host }}
DB_PORT={{ .Data.data.port }}
DB_NAME={{ .Data.data.database }}
DB_USER={{ .Data.data.username }}
DB_PASS={{ .Data.data.password }}
{{ end }}

# Dynamic database credentials
{{ with secret "database/creds/app-role" }}
DB_DYNAMIC_USER={{ .Data.username }}
DB_DYNAMIC_PASS={{ .Data.password }}
# Lease: {{ .LeaseID }} ({{ .LeaseDuration }}s)
{{ end }}

# PKI certificate
{{ with secret "pki/issue/app-cert" "common_name=app.company.com" "ttl=24h" }}
{{ .Data.certificate }}
{{ .Data.private_key }}
{{ end }}

# Conditional
{{ with secret "secret/data/production/feature-flags" }}
{{ if .Data.data.enable_cache }}
CACHE_ENABLED=true
CACHE_TTL={{ .Data.data.cache_ttl }}
{{ else }}
CACHE_ENABLED=false
{{ end }}
{{ end }}

Environment Variable Template

# /etc/vault/templates/db.env.tpl
{{ with secret "secret/data/production/db" -}}
export DB_HOST="{{ .Data.data.host }}"
export DB_PORT="{{ .Data.data.port }}"
export DB_USER="{{ .Data.data.username }}"
export DB_PASS="{{ .Data.data.password }}"
{{- end }}

4. Agent Caching

# Caching configuration
cache {
  use_auto_auth_token = true

  persist {
    type = "kubernetes"
    path = "/vault/agent-cache"
  }
}

listener "tcp" {
  address     = "127.0.0.1:8100"
  tls_disable = true
}

Applications は、Vault サーバーを直接呼び出すのではなく、エージェント (localhost:8100) を呼び出します。エージェントは応答をキャッシュし、認証を自動的に処理します。

5. Vault Proxy

Vault Proxy (Vault 1.14+) は、テンプレートのレンダリングを行わない API プロキシとキャッシング に焦点を当てた、Vault Agent の簡素化されたバージョンです。

# vault-proxy.hcl

vault {
  address = "https://vault.company.com:8200"
}

auto_auth {
  method "kubernetes" {
    mount_path = "auth/kubernetes"
    config = {
      role = "webapp"
    }
  }
}

api_proxy {
  use_auto_auth_token = "force"
}

cache {
  use_auto_auth_token = true

  persist {
    type = "kubernetes"
    path = "/vault/proxy-cache"
  }
}

listener "tcp" {
  address     = "127.0.0.1:8100"
  tls_disable = true
}

Static Secret Caching

# Cache static secrets (KV v2)
cache {
  use_auto_auth_token = true

  persist {
    type = "kubernetes"
    path = "/vault/proxy-cache"
  }

  # Static secret caching (mới)
  static_secret_token_wait = "5s"
}

6。エージェントとプロキシ — いつどちらを使用するか?

Tính năng	Vault Agent	Vault Proxy
Auto-auth	✅	✅
Template rendering	✅	❌
API Proxy	✅	✅
Caching	✅	✅
Process Supervisor	✅	❌
フットプリント	大きい	小さい
ユースケース	ファイルをレンダリングする必要がある	プロキシ API のみが必要

Agent: アプリケーションがファイル (構成ファイル、環境ファイル) からシークレットを読み取るとき
Proxy: アプリケーションが Vault API を直接呼び出す場合、キャッシュと自動認証が必要です

7. Deployment Patterns

Systemd Service

# /etc/systemd/system/vault-agent.service
[Unit]
Description=Vault Agent
Requires=network-online.target
After=network-online.target

[Service]
User=vault
Group=vault
ExecStart=/usr/bin/vault agent -config=/etc/vault/agent.hcl
ExecReload=/bin/kill -HUP $MAINPID
KillSignal=SIGTERM
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Docker Sidecar

# docker-compose.yml
services:
  vault-agent:
    image: hashicorp/vault:1.21
    command: vault agent -config=/vault/config/agent.hcl
    volumes:
      - ./agent.hcl:/vault/config/agent.hcl:ro
      - ./templates:/vault/templates:ro
      - shared-secrets:/vault/secrets
    restart: unless-stopped

  webapp:
    image: myapp:latest
    volumes:
      - shared-secrets:/etc/app/secrets:ro
    depends_on:
      - vault-agent

volumes:
  shared-secrets:

Kubernetes Init Container

apiVersion: v1
kind: Pod
metadata:
  name: webapp
spec:
  initContainers:
    - name: vault-agent-init
      image: hashicorp/vault:1.21
      command: ["vault", "agent", "-config=/vault/config/agent.hcl", "-exit-after-auth"]
      volumeMounts:
        - name: vault-config
          mountPath: /vault/config
        - name: vault-secrets
          mountPath: /vault/secrets
  containers:
    - name: webapp
      image: myapp:latest
      volumeMounts:
        - name: vault-secrets
          mountPath: /etc/app/secrets
          readOnly: true
  volumes:
    - name: vault-config
      configMap:
        name: vault-agent-config
    - name: vault-secrets
      emptyDir:
        medium: Memory

8。概要

Vault Agent — full-featured daemon: auto-auth, templates, caching, API proxy
Vault Proxy — lightweight proxy: auto-auth, caching, API proxy (no templates)
Auto-auth — トークンを自動的に認証および更新し、Secret Zero
Templates — シークレットを設定ファイルにレンダリングし、シークレットが変更されると自動的に再レンダリング
Deployment patterns — systemd, Docker sidecar, K8s init/sidecar container

次の記事では、Kubernetes 上の Vault — Helm チャート、Vault Secrets Operator、CSI Provider、Agent Injector について詳しく説明します。

レッスン 19: Vault Agent と Vault Proxy