Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
172 commits
Select commit Hold shift + click to select a range
44191da
feat: get changes from the PoC (platform secrets as sealed secrest) b…
ferruhcihan Feb 18, 2026
8775f5a
feat: create core secrets in apl-secrets namespace
ferruhcihan Feb 18, 2026
45a1861
fix: add default value for the existingSecret
ferruhcihan Feb 18, 2026
cd503a9
fix: namespace changes
ferruhcihan Feb 18, 2026
edc8ffd
test: sealed secrets with eso
ferruhcihan Feb 18, 2026
0a4cc5a
fix: merge conflicts/changes
ferruhcihan Feb 19, 2026
c5b029f
fix: merge conflicts/changes
ferruhcihan Feb 19, 2026
4fd4dfe
fix: merge conflicts/changes
ferruhcihan Feb 19, 2026
0d8ca84
feat: waiting for sealed secrets
ferruhcihan Feb 19, 2026
431bc0f
feat: move function to k8s.ts
ferruhcihan Feb 19, 2026
8ac4c96
feat: use kubernetes package instead of kubectl
ferruhcihan Feb 20, 2026
1eaf457
Merge branch 'main' into APL-523
ferruhcihan Feb 20, 2026
16f6b27
fix: sealed secret tests
ferruhcihan Feb 20, 2026
9f62106
feat: remove init and prepare endpoints
ferruhcihan Feb 20, 2026
ea466f9
fix: harbor secrets
ferruhcihan Feb 20, 2026
db046ba
feat: update tools image and remove /apl/schema endpoint
ferruhcihan Feb 20, 2026
d48c3bb
fix: versions
ferruhcihan Feb 20, 2026
952a2d1
Merge branch 'main' into APL-523
ferruhcihan Feb 20, 2026
286faf3
test: tools image
ferruhcihan Feb 21, 2026
41a30f9
test: tools image
ferruhcihan Feb 21, 2026
1644634
feat: remove kms from bootstrap files
ferruhcihan Feb 21, 2026
f3755a6
test: tools image
ferruhcihan Feb 21, 2026
18d84ac
feat: remove kms and sops related code
ferruhcihan Feb 21, 2026
8cd84f7
test: tools image
ferruhcihan Feb 21, 2026
13f73c4
feat: update user management
ferruhcihan Feb 22, 2026
5dcded5
feat: update user management
ferruhcihan Feb 22, 2026
85d4a32
fix: create initial platform admin user
ferruhcihan Feb 22, 2026
4951838
fix: create initial platform admin user
ferruhcihan Feb 22, 2026
dfe9f7f
Merge branch 'main' into APL-523
ferruhcihan Feb 24, 2026
27bf17d
Merge branch 'main' into APL-523
svcAPLBot Feb 24, 2026
78a8c9a
Merge branch 'main' into APL-523
svcAPLBot Feb 24, 2026
b5ec54c
Merge branch 'main' into APL-523
svcAPLBot Feb 24, 2026
1e1c892
Merge branch 'main' into APL-523
svcAPLBot Feb 25, 2026
1fa5be8
revert: sops changes for the migration
ferruhcihan Feb 25, 2026
5ae5903
Merge branch 'main' into APL-523
svcAPLBot Feb 25, 2026
2723ef2
Merge branch 'main' into APL-523
svcAPLBot Feb 25, 2026
259adc7
Merge branch 'main' into APL-523
svcAPLBot Feb 25, 2026
df9af60
Merge branch 'main' into APL-523
svcAPLBot Feb 25, 2026
b576980
Merge branch 'main' into APL-523
svcAPLBot Feb 25, 2026
96a4cc1
Merge branch 'main' into APL-523
svcAPLBot Feb 25, 2026
bbdeaff
test: platform secrets migration
ferruhcihan Feb 25, 2026
81fee23
Merge branch 'main' into APL-523
svcAPLBot Feb 25, 2026
44781ee
fix: platform secrets migration
ferruhcihan Feb 25, 2026
d9a168a
fix: platform secrets migration
ferruhcihan Feb 25, 2026
c28e7d8
fix: platform secrets migration
ferruhcihan Feb 25, 2026
7b4574c
fix: platform secrets migration
ferruhcihan Feb 25, 2026
23b900f
test: versions
ferruhcihan Feb 25, 2026
1199673
fix: sealed secrets opaque type
ferruhcihan Feb 25, 2026
2c6bc1f
fix: sealed secrets opaque type test
ferruhcihan Feb 26, 2026
ecd8f7c
Merge branch 'main' into APL-523
svcAPLBot Feb 27, 2026
52c57b7
Merge branch 'main' into APL-523
svcAPLBot Feb 27, 2026
324b056
Merge branch 'main' into APL-523
svcAPLBot Feb 27, 2026
fbbfbc2
Merge branch 'main' into APL-523
svcAPLBot Feb 27, 2026
b988473
Merge branch 'main' into APL-523
ferruhcihan Feb 27, 2026
a0ed525
fix: installer tests
ferruhcihan Feb 27, 2026
aa3e3a1
feat: sealed secrets disaster recovery
ferruhcihan Feb 27, 2026
c75e87e
Merge branch 'main' into APL-523
svcAPLBot Mar 2, 2026
86f1dc2
Merge branch 'main' into APL-523
svcAPLBot Mar 2, 2026
beffad6
feat: improve users during bootstrap
ferruhcihan Mar 2, 2026
c16577e
fix: update sealed secret manifests path
ferruhcihan Mar 2, 2026
0f4d223
feat: update tests/fixtures for local dev env users
ferruhcihan Mar 2, 2026
6aa05e6
fix: update tests/fixtures for local dev env users
ferruhcihan Mar 2, 2026
09c9d0c
Merge branch 'main' into APL-523
svcAPLBot Mar 3, 2026
d3b24b9
Merge branch 'main' into APL-523
svcAPLBot Mar 3, 2026
1f5e7e0
fix: ci error
ferruhcihan Mar 3, 2026
f949522
Merge branch 'main' into APL-523
svcAPLBot Mar 4, 2026
ff2f81d
Merge branch 'main' into APL-523
svcAPLBot Mar 4, 2026
3219b39
Merge branch 'main' into APL-523
svcAPLBot Mar 4, 2026
504b0ee
Merge branch 'main' into APL-523
svcAPLBot Mar 4, 2026
9492266
Merge remote-tracking branch 'origin/main' into APL-523
ferruhcihan Mar 4, 2026
e5d7fed
feat: enhance sealed secrets management and update dependencies
ferruhcihan Mar 4, 2026
be165b2
feat: update sealed secrets handling to return applied secrets list
ferruhcihan Mar 4, 2026
526ee12
fix: secret data keys
ferruhcihan Mar 4, 2026
22143df
fix: values-schema x-secret fields
ferruhcihan Mar 5, 2026
b10418a
fix: restart sealed secrets controller
ferruhcihan Mar 5, 2026
20eb516
fix: remove x-secret field from customRootCA
ferruhcihan Mar 5, 2026
f2a8669
Merge branch 'main' into APL-523
svcAPLBot Mar 5, 2026
7f0a422
fix: create team settings secrets
ferruhcihan Mar 5, 2026
a0ac3f4
Merge branch 'main' into APL-523
svcAPLBot Mar 9, 2026
f333c23
fix: harbor push issues
ferruhcihan Mar 9, 2026
f49a5db
feat: use commands with cwd instead of cd
ferruhcihan Mar 9, 2026
db4524b
fix: use commands with cwd instead of cd
ferruhcihan Mar 9, 2026
e6f34cc
Merge branch 'main' into APL-523
ferruhcihan Mar 10, 2026
ba99c0d
Merge branch 'main' into APL-523
svcAPLBot Mar 10, 2026
d75feb0
Merge branch 'main' into APL-523
svcAPLBot Mar 10, 2026
bf1f4e1
Merge branch 'main' into APL-523
svcAPLBot Mar 10, 2026
c3069e8
Merge branch 'main' into APL-523
svcAPLBot Mar 10, 2026
567cc7f
Merge branch 'main' into APL-523
svcAPLBot Mar 10, 2026
01d1db2
Merge branch 'main' into APL-523
svcAPLBot Mar 10, 2026
e4f1fa9
Merge branch 'main' into APL-523
svcAPLBot Mar 10, 2026
7764233
Merge branch 'main' into APL-523
svcAPLBot Mar 10, 2026
b78add8
Merge branch 'main' into APL-523
svcAPLBot Mar 11, 2026
383c802
Merge branch 'main' into APL-523
svcAPLBot Mar 11, 2026
6c9f846
Merge branch 'main' into APL-523
svcAPLBot Mar 11, 2026
1f1d40f
Merge branch 'main' into APL-523
svcAPLBot Mar 11, 2026
0313ce2
Merge branch 'main' into APL-523
svcAPLBot Mar 11, 2026
8060c60
Merge branch 'main' into APL-523
svcAPLBot Mar 11, 2026
e963a94
Merge branch 'main' into APL-523
svcAPLBot Mar 12, 2026
76e1b74
Merge branch 'main' into APL-523
svcAPLBot Mar 12, 2026
e0ea02a
Merge branch 'main' into APL-523
ferruhcihan Mar 12, 2026
dd8419e
fix: update sealed secrets handling and improve deployment configurat…
ferruhcihan Mar 13, 2026
ace06e2
fix: update sealed secrets handling and rename secrets
ferruhcihan Mar 13, 2026
5ed6563
Merge branch 'main' into APL-523
svcAPLBot Mar 13, 2026
c7dc6e3
feat: remove deprecated secret files from tests/fixtures and replace …
ferruhcihan Mar 13, 2026
fe96078
Merge branch 'main' into APL-523
svcAPLBot Mar 13, 2026
55f60ac
Merge branch 'main' into APL-523
svcAPLBot Mar 13, 2026
346dad6
Merge branch 'main' into APL-523
svcAPLBot Mar 13, 2026
c0fea6e
fix: improve password retrieval logic in getRepo function
ferruhcihan Mar 16, 2026
3e4b181
Merge branch 'main' into APL-523
svcAPLBot Mar 16, 2026
9c2fd72
Merge branch 'main' into APL-523
svcAPLBot Mar 16, 2026
4c8ed82
fix: add new namespaces in core.yaml
ferruhcihan Mar 16, 2026
998b88b
Merge branch 'main' into APL-523
ferruhcihan Apr 1, 2026
1940575
fix: conditional rewrite rules for ingress
ferruhcihan Apr 1, 2026
48a2960
Merge branch 'main' into APL-523
svcAPLBot Apr 1, 2026
d6a9dd7
Merge branch 'main' into APL-523
svcAPLBot Apr 1, 2026
89e303c
Merge branch 'main' into APL-523
svcAPLBot Apr 1, 2026
8d0a018
fix: harbor registry username
ferruhcihan Apr 1, 2026
25bde58
Merge branch 'main' into APL-523
svcAPLBot Apr 2, 2026
714a1b0
Merge branch 'main' into APL-523
svcAPLBot Apr 7, 2026
b4cb969
Merge branch 'main' into APL-523
svcAPLBot Apr 8, 2026
c256ca7
chore: add agents configuration
j-zimnowoda Apr 13, 2026
fdb0b8c
chore: add agents configuration
j-zimnowoda Apr 17, 2026
e437706
Merge remote-tracking branch 'origin/main' into agents
j-zimnowoda Apr 17, 2026
5250db0
Merge branch 'main' into agents
svcAPLBot Apr 20, 2026
74ca049
Merge branch 'main' into agents
svcAPLBot Apr 20, 2026
9511b97
Merge branch 'main' into agents
svcAPLBot Apr 20, 2026
2b0fbdd
Merge branch 'main' into agents
svcAPLBot Apr 20, 2026
e9d311f
Merge branch 'main' into agents
svcAPLBot Apr 21, 2026
b20d5fc
Merge branch 'main' into agents
svcAPLBot Apr 21, 2026
73515ae
Merge branch 'main' into agents
svcAPLBot Apr 21, 2026
3b7b46b
Merge branch 'main' into agents
svcAPLBot Apr 21, 2026
3f6e3b3
Merge branch 'main' into agents
svcAPLBot Apr 21, 2026
e2e4fb0
Merge branch 'main' into agents
svcAPLBot Apr 21, 2026
cc47daf
Merge branch 'main' into agents
svcAPLBot Apr 21, 2026
219836f
Merge branch 'main' into agents
svcAPLBot Apr 22, 2026
1eb8db5
Merge branch 'main' into agents
svcAPLBot Apr 23, 2026
1b571f1
Merge branch 'main' into agents
svcAPLBot Apr 23, 2026
83d216b
Merge branch 'main' into agents
svcAPLBot Apr 23, 2026
5c1c414
Merge branch 'main' into agents
svcAPLBot Apr 23, 2026
97eaf2e
Merge branch 'main' into agents
svcAPLBot Apr 23, 2026
1db436b
Merge branch 'main' into agents
svcAPLBot Apr 24, 2026
f5fa421
Merge branch 'main' into agents
svcAPLBot Apr 24, 2026
d44b110
Merge branch 'main' into agents
svcAPLBot Apr 24, 2026
11c8d19
Merge branch 'main' into agents
svcAPLBot Apr 24, 2026
cee8d74
Merge branch 'main' into agents
svcAPLBot Apr 28, 2026
e8d11f4
Merge branch 'main' into agents
svcAPLBot Apr 29, 2026
e318517
Merge branch 'main' into agents
svcAPLBot Apr 29, 2026
bc021ba
Merge branch 'main' into agents
svcAPLBot Apr 29, 2026
03b591a
Merge branch 'main' into agents
svcAPLBot Apr 29, 2026
c5804f4
Merge branch 'main' into agents
svcAPLBot Apr 30, 2026
748351f
Merge branch 'main' into agents
svcAPLBot Apr 30, 2026
3b1f339
Merge branch 'main' into agents
svcAPLBot Apr 30, 2026
19460d5
Merge branch 'main' into agents
svcAPLBot Apr 30, 2026
e411d35
Merge branch 'main' into agents
svcAPLBot Apr 30, 2026
698fb1f
Merge branch 'main' into agents
svcAPLBot May 1, 2026
4564f39
chore: improve agents.md
j-zimnowoda May 4, 2026
e282b87
fix: restore files
j-zimnowoda May 4, 2026
d8a09b0
chore: improve agents.md
j-zimnowoda May 4, 2026
6ce26a1
chore: improve agents.md
j-zimnowoda May 4, 2026
67ad9be
chore: improve agents.md
j-zimnowoda May 4, 2026
9425c6c
Merge branch 'main' into agents
svcAPLBot May 4, 2026
ee348fb
Merge branch 'main' into agents
svcAPLBot May 6, 2026
ff20516
Merge branch 'main' into agents
svcAPLBot May 6, 2026
b3705aa
Merge branch 'main' into agents
svcAPLBot May 6, 2026
95e1654
Merge branch 'main' into agents
svcAPLBot May 6, 2026
dd38b04
Merge branch 'main' into agents
svcAPLBot May 6, 2026
bfb6d93
Merge branch 'main' into agents
svcAPLBot May 7, 2026
233fe19
Merge branch 'main' into agents
svcAPLBot May 7, 2026
b7a31b9
Merge branch 'main' into agents
svcAPLBot May 7, 2026
1897c78
Merge branch 'main' into agents
svcAPLBot May 7, 2026
23e28c3
Merge branch 'main' into agents
svcAPLBot May 7, 2026
989ed4e
Merge branch 'main' into agents
svcAPLBot May 7, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 15 additions & 142 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,145 +4,18 @@

APL Core (App Platform for Linode) is a Kubernetes platform that integrates 30+ cloud-native applications (Istio, Argo CD, Keycloak, Tekton, Harbor, etc.) into a cohesive, multi-tenant PaaS. The codebase is a hybrid of TypeScript (CLI/operators), Helm charts, Helmfile manifests, and Go templates.

**Core Architecture:** User configuration (`env/` directory) → Helmfile bases → Helmfile releases → Helm charts → Kubernetes manifests

## Critical Development Patterns

### Values Flow (3-Stage Merge)

Values are loaded in a strict 3-stage pipeline (see [ADR-2021-10-18](../adr/2021-10-18-defaults-and-derived.md)):

1. **Defaults** (`helmfile.d/snippets/defaults.yaml`) - Static defaults, will eventually come from schema
2. **User Input** (`$ENV_DIR/env/**/*.yaml`) - User-provided configuration (NEVER write defaults/derived values here)
3. **Derived Values** (`helmfile.d/snippets/derived.gotmpl`) - Computed from defaults + user input

**Critical Rule:** User input directory (`$ENV_DIR`) contains ONLY user-supplied values. Defaults and derived values must never be written back to `$ENV_DIR`.

### Helmfile Release Patterns

All Helmfile specs in `helmfile.d/` execute alphabetically. Use reusable anchors from `helmfile.d/snippets/templates.gotmpl`:

- `*default` - Standard chart deployment. Values merged: `charts/{name}/values.yaml` → `values/{name}/{name}.gotmpl` → `.Values.apps.{name}._rawValues`
- `*raw` - Deploy additional K8s manifests (operators + CRs) from `values/{name}/{name}-raw.gotmpl`
- `*rawCR` - Deploy custom resources using the `raw-cr` chart
- `*jobs` - Deploy jobs to the `maintenance` namespace using `values/jobs/{name}.gotmpl`

### Schema-Driven Validation

All user-configurable parameters MUST be defined in `values-schema.yaml` (JSON Schema). Run `npm run validate-values` to validate. The schema serves as both validation and documentation.

## CLI Commands & Workflow

### Essential Commands

```bash
# Bootstrap a new values repo (creates $ENV_DIR with defaults)
otomi bootstrap

# Validate user configuration against schema
otomi validate-values

# Validate rendered Kubernetes manifests
otomi validate-templates [-l name=myapp]

# Render values for inspection
otomi values

# Render chart values for a specific app
otomi x helmfile -l name=myapp write-values

# Deploy all charts (or use -l name=myapp for selective deploy)
otomi apply [-l name=myapp]

# Generate diff before applying
otomi diff [-l name=myapp]

# Deploy to cluster (initial setup)
otomi install
```

### Development Setup

```bash
# Install dependencies (helmfile, helm, kubectl, etc.)
npm run install-deps

# Run CLI locally (bypass Docker)
export IN_DOCKER=false
export ENV_DIR=$PWD/tests/fixtures
export NODE_ENV=test

# Compile TypeScript
npm run compile

# Run tests
npm test
```

## Integrating a New Core App

1. **Add Helm chart** to `charts/{myapp}/` (or vendor from upstream)
2. **Create values template** at `values/{myapp}/{myapp}.gotmpl`
3. **Define Helmfile release** in appropriate `helmfile.d/helmfile-*.yaml` file:
```yaml
releases:
- name: myapp
installed: {{ .Values.apps.myapp.enabled }}
namespace: my-namespace
<<: *default # or *raw, *rawCR, *jobs
```
4. **Add schema** for user-configurable properties in `values-schema.yaml` under `.definitions.apps.properties.myapp`
5. **Configure defaults** in `helmfile.d/snippets/defaults.yaml` under `apps.myapp`
6. **Add namespace** (if needed) to `core.yaml` at `k8s.namespaces`
7. **Configure ingress** (if needed) in `core.yaml` at `adminApps` or `teamApps`

## Docker-Based Execution

The `binzx/otomi` script wraps all commands in Docker by default:

- Uses `linode/apl-core:${otomi_version}` image
- Mounts `$ENV_DIR` as `/home/app/env/`
- Set `IN_DOCKER=false` to run locally (useful for cloud provider auth plugins)

## Testing Strategy

- Unit tests: `npm test` (Jest, located in `src/**/*.test.ts`)
- Integration tests: Use fixtures in `tests/fixtures/` with `NODE_ENV=test`
- Template validation: `otomi validate-templates` (validates all rendered manifests against K8s schemas)
- Policy tests: `npm run test:opa` (Rego policy testing)

## Key Files & Directories

| Path | Purpose |
| ---------------------- | -------------------------------------------- |
| `src/cmd/*.ts` | CLI command implementations |
| `helmfile.d/` | Helmfile specs (execute alphabetically) |
| `helmfile.d/snippets/` | Reusable templates, defaults, derived values |
| `charts/` | Helm charts (vendored and custom) |
| `values/` | Value templates for each chart |
| `values-schema.yaml` | JSON Schema for user configuration |
| `core.yaml` | Namespaces, ingress, team apps config |
| `binzx/otomi` | Bash wrapper for Docker-based execution |
| `adr/` | Architectural Decision Records |

## Common Gotchas

- **Helmfile labels:** Use `-l name=myapp` to select specific releases (not `-l app=myapp`)
- **Raw values override:** Use `apps.{name}._rawValues` to override chart values not in schema (use sparingly)
- **YAML anchors:** Search for `&anchorname` to find anchor definitions when you see `<<: *anchorname`
- **Keycloak integration:** Use `_derived.oidcBaseUrl`, `apps.keycloak.idp.clientID/clientSecret` for SSO
- **Untrusted CA:** Check `_derived.untrustedCA` to conditionally disable cert verification

## Debugging Tips

- Check deployment state: `otomi status`
- View traces on errors: Collected automatically in `otomi apply` failures
- Inspect Helmfile output: `otomi x helmfile -l name=myapp template`
- Local development: Use `$PWD/tests/fixtures` as `$ENV_DIR`
- Enable verbose logging: Add `-v` flag to any command

## References

- Full development guide: [docs/development.md](../docs/development.md)
- Architectural decisions: [adr/index.md](../adr/index.md)
- Public docs: https://techdocs.akamai.com/app-platform/docs/welcome
## Knowledge Base

Use AGENTS.md files as your primary reference for understanding the codebase structure, conventions, and critical patterns. Each AGENTS.md file provides a comprehensive overview of its respective directory.

| Path | Focus |
| ---------------------------------------------------------------- | --------------------------------------------------- |
| [`AGENTS.md`](AGENTS.md) | High level design |
| [`src/AGENTS.md`](src/AGENTS.md) | TypeScript source structure, conventions, dev setup |
| [`src/cmd/AGENTS.md`](src/cmd/AGENTS.md) | CLI command inventory, patterns |
| [`src/common/AGENTS.md`](src/common/AGENTS.md) | Shared utility modules, dependency graph |
| [`src/operator/AGENTS.md`](src/operator/AGENTS.md) | GitOps operator architecture, execution flow |
| [`helmfile.d/AGENTS.md`](helmfile.d/AGENTS.md) | Helmfile release phases, execution order |
| [`helmfile.d/snippets/AGENTS.md`](helmfile.d/snippets/AGENTS.md) | Critical templates, defaults, derived values |
| [`charts/AGENTS.md`](charts/AGENTS.md) | Custom vs vendored chart inventory |
| [`charts/team-ns/AGENTS.md`](charts/team-ns/AGENTS.md) | Team namespace chart (most complex) |
22 changes: 22 additions & 0 deletions .ignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# we don't allow json files in the root except package.json

.history
.tmp
_.bak
node_modules/
/coverage/
/dist/
/env/
_.DS*Store
.vscode/values-schema.yaml
*.env
/.secrets
chart/apl/values.schema.json
chart/apl/README.md
workflow/
\_.new
.envrc
otomi.cpuprofile
/.idea/
tmp
\*\*values-repo.yaml
Loading
Loading