DOCSEARCHbyAlgolia
Submit Docs

Rancher Desktop Documentation

repository·main·Indexed 27 days ago

https://github.com/rancher-sandbox/rancher-desktop

An open-source Electron application providing Kubernetes and container management on Windows, macOS, and Linux. Includes documentation on BATS testing, Windows networking modes (classic vs. tunneled), i18n translation workflows, OpenAPI code generation for the Go-based rdctl CLI, and the Credential Helper Server protocol.

Tokens
25.6K
Snippets
40
Records
232
Agent score
92%

What's inside Rancher Desktop

  1. Rancher Desktop Feature Status and Roadmap

    main

    Rancher Desktop provides a set of features for container and Kubernetes management. The development status of features is categorized as follows:

    • ✅ Released: Feature is fully available.
    • 📅 Targeted: Feature is planned for the [next] or [later] milestone release.
    • ☀️ Considering: Feature is not currently planned but is under consideration for future releases.

    Milestone Definitions:

    • [next]: Targeted for the upcoming monthly release (typically the 4th Wednesday of the month).
    • [later]: Targeted for the release following the [next] milestone, or spillover from [next].

  2. Understand the Credential Helper Server protocol

    main
    The Credential Helper Server is an internal component used by Rancher Desktop to facilitate finding Docker credentials for other tools. It implements the standard Docker credential helper protocol. For detailed implementation specifications and how to develop against this protocol, refer to the official Docker credential helpers documentation.

  3. Understand Port Forwarding (Network Tunnel) workflow

    main

    Rancher Desktop uses a Network Tunnel mechanism to facilitate port forwarding between the Host and the VM. The process involves the guest-agent coordinating between the container runtime (containerd or dockerd), Kubernetes, and iptables to manage port mappings via wsl-proxy and host-switch.exe.

    Port Addition Workflow

    1. Trigger: The runtime (containerd via /tasks/start, dockerd via event[start], or Kubernetes via event[not deleted]) or iptables polling notifies the guest-agent of a new port.
    2. Proxy Setup: guest-agent instructs wsl-proxy to add the port and begin listening in the default namespace.
    3. Host Mapping: guest-agent instructs host-switch.exe to add the port using the APITracker mechanism, which then adds the port via gvisor on the host side.

    Port Removal Workflow

    1. Trigger: The runtime (containerd via /tasks/exit, dockerd via event[stop] or event[die], or Kubernetes via event[deleted]) or iptables polling notifies the guest-agent to remove a port.
    2. Cleanup: guest-agent instructs wsl-proxy to remove the listener in the default namespace and instructs host-switch.exe to remove the port via gvisor.

  5. Use extension-proxy to forward HTTP requests to a Unix socket

    main

    The extension-proxy program facilitates communication between an extension frontend and an extension backend. It handles forwarding HTTP requests made via relative URLs (e.g., ddClient.extension.vm.service.get('/foo')) from a TCP port to a backend listening on a Unix socket.

    To configure the proxy, you must set the SOCKET environment variable to the absolute path of the Unix socket. The proxy will then forward traffic from port 80 to this socket. In typical deployments, the socket is located in /run/guest-services/ and is shared with other containers via a volume.

  7. Understand the Linux `dev` and `stable` release channels

    main

    Rancher Desktop Linux releases are distributed via two OBS projects:

    dev Channel

    Used by developers. Triggered by commits to main or release-X.Y branches.

    1. A commit triggers the package.yml GitHub Actions workflow.
    2. The workflow builds Rancher Desktop and uploads a .zip to S3 named rancher-desktop-linux-<branch_name>.zip.
    3. The workflow triggers an OBS service run.
    4. OBS downloads/unpacks the S3 zip and pulls format-related files.
    5. OBS builds the packages, making them available via zypper install, apt install, etc.

    stable Channel

    Used by end-users. Triggered by published GitHub releases.

    1. A new release triggers the linux-release.yml GitHub Actions workflow.
    2. The workflow fetches the Linux .zip from the release and uploads it to S3 as rancher-desktop-linux-X.Y.zip.
    3. The workflow triggers an OBS service run.
    4. OBS downloads/unpacks the S3 zip and pulls format-related files.
    5. OBS builds the packages for distribution.

  9. Use the rdctl CLI for Rancher Desktop

    main
    The rdctl command-line interface (CLI) allows you to interact with Rancher Desktop. While most functionality requires the Rancher Desktop HTTP server to be running, certain commands like rdctl factory-reset can be used even when the application is not running to clear state files and generated files.

  10. Enable Docker port mapping

    main

    To enable Docker port mapping, run the guest agent with the --docker flag. The agent watches the Docker API for container type events including start, stop, and die.

    When exposed ports are detected, the agent creates a PortMapping and forwards it to the host. In Docker mode, the agent also manages iptables rules in the PREROUTING and POSTROUTING chains to ensure traffic is correctly routed from the namespaced network's subnet to localhost.

  12. Generate Go code from OpenAPI specifications

    main

    Use oapi-codegen to generate Go code from the command-api.yaml specification file. This is useful for maintaining type safety between the API definition and the implementation.

    Dependencies: You must have oapi-codegen installed. You can install it using:

    go get github.com/deepmap/oapi-codegen/cmd/oapi-codegen
    oapi-codegen pkg/rancher-desktop/assets/specs/command-api.yaml > api/commands.go