Alauda Service Mesh v2 Docs
  • 简体中文

    • Linux Kernel 兼容性说明

    对于运行 4.11 之前 Linux kernel 版本的节点（例如 CentOS 7），在安装 gateway 之前需要进行额外配置。根据是否需要监听 1024 以下的端口，分为以下两种场景：

    • 场景 1: 仅适用于 4.11 之前的 kernel 版本 — gateway 监听 1024 或更高的端口。需要设置 sysctls: []，以移除默认的 net.ipv4.ip_unprivileged_port_start sysctl；该 sysctl 在 4.11 之前的 kernel 中不可用。
    • 场景 2: 4.11 之前的 kernel 版本 + 特权端口 — gateway 需要监听 1024 以下的端口。除了场景 1 中对 sysctls: [] 的更改之外，还必须添加 NET_BIND_SERVICE capability，以允许绑定特权端口。
    INFO

    如果您的 kernel 版本为 4.11 或更高版本，请跳过本节。

    目录

    Istio Gateway前提条件操作步骤场景 1: 仅适用于 4.11 之前的 kernel 版本（端口 ≥ 1024）场景 2: 4.11 之前的 kernel 版本 + 特权端口（端口 < 1024）应用注入模板Kubernetes Gateway API前提条件操作步骤场景 1: 仅适用于 4.11 之前的 kernel 版本（端口 ≥ 1024）场景 2: 4.11 之前的 kernel 版本 + 特权端口（端口 < 1024）应用 ConfigMap

    Istio Gateway

    前提条件

    • 在本地安装 jq，以便在以下步骤中处理 JSON。

    操作步骤

    场景 1: 仅适用于 4.11 之前的 kernel 版本（端口 ≥ 1024）

    1. 创建名为 gateway-injection-template.txt 的 YAML 文件，其中包含 gateway 的默认注入模板。

      点击展开
      gateway-injection-template.txt
      {{- $containers := list }}
{{- range $index, $container := .Spec.Containers }}{{ if not (eq $container.Name "istio-proxy") }}{{ $containers = append $containers $container.Name }}{{end}}{{- end}}
metadata:
  labels:
    service.istio.io/canonical-name: {{ index .ObjectMeta.Labels `service.istio.io/canonical-name` | default (index .ObjectMeta.Labels `app.kubernetes.io/name`) | default (index .ObjectMeta.Labels `app`) | default .DeploymentMeta.Name  | quote }}
    service.istio.io/canonical-revision: {{ index .ObjectMeta.Labels `service.istio.io/canonical-revision` | default (index .ObjectMeta.Labels `app.kubernetes.io/version`) | default (index .ObjectMeta.Labels `version`) | default "latest"  | quote }}
  annotations:
    istio.io/rev: {{ .Revision | default "default" | quote }}
    {{- if ge (len $containers) 1 }}
    {{- if not (isset .ObjectMeta.Annotations `kubectl.kubernetes.io/default-logs-container`) }}
    kubectl.kubernetes.io/default-logs-container: "{{ index $containers 0 }}"
    {{- end }}
    {{- if not (isset .ObjectMeta.Annotations `kubectl.kubernetes.io/default-container`) }}
    kubectl.kubernetes.io/default-container: "{{ index $containers 0 }}"
    {{- end }}
    {{- end }}
spec:
  securityContext:
  {{- if .Values.gateways.securityContext }}
    {{- toYaml .Values.gateways.securityContext | nindent 4 }}
  {{- else }}
    sysctls: []  
  {{- end }}
  containers:
  - name: istio-proxy
  {{- if contains "/" (annotation .ObjectMeta `sidecar.istio.io/proxyImage` .Values.global.proxy.image) }}
    image: "{{ annotation .ObjectMeta `sidecar.istio.io/proxyImage` .Values.global.proxy.image }}"
  {{- else }}
    image: "{{ .ProxyImage }}"
  {{- end }}
    ports:
    - containerPort: 15090
      protocol: TCP
      name: http-envoy-prom
    args:
    - proxy
    - router
    - --domain
    - $(POD_NAMESPACE).svc.{{ .Values.global.proxy.clusterDomain }}
    - --proxyLogLevel={{ annotation .ObjectMeta `sidecar.istio.io/logLevel` .Values.global.proxy.logLevel }}
    - --proxyComponentLogLevel={{ annotation .ObjectMeta `sidecar.istio.io/componentLogLevel` .Values.global.proxy.componentLogLevel }}
    - --log_output_level={{ annotation .ObjectMeta `sidecar.istio.io/agentLogLevel` .Values.global.logging.level }}
  {{- if .Values.global.sts.servicePort }}
    - --stsPort={{ .Values.global.sts.servicePort }}
  {{- end }}
  {{- if .Values.global.logAsJson }}
    - --log_as_json
  {{- end }}
  {{- if .Values.global.proxy.lifecycle }}
    lifecycle:
      {{ toYaml .Values.global.proxy.lifecycle | indent 6 }}
  {{- end }}
    securityContext:
      runAsUser: {{ .ProxyUID | default "1337" }}
      runAsGroup: {{ .ProxyGID | default "1337" }}
    env:
    - name: PILOT_CERT_PROVIDER
      value: {{ .Values.global.pilotCertProvider }}
    - name: CA_ADDR
    {{- if .Values.global.caAddress }}
      value: {{ .Values.global.caAddress }}
    {{- else }}
      value: istiod{{- if not (eq .Values.revision "") }}-{{ .Values.revision }}{{- end }}.{{ .Values.global.istioNamespace }}.svc:15012
    {{- end }}
    - name: POD_NAME
      valueFrom:
        fieldRef:
          fieldPath: metadata.name
    - name: POD_NAMESPACE
      valueFrom:
        fieldRef:
          fieldPath: metadata.namespace
    - name: INSTANCE_IP
      valueFrom:
        fieldRef:
          fieldPath: status.podIP
    - name: SERVICE_ACCOUNT
      valueFrom:
        fieldRef:
          fieldPath: spec.serviceAccountName
    - name: HOST_IP
      valueFrom:
        fieldRef:
          fieldPath: status.hostIP
    - name: ISTIO_CPU_LIMIT
      valueFrom:
        resourceFieldRef:
          resource: limits.cpu
          divisor: "1"
    - name: PROXY_CONFIG
      value: |
             {{ protoToJSON .ProxyConfig }}
    - name: ISTIO_META_POD_PORTS
      value: |-
        [
        {{- $first := true }}
        {{- range $index1, $c := .Spec.Containers }}
          {{- range $index2, $p := $c.Ports }}
            {{- if (structToJSON $p) }}
            {{if not $first}},{{end}}{{ structToJSON $p }}
            {{- $first = false }}
            {{- end }}
          {{- end}}
        {{- end}}
        ]
    - name: GOMEMLIMIT
      valueFrom:
        resourceFieldRef:
          resource: limits.memory
          divisor: "1"
    - name: GOMAXPROCS
      valueFrom:
        resourceFieldRef:
          resource: limits.cpu
          divisor: "1"
    {{- if .CompliancePolicy }}
    - name: COMPLIANCE_POLICY
      value: "{{ .CompliancePolicy }}"
    {{- end }}
    - name: ISTIO_META_APP_CONTAINERS
      value: "{{ $containers | join "," }}"
    - name: ISTIO_META_CLUSTER_ID
      value: "{{ valueOrDefault .Values.global.multiCluster.clusterName `Kubernetes` }}"
    - name: ISTIO_META_NODE_NAME
      valueFrom:
        fieldRef:
          fieldPath: spec.nodeName
    - name: ISTIO_META_INTERCEPTION_MODE
      value: "{{ .ProxyConfig.InterceptionMode.String }}"
    {{- if .Values.global.network }}
    - name: ISTIO_META_NETWORK
      value: "{{ .Values.global.network }}"
    {{- end }}
    {{- if .DeploymentMeta.Name }}
    - name: ISTIO_META_WORKLOAD_NAME
      value: "{{ .DeploymentMeta.Name }}"
    {{ end }}
    {{- if and .TypeMeta.APIVersion .DeploymentMeta.Name }}
    - name: ISTIO_META_OWNER
      value: kubernetes://apis/{{ .TypeMeta.APIVersion }}/namespaces/{{ valueOrDefault .DeploymentMeta.Namespace `default` }}/{{ toLower .TypeMeta.Kind}}s/{{ .DeploymentMeta.Name }}
    {{- end}}
    {{- if (isset .ObjectMeta.Annotations `sidecar.istio.io/bootstrapOverride`) }}
    - name: ISTIO_BOOTSTRAP_OVERRIDE
      value: "/etc/istio/custom-bootstrap/custom_bootstrap.json"
    {{- end }}
    {{- if .Values.global.meshID }}
    - name: ISTIO_META_MESH_ID
      value: "{{ .Values.global.meshID }}"
    {{- else if (valueOrDefault .MeshConfig.TrustDomain .Values.global.trustDomain) }}
    - name: ISTIO_META_MESH_ID
      value: "{{ (valueOrDefault .MeshConfig.TrustDomain .Values.global.trustDomain) }}"
    {{- end }}
    {{- with (valueOrDefault .MeshConfig.TrustDomain .Values.global.trustDomain)  }}
    - name: TRUST_DOMAIN
      value: "{{ . }}"
    {{- end }}
    {{- range $key, $value := .ProxyConfig.ProxyMetadata }}
    - name: {{ $key }}
      value: "{{ $value }}"
    {{- end }}
    {{with .Values.global.imagePullPolicy }}imagePullPolicy: "{{.}}"{{end}}
    readinessProbe:
      httpGet:
        path: /healthz/ready
        port: 15021
      initialDelaySeconds: {{.Values.global.proxy.readinessInitialDelaySeconds }}
      periodSeconds: {{ .Values.global.proxy.readinessPeriodSeconds }}
      timeoutSeconds: 3
      failureThreshold: {{ .Values.global.proxy.readinessFailureThreshold }}
    volumeMounts:
    - name: workload-socket
      mountPath: /var/run/secrets/workload-spiffe-uds
    - name: credential-socket
      mountPath: /var/run/secrets/credential-uds
    {{- if eq .Values.global.caName "GkeWorkloadCertificate" }}
    - name: gke-workload-certificate
      mountPath: /var/run/secrets/workload-spiffe-credentials
      readOnly: true
    {{- else }}
    - name: workload-certs
      mountPath: /var/run/secrets/workload-spiffe-credentials
    {{- end }}
    {{- if eq .Values.global.pilotCertProvider "istiod" }}
    - mountPath: /var/run/secrets/istio
      name: istiod-ca-cert
    {{- end }}
    - mountPath: /var/lib/istio/data
      name: istio-data
    {{ if (isset .ObjectMeta.Annotations `sidecar.istio.io/bootstrapOverride`) }}
    - mountPath: /etc/istio/custom-bootstrap
      name: custom-bootstrap-volume
    {{- end }}
    # SDS channel between istioagent and Envoy
    - mountPath: /etc/istio/proxy
      name: istio-envoy
    - mountPath: /var/run/secrets/tokens
      name: istio-token
    {{- if .Values.global.mountMtlsCerts }}
    # Use the key and cert mounted to /etc/certs/ for the in-cluster mTLS communications.
    - mountPath: /etc/certs/
      name: istio-certs
      readOnly: true
    {{- end }}
    - name: istio-podinfo
      mountPath: /etc/istio/pod
  volumes:
  - emptyDir:
    name: workload-socket
  - emptyDir: {}
    name: credential-socket
  {{- if eq .Values.global.caName "GkeWorkloadCertificate" }}
  - name: gke-workload-certificate
    csi:
      driver: workloadcertificates.security.cloud.google.com
  {{- else}}
  - emptyDir: {}
    name: workload-certs
  {{- end }}
  {{- if (isset .ObjectMeta.Annotations `sidecar.istio.io/bootstrapOverride`) }}
  - name: custom-bootstrap-volume
    configMap:
      name: {{ annotation .ObjectMeta `sidecar.istio.io/bootstrapOverride` "" }}
  {{- end }}
  # SDS channel between istioagent and Envoy
  - emptyDir:
      medium: Memory
    name: istio-envoy
  - name: istio-data
    emptyDir: {}
  - name: istio-podinfo
    downwardAPI:
      items:
        - path: "labels"
          fieldRef:
            fieldPath: metadata.labels
        - path: "annotations"
          fieldRef:
            fieldPath: metadata.annotations
  - name: istio-token
    projected:
      sources:
      - serviceAccountToken:
          path: istio-token
          expirationSeconds: 43200
          audience: {{ .Values.global.sds.token.aud }}
  {{- if eq .Values.global.pilotCertProvider "istiod" }}
  - name: istiod-ca-cert
  {{- if eq (.Values.pilot.env).ENABLE_CLUSTER_TRUST_BUNDLE_API true }}
    projected:
      sources:
      - clusterTrustBundle:
          name: istio.io:istiod-ca:{{ .Values.global.trustBundleName | default "root-cert" }}
          path: root-cert.pem
  {{- else }}
    configMap:
      name: {{ .Values.global.trustBundleName | default "istio-ca-root-cert" }}
  {{- end }}
  {{- end }}
  {{- if .Values.global.mountMtlsCerts }}
  # Use the key and cert mounted to /etc/certs/ for the in-cluster mTLS communications.
  - name: istio-certs
    secret:
      optional: true
      {{ if eq .Spec.ServiceAccountName "" }}
      secretName: istio.default
      {{ else -}}
      secretName: {{  printf "istio.%s" .Spec.ServiceAccountName }}
      {{  end -}}
  {{- end }}
  {{- if .Values.global.imagePullSecrets }}
  imagePullSecrets:
    {{- range .Values.global.imagePullSecrets }}
    - name: {{ . }}
    {{- end }}
  {{- end }}
      1. 移除 sysctls，因为 net.ipv4.ip_unprivileged_port_start 在 4.11 之前的 Linux kernel 中不可用。

    场景 2: 4.11 之前的 kernel 版本 + 特权端口（端口 < 1024）

    如果 gateway 需要监听 1024 以下的端口，除了对 sysctls: [] 的更改之外，还必须添加 NET_BIND_SERVICE capability。修改 gateway-injection-template.txt 中 istio-proxy 容器的 securityContext 部分：

        securityContext:
      capabilities:
        add:
        - NET_BIND_SERVICE
      runAsUser: {{ .ProxyUID | default "1337" }}
      runAsGroup: {{ .ProxyGID | default "1337" }}
      # Uncomment the following fields to run the gateway as root if necessary.
      # runAsUser: 0
      # runAsGroup: 0
      # runAsNonRoot: false
    WARNING

    如果添加 NET_BIND_SERVICE capability 后 gateway 仍无法监听 1024 以下的端口，请考虑以下替代方案：

    1. 使用 1024 或更高的端口（推荐）— 重新配置 gateway listener，使其使用 ≥ 1024 的端口，从根本上避免特权问题。
    2. 以 root 身份运行 gateway
      • 在容器的 securityContext 中设置 runAsUser: 0、runAsGroup: 0 和 runAsNonRoot: false。这会向 gateway 进程授予完整权限。使用此方法前，请仔细评估其安全影响。
      • 同时在 gateway-deployment.yaml 的 istio-proxy 容器上设置 runAsNonRoot: false（或移除该字段），使其与此模板保持一致。否则，其容器级 runAsNonRoot: true 会覆盖模板，导致 gateway pod 被 container's runAsUser breaks non-root policy 拒绝。
      • 以 root 身份运行 gateway 与 Restricted Pod Security Admission profile 不兼容，因为该 profile 禁止 root 容器。gateway namespace 必须强制执行 Baseline profile 或更低级别。有关更多信息，请参阅 Pod Security Admission。

    应用注入模板

    1. 为 Istio resource 修补默认的 gateway 注入模板：

      TEMPLATE_CONTENT=$(cat gateway-injection-template.txt)
PATCH_DATA=$(jq -n \
  --arg template "${TEMPLATE_CONTENT}" \
  '{
    "spec": {
      "values": {
        "sidecarInjectorWebhook": {
          "templates": {
            "gateway": $template
          }
        }
      }
    }
  }')
# Finally apply the patch to the Istio resource named `default`:
kubectl patch istio default --type=merge -p "${PATCH_DATA}"

    2. 运行以下命令，等待 control plane 返回 Ready status condition：

      kubectl wait --for condition=Ready istio/default --timeout=3m

    Kubernetes Gateway API

    前提条件

    • Alauda Container Platform 4.2.0 或更高版本，或者将 Gateway API CRD 升级到最新版本。

    操作步骤

    场景 1: 仅适用于 4.11 之前的 kernel 版本（端口 ≥ 1024）

    1. 在计划部署 Gateway 的同一 namespace 中创建名为 asm-kube-gateway-options 的 ConfigMap：

      apiVersion: v1
kind: ConfigMap
metadata:
  name: asm-kube-gateway-options
  # Replace `<your-gateway-namespace>` with the actual namespace where your Gateway will be deployed. 
  namespace: <your-gateway-namespace>
data:
  deployment: |
    spec:
      template:
        spec:
          securityContext:
            sysctls: []
      1. 移除 sysctls，因为 net.ipv4.ip_unprivileged_port_start 在 4.11 之前的 Linux kernel 中不可用。

    场景 2: 4.11 之前的 kernel 版本 + 特权端口（端口 < 1024）

    如果 gateway 需要监听 1024 以下的端口，请在 ConfigMap 中添加 NET_BIND_SERVICE capability。修改 data.deployment 字段，使其包含容器级 security context：

    apiVersion: v1
kind: ConfigMap
metadata:
  name: asm-kube-gateway-options
  namespace: <your-gateway-namespace>
data:
  deployment: |
    spec:
      template:
        spec:
          securityContext:
            sysctls: []
          # Add the following container-level security context to grant the NET_BIND_SERVICE capability.
          containers:
          - name: istio-proxy
            securityContext:
              capabilities:
                add:
                - NET_BIND_SERVICE
              # Uncomment the following fields to run the gateway as root if necessary.
              # runAsUser: 0
              # runAsGroup: 0
              # runAsNonRoot: false
    WARNING

    如果添加 NET_BIND_SERVICE capability 后 gateway 仍无法监听 1024 以下的端口，请考虑以下替代方案：

    1. 使用 1024 或更高的端口（推荐）— 重新配置 gateway listener，使其使用 ≥ 1024 的端口，从根本上避免特权问题。
    2. 以 root 身份运行 gateway — 在容器的 securityContext 中设置 runAsUser: 0、runAsGroup: 0 和 runAsNonRoot: false。这会向 gateway 进程授予完整权限。使用此方法前，请仔细评估其安全影响。 以 root 身份运行 gateway 与 Restricted Pod Security Admission profile 不兼容，因为该 profile 禁止 root 容器。gateway namespace 必须强制执行 Baseline profile 或更低级别。有关更多信息，请参阅 Pod Security Admission。

    应用 ConfigMap

    1. 添加 infrastructure.parametersRef 字段，在 Gateway resource 中引用该 ConfigMap：

      apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: <your-gateway-name>
  namespace: <your-gateway-namespace>
spec:
  # Add the following infrastructure configuration to your Gateway CR
  infrastructure:
    parametersRef:
      group: ""
      kind: ConfigMap
      name: asm-kube-gateway-options
  # ... rest of your Gateway configuration

      此配置可确保 gateway deployment 使用 ConfigMap 中定义的自定义 security context 设置。