Install and uninstall the debug sidecar proxy#

Introduction#

Aspen Mesh 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 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:

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#

  1. Open your Aspen Mesh override values file (aspen-mesh-override-values.yaml) in a text editor.

  2. 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

  3. 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.

  4. Save and close the file.

  5. Change to the Aspen Mesh release directory.

  6. Upgrade the Istio control plane:

    $ helm upgrade istiod manifests/charts/istio-control/istio-discovery \
    --namespace istio-system \
    --values aspen-mesh-override-values.yaml \
    --wait

  7. Make sure that all Aspen Mesh services are running and healthy.

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

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

  9. 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

  10. 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#

  1. Open your Aspen Mesh override values file (aspen-mesh-override-values.yaml) in a text editor.

  2. 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.

  3. Save and close the file.

  4. Change to the Aspen Mesh release directory.

  5. Upgrade the Istio control plane:

    $ helm upgrade istiod manifests/charts/istio-control/istio-discovery \
    --namespace istio-system \
    --values aspen-mesh-override-values.yaml \
    --wait

  6. Make sure that all Aspen Mesh services are running and healthy.

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

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

  8. 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

  9. 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.