Install and uninstall the debug sidecar proxy#

Introduction#

The Aspen Mesh Platform includes:

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 on-mesh non-gateway pods (pods with sidecars) are using the debug sidecar proxy image

Installing the debug sidecar proxy replaces the Istio proxies for all on-mesh non-gateway pods with the debug sidecar proxy. Uninstalling the debug sidecar proxy replaces all sidecar proxies 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.

Log in to the appropriate artifact registry with Helm and set the repository address#

Install the debug sidecar proxy#

In a terminal window on your computer, make sure you’re in the Aspen Mesh Platform chart directory.
Open your Aspen Mesh override values file (aspen-mesh-override-values.yaml) in a text editor.

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

defaults:
  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.
Set the AM_TAG environment variable to the version of Aspen Mesh that’s installed.

Example
```
$ export AM_TAG=1.21.6-am1
```

Upgrade the Istio control plane:

Kubernetes

$ helm upgrade istiod oci://$AM_REPO/charts/istiod --version $AM_TAG \
    --namespace istio-system \
    --values aspen-mesh-override-values.yaml \
    --wait

OpenShift

$ helm upgrade istiod oci://$AM_REPO/charts/istiod --version $AM_TAG \
    --namespace istio-system \
    --values aspen-mesh-override-values.yaml \
    --set profile=openshift \
    --wait

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 automatic sidecar injection is enabled or there are manually injected sidecars, restart all pods with sidecars:
```
$ kubectl delete pods --namespace <namespaceName> --selector security.istio.io/tlsMode=istio
```
In each namespace in which automatic sidecar injection is enabled or there are manually injected sidecars, 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#

In a terminal window on your computer, make sure you’re in the Aspen Mesh Platform chart directory.
Open your Aspen Mesh override values file (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.
Set the AM_TAG environment variable to the version of Aspen Mesh that’s installed.

Example
```
$ export AM_TAG=1.21.6-am1
```

Upgrade the Istio control plane:

Kubernetes

$ helm upgrade istiod oci://$AM_REPO/charts/istiod --version $AM_TAG \
    --namespace istio-system \
    --values aspen-mesh-override-values.yaml \
    --wait

OpenShift

$ helm upgrade istiod oci://$AM_REPO/charts/istiod --version $AM_TAG \
    --namespace istio-system \
    --values aspen-mesh-override-values.yaml \
    --set profile=openshift \
    --wait

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 automatic sidecar injection is enabled or there are manually injected sidecars, restart all pods with sidecars:
```
$ kubectl delete pods --namespace <namespaceName> --selector security.istio.io/tlsMode=istio
```
In each namespace in which automatic sidecar injection is enabled or there are manually injected sidecars, 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.