Skip to main content
Mapagam

Managing Sidecar Injection

1. Enabling Automatic Sidecar Injection

Configuration Description Default Notes
istio.io/inject Annotation to enable sidecar injection false Set to true to inject sidecar
istio.io/inject Annotation to enable sidecar injection false Set to true to inject sidecar

Example: Enable injection for namespace

apiVersion: v1
kind: Namespace
metadata:
  name: production
  labels:
    istio.io/inject: "true"

Example: Enable injection for pod

apiVersion: v1
kind: Pod
metadata:
  annotations:
    sidecar.istio.io/inject: "true"

2. Implementing Manual Sidecar Injection

Configuration Description Example
inject Controls whether the sidecar is injected into a pod false
inject Controls whether the sidecar is injected into a pod true

Example: Manual Injection with Annotation

apiVersion: v1
kind: Pod
metadata:
  name: my-app
  annotations:
    sidecar.istio.io/inject: "true"
spec:
  containers:
  - name: app
    image: my-app:latest

Example: Manual Injection with Label

apiVersion: v1
kind: Pod
metadata:
  name: my-app
  labels:
    istio-injection: enabled
spec:
  containers:
  - name: app
    image: my-app:latest

3. Configuring Namespace Labels

Label Value Description
istio.io/rev 1-20-0 Specifies the Istio revision to use for sidecar injection
istio.io/inject true or false Controls whether sidecars are injected into pods in this namespace
istio.io/inject-config inject-config-name Name of the Istio injection configuration to use for this namespace

Example: Enabling Sidecar Injection

apiVersion: v1
kind: Namespace
metadata:
  name: production
  labels:
    istio.io/inject: "true"
Note: Setting istio.io/inject to false prevents automatic sidecar injection in the namespace.

4. Configuring Pod Annotations

Annotation Values Description
sidecar.istio.io/inject true | false Controls whether to inject the Istio sidecar. Defaults to true if not set.
sidecar.istio.io/rewriteAppHTTPProbers true | false Enables rewriting of liveness and readiness probes to work with the sidecar. Defaults to false.
traffic.sidecar.istio.io/includeInboundPorts Comma-separated list of ports Specifies the inbound ports to be included in the sidecar proxy. Defaults to all ports.
traffic.sidecar.istio.io/excludeInboundPorts Comma-separated list of ports Specifies the inbound ports to be excluded from the sidecar proxy. Useful for excluding application ports.
traffic.sidecar.istio.io/includeOutboundIPRanges Comma-separated list of CIDR ranges Specifies the outbound IP ranges to be included in the sidecar proxy. Defaults to all IPs.
traffic.sidecar.istio.io/excludeOutboundIPRanges Comma-separated list of CIDR ranges Specifies the outbound IP ranges to be excluded from the sidecar proxy. Useful for excluding external services.
traffic.sidecar.istio.io/excludeOutboundPorts Comma-separated list of ports Specifies the outbound ports to be excluded from the sidecar proxy. Useful for excluding system or external services.
sidecar.istio.io/status JSON object Read-only annotation containing the sidecar injection status and configuration. Used internally by Istio.

Example: Injecting Sidecar with Annotations

apiVersion: v1
kind: Pod
metadata:
  name: my-app
  annotations:
    sidecar.istio.io/inject: "true"
    traffic.sidecar.istio.io/includeInboundPorts: "8080,9090"
    traffic.sidecar.istio.io/excludeOutboundPorts: "53"
spec:
  containers:
  - name: app
    image: my-app-image

5. Excluding Workloads from Injection

Workload Type Exclusion Method Configuration Notes
Deployment istio.io/inject 
{
  "spec": {
    "template": {
      "metadata": {
        "annotations": {
          "istio.io/inject": "false"
        }
      }
    }
  }
}
 Set to false to disable sidecar injection
StatefulSet istio.io/inject 
{
  "spec": {
    "template": {
      "metadata": {
        "annotations": {
          "istio.io/inject": "false"
        }
      }
    }
  }
}
 Same annotation as Deployment
DaemonSet istio.io/inject 
{
  "spec": {
    "template": {
      "metadata": {
        "annotations": {
          "istio.io/inject": "false"
        }
      }
    }
  }
}
 Same annotation as Deployment
Job istio.io/inject 
{
  "spec": {
    "template": {
      "metadata": {
        "annotations": {
          "istio.io/inject": "false"
        }
      }
    }
  }
}
 Same annotation as Deployment

Example: Exclude a Deployment from Injection

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  annotations:
    istio.io/inject: "false"
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: app
        image: my-app:latest
Note: The istio.io/inject annotation can also be set at the namespace level to exclude all workloads in that namespace.

6. Configuring Init Container Settings

Setting Description Default Value Notes
initContainer.image Image used for the init container istio/init Must be compatible with the sidecar proxy image
initContainer.resources Resource limits and requests for the init container {} Can include cpu and memory
initContainer.securityContext Security context for the init container {} Allows setting user, group, and capabilities
initContainer.command Command to run in the init container [/bin/sh, -c, 'cp /usr/local/bin/* /tmp/'] Customize based on required setup steps

Example: Custom Init Container Configuration

initContainer:
  image: "custom-init-image:v1.0"
  resources:
    limits:
      cpu: "200m"
      memory: "128Mi"
    requests:
      cpu: "100m"
      memory: "64Mi"
  securityContext:
    runAsUser: 1000
    runAsGroup: 2000
    capabilities:
      drop:
        - ALL

7. Setting Injection Templates

Property Values Description
injector.template default Template name used for sidecar injection
injector.templateFile inject.yaml Path to custom injection template file

Example: Custom Injection Template

apiVersion: v1
kind: Template
metadata:
  name: custom-inject
spec:
  containers:
    - name: istio-proxy
      image: istio/proxyv2:1.20.0
      args:
        - "--domain"
        - $(POD_NAMESPACE).svc.cluster.local
        - "--log-level"
        - info
Note: Injection templates can be customized to inject additional sidecar configurations or modify default behavior.

8. Managing Injection Webhook

Property Description Default Value Notes
injector.webhook.enabled Enables or disables the sidecar injection webhook true Set to false to disable automatic sidecar injection
injector.webhook.port Port on which the webhook listens for injection requests 443 Must be accessible from the Kubernetes API server
injector.webhook.timeoutSeconds Timeout for webhook requests in seconds 30 Adjust based on network latency or large pod counts

Example: Enabling Sidecar Injection Webhook

injector:
  webhook:
    enabled: true
    port: 443
    timeoutSeconds: 30
Note: The webhook requires a valid TLS certificate to be mounted at /etc/certs. Ensure that the certificate is valid and not expired.
Warning: Disabling the webhook will require manual sidecar injection using kubectl or other tools.

Webhook Configuration Summary

  • Enabled by default: Sidecar injection is enabled unless explicitly disabled.
  • Port binding: The webhook listens on port 443 by default.
  • Timeout: Requests to the webhook timeout after 30 seconds.

9. Troubleshooting Injection Issues

Common Injection Failure Scenarios

  1. Namespace not labeled correctly
  2. Sidecar injection disabled globally or per-namespace
  3. Resource limits insufficient for sidecar
  4. Missing or incorrect annotations
  5. Version mismatch between control plane and data plane
Issue Potential Cause Solution
No sidecar container in pod Namespace missing istio-injection=enabled label Add label: kubectl label namespace <namespace> istio-injection=enabled
Sidecar fails to start Insufficient memory or CPU limits Increase resource limits in deployment YAML
Sidecar not injected despite annotations Incorrect annotation format or missing istio.io/inject Verify annotation syntax: sidecar.istio.io/inject: "true"
Pods stuck in pending state Control plane not reachable or misconfigured Check istiod pod status and logs

Example: Check injection status for a pod

kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.spec.containers[*].name}'

Example: Verify namespace labeling

kubectl get namespace <namespace> -o jsonpath='{.metadata.labels}'
Note: Use kubectl describe pod <pod-name> to inspect events and errors related to sidecar injection.
Warning: Disabling injection globally may break existing services that rely on sidecar behavior.

10. Verifying Sidecar Injection

Verification Method Description Command/Tool Notes
kubectl get pods Check if sidecar containers are present in the pod kubectl get pods -n <namespace> Look for containers named istio-proxy or similar in the output
kubectl describe pod Inspect pod details to confirm sidecar injection kubectl describe pod <pod-name> -n <namespace> Check Containers section for sidecar container status
istioctl proxy-config View configuration and status of sidecar proxies istioctl proxy-config bootstrap <pod-name> -n <namespace> Use istioctl to inspect proxy configuration
Sidecar Injection Labels Verify that the namespace or pod has correct labels kubectl get ns <namespace> -o jsonpath='{.metadata.labels}'; kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.metadata.labels}' Ensure istio.io/rev or sidecar.istio.io/inject labels are set correctly

Example: Verifying Sidecar Injection with kubectl

kubectl get pods -n default
NAME                     READY   STATUS    RESTARTS   AGE
my-app-7b5c9f8d4-xyz12   2/2     Running   0          5m
Note: The READY column shows 2/2, indicating that both the main app container and the sidecar container are running.

Example: Inspecting Pod Description for Sidecar

kubectl describe pod my-app-7b5c9f8d4-xyz12 -n default
...
Containers:
  my-app:
    Container ID:   docker://...
    Image:          my-app:v1
  istio-proxy:
    Container ID:   docker://...
    Image:          istio/proxyv2:1.20.0
...
Note: The istio-proxy container is listed as part of the pod, confirming sidecar injection.

11. Configuring Injection Order

Property Description Default Notes
injector.priority Priority level for sidecar injection 0 Higher values injected first
injector.order Injection order configuration auto Can be auto, before, or after

Example: Configuring Injection Priority

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-inject-config
data:
  injector.priority: "10"
  injector.order: "before"
Note: Injection order affects how sidecars are injected into pods. Setting injector.order to before ensures sidecars are injected before other containers in the pod.

12. Managing Injection for StatefulSets

Property Description Default Notes
inject Controls whether the sidecar is injected into a StatefulSet false Set to true to enable injection
template Custom injection template to use null Allows customizing injection behavior

Example: Enabling Sidecar Injection for StatefulSet

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: web
  annotations:
    sidecar.istio.io/inject: "true"
spec:
  serviceName: "web"
  replicas: 3
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
      - name: web
        image: nginx
Note: Injection for StatefulSets requires the sidecar.istio.io/inject annotation to be set to true.
Warning: Ensure that the StatefulSet's pod template is compatible with sidecar injection to avoid conflicts.

Was this article helpful?

Related Cheat Sheets