Skip to main content

Remote Debug

Remote debugging in CodeNOW lets you run your application code locally while it operates as if it were running inside the cluster. Network traffic, environment variables, and file system access from the target pod are forwarded to your local process, so you can attach a debugger in your IDE and step through real cluster traffic without deploying a debug build.

CodeNOW uses mirrord as the underlying mechanism.

How It Works​

When remote debugging is enabled for a deployment, CodeNOW injects a mirrord agent into the target pod. The agent bridges your local process with the pod:

  • Incoming traffic is mirrored (or stolen, depending on the mirrord configuration) from the pod to your local process
  • Outgoing traffic from your local process is routed through the pod, so downstream services see requests originating from within the cluster
  • Environment variables from the pod are injected into your local process
  • File system access can optionally be proxied to the pod's file system

This means your local process behaves as a cluster-side peer of the running application — with full access to internal services, secrets, and the environment configuration active on that deployment.

warning

Enabling remote debugging requires the affected pods to run without service mesh sidecars and security constraints. This reduces the security posture of the deployment for as long as debugging is active. Always disable it once you are done.

caution

Toggling remote debugging on or off triggers a redeployment of the application.

Prerequisite

Remote debugging requires direct access to the cluster hosting the target environment. Make sure you have the necessary cluster and environment permissions before proceeding — see User Access to CodeNOW Cluster.

  1. Enable remote debugging on the target deployment from the Remote Debug tab
  2. Download the kubeconfig for the cluster hosting the target environment (linked on the same tab) and note its absolute path
  3. Download or copy the generated mirrord configuration file for your component
  4. Install the mirrord IDE extension (IntelliJ or VS Code) or CLI — see the mirrord documentation for setup instructions
  5. Configure mirrord in your IDE with the downloaded configuration file and the kubeconfig path
  6. Run your local application through mirrord — your IDE debugger attaches as usual
  7. Disable remote debugging on the deployment when done

Scope and Limitations​

  • Remote debugging is configured per deployment (environment). Enabling it affects all pods of that application on that environment.
  • The mirrord configuration generated by CodeNOW is pre-filled with the correct namespace and agent settings for your component. You should not need to modify it for basic use.
  • For non-dev environments, consider the security implications carefully before enabling.