693 lines
21 KiB
Markdown
693 lines
21 KiB
Markdown
# kforge
|
|
|
|
**kforge** eliminates Kubernetes boilerplate. You define your app once in a `kforge.yml` file — environments, infrastructure, ingress, TLS, DNS — and kforge generates production-ready flat manifests on every CI run. Nothing is committed to your repo except the config and generated workflows.
|
|
|
|
Built for self-hosted MicroK8s, Gitea Actions, external-dns, cert-manager, and CNPG — but designed to be extended.
|
|
|
|
---
|
|
|
|
## How it works
|
|
|
|
1. Add a `kforge.yml` to your repo root describing your app, environments, and infrastructure.
|
|
2. kforge generates Kubernetes YAML at CI time — Service, Deployment, Ingress, cert-manager Certificates, CronJobs, and infrastructure (database, cache, storage, queue, search).
|
|
3. Generated manifests are applied to the cluster and discarded. Only `kforge.yml` and generated workflow files are committed.
|
|
|
|
```
|
|
kforge.yml → kforge generate → kubectl apply → cluster
|
|
```
|
|
|
|
DNS records are managed by **external-dns** running in the cluster — kforge writes the appropriate annotations on the Ingress and external-dns creates the records automatically. TLS is handled by **cert-manager** reading those same Certificate CRs.
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Option A — Build from source (recommended for self-hosted runners)
|
|
|
|
```bash
|
|
git clone https://gitea.yourdomain.com/yourorg/kforge.git
|
|
cd kforge
|
|
go build -o /usr/local/bin/kforge .
|
|
```
|
|
|
|
Install once on your Gitea runner host and it's available to every repo automatically.
|
|
|
|
### Option B — Gitea Package Registry
|
|
|
|
If you've published kforge to your Gitea instance's generic package registry:
|
|
|
|
```bash
|
|
curl -fsSL \
|
|
-H "Authorization: token $GITEA_TOKEN" \
|
|
"https://gitea.yourdomain.com/api/packages/yourorg/generic/kforge/latest/kforge-linux-amd64" \
|
|
-o /usr/local/bin/kforge
|
|
chmod +x /usr/local/bin/kforge
|
|
```
|
|
|
|
---
|
|
|
|
## Quick start
|
|
|
|
**1. Add `kforge.yml` to your repo:**
|
|
|
|
```yaml
|
|
meta:
|
|
name: my-app
|
|
tenant: my-org
|
|
|
|
registry:
|
|
url: registry.yourdomain.com
|
|
|
|
dns:
|
|
target: ${KFORGE_NODE_IP} # your cluster node's public IP
|
|
|
|
cluster:
|
|
tls_issuer: letsencrypt-prod
|
|
cnpg:
|
|
host: cnpg-main-rw.default.svc.cluster.local
|
|
|
|
defaults:
|
|
port: 3000
|
|
health_check:
|
|
path: /healthcheck
|
|
|
|
infrastructure:
|
|
database:
|
|
provider: cnpg
|
|
cache:
|
|
provider: valkey
|
|
mode: standalone
|
|
|
|
environments:
|
|
staging:
|
|
namespace: staging
|
|
image_tag: latest
|
|
env_vars:
|
|
- name: API_URL
|
|
value: https://api-staging.yourdomain.com
|
|
type: plain
|
|
ingress:
|
|
hosts:
|
|
- hostname: app-staging.yourdomain.com
|
|
tls: true
|
|
dns_record: true # external-dns creates this record
|
|
auth:
|
|
enabled: true
|
|
users:
|
|
- yourname
|
|
|
|
production:
|
|
namespace: production
|
|
image_tag: latest
|
|
env_vars:
|
|
- name: API_URL
|
|
value: https://api.yourdomain.com
|
|
type: plain
|
|
ingress:
|
|
hosts:
|
|
- hostname: app.yourdomain.com
|
|
tls: true
|
|
dns_record: true
|
|
infrastructure:
|
|
cache:
|
|
mode: cluster
|
|
replicas: 3
|
|
```
|
|
|
|
**2. Validate your config and see what secrets you need:**
|
|
|
|
```bash
|
|
kforge validate
|
|
kforge secrets list
|
|
```
|
|
|
|
**3. Preview what gets generated:**
|
|
|
|
```bash
|
|
kforge generate --env production --dry-run
|
|
```
|
|
|
|
**4. Generate your Gitea Actions workflows:**
|
|
|
|
```bash
|
|
kforge gitea-actions > .gitea/workflows/deploy.yml
|
|
kforge gitea-preview > .gitea/workflows/preview.yml # optional — PR preview environments
|
|
```
|
|
|
|
---
|
|
|
|
## Adding kforge to an existing project
|
|
|
|
### Step 1 — Add `kforge.yml` and generate workflows
|
|
|
|
Add `kforge.yml` to your repo root (see Quick start above), then:
|
|
|
|
```bash
|
|
kforge gitea-actions # → .gitea/workflows/deploy.yml
|
|
kforge gitea-preview # → .gitea/workflows/preview.yml (if preview.enabled: true)
|
|
```
|
|
|
|
Commit `kforge.yml` and both generated workflow files.
|
|
|
|
### Step 2 — Gitea secrets
|
|
|
|
**Org-level** (set once, shared across all repos):
|
|
|
|
| Secret | Value |
|
|
|---|---|
|
|
| `DOCKER_USERNAME` | Registry login username |
|
|
| `DOCKER_PASSWORD` | Registry login password/token |
|
|
| `KFORGE_NODE_IP` | Your cluster's public node IP (used as the external-dns record target) |
|
|
|
|
**Repo-level** (per project):
|
|
|
|
| Secret | How to get it |
|
|
|---|---|
|
|
| `KUBE_HOST` | `kubectl config view --raw -o jsonpath='{.clusters[0].cluster.server}'` |
|
|
| `KUBE_CERTIFICATE` | `kubectl config view --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}'` |
|
|
| `KUBE_TOKEN` | See below |
|
|
|
|
Create a long-lived deploy service account:
|
|
|
|
```bash
|
|
kubectl create serviceaccount kforge-deployer -n kube-system
|
|
kubectl create clusterrolebinding kforge-deployer \
|
|
--clusterrole=cluster-admin \
|
|
--serviceaccount=kube-system:kforge-deployer
|
|
kubectl create token kforge-deployer -n kube-system --duration=8760h
|
|
```
|
|
|
|
### Step 3 — Cluster prerequisites
|
|
|
|
These must already be running on your cluster:
|
|
|
|
| Component | Purpose |
|
|
|---|---|
|
|
| **NGINX ingress controller** | Handles `ingress_class: nginx` |
|
|
| **cert-manager** + `ClusterIssuer` named `letsencrypt-prod` | Issues TLS certificates |
|
|
| **external-dns** | Reads Ingress annotations, creates DNS records |
|
|
| **CNPG operator** | Required if `infrastructure.database` is enabled |
|
|
| **`regcred` imagePullSecret** | Must exist in each environment namespace |
|
|
|
|
For external-dns, configure it with your DNS provider and `--source=ingress`. kforge writes the target annotation automatically from `dns.target`.
|
|
|
|
Create `regcred` in each namespace:
|
|
|
|
```bash
|
|
kubectl create secret docker-registry regcred \
|
|
--docker-server=registry.yourdomain.com \
|
|
--docker-username=<user> \
|
|
--docker-password=<pass> \
|
|
-n production
|
|
```
|
|
|
|
### Step 4 — First deploy
|
|
|
|
The workflow is fully automated after setup, but the very first time:
|
|
|
|
1. Create the namespace: `kubectl create namespace production`
|
|
2. Create `regcred` in that namespace (above).
|
|
3. If using CNPG database, make the CNPG superuser Secret available in the namespace. The default secret name is `cnpg-main-superuser` — copy it from wherever your CNPG cluster lives:
|
|
```bash
|
|
kubectl get secret cnpg-main-superuser -n cnpg-system -o yaml \
|
|
| sed 's/namespace: cnpg-system/namespace: production/' \
|
|
| kubectl apply -f -
|
|
```
|
|
4. Push to `main`. The workflow runs `kforge secrets apply` (creates credentials), `kforge generate` (writes manifests), and `kubectl apply`.
|
|
|
|
---
|
|
|
|
## CLI reference
|
|
|
|
### `kforge validate`
|
|
|
|
Parses `kforge.yml`, checks structural correctness, and verifies all required secrets are present in the current environment. Use this as the first step in CI to fail fast before touching the cluster.
|
|
|
|
```bash
|
|
kforge validate
|
|
kforge validate -c path/to/kforge.yml
|
|
```
|
|
|
|
---
|
|
|
|
### `kforge generate`
|
|
|
|
Generates flat Kubernetes manifests for one or all environments. Writes files to `.kforge-out/` by default, or prints to stdout with `--dry-run`.
|
|
|
|
```bash
|
|
kforge generate # all environments
|
|
kforge generate --env staging # one environment
|
|
kforge generate --env production --dry-run
|
|
kforge generate --env production --output .kube/
|
|
kforge generate --pr-number 42 # preview environment for PR #42
|
|
```
|
|
|
|
**Output files per environment:**
|
|
|
|
| File | Contents |
|
|
|---|---|
|
|
| `{env}-core.yaml` | Service, Deployment, Ingress, Certificates, CronJobs |
|
|
| `{env}-infra-cnpg-database.yaml` | CNPG Database CR |
|
|
| `{env}-infra-cnpg-db-init.yaml` | Job that creates the PostgreSQL role and syncs password |
|
|
| `{env}-infra-cache.yaml` | Valkey/Redis Deployment or StatefulSet |
|
|
| `{env}-infra-cache-svc.yaml` | Cache Service |
|
|
| `{env}-infra-storage.yaml` | Minio Deployment |
|
|
| `{env}-infra-queue-nats.yaml` | NATS Deployment |
|
|
| `{env}-infra-search.yaml` | Meilisearch Deployment |
|
|
| `{env}-infra-servicemonitor.yaml` | Prometheus ServiceMonitor CR |
|
|
|
|
When `--pr-number` is given, the output also includes a `Namespace` manifest so `kubectl apply` is self-contained — no separate namespace creation step needed.
|
|
|
|
Infrastructure env vars (`DATABASE_URL`, `CACHE_URL`, `STORAGE_ENDPOINT`, etc.) are automatically injected into the Deployment — you don't wire these up manually.
|
|
|
|
---
|
|
|
|
### `kforge secrets list`
|
|
|
|
Prints the full secrets checklist for this repo, grouped by where each secret needs to live, with live status checks against the current environment.
|
|
|
|
```bash
|
|
kforge secrets list
|
|
```
|
|
|
|
Example output:
|
|
|
|
```
|
|
── Gitea org secret ──
|
|
DOCKER_USERNAME ✗ missing
|
|
KFORGE_NODE_IP ✓ set
|
|
|
|
── Gitea repo secret ──
|
|
KUBE_HOST ✓ set
|
|
KUBE_TOKEN ✓ set
|
|
KUBE_CERTIFICATE ✓ set
|
|
|
|
── Cluster secret (auto-generated) ──
|
|
prod-my-org-my-app-db-credentials — managed by kforge
|
|
prod-my-org-my-app-cache-credentials — managed by kforge
|
|
```
|
|
|
|
---
|
|
|
|
### `kforge secrets apply`
|
|
|
|
Generates secure random credentials and creates Kubernetes Secrets in the cluster for all enabled infrastructure services. Safe to run on every deploy — secrets are only created if they don't already exist. Use `--force` to rotate credentials.
|
|
|
|
```bash
|
|
kforge secrets apply --env staging
|
|
kforge secrets apply --env production --force # rotates all credentials
|
|
kforge secrets apply --pr-number 42 # apply secrets for PR preview #42
|
|
```
|
|
|
|
**What gets created:**
|
|
|
|
| Secret | Contents |
|
|
|---|---|
|
|
| `{full_name}-db-credentials` | PostgreSQL `username` (derived from app name) + random alphanumeric `password` |
|
|
| `{full_name}-basic-auth` | htpasswd entries for ingress basic auth |
|
|
| `{full_name}-cache-credentials` | Valkey/Redis password |
|
|
| `{full_name}-storage-credentials` | Minio access key + secret key |
|
|
| `{full_name}-queue-credentials` | RabbitMQ username + password (NATS needs no credentials) |
|
|
| `{full_name}-search-credentials` | Meilisearch master key |
|
|
|
|
For basic auth secrets, kforge prints the generated passwords once at apply time — save them.
|
|
|
|
Requires `KUBE_HOST`, `KUBE_TOKEN`, and `KUBE_CERTIFICATE` to be set (Gitea injects these automatically during CI).
|
|
|
|
---
|
|
|
|
### `kforge gitea-actions`
|
|
|
|
Generates a complete `.gitea/workflows/deploy.yml` for this app. Re-run whenever you add environments or change deploy configuration.
|
|
|
|
```bash
|
|
kforge gitea-actions
|
|
kforge gitea-actions --output .gitea/workflows/deploy.yml
|
|
kforge gitea-actions --branch main --env staging --env production
|
|
```
|
|
|
|
The generated workflow runs these steps for each environment, in order:
|
|
|
|
1. Build and push Docker image (tagged with git SHA)
|
|
2. `kforge validate`
|
|
3. `kforge secrets apply` — creates any missing cluster secrets
|
|
4. `kforge generate` — writes manifests to `.kforge-out/`
|
|
5. `kubectl apply` — applies core manifests (Service, Deployment, Ingress, Certs)
|
|
6. `kubectl apply` — applies infrastructure manifests (database, cache, etc.)
|
|
7. `kubectl rollout restart` — triggers rolling update
|
|
|
|
DNS records are created automatically by external-dns when the Ingress is applied — no separate DNS step needed.
|
|
|
|
---
|
|
|
|
### `kforge gitea-preview`
|
|
|
|
Generates `.gitea/workflows/preview.yml` that deploys an ephemeral environment for each pull request.
|
|
|
|
```bash
|
|
kforge gitea-preview
|
|
kforge gitea-preview --output .gitea/workflows/preview.yml
|
|
```
|
|
|
|
Requires `preview.enabled: true` in `kforge.yml`. See the [preview environments](#preview-environments) section below.
|
|
|
|
The generated workflow:
|
|
- **On PR open / sync**: Builds a `:pr-{N}` tagged image, applies secrets to a new namespace (`preview-pr-{N}`), generates manifests (including a `Namespace` resource), and deploys.
|
|
- **On PR close**: Deletes the `preview-pr-{N}` namespace, removing all preview resources automatically.
|
|
|
|
---
|
|
|
|
## `kforge.yml` reference
|
|
|
|
### Naming and interpolation
|
|
|
|
kforge generates resource names using the pattern `{env_prefix}-{tenant}-{name}` (e.g. `prod-my-org-my-app`). Use `${tokens}` anywhere in string values to reference resolved fields:
|
|
|
|
| Token | Resolves to |
|
|
|---|---|
|
|
| `${name}` | `meta.name` |
|
|
| `${tenant}` | `meta.tenant` |
|
|
| `${env}` | current environment key |
|
|
| `${env_prefix}` | short env prefix (first 4 chars, or custom) |
|
|
| `${full_name}` | `{env_prefix}-{tenant}-{name}` |
|
|
| `${namespace}` | resolved namespace for the environment |
|
|
|
|
Environment variables (e.g. `${KFORGE_NODE_IP}`) are resolved from the CI process environment at generation time — never hardcode secrets in `kforge.yml`.
|
|
|
|
---
|
|
|
|
### `meta`
|
|
|
|
```yaml
|
|
meta:
|
|
name: my-app # required — short app name, lowercase, hyphens ok
|
|
tenant: my-org # required — org/tenant identifier
|
|
name_override: ~ # optional — override the full generated resource name
|
|
previous_name: ~ # optional — set when renaming; kforge patches rather than recreates
|
|
```
|
|
|
|
---
|
|
|
|
### `registry`
|
|
|
|
```yaml
|
|
registry:
|
|
url: registry.yourdomain.com # default: registry.natelubitz.com
|
|
repository: my-org/my-app # default: {tenant}/{name}
|
|
pull_secret: regcred # default: regcred
|
|
```
|
|
|
|
Override per-environment by adding a `registry:` block under the environment.
|
|
|
|
---
|
|
|
|
### `dns`
|
|
|
|
DNS records are managed by **external-dns** inside the cluster. kforge writes annotations on the Ingress resource for each host with `dns_record: true`:
|
|
|
|
```
|
|
external-dns.alpha.kubernetes.io/hostname: "app.yourdomain.com"
|
|
external-dns.alpha.kubernetes.io/target: "<dns.target>"
|
|
```
|
|
|
|
```yaml
|
|
dns:
|
|
target: ${KFORGE_NODE_IP} # value for the external-dns target annotation
|
|
skip_dns: false # true = don't write external-dns annotations
|
|
```
|
|
|
|
`target` supports token interpolation — `${KFORGE_NODE_IP}` is the most common value, resolved from the `KFORGE_NODE_IP` Gitea org secret at generate time.
|
|
|
|
---
|
|
|
|
### `cluster`
|
|
|
|
```yaml
|
|
cluster:
|
|
tls_issuer: letsencrypt-prod # default: letsencrypt-prod
|
|
ingress_class: nginx # default: nginx
|
|
cnpg:
|
|
host: cnpg-main-rw.default.svc.cluster.local # your CNPG cluster's read-write service
|
|
cluster_name: cnpg-main # default: cnpg-main
|
|
superuser_secret: cnpg-main-superuser # default: cnpg-main-superuser
|
|
namespace_pattern: "${env}" # default: environment key
|
|
```
|
|
|
|
---
|
|
|
|
### `defaults`
|
|
|
|
All fields can be overridden per-environment.
|
|
|
|
```yaml
|
|
defaults:
|
|
port: 3000
|
|
replicas: 1
|
|
image_pull_policy: Always
|
|
service_type: ClusterIP
|
|
dockerfile: Dockerfile
|
|
health_check:
|
|
path: /healthcheck
|
|
port: 3000
|
|
initial_delay_seconds: 15
|
|
period_seconds: 10
|
|
timeout_seconds: 5
|
|
failure_threshold: 3
|
|
liveness: true
|
|
readiness: true
|
|
resources:
|
|
requests:
|
|
cpu: "100m"
|
|
memory: "128Mi"
|
|
limits:
|
|
cpu: "500m"
|
|
memory: "512Mi"
|
|
env_vars: []
|
|
```
|
|
|
|
---
|
|
|
|
### `infrastructure` (root defaults)
|
|
|
|
Define infrastructure at the root level and it applies to **all environments** by default. Per-environment blocks are a shallow merge — only the fields you specify override; everything else inherits.
|
|
|
|
```yaml
|
|
infrastructure:
|
|
database:
|
|
provider: cnpg # only supported provider currently
|
|
cache:
|
|
provider: valkey # valkey (recommended) | redis
|
|
mode: standalone # standalone | cluster
|
|
replicas: 1
|
|
storage:
|
|
enabled: false
|
|
provider: minio # standalone | distributed
|
|
queue:
|
|
enabled: false
|
|
provider: nats # nats (recommended, ~20MB) | rabbitmq (~200MB)
|
|
search:
|
|
enabled: false
|
|
provider: meilisearch
|
|
monitoring:
|
|
enabled: false
|
|
provider: prometheus
|
|
metrics_path: /metrics
|
|
```
|
|
|
|
If a service block exists at root, it is **enabled by default** for all environments. To disable it for a specific environment:
|
|
|
|
```yaml
|
|
environments:
|
|
dev:
|
|
infrastructure:
|
|
cache:
|
|
enabled: false
|
|
```
|
|
|
|
To scale up for production while staging uses the root defaults:
|
|
|
|
```yaml
|
|
environments:
|
|
production:
|
|
infrastructure:
|
|
cache:
|
|
mode: cluster
|
|
replicas: 3 # provider: valkey inherited from root
|
|
```
|
|
|
|
**Injected env vars per service** (automatically added to your Deployment):
|
|
|
|
| Service | Env vars injected |
|
|
|---|---|
|
|
| database (CNPG) | `DATABASE_URL`, `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD` |
|
|
| cache | `CACHE_URL`, `CACHE_HOST`, `CACHE_PORT`, `CACHE_PASSWORD` |
|
|
| storage | `STORAGE_ENDPOINT`, `STORAGE_ACCESS_KEY`, `STORAGE_SECRET_KEY` |
|
|
| queue (NATS) | `QUEUE_URL`, `QUEUE_HOST` |
|
|
| queue (RabbitMQ) | `QUEUE_URL`, `QUEUE_USER`, `QUEUE_PASSWORD` |
|
|
| search | `SEARCH_URL`, `SEARCH_MASTER_KEY` |
|
|
|
|
#### CNPG database details
|
|
|
|
For a centralized CNPG cluster, kforge generates two resources:
|
|
|
|
1. A **`Database` CR** — declaratively manages the database lifecycle (CNPG v1.22+).
|
|
2. A **`db-init` Job** — runs on every deploy to create the PostgreSQL role (if it doesn't exist) and sync its password from the `{full_name}-db-credentials` Secret.
|
|
|
|
`kforge secrets apply` must run before the Job so the Secret exists. The PostgreSQL username is derived from the app's full name (`prod_my_org_my_app`). The password is alphanumeric only, which keeps the init Job shell script simple and safe.
|
|
|
|
The `cnpg-main-superuser` Secret (created by CNPG for the cluster) must be present in the target namespace. Copy it once during cluster bootstrap or namespace creation.
|
|
|
|
---
|
|
|
|
### `preview`
|
|
|
|
Enables PR preview environments. Run `kforge gitea-preview` to generate the workflow.
|
|
|
|
```yaml
|
|
preview:
|
|
enabled: true
|
|
base_environment: staging # inherit infra and env vars from this env
|
|
namespace_prefix: preview-pr # namespace = preview-pr-{PR_NUMBER}
|
|
hostname_template: "pr-${PR_NUMBER}.${name}.yourdomain.com"
|
|
```
|
|
|
|
Supported tokens in `hostname_template`: `${PR_NUMBER}`, `${name}`, `${tenant}`.
|
|
|
|
On PR open/sync, kforge deploys the app to a `preview-pr-{N}` namespace with:
|
|
- Image tagged `:pr-{N}` (built from the PR branch)
|
|
- Hostname from the template
|
|
- Infrastructure and env vars inherited from `base_environment`
|
|
|
|
On PR close, the entire namespace is deleted.
|
|
|
|
---
|
|
|
|
### `environments`
|
|
|
|
```yaml
|
|
environments:
|
|
production:
|
|
namespace: production
|
|
replicas: 1
|
|
image_tag: latest # override with --set image_tag=$SHA in CI
|
|
env_prefix: prod # default: first 4 chars of env key
|
|
|
|
env_vars:
|
|
- name: API_URL
|
|
type: plain
|
|
value: https://api.yourdomain.com
|
|
|
|
- name: SOME_SECRET
|
|
type: secret_ref # pull from an existing Kubernetes Secret
|
|
secret_name: my-secrets
|
|
secret_key: some_secret
|
|
|
|
- name: FEATURE_FLAG
|
|
type: configmap_ref # pull from a ConfigMap
|
|
configmap_name: my-config
|
|
configmap_key: feature_flag
|
|
|
|
ingress:
|
|
hosts:
|
|
- hostname: app.yourdomain.com
|
|
tls: true # kforge generates a cert-manager Certificate
|
|
dns_record: true # external-dns creates this record
|
|
auth:
|
|
enabled: false # enable for staging/dev to protect unreleased work
|
|
users:
|
|
- yourname # passwords are auto-generated by kforge secrets apply
|
|
|
|
infrastructure:
|
|
# shallow merge on top of root — only override what differs
|
|
cache:
|
|
mode: cluster
|
|
replicas: 3
|
|
|
|
cron_jobs:
|
|
- name: cleanup
|
|
schedule: "0 2 * * *"
|
|
command: ["node", "scripts/cleanup.js"]
|
|
inherit_env: true # inherits all deployment env vars
|
|
env_vars:
|
|
- name: BATCH_SIZE
|
|
value: "500"
|
|
type: plain
|
|
resources:
|
|
requests:
|
|
cpu: "50m"
|
|
memory: "64Mi"
|
|
limits:
|
|
cpu: "200m"
|
|
memory: "256Mi"
|
|
restart_policy: OnFailure
|
|
concurrency_policy: Forbid
|
|
|
|
lifecycle:
|
|
delete: false # if true + previous_name set, deletes old resources
|
|
delete_grace_seconds: 300
|
|
```
|
|
|
|
---
|
|
|
|
## Secrets architecture
|
|
|
|
kforge works with three categories of secrets, each living in the right place for its scope.
|
|
|
|
### Category A — Gitea org secrets
|
|
|
|
Set once at the organisation level; available to every repo automatically.
|
|
|
|
| Secret | Purpose |
|
|
|---|---|
|
|
| `DOCKER_USERNAME` | Registry authentication |
|
|
| `DOCKER_PASSWORD` | Registry authentication |
|
|
| `KFORGE_NODE_IP` | Cluster node IP — written as the external-dns target annotation |
|
|
|
|
### Category B — Gitea repo secrets
|
|
|
|
Per-repo, since different apps may deploy to different clusters.
|
|
|
|
| Secret | Purpose |
|
|
|---|---|
|
|
| `KUBE_HOST` | Kubernetes API server URL |
|
|
| `KUBE_TOKEN` | Service account token |
|
|
| `KUBE_CERTIFICATE` | Base64-encoded CA certificate |
|
|
|
|
### Category C — Cluster secrets (auto-generated)
|
|
|
|
Created by `kforge secrets apply`. Never appear in Gitea or in `kforge.yml`.
|
|
|
|
| Secret name | Contents |
|
|
|---|---|
|
|
| `{full_name}-db-credentials` | PostgreSQL `username` + alphanumeric `password` |
|
|
| `{full_name}-basic-auth` | htpasswd for ingress basic auth |
|
|
| `{full_name}-cache-credentials` | Valkey/Redis password |
|
|
| `{full_name}-storage-credentials` | Minio access/secret keys |
|
|
| `{full_name}-queue-credentials` | RabbitMQ credentials |
|
|
| `{full_name}-search-credentials` | Meilisearch master key |
|
|
|
|
Run `kforge secrets list` at any time to see the full checklist with live status for your current repo.
|
|
|
|
---
|
|
|
|
## Project structure
|
|
|
|
```
|
|
kforge.yml ← your app config (committed)
|
|
.gitea/
|
|
workflows/
|
|
deploy.yml ← generated by kforge gitea-actions (committed)
|
|
preview.yml ← generated by kforge gitea-preview (committed, optional)
|
|
```
|
|
|
|
Generated manifests (`.kforge-out/`) are never committed — they are created at CI time and discarded after `kubectl apply`.
|
|
|
|
---
|
|
|
|
## Planned
|
|
|
|
- `kforge serve` — web UI for managing infrastructure across all repos
|
|
- `kforge lifecycle rename` — interactive rename flow with resource patching
|
|
- Route53 and Porkbun DNS providers
|
|
- `--set key=value` flag for runtime overrides (e.g. `--set image_tag=$SHA`)
|