# List Nodes with Resource Information

### Endpoint

`POST /api/k8s/v2/nodes/info-with-resources`

### Authentication

This endpoint requires API key authentication.

### Headers

| Header          | Value                   | Description              |
| --------------- | ----------------------- | ------------------------ |
| `Authorization` | `Bearer <YOUR_API_KEY>` | Your groundcover API key |
| `Content-Type`  | `application/json`      | Request body format      |
| `X-Backend-Id`  | `<YOUR_BACKEND_ID>`     | Your backend identifier  |

### Request Body

| Field     | Type      | Required | Description                                      |
| --------- | --------- | -------- | ------------------------------------------------ |
| `start`   | `string`  | Yes      | Start time in ISO 8601 UTC format                |
| `end`     | `string`  | Yes      | End time in ISO 8601 UTC format                  |
| `sources` | `array`   | No       | Source filters (e.g., cluster filters)           |
| `limit`   | `integer` | No       | Maximum number of nodes to return (default: 100) |

#### Sources Structure (Cluster Filter)

```json
{
  "key": "cluster",
  "type": "string",
  "origin": "root", 
  "filters": [
    {
      "op": "eq",
      "value": "cluster-name"
    }
  ]
}
```

### Example Request

```bash
curl -L \
  --request POST \
  --url 'https://api.groundcover.com/api/k8s/v2/nodes/info-with-resources' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --data '{
    "start": "2025-01-27T12:00:00.000Z",
    "end": "2025-01-27T14:00:00.000Z",
    "sources": [
      {
        "key": "cluster",
        "type": "string",
        "origin": "root",
        "filters": [
          {
            "op": "eq",
            "value": "my-cluster"
          }
        ]
      }
    ],
    "limit": 100,
    "nameFilter": ""
  }'
```

### Response

```json
{
  "nodes": [
    {
      "uid": "node-uid",
      "name": "node-name",
      "cluster": "cluster-name",
      "env": "environment-name",
      "creationTimestamp": "2025-01-01T10:00:00Z",
      "labels": {
        "kubernetes.io/arch": "amd64",
        "kubernetes.io/os": "linux",
        "node.kubernetes.io/instance-type": "t3.medium"
      },
      "addresses": [
        {
          "type": "InternalIP",
          "address": "10.0.1.100"
        },
        {
          "type": "ExternalIP", 
          "address": "203.0.113.100"
        }
      ],
      "nodeInfo": {
        "kubeletVersion": "v1.24.0",
        "kubeProxyVersion": "v1.24.0",
        "operatingSystem": "linux",
        "architecture": "amd64",
        "containerRuntimeVersion": "containerd://1.6.0",
        "kernelVersion": "5.4.0-91-generic",
        "osImage": "Ubuntu 20.04.3 LTS"
      },
      "capacity": {
        "cpu": "2",
        "memory": "8Gi",
        "pods": "110"
      },
      "allocatable": {
        "cpu": "1940m",
        "memory": "7Gi", 
        "pods": "110"
      },
      "usage": {
        "cpu": "500m",
        "memory": "3Gi"
      },
      "ready": true,
      "conditions": [
        {
          "type": "Ready",
          "status": "True",
          "lastTransitionTime": "2025-01-01T10:05:00Z",
          "reason": "KubeletReady",
          "message": "kubelet is posting ready status"
        }
      ]
    }
  ]
}
```

### Response Fields

| Field                       | Type      | Description                                            |
| --------------------------- | --------- | ------------------------------------------------------ |
| `nodes`                     | `array`   | Array of node objects                                  |
| `nodes[].uid`               | `string`  | Unique identifier for the node                         |
| `nodes[].name`              | `string`  | Node name                                              |
| `nodes[].cluster`           | `string`  | Cluster name                                           |
| `nodes[].env`               | `string`  | Environment name                                       |
| `nodes[].creationTimestamp` | `string`  | Node creation time in ISO 8601 format                  |
| `nodes[].labels`            | `object`  | Node labels key-value pairs                            |
| `nodes[].addresses`         | `array`   | Node IP addresses (internal/external)                  |
| `nodes[].nodeInfo`          | `object`  | Node system information                                |
| `nodes[].capacity`          | `object`  | Total node resource capacity                           |
| `nodes[].allocatable`       | `object`  | Allocatable resources (capacity minus system reserved) |
| `nodes[].usage`             | `object`  | Current resource usage                                 |
| `nodes[].ready`             | `boolean` | Node readiness status                                  |
| `nodes[].conditions`        | `array`   | Node condition details                                 |

### Filter Operations

| Operator   | Description        |
| ---------- | ------------------ |
| `eq`       | Equals             |
| `ne`       | Not equals         |
| `gt`       | Greater than       |
| `lt`       | Less than          |
| `contains` | Contains substring |

### Common Use Cases

#### Get All Nodes

```json
{
  "start": "2025-01-27T12:00:00.000Z",
  "end": "2025-01-27T14:00:00.000Z",
  "limit": 100
}
```

#### Filter by Specific Cluster

```json
{
  "start": "2025-01-27T12:00:00.000Z",
  "end": "2025-01-27T14:00:00.000Z",
  "sources": [
    {
      "key": "cluster",
      "type": "string", 
      "origin": "root",
      "filters": [{"op": "eq", "value": "production-cluster"}]
    }
  ],
  "limit": 100
}
```