Sidecar Proxy Injection
Learn about the configuration options for NGINX Service Mesh sidecar proxy injection.
NGINX Service Mesh works by injecting a sidecar proxy into Kubernetes resources.
A couple important things to note about injected Pods:
- The sidecar proxy will not be injected into Pods that define multiple container ports with the same port number or for container ports with the SCTP protocol. UDP and TCP are an exception to this, and may be specified on the same port.
- When you inject the sidecar proxy into a Kubernetes resource, the injected config uses the global mTLS setting. You can define the global setting when you deploy NGINX Service Mesh, or use the default setting. Refer to Secure Mesh Traffic using mTLS for more information.
The mesh supports the following Kubernetes resources and API versions for injection:
|Resource Type||API Version|
You can choose to inject the sidecar proxy into the YAML or JSON definitions for your Kubernetes resources in the following ways:
To enable automatic sidecar injection for all Pods in a namespace, add the
injector.nsm.nginx.com/auto-inject=enabled label to the namespace.
kubectl label namespaces <namespace name> injector.nsm.nginx.com/auto-inject=enabled
For more granular control, you can enable or disable automatic sidecar injection on a per-resource basis.
To do so, add the following label to the resource’s PodTemplateSpec:
Pod labels take precedence over namespace labels.
If you add the auto-inject label to existing resources, you will need to restart the affected Pods in order for the sidecar to be injected.
By the same token if you remove the label or set the Pod label to
disabled, you will need to restart them to remove the sidecar.
kubectl rollout restart to restart your Pods:
kubectl rollout restart <resource type>/<resource name>
kubectl rollout restart deployment/frontend
To inject the sidecar proxy into a resource manually, use the
nginx-meshctl inject command. Provide the path to the resource definition file and your desired output filename.
nginx-meshctl inject < <resource-file> > <new-resource-file>
For example, the following command will write the updated config for “resource.yaml” to a new file, “resource-injected.yaml”:
nginx-meshctl inject < resource.yaml > resource-injected.yaml
You can set the proxy to ignore ports for either incoming or outgoing traffic. The NGINX Service Mesh applies the configurations at injection time.
For automatic injection, add the following annotations to the PodTemplateSpec in your resource definition:
config.nsm.nginx.com/ignore-incoming-ports: "port1, port2, ..., portN" config.nsm.nginx.com/ignore-outgoing-ports: "port1, port2, ..., portN"
For manual injection, you can use the annotations above or specify the ports when running the
nginx-meshctl inject --ignore-incoming-ports "port1,port2,...,portN", --ignore-outgoing-ports "port1,port2,...,portN" < resource.yaml > resource-injected.yaml
Refer to NGINX Service Mesh Annotations for more information around annotations.
By default, the following ports are ignored by the proxy:
- 53 (DNS)
If mTLS mode is set to
strict, then readiness, liveness, and startup probes using HTTP GET do not work. This is
kubelet not having the correct client certificates. To remedy this, application HTTP/S health probes are
rewritten at injection time. The new probes point to an endpoint on the sidecar proxy, which
redirects the health check to the original destination on the application. This allows the health check to bypass
the SSL verification, while still sending the health check to the intended destination.
NGINX Service Mesh automatically detects and adjusts the
eth0 interface to support the 32 bytes of space required for PROXY Protocol V2. See the UDP and eBPF architecture section for more information.