App Environment Pods API

The App Environment Pods API allows you to retrieve pod-level details for an app environment in Quave Cloud. This provides granular information about individual container instances, useful for debugging and understanding pod health.

Make sure to read the Get Started document to understand how the API works.

Note: This API endpoint accepts only user tokens (not environment tokens).

Get App Environment Pods

To retrieve pod details for an app environment, send a GET request to the /api/public/v1/app-env/pods endpoint. You need to provide either appEnvId or envName to identify the environment.

Required Parameters (Either/Or)

You must provide either appEnvId or envName:

Parameter	Type	Description
appEnvId	String	The ID of the app environment to retrieve pods for.
envName	String	The CLI environment name (alternative to appEnvId).

Optional Parameters

Parameter	Type	Description
contentId	String	Filter pods by content version ID (only show pods for this version).

Response Structure

The response is a JSON object with the following fields:

Field	Type	Description
appEnvId	String	The app environment ID.
contentId	String	The content version ID filter (null if not provided).
pods	Array	Array of pod entries (see below).

Pod Entry

Each pod in the pods array contains:

Field	Type	Description
name	String	Pod name (e.g., "my-app-web-5f8a9b").
podId	String	Kubernetes UID for the pod.
status	String	Pod status (e.g., Running, Pending, Failed, Succeeded).
containerReady	Boolean	Whether the container passed readiness checks.
startedAt	Date	When the pod started (null if not started).
finishedAt	Date	When the pod finished/terminated (null if still running).
restartCount	Number	Number of times the container has restarted.
lastTermination	Object	Details of the last termination (null if never terminated).
resources	Object	Resource allocation for this pod.
nodeName	String	Kubernetes node where this pod is running (null if not scheduled).
contentId	String	Content version this pod is running (null if not available).
version	Number	Version number this pod is running (null if not available).

Last Termination Object

The lastTermination object (if present) contains:

Field	Type	Description
exitCode	Number	Container exit code (0 for successful exit).
reason	String	Reason for termination (e.g., OOMKilled, Error).
message	String	Detailed termination message.
finishedAt	Date	When the container terminated.

Resources Object

The resources object within each pod shows resource allocation:

Field	Type	Description
cpu	Number	CPU allocation in cores (null if not set).
memory	Number	Memory allocation in MB (null if not set).

Example: Get All Pods (with appEnvId)

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/pods?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7b'

Example: Get Pods (with envName)

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/pods?envName=production'

Example: Get Pods for Specific Version

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/pods?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7b&contentId=abc123def456'

Example Response

{
  "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
  "contentId": null,
  "pods": [
    {
      "name": "my-app-web-5f8a9b",
      "podId": "abc-123-def-456",
      "status": "Running",
      "containerReady": true,
      "startedAt": "2024-01-15T10:00:00.000Z",
      "finishedAt": null,
      "restartCount": 0,
      "lastTermination": null,
      "resources": {
        "cpu": 0.5,
        "memory": 256
      },
      "nodeName": "node-1",
      "contentId": "abc123def456",
      "version": 42
    },
    {
      "name": "my-app-web-7g9h1c",
      "podId": "ghi-789-jkl-012",
      "status": "Running",
      "containerReady": true,
      "startedAt": "2024-01-15T10:00:05.000Z",
      "finishedAt": null,
      "restartCount": 2,
      "lastTermination": {
        "exitCode": 137,
        "reason": "OOMKilled",
        "message": "Container was killed due to out of memory",
        "finishedAt": "2024-01-15T09:55:00.000Z"
      },
      "resources": {
        "cpu": 0.5,
        "memory": 256
      },
      "nodeName": "node-2",
      "contentId": "abc123def456",
      "version": 42
    }
  ]
}

Use Cases

This endpoint is useful for:

1. Debugging Restarts - Identify which pods are restarting and why
2. Health Monitoring - Check if containers are ready and healthy
3. Resource Issues - Identify OOMKilled pods (out of memory)
4. Distribution - See how pods are distributed across nodes
5. Version Validation - Verify all pods are running the expected version
6. Troubleshooting - Get detailed termination reasons for failed pods

Pod Status Values

Common status values:

• Running - Pod is actively running
• Pending - Pod is waiting to be scheduled or start
• Succeeded - Pod completed successfully (rare for long-running apps)
• Failed - Pod failed to run
• Unknown - Status cannot be determined
• CrashLoopBackOff - Pod is repeatedly crashing
• ContainerCreating - Container is being created
• Terminating - Pod is being terminated

Understanding Restarts

The restartCount field shows how many times a container has restarted:

• 0 restarts: Healthy pod running since first start
• 1-2 restarts: May be normal (transient failures)
• 3+ restarts: Indicates a problem (check lastTermination for details)
• High restart count: Container is in a crash loop

Common Termination Reasons

• OOMKilled - Container exceeded memory limit (needs more memory)
• Error - Container exited with non-zero status
• Completed - Container finished normally (exit code 0)
• ContainerCannotRun - Container failed to start
• DeadlineExceeded - Container took too long to become ready

Container Ready Status

The containerReady field indicates health check status:

• true: Container passed health checks and is receiving traffic
• false: Container failed health checks or hasn't passed yet
• Pods with containerReady: false won't receive user traffic

Filtering by Version

Use the contentId parameter to see pods for a specific deployment:

# Get current version's pods only
curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/pods?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7b&contentId=current-content-id'

This is useful during blue-green deployments to see which pods belong to which version.

Debugging Scenarios

Scenario: App is slow

1. Check if all pods have containerReady: true
2. Look for pods with high restartCount
3. Check if pods are OOMKilled (need more memory)

Scenario: Pods keep restarting

1. Check lastTermination.reason for the cause
2. If OOMKilled, increase memory allocation
3. If Error, check application logs for the pod

Scenario: Uneven load distribution

1. Check nodeName to see pod distribution
2. Verify all pods are Running with containerReady: true
3. Check if some pods have recent startedAt (newly restarted)

Error Responses

• 400 - Missing required parameters (neither appEnvId nor envName provided)
• 401 - User not authenticated
• 403 - User doesn't have permission to access this app environment
• 404 - App environment not found for the given appEnvId or envName

Notes

Environment Identification:

• You can use either appEnvId or envName to identify the environment
• If both are provided, appEnvId takes precedence

Pod Lifecycle:

• Pods are ephemeral and may be replaced at any time
• During deployments, you may see both old and new version pods
• Terminated pods may remain in the list temporarily

Empty Pods Array:

• If pods is empty, the environment may be stopped
• New environments may take a minute to show pods after first deployment