diff options
| -rw-r--r-- | docs/tutorials/podman-for-windows.md | 417 | ||||
| -rw-r--r-- | docs/tutorials/podman-win-install.jpg | bin | 0 -> 516666 bytes | |||
| -rw-r--r-- | docs/tutorials/podman-wsl-term.jpg | bin | 0 -> 146541 bytes |
3 files changed, 417 insertions, 0 deletions
diff --git a/docs/tutorials/podman-for-windows.md b/docs/tutorials/podman-for-windows.md new file mode 100644 index 000000000..bb9674774 --- /dev/null +++ b/docs/tutorials/podman-for-windows.md @@ -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 diff --git a/docs/tutorials/podman-win-install.jpg b/docs/tutorials/podman-win-install.jpg Binary files differnew file mode 100644 index 000000000..cf1b3ca86 --- /dev/null +++ b/docs/tutorials/podman-win-install.jpg diff --git a/docs/tutorials/podman-wsl-term.jpg b/docs/tutorials/podman-wsl-term.jpg Binary files differnew file mode 100644 index 000000000..a01bea84e --- /dev/null +++ b/docs/tutorials/podman-wsl-term.jpg |
