Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Pratyay360/podman-ts/llms.txt

Use this file to discover all available pages before exploring further.

KubeManager bridges Podman and Kubernetes by letting you generate Kubernetes YAML from running containers and pods, apply YAML workloads back into Podman, and produce systemd unit files for any named resource. It is accessible via client.kube on any PodmanClient instance.
KubeManager does not extend Manager and has no list() or get() method — it is a stateless operation surface, not a resource manager.

​
KubeManager methods

​
generate

generate(names: string | string[], options?: GenerateKubeOptions): Promise<string>
Generate a Kubernetes YAML manifest from one or more Podman containers or pods. Returns the YAML as a string, ready to write to a file or pass directly to apply() or play().
​
names
string | string[]
required
One or more container or pod names/IDs to include in the generated YAML.
​
options.pods
boolean
Include the pod(s) that own the named containers in the output.
​
options.replicas
number
Set the replica count when the generated resource type is Deployment.
​
options.service
boolean
Append a Kubernetes Service object alongside the workload resource.
​
options.type
string
Kubernetes resource type to generate (e.g. "Deployment", "Job"). Defaults to the Podman API’s built-in choice.
​
options.noTrunc
boolean
Do not truncate container/pod IDs in the generated output.

​
generateSystemd

generateSystemd(name: string, options?: GenerateSystemdOptions): Promise<Record<string, string>>
Generate systemd unit files for a named container or pod. Returns a record mapping unit file names to their text content (e.g. { "container-myapp.service": "..." }).
​
name
string
required
Container or pod name/ID.
​
options.useName
boolean
Use the container/pod name rather than its ID in the generated unit name.
​
options.new
boolean
Generate a unit that creates a new container on start instead of restarting an existing one.
​
options.noHeader
boolean
Omit the comment header from the generated unit file.
​
options.startTimeout
number
TimeoutStartSec value in seconds.
​
options.stopTimeout
number
TimeoutStopSec value in seconds.
​
options.restartPolicy
string
Systemd Restart directive (e.g. "on-failure", "always", "no").
​
options.containerPrefix
string
Prefix for container unit names. Defaults to "container".
​
options.podPrefix
string
Prefix for pod unit names. Defaults to "pod".
​
options.separator
string
Separator between the prefix and the container/pod name (e.g. "-" or "_").
​
options.wants
string[]
Additional Wants= dependencies to add to the [Unit] section.
​
options.after
string[]
Additional After= ordering dependencies.
​
options.requires
string[]
Additional Requires= hard dependencies.
​
options.additionalEnvVariables
string[]
Extra Environment= lines to inject (e.g. ["MY_VAR=value"]).

​
apply

apply(yaml: string, options?: KubeApplyOptions): Promise<Record<string, unknown>>
Apply a Kubernetes YAML workload to a Podman service or a live Kubernetes cluster (when a kubeconfig is provided). The YAML is sent as the request body.
​
yaml
string
required
YAML content as a string.
​
options.caCertFile
string
Path to a CA certificate file used for TLS verification against the target cluster.
​
options.kubeConfig
string
Path to a kubeconfig file. When set, the YAML is applied to the configured Kubernetes cluster instead of the local Podman service.
​
options.namespace
string
Kubernetes namespace to apply the resources into.
​
options.file
string
Path at which to save the YAML file on the server before applying.
​
options.serviceAccount
string
Service account name to use when applying the resources.

​
play

play(yaml: string, options?: PlayKubeOptions): Promise<Record<string, unknown>>
Create pods and containers from a Kubernetes YAML file using the local Podman engine (equivalent to podman play kube). Returns a summary of created resources.
​
yaml
string
required
YAML content as a string.
​
options.annotations
Record<string, string>
Annotations to attach to created pods.
​
options.authFile
string
Path to a registry auth file for pulling images.
​
options.network
string[]
Network mode or network names to attach pods to.
​
options.replace
boolean
Tear down and recreate pods that already exist.
​
options.start
boolean
Start pods immediately after creation (default behaviour when omitted).
​
options.tlsVerify
boolean
Verify TLS certificates when pulling images.
​
options.configMaps
string[]
Paths to ConfigMap YAML files to make available during play.
​
options.build
boolean
Build images from Containerfiles referenced in the YAML before running.
​
options.quiet
boolean
Suppress image pull progress output.
​
options.logDriver
string
Log driver for created containers (e.g. "journald", "k8s-file").

​
playDown

playDown(yaml: string, options?: { force?: boolean }): Promise<Record<string, unknown>>
Remove the pods and containers that were created by a previous play() call. Pass the same YAML that was used for play(). Returns a summary of removed resources.
​
yaml
string
required
The same YAML string that was passed to play().
​
options.force
boolean
Force removal even if containers are still running.

​
Code examples

​
Generate Kubernetes YAML from a container

import { PodmanClient } from "@pratyay360/podman-ts";

const client = new PodmanClient();

const yaml = await client.kube.generate("my-nginx", {
  service: true,
  type: "Deployment",
  replicas: 3,
});

console.log(yaml);
// Write to disk if needed:
await Bun.write("my-nginx.yaml", yaml);

​
Generate systemd units for a container

const units = await client.kube.generateSystemd("my-nginx", {
  useName: true,
  new: true,
  restartPolicy: "on-failure",
  stopTimeout: 10,
});

for (const [filename, content] of Object.entries(units)) {
  console.log(`--- ${filename} ---`);
  console.log(content);
  await Bun.write(`/etc/systemd/user/${filename}`, content);
}
Set useName: true so the generated unit file is named after the container (e.g. container-my-nginx.service) rather than its ID, which changes every time the container is recreated.

​
Apply a YAML workload to Podman

import { readFileSync } from "fs";

const yaml = readFileSync("./my-nginx.yaml", "utf8");

const result = await client.kube.apply(yaml, {
  namespace: "default",
});

console.log("Applied:", result);

​
Apply YAML to a Kubernetes cluster

const result = await client.kube.apply(yaml, {
  kubeConfig: "/home/user/.kube/config",
  namespace: "production",
  caCertFile: "/etc/ssl/certs/cluster-ca.crt",
});

console.log("Applied to cluster:", result);

​
Play a Kubernetes YAML file locally

const yaml = await Bun.file("./my-app.yaml").text();

const result = await client.kube.play(yaml, {
  replace: true,
  tlsVerify: true,
  configMaps: ["./configmap.yaml"],
});

console.log("Resources created:", result);

​
Tear down resources from a previous play

const yaml = await Bun.file("./my-app.yaml").text();

// Uses the same YAML that was passed to play()
const result = await client.kube.playDown(yaml, { force: true });

console.log("Resources removed:", result);

Build docs developers (and LLMs) love

Get started for freeTalk to us