https://github.com/crossplane/inspector-sidecar
https://github.com/crossplane/inspector-sidecar
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/crossplane/inspector-sidecar
- Owner: crossplane
- License: apache-2.0
- Created: 2026-01-21T16:04:59.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-30T11:57:54.000Z (5 months ago)
- Last Synced: 2026-01-31T04:09:19.391Z (5 months ago)
- Language: Go
- Size: 31.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Pipeline Inspector Sidecar
A minimal reference implementation of a sidecar container for Crossplane that captures
function pipeline execution data (requests and responses) and logs them to stdout.
The full design of this feature can be found in the [design doc](https://github.com/crossplane/crossplane/blob/main/design/one-pager-pipeline-inspector.md).
## Features
- Captures `RunFunctionRequest` and `RunFunctionResponse` data for each function invocation
- Supports JSON and human-readable text output formats
- Correlates pipeline steps using trace IDs, span IDs, and step indices
- Runs as a non-root user in a minimal distroless container
## CLI Flags
| Flag | Environment Variable | Default | Description |
|------|---------------------|---------|-------------|
| `--socket-path` | `PIPELINE_INSPECTOR_SOCKET` | `/var/run/pipeline-inspector/socket` | Unix socket path to listen on |
| `--format` | - | `json` | Output format (`json` or `text`) |
| `--max-recv-msg-size` | `MAX_RECV_MSG_SIZE` | `4194304` (4MB) | Maximum gRPC receive message size in bytes |
| `--shutdown-timeout` | `SHUTDOWN_TIMEOUT` | `5s` | Graceful shutdown timeout |
## Usage
This repository publishes release images to
`xpkg.crossplane.io/crossplane/inspector-sidecar`. This image can be
included as a sidecar container for Crossplane through the Helm chart's values.
```yaml
# Example:
# helm upgrade --install crossplane crossplane/crossplane \
# -n crossplane-system --create-namespace \
# -f pipeline-inspector-values.yaml
args:
- --enable-pipeline-inspector
- --pipeline-inspector-socket=/var/run/pipeline-inspector/socket
extraVolumesCrossplane:
- name: pipeline-inspector-socket
emptyDir: {}
extraVolumeMountsCrossplane:
- name: pipeline-inspector-socket
mountPath: /var/run/pipeline-inspector
sidecarsCrossplane:
- name: pipeline-inspector
image: xpkg.crossplane.io/crossplane/inspector-sidecar:latest
args:
- --format=json
# Increase if your function payloads exceed 4MB
# - --max-recv-msg-size=8388608
volumeMounts:
- name: pipeline-inspector-socket
mountPath: /var/run/pipeline-inspector
resources:
requests:
cpu: 10m
memory: 64Mi
limits:
cpu: 100m
memory: 128Mi
```
## Output Formats
### JSON Format (default)
The meta field contains either `compositionMeta` (for XR reconciliation) or `operationMeta` (for standalone operations):
```json
{"meta":{"compositionMeta":{"compositeResourceApiVersion":"example.org/v1","compositeResourceKind":"XDatabase","compositeResourceName":"my-db","compositeResourceNamespace":"default","compositeResourceUid":"abc-123","compositionName":"my-composition"},"functionName":"function-patch-and-transform","iteration":0,"spanId":"span-456","stepIndex":0,"timestamp":"2026-01-15T10:30:00Z","traceId":"trace-789"},"payload":{...},"type":"REQUEST"}
```
```json
{"meta":{"operationMeta":{"operationName":"reconcile","operationUid":"op-uid-123"},"functionName":"function-patch-and-transform","iteration":0,"spanId":"span-456","stepIndex":0,"timestamp":"2026-01-15T10:30:00Z","traceId":"trace-789"},"payload":{...},"type":"REQUEST"}
```
### Text Format
Use `--format=text` for human-readable output. The output adapts based on the context type:
#### Composition Context (XR reconciliation)
```
=== REQUEST ===
XR: example.org/v1/XDatabase (my-db)
XR UID: abc-123
XR NS: default
Composition: my-composition
Step: my-step (index 0, iteration 0)
Function: function-patch-and-transform
Trace ID: trace-789
Span ID: span-456
Timestamp: 2026-01-15T10:30:00.000Z
Payload:
apiVersion: apiextensions.crossplane.io/v1
...
```
#### Operation Context (standalone operations)
```
=== REQUEST ===
Operation: reconcile
Op UID: op-uid-123
Step: my-step (index 0, iteration 0)
Function: function-patch-and-transform
Trace ID: trace-789
Span ID: span-456
Timestamp: 2026-01-15T10:30:00.000Z
Payload:
...
```
## Building
```bash
# Build locally
go build -o inspector-sidecar .
# Build Docker image
docker build -t inspector-sidecar .
```
## Testing
```bash
go test ./...
```