Options for Google Kubernetes Engine Pod setup with automatic Envoy injection

This guide provides you with information on additional options and tasks for the automatic Envoy sidecar injector.

Adding sidecar proxies to existing workloads

After you've installed the sidecar injector to your clusters, sidecar proxies are automatically injected to newly created pods in enabled namespaces. If you have workloads already running prior to enabling the sidecar injector, you must restart them for injection to take place.

For pods managed by Deployment, DaemonSet or StatefulSet controllers, you can run the following:

# Deployment
kubectl rollout restart deployment/DEPLOYMENT_NAME --namespace NAMESPACE

# DaemonSet
kubectl rollout restart daemonset/DAEMONSET_NAME --namespace NAMESPACE

# StatefulSet
kubectl rollout restart statefulset/STATEFULSET_NAME --namespace NAMESPACE

If you didn't use any of the above controllers to deploy your pod(s), you must delete the pod(s) individually. Afterwards, they are automatically recreated with new sidecar proxies.

kubectl delete pod POD_NAME -n NAMESPACE

Verify that a sidecar proxy container has been injected in each of your pods:

kubectl get pods -n NAMESPACE

For example, with the busybox client created above, you should see 2/2 pods running, one for the busybox application itself and one for the injected Envoy sidecar proxy:

NAME                      READY   STATUS    RESTARTS   AGE
busybox-c54f578c9-c9fk4   2/2     Running   183        7d15h

Injection overrides

By default, enabling a namespace enables sidecar proxy injection for all resident pods. Injection can also be selectively configured for different scopes to suit specific needs. For instance, overrides should be used to prevent sidecar proxy injection for proxyless gRPC services.

Note that the injection overrides only apply when the namespace is enabled, and take effect with the following priority: Pod Annotations > NeverInjectSelector > AlwaysInjectSelector > Default Policy

Enabling/disabling injection for specific individual pods

Use the following pod annotation to turn injection on or off for a specific pod in an enabled namespace:

...
metadata:
  annotations:
    sidecar.istio.io/inject: "true" / "false"

Enabling/disabling injection for specific groups of pods

The sidecar injector itself can be configured to always or never inject pods in enabled namespaces based on an array of Kubernetes label selectors. For example, use the following commands to configure the sidecar injector to not inject a sidecar proxy if the pod has the label "run=client":

kubectl edit configmap -n istio-control istio-sidecar-injector

...
config: |-
  policy: enabled
  alwaysInjectSelector:
    []

  neverInjectSelector:
    - matchLabels:
        run: client
...

Existing sidecar injector deployments must be restarted for this configuration to take effect.

Configuring sidecar proxy metadata

To support additional Traffic Director features, sidecar proxies can inherit specific metadata from their encapsulating Pods. For example, include the following annotation in your Pod template specification to apply the "version=dev" label to its injected sidecar proxies.

...
metadata:
  annotations:
    cloud.google.com/proxyMetadata: '{"version": "dev"}'

Config filtering then allows Traffic Director to share a subset of configuration only with the specific proxies that match on this "version=dev" label.

Existing deployments must be restarted for this configuration to take effect.

Supported pod annotations

Traffic Director supports the following pod annotations for sidecar injection. Though additional sidecar injector annotations might work, the following list represents annotations that Traffic Director supports. To avoid breakage or instability, do not create a dependency on other annotations in your production deployment.

Annotation Name Value Description
sidecar.istio.io/inject Boolean, represented as a string. For example: "true" Specifies whether or not an Envoy sidecar should be automatically injected into the workload.
cloud.google.com/proxyMetadata JSON map of key-value pairs. For example: "'{"version": "dev"}'" Specifies the key/value pairs in a JSON map that should be appended to Envoy metadata.

Uninstalling the sidecar injector

Uninstall the sidecar injector with the following commands:

kubectl delete -f specs/
kubectl label namespace default istio-injection-