add "podman kube down" command

The "podman kube down" reads in a structured file of
Kubernetes YAML and removes pods based on the Kubernetes kind described in the YAML,
similiar to "podman play kube --down". Users will still be able to use
"podman play kube --down" and "podman kube play --down" to
perform the same function.

Signed-off-by: Niall Crowe <nicrowe@redhat.com>

3 files changed, 51 insertions, 9 deletions

diff --git a/docs/source/markdown/podman-kube-down.1.md b/docs/source/markdown/podman-kube-down.1.md
new file mode 100644
index 000000000..35725043b
--- /dev/null
+++ b/docs/source/markdown/podman-kube-down.1.md
@@ -0,0 +1,43 @@
+% podman-kube-down(1)
+
+## NAME
+podman-kube-down - Remove containers and pods based on Kubernetes YAML
+
+## SYNOPSIS
+**podman kube down** *file.yml|-*
+
+## DESCRIPTION
+**podman kube down** reads a specified Kubernetes YAML file, tearing down pods that were created by the `podman kube play` command via the same Kubernetes YAML file. Any volumes that were created by the previous `podman kube play` command remain intact. If the YAML file is specified as `-`, `podman kube down` reads the YAML from stdin.
+
+## EXAMPLES
+
+Example YAML file `demo.yml`:
+```
+apiVersion: v1
+kind: Pod
+metadata:
+...
+spec:
+  containers:
+  - command:
+    - top
+    - name: container
+      value: podman
+    image: foobar
+...
+```
+
+Remove the pod and containers as described in the `demo.yml` file
+```
+$ podman kube down demo.yml
+52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6
+```
+
+Remove the pod and containers as described in the`demo.yml` file YAML sent to stdin
+```
+$ cat demo.yml | podman kube play -
+52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6
+```
+
+## SEE ALSO
+**[podman(1)](podman.1.md)**, **[podman-kube(1)](podman-kube.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)**, **[podman-generate-kube(1)](podman-generate-kube.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**
diff --git a/docs/source/markdown/podman-kube-play.1.md b/docs/source/markdown/podman-kube-play.1.md
index 25248ce99..b3c385fe9 100644
--- a/docs/source/markdown/podman-kube-play.1.md
+++ b/docs/source/markdown/podman-kube-play.1.md
@@ -1,7 +1,7 @@
 % podman-kube-play(1)
 
 ## NAME
-podman-kube-play - Create containers, pods or volumes based on Kubernetes YAML
+podman-kube-play - Create containers, pods and volumes based on Kubernetes YAML
 
 ## SYNOPSIS
 **podman kube play** [*options*] *file.yml|-*
@@ -30,6 +30,9 @@ Note: If the `:latest` tag is used, Podman will attempt to pull the image from a
 
 Note: The command `podman play kube` is an alias of `podman kube play`, and will perform the same function.
 
+Note: The command `podman kube down` can be used to stop and remove pods or containers based on the same Kubernetes YAML used
+by `podman kube play` to create them.
+
 `Kubernetes PersistentVolumeClaims`
 
 A Kubernetes PersistentVolumeClaim represents a Podman named volume. Only the PersistentVolumeClaim name is required by Podman to create a volume. Kubernetes annotations can be used to make use of the available options for Podman volumes.
@@ -145,11 +148,6 @@ The [username[:password]] to use to authenticate with the registry if required.
 If one or both values are not supplied, a command line prompt will appear and the
 value can be entered.  The password is entered without echo.
 
-#### **--down**
-
-Tears down the pods that were created by a previous run of `kube play`.  The pods are stopped and then
-removed.  Any volumes created are left intact.
-
 #### **--help**, **-h**
 
 Print usage statement
@@ -325,7 +323,7 @@ $ podman kube play demo.yml --network net1:ip=10.89.1.5 --network net2:ip=10.89.
 Please take into account that networks must be created first using podman-network-create(1).
 
 ## SEE ALSO
-**[podman(1)](podman.1.md)**, **[podman-kube(1)](podman-kube.1.md)**, **[podman-network-create(1)](podman-network-create.1.md)**, **[podman-generate-kube(1)](podman-generate-kube.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**
+**[podman(1)](podman.1.md)**, **[podman-kube(1)](podman-kube.1.md)**, **[podman-kube-down(1)](podman-kube-down.1.md)**, **[podman-network-create(1)](podman-network-create.1.md)**, **[podman-generate-kube(1)](podman-generate-kube.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**
 
 ## HISTORY
 December 2018, Originally compiled by Brent Baude (bbaude at redhat dot com)
diff --git a/docs/source/markdown/podman-kube.1.md b/docs/source/markdown/podman-kube.1.md
index f815ffae2..7a6978a2b 100644
--- a/docs/source/markdown/podman-kube.1.md
+++ b/docs/source/markdown/podman-kube.1.md
@@ -14,7 +14,8 @@ file input.  Containers will be automatically started.
 
 | Command  | Man Page                                            | Description                                                                  |
 | -------  | --------------------------------------------------- | ---------------------------------------------------------------------------- |
-| play     | [podman-kube-play(1)](podman-kube-play.1.md)        | Create containers, pods or volumes based on Kubernetes YAML.                         |
+| down     | [podman-kube-down(1)](podman-kube-down.1.md)        | Remove containers and pods based on Kubernetes YAML.                          |
+| play     | [podman-kube-play(1)](podman-kube-play.1.md)        | Create containers, pods and volumes based on Kubernetes YAML.                 |
 
 ## SEE ALSO
-**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-container(1)](podman-container.1.md)**, **[podman-generate(1)](podman-generate.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)**
+**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-container(1)](podman-container.1.md)**, **[podman-generate(1)](podman-generate.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)**, **[podman-kube-down(1)](podman-kube-down.1.md)**