Imported from jawsbaek/scp-gitops-sample (policies/AGENTS.md). Install upstream with npx skills add jawsbaek/scp-gitops-sample --skill policies. Copyright stays with the author.

policies/ — 정책 레이어 (OPA·Kyverno·Conftest)

Purpose

SCP GitOps 프로젝트의 정책 계층으로 3가지 정책 엔진을 조합하여 IaC와 K8s 런타임을 검증합니다.

• OPA: K8s 런타임 Webhook (AdmissionReview) — Pod/Deployment 생성 시 보안·데이터 주권·비용 제어 강제
• Kyverno: K8s ClusterPolicy (네이티브) — 간결한 YAML 문법으로 어드미션 컨트롤
• Conftest: Terraform plan JSON 검증 — IaC 배포 전 리전·태그·보안 설정 검증

Directory Structure

policies/
├── opa/                           # K8s 런타임 OPA Rego 정책
│   ├── security.rego              # SCP-SEC-* (이미지, 권한, root)
│   ├── security_test.rego         # 단위 테스트
│   ├── data-sovereignty.rego      # SCP-DS-* (리전, 데이터 주권)
│   ├── data_sovereignty_test.rego # 단위 테스트
│   ├── cost-control.rego          # SCP-COST-* (리소스 한계, 복제본)
│   ├── cost_control_test.rego     # 단위 테스트
│   ├── networking.rego            # SCP-NET-* (네트워크 격리)
│   ├── networking_test.rego       # 단위 테스트
│   ├── lib/
│   │   └── scp_helpers.rego       # 공통 헬퍼 함수
│   └── README.md
│
├── kyverno/                       # K8s ClusterPolicy
│   ├── disallow-latest-tag.yaml
│   ├── disallow-default-namespace.yaml
│   ├── require-labels.yaml
│   ├── require-run-as-nonroot.yaml
│   ├── require-readonly-rootfs.yaml
│   ├── restrict-registries.yaml
│   ├── restrict-host-ports.yaml
│   ├── restrict-volume-types.yaml
│   ├── require-network-policy.yaml
│   ├── require-probes.yaml
│   ├── require-resource-limits.yaml
│   ├── restrict-privilege-escalation.yaml
│   └── AGENTS.md
│
├── conftest/
│   ├── terraform/
│   │   ├── region.rego            # 리전 검증
│   │   ├── tags.rego              # 필수 태그 검증
│   │   └── security.rego          # 보안 설정 검증
│   └── AGENTS.md
│
├── AGENTS.md                      # 이 파일
├── README.md
└── opa/ 및 kyverno/, conftest/ 하위 AGENTS.md

Key Concepts

정책 ID 체계

정책 검증 플로우

┌─────────────────────────────────────┐
│   1. 로컬 개발 (개발자 PC)            │
│   - make validate (tofu fmt + validate)
│   - opa test policies/opa/ -v       │
│   - kyverno apply ... (선택)        │
│   - conftest test (선택)            │
└──────────────┬──────────────────────┘
               │ git push feature/*
               ↓
┌─────────────────────────────────────┐
│   2. PR 검증 (GitHub Actions)        │
│   - terraform-validate.yaml         │
│     • tofu fmt -check               │
│     • tofu validate                 │
│     • TFLint, Checkov               │
│     • Security (Checkov + tfsec)    │
│   - policy-check.yaml               │
│     • OPA (opa test ...)            │
│     • Kyverno (kyverno apply)       │
│     • Conftest (conftest test)      │
└──────────────┬──────────────────────┘
               │ Approved
               ↓
┌─────────────────────────────────────┐
│   3. 배포 (tofu apply)               │
│   - K8s 리소스 생성 시 OPA/Kyverno   │
│     Webhook 작동 → 정책 검증        │
└─────────────────────────────────────┘

정책별 적용 단계

For AI Agents

Working In This Directory

전체 정책 검증 명령어:

# 1. OPA 테스트 (K8s 런타임)
opa test policies/opa/ -v

# 2. Kyverno 검증 (선택)
kyverno apply policies/kyverno/*.yaml --resource sample.yaml

# 3. Conftest 검증 (Terraform)
cd environments && tofu plan -json > plan.json
conftest test -p ../policies/conftest/terraform/ plan.json -v

# 4. 전체 정책 (CI 명령)
make policy-test

Testing Requirements

정책 추가 후 필수 검증:

# 단일 정책 테스트
opa test policies/opa/security.rego policies/opa/security_test.rego -v

# Conftest Terraform JSON 생성 및 검증
cd environments
tofu init -backend=false
tofu plan -json -var-file=dev.tfvars > plan.json
conftest test -p ../policies/conftest/terraform/ plan.json

# Kyverno 로컬 검증
kyverno apply policies/kyverno/disallow-latest-tag.yaml \
  --resource <(cat <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: test
spec:
  containers:
  - name: app
    image: harbor.scp.internal/app:latest
EOF
)

Common Patterns

1. 정책 추가 체크리스트

• _test.rego (OPA) 또는 _test.yaml (Kyverno) 파일 작성
• 정책 ID 부여: SCP-{DOMAIN}-{NUMBER} 또는 SCP-TF-*
• 메시지: 한국어 + 정책 ID + 해결 방법
• 로컬 테스트 실행: opa test / kyverno apply / conftest test
• make policy-test 전체 통과
• CI 체크: policy-check.yaml 워크플로우 성공

2. 정책 ID 네이밍

# OPA 정책
msg := "[SCP-SEC-001] 미승인 레지스트리 이미지 차단: ..."
msg := "[SCP-DS-001] 허용되지 않는 리전: ..."
msg := "[SCP-COST-W01] CPU 요청 미설정 (경고): ..."
msg := "[SCP-NET-001] 네트워크 정책 부재: ..."

# Conftest 정책
msg := "[SCP-TF-REGION] VPC 리전 검증: ..."
msg := "[SCP-TF-TAGS] 필수 태그 누락: ..."
msg := "[SCP-TF-SEC] 암호화 미설정: ..."

3. 정책 면제 (예외)

# OPA: 시스템 네임스페이스 면제
namespace := get_namespace(input.review.object)
not namespace in data.lib.scp.system_namespaces

# Kyverno: 특정 네임스페이스 제외
spec:
  validationFailureAction: enforce
  rules:
    - name: rule-name
      matchResources:
        exclude:
          - resources:
              namespaces:
                - kube-system
                - istio-system

Dependencies

참고 문서

• ../AGENTS.md — 루트 컨텍스트
• ./opa/AGENTS.md — OPA 상세 가이드
• ./kyverno/AGENTS.md — Kyverno 상세 가이드
• ./conftest/AGENTS.md — Conftest 상세 가이드
• ../CLAUDE.md — 프로젝트 보안 정책