Package: docker-entrypoint
Docker Entrypointdocker-entrypointis a basic utility to proxy a container's normal entrypoint. This avoid a few pitfalls in developing and debugging processes running in kubernetes pods, namely:Starting/stopping debugging sessions without restarting the container, and subsequently losing state of the filesystem.Changing environment variables without restarting the container, so environment changes can be made without redeploying to kubernetes.How to Installdocker-entrypointcan be installed in your docker image viapip:pipinstalldocker-entrypointSince there is no mechanism for injecting the entrypoint script into your image, you'll likely want to installdocker-entrypointat image build time (i.e. in your Dockerfile). Here's a basic, incomplete example:FROMpython:3.7...# Install via pip:RUNpipinstalldocker-entrypoint# Continue as normal:WORKDIR/path/to/my/appENTRYPOINT["python","main.py"]How to UseRunning your process throughentrypointdocker-entrypointwill install anentrypointdriver globally which accepts your normal entrypoint command as arguments.root@my-pod:/path/to/my/app#entrypointpythonmain.pySinceentrypointmust be running as PID 1 in the pod's container to have any value, we must modify the configured entrypoint for the container at launch. There are two options to do so.Option one: Kubernetes Container SpecSpecify an alternate entrypoint in the container spec for your pod/deploy/statefulset manifest:spec:containers:-name:my-appcommand:["entrypoint"]args:["python","main.py"]Option two: DockerfileENTRYPOINTUseentrypointas your entrypoint in the Dockerfile itself:FROMpython:3.7...# Install via pip:RUNpipinstalldocker-entrypoint# Note the ENTRYPOINT change:WORKDIR/path/to/my/appENTRYPOINT["entrypoint","python","main.py"]Starting a debug sessionSimply import theDebuggerclass, make an instance, and callDebugger.start()fromentrypoint.debugimportDebuggerdbg=Debugger()dbg.start()# Will wait for debugger to attach, depending on configuration.docker-entrypointincludes a module that supports remote debugging for VS Code and PyCharm. TheDebuggerclass currently makes several assumptions:Environment VariableValid OptionsDefaultDEBUGGER_ENABLEDtrue,falsefalseDEBUGGER_ADDRESSany hostname/IPlocalhostDEBUGGER_EDITORvscode,pycharmvscodeDEBUGGER_WAITtrue,falsetrueThese values are pulled from a "dotenv" file located at/tmp/.env. This is hardcoded. Additionally, the ports used for forwarding and reverse forwarding are hardcoded to9000and9001, respectively. When launching port-forwarding commands, be sure to use these ports for the pod-side binding.Get the name of your pod:POD_NAME=$(kubectlgetpods-lrelease=my-app--field-selectorstatus.phase=Running-ojsonpath={.items[0].metadata.name})Restart your process. This doesnotrestart your container, only the process being managed byentrypoint.kubectlexec$POD_NAME--bash-c"kill -HUP 1"Environment variables are loaded from the in-pod.envfile prior to each launch of the debugger, so they can be updated on-demand from a local.envfile. Simply copy your local .env file into the pod and restart your process. Again, this doesnotrestart the container.kubectlcp.env$POD_NAME:/tmp/.env
kubectlexec$POD_NAME--bash-c"kill -HUP 1"For IDEs that create a debug server and require the remote process to attach to it (i.e. PyCharm),Debugger.start()will wait untilSIGUSR1OS signal is received. Start your debug server in your IDE and send your pod a signal when its waiting for a connection.kubectlexec$POD_NAME--bash-c"kill -USR1 1"Module Breakdownmain.pyDefines anasyncioloop for managing the process proxied byentrypoint. This includes forwarding relevant signals and restarting your process when it exits. The following table documents the signals that are currently handled:SignalOutcomeSIGTERMCausesentrypointto stop managing and exit. This restarts the container as normal.SIGINTCausesentrypointto stop managing and exit. This restarts the container as normal.SIGHUPSignalentrypointto forwardSIGTERMto process, and then spawns another process.SIGUSR1Signalentrypointto continue with establishing a debugging session. Only necessary whenDEBUGGER_EDITOR=pycharm.debug.pyDefines aDebuggerclass that will start a debugging session based on environment variables (as documentedhere).Debugger.__init__()Loads environment variables intoos.environfrom a dotenv file located at/tmp/.env, and then parses these values for use in a debugging session.Debugger.start()Starts a debugging session.