infra-deploy-guide

name	infra-deploy-guide
description	Deploy Kubernetes infrastructure with kubectl, Helm, Argo CD CLI, and Git. Use for cluster initialization, GitOps setup, ArgoCD deployment, VictoriaMetrics, VictoriaLogs, kube-prometheus-stack, monitoring or logging stack installation. 适用于集群初始化、基础设施部署、监控系统搭建、日志系统搭建和 ArgoCD GitOps 配置。

Infrastructure Deployment Guide

Cluster Initialization Deployment Flow

Prerequisite Check

1. Run kubectl config current-context and state the exact target context.
2. Confirm cluster reachability with kubectl cluster-info.
3. Confirm Helm repositories and GitOps repository access.
4. Run read-only diff/template commands before requesting apply approval.

Deployment Order (Dependencies)

1. ArgoCD          → Base, other components deployed via ArgoCD GitOps
2. VictoriaMetrics → Metrics storage backend
3. kube-prometheus-stack → Metrics collection (remote_write to VM)
4. VictoriaLogs    → Log storage backend

Step 1: Deploy ArgoCD

# Create namespace
kubectl create namespace argocd

# Deploy with Helm
helm install argocd argo/argo-cd \
  --namespace argocd \
  -f charts/argocd/values.yaml

Key config items (charts/argocd/values.yaml):

• server.ingress.enabled: Enable Ingress
• server.ingress.hosts: Access domain
• configs.repositories: Git repository config

Verification:

• ArgoCD Server Pod Running
• ArgoCD Repo Server Pod Running
• UI/CLI login works

Step 2: Deploy VictoriaMetrics

helm install victoria-metrics vm/victoria-metrics-k8s-stack \
  --namespace monitoring --create-namespace \
  -f charts/victoria-metrics-stack/values.yaml

Key config items:

• vmsingle.spec.retentionPeriod: Data retention (default 30d)
• vmsingle.spec.storage.storageClassName: Storage class
• vmsingle.spec.storage.resources.requests.storage: Storage size

Verification:

• VMSingle/VMCluster Pod Running
• VMAlert Pod Running (if enabled)
• API can query metrics

Step 3: Deploy kube-prometheus-stack

helm install kps prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  -f charts/kube-prometheus-stack/values.yaml

Key config:

• prometheus.prometheusSpec.remoteWrite: Configure remote_write to VictoriaMetrics
• Disable Grafana (use standalone or VM built-in)
• Disable AlertManager (use VMAlert)

Verification:

• Prometheus Pod Running
• node-exporter DaemonSet Running
• kube-state-metrics Running
• remote_write target reachable

Step 4: Deploy VictoriaLogs

helm install victoria-logs vm/victoria-logs-single \
  --namespace logging --create-namespace \
  -f charts/victoria-logs/values.yaml

Key config:

• server.retentionPeriod: Log retention
• server.persistentVolume.size: Storage size
• Log collector (fluent-bit/vector) config

Verification:

• VictoriaLogs Pod Running
• Log collector DaemonSet Running
• LogsQL can query logs

Post-Deployment Verification Checklist

Component	Check Item	Method
ArgoCD	Server running	kubectl get pods -n argocd
ArgoCD	UI accessible	Browser to Ingress URL
VictoriaMetrics	VMSingle running	kubectl get pods -n monitoring -l app=vmsingle
VictoriaMetrics	Metrics writing	PromQL: up
KPS	Prometheus running	kubectl get pods -n monitoring -l app.kubernetes.io/name=prometheus
KPS	remote_write OK	Prometheus targets page
VictoriaLogs	Server running	kubectl get pods -n logging
VictoriaLogs	Log writing	LogsQL: *

Safety

• Use helm template, helm diff upgrade, kubectl diff, and argocd app diff before mutations.
• Require explicit approval for install, upgrade, sync, rollback, delete, scale, or Git push.
• Scope every kubectl and Helm command to an explicit context and namespace.
• Never put repository tokens, kubeconfig contents, or generated passwords in output.

Troubleshooting

ArgoCD Deployment Failure

• Check PVC binding (requires StorageClass)
• Check Ingress Controller exists
• Check Git repo connectivity (SSH key / token)

VictoriaMetrics Deployment Failure

• Check storage quota is sufficient
• Check CRD installed (vm-operator)

remote_write Not Working

• Check VictoriaMetrics endpoint address
• Check network policies allow cross-namespace traffic
• Check auth configuration