mirror of
https://github.com/containers/podman.git
synced 2025-06-03 20:33:20 +08:00
db439dd23e
Intended to be run from nightly Cirrus cron job. 1) Queries github for highest-sorting (not necessarily "latest") tag 2) Checks that the Windows MSI exists, fails if not 3) Cross-checks markdown files to ensure they have up-to-date links When run interactively, it will auto-update the .md files to show and link to the latest version. This makes it easy for anyone to then submit an update PR. And, it turns out that MSI is obsolete, the new thing is EXE. Update the tutorials to reflect that. Signed-off-by: Ed Santiago <santiago@redhat.com>
424 lines
14 KiB
Markdown
424 lines
14 KiB
Markdown
|
|
|
|
Podman for Windows
|
|
==================
|
|
|
|
While "containers are Linux," Podman also runs on Mac and Windows, where it
|
|
provides a native CLI and embeds a guest Linux system to launch your
|
|
containers. This guest is referred to as a Podman machine and is managed with
|
|
the `podman machine` command. On Windows, each Podman machine is backed by a
|
|
virtualized Windows System for Linux (WSLv2) distribution. The podman command
|
|
can be run directly from your Windows PowerShell (or CMD) prompt, where it
|
|
remotely communicates with the podman service running in the WSL environment.
|
|
Alternatively, you can access Podman directly from the WSL instance if you
|
|
prefer a Linux prompt and Linux tooling. In addition to command-line access,
|
|
Podman also listens for Docker API clients, supporting direct usage of
|
|
Docker-based tools and programmatic access from your language of choice.
|
|
|
|
Prerequisites
|
|
-------------
|
|
|
|
Since Podman uses WSL, you need a recent release of Windows 10 or Windows 11.
|
|
On x64, WSL requires build 18362 or later, and 19041 or later is required for
|
|
arm64 systems. Internally, WSL uses virtualization, so your system must
|
|
support and have hardware virtualization enabled. If you are running Windows
|
|
on a VM, you must have a VM that supports nested virtualization.
|
|
|
|
It is also recommended to install the modern "Windows Terminal," which
|
|
provides a superior user experience to the standard PowerShell and CMD
|
|
prompts, as well as a WSL prompt, should you want it.
|
|
|
|
You can install it by searching the Windows Store or by running the following
|
|
`winget` command:
|
|
|
|
`winget install Microsoft.WindowsTerminal`
|
|
|
|
|
|
Installing Podman
|
|
-----------------
|
|
|
|
Installing the Windows Podman client begins by downloading the Podman Windows
|
|
installer. The Windows installer is built with each Podman release and can be
|
|
downloaded from the official
|
|
[Github release page](https://github.com/containers/podman/releases). The
|
|
Windows installer file is named podman-#.#.#-setup.exe, where the # symbols
|
|
represent the version number of Podman. Be sure to download a 4.1 or later
|
|
release for the capabilities discussed in this guide.
|
|
As of 2022-11-09 the latest version is [v4.3.0](https://github.com/containers/podman/releases/download/v4.3.0/podman-v4.3.0-setup.exe).
|
|
|
|
|
|
|
|
Once downloaded, simply run the EXE file, and relaunch a new terminal. After
|
|
this point, podman.exe will be present on your PATH, and you will be able to run
|
|
the `podman machine init` command to create your first machine.
|
|
|
|
`PS C:\Users\User> podman machine init`
|
|
|
|
Automatic WSL Installation
|
|
--------------------------
|
|
|
|
If WSL has not been installed on your system, the first machine init command
|
|
will prompt a dialog to begin an automated install. If accepted, this process
|
|
will install the necessary Windows components, restart the system, and after
|
|
login, relaunch the machine creation process in a terminal window. Be sure to
|
|
wait a minute or two for the relaunch to occur, as Windows has a delay before
|
|
executing startup items. Alternatively, you can decline automatic installation
|
|
and install WSL manually. However, this will require additional download and
|
|
setup time.
|
|
|
|
Machine Init Process
|
|
--------------------
|
|
|
|
After WSL is installed, the init command will install a minimal installation
|
|
of Fedora, customizing it to run podman.
|
|
|
|
```
|
|
PS C:\Users\User> podman machine init
|
|
Extracting compressed file
|
|
Importing operating system into WSL (this may take 5+ minutes on a new WSL install)...
|
|
Installing packages (this will take a while)...
|
|
Complete!
|
|
Configuring system...
|
|
Generating public/private ed25519 key pair.
|
|
Your identification has been saved in podman-machine-default
|
|
Your public key has been saved in podman-machine-default.pub
|
|
The key fingerprint is:
|
|
SHA256:RGTGg2Q/LX7ijN+mzu8+BzcS3cEWP6Hir6pYllJtceA root@WINPC
|
|
Machine init complete
|
|
To start your machine run:
|
|
|
|
podman machine start
|
|
```
|
|
|
|
|
|
Starting Machine
|
|
----------------
|
|
|
|
After the machine init process completes, it can then be started and stopped
|
|
as desired:
|
|
|
|
```
|
|
PS C:\Users\User> podman machine start
|
|
|
|
Starting machine "podman-machine-default"
|
|
|
|
This machine is currently configured in rootless mode. If your containers
|
|
require root permissions (e.g. ports < 1024), or if you run into compatibility
|
|
issues with non-podman clients, you can switch using the following command:
|
|
|
|
podman machine set --rootful
|
|
|
|
API forwarding listening on: npipe:////./pipe/docker_engine
|
|
|
|
Docker API clients default to this address. You do not need to set DOCKER_HOST.
|
|
Machine "podman-machine-default" started successfully
|
|
```
|
|
|
|
First Podman Command
|
|
--------------------
|
|
|
|
From this point on, podman commands operate similarly to how they would on
|
|
Linux.
|
|
|
|
For a quick working example with a small image, you can run the Linux date
|
|
command on PowerShell.
|
|
|
|
```
|
|
PS C:\Users\User> podman run ubi8-micro date
|
|
Thu May 5 21:56:42 UTC 2022
|
|
```
|
|
|
|
Port Forwarding
|
|
---------------
|
|
|
|
Port forwarding also works as expected; ports will be bound against localhost
|
|
(127.0.0.1). Note: When running as rootless (the default), you must use a port
|
|
greater than 1023. See the Rootful and Rootless section for more details.
|
|
|
|
To launch httpd, you can run:
|
|
|
|
```
|
|
PS C:\Users\User> podman run --rm -d -p 8080:80 --name httpd docker.io/library/httpd
|
|
f708641300564a6caf90c145e64cd852e76f77f6a41699478bb83a162dceada9
|
|
```
|
|
|
|
A curl command against localhost on the PowerShell prompt will return a
|
|
successful HTTP response:
|
|
|
|
```
|
|
PS C:\Users\User> curl http://localhost:8080/ -UseBasicParsing
|
|
|
|
StatusCode : 200
|
|
StatusDescription : OK
|
|
Content : <html><body><h1>It works!</h1></body></html>
|
|
```
|
|
|
|
As with Linux, to stop, run:
|
|
|
|
`podman stop httpd`
|
|
|
|
|
|
Using API Forwarding
|
|
--------------------
|
|
|
|
API forwarding allows Docker API tools and clients to use podman as if it was
|
|
Docker. Provided there is no other service listening on the Docker API pipe;
|
|
no special settings will be required.
|
|
|
|
```
|
|
PS C:\Users\User> .\docker.exe run -it fedora echo "Hello Podman!"
|
|
Hello Podman!
|
|
```
|
|
|
|
Otherwise, after starting the machine, you will be notified of an environment
|
|
variable you can set for tools to point to podman. Alternatively, you can shut
|
|
down both the conflicting service and podman, then finally run `podman machine
|
|
start` to restart, which should grab the Docker API address.
|
|
|
|
|
|
```
|
|
Another process was listening on the default Docker API pipe address.
|
|
You can still connect Docker API clients by setting DOCKER HOST using the
|
|
following PowerShell command in your terminal session:
|
|
|
|
$Env:DOCKER_HOST = 'npipe:////./pipe/podman-machine-default'
|
|
|
|
Or in a classic CMD prompt:
|
|
|
|
set DOCKER_HOST = 'npipe:////./pipe/podman-machine-default'
|
|
|
|
Alternatively, terminate the other process and restart podman machine.
|
|
Machine "podman-machine-default" started successfully
|
|
|
|
PS C:\Users\User> $Env:DOCKER_HOST = 'npipe:////./pipe/podman-machine-default'
|
|
PS C:\Users\User>.\docker.exe version --format '{{(index .Server.Components 0).Name}}'
|
|
Podman Engine
|
|
```
|
|
|
|
Rootful & Rootless
|
|
------------------
|
|
|
|
On the embedded WSL Linux distro, podman can either be run under the root user
|
|
(rootful) or a non-privileged user (rootless). For behavioral consistency with
|
|
Podman on Linux, rootless is the default. Note: Rootful and Rootless
|
|
containers are distinct and isolated from one another. Podman commands against
|
|
one (e.g., podman ps) will not represent results/state for the other.
|
|
|
|
While most containers run fine in a rootless setting, you may find a case
|
|
where the container only functions with root privileges. If this is the case,
|
|
you can switch the machine to rootful by stopping it and using the set
|
|
command:
|
|
|
|
```
|
|
podman machine stop
|
|
podman machine set --rootful
|
|
```
|
|
|
|
To restore rootless execution, set rootful to false:
|
|
|
|
```
|
|
Podman machine stop
|
|
Podman machine set --rootful=false
|
|
```
|
|
|
|
Another case in which you may wish to use rootful execution is binding a port
|
|
less than 1024. However, future versions of podman will likely drop this to a
|
|
lower number to improve compatibility with defaults on system port services (such
|
|
as MySQL)
|
|
|
|
Volume Mounting
|
|
---------------
|
|
|
|
New in Podman v4.1 is the ability to perform volume mounts from Windows paths into a
|
|
Linux container. This supports several notation schemes, including:
|
|
|
|
Windows Style Paths:
|
|
|
|
`podman run --rm -v c:\Users\User\myfolder:/myfolder ubi8-micro ls /myfolder`
|
|
|
|
Unixy Windows Paths:
|
|
|
|
`podman run --rm -v /c/Users/User/myfolder:/myfolder ubi8-micro ls /myfolder`
|
|
|
|
Linux paths local to the WSL filesystem:
|
|
|
|
`podman run --rm -v /var/myfolder:/myfolder ubi-micro ls /myfolder`
|
|
|
|
All of the above conventions work, whether running on a Windows prompt or the
|
|
WSL Linux shell. Although when using Windows paths on Linux, appropriately quote
|
|
or escape the Windows path portion of the argument.
|
|
|
|
|
|
Listing Podman Machine(s)
|
|
-------------------------
|
|
|
|
To list the available podman machine instances and their current resource
|
|
usage, use the `podman machine ls` command:
|
|
|
|
```
|
|
PS C:\Users\User> podman machine ls
|
|
|
|
|
|
NAME VM TYPE CREATED LAST UP CPUS MEMORY DISK SIZE
|
|
podman-machine-default wsl 2 hours ago Currently running 4 331.1MB 768MB
|
|
```
|
|
|
|
Since WSL shares the same virtual machine and Linux kernel across multiple
|
|
distributions, the CPU and Memory values represent the total resources shared
|
|
across running systems. The opposite applies to the Disk value. It is
|
|
independent and represents the amount of storage for each individual
|
|
distribution.
|
|
|
|
|
|
Accessing the Podman Linux Environment
|
|
--------------------------------------
|
|
|
|
While using the podman.exe client on the Windows environment provides a
|
|
seamless native experience supporting the usage of local desktop tools and
|
|
APIs, there are a few scenarios in which you may wish to access the Linux
|
|
environment:
|
|
|
|
+ Updating to the latest stable packages on the embedded Fedora instance
|
|
+ Using Linux development tools directly
|
|
+ Using a workflow that relies on EXT4 filesystem performance or behavior
|
|
semantics
|
|
|
|
There are three mechanisms to access the embedded WSL distribution:
|
|
1. SSH using `podman machine ssh`
|
|
2. WSL command on the Windows PowerShell prompt
|
|
3. Windows Terminal Integration
|
|
|
|
### Using SSH
|
|
|
|
SSH access provides a similar experience as Podman on Mac. It immediately
|
|
drops you into the appropriate user based on your machine's rootful/rootless
|
|
configuration (root in the former, 'user' in the latter). The --username
|
|
option can be used to override with a specific user.
|
|
|
|
An example task using SSH is updating your Linux environment to pull down the
|
|
latest OS bugfixes:
|
|
|
|
`podman machine ssh sudo dnf upgrade -y`
|
|
|
|
### Using the WSL Command
|
|
|
|
The `wsl` command provides direct access to the Linux system but enters the
|
|
shell as root first. This is due to design limitations of WSL, where running
|
|
systemd (Linux's system services) requires the usage of a privileged process
|
|
namespace.
|
|
|
|
Unless you have no other distributions of WSL installed, it's recommended to
|
|
use the `-d` option with the name of your podman machine (podman-machine-default
|
|
is the default)
|
|
|
|
```
|
|
PS C:\Users\User> wsl -d podman-machine-default
|
|
```
|
|
|
|
You will be automatically entered into a nested process namespace where
|
|
systemd is running. If you need to access the parent namespace, hit `ctrl-d`
|
|
or type exit. This also means to log out, you need to exit twice.
|
|
|
|
```
|
|
[root@WINPC /]# podman --version
|
|
podman version 4.1.0
|
|
```
|
|
|
|
|
|
To access commands as the non-privileged user (rootless podman), you must
|
|
first type `su user`. Alternatively, you can prefix the `wsl` command to use the
|
|
special `enterns`:
|
|
|
|
```
|
|
wsl -d podman-machine-default enterns su user
|
|
[user@WINPC /]$ id
|
|
uid=1000(user) gid=1000(user) groups=1000(user),10(wheel)
|
|
```
|
|
|
|
Likewise, running commands as root without entering a prompt should also be
|
|
prefixed with `enterns`.
|
|
|
|
`wsl -d podman-machine-default enterns systemctl status`
|
|
|
|
Accessing the WSL instance as a specific user using `wsl -u` or using inline
|
|
commands without `enterns` is not recommended since commands will execute
|
|
against the incorrect namespace.
|
|
|
|
### Using Windows Terminal Integration
|
|
|
|
Entering WSL as root is a 2-click operation. Simply click the drop-down tag,
|
|
and pick 'podman-machine-default,' where you will be entered directly as root.
|
|
|
|
|
|
|
|
As before, to switch to a non-privileged user for rootless podman commands,
|
|
type `su user`.
|
|
|
|
```
|
|
[root@WINPC /]# su user
|
|
[user@WINPC /]$ podman info --format '{{.Store.RunRoot}}'
|
|
/run/user/1000/containers
|
|
```
|
|
|
|
Stopping a Podman Machine
|
|
-------------------------
|
|
|
|
To stop a running podman machine, use the `podman machine stop` command:
|
|
|
|
```
|
|
PS C:\Users\User> podman machine stop
|
|
Machine "podman-machine-default" stopped successfully
|
|
```
|
|
|
|
Removing a Podman Machine
|
|
-------------------------
|
|
|
|
To remove a machine, use the `podman machine rm` command:
|
|
|
|
```
|
|
PS C:\Users\User> podman machine rm
|
|
|
|
The following files will be deleted:
|
|
|
|
C:\Users\User\.ssh\podman-machine-default
|
|
C:\Users\User\.ssh\podman-machine-default.pub
|
|
C:\Users\User\.local\share\containers\podman\machine\wsl\podman-machine-default_fedora-35-x86_64.tar
|
|
C:\Users\User\.config\containers\podman\machine\wsl\podman-machine-default.json
|
|
C:\Users\User\.local\share\containers\podman\machine\wsl\wsldist\podman-machine-default
|
|
|
|
|
|
Are you sure you want to continue? [y/N] y
|
|
```
|
|
|
|
|
|
|
|
Troubleshooting
|
|
---------------
|
|
|
|
Recovering from a failed auto-installation of WSL
|
|
|
|
If auto-install fails and retrying is unsuccessful, you can attempt to reset
|
|
your WSL system state and perform a manual WSL installation using the `wsl
|
|
--install command`. To do so, perform the following steps:
|
|
|
|
1. Launch PowerShell as administrator
|
|
```
|
|
Start-Process powershell -Verb RunAs
|
|
```
|
|
2. Disable WSL Features
|
|
```
|
|
dism.exe /online /disable-feature /featurename:Microsoft-Windows-Subsystem-Linux /norestart
|
|
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /norestart
|
|
```
|
|
3. Reboot
|
|
4. Run manual WSL install
|
|
```
|
|
wsl --install
|
|
```
|
|
5. Continue with podman machine init
|
|
|
|
Install Certificate Authority
|
|
=============================
|
|
|
|
Instructions for installing a CA certificate can be found [here](podman-install-certificate-authority.md).
|