Give Polyaxon sidecars access to run connections

A training job may need a colocated helper to inspect an input, run a local proxy, or publish a readiness signal. If that helper needs the same dataset or secret as the main container, duplicating connection mounts in Kubernetes YAML creates another place for the two configurations to drift.

Since Polyaxon 2.12, user-defined sidecars automatically receive the run's connections and context volumes. Define the connection once on the operation, then give the helper its own command and resources. This is about custom sidecars in run.sidecars; Polyaxon's built-in artifact-collection sidecar is a separate component.

Start with one connection

Suppose review-data is a connection to a read-only persistent volume containing /mnt/review-data/cases.jsonl. An administrator can define it using the volume-claim connection schema:

connections:
  - name: review-data
    kind: volume_claim
    schema:
      mountPath: /mnt/review-data
      volumeClaim: review-data-pvc
      readOnly: true

The PVC and the job must be available in the appropriate agent namespace, and the connection must be available to the project. The file is an input prepared by your team; Polyaxon does not create or label it for this example.

Let a custom sidecar use it

Save this component as inspect-with-sidecar.yaml. The main container checks that the input exists. A small custom sidecar counts its lines for a diagnostic log. Both containers address the same mounted path; the component declares review-data only once.

version: 1.1
kind: component
name: inspect-with-sidecar
run:
  kind: job
  connections: [review-data]
  sidecars:
    - name: input-inspector
      image: busybox:1.36
      command: ["sh", "-c"]
      args:
        - >-
          test -r /mnt/review-data/cases.jsonl
          && wc -l /mnt/review-data/cases.jsonl
      resources:
        requests:
          cpu: "50m"
          memory: "64Mi"
  container:
    image: python:3.12-slim
    command: ["python", "-c"]
    args:
      - |
        from pathlib import Path
        path = Path('/mnt/review-data/cases.jsonl')
        if not path.is_file():
            raise FileNotFoundError(path)
        print('input available:', path.name)
    resources:
      requests:
        cpu: "100m"
        memory: "128Mi"

Submit it with polyaxon run -f inspect-with-sidecar.yaml and inspect both container logs for the operation. A missing file or inaccessible mount should fail this example rather than print a success message. The line count is a diagnostic, not a dataset-quality check. For a real workflow, give the helper a task that genuinely needs to run beside the main container and review its image, permissions, and resource budget.

The sidecars specification says custom sidecars inherit the run's connection volumes, environment variables, secrets, config maps, and context volumes. They do not need a second connections: declaration. The helper remains an additional container in the same Pod; it does not become its own Polyaxon run, gain independent scheduling, or automatically create a tracked dataset artifact.

Remove access when it is unnecessary

Inheritance is convenient when the helper needs the connection, but it also extends access to that container. If a custom sidecar only exposes a local health endpoint or writes a generic log and should not receive the run's connections, set:

plugins:
  sidecar:
    noConnections: true

This setting prevents connection and context-volume inheritance for sidecars. Do not add it to the example above unchanged: input-inspector would no longer have /mnt/review-data/cases.jsonl. First remove the helper's use of that path or give it a different, intentionally scoped design. If two helpers have different access needs, review the effective Pod specification rather than assuming a connection can be selectively inherited by one helper through this global setting.

Connections are only one part of the Pod's access boundary. A custom sidecar can also share network reachability and other Pod-level settings with the main container. Use a reviewed image, avoid copying secrets into logs, and allocate resources for both containers. The Kubernetes sidecar guide covers lifecycle and data-ownership choices when helpers exchange files.

Choose the smallest coupling

Use a sidecar when the helper must run alongside this particular job or service and use its context. Use an initializer for work that finishes before the main process starts; use another Polyaxon operation when the helper needs its own scheduling, retries, or run record. For a sidecar that does belong in the Pod, Polyaxon's connection inheritance removes repetitive mount wiring while noConnections makes the access decision explicit.