Add troubleshooting guide on how to work locally with Podman when 'od…

…o dev' tries to push image components This seems to be quite common case, since it was already reported and explained twice. Ref redhat-developer#7224
rm3l · Mar 8, 2024 · ff28e9b · ff28e9b
1 parent 37e8a9a
commit ff28e9b
Showing 1 changed file with 256 additions and 0 deletions.
diff --git a/docs/website/docs/troubleshooting.md b/docs/website/docs/troubleshooting.md
@@ -305,3 +305,259 @@ $ ssh -v -i /path/to/ssh/key -NL 20001:127.0.0.1:20001 -l $user $podman_backend_
 Right after creating the SSH Tunnel in a separate terminal , you will be able to reach the port displayed by `odo` for port forwarding.
 
 More details on [SSH Tunneling](https://www.ssh.com/academy/ssh/tunneling).
+
+### I have an `image` component in my Devfile and `odo dev` on Podman errors out with `requested access to the resource is denied`
+
+#### Description
+
+You are iterating locally with Podman and have a Devfile more or less similar to the one below, in which you are building a local container image and starting a container component based on the image built.
+
+```yaml
+components:
+- image:
+    autoBuild: true
+    dockerfile:
+      buildContext: .
+      rootRequired: false
+      uri: Containerfile-web
+    imageName: web
+  name: webimage
+- container:
+    image: web
+  name: web
+metadata:
+  name: helloworld
+schemaVersion: 2.2.0
+```
+
+Running `odo dev --platform=podman` would error out with the following error message:
+
+```shell
+$ odo dev --platform=podman
+
+[...]
+↪ Building & Pushing Image: webimage                                                         
+ •  Building image locally  ... 
+[...]
+ ✓  Building image locally [23s]
+ •  Pushing image to container registry  ...
+[...]
+# highlight-start
+Error: writing blob: initiating layer upload to /v2/library/webimage/blobs/uploads/
+  in registry-1.docker.io: requested access to the resource is denied
+# highlight-end
+[...]
+```
+
+#### Possible causes
+
+In the example above, the `webimage` image component has `autoBuild` set to `true`, which means that it will be built automatically at start time.
+And when handling an image component, `odo dev` will try to build it **and** push it.
+In this case, because it is a relative image name (`imageName: web`), by default, the container engine tries to push it to `docker.io`. Therefore, we will need to:
+- either instruct `odo dev` not to push images built,
+- or set an `ImageRegistry` preference indicating where to push the images.
+
+If you instruct `odo dev` not to push images, `odo` might still fail when trying to create the pod on Podman, with an error similar to the following:
+```
+ ✗  Deploying pod [462ms]
+Error occurred on Push - exit status 125: 
+Complete Podman output:
+Trying to pull localhost/web:latest...
+Error: initializing source docker://localhost/web:latest:
+  pinging container registry localhost:
+    Get "https://localhost/v2/":
+      tls: failed to verify certificate:
+        x509: certificate is valid for *.apps-crc.testing, not localhost
+```
+This is because the `imagePullPolicy` is `Always` by default; Podman will try to pull the image, and uses `localhost` as the default search registry for relative image names.
+
+#### Recommended solution
+
+1. If the Container component in the Devfile uses the image built from an Image component, you'll need to override the Image Pull Policy, as depicted in [The Image Pull Policy of the dev container is `Always` and I cannot change it](#the-image-pull-policy-of-the-dev-container-is-always-and-i-cannot-change-it). From the example Devfile above, this would mean adding the following `container-overrides` attributes to the Container component:
+
+```yaml
+components:
+- image:
+    autoBuild: true
+    dockerfile:
+      buildContext: .
+      rootRequired: false
+      uri: Containerfile-web
+    imageName: web
+  name: webimage
+- container:
+    image: web
+  name: web
+# highlight-start
+  attributes:
+    container-overrides:
+      imagePullPolicy: IfNotPresent
+# highlight-end
+metadata:
+  name: helloworld
+schemaVersion: 2.2.0
+```
+
+2. The second step depends on whether you want to push the images built or not.
+
+##### If you do not want to push images or do not have access to a registry
+
+You need to instruct `odo dev` not to push image components since you don't have access to a registry. This can be done by setting the `ODO_PUSH_IMAGES` environment variable to `false`. See [Environment variables controlling `odo` behavior](./overview/configure.md#environment-variables-controlling-odo-behavior).
+
+```shell
+ODO_PUSH_IMAGES=false odo dev --platform podman
+```
+
+<details>
+<summary>Example Output</summary>
+
+```shell
+$ ODO_PUSH_IMAGES=false odo dev --platform podman
+  __
+ /  \__     Developing using the "helloworld" Devfile
+ \__/  \    Platform: podman
+ /  \__/    odo version: v3.15.0 (b403a1bfb)
+ \__/
+
+↪ Running on podman in Dev mode
+ ✓  Web console accessible at http://localhost:20000/ 
+ ✓  API Server started at http://localhost:20000/api/v1 
+ ✓  API documentation accessible at http://localhost:20000/swagger-ui/ 
+
+↪ Building Image: web
+ •  Building image locally  ...
+STEP 1/8: FROM python:3.12
+STEP 2/8: ENV PYTHONUNBUFFERED 1
+--> Using cache 380bc9cde8e1ea3af6511d1555288e5771e11eab7cafc508e62eb65a0c283a4c
+--> 380bc9cde8e1
+STEP 3/8: WORKDIR /app
+--> Using cache 3b9fdb6786929f522c70bc75af33ef97cd53e56fbfadd7df70ffb283249a9180
+--> 3b9fdb678692
+STEP 4/8: COPY requirements.txt /app/
+--> Using cache b35333848f81df494194f23be0540f308033d2a002db004e06fa7b349650af11
+--> b35333848f81
+STEP 5/8: RUN pip install -r requirements.txt
+--> Using cache a55bb417c97be3072d923b59001f918554ffe5d4e46982a524f246c3d951c8fc
+--> a55bb417c97b
+STEP 6/8: COPY ./helloworld /app/
+--> Using cache be5ec312ad362a4932c32b12db084c9b90450cd95ad58ccd8b92f6c8f48e625b
+--> be5ec312ad36
+STEP 7/8: RUN python3 manage.py makemigrations polls
+--> Using cache 15cc24d28d245e4ef3e1055b7cfe8bae1ac6c784fcbb66c8d04063e45b2a8ed4
+--> 15cc24d28d24
+STEP 8/8: CMD ["sh", "-c", "python manage.py migrate && python manage.py runserver 0.0.0.0:8000"]
+--> Using cache 1af836519aea46df4787526fc2a8aed578ae48dca0f2f5cf8d83641923ce098e
+COMMIT web
+--> 1af836519aea
+Successfully tagged localhost/web:latest
+1af836519aea46df4787526fc2a8aed578ae48dca0f2f5cf8d83641923ce098e
+ ✓  Building image locally [572ms]
+ ✓  Deploying pod [629ms]
+ ✓  Syncing files into the container [416ms]
+================================
+⚠  Missing default run command
+================================
+
+↪ Dev mode
+ Status:
+ Watching for changes in the current directory /tmp/odo-test/podman-django-template
+
+Web console accessible at http://localhost:20000/
+
+Keyboard Commands:
+[Ctrl+c] - Exit and delete resources from podman
+     [p] - Manually apply local changes to the application on podman
+```
+</details>
+
+##### If you want to push images to a registry
+
+You can set the `ImageRegistry` preference to a registry where you have access. See [How `odo` handles image names](./development/devfile.md#how-odo-handles-image-names) for further details.
+
+Note that Podman will need to be able to pull images from that location.
+
+```
+odo preference set ImageRegistry quay.io/$USER
+```
+
+Now running `odo dev --platform=podman` should work by pushing and pulling the images built from that location.
+
+<details>
+<summary>Example Output</summary>
+
+```shell
+$ odo dev --platform podman
+  __
+ /  \__     Developing using the "helloworld" Devfile
+ \__/  \    Platform: podman
+ /  \__/    odo version: v3.15.0 (b403a1bfb)
+ \__/
+
+↪ Running on podman in Dev mode
+ ✓  Web console accessible at http://localhost:20000/ 
+ ✓  API Server started at http://localhost:20000/api/v1 
+ ✓  API documentation accessible at http://localhost:20000/swagger-ui/ 
+
+↪ Building & Pushing Image: quay.io/user/helloworld-web:1624742
+ •  Building image locally  ...
+STEP 1/8: FROM python:3.12
+STEP 2/8: ENV PYTHONUNBUFFERED 1
+--> Using cache d14586395ed0e0dc42f172ed1ca62b37a210f0e668221c9343d9b63afc819e80
+--> d14586395ed0
+STEP 3/8: WORKDIR /app
+--> Using cache 3185ec931b843857a9cfe8aa367fb77d1cfe39ef6c96fde6e0acd9a5c0975673
+--> 3185ec931b84
+STEP 4/8: COPY requirements.txt /app/
+--> Using cache d5f0e542165e77a59fac49dc0fa418dc759e56e17153c2c9ccbc2d8043872046
+--> d5f0e542165e
+STEP 5/8: RUN pip install -r requirements.txt
+--> Using cache b8e2815a4ef279cfd40f180c8c94e24b60adf934e17ba94bb398c556979054b7
+--> b8e2815a4ef2
+STEP 6/8: COPY ./helloworld /app/
+--> Using cache df77575d7573f24812772e5e99172735c0536ea0109e3050a3c2923875f14dac
+--> df77575d7573
+STEP 7/8: RUN python3 manage.py makemigrations polls
+--> Using cache d347f04dc1b05561c0816d2c649bd0d5fabbf87c3074d4d403ba7e98c83cbdaa
+--> d347f04dc1b0
+STEP 8/8: CMD ["sh", "-c", "python manage.py migrate && python manage.py runserver 0.0.0.0:8000"]
+--> Using cache 7a942a913e712f51370d50470bef4b6445b68fbc72d5fae1cfe0934dc0487f02
+COMMIT quay.io/user/helloworld-web:1624742
+--> 7a942a913e71
+Successfully tagged quay.io/user/helloworld-web:1624742
+Successfully tagged localhost/web:latest
+7a942a913e712f51370d50470bef4b6445b68fbc72d5fae1cfe0934dc0487f02
+ ✓  Building image locally [596ms]
+ •  Pushing image to container registry  ...
+Getting image source signatures
+Copying blob 84f540ade319 done   | 
+Copying blob a07a24a37470 done   | 
+Copying blob 9fe4e8a1862c done   | 
+Copying blob f3f47b3309ca done   | 
+Copying blob 909275a3eaaa done   | 
+Copying blob 1a5fc1184c48 done   | 
+Copying blob 349b0b22a493 done   | 
+Copying blob 3dd1a7b3caf3 done   | 
+Copying blob c5873de99713 done   | 
+Copying blob 4769db4ebaab done   | 
+Copying blob 08b88032f3bc done   | 
+Copying blob 614964f5ff0f done   | 
+Copying config 7a942a913e done   | 
+Writing manifest to image destination
+ ✓  Pushing image to container registry [2m]
+ ✓  Deploying pod [745ms]
+ ✓  Syncing files into the container [335ms]
+================================
+⚠  Missing default run command
+================================
+
+↪ Dev mode
+ Status:
+ Watching for changes in the current directory /tmp/odo-test/podman-django-template
+
+Web console accessible at http://localhost:20000/
+
+Keyboard Commands:
+[Ctrl+c] - Exit and delete resources from podman
+     [p] - Manually apply local changes to the application on podman
+```
+</details>