Skip to content

Commit

Permalink
[CI:DOCS] man pages: document some --format options
Browse files Browse the repository at this point in the history 
Baby steps toward merging #14046: document a few of the Go format
command-line options.

Signed-off-by: Ed Santiago <[email protected]>
  • Loading branch information
@edsantiago
edsantiago committed Sep 15, 2022
1 parent 50c538b commit 7d1f688
Show file tree
Hide file tree
Showing 7 changed files with 144 additions and 31 deletions.
44 changes: 44 additions & 0 deletions docs/source/markdown/podman-container-inspect.1.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,50 @@ all results in a JSON array. If a format is specified, the given template will b
Format the output using the given Go template.
The keys of the returned JSON can be used as the values for the --format flag (see examples below).

Valid placeholders for the Go template are listed below:

| **Placeholder** | **Description** |
| ----------------- | ------------------ |
| .AppArmorProfile | AppArmor profile (string) |
| .Args | Command-line arguments (array of strings) |
| .BoundingCaps | Bounding capability set (array of strings) |
| .Config ... | Structure with config info |
| .ConmonPidFile | Path to file containing conmon pid (string) |
| .Created | Container creation time (string, ISO3601) |
| .Dependencies | Dependencies (array of strings) |
| .Driver | Storage driver (string) |
| .EffectiveCaps | Effective capability set (array of strings) |
| .ExecIDs | Exec IDs (array of strings) |
| .GraphDriver ... | Further details of graph driver (struct) |
| .HostConfig ... | Host config details (struct) |
| .HostnamePath | Path to file containing hostname (string) |
| .HostsPath | Path to container /etc/hosts file (string) |
| .ID | Container ID (full 64-char hash) |
| .Image | Container image ID (64-char hash) |
| .ImageName | Container image name (string) |
| .IsInfra | Is this an infra container? (string: true/false) |
| .IsService | Is this a service container? (string: true/false) |
| .MountLabel | SELinux label of mount (string) |
| .Mounts | Mounts (array of strings) |
| .Name | Container name (string) |
| .Namespace | Container namespace (string) |
| .NetworkSettings ... | Network settings (struct) |
| .OCIConfigPath | Path to OCI config file (string) |
| .OCIRuntime | OCI runtime name (string) |
| .Path | Path to container command (string) |
| .PidFile | Path to file containing container PID (string) |
| .Pod | Parent pod (string) |
| .ProcessLabel | SELinux label of process (string) |
| .ResolvConfPath | Path to container's resolv.conf file (string) |
| .RestartCount | Number of times container has been restarted (int) |
| .Rootfs | Container rootfs (string) |
| .SizeRootFs | Size of rootfs, in bytes [1] |
| .SizeRw | Size of upper (R/W) container layer, in bytes [1] |
| .State ... | Container state info (struct) |
| .StaticDir | Path to container metadata dir (string) |

[1] This format specifier requires the **--size** option

#### **--latest**, **-l**

Instead of providing the container name or ID, use the last created container. If you use methods other than Podman
Expand Down
10 changes: 10 additions & 0 deletions docs/source/markdown/podman-info.1.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,16 @@ Displays information pertinent to the host, current storage stats, configured co

Change output format to "json" or a Go template.

| **Placeholder** | **Info pertaining to ...** |
| ------------------- | --------------------------------------- |
| .Host ... | ...the host on which podman is running |
| .Plugins ... | ...external plugins |
| .Registries ... | ...configured registries |
| .Store ... | ...the storage driver and paths |
| .Version ... | ...podman version |

Each of the above branch out into further subfields, more than can
reasonably be enumerated in this document.

## EXAMPLES

Expand Down
52 changes: 36 additions & 16 deletions docs/source/markdown/podman-pod-inspect.1.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,22 +18,42 @@ Change the default output format. This can be of a supported type like 'json'
or a Go template.
Valid placeholders for the Go template are listed below:

| **Placeholder** | **Description** |
| ----------------- | ----------------------------------------------------------------------------- |
| .ID | Pod ID |
| .Name | Pod name |
| .State | Pod state |
| .Hostname | Pod hostname |
| .Labels | Pod labels |
| .Created | Time when the pod was created |
| .CreateCgroup | Whether cgroup was created |
| .CgroupParent | Pod cgroup parent |
| .CgroupPath | Pod cgroup path |
| .CreateInfra | Whether infrastructure created |
| .InfraContainerID | Pod infrastructure ID |
| .SharedNamespaces | Pod shared namespaces |
| .NumContainers | Number of containers in the pod |
| .Containers | Pod containers |
| **Placeholder** | **Description** |
|----------------------|---------------------------------------------|
| .BlkioDeviceReadBps | Block I/O Device Read, in bytes/sec |
| .BlkioDeviceWriteBps | Block I/O Device Read, in bytes/sec |
| .BlkioWeight | Block I/O Weight |
| .BlkioWeightDevice | Block I/O Device Weight |
| .CgroupParent | Pod cgroup parent |
| .CgroupPath | Pod cgroup path |
| .Containers | Pod containers |
| .CPUPeriod | CPU period |
| .CPUQuota | CPU quota |
| .CPUSetCPUs | CPU Set CPUs |
| .CPUSetMems | CPU Set Mems |
| .CPUShares | CPU Shares |
| .CreateCgroup | Whether cgroup was created |
| .CreateCommand | Create command |
| .Created | Time when the pod was created |
| .CreateInfra | Whether infrastructure created |
| .Devices | Devices |
| .ExitPolicy | Exit policy |
| .Hostname | Pod hostname |
| .ID | Pod ID |
| .InfraConfig ... | Infra config (contains further fields) |
| .InfraContainerID | Pod infrastructure ID |
| .InspectPodData ... | Nested structure, for experts only |
| .Labels | Pod labels |
| .MemoryLimit | Memory limit, bytes |
| .MemorySwap | Memory swap limit, in bytes |
| .Mounts | Mounts |
| .Name | Pod name |
| .Namespace | Namespace |
| .NumContainers | Number of containers in the pod |
| .SecurityOpts | Security options |
| .SharedNamespaces | Pod shared namespaces |
| .State | Pod state |
| .VolumesFrom | Volumes from |

#### **--latest**, **-l**

Expand Down
8 changes: 4 additions & 4 deletions docs/source/markdown/podman-pod-stats.1.md.in
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,16 +23,16 @@ Valid placeholders for the Go template are listed below:

| **Placeholder** | **Description** |
| --------------- | ------------------ |
| .Pod | Pod ID |
| .BlockIO | Block IO |
| .CID | Container ID |
| .Name | Container Name |
| .CPU | CPU percentage |
| .Mem | Memory percentage |
| .MemUsage | Memory usage |
| .MemUsageBytes | Memory usage (IEC) |
| .Mem | Memory percentage |
| .Name | Container Name |
| .NetIO | Network IO |
| .BlockIO | Block IO |
| .PIDS | Number of PIDs |
| .Pod | Pod ID |

When using a GO template, you may precede the format with `table` to print headers.

Expand Down
11 changes: 11 additions & 0 deletions docs/source/markdown/podman-secret-inspect.1.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,17 @@ Secrets can be queried individually by providing their full name or a unique par

Format secret output using Go template.

| **Placeholder** | **Description** |
| ------------------------ | ----------------------------------------------------------------- |
| .CreatedAt | When secret was created (relative timestamp, human-readable) |
| .ID | ID of secret |
| .Spec | Details of secret |
| .Spec.Driver | Driver info |
| .Spec.Driver.Name | Driver name (string) |
| .Spec.Driver.Options ... | Driver options (map of driver-specific options) |
| .Spec.Name | Name of secret |
| .UpdatedAt | When secret was last updated (relative timestamp, human-readable) |

#### **--help**

Print usage statement.
Expand Down
42 changes: 31 additions & 11 deletions docs/source/markdown/podman-stats.1.md.in
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,17 +30,37 @@ Pretty-print container statistics to JSON or using a Go template

Valid placeholders for the Go template are listed below:

| **Placeholder** | **Description** |
| --------------- | ------------------ |
| .ID | Container ID |
| .Name | Container Name |
| .CPUPerc | CPU percentage |
| .MemUsage | Memory usage |
| .MemUsageBytes | Memory usage (IEC) |
| .MemPerc | Memory percentage |
| .NetIO | Network IO |
| .BlockIO | Block IO |
| .PIDS | Number of PIDs |
| **Placeholder** | **Description** |
|---------------------|--------------------------------------------------|
| .AvgCPU | Average CPU, full precision float |
| .AVGCPU | Average CPU, formatted as a percent |
| .BlockInput | Block Input |
| .BlockIO | Block IO |
| .BlockOutput | Block Output |
| .ContainerID | Container ID, full (untruncated) hash |
| .ContainerStats ... | Nested structure, for experts only |
| .CPU | Percent CPU, full precision float |
| .CPUNano | CPU Usage, total, in nanoseconds |
| .CPUPerc | CPU percentage |
| .CPUSystemNano | CPU Usage, kernel, in nanoseconds |
| .Duration | Same as CPUNano |
| .ID | Container ID, truncated |
| .MemLimit | Memory limit, in bytes |
| .MemPerc | Memory percentage |
| .MemUsage | Memory usage |
| .MemUsageBytes | Memory usage (IEC) |
| .Name | Container Name |
| .NetInput | Network Input |
| .NetIO | Network IO |
| .NetOutput | Network Output |
| .PerCPU | CPU time consumed by all tasks [1] |
| .PIDs | Number of PIDs |
| .PIDS | Number of PIDs (yes, we know it's a dup) |
| .SystemNano | Current system datetime, nanoseconds since epoch |
| .Up | Duration (CPUNano), in human-readable form |
| .UpTime | Same as UpTime |

[1] Cgroups V1 only

When using a GO template, you may precede the format with `table` to print headers.

Expand Down
8 changes: 8 additions & 0 deletions docs/source/markdown/podman-version.1.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,14 @@ OS, and Architecture.

Change output format to "json" or a Go template.

| **Placeholder** | **Description** |
| ------------------- | ------------------------ |
| .Client ... | Version of local podman |
| .Server ... | Version of remote podman |

Each of the above fields branch deeper into further subfields
such as .Version, .APIVersion, .GoVersion, and more.

## Example

A sample output of the `version` command:
Expand Down

0 comments on commit 7d1f688

Please sign in to comment.