f.weber/aptly-containerized
Public Access
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases 6 Wiki Activity

Initial implementation: aptly container image, Compose stacks, Helm chart, and Gitea Actions pipelines
CI / lint (push) Failing after 24s
Details
CI / smoke-test (push) Failing after 2m4s
Details
Release image / release (push) Successful in 23m18s
Details
Release chart / release (push) Successful in 7s
Details

Browse Source 
Provides a self-contained, containerized aptly (Debian repo manager)
stack with independently releasable image and Helm chart versions.

- images/: aptly-server (aptly built from source, cross-compiled) and
  aptly-deb-builder (nfpm + dpkg-buildpackage) container images
- rootfs/: shared aptly-init/aptly-reconcile/aptly-push/aptly-pack
  scripts consumed identically by Compose and the Helm chart, driven
  by one declarative state.yaml contract
- compose/: test (ephemeral, open) and production docker-compose
  stacks with an nginx read/auth sidecar
- charts/aptly/: aptly-native Helm chart covering every security
  posture from fully open to authenticated read+write, Ingress and
  Gateway API support (usable in parallel for migration scenarios),
  metrics, and declarative repo/mirror/publish reconciliation via a
  Helm hook
- .gitea/workflows/: CI (lint, template, kubeconform, E2E smoke test)
  plus separately tagged image (image/v*) and chart (chart/v*)
  releases, weekly rebuilds, and a preflight workflow validating the
  runner's Docker/Helm-OCI capabilities
- pubkeys/: RSA chart-signing key for Helm --sign / Artifact Hub's
  signKey annotation (Helm can't verify Ed25519 keys)
- docs/, README.md, charts/aptly/README.md: usage, security, and
  versioning documentation
This commit is contained in:
f.weber
2026-08-12 12:21:08 +02:00
commit 103ad311b7
71 changed files with 4843 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
charts/aptly/README.md
+395
View File
@@ -0,0 +1,395 @@
# aptly
[aptly](https://www.aptly.info/) (Debian repository management tool) on Kubernetes:
a single-pod StatefulSet (aptly + an nginx read/auth sidecar), a fully aptly-native
values API, and declarative repo/mirror/publish state reconciled by a Helm hook —
no library-chart dependency, no concepts to learn beyond aptly's and Kubernetes' own.
## TL;DR
```bash
helm install my-aptly oci://git.morlana.online/f.weber/aptly --version <version>
```
## Introduction
This chart deploys [aptly](https://www.aptly.info/) as:
- a `StatefulSet` running two containers in one pod — `aptly` itself (bound to
`127.0.0.1`, never reachable off-pod) and an `nginx` sidecar that is the only
thing actually exposed, handling reads, auth, and the write-API proxy;
- a `Service` in front of `nginx`, and optional `Ingress` and/or Gateway API
`HTTPRoute` resources for apt clients and the API — both can be enabled at the
same time, e.g. mid-migration between the two (see [Gateway API](#gateway-api));
- a post-install/post-upgrade `Job` that reconciles the local repos, mirrors, and
publish targets declared in `values.yaml` against the running instance's REST API.
Three things this chart is built around:
1. **A single security switch that actually reaches every mode**, including
completely open (no auth on read *or* write) if that's what you want — see
[Security modes](#security-modes) below.
2. **An aptly-native config surface**: curated `aptly.*` keys for the common cases,
plus `aptly.configOverrides` as a raw passthrough so any current or future aptly
config key is reachable without waiting on a chart update.
3. **Declarative state**: local repos, mirrors, and publish targets live in
`values.yaml` and are converged towards on every `helm install`/`helm upgrade`,
the same way the rest of the cluster is managed.
## Prerequisites
- Kubernetes 1.24+
- Helm 3.8+ (for OCI registry support) — Helm 4 also works
- A `StorageClass` supporting `ReadWriteOnce`, unless `persistence.enabled: false`
## Installing the chart
```bash
helm install my-aptly oci://git.morlana.online/f.weber/aptly --version <version> \
--set ingress.enabled=true \
--set ingress.repo.host=apt.example.com
```
Without `ingress.enabled`, the post-install NOTES print a `kubectl port-forward`
command instead — nothing has to be configured up front to try the chart out (e.g.
in kind/k3d).
## Uninstalling the chart
```bash
helm uninstall my-aptly
```
The `PersistentVolumeClaim` created by this chart's `volumeClaimTemplate` (i.e.
when `persistence.existingClaim` is unset) is **not** deleted — StatefulSet-owned
PVCs never are, by Kubernetes' own design, regardless of any Helm annotation.
Remove it yourself if you're done with the data — for a release named `my-aptly`,
that PVC is `data-my-aptly-0` (`data-<statefulset-name>-<ordinal>`; find the exact
name with `kubectl get pvc -l app.kubernetes.io/instance=<release>`):
`kubectl delete pvc data-my-aptly-0`.
## Security modes
aptly itself ships with **no authentication at all**; this chart's `security.preset`
switch controls what the nginx sidecar in front of it requires:
| `security.preset` | Read (apt clients) | Read auth | Write (`/api/`) | Write auth |
|---|---|---|---|---|
| `open` | on | **no** | on | **no** |
| `publicRead` (**default**) | on | no | on | yes |
| `authenticated` | on | yes | on | yes |
| `readOnly` | on | no | **off (404)** | — |
```yaml
security:
preset: open # the fully-unsecured mode — one line, no confirmation gate
```
`security.read.*` and `security.write.*` override the preset explicitly, so every
individual cell of the matrix is reachable (e.g. `authenticated` but with anonymous
reads, or `open` restricted to a CIDR on the write path). Health probes
(`/api/ready`, `/api/healthy`) never require credentials, in any mode.
Credentials come from `security.auth.users` (plaintext, hashed into an
`htpasswd` file by the initContainer at pod start — never store a pre-hashed
password here, see the comment in `values.yaml`) or from
`security.auth.existingSecret` (a pre-built `htpasswd` Secret key — the recommended
production path, e.g. via ExternalSecrets/SealedSecrets).
Full write-up of the Ingress `split` mode, the `trustedProxies`/`allowCIDRs`
pitfall behind an Ingress controller, and `write.inClusterOnly`:
[docs/security.md](https://git.morlana.online/f.weber/aptly-containerized/src/branch/main/docs/security.md)
in the repository.
## Gateway API
`gateway.*` is a complete, independent alternative to `ingress.*` — enable either
one, or **both at once**. Nothing about this chart forces a choice, on purpose:
if you're partway through migrating a cluster from Ingress to Gateway API, both
resource sets can point at the same `Service` for as long as that takes.
```yaml
gateway:
enabled: true
parentRefs:
- name: my-gateway # a Gateway your cluster admin already manages —
namespace: gateway-infra # this chart never creates one itself
repo:
hostnames: [apt.example.com]
```
This mirrors `ingress.*` concept for concept:
- `gateway.mode: single` (default) creates one `HTTPRoute` that carries both apt
reads and `/api/` writes — nginx does the split internally, exactly as in
Ingress `single` mode.
- `gateway.mode: split` creates a second `HTTPRoute` for `/api/` under
`gateway.api.hostnames`, optionally attached to a **different** Gateway via
`gateway.api.parentRefs` (falls back to `gateway.parentRefs` when unset) — e.g.
an internal-only Gateway for the write path. Same caveat as Ingress `split`
mode applies: this is a route-level split, not something nginx itself enforces,
so combine it with `security.write.inClusterOnly` or a `NetworkPolicy` if a
request arriving on the wrong hostname must actually be rejected at the network
level.
- `security.write.inClusterOnly: true` omits the API `HTTPRoute` entirely in
`split` mode, the same way it omits the API `Ingress`.
- The shared `proxy.enabled=false` guard applies here too: a `HTTPRoute` (or
`Ingress`) in front of aptly's unauthenticated write API is refused unless
`security.preset: open` confirms it's intended.
One real difference from Ingress: **TLS is not configured here.** Gateway API
deliberately separates infrastructure (the `Gateway` and its listeners, owned by
a cluster admin) from routing (the `HTTPRoute`, owned by this chart) — so TLS
termination is the referenced `Gateway`'s job, not a `gateway.repo.tls`-style
field this chart would need to expose.
Core Gateway API resources have been GA (`gateway.networking.k8s.io/v1`) since
v1.0; `gateway.apiVersion` exists as an escape hatch only if your cluster's CRDs
still predate that.
## Configuring aptly itself
Two layers, always merged in this order — nothing in aptly's own configuration is
ever unreachable through this chart:
1. curated `aptly.*` keys (omitted from the rendered config when unset, so a
default install matches aptly's own upstream defaults exactly);
2. `aptly.configOverrides` — raw aptly YAML (snake_case keys, same as aptly's own
config file), deep-merged over the generated config last, always wins.
```yaml
aptly:
architectures: [amd64, arm64]
metrics:
enabled: true
configOverrides:
s3_publish_endpoints:
cdn:
region: eu-central-1
bucket: apt-example
```
## Declarative state
Local repos, mirrors, and publish targets declared under `aptly.*` are converged
towards by a Helm hook Job on every install/upgrade — talking only to aptly's REST
API, never the CLI (the API server holds aptly's database lock).
```yaml
aptly:
localRepos:
- name: stable
defaultDistribution: stable
defaultComponent: main
publish:
- name: stable-root
prefix: ""
distribution: stable
sourceKind: local
sources: [{ name: stable, component: main }]
architectures: [amd64, arm64]
```
Known limitation: `mirrors[].components` cannot be changed after a mirror is
created (aptly's API has no endpoint for that) — changing it means deleting and
recreating the mirror. Everything else is kept in sync on every run.
## GPG signing
```yaml
aptly:
gpg:
enabled: true # false = gpg_disable_sign + Signing.Skip on every publish call
provider: gpg # gpg (default) | internal (pure-Go, no gnupg binary)
signingKey:
existingSecret: my-signing-key # keys: privateKey (or secretKeyring), passphrase
```
The public key is served at `aptly.gpg.publishPublicKey.path` (default
`/signing-key.asc`) so clients can fetch it directly:
```bash
curl -fsSL https://apt.example.com/signing-key.asc | gpg --dearmor \
| sudo tee /usr/share/keyrings/example.gpg >/dev/null
echo 'deb [signed-by=/usr/share/keyrings/example.gpg] https://apt.example.com/ stable main' \
| sudo tee /etc/apt/sources.list.d/example.list
```
Never put a real private key inline in `values.yaml` — `aptly.gpg.signingKey.privateKey`
exists only as a quick-test escape hatch.
## Storage
`persistence.size`/`persistence.storageClass` are **immutable** once installed —
Kubernetes forbids changing a StatefulSet's `volumeClaimTemplates` in place. Set
`persistence.existingClaim` from the start in production: then no
`volumeClaimTemplate` exists at all, and resizing the referenced PVC directly is a
plain, supported operation.
## Parameters
### Image
| Key | Default | Description |
|---|---|---|
| `image.repository` | `git.morlana.online/f.weber/aptly` | aptly-server image |
| `image.tag` | `""` | falls back to `.Chart.AppVersion` — the last released image, never `latest` |
| `image.pullPolicy` | `IfNotPresent` | |
| `image.pullSecrets` | `[]` | |
| `nginx.image.repository` | `nginxinc/nginx-unprivileged` | upstream image, unmodified |
| `nginx.image.tag` | `1-alpine` | |
| `nginx.image.pullPolicy` | `IfNotPresent` | |
| `nginx.resources` | `{}` | |
| `nginx.securityContext` | non-root, all caps dropped | |
### aptly configuration
| Key | Default | Description |
|---|---|---|
| `aptly.architectures` | `[]` | empty = all available |
| `aptly.logLevel` | `info` | |
| `aptly.logFormat` | `json` | |
| `aptly.download.concurrency` | `4` | |
| `aptly.download.limit` | `0` | KB/s, `0` = unlimited |
| `aptly.download.retries` | `0` | |
| `aptly.download.sourcePackages` | `false` | |
| `aptly.publishing.skipContents` | `false` | |
| `aptly.publishing.skipBz2` | `false` | |
| `aptly.metrics.enabled` | `false` | exposes `/api/metrics` on a separate, unauthenticated port — see [Metrics](#metrics) |
| `aptly.swagger.enabled` | `false` | exposes `/docs.html` |
| `aptly.gpg.enabled` | `true` | `false` disables signing entirely — see [GPG signing](#gpg-signing) |
| `aptly.gpg.verify` | `true` | mirror signature verification |
| `aptly.gpg.provider` | `gpg` | `gpg` \| `internal` |
| `aptly.gpg.signingKey.existingSecret` | `""` | Secret key `privateKey` or `secretKeyring`, optional `passphrase` |
| `aptly.gpg.signingKey.privateKey` | `""` | inline armored key — quick tests only, never for production |
| `aptly.gpg.signingKey.passphrase` | `""` | only used with the inline key above |
| `aptly.gpg.publishPublicKey.enabled` | `true` | serve the public key over HTTP |
| `aptly.gpg.publishPublicKey.path` | `/signing-key.asc` | |
| `aptly.gpgKeys` | `[]` | trusted keys imported for mirror verification — `[{name, armored}]` |
| `aptly.localRepos` | `[]` | see [Declarative state](#declarative-state) |
| `aptly.mirrors` | `[]` | see [Declarative state](#declarative-state) |
| `aptly.publish` | `[]` | see [Declarative state](#declarative-state) |
| `aptly.configOverrides` | `{}` | raw aptly config, deep-merged last — see [Configuring aptly itself](#configuring-aptly-itself) |
| `aptly.existingSecretEnv` | `[]` | Secret names to `envFrom`, for `${VAR}` placeholders inside `configOverrides` |
### Security
| Key | Default | Description |
|---|---|---|
| `security.preset` | `publicRead` | `open` \| `publicRead` \| `authenticated` \| `readOnly` — see [Security modes](#security-modes) |
| `security.auth.users` | `{}` | `name: plaintext-password` map, hashed at pod start |
| `security.auth.existingSecret` | `""` | pre-built `htpasswd` Secret — wins over `users` |
| `security.auth.internalUser.enabled` | `true` | credentials the reconcile Job authenticates through nginx with, in every preset |
| `security.auth.internalUser.username` | `aptly-internal` | |
| `security.trustedProxies` | `[]` | CIDRs to trust `X-Forwarded-For` from — required for `allowCIDRs` to be meaningful behind an Ingress |
| `security.read.enabled` | `true` | overrides the preset |
| `security.read.requireAuth` | `null` | `null` = preset's value |
| `security.read.allowCIDRs` | `[]` | |
| `security.write.enabled` | `true` | overrides the preset |
| `security.write.requireAuth` | `null` | `null` = preset's value |
| `security.write.allowCIDRs` | `[]` | |
| `security.write.inClusterOnly` | `false` | in `ingress.mode: split`, omits the API Ingress entirely |
### Proxy
| Key | Default | Description |
|---|---|---|
| `proxy.enabled` | `true` | `false` = aptly serves reads itself (`serve_in_api_mode`), no nginx split — only sane with `security.preset: open` |
| `proxy.compatPaths` | `true` | also serve the tree under `/repos/<name>/`, aptly's own URL shape |
| `proxy.maxUploadSize` | `"0"` | nginx `client_max_body_size`, `"0"` = unlimited |
| `proxy.readTimeout` | `3600s` | |
| `proxy.publishEndpointName` | `public` | the `filesystem_publish_endpoints` key aptly publishes under |
### Persistence
| Key | Default | Description |
|---|---|---|
| `persistence.enabled` | `true` | `false` = `emptyDir` |
| `persistence.existingClaim` | `""` | **set this in production** — see [Storage](#storage) |
| `persistence.storageClass` | `""` | falls back to `global.defaultStorageClass` |
| `persistence.accessMode` | `ReadWriteOnce` | |
| `persistence.size` | `20Gi` | immutable once installed unless using `existingClaim` |
| `persistence.annotations` | `{}` | |
### Workload
| Key | Default | Description |
|---|---|---|
| `workload.updateStrategy.type` | `RollingUpdate` | safe with `replicas: 1` on a StatefulSet |
| `workload.podManagementPolicy` | `OrderedReady` | |
| `workload.revisionHistoryLimit` | `3` | |
| `workload.terminationGracePeriodSeconds` | `60` | |
| `workload.annotations` / `podAnnotations` / `podLabels` | `{}` | |
| `podSecurityContext` | non-root, uid/gid 10001 | |
| `containerSecurityContext` | all caps dropped, read-only root fs | |
| `resources` | `{}` | the `aptly` container |
| `probes.startup` / `.readiness` / `.liveness` | see `values.yaml` | tuned for LevelDB recovery time on unclean shutdown |
### Networking
| Key | Default | Description |
|---|---|---|
| `service.type` | `ClusterIP` | |
| `service.port` | `8080` | |
| `service.annotations` | `{}` | |
| `ingress.enabled` | `false` | |
| `ingress.mode` | `single` | `single` \| `split` — see [docs/security.md](https://git.morlana.online/f.weber/aptly-containerized/src/branch/main/docs/security.md) |
| `ingress.className` | `""` | |
| `ingress.annotations` | body-size/read-timeout defaults for nginx-ingress | |
| `ingress.repo.host` / `.path` / `.pathType` / `.tls` | | apt-client-facing Ingress |
| `ingress.api.enabled` / `.host` / `.className` / `.annotations` / `.tls` | | `split` mode only |
| `gateway.enabled` | `false` | independent of `ingress.enabled` — both may be `true` at once, see [Gateway API](#gateway-api) |
| `gateway.apiVersion` | `gateway.networking.k8s.io/v1` | override only for pre-GA clusters |
| `gateway.mode` | `single` | `single` \| `split` — same meaning as `ingress.mode` |
| `gateway.parentRefs` | `[]` | required when `gateway.enabled: true` — `[{name, namespace, sectionName}]` |
| `gateway.repo.hostnames` / `.path` / `.pathType` | | apt-client-facing `HTTPRoute`; `pathType` is Gateway API's own enum (`PathPrefix`/`Exact`/`RegularExpression`), distinct from `ingress.repo.pathType`'s |
| `gateway.api.enabled` / `.hostnames` / `.parentRefs` | | `split` mode only; `.parentRefs` falls back to `gateway.parentRefs` when unset |
| `networkPolicy.enabled` | `false` | |
| `networkPolicy.allowedNamespaces` | `[]` | empty = no ingress restriction |
| `networkPolicy.extraIngress` | `[]` | |
| `networkPolicy.egress.allowAll` | `true` | disabling this breaks mirrors unless you add `egress.extra` rules yourself |
### Metrics
| Key | Default | Description |
|---|---|---|
| `metrics.service.enabled` | `false` | separate, unauthenticated port |
| `metrics.service.port` | `9090` | |
| `metrics.serviceMonitor.enabled` | `false` | requires the Prometheus Operator CRDs |
| `metrics.serviceMonitor.interval` | `30s` | |
### Reconcile
| Key | Default | Description |
|---|---|---|
| `reconcile.enabled` | `true` | |
| `reconcile.mode` | `hook` | `hook` \| `job` (GitOps-friendly, hashed name) \| `manual` |
| `reconcile.failOnError` | `false` | `true` makes an unreachable mirror fail the release |
| `reconcile.timeoutSeconds` | `600` | |
| `reconcile.image` | `{}` | overrides `repository`/`tag`/`pullPolicy`; defaults to the main `image` |
| `reconcile.resources` | `{}` | |
### Pod disruption & scheduling
| Key | Default | Description |
|---|---|---|
| `podDisruptionBudget.enabled` | `false` | |
| `podDisruptionBudget.maxUnavailable` | `1` | never set `minAvailable` here — with `replicas: 1` it blocks every node drain forever |
| `nodeSelector` / `tolerations` / `affinity` / `topologySpreadConstraints` / `priorityClassName` | | standard scheduling escape hatches |
### Escape hatches
| Key | Default | Description |
|---|---|---|
| `extraEnv` / `extraEnvFrom` | `[]` | on the `aptly` container |
| `extraVolumes` / `extraVolumeMounts` | `[]` | |
| `extraInitContainers` / `extraContainers` | `[]` | |
| `global.imageRegistry` | `""` | prefixes both `image.repository` and `nginx.image.repository` |
| `global.imagePullSecrets` | `[]` | |
| `global.defaultStorageClass` | `""` | |
## License
MIT. See [LICENSE](https://git.morlana.online/f.weber/aptly-containerized/src/branch/main/LICENSE)
and [NOTICE.md](https://git.morlana.online/f.weber/aptly-containerized/src/branch/main/NOTICE.md)
in the repository.