Getting Started

Getting Started

Install

pip install squarepeg

This installs the squarepeg console script plus its runtime dependencies: click, kubernetes (the official Python client), and PyYAML.

Working on squarepeg itself instead of just using it? See Development for an editable install from a checkout of the repo.

Prerequisites

• A working kubectl-style kubeconfig — squarepeg uses the exact same resolution kubectl does ($KUBECONFIG, then ~/.kube/config, current context). If kubectl get pods works, squarepeg will too. (Running squarepeg itself as a container, with no kubeconfig at all? It falls back to the pod's own service account — see Execution Lifecycle → Connect to the cluster.)
• Permission in your target namespace to create/watch/delete Pods (and Jobs, if you use --mode job).

Your first run

squarepeg run alpine echo "hello from a pod"

squarepeg will:

1. Print which kubeconfig context and namespace it's using (to stderr, unless --quiet).
2. Build and create a Pod manifest.
3. Wait for the container to start, failing fast if the image can't be pulled.
4. Stream the container's stdout/stderr to your terminal as it runs.
5. Wait for the container to terminate.
6. Delete the Pod.
7. Exit with the container's exit code.

A few things to try immediately

See what would be created without touching the cluster:

squarepeg run --dry-run --cpus 0.5 -m 512m -e FOO=bar alpine echo hi

This prints the exact Pod manifest YAML — no cluster connection required at all. See Execution Lifecycle for details.

Run as a Job instead of a Pod:

squarepeg run --mode job alpine echo hi

Keep the resource around afterwards for debugging:

squarepeg run --keep --name debug-me alpine sh -c "exit 7"
kubectl describe pod debug-me

See your fully resolved config (useful once you have config files layered):

squarepeg config show

Next steps

• CLI Reference for the full flag list.
• Configuration once you want to stop repeating --cpus/--memory/namespace/etc. on every invocation, or need to set Kubernetes fields squarepeg has no dedicated flag for (node selectors, tolerations, service accounts, PVCs, ...).
• Docker Compatibility to see exactly which docker run flags are supported, and what to do instead for the ones that aren't.