From d856fb43e11b3a4a93b423d330ce3435afddde4b Mon Sep 17 00:00:00 2001 From: Niall Crowe Date: Thu, 4 Aug 2022 09:02:54 +0100 Subject: Add "podman kube generate" command "podman kube generate" creates Kubernetes YAML from Podman containers, pods or volumes. Users will still be able to use "podman generate kube" as an alias of "kube generate". Signed-off-by: Niall Crowe --- docs/source/markdown/links/podman-generate-kube.1 | 1 + docs/source/markdown/podman-generate-kube.1.md | 219 ---------------------- docs/source/markdown/podman-generate.1.md | 2 +- docs/source/markdown/podman-kube-down.1.md | 2 +- docs/source/markdown/podman-kube-generate.1.md | 219 ++++++++++++++++++++++ docs/source/markdown/podman-kube-play.1.md.in | 7 +- docs/source/markdown/podman-kube.1.md | 14 +- 7 files changed, 233 insertions(+), 231 deletions(-) create mode 100644 docs/source/markdown/links/podman-generate-kube.1 delete mode 100644 docs/source/markdown/podman-generate-kube.1.md create mode 100644 docs/source/markdown/podman-kube-generate.1.md (limited to 'docs/source') diff --git a/docs/source/markdown/links/podman-generate-kube.1 b/docs/source/markdown/links/podman-generate-kube.1 new file mode 100644 index 000000000..f726a4222 --- /dev/null +++ b/docs/source/markdown/links/podman-generate-kube.1 @@ -0,0 +1 @@ +.so man1/podman-kube-generate.1 diff --git a/docs/source/markdown/podman-generate-kube.1.md b/docs/source/markdown/podman-generate-kube.1.md deleted file mode 100644 index bd7bc711c..000000000 --- a/docs/source/markdown/podman-generate-kube.1.md +++ /dev/null @@ -1,219 +0,0 @@ -% podman-generate-kube(1) -## NAME -podman-generate-kube - Generate Kubernetes YAML based on containers, pods or volumes - -## SYNOPSIS -**podman generate kube** [*options*] *container...* | *pod...* | *volume...* - -## DESCRIPTION -**podman generate kube** will generate Kubernetes YAML (v1 specification) from Podman containers, pods or volumes. Regardless of whether -the input is for containers or pods, Podman will always generate the specification as a Pod. The input may be in the form -of one or more containers, pods or volumes names or IDs. - -`Podman Containers or Pods` - -Volumes appear in the generated YAML according to two different volume types. Bind-mounted volumes become *hostPath* volume types and named volumes become *persistentVolumeClaim* volume types. Generated *hostPath* volume types will be one of three subtypes depending on the state of the host path: *DirectoryOrCreate* when no file or directory exists at the host, *Directory* when host path is a directory, or *File* when host path is a file. The value for *claimName* for a *persistentVolumeClaim* is the name of the named volume registered in Podman. - -Potential name conflicts between volumes are avoided by using a standard naming scheme for each volume type. The *hostPath* volume types are named according to the path on the host machine, replacing forward slashes with hyphens less any leading and trailing forward slashes. The special case of the filesystem root, `/`, translates to the name `root`. Additionally, the name is suffixed with `-host` to avoid naming conflicts with *persistentVolumeClaim* volumes. Each *persistentVolumeClaim* volume type uses the name of its associated named volume suffixed with `-pvc`. - -Note that if an init container is created with type `once` and the pod has been started, the init container will not show up in the generated kube YAML as `once` type init containers are deleted after they are run. If the pod has only been created and not started, it will be in the generated kube YAML. -Init containers created with type `always` will always be generated in the kube YAML as they are never deleted, even after running to completion. - -*Note*: When using volumes and generating a Kubernetes YAML for an unprivileged and rootless podman container on an **SELinux enabled system**, one of the following options must be completed: - * Add the "privileged: true" option to the pod spec - * Add `type: spc_t` under the `securityContext` `seLinuxOptions` in the pod spec - * Relabel the volume via the CLI command `chcon -t container_file_t -R ` - -Once completed, the correct permissions will be in place to access the volume when the pod/container is created in a Kubernetes cluster. - -Note that the generated Kubernetes YAML file can be used to re-run the deployment via podman-play-kube(1). - -## OPTIONS - -#### **--filename**, **-f**=*filename* - -Output to the given file, instead of STDOUT. If the file already exists, `generate kube` will refuse to replace it and return an error. - -#### **--service**, **-s** - -Generate a Kubernetes service object in addition to the Pods. Used to generate a Service specification for the corresponding Pod output. In particular, if the object has portmap bindings, the service specification will include a NodePort declaration to expose the service. A -random port is assigned by Podman in the specification. - -## EXAMPLES - -Create Kubernetes Pod YAML for a container called `some-mariadb`. -``` -$ sudo podman generate kube some-mariadb -# Save the output of this file and use kubectl create -f to import -# it into Kubernetes. -# -# Created with podman-0.11.2-dev -apiVersion: v1 -kind: Pod -metadata: - creationTimestamp: 2018-12-03T19:07:59Z - labels: - app: some-mariadb - name: some-mariadb-libpod -spec: - containers: - - command: - - docker-entrypoint.sh - - mysqld - env: - - name: HOSTNAME - - name: GOSU_VERSION - value: "1.10" - - name: GPG_KEYS - value: "199369E5404BD5FC7D2FE43BCBCB082A1BB943DB \t177F4010FE56CA3336300305F1656F24C74CD1D8 - \t430BDF5C56E7C94E848EE60C1C4CBDCDCD2EFD2A \t4D1BB29D63D98E422B2113B19334A25F8507EFA5" - - name: MARIADB_MAJOR - value: "10.3" - - name: MARIADB_VERSION - value: 1:10.3.10+maria~bionic - - name: MYSQL_ROOT_PASSWORD - value: x - image: quay.io/baude/demodb:latest - name: some-mariadb - ports: - - containerPort: 3306 - hostPort: 36533 - resources: {} - securityContext: - capabilities: - drop: - - CAP_MKNOD - - CAP_NET_RAW - - CAP_AUDIT_WRITE - tty: true -status: {} -``` - -Create Kubernetes Pod YAML for a container with the directory `/home/user/my-data` on the host bind-mounted in the container to `/volume`. -``` -$ podman generate kube my-container-with-bind-mounted-data -# Save the output of this file and use kubectl create -f to import -# it into Kubernetes. -# -# Created with podman-3.1.0-dev -apiVersion: v1 -kind: Pod -metadata: - creationTimestamp: "2021-03-18T16:26:08Z" - labels: - app: my-container-with-bind-mounted-data - name: my-container-with-bind-mounted-data -spec: - containers: - - command: - - /bin/sh - image: docker.io/library/alpine:latest - name: test-bind-mount - resources: {} - securityContext: - capabilities: - drop: - - CAP_MKNOD - - CAP_NET_RAW - - CAP_AUDIT_WRITE - volumeMounts: - - mountPath: /volume - name: home-user-my-data-host - restartPolicy: Never - volumes: - - hostPath: - path: /home/user/my-data - type: Directory - name: home-user-my-data-host -status: {} -``` - -Create Kubernetes Pod YAML for a container with the named volume `priceless-data` mounted in the container at `/volume`. -``` -$ podman generate kube my-container-using-priceless-data -# Save the output of this file and use kubectl create -f to import -# it into Kubernetes. -# -# Created with podman-3.1.0-dev -apiVersion: v1 -kind: Pod -metadata: - creationTimestamp: "2021-03-18T16:26:08Z" - labels: - app: my-container-using-priceless-data - name: my-container-using-priceless-data -spec: - containers: - - command: - - /bin/sh - image: docker.io/library/alpine:latest - name: test-bind-mount - resources: {} - securityContext: - capabilities: - drop: - - CAP_MKNOD - - CAP_NET_RAW - - CAP_AUDIT_WRITE - volumeMounts: - - mountPath: /volume - name: priceless-data-pvc - restartPolicy: Never - volumes: - - name: priceless-data-pvc - persistentVolumeClaim: - claimName: priceless-data -status: {} -``` - -Create Kubernetes Pod YAML for a pod called `demoweb` and include a service. -``` -$ sudo podman generate kube -s demoweb -# Save the output of this file and use kubectl create -f to import -# it into Kubernetes. -# -# Created with podman-0.12.2-dev -apiVersion: v1 -kind: Pod -metadata: - creationTimestamp: 2018-12-18T15:16:06Z - labels: - app: demoweb - name: demoweb-libpod -spec: - containers: - - command: - - python3 - - /root/code/graph.py - image: quay.io/baude/demoweb:latest - name: practicalarchimedes - resources: {} - tty: true - workingDir: /root/code -status: {} ---- -apiVersion: v1 -kind: Service -metadata: - creationTimestamp: 2018-12-18T15:16:06Z - labels: - app: demoweb - name: demoweb-libpod -spec: - ports: - - name: "8050" - nodePort: 31269 - port: 8050 - targetPort: 0 - selector: - app: demoweb - type: NodePort -status: - loadBalancer: {} -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-container(1)](podman-container.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)** - -## HISTORY -December 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) diff --git a/docs/source/markdown/podman-generate.1.md b/docs/source/markdown/podman-generate.1.md index 8466068f2..d84a9e098 100644 --- a/docs/source/markdown/podman-generate.1.md +++ b/docs/source/markdown/podman-generate.1.md @@ -13,7 +13,7 @@ The generate command will create structured output (like YAML) based on a contai | Command | Man Page | Description | |---------|------------------------------------------------------------|-------------------------------------------------------------------------------------| -| kube | [podman-generate-kube(1)](podman-generate-kube.1.md) | Generate Kubernetes YAML based on containers, pods or volumes. | +| kube | [podman-kube-generate(1)](podman-kube-generate.1.md) | Generate Kubernetes YAML based on containers, pods or volumes. | | spec | [podman-generate-spec(1)](podman-generate-spec.1.md) | Generate Specgen JSON based on containers or pods. | | systemd | [podman-generate-systemd(1)](podman-generate-systemd.1.md) | Generate systemd unit file(s) for a container or pod. | diff --git a/docs/source/markdown/podman-kube-down.1.md b/docs/source/markdown/podman-kube-down.1.md index 35725043b..92abd4ba3 100644 --- a/docs/source/markdown/podman-kube-down.1.md +++ b/docs/source/markdown/podman-kube-down.1.md @@ -40,4 +40,4 @@ $ cat demo.yml | podman kube play - ``` ## 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)** +**[podman(1)](podman.1.md)**, **[podman-kube(1)](podman-kube.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)**, **[podman-kube-generate(1)](podman-kube-generate.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-generate.1.md b/docs/source/markdown/podman-kube-generate.1.md new file mode 100644 index 000000000..f46f86de6 --- /dev/null +++ b/docs/source/markdown/podman-kube-generate.1.md @@ -0,0 +1,219 @@ +-% podman-kube-generate(1) +## NAME +podman-kube-generate - Generate Kubernetes YAML based on containers, pods or volumes + +## SYNOPSIS +**podman kube generate** [*options*] *container...* | *pod...* | *volume...* + +## DESCRIPTION +**podman kube generate** will generate Kubernetes YAML (v1 specification) from Podman containers, pods or volumes. Regardless of whether +the input is for containers or pods, Podman will always generate the specification as a Pod. The input may be in the form +of one or more containers, pods or volumes names or IDs. + +`Podman Containers or Pods` + +Volumes appear in the generated YAML according to two different volume types. Bind-mounted volumes become *hostPath* volume types and named volumes become *persistentVolumeClaim* volume types. Generated *hostPath* volume types will be one of three subtypes depending on the state of the host path: *DirectoryOrCreate* when no file or directory exists at the host, *Directory* when host path is a directory, or *File* when host path is a file. The value for *claimName* for a *persistentVolumeClaim* is the name of the named volume registered in Podman. + +Potential name conflicts between volumes are avoided by using a standard naming scheme for each volume type. The *hostPath* volume types are named according to the path on the host machine, replacing forward slashes with hyphens less any leading and trailing forward slashes. The special case of the filesystem root, `/`, translates to the name `root`. Additionally, the name is suffixed with `-host` to avoid naming conflicts with *persistentVolumeClaim* volumes. Each *persistentVolumeClaim* volume type uses the name of its associated named volume suffixed with `-pvc`. + +Note that if an init container is created with type `once` and the pod has been started, the init container will not show up in the generated kube YAML as `once` type init containers are deleted after they are run. If the pod has only been created and not started, it will be in the generated kube YAML. +Init containers created with type `always` will always be generated in the kube YAML as they are never deleted, even after running to completion. + +*Note*: When using volumes and generating a Kubernetes YAML for an unprivileged and rootless podman container on an **SELinux enabled system**, one of the following options must be completed: + * Add the "privileged: true" option to the pod spec + * Add `type: spc_t` under the `securityContext` `seLinuxOptions` in the pod spec + * Relabel the volume via the CLI command `chcon -t container_file_t -R ` + +Once completed, the correct permissions will be in place to access the volume when the pod/container is created in a Kubernetes cluster. + +Note that the generated Kubernetes YAML file can be used to re-run the deployment via podman-play-kube(1). + +## OPTIONS + +#### **--filename**, **-f**=*filename* + +Output to the given file, instead of STDOUT. If the file already exists, `kube generate` will refuse to replace it and return an error. + +#### **--service**, **-s** + +Generate a Kubernetes service object in addition to the Pods. Used to generate a Service specification for the corresponding Pod output. In particular, if the object has portmap bindings, the service specification will include a NodePort declaration to expose the service. A +random port is assigned by Podman in the specification. + +## EXAMPLES + +Create Kubernetes Pod YAML for a container called `some-mariadb`. +``` +$ sudo podman kube generate some-mariadb +# Save the output of this file and use kubectl create -f to import +# it into Kubernetes. +# +# Created with podman-0.11.2-dev +apiVersion: v1 +kind: Pod +metadata: + creationTimestamp: 2018-12-03T19:07:59Z + labels: + app: some-mariadb + name: some-mariadb-libpod +spec: + containers: + - command: + - docker-entrypoint.sh + - mysqld + env: + - name: HOSTNAME + - name: GOSU_VERSION + value: "1.10" + - name: GPG_KEYS + value: "199369E5404BD5FC7D2FE43BCBCB082A1BB943DB \t177F4010FE56CA3336300305F1656F24C74CD1D8 + \t430BDF5C56E7C94E848EE60C1C4CBDCDCD2EFD2A \t4D1BB29D63D98E422B2113B19334A25F8507EFA5" + - name: MARIADB_MAJOR + value: "10.3" + - name: MARIADB_VERSION + value: 1:10.3.10+maria~bionic + - name: MYSQL_ROOT_PASSWORD + value: x + image: quay.io/baude/demodb:latest + name: some-mariadb + ports: + - containerPort: 3306 + hostPort: 36533 + resources: {} + securityContext: + capabilities: + drop: + - CAP_MKNOD + - CAP_NET_RAW + - CAP_AUDIT_WRITE + tty: true +status: {} +``` + +Create Kubernetes Pod YAML for a container with the directory `/home/user/my-data` on the host bind-mounted in the container to `/volume`. +``` +$ podman kube generate my-container-with-bind-mounted-data +# Save the output of this file and use kubectl create -f to import +# it into Kubernetes. +# +# Created with podman-3.1.0-dev +apiVersion: v1 +kind: Pod +metadata: + creationTimestamp: "2021-03-18T16:26:08Z" + labels: + app: my-container-with-bind-mounted-data + name: my-container-with-bind-mounted-data +spec: + containers: + - command: + - /bin/sh + image: docker.io/library/alpine:latest + name: test-bind-mount + resources: {} + securityContext: + capabilities: + drop: + - CAP_MKNOD + - CAP_NET_RAW + - CAP_AUDIT_WRITE + volumeMounts: + - mountPath: /volume + name: home-user-my-data-host + restartPolicy: Never + volumes: + - hostPath: + path: /home/user/my-data + type: Directory + name: home-user-my-data-host +status: {} +``` + +Create Kubernetes Pod YAML for a container with the named volume `priceless-data` mounted in the container at `/volume`. +``` +$ podman kube generate my-container-using-priceless-data +# Save the output of this file and use kubectl create -f to import +# it into Kubernetes. +# +# Created with podman-3.1.0-dev +apiVersion: v1 +kind: Pod +metadata: + creationTimestamp: "2021-03-18T16:26:08Z" + labels: + app: my-container-using-priceless-data + name: my-container-using-priceless-data +spec: + containers: + - command: + - /bin/sh + image: docker.io/library/alpine:latest + name: test-bind-mount + resources: {} + securityContext: + capabilities: + drop: + - CAP_MKNOD + - CAP_NET_RAW + - CAP_AUDIT_WRITE + volumeMounts: + - mountPath: /volume + name: priceless-data-pvc + restartPolicy: Never + volumes: + - name: priceless-data-pvc + persistentVolumeClaim: + claimName: priceless-data +status: {} +``` + +Create Kubernetes Pod YAML for a pod called `demoweb` and include a service. +``` +$ sudo podman kube generate -s demoweb +# Save the output of this file and use kubectl create -f to import +# it into Kubernetes. +# +# Created with podman-0.12.2-dev +apiVersion: v1 +kind: Pod +metadata: + creationTimestamp: 2018-12-18T15:16:06Z + labels: + app: demoweb + name: demoweb-libpod +spec: + containers: + - command: + - python3 + - /root/code/graph.py + image: quay.io/baude/demoweb:latest + name: practicalarchimedes + resources: {} + tty: true + workingDir: /root/code +status: {} +--- +apiVersion: v1 +kind: Service +metadata: + creationTimestamp: 2018-12-18T15:16:06Z + labels: + app: demoweb + name: demoweb-libpod +spec: + ports: + - name: "8050" + nodePort: 31269 + port: 8050 + targetPort: 0 + selector: + app: demoweb + type: NodePort +status: + loadBalancer: {} +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-container(1)](podman-container.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)**, **[podman-kube-down(1)](podman-kube-down.1.md)** + +## HISTORY +December 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) diff --git a/docs/source/markdown/podman-kube-play.1.md.in b/docs/source/markdown/podman-kube-play.1.md.in index 9e9fc7f38..74565b75b 100644 --- a/docs/source/markdown/podman-kube-play.1.md.in +++ b/docs/source/markdown/podman-kube-play.1.md.in @@ -10,7 +10,7 @@ podman-kube-play - Create containers, pods and volumes based on Kubernetes YAML **podman kube play** will read in a structured file of Kubernetes YAML. It will then recreate the containers, pods or volumes described in the YAML. Containers within a pod are then started and the ID of the new Pod or the name of the new Volume is output. If the yaml file is specified as "-" then `podman kube play` will read the YAML file from stdin. Using the `--down` command line option, it is also capable of tearing down the pods created by a previous run of `podman kube play`. Using the `--replace` command line option, it will tear down the pods(if any) created by a previous run of `podman kube play` and recreate the pods with the Kubernetes YAML file. -Ideally the input file would be one created by Podman (see podman-generate-kube(1)). This would guarantee a smooth import and expected results. +Ideally the input file would be one created by Podman (see podman-kube-generate(1)). This would guarantee a smooth import and expected results. Currently, the supported Kubernetes kinds are: - Pod @@ -320,7 +320,4 @@ $ 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-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) +**[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-kube-generate(1)](podman-kube-generate.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.1.md b/docs/source/markdown/podman-kube.1.md index 7a6978a2b..0d3654011 100644 --- a/docs/source/markdown/podman-kube.1.md +++ b/docs/source/markdown/podman-kube.1.md @@ -12,10 +12,14 @@ file input. Containers will be automatically started. ## COMMANDS -| Command | Man Page | Description | -| ------- | --------------------------------------------------- | ---------------------------------------------------------------------------- | -| 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. | +| Command | Man Page | Description | +| ------- | ---------------------------------------------------- | ----------------------------------------------------------------------------- | +| down | [podman-kube-down(1)](podman-kube-down.1.md) | Remove containers and pods based on Kubernetes YAML. | +| generate | [podman-kube-generate(1)](podman-kube-generate.1.md) | Generate Kubernetes YAML based on containers, pods or volumes. | +| 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-kube-down(1)](podman-kube-down.1.md)** +**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-container(1)](podman-container.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)**, **[podman-kube-down(1)](podman-kube-down.1.md)**, **[podman-kube-generate(1)](podman-kube-generate.1.md)** + +## HISTORY +December 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) -- cgit v1.2.3-54-g00ecf