OpenTelemetry Operator 是 Kubernetes Operator 的一种实现。
该 Operator 管理:
您可以通过 opentelemetry-helm-charts 仓库中的 https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-operator 安装 OpenTelemetry Operator。更多信息可在 https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-operator 获取。
要在现有集群中安装 Operator,请确保已安装 cert-manager 并运行:
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml
当 opentelemetry-operator 部署就绪后,创建 OpenTelemetry Collector(otelcol)实例,例如:
kubectl apply -f -
[!NOTE] 目前,Operator 不会验证配置文件的全部内容:如果配置无效,实例仍可能被创建,但底层 OpenTelemetry Collector 可能会崩溃。
Operator 会出于以下几个目的检查配置文件:
发现已配置的接收器及其端口。如果发现带有端口的接收器,它会创建一对 Kubernetes 服务(一个无头服务),在集群内暴露这些端口。如果端口使用环境变量扩展或无法解析,将返回错误。无头服务包含 service.beta.openshift.io/serving-cert-secret-name 注解,该注解会使 OpenShift 创建包含证书和密钥的 Secret。此 Secret 可作为卷挂载,并在这些接收器的 TLS 配置中使用证书和密钥。
检查是否启用了 Collector 可观测性(由 spec.observability.metrics.enableMetrics 控制)。在这种情况下,会为 Collector 实例创建 Service 和 ServiceMonitor/PodMonitor。因此,如果指标服务地址包含无效端口或对端口使用环境变量扩展,将返回错误。对于环境变量的情况,一种解决方法是将 enableMetrics 设置为 false,并在需要时手动创建具有正确端口的上述对象。
如上所述,OpenTelemetry Collector 格式仍在不断发展。不过,会尽最大努力升级所有受管理的 OpenTelemetryCollector 资源。
在某些情况下,可能需要阻止 Operator 升级特定的 OpenTelemetryCollector 资源。例如,当资源配置了自定义 .Spec.Image 时,最终用户可能希望自己管理配置,而不是由 Operator 进行升级。可通过暴露的 .Spec.UpgradeStrategy 属性按资源单独配置。
通过将资源的 .Spec.UpgradeStrategy 配置为 none,Operator 在升级过程中会跳过该实例。
.Spec.UpgradeStrategy 的默认值和唯一其他可接受值是 automatic。
以下是每种部署模式的示例:
通过将 Pod 注解 sidecar.opentelemetry.io/inject 设置为 "true" 或具体 OpenTelemetryCollector 的名称,可以将带有 OpenTelemetry Collector 的边车注入基于 Pod 的工作负载,如下例所示:
kubectl apply -f -
kubectl create secret docker-registry --docker-server= \
--docker-username=DUMMY_USERNAME --docker-password=DUMMY_DOCKER_PASSWORD \
--docker-email=DUMMY_DOCKER_EMAIL
kubectl patch serviceaccount -p '{"imagePullSecrets": [{"name": " "}]}'
Operator 可以注入和配置 OpenTelemetry auto-instrumentation 库。目前支持 Apache HTTPD、DotNet、Go、Java、Nginx、NodeJS 和 Python。
要使用 auto-instrumentation,请配置带有 SDK 和 instrumentation 配置的 Instrumentation 资源。
kubectl apply -f -
[!NOTE] 对于
DotNetauto-instrumentation,默认情况下,Operator 会设置OTEL_DOTNET_AUTO_TRACES_ENABLED_INSTRUMENTATIONS环境变量,该变量指定要启用的跟踪源 instrumentation 列表。Operator 默认设置的值是镜像中使用的openTelemery-dotnet-instrumentation版本所支持的所有可用 instrumentation,即AspNet,HttpClient,SqlClient。可通过显式配置该环境变量来覆盖此值。
如果未指定其他内容,插桩将在 Pod 规范中的第一个可用容器(来自 .spec.containers,而非 init 容器)上执行。在某些情况下(例如注入 Istio 边车时),需要指定必须在哪些容器上执行此注入。
为此,可以微调要执行注入的 Pod。
为此,我们将使用 instrumentation.opentelemetry.io/container-names 注解,在该注解中指明必须进行注入的一个或多个容器名称(来自 .spec.containers.name 或 .spec.initContainers.name):
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-deployment-with-multiple-containers
spec:
selector:
matchLabels:
app: my-pod-with-multiple-containers
replicas: 1
template:
metadata:
labels:
app: my-pod-with-multiple-containers
annotations:
instrumentation.opentelemetry.io/inject-java: "true"
instrumentation.opentelemetry.io/container-names: "myapp,myapp2"
spec:
containers:
- name: myapp
image: myImage1
- name: myapp2
image: myImage2
- name: myapp3
image: myImage3
可以通过在 container-names 注解中包含 Init 容器的名称来为其注入 instrumentation。当目标为 Init 容器注入 instrumentation 时,operator 会在 Pod 的 Init 容器序列中,自动将 instrumentation Init 容器插入到目标 Init 容器之前。这样可以确保目标 Init 容器运行时,instrumentation 代理文件已可用。
Init 容器支持的 instrumentation:
Init 容器不支持的 instrumentation:
[!NOTE] Kubernetes 保证 Pod 规范中的
initContainers和containers列表中的容器名称是唯一的。这使得 operator 能够明确识别容器名称是指 Init 容器还是常规容器。
同时为 Init 容器和常规容器注入 instrumentation 的示例:
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-deployment-with-init-container
spec:
selector:
matchLabels:
app: my-app
replicas: 1
template:
metadata:
labels:
app: my-app
annotations:
instrumentation.opentelemetry.io/inject-python: "true"
instrumentation.opentelemetry.io/container-names: "my-init-job,myapp"
spec:
initContainers:
- name: my-init-job
image: my-python-init-image
containers:
- name: myapp
image: my-python-app-image
在此示例中,my-init-job(一个 Init 容器)和 myapp(一个常规容器)都将使用 Python 自动 instrumentation 进行注入。
OpenTelemetry Operator 包含一个可选组件:目标分配器(Target Allocator,TA)。创建 OpenTelemetryCollector 自定义资源(CR)并启用 TA 后,Operator 会创建新的 Deployment 和 Service,为该 CR 中的每个 Collector Pod 提供特定的 http_sd_config 指令。它还会重写 CR 中的 Prometheus 接收器配置,使其使用已部署的目标分配器。以下示例展示了如何开始使用目标分配器:
kubectl apply -f - <<EOF
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
name: collector-with-ta
spec:
mode: statefulset
targetAllocator:
enabled: true
config:
receivers:
prometheus:
config:
scrape_configs:
- job_name: 'otel-collector'
scrape_interval: 10s
static_configs:
- targets: [ '0.0.0.0:8888' ]
metric_relabel_configs:
- action: labeldrop
regex: (id|name)
- action: labelmap
regex: label_(.+)
replacement: $1
exporters:
debug: {}
service:
pipelines:
metrics:
receivers: [prometheus]
exporters: [debug]
EOF
上述示例中替换键使用 `# OpenTelemetry Operator for Kubernetes
OpenTelemetry Operator 是 Kubernetes Operator 的一种实现。
该 Operator 管理:
您可以通过 opentelemetry-helm-charts 仓库中的 https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-operator 安装 OpenTelemetry Operator。更多信息可在 https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-operator 获取。
要在现有集群中安装 Operator,请确保已安装 cert-manager 并运行:
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml
当 opentelemetry-operator 部署就绪后,创建 OpenTelemetry Collector(otelcol)实例,例如:
kubectl apply -f -
[!NOTE] 目前,Operator 不会验证配置文件的全部内容:如果配置无效,实例仍可能被创建,但底层 OpenTelemetry Collector 可能会崩溃。
Operator 会出于以下几个目的检查配置文件:
发现已配置的接收器及其端口。如果发现带有端口的接收器,它会创建一对 Kubernetes 服务(一个无头服务),在集群内暴露这些端口。如果端口使用环境变量扩展或无法解析,将返回错误。无头服务包含 service.beta.openshift.io/serving-cert-secret-name 注解,该注解会使 OpenShift 创建包含证书和密钥的 Secret。此 Secret 可作为卷挂载,并在这些接收器的 TLS 配置中使用证书和密钥。
检查是否启用了 Collector 可观测性(由 spec.observability.metrics.enableMetrics 控制)。在这种情况下,会为 Collector 实例创建 Service 和 ServiceMonitor/PodMonitor。因此,如果指标服务地址包含无效端口或对端口使用环境变量扩展,将返回错误。对于环境变量的情况,一种解决方法是将 enableMetrics 设置为 false,并在需要时手动创建具有正确端口的上述对象。
如上所述,OpenTelemetry Collector 格式仍在不断发展。不过,会尽最大努力升级所有受管理的 OpenTelemetryCollector 资源。
在某些情况下,可能需要阻止 Operator 升级特定的 OpenTelemetryCollector 资源。例如,当资源配置了自定义 .Spec.Image 时,最终用户可能希望自己管理配置,而不是由 Operator 进行升级。可通过暴露的 .Spec.UpgradeStrategy 属性按资源单独配置。
通过将资源的 .Spec.UpgradeStrategy 配置为 none,Operator 在升级过程中会跳过该实例。
.Spec.UpgradeStrategy 的默认值和唯一其他可接受值是 automatic。
以下是每种部署模式的示例:
通过将 Pod 注解 sidecar.opentelemetry.io/inject 设置为 "true" 或具体 OpenTelemetryCollector 的名称,可以将带有 OpenTelemetry Collector 的边车注入基于 Pod 的工作负载,如下例所示:
kubectl apply -f -
kubectl create secret docker-registry --docker-server= \
--docker-username=DUMMY_USERNAME --docker-password=DUMMY_DOCKER_PASSWORD \
--docker-email=DUMMY_DOCKER_EMAIL
kubectl patch serviceaccount -p '{"imagePullSecrets": [{"name": " "}]}'
Operator 可以注入和配置 OpenTelemetry auto-instrumentation 库。目前支持 Apache HTTPD、DotNet、Go、Java、Nginx、NodeJS 和 Python。
要使用 auto-instrumentation,请配置带有 SDK 和 instrumentation 配置的 Instrumentation 资源。
kubectl apply -f -
[!NOTE] 对于
DotNetauto-instrumentation,默认情况下,Operator 会设置OTEL_DOTNET_AUTO_TRACES_ENABLED_INSTRUMENTATIONS环境变量,该变量指定要启用的跟踪源 instrumentation 列表。Operator 默认设置的值是镜像中使用的openTelemery-dotnet-instrumentation版本所支持的所有可用 instrumentation,即AspNet,HttpClient,SqlClient。可通过显式配置该环境变量来覆盖此值。
如果未指定其他内容,插桩将在 Pod 规范中的第一个可用容器(来自 .spec.containers,而非 init 容器)上执行。在某些情况下(例如注入 Istio 边车时),需要指定必须在哪些容器上执行此注入。
为此,可以微调要执行注入的 Pod。
为此,我们将使用 instrumentation.opentelemetry.io/container-names 注解,在该注解中指明必须进行注入的一个或多个容器名称(来自 .spec.containers.name 或 .spec.initContainers.name):
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-deployment-with-multiple-containers
spec:
selector:
matchLabels:
app: my-pod-with-multiple-containers
replicas: 1
template:
metadata:
labels:
app: my-pod-with-multiple-containers
annotations:
instrumentation.opentelemetry.io/inject-java: "true"
instrumentation.opentelemetry.io/container-names: "myapp,myapp2"
spec:
containers:
- name: myapp
image: myImage1
- name: myapp2
image: myImage2
- name: myapp3
image: myImage3
可以通过在 container-names 注解中包含 Init 容器的名称来为其注入 instrumentation。当目标为 Init 容器注入 instrumentation 时,operator 会在 Pod 的 Init 容器序列中,自动将 instrumentation Init 容器插入到目标 Init 容器之前。这样可以确保目标 Init 容器运行时,instrumentation 代理文件已可用。
Init 容器支持的 instrumentation:
Init 容器不支持的 instrumentation:
[!NOTE] Kubernetes 保证 Pod 规范中的
initContainers和containers列表中的容器名称是唯一的。这使得 operator 能够明确识别容器名称是指 Init 容器还是常规容器。
同时为 Init 容器和常规容器注入 instrumentation 的示例:
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-deployment-with-init-container
spec:
selector:
matchLabels:
app: my-app
replicas: 1
template:
metadata:
labels:
app: my-app
annotations:
instrumentation.opentelemetry.io/inject-python: "true"
instrumentation.opentelemetry.io/container-names: "my-init-job,myapp"
spec:
initContainers:
- name: my-init-job
image: my-python-init-image
containers:
- name: myapp
image: my-python-app-image
在此示例中,my-init-job(一个 Init 容器)和 myapp(一个常规容器)都将使用 Python 自动 instrumentation 进行注入。
OpenTelemetry Operator 包含一个可选组件:目标分配器(Target Allocator,TA)。创建 OpenTelemetryCollector 自定义资源(CR)并启用 TA 后,Operator 会创建新的 Deployment 和 Service,为该 CR 中的每个 Collector Pod 提供特定的 http_sd_config 指令。它还会重写 CR 中的 Prometheus 接收器配置,使其使用已部署的目标分配器。以下示例展示了如何开始使用目标分配器:
kubectl apply -f - <<EOF
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
name: collector-with-ta
spec:
mode: statefulset
targetAllocator:
enabled: true
config:
receivers:
prometheus:
config:
scrape_configs:
- job_name: 'otel-collector'
scrape_interval: 10s
static_configs:
- targets: [ '0.0.0.0:8888' ]
metric_relabel_configs:
- action: labeldrop
regex: (id|name)
- action: labelmap
regex: label_(.+)
replacement: $1
exporters:
debug: {}
service:
pipelines:
metrics:
receivers: [prometheus]
exporters: [debug]
EOF
上述示例中替换键使用 的原因基于 Prometheus 接收器 https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/prometheusreceiver/README.md 文档中的说明:
注意:由于 Collector 配置支持环境变量替换,Prometheus 配置中的 $ 字符会被解释为环境变量。如果要在 Prometheus 配置中使用 $ 字符,必须使用 $$ 进行转义。
在后台,OpenTelemetry Operator 会在调和后将 Collector 的配置转换为以下内容:
receivers:
prometheus:
target_allocator:
endpoint: http://collector-with-ta-targetallocator:80
interval: 30s
collector_id: $POD_NAME
exporters:
debug:
service:
pipelines:
metrics:
receivers: [prometheus]
exporters: [debug]
OpenTelemetry Operator 还会在调和后将目标分配器的 Prometheus 配置转换为以下内容:
config:
scrape_configs:
- job_name: otel-collector
scrape_interval: 10s
static_configs:
- targets: ["0.0.0.0:8888"]
metric_relabel_configs:
- action: labeldrop
regex: (id|name)
- action: labelmap
regex: label_(.+)
replacement: $1
请注意,在这种情况下,Operator 会将替换键中的 "$$" 替换为单个 "$"。这是因为 Collector 支持环境变量替换,而 TA(目标分配器)不支持。因此,为确保兼容性,TA 配置应仅包含单个 "$" 符号。
有关目标分配器的更多信息,请参见 此处。
目标分配器可以使用 prometheus-operator 生态系统中的自定义资源(如 ServiceMonitor 和 PodMonitor)进行服务发现,其功能类似于 prometheus-operator 本身。这可通过 Collector CR 中的 prometheusCR 部分启用。
以下是一个最小示例:
kubectl apply -f - <<EOF
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
name: collector-with-ta-prometheus-cr
spec:
mode: statefulset
targetAllocator:
enabled: true
serviceAccount: everything-prometheus-operator-needs
prometheusCR:
enabled: true
serviceMonitorSelector: {}
podMonitorSelector: {}
scrapeClasses: []
config:
receivers:
prometheus:
config: {}
exporters:
debug: {}
service:
pipelines:
metrics:
receivers: [prometheus]
exporters: [debug]
EOF
scrapeClasses 属性引用 Prometheus Operator 的 ScrapeClass 功能。有关 scrape class 的更多信息,请参阅 [***]
设置资源属性的优先级如下(最先找到的值生效):
OTEL_RESOURCE_ATTRIBUTES 和 OTEL_SERVICE_NAME 环境变量设置的资源属性resource.opentelemetry.io/ 前缀)设置的资源属性app.kubernetes.io/name)设置的资源属性(前提是 Instrumentation CR 中设置了 defaults.useLabelsForResourceAttributes=true,见上文)k8s.pod.name)Instrumentation CR(在 spec.resource.resourceAttributes 部分)设置的资源属性此优先级针对每个资源属性单独应用,因此可以通过注解设置某些属性,同时通过标签设置其他属性。
探索更多轩辕镜像的使用方法,找到最适合您系统的配置方式
通过 Docker 登录认证访问私有仓库
无需登录使用专属域名
Kubernetes 集群配置 Containerd
K3s 轻量级 Kubernetes 镜像加速
VS Code Dev Containers 配置
Podman 容器引擎配置
HPC 科学计算容器配置
ghcr、Quay、nvcr 等镜像仓库
Harbor Proxy Repository 对接专属域名
Portainer Registries 加速拉取
Nexus3 Docker Proxy 内网缓存
需要其他帮助?请查看我们的 常见问题Docker 镜像访问常见问题解答 或 提交工单
docker search 限制
站内搜不到镜像
离线 save/load
插件要用 plugin install
WSL 拉取慢
安全与 digest
新手拉取配置
镜像合规机制
不支持 push
manifest unknown
no matching manifest(架构)
invalid tar header(解压)
TLS 证书失败
DNS 超时
域名连通性排查
410 Gone 排查
402 与流量用尽
401 认证失败
429 限流
D-Bus 凭证提示
413 与超大单层
来自真实用户的反馈,见证轩辕镜像的优质服务