106 lines
2.8 KiB
Plaintext
106 lines
2.8 KiB
Plaintext
# skill_digest: 651e129c7e0478c097161a76655c9f54e3566f5510368426e68d88fbbceb77b9
|
|
## Debugging ImagePullBackOff Error
|
|
|
|
ImagePullBackOff indicates Kubernetes cannot pull the container image. Let's investigate step by step.
|
|
|
|
### Step 1: Find the Failed Pod
|
|
|
|
First, identify which pipeline and pod is failing:
|
|
|
|
```bash
|
|
# List recent PipelineRuns
|
|
kubectl get pipelinerun -n <namespace> --sort-by=.metadata.creationTimestamp
|
|
|
|
# Or if you know the PipelineRun name:
|
|
kubectl get pipelinerun <pr-name> -n <namespace>
|
|
|
|
# Find the associated TaskRuns
|
|
kubectl get taskruns -l tekton.dev/pipelineRun=<pr-name> -n <namespace>
|
|
|
|
# Find the pod with the issue
|
|
kubectl get pods -n <namespace> | grep ImagePullBackOff
|
|
```
|
|
|
|
### Step 2: Check Pod Events
|
|
|
|
Once you've identified the pod, check the events for specific details:
|
|
|
|
```bash
|
|
kubectl describe pod <pod-name> -n <namespace> | grep -A10 "Events"
|
|
```
|
|
|
|
This will show you:
|
|
- **Exact image name** that failed to pull
|
|
- **Error reason** (authentication failed, not found, etc.)
|
|
- **Registry** being accessed
|
|
|
|
### Step 3: Common Root Causes & Fixes
|
|
|
|
**A. Image Name/Tag Typo**
|
|
- Check if the image name and tag are spelled correctly
|
|
- Verify the image actually exists in the registry
|
|
|
|
**B. Registry Authentication**
|
|
```bash
|
|
# Check if ServiceAccount has imagePullSecrets
|
|
kubectl get sa <service-account-name> -n <namespace> -o yaml
|
|
|
|
# Check if the secret exists
|
|
kubectl get secrets -n <namespace>
|
|
```
|
|
|
|
**Fix**: Add imagePullSecret to your ServiceAccount:
|
|
```yaml
|
|
apiVersion: v1
|
|
kind: ServiceAccount
|
|
metadata:
|
|
name: <sa-name>
|
|
imagePullSecrets:
|
|
- name: <registry-secret-name>
|
|
```
|
|
|
|
**C. Private Registry - Missing Credentials**
|
|
```bash
|
|
# Create a docker registry secret
|
|
kubectl create secret docker-registry <secret-name> \
|
|
--docker-server=<registry-url> \
|
|
--docker-username=<username> \
|
|
--docker-password=<password> \
|
|
--docker-email=<email> \
|
|
-n <namespace>
|
|
```
|
|
|
|
**D. Image Doesn't Exist**
|
|
- Verify the image exists in your registry
|
|
- Check if the tag is correct (common issue: using `latest` when it doesn't exist)
|
|
|
|
**E. Network/Registry Issues**
|
|
```bash
|
|
# Check if the registry is accessible from the cluster
|
|
kubectl run test-pull --image=<your-image> -n <namespace> --rm -it --restart=Never
|
|
```
|
|
|
|
### Quick Diagnosis Commands
|
|
|
|
Run these to gather all relevant info:
|
|
|
|
```bash
|
|
# Get full pod details
|
|
kubectl describe pod <pod-name> -n <namespace>
|
|
|
|
# Check the TaskRun spec for image references
|
|
kubectl get taskrun <tr-name> -n <namespace> -o yaml | grep -A2 "image:"
|
|
|
|
# View ServiceAccount configuration
|
|
kubectl get sa -n <namespace> -o yaml
|
|
```
|
|
|
|
---
|
|
|
|
**Next Steps:**
|
|
1. Run the commands above with your actual namespace and resource names
|
|
2. Share the output from `kubectl describe pod` (especially the Events section)
|
|
3. I can help you identify the exact cause and create the appropriate fix
|
|
|
|
What's your namespace and do you know the PipelineRun or pod name that's failing?
|