postman/postman-kubernetes-listener repository overview

⁠Postman K8s Listener Service

The Postman Kubernetes Listener Service watches Kubernetes deployments in your cluster and automatically reports them to Postman's Service Inventory⁠. This gives your team real-time visibility into what's deployed, where, and which version.

⁠Prerequisites

• A Kubernetes cluster (1.24+)
• Helm⁠ 3.x
• A Postman API key with Service Inventory access

⁠Choosing a deployment path

The chart supports three ways to provide the Postman API key. Pick one based on how you already manage secrets:

⁠Install

The chart is published as an OCI artifact on Docker Hub at oci://registry-1.docker.io/postman/postman-kubernetes-listener. Pin a specific version on every install with --version <x.y.z>.

Discover the available chart versions:

helm show chart oci://registry-1.docker.io/postman/postman-kubernetes-listener

⁠Install with an existing Kubernetes secret

The recommended way to authenticate with the Postman servers is using an API key stored in a Kubernetes secret:

kubectl create secret generic postman-api-key \
  --from-literal=api-key=YOUR_POSTMAN_API_KEY

helm install k8s-listener \
  oci://registry-1.docker.io/postman/postman-kubernetes-listener \
  --version <chart-version> \
  --set postman.apiKeyExistingSecret=postman-api-key \
  --set listener.clusterName=my-cluster \
  --set listener.region=us-east-1 \
  --set listener.environmentName=production

⁠Install with External Secrets Operator

If you already run External Secrets Operator (ESO)⁠, the chart can create an ExternalSecret that syncs the API key from your remote secret store (Vault, AWS Secrets Manager, GCP Secret Manager, etc.).

Prerequisites and pitfalls:

• ESO must be installed in your cluster (CRDs available).
• The chart uses a ClusterSecretStore (cluster-scoped). Set its name via global.externalSecretStore.
• The remote secret in your store must have a field named value — the chart reads property: value from the remote reference.
• The chart creates a Kubernetes Secret named <baseName>-api-key with key api-key, refreshed every 10 minutes.

helm install k8s-listener \
  oci://registry-1.docker.io/postman/postman-kubernetes-listener \
  --version <chart-version> \
  --set postman.apiKeyExternalSecret=secret/data/postman/api-key \
  --set global.externalSecretStore=my-cluster-secret-store \
  --set listener.clusterName=my-cluster \
  --set listener.region=us-east-1 \
  --set listener.environmentName=production

⁠Install with an inline API key

helm install k8s-listener \
  oci://registry-1.docker.io/postman/postman-kubernetes-listener \
  --version <chart-version> \
  --set postman.apiKey=YOUR_POSTMAN_API_KEY \
  --set listener.clusterName=my-cluster \
  --set listener.region=us-east-1 \
  --set listener.environmentName=production

⁠Configuration reference

All configuration is done through Helm values. You can pass them with --set, or create a values.yaml file and use -f:

helm install k8s-listener \
  oci://registry-1.docker.io/postman/postman-kubernetes-listener \
  --version <chart-version> \
  -f my-values.yaml

⁠Postman API (Required)

Exactly one of apiKey, apiKeyExistingSecret, or apiKeyExternalSecret should be set.

⁠Listener Settings

⁠Global

⁠Resources

⁠Pod security

The chart's defaults satisfy the Pod Security Standards "restricted" profile (non-root, read-only root filesystem, all capabilities dropped, no privilege escalation, RuntimeDefault seccomp). Override only if your cluster needs different settings.

⁠Other

⁠Listener overrides

listener.overrides is a free-form map of environment variables passed through to the container. Use it to tune listener behaviors that aren't exposed as first-class Helm values.

Example:

listener:
  overrides:
    LISTENER_LABEL_SELECTOR: app.postman.io/k8s-app
    LISTENER_VERSION_LABEL_NAME: app.kubernetes.io/version
    LISTENER_LABEL_PATTERN: "^app\\..*"

To watch a specific list of namespaces, use the dedicated listener.namespaces value rather than setting LISTENER_NAMESPACES here — the chart already wires the dedicated value into the container.

⁠Verifying the installation

Check that the pod is running:

kubectl get pods -l app.kubernetes.io/name=postman-kubernetes-listener

View logs:

kubectl logs -l app.kubernetes.io/name=postman-kubernetes-listener -f

Check the health endpoint. The chart does not ship a Service, so port-forward directly to the pod:

POD=$(kubectl get pod -l app.kubernetes.io/name=postman-kubernetes-listener \
  -o jsonpath='{.items[0].metadata.name}')
kubectl port-forward "pod/$POD" 8081:8081
curl http://localhost:8081/actuator/health

⁠Verifying the published artifacts

Every public release publishes the following supply-chain artifacts to the OCI registry alongside the image:

• A cosign⁠ keyless signature (Sigstore OIDC, issued by GitHub Actions)
• An SBOM in SPDX-JSON format
• A build provenance attestation

⁠Verify the cosign signature

cosign verify \
  --certificate-identity-regexp "https://github.com/postman-eng/postman-kubernetes-listener-pub/.+" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  index.docker.io/postman/postman-kubernetes-listener:<tag>

⁠Verify the SBOM and build provenance

Both the SBOM and the build provenance attestation can be verified with the GitHub CLI:

gh attestation verify \
  oci://index.docker.io/postman/postman-kubernetes-listener:<tag> \
  --owner postman-eng

To download and inspect the SBOM itself, use cosign download attestation or oras discover.

⁠How it works

The Postman Kubernetes Listener Service connects to the Kubernetes API server using its service account credentials and opens a watch stream⁠ on Deployment resources. When a deployment is created, updated, or deleted, the service extracts relevant metadata (name, namespace, labels, version, replica count) and reports it to Postman's Service Inventory API.

Namespace filters can be used to control which deployments are tracked. Only deployments in namespaces matching your configured listener.namespaces will be reported.

⁠Ports

⁠RBAC permissions

The service requires read-only access to Deployment resources:

• API Group: apps
• Resources: deployments
• Verbs: get, list, watch

⁠Upgrading

helm upgrade k8s-listener \
  oci://registry-1.docker.io/postman/postman-kubernetes-listener \
  --version <chart-version> \
  --reuse-values

⁠Uninstalling

helm uninstall k8s-listener

⁠Troubleshooting

Pod CrashLoopBackOff with auth error — The API key is missing or the secret has the wrong key name. The chart expects the secret to have a key named api-key. Verify with kubectl get secret <name> -o yaml.

Pod can't list deployments — The ClusterRole/Binding may not be applied, or another policy is blocking it. Verify with:

kubectl auth can-i list deployments \
  --as=system:serviceaccount:<namespace>:<service-account>

Nothing showing up in Service Inventory — Either your listener.namespaces filter excludes the workloads you expect to see, or your Deployments don't match the default LISTENER_LABEL_SELECTOR (app.postman.io/api-catalog). Set postman.apiHttpLogLevel=TRACE to log outbound calls and confirm what's being sent.