Debugging in OpenShift: A Beginner’s Guide

OpenShift, a powerful Kubernetes distribution by Red Hat, has quickly become a go-to platform for containerized applications. As with any platform, there might be instances where things don’t go as planned, and you’re left scratching your head. Fortunately, OpenShift offers a myriad of commands and tools to help you diagnose and remedy these hitches.

1. Understanding Access Levels in OpenShift

Before diving into troubleshooting, it’s essential to understand the access levels in OpenShift:

• Cluster Administrator: Manages the entire cluster, from adding nodes to assigning project quotas.
• Project Administrator: Manages resources inside a project, from setting resource limits to granting user permissions.
• Developer: Manages a subject of a project’s resources necessary for application build and deployment.

Your access level will determine the range of commands available to you. Generally, as a developer, you’d have project administrator right for any project you create.

2. Basic Commands to Start With

• oc status: Offers a concise overview of the project’s current state.
• oc get: Fetches summary information about various resources in your project, like whether a build failed or if a pod is ready.

These two commands are your first line of defense in understanding what’s happening in your environment.

3. Digging Deeper with Descriptions and Logs

If the status and get commands don’t offer enough clarity, it’s time to delve deeper:

• oc describe: This command displays detailed information about a specific resource, including its current state, configuration, and recent events.
• oc logs: Retrieves logs from runnable resources like pods and builds, crucial for diagnosing application-specific errors.

Notably, oc describe can follow relationships between resources. For instance, describing a build configuration would show information about the recent builds related to it. On the other hand, the -o option with the oc get command only displays details about the requested resource, without showing related entities.

4. Understanding Build Logs in OpenShift

When dealing with build logs, it’s crucial to know where to look:

• By Build Configuration with oc logs bc/<name>: Fetch logs from the latest build of the specified configuration.
• By Build Resource with oc logs build/<name>: Access logs from a particular build resource.
• By Build Pod with oc logs <pod-name>: Get logs directly from the temporary pod that performed the build.

The method you choose can vary based on your needs. Typically, if you want logs from a specific build, referencing by the build resource or build pod might be more direct.

5. Interactive Troubleshooting

For advanced debugging:

• oc cp and oc rsync: These commands offer a way to interact directly with the file system of running containers.
  - oc cp: Allows copying individual files or directories between the local filesystem and the container. This can be essential when you want to inject specific configuration files, scripts, or other resources for debugging purposes. Conversely, it’s also useful to extract logs or data from the container for offline analysis.
  - oc rsync: This is particularly useful when dealing with larger data sets or synchronizing entire directories. For instance, if a particular configuration directory has multiple files, and you suspect one of them could be causing the issue, oc rsync allows you to quickly pull all of them for examination on your local system.
• oc rsh: Allows you to remotely access and execute commands inside a running container. Adding the -t option lets you start an interactive shell session.

However, always remember: the commands available within a container via oc rsh depend on what’s installed in that container. Not all UNIX utilities might be present.

6. Environment Variables for Configurations

Many container images in OpenShift expect environment variables for configuration. Understanding and setting these can often resolve issues related to misconfiguration. For instance, the Node.js S2I builder image uses environment variables to determine npm module repositories. Ensuring these variables are set correctly can prevent build errors.

7. Network Debugging in OpenShift

Network problems can often be a primary cause for application issues in a platform like OpenShift. While I plan to pen an in-depth exploration of networking concerns in a future post, I felt the need to centralize basic debugging methods for now.

1. Service Endpoint Checks
   Before checking external connectivity via routes, ensure that internal service endpoints are correctly set up and accessible. oc get svc
   This command lists services in your namespace. Once you’ve identified the service of interest, describe it to view its endpoints: oc describe svc <service-name> | grep Endpoints
   The Endpointssection displays the IP addresses and ports for pods that back the service. If no endpoints are listed, it might indicate a potential problem with pod selectors or the pods themselves.
2. Route Checks
   Ensure the route is correctly set up and and points to the intended service: oc get route
   For detailed information about a specific route:
   oc describe route <route-name>
   Ensure the route’s host and the backend service are set up correctly.
3. Connectivity Checks Using curl
   Check connectivity to the route using ‘curl’:
   curl -I http://<route-hostname>
   The -I option fetches only the headers, providing quick feedback. A successful connection should return HTTP/1.1 200 OK or another 2xx/3xx status code. A 404 status means the route is accessible, but the application might not serve content at the root or provided path.

Conclusion

OpenShift offers a robust platform for your applications. Understanding its architecture and the tools at your disposal will ensure you can debug efficiently and keep your applications running smoothly.

Happy debugging!