Deploy Kubernetes Workloads using Podman with Oracle Cloud Native Environment

Introduction

Podman kube provides developers and administrators with a way to test Kubernetes workloads using Podman before deploying them to a Kubernetes cluster. The podman kube command is used to generate Kubernetes-compliant YAML from existing Podman containers, or Pods, or to create containers/pods from a Kubernetes YAML file. This provides a convenient way to easily transition between Podman and Kubernetes environments, thereby leveraging the best of both ecosystems to reduce the development and test cycles.

Note: The podman kube play command reads any valid Kubernetes YAML file, and starts the pods, containers or volumes defined in the YAML file on your locally running Podman instance. However, not all Kubernetes YAML file types are supported; the currently supported Kubernetes kinds are:

Pod
Deployment
PersistentVolumeClaim
ConfigMap
Secret
DaemonSet
Job

A more detailed list of the Kubernetes YAML fields currently supported by the podman kube play command is located here .

Podman can apply supported Kubernetes YAML files to a Kubernetes cluster using the podman kube apply command. These steps work with any Kubernetes cluster. However, we recommend Oracle Cloud Native Environment as a Kubernetes deployment option. For more information, see the Oracle Cloud Native Environment documentation .

Note: This tutorial demonstrates the use of Podman to generate Kubernetes YAML files and subsequently shows how to deploy them to a Kubernetes cluster. Any further management of the deployed objects has to be completed using kubectl commands. For more information on using kubectl, see the upstream documentation .

Objectives

In this tutorial, you'll learn to:

Create and run a Pod on Podman using Kubernetes YAML.
Use Podman to generate Kubernetes YAML.
Use Podman Kube to deploy a Kubernetes YAML file to a Kubernetes cluster.

Prerequisites

Installation of Oracle Cloud Native Environment (Oracle CNE)
A single control node and one worker node
Podman installed

Configure Oracle Cloud Native Environment

Note: If running in your own tenancy, read the linux-virt-labs GitHub project README.md and complete the prerequisites before deploying the lab environment.

Open a terminal on the Luna Desktop.

Clone the linux-virt-labs GitHub project.

git clone https://github.com/oracle-devrel/linux-virt-labs.git

Change into the working directory.
```
cd linux-virt-labs/ocne2
```

Install the required collections.

ansible-galaxy collection install -r requirements.yml

Deploy the lab environment.
```
ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e use_podman=true -e install_ocne_rpm=true -e create_ocne_cluster=true -e "ocne_cluster_node_options='-n 1 -w 1'"
```
The free lab environment requires the extra variable local_python_interpreter, which sets ansible_python_interpreter for plays running on localhost. This variable is needed because the environment installs the RPM package for the Oracle Cloud Infrastructure SDK for Python, located under the python3.6 modules.
The default deployment shape uses the AMD CPU and Oracle Linux 8. To use an Intel CPU or Oracle Linux 9, add -e instance_shape="VM.Standard3.Flex" or -e os_version="9" to the deployment command.
Important: Wait for the playbook to run successfully and reach the pause task. At this stage of the playbook, the installation of the Oracle CNE is complete, and the instances are ready. Take note of the previous play, which prints the public and private IP addresses of the nodes it deploys and any other deployment information needed while running the lab.

Access the Kubernetes Cluster

Open a terminal and connect via SSH to the ocne instance.
```
ssh oracle@<ip_address_of_instance>
```
Wait for the cluster to stabilize and all pods to report they are running.
```
watch kubectl get pods -A
```
Once all the pods show a STATUS of Running, type Ctrl-C to exit the watch command.
Confirm how many nodes are present.
```
kubectl get nodes
```

Confirm Podman Works

Check the version of Podman.
```
podman -v
```

Confirm the Podman CLI is working.

podman run quay.io/podman/hello

Example Output:

[oracle@ol-server ~]$ podman run quay.io/podman/hello
Trying to pull quay.io/podman/hello:latest...
Getting image source signatures
Copying blob f82b04e85914 done
Copying config dbd85e09a1 done
Writing manifest to image destination
Storing signatures
!... Hello Podman World ...!

         .--"--.
       / -     - \
      / (O)   (O) \
   ~~~| -=(,Y,)=- |
    .---. /`  \   |~~
 ~/  o  o \~~~~.----. ~~
  | =(X)= |~  / (O (O) \
   ~~~~~~~  ~| =(Y_)=-  |
  ~~~~    ~~~|   U      |~~

Project:   https://github.com/containers/podman
Website:   https://podman.io
Documents: https://docs.podman.io
Twitter:   @Podman_io

Create the Kubernetes YAML files

The Podman Kube feature can work with either Podman-generated Kubernetes YAML files or with native Kubernetes YAML files. Let's look at both in turn.

Create a Podman Pod with a Container and Generate Kubernetes YAML

First off, deploy a container into a Podman pod locally. Then use the deployment to generate a Kubernetes YAML file that can be deployed to a Kubernetes cluster.

Create a pod with an Nginx server that maps port 8081 to the host.
```
podman run -dt --pod new:my-nginx --name nginx-container -p 8081:80 ghcr.io/oracle/oraclelinux9-nginx:1.20
```
This creates a new pod called 'my-nginx', deploys an Nginx container inside the pod and maps the container to port 8081 on the host.

Verify the Pod has been created.

podman pod ps

Example Output:

[oracle@ocne ~]$ podman pod ps
POD ID        NAME        STATUS      CREATED         INFRA ID      # OF CONTAINERS
e5248f6968b3  my-nginx    Running     48 seconds ago  5e41ad85e232  2

Confirm you can access the new pod and its container from the host.
```
curl http://localhost:8081
```
Generate a Kubernetes file YAML from the running pod.
```
podman kube generate my-nginx --type pod > nginx-pod.yaml
```
The Podman generate command creates a Kubernetes-compliant file from a running Podman pod with containers. Making it very useful for local prototyping, and subsequently creating a Kubernetes-compliant manifest file, you can deploy to a Kubernetes cluster.

Review the generated file.

cat nginx-pod.yaml

Example Output:

[oracle@ocne ~]$ cat nginx-pod.yaml
# Save the output of this file and use kubectl create -f to import
# it into Kubernetes.
#
# Created with podman-4.9.4-rhel
apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: "2025-08-11T14:08:13Z"
  labels:
    app: my-nginx
  name: my-nginx
spec:
  containers:
  - env:
    - name: TERM
      value: xterm
    image: ghcr.io/oracle/oraclelinux9-nginx:1.20
    name: zenbardeen
    ports:
    - containerPort: 80
      hostPort: 8081
    tty: true

Remove Pod and Containers Deployed using Podman Kube

Pods and their associated containers can be removed easily once you have finished working with them.

Delete the my-nginx pod.
```
podman kube down nginx-pod.yaml
```
Confirm both pods have been deleted.
```
podman pod ps
```
Example Output:
```
[oracle@ocne ~]$ podman pod ps
POD ID      NAME        STATUS      CREATED     INFRA ID    # OF CONTAINERS
```
This confirms that the Podman-generated Kubernetes YAML file you created earlier is valid.

Use Podman Kube to Deploy Kubernetes YAML to a Kubernetes Cluster

Podman can only deploy to a Kubernetes cluster if your host has a valid kubeconfig file located in the $HOME/.kube directory.

Confirm Your Environment is Valid

Confirm the KUBECONFIG environment variable is set.
```
env | grep KUBE
```
Example Output:
```
[oracle@ocne ~]$ env | grep KUBE
KUBECONFIG=/home/oracle/.kube/kubeconfig.ocne.local
```
Information: If you have kubectl installed and there are multiple config files in the ${HOME}/.kube directory, execute this command to confirm which config file is currently being used by kubectl:
```
kubectl get pod  -v6 2>&1 | awk '/Config loaded from file:/{print $NF}'
```
Example Output:
```
[oracle@ocne ~]$ kubectl get pod  -v6 2>&1 | awk '/Config loaded from file:/{print $NF}'
/home/oracle/.kube/kubeconfig.ocne.local
```
Note: Execute any kubectl command with verbosity set to level 6 or higher, and the current kubeconfig being used is included in the output.

Deploy a valid Kubernetes YAML file

Create a Kubernetes YAML file.

cat << EOF | tee testpod.yaml > /dev/null
apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
  - name: test-container
    image: ghcr.io/oracle/oraclelinux9-nginx:1.20
    ports:
    - containerPort: 8080
EOF

Use Podman to deploy the testpod.yaml file to your Kubernetes cluster.

podman kube apply -f testpod.yaml

Example Output:

[oracle@ocne ~]$ podman kube apply -f testpod.yaml
Deploying to cluster...
Successfully deployed workloads to cluster!

Note: This is deployed to the default namespace by default.

Confirm the Pod is deployed to your cluster.

kubectl get pods

Example Output:

[oracle@ocne ~]$ kubectl get pods
NAME      READY   STATUS    RESTARTS   AGE
my-pod    1/1     Running   0          23s

This confirms that podman deployed a pod called 'my-pod' to the cluster.

Confirm Nginx is deployed as expected.

kubectl describe pods/my-pod

Example Output:

[oracle@ocne ~]$ kubectl describe pods/my-pod
Name:             my-pod
Namespace:        default
Priority:         0
Service Account:  default
Node:             ocne-worker-1/192.168.122.122
Start Time:       Wed, 06 Aug 2025 15:09:55 +0000
Labels:           <none>
Annotations:      <none>
Status:           Running
IP:               10.244.1.6
IPs:
  IP:  10.244.1.6
Containers:
  test-container:
    Container ID:   cri-o://c2ea59274a702f9cdb044d92869b63da27249370a0c55bef2994f49a092e527a
    Image:          ghcr.io/oracle/oraclelinux9-nginx:1.20
    Image ID:       ghcr.io/oracle/oraclelinux9-nginx@sha256:16b15a609a172059f9e66ae412dde3b9febe0b0fdd4eb1084eac2783088de6f1
    Port:           8080/TCP
    Host Port:      0/TCP
    State:          Running
...
...
...
Events:
  Type    Reason     Age   From               Message
  ----    ------     ----  ----               -------
  Normal  Scheduled  48m   default-scheduler  Successfully assigned default/my-pod to ocne-worker-1
  Normal  Pulling    48m   kubelet            Pulling image "ghcr.io/oracle/oraclelinux9-nginx:1.20"
  Normal  Pulled     48m   kubelet            Successfully pulled image "ghcr.io/oracle/oraclelinux9-nginx:1.20" in 10.66s (10.66s including waiting). Image size: 267010601 bytes.
  Normal  Created    48m   kubelet            Created container: test-container
  Normal  Started    48m   kubelet            Started container test-container

This confirms that the podman kube play command used the Kubernetes YAML file to deploy a pod directly to a Kubernetes cluster.

Deploy Podman-generated Kubernetes YAML to a Kubernetes Cluster

Deploy the Podman-generated Kubernetes YAML file you created at the start of the tutorial to a Kubernetes Cluster.

Deploy the nginx-pod.yaml file to your Kubernetes cluster.

podman kube apply -f nginx-pod.yaml

Example Output:

[oracle@ocne ~]$ podman kube apply -f nginx-pod.yaml
Deploying to cluster...
Successfully deployed workloads to cluster!

Confirm the Pod is deployed to your cluster.

kubectl get pods

Example Output:

[oracle@ocne ~]$ kubectl get pods
NAME       READY   STATUS    RESTARTS   AGE
my-nginx   1/1     Running   0          1m59s
my-pod     1/1     Running   0          5m12s

Confirm Nginx is deployed as expected.
```
kubectl describe pods/my-nginx
```
This confirms that Podman successfully deployed a podman-generated Kubernetes YAML called 'my-nginx' to the Kubernetes cluster.

Next Steps

This tutorial demonstrated how to use Podman to deploy Kubernetes workloads to a Kubernetes cluster with Oracle Cloud Native Environment. Check out the Oracle Linux Training Station for additional tutorials and content.