# Configuration reference

> Every field you can set on a deployment, by resource type: web, worker, job, database, and function. Defaults, ranges, and what each one does.

Every deployment is configured from a single form in your [dashboard](https://app.ownkube.io/dashboard), with different fields depending on the **resource type**. This page is the exhaustive field reference. For the conceptual overview, see [Deployments](/docs/features/deployments).

Every field is editable after creation from the deployment's **Settings** tab. Saving triggers a rolling update.

## Fields shared by every resource type

| Field | Type | Default | Rules |
|---|---|---|---|
| **Name** | text | none | Lowercase letters, numbers, and dashes; must start with a letter; up to 63 characters. Unique within the **cluster + environment** pair. Required. |
| **Cluster** | select | shared Starter cluster | Any active cluster in your organization. Functions attach to an AWS account and region instead of a cluster. |
| **Environment** | select | none | An [environment](/docs/features/environments) like `Development` or `Production`, or none. Pick an existing one or create it inline. |

**Environment variables** work the same on web, worker, job, and function deployments: any number of `KEY=value` pairs, each with a **Secret** toggle. Keys must be valid shell identifiers (letters, numbers, underscores; not starting with a number). See [Environment variables](/docs/guides/environment-variables).

## Source: where the image comes from

Web, worker, and job deployments run a container image. You give Ownkube one of:

#### Build from GitHub

| Field | Type | Default | Notes |
|---|---|---|---|
| **Repository** | GitHub repo picker | none | Picked from your [connected GitHub App](/docs/features/registries) install. |
| **Branch** | text | repo default (e.g. `main`) | The branch to build from. |
| **Dockerfile path** | select | `./Dockerfile` | Chosen from the Dockerfiles Ownkube auto-detects in the repo. |

Ownkube builds the image, pushes it to your ECR, and can open a pull request that adds a build-and-push workflow so every push ships a new image.

#### Use an existing image

| Field | Type | Default | Notes |
|---|---|---|---|
| **Image** | text | none | An image reference from a [connected registry](/docs/features/registries) (e.g. your ECR) or any public image. |
| **Tag** | text | none | Autocompletes from the repository. Pin a specific tag (`v1.4.2`, a short git SHA) rather than `latest` so every deploy is traceable. |

## Web and worker

Web and worker deployments share the same fields. The difference is intent: a **web** service is meant to be reached over HTTP (usually with a public hostname), a **worker** runs continuously in the background (queue consumers, processors, scheduled background tasks) and normally stays private.

### Container

| Field | Type | Default | Range |
|---|---|---|---|
| **Port** | number | none | 1 to 65535. Required. The port your container listens on. |
| **Replicas** | number | `1` | 0 to 20. `0` pauses the deployment without deleting it. Ignored when autoscaling is on. |

### Public exposure

| Field | Type | Default | Notes |
|---|---|---|---|
| **Make this deployment public** | toggle | off | Allocates a generated `*.ownkube.app` hostname with automatic TLS. Workers can opt in but usually stay private. |
| **WAF and DDoS protection** | toggle | on | Only shown when public is on. When on, traffic is proxied for edge protection; when off, DNS points straight at the load balancer. |

To serve from a hostname you own, see [Map a custom domain](/docs/guides/custom-domain).

### Resources

Request and limit CPU and memory separately. CPU is set in millicores (`m`, where `1000m` = 1 vCPU); memory in mebibytes (`Mi`).

| Field | Type | Default |
|---|---|---|
| **Requests, CPU** | quantity | `100m` |
| **Requests, Memory** | quantity | `128Mi` |
| **Limits, CPU** | quantity | `500m` |
| **Limits, Memory** | quantity | `512Mi` |

Requests are the floor your container is guaranteed and the baseline autoscaling measures against. Set an honest request, not a wishful peak. On the shared Starter cluster, requests are capped at `500m` CPU and `512Mi` memory per deployment.

### Autoscaling

Only persisted when enabled. See [Autoscaling](/docs/features/autoscaling) for the full behavior.

| Field | Type | Default | Range |
|---|---|---|---|
| **Enable autoscaling** | toggle | off | n/a |
| **Min replicas** | number | `1` | 1 to 100, and at most Max replicas |
| **Max replicas** | number | `3` | 1 to 100, and at least Min replicas |
| **Target CPU utilization** | number | `80` | 1 to 100 (% of the CPU request) |
| **Target memory utilization** | number | `80` | 1 to 100 (% of the memory request) |

### Health probes

Three independent probes, each off by default. When enabled, each takes the same fields.

| Field | Type | Default | Range |
|---|---|---|---|
| **Path** | text | `/health` (liveness), `/ready` (readiness, startup) | non-empty |
| **Period** | seconds | `10` | 1 to 300 |
| **Timeout** | seconds | `5` | 1 to 60 |
| **Failure threshold** | count | `3` | 1 to 30 |
| **Initial delay** | seconds | `0` | 0 to 300 |

- **Startup** gates how long a container has to boot before it's considered dead.
- **Liveness** restarts the container if it fails.
- **Readiness** holds traffic until it passes.

Most web apps only need a readiness probe on `/health` or `/ready`.

### Access protection

Shown only when the deployment is public. Protection is enforced on **Starter (K3s)** clusters today; Production (EKS) parity is on the roadmap.

| Field | Type | Default | Notes |
|---|---|---|---|
| **Require a password** | toggle | off | HTTP basic auth. Set a **Username** (no spaces or colons) and **Password**. |
| **Require Google sign-in** | toggle | off | Restrict access to an allowlist of domains or emails. Mutually exclusive with password. **Roadmap:** this option is visible but not yet enabled. |

## Job

**Jobs are in beta.** A job runs a container to completion and exits. It has no port, replicas, public hostname, autoscaling, health probes, or access protection.

Jobs share **Source**, **Resources**, and **Environment variables** with web deployments (same fields, same defaults). They add:

### Command

| Field | Type | Default | Range |
|---|---|---|---|
| **Command** | list | image entrypoint | up to 64 entries |
| **Arguments** | list | image default | up to 64 entries |

### Schedule

| Field | Type | Default | Notes |
|---|---|---|---|
| **Active** | toggle | on | When off, the schedule is suspended. |
| **Cron expression** | text | none | Standard 5-field cron (or an `@macro`). |
| **Overlapping runs** | select | `Forbid` | `Allow`, `Forbid` (skip if still running), or `Replace`. |
| **Time zone** | text | cluster default (UTC) | Optional IANA time zone (e.g. `America/New_York`). |
| **Start deadline** | seconds | none | 0 to 86400. How late a run may start before it's skipped. |
| **Keep successful runs** | count | none | 0 to 100 finished runs retained for history. |
| **Keep failed runs** | count | none | 0 to 100 failed runs retained. |

### Execution

| Field | Type | Default | Range |
|---|---|---|---|
| **On failure** | select | `Never` | `Never` (leave the container for inspection) or `OnFailure` (retry in place). |
| **Retry limit** | number | none | 0 to 20 |
| **Run timeout** | seconds | none | 1 to 86400 |
| **Clean up after** | seconds | none | 0 to 604800 (delete the finished run after this long) |
| **Parallel tasks** | number | `1` | 1 to 20 |
| **Completions** | number | `1` | 1 to 20 |

## Database

A managed PostgreSQL deployment. Databases have no environment variables, port, replicas, autoscaling, health probes, or access-protection fields; connection details are injected into the apps you attach. See [Databases](/docs/features/databases) for engines, backups, and connection strings.

| Field | Type | Default | Notes |
|---|---|---|---|
| **Version** | select | `18` | PostgreSQL `17` or `18`. Set at creation. |
| **Storage** | select | `10Gi` | `1`, `5`, `10`, `20`, `50`, or `100 GiB`. Can grow later, never shrink. |
| **Instance count** | number | `2` | 1 to 10 for high availability on Production. Always `1` on a Starter (K3s) cluster. |
| **Public access** | toggle | off | Allocates a stable public hostname with its own TLS certificate. Available on Starter clusters; keep it off unless you need it. |
| **Database name** | text | derived from the deployment name | A valid PostgreSQL identifier (lowercase, underscores). Set at creation. |
| **Owner role** | text | derived from the deployment name | The owning database role. Set at creation. |

High availability, connection pooling, encryption, and automated backups are configured for you based on the cluster shape. They aren't manual fields.

## Function

**Functions are in beta.** A function is a serverless event handler that runs without a cluster. It attaches to an AWS account and region, builds from a GitHub repository, and fires on an HTTP request or a schedule. Pricing isn't finalized. See [Functions](/docs/features/functions) for the full detail.

| Field | Type | Default | Notes |
|---|---|---|---|
| **Runtime** | select | `nodejs22.x` | Node.js, Python, Java, .NET, Ruby, or a custom runtime for Go and Rust. Set at the first build. |
| **Handler** | text | seeded per runtime | The entry point in your code (e.g. `index.handler`). |
| **Architecture** | select | `arm64` | `arm64` (cheaper) or `x86_64`. |
| **Memory** | select | `256` MB | 128 MB up to 10240 MB. |
| **Timeout** | seconds | `30` | 1 to 900. |
| **Log retention** | days | `14` | 1 to 3653. |
| **HTTP trigger** | toggle + select | on | A public invoke URL. **Access** is `none` (open) or `iam` (signed AWS callers only). |
| **Schedule trigger** | text | off | A `rate(...)` or `cron(...)` expression. At least one trigger is required. |

## Cross-cutting behavior

- **Rolling updates.** Every saved change rolls out gradually: new containers start and pass health checks before old ones drain. There is no separate deploy button.
- **Secrets.** A variable marked **Secret** is stored securely, masked in the UI, and redacted from logs and change history. Saving a secret with a blank value keeps the existing stored value.
- **Revisions.** Every change is recorded as a revision with a field-level diff, so you can see what changed and roll back.
- **App platform version.** Web, worker, and job deployments run on the **app platform version**, the runtime Ownkube ships to power them. Upgrades are forward-only; an **Upgrade** control appears on the **Overview** tab when a newer version is available. See [Deployments](/docs/features/deployments#app-platform-version).

- [Deployments](/docs/features/deployments)
- [Autoscaling](/docs/features/autoscaling)
- [Deploy your first app](/docs/guides/deploy-first-app)

---

**Don't see a feature you need?** Email [support@ownkube.io](mailto:support@ownkube.io?subject=Feature%20request). Ownkube is shaped by the teams using it and we ship what our users ask for.