Install and uninstall the debug sidecar proxy#

Introduction#

Aspen Mesh 1.11.8-am2 and later include:

A debug sidecar proxy image that you can temporarily install for debugging and other purposes
A script (list-proxy-images.sh) that you can use to verify whether pods with sidecars are using the debug sidecar proxy image

Installing the debug sidecar proxy replaces all sidecar proxies in your service mesh with the debug sidecar proxy. Uninstalling the debug sidecar proxy replaces all sidecar proxies in your service mesh with the standard sidecar proxy.

What you can do with the debug sidecar proxy#

You can use the debug sidecar proxy to do the following:

Collect debug information from sidecar proxies.
Get port information for pods when using the verify-dual-stack.sh script.

When to install and uninstall the debug sidecar proxy#

The debug sidecar proxy is intended for temporary use. Install the debug sidecar proxy only when other instructions tell you to do so. When you no longer need the debug sidecar proxy, uninstall it.

Install the debug sidecar proxy#

Make sure the version of Aspen Mesh you have installed is 1.11.8-am2 or later.

Earlier versions of Aspen mesh don’t include the list-proxy-images.sh script that you’ll use to confirm the debug sidecar proxy has been installed.
Open your Aspen Mesh override values file (for example, aspen-mesh-override-values.yaml) in a text editor.

Add the following information at the top level of the hierarchy:

global:
  proxy_init:
    image: proxyv2-debug
  proxy:
    image: proxyv2-debug
    # Include these fields only when you want to collect debug information from sidecar proxies:
    # logLevel: debug
    # enableCoreDump: true

If you’re installing the debug sidecar proxy to collect debug information from sidecar proxies (for example, core files or heap-usage information), uncomment the logLevel and enableCoreDump fields.
Save and close the file.
Change to the Aspen Mesh release directory.
Upgrade the Istio control plane, making sure to replace <aspenMeshOverrideValuesFilename> with the path and filename (for example, aspen-mesh-override-values.yaml) of your Aspen Mesh override values file:
```
$ helm upgrade istiod manifests/charts/istio-control/istio-discovery \
    --namespace istio-system \
    --values <aspenMeshOverrideValuesFilename>
```
Make sure that all Aspen Mesh services are running and healthy.

Upgrade all manually injected sidecars, as in this example for a deployment:

$ kubectl apply -f < (istioctl kube-inject -f <deploymentManifestFilename>)

In each namespace in which sidecar injection (either automatic or manual) should occur, restart all pods with sidecars:
```
$ kubectl delete pods --namespace <namespaceName> --selector security.istio.io/tlsMode=istio
```
In each namespace in which sidecar injection (either automatic or manual) should occur, execute the script to verify that all pods with sidecars are using the debug sidecar proxy (proxyv2-debug):
```
$ ./tools/list-proxy-images.sh <namespaceName> debug
```
If the script indicates that any pods are still using the standard sidecar proxy, restart those pods and then execute the script again.

Uninstall the debug sidecar proxy#

Open your Aspen Mesh override values file (for example, aspen-mesh-override-values.yaml) in a text editor.
Remove the following information (under .global):
```
  proxy_init:
    image: proxyv2-debug
  proxy:
    image: proxyv2-debug
    logLevel: debug
    enableCoreDump: true
```
The logLevel and enableCoreDump fields are present only if you installed the debug sidecar proxy to collect debug information from sidecar proxies.
Save and close the file.
Change to the Aspen Mesh release directory.
Upgrade the Istio control plane, making sure to replace <aspenMeshOverrideValuesFilename> with the path and filename (for example, aspen-mesh-override-values.yaml) of your Aspen Mesh override values file:
```
$ helm upgrade istiod manifests/charts/istio-control/istio-discovery \
    --namespace istio-system \
    --values <aspenMeshOverrideValuesFilename>
```
Make sure that all Aspen Mesh services are running and healthy.

Upgrade all manually injected sidecars, as in this example for a deployment:

$ kubectl apply -f < (istioctl kube-inject -f <deploymentManifestFilename>)

In each namespace in which sidecar injection (either automatic or manual) should occur, restart all pods with sidecars:
```
$ kubectl delete pods --namespace <namespaceName> --selector security.istio.io/tlsMode=istio
```
In each namespace in which sidecar injection (either automatic or manual) should occur, execute the script to verify that all pods with sidecars are using the standard sidecar proxy (proxyv2):
```
$ ./tools/list-proxy-images.sh <namespaceName> standard
```
If the script indicates that any pods are still using the debug sidecar proxy, restart those pods and then execute the script again.