#迁移可观测性堆栈

属于阶段 6。Mesh v1 自带一条 tracing pipeline——一个 OpenTelemetry v1 collector 和一个 Jaeger 1.x backend——二者都随其在阶段 5中移除。本文档将安装当前堆栈，保留迁移前收集的 traces 以便查询，并恢复应用程序的遥测行为。

OpenTelemetry v1 和 v2 Operators 使用相同的 custom resource definitions，因此只有在移除包含 v1 的 Mesh v1 后，才能安装 v2。

#开始之前

加载迁移变量 source "${BACKUP_DIR}/vars.env"，并收集阶段 0记录的内容：

• ${BACKUP_DIR}/v1-jaeger.txt — Elasticsearch index 前缀以及 Mesh v1 tracing backend 的保留期限。

• ${BACKUP_DIR}/v1-jaeger-es-credentials.yaml — Mesh v1 backend 用于向 Elasticsearch 进行身份验证的 secret。新的 backend 将部署到同一个 Elasticsearch 集群，并需要相同的凭据：

  ES_SECRET=$(kubectl create -f "${BACKUP_DIR}/v1-jaeger-es-credentials.yaml" --dry-run=client -o json)
  export ES_ENDPOINT=$(sed -n 's/.*url=\([^ ]*\).*/\1/p' "${BACKUP_DIR}/v1-jaeger.txt")
  export ES_USER=$(jq -r '.data.ES_USERNAME' <<<"${ES_SECRET}" | base64 -d)
  export ES_PASS=$(jq -r '.data.ES_PASSWORD' <<<"${ES_SECRET}" | base64 -d)
  echo "${ES_ENDPOINT} user=${ES_USER}"

  这些是以下安装步骤要求提供的 ES_ENDPOINT、ES_USER 和 ES_PASS。Mesh v1 secret 中的键名为 ES_USERNAME 和 ES_PASSWORD。

• ${BACKUP_DIR}/instrumentations.yaml — Mesh v1 的 Instrumentation resource，其中包含 exporter endpoint、sampler 以及应用程序上报的 service name pattern。

• ${BACKUP_DIR}/v1-instrumented-pods.txt — 使用 Java auto-instrumentation 的 workloads，每行一个：namespace、workload、application container、microservice name 和 reported service name。

• ${BACKUP_DIR}/v1-injected-env.txt — Mesh v1 webhooks 添加到 application containers 的变量。

准备好一条迁移前的 trace——其 trace ID、service name 和 span 数量。它是末尾验证所依据的参考。

#接管现有索引的保留期限

Mesh v1 tracing backend 运行一个 cron job，在索引超过配置的保留期限后将其删除。该 job 由 Mesh v1 tracing resource 所有，并随该 resource 一同删除，因此这些索引目前不会过期。

按照 接管旧版索引的保留期限 的说明，为现有索引系列应用仅删除索引生命周期策略，并使用 ${BACKUP_DIR}/v1-jaeger.txt 中的值：

• LEGACY_ES_INDEX_PREFIX — Mesh v1 tracing backend 的 es.index-prefix，默认为 asm-mesh-<meshID>。
• 删除索引的期限 — 其 index cleaner 的 numberOfDays，默认为 7。

#安装新的 tracing stack

按照使用 Service Mesh 配置分布式 tracing 平台 中的前提条件，在 jaeger-system namespace 中安装 Alauda Container Platform Distributed Tracing（此前称为 Alauda Build of Jaeger v2）集群插件、Alauda Container Platform Application Observability（此前称为 Alauda Build of OpenTelemetry v2）Operator、Jaeger v2 实例以及 v2 collector。

对于迁移后的 mesh，以下三个选择十分重要：

• 使用与 Mesh v1 backend 相同的 Elasticsearch 集群，否则新的 backend 无法提供现有 traces。
• 按 mesh 而非按集群选择 index prefix。 跨多个集群的 mesh 会写入同一个索引系列，以便从同一位置组装跨集群的 trace。作用于 Elasticsearch 的步骤——生命周期策略和索引初始化——随后属于 mesh，而不是集群：使用 mesh 的 prefix 执行一次，并在每个其他集群上跳过这些步骤。之后，任意集群的 Jaeger 实例都可以提供整个 mesh 的 traces。保留默认 prefix，且绝不要复用 Mesh v1 的 prefix：接管 Mesh v1 索引保留期限以及之后弃用这些索引的步骤会按 <prefix>-jaeger-* 选择索引，因此共享 prefix 也会将这些步骤应用到新的索引系列。
• 为每个集群提供其专属的 collector。 所有集群的 collectors 共享一个 service name，而重新指向 mesh 的步骤会将该 service 声明为集群本地服务，因此每个 proxy 都会向其所属集群的 collector 导出数据，参见将 trace 上报限制在各集群内部。

完成前提条件后停止。mesh 侧的配置已在迁移过程中存在，下一步会更新该配置。

#将现有索引附加到新的读取别名

将 Mesh v1 索引附加到新索引系列的读取别名后，迁移前的 traces 便可在新的 Jaeger UI 中查询。不会复制或重新建立索引，旧索引仍保持只读。

按照 Attach the legacy indices to the new read aliases 操作，将 LEGACY_ES_INDEX_PREFIX 设置为 Mesh v1 的 prefix，并将 JAEGER_ES_INDEX_PREFIX 设置为新 instance 的 prefix。在多 cluster mesh 中，只需对整个 mesh 执行一次。

#将 mesh 重新指向新的 collector

mesh 会将 spans 发送到 Istio resource 中定义的 provider。将 Mesh v1 provider 替换为指向新 collector 的 provider，并更新 mesh-wide Telemetry resource 以使用该 provider。

SETTINGS=$(kubectl get istio default -o json \
  | jq -c '[(.spec.values.meshConfig.serviceSettings // [])[]
            | select((.hosts // []) | index("otel-collector.jaeger-system.svc.cluster.local") | not)]
           + [{settings: {clusterLocal: true}, hosts: ["otel-collector.jaeger-system.svc.cluster.local"]}]')
kubectl patch istio default --type=merge -p "$(cat <<EOF
{"spec":{"values":{"meshConfig":{
  "extensionProviders":[
    {"name":"otel","opentelemetry":{"port":4317,"service":"otel-collector.jaeger-system.svc.cluster.local"}}
  ],
  "serviceSettings":${SETTINGS}}}}}
EOF
)"
kubectl wait --for condition=Ready istio/default --timeout=5m

kubectl -n istio-system patch telemetry asm-default --type=merge \
  -p "{\"spec\":{\"tracing\":[{\"providers\":[{\"name\":\"otel\"}],\"randomSamplingPercentage\":${V1_TRACE_SAMPLING}}]}}"

如果 Istio resource 使用 discoverySelectors 限制 discovery，请为 jaeger-system namespace 添加标签，以便控制平面能够解析 collector service。

如果 Sidecar resource 限制 egress.hosts，请向其中添加 jaeger-system/*，否则其 proxies 会在没有错误的情况下丢弃每个 span，请参阅使用 Sidecar 导入。

Mesh spans 现在已到达新的 backend。继续之前，请检查 Jaeger UI。

#迁移 Java auto-instrumentation

由 OpenTelemetry Operator 进行 instrument 的应用需要恢复三项内容：注入 annotations、一个 Instrumentation resource，以及它们在迁移前报告的环境。

在 Mesh v1 中，平台 webhook 向每个 pod 添加注入 annotations 和身份变量，Instrumentation 中的 cpaas-system resource 引用了这些内容。现在两者都不存在，因此必须将 annotations 和变量值写入能够自行持久保留的位置。

export MESH_NAMESPACE=<namespace> WORKLOAD=<workload>
read -r APP_CONTAINER MS_NAME SERVICE_NAME <<<"$(awk -v ns="${MESH_NAMESPACE}" -v w="${WORKLOAD}" \
  '$1 == ns && $2 == w {print $3, $4, $5}' "${BACKUP_DIR}/v1-instrumented-pods.txt")"
export APP_CONTAINER MS_NAME SERVICE_NAME
echo "container=${APP_CONTAINER} msname=${MS_NAME} service=${SERVICE_NAME}"

export JAVA_AGENT_IMAGE=<java-auto-instrumentation-image>

cat <<EOF | kubectl apply -f -
apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: java
  namespace: ${MESH_NAMESPACE}
spec:
  exporter:
    endpoint: http://otel-collector.jaeger-system.svc.cluster.local:4318
  propagators:
    - tracecontext
    - baggage
  sampler:
    type: parentbased_traceidratio
    argument: "1.0"
  env:
    - name: OTEL_TRACES_EXPORTER
      value: otlp
    - name: OTEL_METRICS_EXPORTER
      value: otlp
    - name: OTEL_LOGS_EXPORTER
      value: none
  java:
    image: ${JAVA_AGENT_IMAGE}
EOF

kubectl -n "${MESH_NAMESPACE}" patch deploy "${WORKLOAD}" -p "$(cat <<EOF
{"spec":{"template":{"spec":{"containers":[
  {"name":"${APP_CONTAINER}","env":[{"name":"OTEL_SERVICE_NAME","value":"${SERVICE_NAME}"}]}
]}}}}
EOF
)"

kubectl -n "${MESH_NAMESPACE}" patch deploy "${WORKLOAD}" -p "$(cat <<EOF
{"spec":{"template":{"spec":{"containers":[
  {"name":"${APP_CONTAINER}","env":[
    {"name":"ASM_MS_NAME","value":"${MS_NAME}"},
    {"name":"ASM_POD_NAMESPACE","valueFrom":{"fieldRef":{"fieldPath":"metadata.namespace"}}}
  ]}
]}}}}
EOF
)"

kubectl -n "${MESH_NAMESPACE}" get deploy "${WORKLOAD}" -o json \
  | jq -r --arg c "${APP_CONTAINER}" '[.spec.template.spec.containers[] | select(.name == $c) | (.env // [])[]
      | select(.name | test("^(OTEL_|ASM_)"))]
    | group_by(.name)[]
    | "\(.[0].name) \(length)x \([.[] | .value // .valueFrom.fieldRef.fieldPath // ""] | join(" | "))"'

ASM_MS_NAME 1x frontend-ms
ASM_POD_NAMESPACE 1x metadata.namespace
OTEL_SERVICE_NAME 1x frontend-ms.app-all

kubectl -n "${MESH_NAMESPACE}" patch deploy "${WORKLOAD}" --type=merge -p "$(cat <<EOF
{"spec":{"template":{"metadata":{"annotations":{
  "instrumentation.opentelemetry.io/inject-java": "java",
  "instrumentation.opentelemetry.io/java-container-names": "${APP_CONTAINER}"
}}}}}
EOF
)"
kubectl -n "${MESH_NAMESPACE}" rollout status "deploy/${WORKLOAD}" --timeout=300s

kubectl annotate ns "${MESH_NAMESPACE}" instrumentation.opentelemetry.io/inject-java=java --overwrite
kubectl -n "${MESH_NAMESPACE}" rollout restart deploy

#将 Kiali 连接到 Jaeger v2

按照将分布式 tracing 平台与 Alauda Build of Kiali 集成中的说明，将 Kiali 资源的 tracing 配置设置为新的 Jaeger query service。阶段 1安装 Kiali 时未配置该服务。

在多集群 mesh 中，将 Kiali 指向其所在 cluster 的 Jaeger 实例，并将 tracing 部分的 query scope 设置为整个 mesh，即 istio.mesh_id: <mesh-id>，与 monitoring query scope 保持一致。整个 mesh 使用同一组索引，因此该实例可以为每个 cluster 提供响应。

#验证

kubectl -n jaeger-system get pod
kubectl -n "${MESH_NAMESPACE}" get pod -o json | jq -r '.items[]
  | select(any(.spec.initContainers[]?; .name == "opentelemetry-auto-instrumentation-java"))
  | .metadata.name as $pod
  | .spec.containers[]
  | select(any(.env[]?; .name == "JAVA_TOOL_OPTIONS"))
  | "\($pod) \(.name) \([.env[]? | select(.name=="OTEL_SERVICE_NAME") | .value] | join(","))"'

第二条命令会针对每个注入了 agent 的 pod，列出 agent 所进入的 container 以及该 container 报告的名称。

• 迁移后生成的 traces 会出现在 Jaeger v2 UI 中，包括 mesh proxy 和经过 instrument 的应用的 traces。
• 迁移前保留的 trace 仍可通过其 trace ID 找到，并且 span 数量和 service name 都保持不变。该 trace 是存储下来的，而不是重新生成的，因此不会发生变化。同一个请求的新 trace 可能比迁移前包含更少的 spans — 2.x Java agent instrument 的库集合不同于 Mesh v1 随附的 1.x agent。请将旧 trace 与旧 trace 比较，而不要将其与新 trace 比较。
• 经过 instrument 的应用的 service names 与迁移前报告的名称一致，并且 agent 所进入的 container 是应用 container，绝不会是 istio-proxy。
• Kiali 会在 service 详情页上显示 traces。
• 之前从 Java agent 收集的应用指标现已恢复可用，但现在是通过 collector 提供的。

返回完成迁移，完成迁移的最终验收。