k8s-agent-skills 1.2.0

package/skills/harbor/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: harbor
+description: Use when working with Harbor container registry — route to the correct sub-skill based on what the user needs: API calls, Helm deployment, or Terraform management.
+---
+
+# Harbor — Skill Router
+
+Pick the right sub-skill.
+
+## Which Sub-Skill?
+
+| User wants to... | Load skill |
+|---|---|
+| Hit REST API endpoints, manage projects/artifacts/robots via curl | `harbor-api` |
+| Deploy, configure, upgrade Harbor on K8s with Helm | `harbor-helm` |
+| Manage Harbor infrastructure as code with Terraform | `harbor-terraform` |
+
+## Quick Map
+
+| Task | Skill |
+|---|---|
+| "Create a project via API" | `harbor-api` |
+| "Set up a robot account for CI" | `harbor-api` |
+| "Deploy Harbor on Kubernetes" | `harbor-helm` |
+| "Configure external database for Harbor" | `harbor-helm` |
+| "Manage Harbor resources with Terraform" | `harbor-terraform` |
+| "Create a replication rule" | `harbor-api` |
+| "Configure Trivy scanner" | `harbor-api` |
+| "Upgrade Harbor Helm release" | `harbor-helm` |
+| "Provision projects + robot accounts as code" | `harbor-terraform` |
+| "Manage retention policies" | `harbor-api` |
+| "Configure OIDC auth" | `harbor-api` |

package/skills/harbor-api/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: harbor-api
+description: Use when working with the Harbor REST API v2 — project management, artifact operations, robot accounts, replication, vulnerability scanning, OIDC/LDAP config, garbage collection, and general API automation with curl.
+---
+
+# Harbor REST API v2
+
+Base: `/api/v2.0`. Latest stable: **Harbor v2.15.1** (May 2026). API spec: Swagger 2.0 at `api/v2.0/swagger.yaml`. Built-in Swagger UI: `https://<harbor>/devcenter-api-2.0`.
+
+## Authentication
+
+| Method | Header / Usage | Use Case |
+|--------|---------------|----------|
+| Basic Auth | `-u username:password` | Direct admin/developer API access |
+| Bearer Token | `Authorization: Bearer <token>` | Obtained from `/service/token` per Docker Registry v2 spec |
+| Robot Account | `-u robot$<prefix><name>:<secret>` | Automated CI/CD with scoped permissions |
+| OIDC ID Token | `Authorization: Bearer <oidc_id_token>` | OIDC-authenticated users (basic auth not supported for OIDC) |
+
+### Bearer Token Flow
+```bash
+# Get token for push/pull access to a repo
+TOKEN=$(curl -s -u "username:password" \
+  "https://harbor.example.com/service/token?service=harbor-registry&scope=repository:project/repo:pull,push" \
+  | jq -r '.token')
+
+# Use for registry operations
+curl -H "Authorization: Bearer $TOKEN" https://harbor.example.com/v2/_catalog
+```
+
+### Robot Account Notes
+- Secret shown **only once** at creation — Harbor does not store it
+- Username format: `robot$<prefix><account_name>`
+- System-level (v2.2.0+) or project-level scope
+- Permissions: granular RBAC (push, pull, create, read, delete, list, etc.)
+
+## Key Endpoints
+
+### Health & Status
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/health` | Component health (no auth) |
+| GET | `/statistics` | Project & repo statistics |
+| GET | `/search?q=<query>` | Search projects, repos, helm charts |
+
+### Project Management
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/projects` | List projects (filter: name, public, owner) |
+| POST | `/projects` | Create project |
+| HEAD | `/projects` | Check project name exists |
+| GET | `/projects/{name_or_id}` | Get project |
+| PUT | `/projects/{name_or_id}` | Update project |
+| DELETE | `/projects/{name_or_id}` | Delete project |
+| GET | `/projects/{name_or_id}/_deletable` | Check if deletable |
+| GET | `/projects/{name_or_id}/summary` | Project summary |
+| GET | `/projects/{name_or_id}/metadatas` | List metadata |
+| POST | `/projects/{name_or_id}/metadatas` | Add metadata |
+| GET/PUT/DELETE | `/projects/{name_or_id}/metadatas/{meta_name}` | CRUD metadata entry |
+| GET | `/projects/{name_or_id}/members` | List members |
+| POST | `/projects/{name_or_id}/members` | Add member |
+| GET/PUT/DELETE | `/projects/{name_or_id}/members/{mid}` | CRUD member |
+
+### Repository Management
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/repositories` | List all authorized repos |
+| GET | `/projects/{project}/repositories` | List repos in project |
+| GET | `/projects/{project}/repositories/{repo}` | Get repo |
+| PUT | `/projects/{project}/repositories/{repo}` | Update repo description |
+| DELETE | `/projects/{project}/repositories/{repo}` | Delete repo |
+
+### Artifact Management
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/projects/{proj}/repositories/{repo}/artifacts` | List artifacts (`?q=tags=*`, labels, etc.) |
+| POST | `/projects/{proj}/repositories/{repo}/artifacts` | Copy artifact |
+| GET | `/projects/{proj}/repositories/{repo}/artifacts/{ref}` | Get artifact by digest or tag |
+| DELETE | `/projects/{proj}/repositories/{repo}/artifacts/{ref}` | Delete artifact |
+| PUT | `/projects/{proj}/repositories/{repo}/artifacts/{ref}/add-label` | Add label |
+| DELETE | `/projects/{proj}/repositories/{repo}/artifacts/{ref}/labels/{label_id}` | Remove label |
+| GET | `/projects/{proj}/repositories/{repo}/artifacts/{ref}/tags` | List tags |
+| POST | `/projects/{proj}/repositories/{repo}/artifacts/{ref}/tags` | Create tag |
+| DELETE | `/projects/{proj}/repositories/{repo}/artifacts/{ref}/tags/{tag}` | Delete tag |
+
+### Vulnerability Scanning
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| POST | `/projects/{proj}/repositories/{repo}/artifacts/{ref}/scan` | Trigger scan |
+| POST | `/projects/{proj}/repositories/{repo}/artifacts/{ref}/scan/stop` | Stop scan |
+| GET | `/scanners` | List scanners |
+| GET | `/scanners/{id}` | Get scanner metadata |
+| POST | `/scanners/ping` | Ping scanner adapter |
+| GET | `/projects/{proj}/repositories/{repo}/artifacts/{ref}/scan/{report_id}` | Get scan report |
+
+### Robot Accounts
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/robots` | List robot accounts |
+| POST | `/robots` | Create robot account |
+| GET | `/robots/{id}` | Get robot |
+| PUT | `/robots/{id}` | Update robot |
+| DELETE | `/robots/{id}` | Delete robot |
+| PATCH | `/robots/{id}` | Refresh robot secret |
+
+### Replication
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/replication/policies` | List policies |
+| POST | `/replication/policies` | Create policy |
+| GET/PUT/DELETE | `/replication/policies/{id}` | CRUD policy |
+| GET | `/replication/executions` | List executions |
+| POST | `/replication/executions` | Start replication |
+| GET | `/replication/executions/{id}` | Get execution status |
+| GET | `/replication/executions/{id}/tasks` | List execution tasks |
+| GET | `/registries` | List registries |
+| POST | `/registries` | Create registry endpoint |
+| GET/PUT/DELETE | `/registries/{id}` | CRUD registry |
+| POST | `/registries/ping` | Ping registry endpoint |
+
+### Garbage Collection
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/system/gc` | List GC schedules |
+| POST | `/system/gc` | Create GC schedule |
+| GET | `/system/gc/{id}` | Get GC job |
+| GET | `/system/gc/{id}/log` | Get GC log |
+
+### OIDC / LDAP
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| POST | `/ldap/ping` | Ping LDAP |
+| GET | `/ldap/users/search` | Search LDAP users |
+| POST | `/ldap/users/import` | Import LDAP users |
+| GET | `/ldap/groups/search` | Search LDAP groups |
+| POST | `/system/oidc/ping` | Ping OIDC provider |
+| GET | `/configurations` | Get system config (auth_mode, oidc, ldap) |
+| PUT | `/configurations` | Update system config |
+
+### System & Admin
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/systeminfo` | System info |
+| GET | `/systeminfo/volumes` | Storage volume info |
+| GET | `/internalconfig` | Internal config (admin only) |
+| GET | `/labels` | List labels |
+| POST | `/labels` | Create label |
+| GET/PUT/DELETE | `/labels/{id}` | CRUD label |
+| GET | `/usergroups` | List user groups |
+| POST | `/usergroups` | Create user group |
+| GET/PUT/DELETE | `/usergroups/{id}` | CRUD user group |
+| GET | `/preheat/policies` | List preheat policies |
+| POST | `/preheat/policies` | Create preheat policy |
+| GET | `/preheat/instances` | List preheat instances |
+| POST | `/preheat/instances` | Create preheat instance |
+| GET | `/audit-logs` | List audit logs |
+| GET | `/quota` | List storage quotas |
+
+## Examples
+
+```bash
+# Create a project
+curl -X POST https://harbor.example.com/api/v2.0/projects \
+  -u "admin:Harbor12345" \
+  -H "Content-Type: application/json" \
+  -d '{"project_name": "myapp", "public": false, "storage_limit": -1}'
+
+# Create a robot account (system-level)
+curl -X POST https://harbor.example.com/api/v2.0/robots \
+  -u "admin:Harbor12345" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "ci-deploy",
+    "description": "CI/CD deployment robot",
+    "level": "system",
+    "permissions": [{
+      "kind": "project",
+      "namespace": "myapp",
+      "access": [
+        {"resource": "repository", "action": "pull"},
+        {"resource": "repository", "action": "push"}
+      ]
+    }]
+  }'
+
+# Trigger artifact scan
+curl -X POST "https://harbor.example.com/api/v2.0/projects/myapp/repositories/nginx/artifacts/latest/scan" \
+  -u "admin:Harbor12345"
+
+# Create a replication rule
+curl -X POST https://harbor.example.com/api/v2.0/replication/policies \
+  -u "admin:Harbor12345" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "backup-to-dr",
+    "description": "Replicate to DR site",
+    "trigger": {"type": "event_based"},
+    "dest_registry": {"id": 2},
+    "filters": [{"type": "name", "value": "myapp/**"}],
+    "deletion": true,
+    "override": true
+  }'
+
+# Search across Harbor
+curl -s "https://harbor.example.com/api/v2.0/search?q=nginx" \
+  -u "admin:Harbor12345"
+
+# Trigger garbage collection
+curl -X POST https://harbor.example.com/api/v2.0/system/gc \
+  -u "admin:Harbor12345" \
+  -H "Content-Type: application/json" \
+  -d '{"schedule": {"type": "Weekly", "weekday": 0, "offtime": 0}}'
+```
+
+## Common Mistakes
+
+- **Robot secret not saved** — Secret is only returned on creation. Store it immediately.
+- **API version path** — Always use `/api/v2.0/`, not `/api/` (v1.x legacy path).
+- **OIDC users can't use basic auth** — Must use OIDC ID token as Bearer token.
+- **Robot tokens auto-expire** — Set `duration` in days on creation (default: no expiry).
+- **Scan reports deleted on v2.2 upgrade** — Schema migration clears old scan data. Re-scan after upgrade.
+- **Bearer token scope** — Token is scoped to the `scope` param in the `/service/token` request. Use `repository:*:pull` for read-only, `repository:*:pull,push` for write.

package/skills/harbor-helm/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: harbor-helm
+description: Use when deploying, configuring, or upgrading Harbor on Kubernetes via Helm chart — values configuration, external database, TLS/certificates, storage, ingress, authentication, and production patterns.
+---
+
+# Harbor Helm Chart
+
+Source: `https://helm.goharbor.io`. Latest chart version: **1.19.1** (app version 2.15.1). Images: all v2.15.1 (core, portal, jobservice, registry, trivy, nginx, log, database, redis, exporter).
+
+## Quick Install
+
+```bash
+helm repo add harbor https://helm.goharbor.io
+helm repo update
+
+helm install harbor harbor/harbor \
+  --namespace harbor \
+  --create-namespace \
+  --set expose.tls.auto.commonName=harbor.example.com \
+  --set externalURL=https://harbor.example.com \
+  --set harborAdminPassword=admin123
+```
+
+## Values Overview
+
+### Expose / Ingress
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `expose.type` | `ingress` | `ingress`, `clusterIP`, `nodePort`, `loadBalancer` |
+| `expose.tls.auto.commonName` | — | Auto-generate cert for this hostname |
+| `expose.tls.secretName` | — | Use existing TLS secret |
+| `expose.tls.certSource` | `auto` | `auto`, `secret`, `none` |
+| `expose.ingress.hosts.core` | `core.harbor.domain` | Core ingress host |
+| `expose.ingress.hosts.notary` | `notary.harbor.domain` | Notary ingress host |
+| `expose.ingress.className` | — | Ingress class name |
+| `expose.ingress.annotations` | `{}` | Ingress annotations |
+
+### External URL
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `externalURL` | `https://core.harbor.domain` | Full URL users access Harbor at |
+
+### Auth
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `harborAdminPassword` | `Harbor12345` | Initial admin password |
+| `database.internal` | `true` | Use internal PostgreSQL |
+| `database.type` | `postgresql` | `postgresql` or `external` |
+
+### External Database
+
+```yaml
+database:
+  type: external
+  external:
+    host: postgres.example.com
+    port: 5432
+    username: harbor
+    password: secret
+    database: harbor
+    sslmode: require
+    maxIdleConns: 100
+    maxOpenConns: 900
+```
+
+### External Redis
+
+```yaml
+redis:
+  type: external
+  external:
+    addr: redis.example.com:6379
+    password: secret
+    sentinelMaster: mymaster  # if using sentinel
+```
+
+### Storage
+
+| Component | Default PVC | Parameter |
+|-----------|-------------|-----------|
+| Registry | `200Gi` | `persistence.persistentVolumeClaim.registry.size` |
+| Jobservice | `1Gi` | `persistence.persistentVolumeClaim.jobservice.size` |
+| Database | `1Gi` | `persistence.persistentVolumeClaim.database.size` |
+| Redis | `1Gi` | `persistence.persistentVolumeClaim.redis.size` |
+| Trivy | `5Gi` | `persistence.persistentVolumeClaim.trivy.size` |
+
+Object storage (S3-compatible) for registry:
+
+```yaml
+persistence:
+  imageChartStorage:
+    type: s3
+    s3:
+      region: us-east-1
+      bucket: harbor-registry
+      accesskey: AKIA...
+      secretkey: ...
+      rootdirectory: /registry
+```
+
+### Trivy Scanner
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `trivy.enabled` | `true` | Enable Trivy vulnerability scanner |
+| `trivy.image.repository` | `goharbor/trivy-adapter` | Scanner image |
+| `trivy.image.tag` | `v0.35.1` | Adapter version (Harbor 2.15.x) |
+| `trivy.gitHubToken` | — | GitHub token for Trivy DB download (avoid rate limits) |
+| `trivy.skipUpdate` | `false` | Skip Trivy DB update on startup |
+| `trivy.offlineScan` | `false` | Disable vulnerability DB updates |
+
+### Components
+
+| Parameter | Description |
+|-----------|-------------|
+| `portal.enabled` | Enable Harbor web UI (core depends on it) |
+| `core.replicas` | Core API replicas |
+| `jobservice.replicas` | Job service replicas |
+| `registry.replicas` | Registry replicas |
+| `exporter.enabled` | Enable Prometheus metrics exporter |
+| `chartmuseum.enabled` | Enable Helm Chart Museum |
+| `notary.enabled` | Enable Notary (deprecated, disabled by default) |
+| `notary.disabled` | Notary v1 removed in v2.9+ |
+
+## Production Values Example
+
+```yaml
+expose:
+  type: ingress
+  tls:
+    certSource: secret
+    secretName: harbor-tls
+  ingress:
+    className: cilium
+    annotations:
+      cert-manager.io/cluster-issuer: letsencrypt-prod
+    hosts:
+      core: harbor.example.com
+      notary: notary.example.com
+
+externalURL: https://harbor.example.com
+
+harborAdminPassword: changeme
+
+database:
+  type: external
+  external:
+    host: postgres-cluster-rw.db.svc
+    port: 5432
+    username: harbor
+    password: "${DB_PASSWORD}"
+    database: harbor
+    sslmode: require
+    maxIdleConns: 50
+    maxOpenConns: 500
+
+redis:
+  type: external
+  external:
+    addr: redis-cluster.redis.svc:6379
+    password: "${REDIS_PASSWORD}"
+
+persistence:
+  enabled: true
+  resourcePolicy: keep
+  imageChartStorage:
+    type: s3
+    s3:
+      region: us-east-1
+      bucket: harbor-registry
+      accesskey: "${AWS_ACCESS_KEY}"
+      secretkey: "${AWS_SECRET_KEY}"
+      rootdirectory: /registry
+  persistentVolumeClaim:
+    registry:
+      size: 500Gi
+    jobservice:
+      size: 10Gi
+    trivy:
+      size: 20Gi
+
+trivy:
+  enabled: true
+  gitHubToken: "${GITHUB_TOKEN}"
+  replicas: 2
+
+core:
+  replicas: 3
+  resources:
+    requests:
+      cpu: 500m
+      memory: 1Gi
+    limits:
+      cpu: 2
+      memory: 4Gi
+
+registry:
+  replicas: 3
+  resources:
+    requests:
+      cpu: 500m
+      memory: 1Gi
+
+jobservice:
+  replicas: 2
+
+exporter:
+  enabled: true
+```
+
+## Upgrading
+
+```bash
+helm repo update
+helm upgrade harbor harbor/harbor \
+  --namespace harbor \
+  --values values.yaml \
+  --version 1.19.1
+```
+
+### Migration Path
+- Harbor v2.11.0+ → v2.15.0 directly (via `goharbor/prepare` Docker image)
+- < v2.11.0 requires sequential upgrades through intermediate versions
+- **Must backup ALL data before migration**
+- External PostgreSQL must be ≥ v12
+
+## Common Mistakes
+
+- **Admin password change** — Changing `harborAdminPassword` after initial deploy does NOT update the password. Change via UI or API.
+- **Internal DB in production** — Internal PostgreSQL is single-Pod. Use external PostgreSQL with HA for production.
+- **Notary v1 deprecated** — Disabled since v2.9. Don't enable unless you still need it.
+- **Trivy DB download** — Without `trivy.gitHubToken`, Trivy DB downloads are rate-limited to 60 req/hr. Set a GitHub token.
+- **S3 region mismatch** — Registry S3 bucket and IAM credentials must match the configured region.
+- **Exporter credentials** — Prometheus exporter uses the same admin credentials. Set `exporter.secret` for a dedicated monitoring password.
+- **Upgrade schema migration** — `goharbor/prepare` must run during upgrade to apply DB schema migrations. The Helm chart handles this automatically.