diff --git a/docs/website/docs/command-reference/_category_.json b/docs/website/docs/command-reference/_category_.json index 61efddf4c7d..771cffab120 100644 --- a/docs/website/docs/command-reference/_category_.json +++ b/docs/website/docs/command-reference/_category_.json @@ -1,4 +1,4 @@ { "label": "Command Reference", - "position": 4 + "position": 5 } \ No newline at end of file diff --git a/docs/website/docs/overview/_category_.json b/docs/website/docs/overview/_category_.json index ac38177418c..2dcd1ed831b 100644 --- a/docs/website/docs/overview/_category_.json +++ b/docs/website/docs/overview/_category_.json @@ -1,5 +1,5 @@ { "label": "Overview", - "position": 1, + "position": 2, "collapsed": false } diff --git a/docs/website/docs/troubleshooting.md b/docs/website/docs/troubleshooting.md new file mode 100644 index 00000000000..0a3433f9082 --- /dev/null +++ b/docs/website/docs/troubleshooting.md @@ -0,0 +1,203 @@ +--- +sidebar_position: 4 +title: Troubleshooting +toc_min_heading_level: 2 +toc_max_heading_level: 3 +--- + +This page documents possible solutions for the most common issues reported by users. + +If your issue is not listed here, feel free to reach out to the team in the [#odo channel](https://kubernetes.slack.com/archives/C01D6L2NUAG) on the [Kubernetes Slack](http://slack.k8s.io/). +Or you can also [file an issue](https://github.com/redhat-developer/odo/issues/new/choose) or [start a new discussion](https://github.com/redhat-developer/odo/discussions). + +[//]: # (## Generic issues) + +## Authentication issues + +### `odo deploy` is failing to push container image components due to 401 errors + +#### Description + +`odo` is failing to push the Image component from the Devfile. It looks like it is trying to push images to the `docker.io` registry. + +
+ Example output + +```shell +$ odo deploy + __ + / \__ Running the application in Deploy mode using go Devfile + \__/ \ Namespace: my-test-project-1 + / \__/ odo version: v3.9.0 + \__/ + +↪ Building & Pushing Image: go-image:latest + • Building image locally ... +[...] +Successfully tagged localhost/go-image:latest +62cbfab7488bcb420404a7be564bb9a41dd2550c027e00fc9ca7037ae98cd193 + ✓ Building image locally [4s] + • Pushing image to container registry ... +Getting image source signatures +Error: trying to reuse blob sha256:314640f419c581ddcac8f3618af39342a4571d5dc7a4e1f5b64d60f37e630b49 at destination: checking whether a blob sha256:314640f419c581ddcac8f3618af39342a4571d5dc7a4e1f5b64d60f37e630b49 exists in docker.io/library/go-image: errors: +denied: requested access to the resource is denied +error parsing HTTP 401 response body: unexpected end of JSON input: "" + + ✗ Pushing image to container registry [507ms] + ✗ error running podman command: exit status 125 +``` + +
+ +This most commonly happens with `odo deploy`, but might also happen with `odo dev` if an Image component is included in the Devfile as part of the inner-loop workflow. + +#### Possible Causes + +The most common cause for this issue is that the Image component from the local Devfile is using a relative name in its `imageName` field. +For example: + +```yaml +[...] +components: +- name: image-build + image: + # highlight-next-line + imageName: go-image:latest + dockerfile: + uri: docker/Dockerfile + buildContext: . + rootRequired: false +``` + +Note that we recommend using relative image names to keep the Devfile portable. + +#### Recommended Solution + +As of `odo` [v3.11.0](/blog/odo-v3.11.0#handling-imagename-in-image-component-as-a-selector), we are handling relative image names as selectors, provided that you locally indicate to `odo` a registry where to push those relative images. +See [How `odo` handles image names](./development/devfile.md#how-odo-handles-image-names) for more details. + +To fix this issue, use the command below to set your `ImageRegistry` preference before calling `odo deploy`. + +```shell +odo preference set ImageRegistry $registry +``` + +
+ Example output + +```shell +$ odo preference set ImageRegistry quay.io/$USER + ✓ Value of 'imageregistry' preference was set to 'quay.io/user' +``` + +
+ + + +[//]: # (## Devfile issues) + +## Dev Sessions issues + +### I'm getting "Permission denied" errors when `odo dev` is syncing files + +#### Description +When running `odo dev` against certain clusters, the `Syncing files into the container` stage fails due to "Permission denied" errors. + +
+ Example output + +```shell +$ odo dev + __ + / \__ Developing using the "places" Devfile + \__/ \ Namespace: default + / \__/ odo version: v3.10.0 + \__/ + + ⚠ You are using "default" namespace, odo may not work as expected in the default namespace. + ⚠ You may set a new namespace by running `odo create namespace `, or set an existing one by running `odo set namespace ` + +↪ Running on the cluster in Dev mode + • Waiting for Kubernetes resources ... + ⚠ Pod is Pending + ✓ Pod is Running + ◐ Syncing files into the container ✗ Command 'tar xf - -C /projects --no-same-owner' in container failed. + + ✗ stdout: + + ✗ stderr: tar: main.go: Cannot open: Permission denied +tar: .gitignore: Cannot open: Permission denied +tar: README.md: Cannot open: Permission denied +tar: devfile.yaml: Cannot open: Permission denied +tar: go.mod: Cannot open: Permission denied +tar: Exiting with failure status due to previous errors + + + ✗ err: error while streaming command: command terminated with exit code 2 + + ✗ Syncing files into the container [4s] +Error occurred on Push - watch command was unable to push component: failed to sync to component with name places: failed to sync to component with name places: unable push files to pod: error while streaming command: command terminated with exit code 2 + + +↪ Dev mode + Status: + Watching for changes in the current directory /tmp/go-app + + Keyboard Commands: +[Ctrl+c] - Exit and delete resources from the cluster + [p] - Manually apply local changes to the application on the cluster +``` + +
+ +#### Possible Causes + +Various factors are responsible for this: + +- Storage Provisioner used for the cluster +- User set by the container image +- Location on the container where the files are to be synced +- Using Ephemeral vs Non-Ephemeral Volumes + +#### Recommended Solution + +Please refer to [Troubleshoot Storage Permission issues on managed cloud providers clusters](./user-guides/advanced/using-odo-with-other-clusters.md) for possible solutions to fix this. + +## Podman Issues + +### `odo` says it cannot access Podman + +#### Description + +`odo dev --platform podman` fails to start with the following error: + +``` +✗ unable to access podman.Do you have podman client installed and configured correctly? +cause: executable "podman" not recognized as podman client +``` + +This seems flaky however, because sometimes it works. + +#### Possible Causes + +When initializing our connector to Podman, we have a default timeout of 1 second for the Podman executable to respond. +For some reason, `odo` sometimes might not be able to get a response from Podman during this short period of time. + +#### Recommended Solution + +First make sure the `podman version -f json` command returns in a timely manner on your system. +If the `podman` command cannot be found, please make sure Podman is installed correctly and available on your system path. +Or you can set the `PODMAN_CMD` environment variable to indicate where `odo` can find the `podman` executable, for example: + +```shell +export PODMAN_CMD=/absolute/path/to/podman +``` + +If the `podman` executable is available, you can increase the timeout using the `PODMAN_CMD_INIT_TIMEOUT` environment variable. +You can increase this timeout before running `odo` and this should hopefully fix the issue, for example: + +```shell +export PODMAN_CMD_INIT_TIMEOUT=10s +``` + +Please [file an issue](https://github.com/redhat-developer/odo/issues/new/choose) if the problem persists. diff --git a/docs/website/docs/user-guides/_category_.json b/docs/website/docs/user-guides/_category_.json index 9e4194493e1..536e702fcf3 100644 --- a/docs/website/docs/user-guides/_category_.json +++ b/docs/website/docs/user-guides/_category_.json @@ -1,5 +1,5 @@ { "label": "User Guides", - "position": 2, + "position": 3, "collapsed": false } diff --git a/docs/website/docs/user-guides/advanced/_category_.json b/docs/website/docs/user-guides/advanced/_category_.json index 68a7b652565..d59e12e4db8 100644 --- a/docs/website/docs/user-guides/advanced/_category_.json +++ b/docs/website/docs/user-guides/advanced/_category_.json @@ -1,5 +1,5 @@ { "label": "Advanced Usage", "position": 3, - "collapsed": false, + "collapsed": true }