---
title: "규칙 오버라이드 API"
description: "Alpacon 서버별 경고 규칙 오버라이드를 위한 REST API 레퍼런스. 서버 하나에만 다른 임계값·복귀 임계값·지속 시간을 지정하거나, 워크스페이스 경고 규칙에서 완전히 제외합니다."
---

> Full documentation index: https://docs.alpacax.com/llms.ko.txt

# 규칙 오버라이드 API

**엔드포인트**: `/api/metrics/rule-overrides/`

오버라이드는 서버 하나가 자신이 붙어 있는 [경고 규칙](/reference/api/metrics/rules/)에서 벗어나는 예외입니다. 그 서버만의 임계값, 복귀 임계값, 지속 시간을 따로 두거나, 규칙 자체에서 아예 제외할 수 있습니다. 다른 서버에는 영향을 주지 않습니다. 콘솔에서는 서버 상세의 **규칙** 탭에서 같은 설정을 할 수 있습니다([서버별 재정의](/use/metrics/rules/#서버별-설정) 참고). 오버라이드가 규칙 동작에 어떻게 반영되는지는 [메트릭 알림](/use/servers/monitor/#메트릭-알림)을 참고하세요.

워크스페이스에서 Metrics 확장 기능이 켜져 있어야 하며, 이 자격 증명이 이미 관리할 수 있는 서버에만 접근할 수 있습니다. 다른 서버를 지정하면 찾을 수 없는 것으로 응답합니다.

## 오버라이드 관리 권한

[핵심 디스크 사용률 규칙](/reference/api/metrics/rules/#핵심-디스크-사용률-규칙)을 제외한 모든 규칙의 오버라이드는 평소와 같은 [`rule_override` 권한 범위](/reference/scopes/#rule_override)를 따릅니다. 이 핵심 규칙만은 예외로, 오버라이드를 생성·수정·삭제하거나 오버라이드를 이 규칙으로 옮기거나 이 규칙에서 다른 규칙으로 옮기는 것은 워크스페이스 관리자만 할 수 있습니다. `operator`와 모든 서비스 토큰은 요청 본문을 검사하기도 전에 403 `metrics_alert_rule_core_admin_only`를 받습니다.

## 규칙 오버라이드 목록 조회

규칙 오버라이드 목록을 페이지네이션하여 가져옵니다.

```http
GET /api/metrics/rule-overrides/
```

### 쿼리 파라미터

| 파라미터 | 타입 | 설명 |
|-----------|------|-------------|
| `server` | string (UUID) | 서버 ID로 필터링 |
| `rule` | string (UUID) | 경고 규칙 ID로 필터링 |
| `enabled` | boolean | 오버라이드 활성 여부로 필터링 (`false`가 제외 상태) |
| `search` | string | 서버명, 규칙명으로 검색 |
| `ordering` | string | 정렬 순서 (예: `added_at`, `-updated_at`). 기본값: `-added_at` |
| `page` | integer | 페이지 번호 |
| `page_size` | integer | 페이지당 결과 수 (기본값: 15, 최대: 100) |

### 응답

```json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "server": {
        "id": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8",
        "name": "web-server-01",
        "os": "Ubuntu 22.04",
        "is_connected": true
      },
      "rule": "8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e",
      "threshold": 90,
      "recovery_threshold": 80,
      "duration_s": null,
      "enabled": true,
      "added_at": "2026-09-10T09:00:00Z",
      "updated_at": "2026-09-10T09:00:00Z"
    }
  ]
}
```

필요한 스코프: [`rule_override:read`](/reference/scopes/#rule_override-read)

### 예시

```bash
curl -X GET "https://your-workspace.ap1.alpacon.io/api/metrics/rule-overrides/?server=7e3984de-49ab-4cc6-bcdf-21fbd35858b8" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
```

## 규칙 오버라이드 생성

서버 하나에 그 규칙만의 값을 지정하거나, 규칙에서 제외합니다.

```http
POST /api/metrics/rule-overrides/
```

### 요청 본문

```json
{
  "server": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8",
  "rule": "8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e",
  "threshold": 90,
  "recovery_threshold": 80
}
```

### 요청 파라미터

| 필드 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `server` | string (UUID) | Yes | 오버라이드를 적용할 서버. 이 자격 증명이 관리할 수 있는 서버여야 함 |
| `rule` | string (UUID) | Yes | 오버라이드할 경고 규칙 |
| `threshold` | number | No | 이 서버에 한해 규칙의 임계값을 대체. 비워 두면 규칙의 값을 그대로 사용 |
| `recovery_threshold` | number | No | 이 서버에 한해 규칙의 복귀 임계값을 대체. 규칙의 방향을 기준으로, 적용되는 임계값의 회복하는 쪽에 있어야 함. 비워 두면 규칙의 값을 그대로 사용 |
| `duration_s` | integer | No | 이 서버에 한해 규칙의 지속 시간(초)을 대체. 비워 두면 규칙의 값을 그대로 사용하며, `0`이면 조건을 만족하는 첫 샘플에서 바로 발생 |
| `enabled` | boolean | No | `false`이면 다른 필드 값과 관계없이 이 서버를 규칙에서 완전히 제외. 기본값 `true` |

서버 하나당 규칙 하나에는 오버라이드를 하나만 둘 수 있습니다.

### 응답

```json
{
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "server": {
    "id": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8",
    "name": "web-server-01",
    "os": "Ubuntu 22.04",
    "is_connected": true
  },
  "rule": "8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e",
  "threshold": 90,
  "recovery_threshold": 80,
  "duration_s": null,
  "enabled": true,
  "added_at": "2026-09-10T09:00:00Z",
  "updated_at": "2026-09-10T09:00:00Z"
}
```

필요한 스코프: [`rule_override:create`](/reference/scopes/#rule_override-create)

### 예시

```bash
curl -X POST "https://your-workspace.ap1.alpacon.io/api/metrics/rule-overrides/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
  -H "Content-Type: application/json" \
  -d '{"server": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8", "rule": "8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e", "threshold": 90}'
```

## 규칙 오버라이드 상세 조회

특정 규칙 오버라이드를 ID로 조회합니다.

```http
GET /api/metrics/rule-overrides/{override_id}/
```

### 경로 파라미터

| 파라미터 | 타입 | 설명 |
|----------|------|------|
| `override_id` | string (UUID) | 조회할 오버라이드의 ID |

### 응답

[규칙 오버라이드 생성](#규칙-오버라이드-생성)과 같은 스키마입니다.

필요한 스코프: [`rule_override:read`](/reference/scopes/#rule_override-read)

### 예시

```bash
curl -X GET "https://your-workspace.ap1.alpacon.io/api/metrics/rule-overrides/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
```

## 규칙 오버라이드 수정

기존 오버라이드를 수정합니다. `PATCH`를 통한 부분 업데이트를 지원합니다.

```http
PATCH /api/metrics/rule-overrides/{override_id}/
```

### 경로 파라미터

| 파라미터 | 타입 | 설명 |
|----------|------|------|
| `override_id` | string (UUID) | 수정할 오버라이드의 ID |

### 요청 본문

```json
{
  "enabled": false
}
```

### 요청 파라미터

[규칙 오버라이드 생성](#규칙-오버라이드-생성)과 같은 필드이며, 모두 선택 사항입니다. `server`와 `rule`을 포함해 어떤 필드도 바꿀 수 있으며, 오버라이드를 다른 서버나 규칙으로 옮길 수 있습니다. 다만 한 서버는 규칙 하나당 오버라이드를 최대 하나만 가질 수 있으므로, 이미 오버라이드가 있는 `(server, rule)` 조합으로 옮기려 하면 실패합니다.

### 응답

수정된 필드를 포함한 전체 오버라이드 객체를 반환합니다 ([규칙 오버라이드 상세 조회](#규칙-오버라이드-상세-조회)와 같은 스키마).

필요한 스코프: [`rule_override:update`](/reference/scopes/#rule_override-update)

### 예시

```bash
curl -X PATCH "https://your-workspace.ap1.alpacon.io/api/metrics/rule-overrides/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
```

## 규칙 오버라이드 삭제

오버라이드를 삭제합니다. 서버는 다시 규칙 자체의 값을 따릅니다.

```http
DELETE /api/metrics/rule-overrides/{override_id}/
```

### 경로 파라미터

| 파라미터 | 타입 | 설명 |
|----------|------|------|
| `override_id` | string (UUID) | 삭제할 오버라이드의 ID |

### 응답

```http
204 No Content
```

필요한 스코프: [`rule_override:delete`](/reference/scopes/#rule_override-delete)

### 예시

```bash
curl -X DELETE "https://your-workspace.ap1.alpacon.io/api/metrics/rule-overrides/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
```

## 오류 코드

| 상태 | 오류 코드 | 설명 |
|------|----------|------|
| 400 | `metrics_alert_rule_recovery_threshold_invalid` | 적용되는 `recovery_threshold`가 적용되는 `threshold`의 회복하는 쪽에 있지 않음 |
| 400 | `INVALID_REQUEST` | 이 규칙에 대한 오버라이드가 이미 있거나, `server` 또는 `rule`을 찾을 수 없음 |
| 401 | `UNAUTHORIZED` | 유효하지 않거나 누락된 인증 정보 |
| 403 | `metrics_alert_rule_core_admin_only` | 워크스페이스 관리자가 아닌 주체가 핵심 디스크 사용률 규칙의 오버라이드를 생성·수정·삭제했거나, 오버라이드를 이 규칙으로 또는 이 규칙에서 다른 규칙으로 옮기려 함 |
| 403 | `FORBIDDEN` | 권한 부족, 또는 이 워크스페이스에서 Metrics 확장 기능이 꺼져 있음 |
| 404 | `NOT_FOUND` | 오버라이드를 찾을 수 없거나, `server`가 이 자격 증명으로 관리할 수 없는 서버를 가리킴 |

Source: https://docs.alpacax.com/ko/reference/api/metrics/rule-overrides/