Kubernetes

Native Kubernetes integration of the Polycrate CLI: kubeconfig search paths and inheritance, the debug pod via polycrate k8s debug, and kubeconfig synchronization from the Polycrate API with polycrate k8s sync-kubeconfigs.

Kubernetes

Polycrate offers native Kubernetes integration for managing clusters and for debugging.

Kubeconfig

Polycrate is integrated with Kubernetes and can connect to a cluster via a kubeconfig file.

Kubeconfig search paths

Polycrate searches for a kubeconfig in the following order:

1. Workspace secrets: artifacts/secrets/kubeconfig.yml (recommended for encrypted workspaces)
2. Workspace configuration: path defined in workspace.poly (kubeconfig.filename)
3. Workspace root: kubeconfig.yml in the workspace directory
4. Block artifacts: artifacts/blocks/k8s/kubeconfig.yml (legacy)
5. Global kubeconfig: ~/.kube/config (fallback)

Kubeconfig in workspace.poly

The kubeconfig can be configured in workspace.poly:

# workspace.poly
name: my-workspace

kubeconfig:
  filename: kubeconfig.yml  # path relative to the workspace

Inheriting the kubeconfig from another block

In workspace.poly a block can inherit the kubeconfig from another block:

# workspace.poly
name: my-workspace

blocks:
  # The k8s block generates the kubeconfig
  - name: k8s
    from: registry.my-org.com/blocks/k8s/cluster:1.0.0
    config:
      # ...

  # The my-app block inherits the kubeconfig from the k8s block
  - name: my-app
    from: registry.my-org.com/blocks/k8s/my-app:1.0.0
    kubeconfig:
      from: k8s  # inherits kubeconfig from block "k8s"

This automatically adds an environment variable (KUBECONFIG=path/to/kubeconfig/of/k8s) to the container, so that kubectl, helm and other tools use the correct kubeconfig.

Recommended structure

For encrypted workspaces we recommend:

my-workspace/
├── workspace.poly              # kubeconfig.from is defined here per block instance
├── artifacts/
│   └── secrets/
│       └── kubeconfig.yml      # is encrypted as kubeconfig.yml.age
└── blocks/
    └── my-app/
        └── block.poly          # block definition (no kubeconfig.from here)

Debug pod

With polycrate k8s debug you can start a temporary debug pod in the cluster to work directly in the cluster context.

Usage

polycrate k8s debug

What happens?

1. Create ServiceAccount: a ServiceAccount polycrate-admin is created in the target namespace (if not present)
2. ClusterRoleBinding: the ServiceAccount receives cluster-admin rights
3. Start pod: a pod with the Polycrate image is started
4. Attach: Polycrate automatically attaches to the shell in the pod
5. Cleanup: after the session ends the pod is deleted automatically

Options

Examples

# Debug pod in the default namespace (kube-system)
polycrate k8s debug

# Debug pod in another namespace
polycrate k8s debug -n default

# With explicit workspace path
polycrate k8s debug -w /path/to/workspace

Example session

$ polycrate k8s debug
INFO Starting debug pod polycrate-debug-1701234567 in namespace kube-system
INFO Creating service account polycrate-admin in namespace kube-system
INFO Creating cluster role binding polycrate-admin-cluster-admin
INFO Pod created, waiting for it to be ready...
INFO Pod is running, attaching...

# Now inside the pod:
bash-5.1# kubectl get nodes
NAME           STATUS   ROLES           AGE   VERSION
master-1       Ready    control-plane   30d   v1.28.2
worker-1       Ready    <none>          30d   v1.28.2
worker-2       Ready    <none>          30d   v1.28.2

bash-5.1# helm list -A
NAME            NAMESPACE       REVISION    STATUS      CHART
ingress-nginx   ingress         1           deployed    ingress-nginx-4.8.0
cert-manager    cert-manager    1           deployed    cert-manager-1.13.0

bash-5.1# exit

INFO Debug session ended
INFO Cleaning up debug pod polycrate-debug-1701234567...
INFO Debug pod deleted

Use cases

Tools available in the pod

The debug pod contains all tools from the Polycrate image:

Kubernetes & containers:

• kubectl - Kubernetes CLI
• helm - Helm package manager (+ helm-diff plugin)
• kustomize - Kubernetes configuration
• cilium - Cilium CNI CLI
• argocd - Argo CD CLI
• velero - Kubernetes backup tool
• docker - Docker CLI
• skopeo - Container image management

Backup & encryption:

• restic - Backup tool
• kopia - Backup tool
• age - Modern encryption

Utilities:

• ansible - Configuration management
• git, curl, wget, rsync
• jq, yq - JSON/YAML processing
• psql, mysql - Database clients
• dig, nslookup, telnet - Network tools

See The Polycrate Container for the complete tool list.

Kubeconfig synchronization

The CLI feature is polycrate k8s sync-kubeconfigs: all K8sCluster objects of the Polycrate API (every kind) whose credential contains a kubeconfig. Not loopback-specific, not part of the Kubernetes distro.

polycrate k8s sync-kubeconfigs writes the contexts into the local kubeconfig file (default: ~/.kube/config). Existing entries with the same cluster name are overwritten — the command is idempotent.

Usage

polycrate k8s sync-kubeconfigs

What happens?

1. Fetch clusters: all K8sCluster objects are loaded from the Polycrate API.
2. Load credential: for each cluster the associated credential (incl. kubeconfig content) is fetched.
3. Merge: cluster, AuthInfo and context from the respective kubeconfig are entered into the local kubeconfig under the cluster name (cluster.name).
4. Write: the updated kubeconfig is saved to ~/.kube/config (the directory is created if necessary).

Clusters without a credential or with empty kubeconfig content are skipped and logged.

Example

$ polycrate k8s sync-kubeconfigs
● Fetching K8s clusters from API...
● Found 3 cluster(s)
✓ archenemy
✓ laser24
● skipped: tank-3 (no credential)
● Wrote 2 context(s) to /home/user/.kube/config (1 skipped)

After synchronization the contexts can be used directly with kubectl:

kubectl config get-contexts
kubectl config use-context archenemy
kubectl get nodes

Switching context

polycrate k8s set-context sets the active context in ~/.kube/config:

# Specify the context explicitly
polycrate k8s set-context archenemy

# Without argument: interactive TUI for context selection (since CLI 0.44.2)
polycrate k8s set-context

# Text listing only (no TUI)
polycrate k8s set-context --no-tui

# Then switch quickly between clusters
polycrate k8s set-context archenemy
kubectl get nodes
```

Customizing the target kubeconfig

By default ~/.kube/config is used. The target can be changed in ~/.polycrate/polycrate.yml:

# ~/.polycrate/polycrate.yml
kubeconfig: /path/to/kubeconfig.yml

Workspace file before action runs

sync-kubeconfigs writes to ~/.kube/config (or kubeconfig: in polycrate.yml). Actions inside the container often use a workspace-local file (artifacts/secrets/kubeconfig.yml).

Before an interactive polycrate run the CLI can reconcile this file with the credential of the API cluster assigned to the workspace and offer a download. The flag is historically named --sync-loopback-kubeconfig / sync_loopback_kubeconfig (default true): the implementation currently only matches clusters with API kind=loopback — because their kubeconfig is rotated in the API, not because loopback is a distro variant.

polycrate run my-block install --sync-loopback-kubeconfig=false

No abort gate; skipped in CI; never the global ~/.kube/config fallback. For all cluster kinds: polycrate k8s sync-kubeconfigs.

On the API side the Loopback integration (typing, certificate alerts, metadata) remains — independent of the distro.

See also

• CLI reference - Complete command reference
• The Polycrate Container - Tools available in the container
• API integration - Configuring the Polycrate API