rancher-sandbox / docs.rancherdesktop.io Goto Github PK

When viewing the rancher desktop docs, it would be helpful to have a walkthrough which describes how to launch, stop, and delete a Kubernetes cluster. As a minikube user who is new to using a UI for working with a local cluster, it was not instantly intuitive on what the typical workflow for using rancher desktop was.

Luckily, rancher desktop has a pretty nice UX, and, after poking around a bit, it was pretty simple to understand the basic workflow (i.e. Launch rancher desktop, select k8s version, and quit rancher desktop to stop the cluster or reset the cluster to delete/restore the cluster). Including pictures of the desktop UI to accompany this flow would be helpful as well.

Thanks for all the work on rancher desktop! Looking forward to your thoughts.

The URL for any other version is created by including the version string, e.g.

https://docs.rancherdesktop.io/next/references/architecture/

To access the current version of the docs from inside the application, we would need to reference it like (1.6.1 should really be 1.6, see #117):

https://docs.rancherdesktop.io/1.6.1/references/architecture/

This URL currently gets a 404, but should have redirected to

https://docs.rancherdesktop.io/references/architecture/

(openSUSE Leap 15.4) linux.zip

There should be some quick link on https://docs.rancherdesktop.io/getting-started/installation/#linux for users just wanting to upgrade to the latest version.

For Windows and macOS the users just download the latest version directly from the Github release page, but for Linux they have to read through several blocks of text to find the relevant information.

On the FAQ page, under the loss of Docker Compose, the suggested fix links to the page to install Docker Compose, which in the case of Windows means that Docker Desktop appears to be needed to be re-installed. If there was a way to use Docker Compose without reinstalling Docker Desktop, that would be good to link to.

The english version dynamically displays the current year.

See https://github.com/rancher-sandbox/docs.rancherdesktop.io/blob/main/i18n/zh/docusaurus-theme-classic/footer.json

In the regular docs pages there is a # anchor link visible on hover.

I would like to have this also for each question on the FAQ page, so I link directly to a question.

Right now the current docs version is 1.6.1. This does not match the latest release, which is 1.6.2. I don't think we want/need separate versions per patch release; patches only include fixes for regressions or security issues.

So I think the current docs should be version 1.6 right now, and the next version 1.7 etc.

(Windows 10) windows.zip

I just downloaded the Apple Silicon version of Rancher Desktop from the homepage and installed it.

I unchecked Kubernetes when first launching because I only needed docker. I allowed the permissions it asked me, but when the UI comes up, I get this error:

Kubernetes Error
Error Starting Kubernetes
Error: /Applications/Rancher Desktop.app/Contents/Resources/resources/darwin/lima/bin/limactl exited with code 1

Last command run:
limactl start --tty=false 0

Context:
Starting virtual machine

Some recent logfile lines:

time="2022-03-17T12:54:39+11:00" level=info msg="Using the existing instance \"0\""
time="2022-03-17T12:54:39+11:00" level=info msg="Starting switch daemon for \"bridged_en0\" network"
time="2022-03-17T12:54:39+11:00" level=fatal msg="\"/private/var/run/rancher-desktop-lima\" doesn't seem to be writable by the daemon (gid:1) group"
2022-03-17T01:54:39.769Z: + limactl start --tty=false 0
2022-03-17T01:54:39.770Z: Error: /Applications/Rancher Desktop.app/Contents/Resources/resources/darwin/lima/bin/limactl exited with code 1
2022-03-17T01:54:39.771Z: Error starting lima: Error: /Applications/Rancher Desktop.app/Contents/Resources/resources/darwin/lima/bin/limactl exited with code 1
    at ChildProcess.<anonymous> (/Applications/Rancher Desktop.app/Contents/Resources/app.asar/dist/app/background.js:1:8692)
    at ChildProcess.emit (node:events:394:28)
    at Process.ChildProcess._handle.onexit (node:internal/child_process:290:12)

Hi,
I think the rancher tutorial is not up-to date on https://docs.rancherdesktop.io/how-to-guides/rancher-on-rancher-desktop
If I run

docker run --privileged -d --restart=no -p 8080:80 -p 8443:443 rancher/rancher

it won't show the rancher UI but an error message instead.

docker run -d --restart=unless-stopped -p 8080:8080 rancher/server
worked for me.

If I just did something wrong, feel free to just close this issue.

Kind regards,
Denise

The docs currently claim that the cache directory contains just *.tar files of the airgap images, but for newer versions these will actually be *.tar.zstd compressed tarballs.

As per this report on Slack: https://rancher-users.slack.com/archives/C0200L1N1MM/p1681276046814379 it seems like the "VS Code Remote Containers" seems to be slightly outdated. I think the VSCode UI has been changed. I tested it with Version 1.77.2 and can confirm the behavior.
As the user reported, the option "Open Folder in Container..." is not shown as explained in the tutorial. As far as I can tell, there is now one additional step needed:

• Click on the green icon in the lower right corner
• Press F1 to search for available commands
• Start typing and search for command: "Dev Containers: Open Folder in Container..."

Per feedback from the web team, we should have a link back to rancher.com for branding/SEO purposes similar to what Rancher Manager has done. The link's label should be "Rancher Home".

When following the instructions in the Hello World example number 2 I end up with a pod which fails to start with an 'ErrImageNeverPull' error. If you dig into the pod logs you find 'Container image "nginx-helloworld:latest" is not present with pull policy of Never'. I assumed that this meant that my local docker repository on my laptop was not accessible by my kubernetes cluster. After a lot of searching I managed to work out that if I ran k3d image import nginx-helloworld:latest -c mycluster that the docker image is imported to my cluster and then becomes available. Is there anywhere within the docs which outlines a permanent fix or could this information be added to the instructions?

It could be that my set up was incorrect but I could not see anything in the instructions for quick starting to somehow link the local repository to any kubernetes cluster created and I thought I followed it pretty faithfully.

I am seeing an error when I am trying to run cockroach DB image using rancher desktop

My host machine details:

Mac, Monterey 12.2.1, intel core i7

My docker-compose file

version: '3.5'

services:

 db-node-1:
    container_name: db-node-1
    image: cockroachdb/cockroach:latest
    volumes:
      - ./data/db-node-1:/cockroach/cockroach-data
    command: start-single-node --insecure
    ports:
      - '26257:26257'
      - '8080:8080'

command: nerdctl compose up

error:

db-node-1_1 |time="2022-05-13T20:33:35Z" level=fatal msg="no running task found: task 9125f9e13d04a92fce2045ae459d4659598eec1ecb28f02c5bfca54818a5f598 not found: not found"
db-node-1   |*
db-node-1   |* WARNING: ALL SECURITY CONTROLS HAVE BEEN DISABLED!
db-node-1   |* 
db-node-1   |* This mode is intended for non-production testing only.
db-node-1   |* 
db-node-1   |* In this mode:
db-node-1   |* - Your cluster is open to any client that can access any of your IP addresses.
db-node-1   |* - Intruders with access to your machine or network can observe client-server traffic.
db-node-1   |* - Intruders can log in without password and read or write any data in the cluster.
db-node-1   |* - Intruders can consume all your server's resources and cause unavailability.
db-node-1   |*
db-node-1   |*
db-node-1   |* INFO: To start a secure server without mandating TLS for clients,
db-node-1   |* consider --accept-sql-without-tls instead. For other options, see:
db-node-1   |* 
db-node-1   |* - https://go.crdb.dev/issue-v/53404/v21.2
db-node-1   |* - https://www.cockroachlabs.com/docs/v21.2/secure-a-cluster.html
db-node-1   |*
db-node-1   |*
db-node-1   |* ERROR: ERROR: failed to start server: failed to create engines: hard open file descriptor limit of 1024 is under the minimum required 1956
db-node-1   |* please see https://www.cockroachlabs.com/docs/v21.2/recommended-production-settings.html for more details
db-node-1   |*
db-node-1   |ERROR: failed to start server: failed to create engines: hard open file descriptor limit of 1024 is under the minimum required 1956
db-node-1   |please see https://www.cockroachlabs.com/docs/v21.2/recommended-production-settings.html for more details
db-node-1   |Failed running "start-single-node"

Per Slack, some new features for 1.1.0 need to be documented. Reference: RD releases.

1. Document how credentials are managed and accessed from the Rancher Desktop VM

• Use gpg --generate-key to get a GPG key
• Run pass init GPG-ID
  (I'm not completely clear on how to figure out the GPG key, just went with what seemed obvious.

Now, whether you're using moby or containerd, their command-line clients will hit the VM-side docker-credential-rancher-desktop script to manage the credentials. This script does a curl to the credential-server, running on the host, and that opens up ~/.docker/config.json to figure out which credential manager is being used on the server, looking at the credsStore field. This is wincred on Windows, osxkeychain on macOS, and either secretservice or pass on Linux.

2. Explain that pass has to be installed and initialized using gpg -- see https://www.passwordstore.org/

rancher-sandbox/rancher-desktop#1180 (comment) describes the steps that can be used to manually expose the port until we have proper support for this in Rancher Desktop.

As per suggestions for elastic search here the instruction currently suggests the following provisioning:

provision:
- mode: system
  script: |
    #!/bin/sh
    cat <<'EOF' > /etc/security/limits.d/rancher-desktop.conf
    * soft     nofile         82920
    * hard     nofile         82920
    sysctl -w vm.max_map_count=262144
    EOF

This doesn't seem to be correct since it places the maximum map count alter command via sysctl inside the rancher-desktop.conf. I believe this should be correct to:

provision:
- mode: system
  script: |
    #!/bin/sh
    cat <<'EOF' > /etc/security/limits.d/rancher-desktop.conf
    * soft     nofile         82920
    * hard     nofile         82920
    EOF
    sysctl -w vm.max_map_count=262144

I've added sample screenshots in rancher-sandbox/rancher-desktop#4418.

Re: https://docs.rancherdesktop.io/how-to-guides/rancher-on-rancher-desktop/

Following the instructions for Helm on WSL, I ran into the error message described on this page -- rancher/rancher#38392

Error: chart requires kubeVersion: < 1.24.0-0 which is incompatible with Kubernetes v1.24.3+k3s1

There should probably be some acknowledgement of the error and information on how to resolve it. Although, as a Rancher Desktop newbie, I had trouble following the suggested workarounds posted on rancher/rancher#38392

The links to the Application sub-tabs in the Preferences page have a number at the end, instead of the pure section id.
This causes a mismatch with the Help buttons link in Rancher Desktop.

Example:

The 'Environment' link is https://docs.rancherdesktop.io/next/ui/preferences/application/#environment-1

Actual Behavior

$ rdctl set --kubernetes-enabled false
Error: set command: unrecognized command-line arguments specified: [false]

The command as described in the documentation does not work.

Steps to Reproduce

Run
$ rdctl set --kubernetes-enabled false
Will fail every time

Result

Error: set command: unrecognized command-line arguments specified: [false]

Expected Behavior

I would expect that command to disable Kuberenetes and return an affirmative response, not to return an error.

Additional Information

This does work:
rdctl set --kubernetes-enabled=false

Rancher Desktop Version

1.2.1

Rancher Desktop K8s Version

K8s Disabled

Which container runtime are you using?

moby (docker cli)

What operating system are you using?

macOS

Operating System / Build Version

12.3.1

What CPU architecture are you using?

x64

Linux only: what package format did you use to install Rancher Desktop?

No response

Windows User Only

No response

Note that any files with a file extension of .start, such as k3s-overrides.start, can be executed when Rancher Desktop starts its Kubernetes backend (if enabled).

According to @mook-as this is not true; they should always run, even when Kubernetes is disabled.

Lima & WSL both pre-mount volumes, but someone asked on slack:

Question was:

Is filesharing working same like Docker Desktop?  I am using rancher desktop and i would like volume my local directiores? Do I have to configure anything on rancher desktop?

The warning at the top that the app needs to be running for rdctl to work is incomplete. Some subcommands, like rdctl start and rdctl factory-reset work by themselves.

The lists of available subcommands, or options (especially for rdctl start and rdctl set) seems very out-of-date.

While experimenting with the following command, I spotted an API that's not present in upstream Kubernetes, which doesn't conform to their schema standards (it's non-json)

$ kubectl  get --raw / | grep logs
    "/logs",

$ kubectl  get --raw /logs
<pre>
<a href="acpid.log">acpid.log</a>
<a href="buildkitd.log">buildkitd.log</a>
<a href="cloud-init-output.log">cloud-init-output.log</a>
<a href="containerd.log">containerd.log</a>
<a href="containers/">containers/</a>
<a href="dmesg">dmesg</a>
<a href="lima-init.log">lima-init.log</a>
<a href="messages">messages</a>
<a href="openresty/">openresty/</a>
<a href="pods/">pods/</a>
<a href="rancher-desktop-guestagent.log">rancher-desktop-guestagent.log</a>
<a href="wtmp">wtmp</a>
</pre>

This should be documented, and preferrably be json to conform to the other APIs exposed.

# Version info
$ rdctl  version
rdctl client version: 1.1.0, targeting server version: v0
# Rancher Desktop version 1.7.0 on Ubuntu 22.04.1 x64
$ kubectl version
WARNING: This version information is deprecated and will be replaced with the output from kubectl version --short.  Use --output=yaml|json to get the full version.
Client Version: version.Info{Major:"1", Minor:"24", GitVersion:"v1.24.4", GitCommit:"95ee5ab382d64cfe6c28967f36b53970b8374491", GitTreeState:"clean", BuildDate:"2022-08-17T18:54:23Z", GoVersion:"go1.18.5", Compiler:"gc", Platform:"linux/amd64"}
Kustomize Version: v4.5.4
Server Version: version.Info{Major:"1", Minor:"24", GitVersion:"v1.24.8+k3s1", GitCommit:"648004e4faeaf9e8705386342e95ec9bd211c2b8", GitTreeState:"clean", BuildDate:"2022-11-18T18:29:47Z", GoVersion:"go1.18.8", Compiler:"gc", Platform:"linux/amd64"}

Thanks,

Traefik is not accessible out of the box after a successful RD deployment on Linux. As mentioned in rancher-sandbox/rancher-desktop#3916 (comment) and rancher-sandbox/rancher-desktop#1668 (comment), the lower port bindings need to be allowed, first. This can be done by (sudo is required):

sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80

Because this command is only mandatory in Linux, it would be great if the installation guide could cover it, too.

Screenshots are here: output.zip

Full Linux: Ubuntu 20.04

Follow these instructions:

cd /tmp
mkdir dc-work
cd dc-work
curl -o docker-compose -kL https://github.com/docker/compose/releases/download/v2.2.3/docker-compose-linux-x86_64
chmod +x docker-compose
mkdir -p ~/.docker/cli-plugins/
mv docker-compose ~/.docker/cli-plugins/
cd ..
rmdir dc-work

This line fails:
curl -o docker-compose -kL https://github.com/docker/compose/releases/download/v2.2.3/docker-compose-linux-x86_64

with
Warning: Failed to create the file docker-compose: Permission denied
curl: (23) Failure writing output to destination

Try with "sudo". Same error - checked github. File exists

I then tried to do this manually, i.e.

Go to the github website directly and download the file (same version). Copy file to dc-work and rename to "docker-compose".
continue as above from (and including) chmod +x docker-compose

Try to run docker-compose from command line, response:

Command 'docker-compose' not found, but can be installed with:

sudo snap install docker          # version 20.10.12, or
sudo apt  install docker-compose  # version 1.25.0-1

See 'snap info docker' for additional versions.

Are there any instructions missing (i.e. to create a link or something?)

FYI: I'm not a linux expert

I also mistakenly tried running the apt install docker-compose which then installed "full docker" locally instead of using my rancher version and lead to me needing to cleanup/remove docker/rancher and re-install rancher to get it all back to normal again

From the (draft) release notes:

helm 3.11.2 → 3.11.3
docker 23.0.1 → 23.0.3
docker-compose 2.16.0 → 2.17.2
nerdctl 1.2.1 → 1.3.0
trivy 0.38.2 → 0.39.1

I just had an idea to auto-update some parts of the documentation by embedding the commands that generates them into the docs. That way you simply install the latest Rancher Desktop and then let it update the documents automatically.

Here is a proof-of-concept. Sample doc:

# Sample doc

```console
This will stay the same
```

Dynamic content:

```console command="ls *.md"
> ls
nothing to see
```

Command may include escaped quotes:

```console command="echo \"Hello world\"" title="Wazzup?"
Hi there!
```

And this is update-output.pl:

#!/usr/bin/env perl

use strict;
use warnings;

my $skip;

while (<>) {
    # Match command, including escaped embedded quotes
    if (/^```.*command="((?:\\.|[^"\\])+)"/) {
        # Unescape all characters in the command
        my $command = $1 =~ s/\\(.)/$1/gr;
        print;
        print "> $command\n";
        print qx($command);
        $skip = 1;
        next;
    }
    undef $skip if /^```\s*$/;
    print unless $skip;
}

Running update-output.pl sample.md produces an updated version of the document by running all commands again:

# Sample doc

```console
This will stay the same
```

Dynamic content:

```console command="ls *.md"
> ls *.md
README.md
sample.md
```

Command may include escaped quotes:

```console command="echo \"Hello world\"" title="Wazzup?"
> echo "Hello world"
Hello world
```

I've verified that adding command="..." on the code blocks is ignored by Docusaurus.

The place you click to see this is "GitHub" in the top right corner of the docs site.

Right now it returns results for each version, and the display doesn't even indicate which version each result comes from:

"nerdctl rmi" or "nerdctl system prune --all" only remove the reference of unused data, release none on physics disk. The Avail storage value remains same on 'df -h' after run the above commands.
Where is the unused data? seems not in '/var/lib/nerdctl'.

my env: macos13, m1 version

The troubleshooting tips page needs an update to group the tips into specific areas/topics to improve user experience.

A documentation update needs to be made to address the tray icon issue. Proposed update to troubleshooting section alerting users that the tray icon for Ubuntu versions >=20.04.5 LTS after enabling the hide notification icon will still appear and is a known Ubuntu issue.

https://bugs.launchpad.net/ubuntu/+source/libappindicator/+bug/1395229
https://bugs.launchpad.net/ubuntu/+source/mutter/+bug/1796607
electron/electron#17622

Currently this gets written to tmp()/rdctl-stdout.txt`

where on linux tmp() is usually /tmp,

on macOS it's given by $TMPDIR

and on Windows by %TEMP% or $env:TEMP` for powershell users.

The full path does get written to background.log, but unless the user is tailing this file when starting the factory-reset operation, this information will be lost when factory-reset deletes the log file.

The output is only necessary for post-mortem analysis when the factory-reset operation appears to fail.

We should move https://docs.rancherdesktop.io/getting-started/features#troubleshooting-tips away from under Features and have it be its own top-level menu item in the Docs. Preferably at the bottom under FAQ. Then we can update Rancher Desktop with a link to that section, which we can expand over time.

https://www.linuxuprising.com/2021/01/apt-key-is-deprecated-how-to-add.html

You can suggest using curl to add a file to a trusted-gpg thing, or a specific path and properly pin just your repo to it.

Somebody asked about installing Longhorn on Rancher Desktop; I'm not sure if this is useful for our docs (it's basically a retread of Longhorn docs — it's not like I looked at installing Longhorn before), but since I had it I might as well post it:

1. Installing Longhorn dependencies
   1. rdctl shell
   2. (From the shell) sudo su -
   3. apk add -U nfs-utils open-iscsi
   4. modprobe iscsi_tcp
   5. (Exit out of rdctl shell)
2. Install longhorn using the helm v3 method

Note: This does not work on Windows, because we can't load kernel modules there.

In the TOC under "User Interface", the page names "Port forwarding" and "Container engine" should be "Port Forwarding" and "Container Engine" to be consistent with capitalization for other page names.

It looks like expanding the navigation menu is sort of broken.

Steps to reproduce:

1. Navigate to https://docs.rancherdesktop.io/
2. While still on the Getting Started → Introduction page, switch to a different version using the version dropdown at the top.
3. Without navigating to a different page, expand the User Interface heading, and then then Preferences sub-heading.

Expected results:

The Preferences sub-heading expands.

Actual results:

The toggle to the right of Preferences changes from ▷ to ▽ but no additional headings show up.

Additional information

If we switch to any page under the User Interface section before switching versions, the sub-headings show up correctly.

I'm not sure how to determine the deployed version of the docs site, but it's probably at 042b5e0.

Current documentation has a "Hello World" example for using nerdctl but for that I could just use docker...

From my point of view where Rancher Desktop comes into play is actually when you:

• develop application locally
• create container image locally (without pushing to a remote image repository)
• execute it in local kubernetes environment

I'm new to this kubernetes/rancher desktop/containers world so it took me a while to figure out how to execute above scenario on my own (and am not even certain that I used it correctly and not just accidentally found one of solutions that is not really the most elegant).

It'd be nice to have a hello world example that would:

• use command like: nerdctl build -t <image_name>:local --namespace k8s.io -f <path_to>/Dockerfile .
• show how you have to change kubernetes deployment script from remote repo:

image: <image_name>:latest
imagePullPolicy: Always

to local:

image: <image_url>:local
imagePullPolicy: Never

Add a bold note in Working with Images and Features (Images subsection) section that images from default namespace are not visible in kubernetes and have be forced into k8s.io namespace in order to be visible there. Current documentation only contains a cryptic somewhat hidden "oh and btw" in this segment:

The initial set of images are stored in the same containerd that Kubernetes uses, and are part of the k8s.io namespace. You can also switch to a namespace called default if you wish to build or pull images into a different namespace.

Which requires you to read the whole thing to find out such an important "default is not actually what you want..." information and is actually misleading as it gives you the feeling that "k8s.io" is the default namespace while "default" is actually the default nerdctl namespace.
It's possible that this information is valid on a different OS - can't check - but I'm using Linux and there it doesn't work as described (or I misunderstood the text completely which is probably also a documentation issue).

Maybe it's possible that Deployment yaml can be namespaced so that it looks in "default" nerdctl namespace for known images but my knowledge of that is non-existent atm... If it is then this namespace interaction should probably also be documented as the issue remains: you have to force namespace somewhere (be it in nerdctl or in Deployment yaml file) to get the "works out of the box" experience for default Rancher Desktop usecase.

Right now only the macOS screenshots include shadows, that separate them nicely from the page background.

Instead of including them in the images, we want to disable shadows in the macOS screenshots, and then add the shadows in the docs via CSS.

There's documentation for intentionally running Rancher Desktop offline, but there isn't documentation explaining how to find out why Rancher Desktop thinks it's offline when the user doesn't.

Why?

With the versioned docs rolled our from Rancher Desktop release 1.7.0, we need to maintain a set of images for every Rancher desktop minor release that goes out, and it increases the size of this repo as we do releases.

So, The idea of this issue is to store images elsewhere so that docs engineers do not have to clone all the images of all versions all the time. Some potential approaches are:

• Use a cloud storage solution such as AWS S3
• Maintain the images in a separate GitHub repo and link to the images from docs using raw urls
• Maintain the images in a separate branch in this repo and link to the images from docs using raw urls

The Introduction page shows a double-screenshot:

The Kubernetes settings have been moved from a main application page to the Preferences dialog a long time ago.

Ideally we should be able to create the image from the individual screenshots we already have.

If this is not possible, then we should have a script that uses e.g. imagemagick to create it from screenshots automatically, so it stays up-to-date from release to release.