Requirements
- Kubernetes nodes with Linux 5.15 or later, kernel BTF, and cgroup v2.
- A privileged runner container. For a Pod that cannot run privileged, use PMG in Kubernetes instead.
- A runner image that you build. The image needs
bash. It also needssudowhen it does not run as root. - PMG
v0.36.0or later. - A SafeDep Cloud API key and tenant ID, only if you use SafeDep Cloud.
PMG blocks malicious packages without SafeDep Cloud. The cloud policy and the event sync to SafeDep Cloud need the Team or Enterprise plan. See pricing.
docker build, docker run, job containers, and service containers. For all the limits, see Limits.
Set up PMG in a runner pool
Do the setup on one pilot pool first. Move the other pools when the pilot pool works.1
Add PMG to the runner image
Start from the runner image that you build today. Add the
COPY line, the ENTRYPOINT, and the CMD. Keep your own additions as they are.- summerwind ARC
- ARC runner scale sets
CMD holds the runner start command of the base image. pmg-entrypoint.sh starts PMG first. Then it runs the command in CMD. When the Pod stops, pmg-entrypoint.sh stops the runner first and PMG last.If you use another base image, put the runner start command of that image in CMD.If your image has its own entrypoint script, do not move it to CMD. Use one of these two forms:-
Put your script after
pmg-entrypoint.shinENTRYPOINT.pmg-entrypoint.shstarts PMG and then runs your script. -
Keep your own
ENTRYPOINT, and callpmg-entrypoint.shfrom your script. See Start PMG from your own entrypoint script.
2
Add your SafeDep Cloud keys (optional)
Skip this step if you do not use SafeDep Cloud. Without the keys, PMG still blocks malicious packages, and The next step mounts the Secret at
pmg-entrypoint.sh turns off cloud sync.With the keys, PMG applies the policy of your SafeDep Cloud tenant and sends its events to SafeDep Cloud. Create a Secret in the namespace of your runners:/etc/pmg-secret with mode 0400. Keep this mode. With the default mode 0644, every job step can read the keys.pmg-entrypoint.sh reads the keys from the files and gives them only to PMG. The keys are not in the environment of job steps. But a job step with sudo can read the files. The summerwind and GitHub runner images give the runner user sudo with no password. So add the keys only to pools that run workflows you trust.To use another path, set PMG_SECRET_DIR on the runner container.3
Use the image in a pilot pool
Point one pool at the new image. Give the pool its own label, so only the jobs that ask for that label run on it.Keep the other settings of your pool.
- summerwind ARC
- ARC runner scale sets
Use a A runner with
RunnerDeployment with the new image and dockerdWithinRunnerContainer: true:dockerdWithinRunnerContainer: true is privileged.4
Move the other pools
When the pilot pool works, change the image of each other pool. Move one pool at a time.
Start PMG from your own entrypoint script
Use this form if your own entrypoint script must start PMG, and you cannot putpmg-entrypoint.sh in ENTRYPOINT. Add the COPY line from step 1 to the image, and keep your own ENTRYPOINT. On ARC runner scale sets, set command in the values to your own entrypoint script.
In your entrypoint script, add these two lines before your script starts the runner. With summerwind ARC, also put them before your script starts dockerd:
Change the PMG settings
pmg-entrypoint.sh writes the PMG config to /etc/safedep/pmg/config.yml only when no file is at that path. The config that it writes has these settings:
PMG does not route the API server address, because in-cluster
kubectl and helm connect to it by IP address. Such a TLS connection has no server name, and PMG drops a TLS connection without one.
PMG checks the public registries, such as registry.npmjs.org and pypi.org, and the registries in proxy.registries. If your jobs install through a mirror, such as Artifactory or Nexus, add the mirror to proxy.registries in your own config file. PMG does not check a mirror that is not in this list. It only logs the host of the mirror.
PMG also does not route traffic that a job sends to a forward proxy on another port, such as 3128. To route it, add the port with PMG_PROXY_SERVER_ENFORCE_PORTS.
Change one setting
Set aPMG_* environment variable on the runner container. For example, this variable adds the address of an internal service to the destinations that PMG does not route:
$(KUBERNETES_SERVICE_HOST). Do not add the address of a registry or a mirror, because PMG does not check a destination in this list. PMG_PROXY_SERVER_ENFORCE_PORTS sets the enforced ports. For the other variables, see Environment Variables in the PMG configuration reference.
Use your own config file
Put your file at/etc/safedep/pmg/config.yml. pmg-entrypoint.sh then uses your file and does not write one. It always starts PMG with kernel enforcement, so your file needs only your own settings, such as cloud.enabled, block lists and mirrors. For example, this file turns on SafeDep Cloud and adds an npm mirror:
proxy.registries, see Custom Registries in the PMG reference.
Your file has no destinations that PMG does not route. If your jobs use kubectl or helm in the cluster, set PMG_PROXY_SERVER_ENFORCE_SKIP_DESTINATIONS to $(KUBERNETES_SERVICE_HOST)/32, as in Change one setting.
Mount the file from a ConfigMap with subPath:
/etc/safedep/pmg/. You can also add the file to the runner image at that path.
With your own file, pmg-entrypoint.sh does not set cloud.enabled from the Secret. To use SafeDep Cloud, set cloud.enabled: true in your file.
Name the pool in SafeDep Cloud
PMG gives the runner Pods of a pool one endpoint in SafeDep Cloud. It names the endpoint from the namespace and a workload name that it derives from the Pod name. A derived name can change when the pool changes. To keep one name, set the name of the pool and the cluster on the runner container:KUBE_CLUSTER_NAME keeps the pools of two clusters apart. For the other identity variables, see How PMG names the endpoint.
Check the setup (optional)
Run this workflow on the pilot pool.pmg-pilot is the label of the summerwind pool and the name of the scale set.
npm steps must pass. safedep-test-pkg is a harmless package that SafeDep marks as malicious for tests. PMG blocks it, and npm fails with E403.
If a step fails with a certificate error on a registry, the tool in that step does not trust the PMG CA. Point the tool at the file in PMG_CA_BUNDLE.
How PMG Works on ARC Runners in Kubernetes
See the architecture, what PMG covers, and the limits.
Kernel Enforcement on Linux
See how the kernel routes package installs through PMG on a Linux host.
PMG in Kubernetes
Add PMG to the image of a Kubernetes workload that installs packages.
Cloud Policy in PMG
See how PMG applies the policy of your SafeDep Cloud tenant.

