github.com/openshift/source-to-image@v1.4.1-0.20240516041539-bf52fc02204e/docs/debugging-s2i.md (about)

     1  
     2  Troubleshooting
     3  =================
     4  
     5  This document contains some tips and suggestions for troubleshooting the use of source-to-image ("s2i") to build Docker images.
     6  
     7  Can't Find The `s2i` Executable
     8  --------------
     9  
    10  Whether by  running `make build` or `hack/build-release.sh`, look under the `_output/local/go/bin` directory.
    11  
    12  If you have downloaded one of the official releases (see [releases](https://github.com/openshift/source-to-image/releases)), the `s2i` executable is the only file in the tar archive.
    13  
    14  Security And Docker
    15  --------------
    16  
    17  As noted [here](https://github.com/openshift/source-to-image/#security), there are considerations to allow S2I to interact with Docker, including possibly running `sudo s2i`.
    18  
    19  Image Mechanics
    20  --------------
    21  
    22  By default, s2i will use the local builder image if available on the host from
    23  which you are running the `s2i` command. However, if you want to always pull
    24  the image from the remote Docker repository to be sure that you are not using
    25  stale and out of date image you should provide `--pull-policy=always` option
    26  when running the `s2i` command.
    27  
    28  Permissions Needed During the S2I Process
    29  --------------
    30  
    31  The s2i process will leverage the `/tmp` directory at various stages, such as when cloning the source repository, when augmenting the Dockerfile for layered builds, during various `tar` operations that are performed, and when executing the scripts you have provided.  Invalid permissions will result in a message like this:
    32  
    33       E0720 21:07:17.145257 04202 main.go:328] An error occurred: creating temporary directory  failed
    34  
    35  Hence, the user ID you execute the `s2i` command with must have the appropriate permission to read, create, and remove files under `/tmp`.
    36  
    37  Passing In Environment Variables
    38  --------------
    39  
    40  If you are passing in environment variables with the -e option from the command line, and those environment variables have values with commas in them, Go command line processing will break.
    41  
    42         $ s2i build --loglevel=5 -e "MAVEN_ARGS='-P some-repo,some-other-repo'" file:///home/mfojtik/sandbox/ruby openshift/ruby-20-centos7 foo
    43         	 I0519 14:20:51.410089 17228 util.go:34] Using my@cred.sk credentials for pulling openshift/ruby-20-centos7
    44       	 I0519 14:20:51.410222 17228 main.go:239] An error occurred: malformed env string: some-other-repo'
    45  
    46  To deal with this behavior, s2i by default will look for environment variables in the file `.s2i/environment` in your source repository.  You can also point to a separate file with environment variable settings with the -E option.
    47  With both approaches, leveraging a file instead of the command line allows for the values of environment variable to contain commas.  Environment variable processing is described in the [README](https://github.com/openshift/source-to-image#anatomy-of-a-builder-image) as well.
    48  
    49  With the above example, whichever file you leverage for environment variables would have this line:
    50  
    51  
    52  ```
    53  MAVEN_ARGS='-P some-repo,some-other-repo'
    54  ```
    55  
    56  
    57  Providing S2I Scripts
    58  --------------
    59  
    60  First, a basic reminder:  you should verify your scripts have executable permissions.
    61  
    62  Then, a few of the trickier obstacles that have arisen for users in the past:
    63  
    64  #### Interfacing With `tar`
    65  
    66  As noted [here](https://github.com/openshift/source-to-image/blob/master/docs/builder_image.md#save-artifacts), if you employ a `save-artifacts` script, that script is responsible for properly receiving tar streams.  Issues with `tar` stream processing could result in messages like:
    67  
    68  	      W0720 21:07:52.145257 04204 sti.go:131 Clean build will be performed because of error saving previous build artifacts
    69  	      E0720 21:07:52.145263 04204 sti.go:133] ERROR: timeout waiting for tar stream
    70  
    71  
    72  Review the example [here](https://github.com/gabemontero/source-to-image/blob/master/docs/builder_image.md#save-artifacts), and perhaps revisit the tar man pages or the bash user manual, to help address any problems.
    73  
    74  
    75  #### Dowloading / Finding The Scripts
    76  
    77  Per this discussion point  [here](https://github.com/openshift/source-to-image/blob/master/docs/builder_image.md#s2i-scripts), if your s2i related scripts are already placed in the image, but their locations are not indicated by one of the provided means, attempts to download the scripts will fail.
    78  
    79     	E0720 21:08:37.166063 04204 main.go:328] An error occurred: scripts inside the image:  image:///path/to/image
    80  
    81  Properly reference the script location with the methods described in the above link.
    82  
    83  
    84  #### ONBUILD
    85  
    86  At various points when executing ONBUILD instructions (these are defined in the Dockerfile of the builder image you are using with s2i), if those instructions result in the need for root user access, but your builder image is not configured to run as root,
    87  then attempts to reference that image in another Dockerfile will result in permission errors.
    88  
    89  If you consider the following Dockerfile pseudo-example:
    90  
    91  ```
    92  FROM foo
    93  USER root
    94  RUN some-root-operation
    95  ONBUILD some-root-operation
    96  USER joe
    97  ```
    98  
    99  You will be able to Docker build the image, but when you then reference that image in another Dockerfile, things will fail because the ONBUILD commands will execute as "joe" and not "root".
   100  
   101  Must Gather
   102  -----------
   103  If you find yourself still stuck, before seeking help in #openshift on freenode.net, please recreate your issue and gather the following:
   104  
   105  1. s2i logs at level 5 (verbose logging):
   106  
   107          $ s2i < other options >  --loglevel=5 &> /tmp/s2i.log
   108  
   109  2. Container logs
   110  
   111      The following bit of scripting will pull logs for **all** containers that have been run on your system.  This might be excessive if you don't keep a clean history, so consider manually grabbing logs for the relevant containers instead:
   112  
   113          for container in $(docker ps -aq); do
   114              docker logs $container >& $LOG_DIR/container-$container.log
   115          done
   116  
   117  3. By default, the working directory under `/tmp` is removed when the `s2i` command completes.  The `--save-temp-dir=true` option will preserve the working directory under `/tmp`.  Those files can often provide useful diagnostics.
   118  
   119  
   120  
   121  Debugging Integration Test Failures
   122  --------------
   123  
   124  For diagnosing failures when running hack/test-integration.sh, passing the -v option to the hack/test-integration.sh script will not only turn on verbose bash tracing, but will set --loglevel=5 tracing for the S2I internals, in
   125  order to provide additional details that can help diagnose issues.