Add configuration and documentation for debugging remote instance in the cluster

CHANGELOG.md

@@ -12,6 +12,7 @@ Write the date in place of the "Unreleased" in the case a new version is release
   have been removed. These were used internally by the server and should
   not affect user code.
 - Publish Container image and Helm chart only during a tagged release.
+- Enable and document remote debugging with Helm
 
 ## v0.1.0-b17 (2024-01-29)
 

Dockerfile

@@ -51,6 +51,8 @@ ENV PATH="$VIRTUAL_ENV/bin:$PATH"
 COPY --from=builder $VIRTUAL_ENV $VIRTUAL_ENV
 # We want cURL and httpie so healthchecks can be performed within the container
 RUN apt-get update && apt-get install -y curl httpie
+# Install debugpy to allow us to use remote debugging
+RUN pip install debugpy
 
 WORKDIR /deploy
 RUN mkdir /deploy/config

docs/source/how-to/helm.md

@@ -96,3 +96,54 @@ tiled:
 
 Additional templates to be deployed alongside the tiled server can be defined- for
 example the SealedSecret defined above.
+
+## Remote debugging
+
+The helm chart defines values for enabling debugpy breakpoints inside of the deployed
+container, for use in the situation that cluster infrastructure is required for
+debugging: e.g. checking the value of headers passed from authentication providers.
+
+```yaml
+debug:
+  # Whether the container should start in debug mode
+  enabled: true
+  # Whether to suspend the process until a debugger connects
+  suspend: true
+  # Port to listen for the debugger on
+  port: 5678
+```
+
+To connect to the port of the pod on the cluster, you can use `kubectl port forward` to
+forward your local machine's port 5678 to the container's:
+
+```sh
+$ kubectl get pods
+NAME                            READY   STATUS    RESTARTS        AGE
+tiled-cbbc9df58-hjm7q           1/1     Running   0 (5d19h ago)   5d19h
+$ kubectl port forward pod/tiled-cbbc9df58-hjm7q 5678:5678
+Forwarding from 127.0.0.1:5678 -> 5678
+```
+
+Check out the deployed version of tiled and configure your IDE to attach to a remote
+debugpy process: the following is a launch configuration from VSCode `launch.json`.
+Note that the version of python and port may need to be changed. With this
+configuration, `"justMyCode": False` was required for breakpoints to be active.
+
+```json
+{
+    "name": "Python Debugger: Remote Attach",
+    "type": "debugpy",
+    "request": "attach",
+    "connect": {
+        "host": "localhost",
+        "port": 5678
+    },
+    "pathMappings": [
+        {
+            "localRoot": "${workspaceFolder}/tiled",
+            "remoteRoot": "/opt/venv/lib/python3.12/site-packages/tiled"
+        }
+    ],
+    "justMyCode": false
+}
+```

helm/tiled/templates/deployment.yaml

@@ -32,6 +32,28 @@ spec:
         {{- toYaml .Values.podSecurityContext | nindent 8 }}
       containers:
         - name: {{ .Chart.Name }}
+          command:
+          - "python"
+          {{- if .Values.debug.enabled}}
+          - "-Xfrozen_modules=off"
+          - "-m"
+          - "debugpy"
+          {{- if .Values.debug.suspend }}
+          - "--wait-for-client"
+          {{- end }}
+          - "--listen"
+          - "0.0.0.0:{{ .Values.debug.port }}"
+          {{- end }}
+          - "-m"
+          args:
+          - "tiled"
+          - "serve"
+          - "config"
+          - "--host"
+          - "0.0.0.0"
+          - "--port"
+          - "8000"
+          - "--scalable"
           securityContext:
             {{- toYaml .Values.securityContext | nindent 12 }}
           image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"

helm/tiled/values.yaml

@@ -13,6 +13,15 @@ config:
         writable_storage: "/storage/data"
         init_if_not_exists: true
 
+# Use `kubectl port forward` to access from your machine
+debug:
+  # Whether the container should start in debug mode
+  enabled: false
+  # Whether to suspend the process until a debugger connects
+  suspend: false
+  # Port to listen for the debugger on
+  port: 5678
+
 # This will set the replicaset count more information can be found here: https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/
 replicaCount: 1