mirror of https://github.com/containers/podman
Add initial Windows guide
Signed-off-by: Jason T. Greene <jason.greene@redhat.com>pull/14141/head
Jason T. Greene
Jason T. Greene
parent
2dcf3067ec
commit
876b05cdb3
|
|
@ -0,0 +1,417 @@
|
|||
|
||||
|
||||
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-v.#.#.#.msi, 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.
|
||||
|
||||
|
||||
|
||||
Once downloaded, simply run the MSI 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 Rooftull 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
|
||||
```
|
||||
|
||||
Rootfull & 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: Rootfull 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 -it c:\Users\User\myfolder:/myfolder ubi8-micro ls /myfolder`
|
||||
|
||||
Unixy Windows Paths:
|
||||
|
||||
`podman run -it /c/Users/User/myfolder:/myfolder ubi8-micro ls /myfolder`
|
||||
|
||||
Linux paths local to the WSL filesystem:
|
||||
|
||||
`podman run -it /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
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 505 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 143 KiB |
Loading…
Reference in New Issue