apache
diff --git a/‎AGENTS.md‎
Lines changed: 357 additions & 0 deletions b/‎AGENTS.md‎
Lines changed: 357 additions & 0 deletions
@@ -0,0 +1,357 @@
+# Apache Camel K - AI Agent Guidelines
+
+Guidelines for AI agents working on this codebase.
+
+## Project Info
+
+Apache Camel K is a Kubernetes-native integration platform built on Apache Camel. It is a
+Go **operator** plus the `kamel` **CLI** that turn user-supplied Camel route Custom Resources
+(`Integration`, `Pipe`, `Kamelet`, …) into built container images and running workloads on
+Kubernetes/OpenShift.
+
+- Version: not hardcoded — read it from `pkg/util/defaults/defaults.go`
+  (`Version = "…"`), or run `make get-version`.
+- Go: not hardcoded — read the `go` directive in `go.mod`.
+- Build: `make` (Go toolchain, not Maven)
+- Module: `github.com/apache/camel-k/v2` (see `go.mod`)
+- Issue tracker: **GitHub Issues** (not JIRA)
+
+## AI Agent Rules of Engagement
+
+These rules apply to ALL AI agents working on this codebase.
+
+### Attribution
+
+- All AI-generated content (GitHub PR descriptions, review comments, issue comments) MUST clearly
+  identify itself as AI-generated and mention the human operator.
+  Example: "_Claude Code on behalf of [Human Name]_"
+
+### PR Volume
+
+- An agent MUST NOT open more than 10 PRs per day per operator to ensure human reviewers can keep up.
+- Prioritize quality over quantity — fewer well-tested PRs are better than many shallow ones.
+
+### Git branch
+
+- An agent MUST NEVER push commits to a branch it did not create.
+- If a contributor's PR needs changes, the agent may suggest changes via review comments,
+  but must not push to their branch without explicit permission.
+- An agent should prefer to use its own fork to push branches instead of the main
+  `apache/camel-k` repository. It avoids filling the main repository with a long list of
+  uncleaned branches.
+- An agent must provide a useful branch name following the project conventions:
+  `fix/<ISSUE_NUMBER>`, `feature/<ISSUE_NUMBER>-<short-slug>`, `bugfix/<ISSUE_NUMBER>`,
+  `quick-fix/<short-slug>`, or `ci-issue/<short-slug>`.
+- After a Pull Request is merged or rejected, the branch should be deleted.
+
+### GitHub Issue Ownership
+
+- An agent MUST ONLY pick up **unassigned** GitHub issues.
+- If an issue is already assigned to a human, the agent must not reassign it or work on it.
+- Before starting work, the agent must assign the issue to its operator.
+- Link the PR to the issue (`Fixes #<ISSUE_NUMBER>`) so it is closed on merge, and apply the
+  relevant labels/milestone before closing where the project uses them.
+
+### PR Description Maintenance
+
+When pushing new commits to a PR, **always update the PR description** (and title if needed) to
+reflect the current state of the changeset. PRs evolve across commits — the description must stay
+accurate and complete. Use `gh pr edit --title "..." --body "..."` after each push.
+
+### PR Reviewers
+
+When creating a PR, **always identify and request reviews** from the most relevant committers:
+
+- Run `git log --format='%an' --since='1 year' -- <affected-files> | sort | uniq -c | sort -rn | head -10`
+  to find who has been most active on the affected files.
+- Use `git blame` on key modified files to identify who wrote the code being changed.
+- Cross-reference with the [committer list](https://home.apache.org/committers-by-project.html#camel)
+  to ensure you request reviews from active committers (not just contributors).
+- For controller/trait/builder changes, prefer reviewers who recently worked on that area.
+- For cross-cutting changes (apis, controller, platform), include committers with broader
+  project knowledge.
+- Request review from **at least 2 relevant committers** using `gh pr edit --add-reviewer`.
+- When all comments on the Pull Request are addressed (by providing a fix or more explanation)
+  and the PR checks are green, re-request review so reviewers know the new changeset is ready.
+
+### Merge Requirements
+
+- An agent MUST NOT merge a PR if there are any **unresolved review conversations**.
+- An agent MUST NOT merge a PR without at least **one human approval**.
+- An agent MUST NOT approve its own PRs — human review is always required.
+
+### Code Quality
+
+- Every PR must include tests for new functionality or bug fixes.
+- Every PR must include documentation updates where applicable.
+- All code must be formatted (`make fmt` and `make goimport`) and pass `make lint`
+  (golangci-lint) before pushing.
+- All generated artifacts must be regenerated and committed — run `make generate` (codegen,
+  CRDs, deepcopy, RBAC) and `make update-docs` (autogenerated trait docs). CI fails if there
+  are uncommitted changes after a build.
+
+### Asynchronous Testing: Use `Eventually`, not `time.Sleep`
+
+Do **NOT** use `time.Sleep()` to wait for asynchronous state in tests. It leads to flaky, slow,
+and non-deterministic tests. Use polling with a timeout instead — Gomega's `Eventually` in the
+e2e suites, or a bounded poll helper in unit tests.
+
+**Example — waiting for an Integration to reach the running phase (e2e):**
+
+```go
+import (
+	. "github.com/onsi/gomega"
+	v1 "github.com/apache/camel-k/v2/pkg/apis/camel/v1"
+)
+
+Eventually(IntegrationPhase(t, ctx, ns, "my-it"), TestTimeoutMedium).
+	Should(Equal(v1.IntegrationPhaseRunning))
+```
+
+**Rules:**
+
+- New test code MUST NOT introduce `time.Sleep()` to await state.
+- When modifying existing test code that sleeps to await state, migrate it to `Eventually`.
+- Always set an explicit timeout to avoid hanging builds.
+- Use a clear assertion/predicate — do not replace a sleep with a busy-wait loop.
+
+### Issue Investigation (Before Implementation)
+
+Before implementing a fix for a GitHub issue, **thoroughly investigate** the issue's validity
+and context. Camel K coordinates many moving parts (operator, builds, traits, CRDs, the
+Camel runtime); code often looks "wrong" but exists for good reasons. Do NOT jump straight to
+implementation after reading the issue description and the current code.
+
+**Required investigation steps:**
+
+1. **Validate the issue**: Confirm the reported problem is real and reproducible. Question
+   assumptions in the issue description — they may be incomplete or based on misunderstanding.
+2. **Check git history**: Run `git log --oneline <file>` and `git blame <file>` on the affected
+   code. Read commit messages and linked issues/PRs to understand *why* the code is the way it is.
+3. **Search for related issues**: Search GitHub for related issues/PRs (same area, similar
+   keywords) to find prior discussions, rejected approaches, or intentional design decisions.
+4. **Look for design documents**: Check the `proposals/` directory for design docs (`.adoc`)
+   that may explain architectural decisions. Key proposals by area:
+   - **Security / monitoring** (RBAC, metrics endpoint hardening, multi-tenancy):
+     [`proposals/monitoring-security.adoc`](proposals/monitoring-security.adoc)
+   - **Kamelets** (provided kamelet catalog): [`proposals/provided-kamelets.adoc`](proposals/provided-kamelets.adoc)
+   - **Service binding**: [`proposals/service-binding.adoc`](proposals/service-binding.adoc)
+   - **Threat model** (trust boundaries, what is a vulnerability): [`docs/threat-model.md`](docs/threat-model.md)
+5. **Understand the broader context**: If the issue involves a feature that replaced or
+   deprecated another (e.g. `pod` trait, synthetic Integrations, multi-operator), understand
+   *why* the change was made and what was intentionally changed vs. accidentally omitted.
+6. **Check if the "fix" reverts prior work**: If your proposed change effectively reverts a
+   prior intentional commit, stop and reconsider. If the revert is still justified, explicitly
+   acknowledge it in the PR description and explain why despite the original rationale.
+
+**Present your findings** to the operator before implementing. Flag any risks, ambiguities, or
+cases where the issue may be invalid or the proposed approach may conflict with prior decisions.
+
+### Knowledge Cutoff Awareness
+
+AI agents have a training data cutoff and may not know about recent releases, API changes, or
+deprecations in external projects (Kubernetes, Knative, Quarkus, the Camel runtime). **Never
+make authoritative claims about external project state based solely on training knowledge.**
+
+- When an issue, PR, or code references a specific version of an external dependency, **verify
+  it exists** via official sources before questioning or relying on it.
+- When implementing or reviewing changes that depend on external project behavior, verify the
+  current state rather than assuming training data is up to date.
+- If uncertain whether something exists or has changed, say so and verify — do not confidently
+  assert something is wrong based on potentially stale knowledge.
+
+### Git History Review (When Reviewing PRs)
+
+When reviewing PRs, apply the same investigative rigor:
+
+- Check `git log` and `git blame` on modified files to see if the change conflicts with prior
+  intentional decisions.
+- Verify that "fixes" don't revert deliberate behavior without justification.
+- Check for design proposals (`proposals/*.adoc`) and the threat model
+  (`docs/threat-model.md`) related to the affected area.
+- Search for related GitHub issues that provide context on why the code was written that way.
+
+### Documentation Conventions
+
+When writing or modifying `.adoc` documentation under `docs/modules/`:
+
+- **Use `xref:` for internal links**, never external `https://camel.apache.org/camel-k/...`
+  URLs.
+- Trait reference pages and parts of the docs are **autogenerated** (see `cmd/util/doc-gen`
+  and the `// Start of autogenerated code - DO NOT EDIT!` markers). Do not hand-edit
+  autogenerated blocks; change the Go source and run `make update-docs`.
+- When reviewing doc PRs, check that `xref:` links and the Antora nav resolve correctly.
+
+## Security Model
+
+Camel K has a documented threat model that defines who is trusted, where the trust boundaries
+sit, what counts as a Camel K vulnerability, and what is operator/deployer responsibility. The
+canonical document is [`docs/threat-model.md`](docs/threat-model.md). It is the **additive
+Camel-K sub-project expansion** of the umbrella
+[Apache Camel Security Model](https://camel.apache.org/manual/security-model.html), which
+explicitly scopes itself to "Camel embedded in someone else's application, **not a multi-tenant
+managed service**" — the Kubernetes operator / Custom Resource / cluster layer is Camel K's to
+model. Use `docs/threat-model.md` (and its `docs/threat-model.yaml` triage sidecar) when
+triaging security reports, deciding whether a finding warrants a CVE, or reviewing a
+security-sensitive PR.
+
+For the vulnerability **reporting** convention, [`SECURITY.md`](SECURITY.md) at the repository
+root is the entry point GitHub and security tooling expect. It points to the threat model for
+scope and to the ASF process for private disclosure. An agent that discovers or is handed a
+suspected vulnerability MUST NOT open a public issue, PR, or mailing-list post about it —
+follow the private process in `SECURITY.md` and stop.
+
+### Trust assumptions (Camel K layer)
+
+- **Platform admins / operator-deployers** are **fully trusted**. They install the operator,
+  set its RBAC, and edit `IntegrationPlatform` / `IntegrationProfile` (registry, base image,
+  Maven settings, build strategy). Compromise here is total and out of model.
+- **CR authors** (whoever can create/patch `Integration`, `Pipe`, `Kamelet`,
+  `IntegrationKit`, `Build`, `IntegrationProfile`) are trusted **only at the target
+  namespace's level**. Submitting such a CR is, by design, arbitrary code and container
+  execution in that namespace; the only gate is Kubernetes RBAC.
+- **Cluster tenants without Camel K CR RBAC** are **untrusted** and in scope as adversaries.
+- **Network clients of the deployed integration** are **untrusted**; the running route's own
+  attack surface is **Apache Camel core's** threat model, not Camel K's.
+
+### What is in scope (concise summary)
+
+- A principal **without** Camel K CR RBAC causing builds/workloads, or reading another
+  tenant's secrets/artifacts through the operator.
+- **Cross-namespace / cross-trust escalation** via the operator (it can create
+  `roles`/`rolebindings`/`clusterrolebindings`, `serviceaccounts`, and `pods/exec`): any path
+  by which creating a CR in namespace A yields rights in namespace B / cluster-scope the
+  author lacked is `VALID`.
+- Camel K weakening or bypassing Kubernetes RBAC as the authorization gate.
+- Insecure defaults the operator ships that expose the above with zero extra configuration.
+
+### What is out of scope
+
+- A CR author running arbitrary code/containers in their own namespace (trusted at that
+  level — by design, not a vulnerability), incl. `builder.tasks`, `container.image`, the
+  `pod` trait, `spec.template`.
+- Platform-admin / `IntegrationPlatform` editor actions; a hostile Maven repo / registry /
+  base image / remote Kamelet catalog the deployer chose to trust (supply chain is the
+  deployer's).
+- The deployed route's own runtime behavior (Apache Camel core's model).
+- Behavior reachable only under a non-default, discouraged knob (`registry.insecure`,
+  Maven `InsecureSkipVerify`, `routine` build strategy with untrusted CR authors).
+- Shipped-but-unsupported code (`examples/`, `e2e/`, `proposals/`, samples, deprecated
+  Buildah/Kaniko/Spectrum tasks, `pod` trait, synthetic Integrations, multi-operator).
+- Automated scanner reports without a PoC demonstrating an actual trust-boundary breach.
+
+### Operator hardening checklist
+
+When reviewing or recommending a deployment, surface the following:
+
+- Treat "create/patch `Integration` / `Pipe` / `Kamelet` / `IntegrationKit` / `Build` /
+  `IntegrationProfile` in namespace N" as equivalent to "run arbitrary code in N" — grant
+  that RBAC only to principals trusted at that level.
+- Lock down `IntegrationPlatform` / `IntegrationProfile` and the install namespace.
+- For untrusted or multi-tenant CR authors, use the **`pod` build strategy**, not `routine`
+  (which runs the Maven build inside the operator pod). This is required, not advisory.
+- Provide a trusted Maven proxy/mirror and a controlled registry; never enable
+  `insecure` / `InsecureSkipVerify` in production.
+- Apply Kubernetes-native isolation: namespaces, Pod Security Admission,
+  ResourceQuota/LimitRange, NetworkPolicies (Camel K ships none).
+- Set `runAsNonRoot` / `runAsUser` explicitly — the default does not.
+
+### Committer review checklist (for security-sensitive PRs)
+
+When reviewing a PR that touches the operator, a controller, a trait, the builder, RBAC
+manifests, or a CRD:
+
+- Does a new CR field or trait give a CR author new control over images, commands, mounts,
+  the raw pod spec, or the build? If so it must be covered by `docs/threat-model.md` §4.6.
+- Does the change widen the operator's RBAC (`secrets`, `rolebindings`,
+  `clusterrolebindings`, `pods/exec`, cross-namespace)? Cross-namespace/cross-trust
+  escalation is `VALID` — justify and minimize.
+- Does the change add a new external fetch (Maven repo, registry, remote Kamelet catalog,
+  git, HTTP source)? Note it as a supply-chain edge.
+- Does it relax a security-relevant default (build strategy, `runAsNonRoot`, TLS verify)?
+  New defaults err toward the safer value; a relaxation needs an upgrade note and PMC
+  sign-off, and a matching update to `docs/threat-model.md` (§4.5a / §4.12).
+- Does it ship or change an admission webhook? Today there is none by design — adding one
+  moves the §4.4 trust boundary and must be reflected in the threat model.
+
+## Structure
+
+```
+camel-k/
+├── cmd/kamel/        # kamel CLI entrypoint
+├── pkg/
+│   ├── apis/         # CRD Go types (camel.apache.org/v1)
+│   ├── controller/   # reconcilers (integration, integrationkit, build, …)
+│   ├── trait/        # traits (how a CR maps to Kubernetes resources)
+│   ├── builder/      # build subsystem (Maven, Jib, S2I)
+│   ├── cmd/           # CLI + operator command implementations
+│   ├── platform/     # IntegrationPlatform defaults & helpers
+│   ├── client/       # generated Kubernetes client
+│   └── resources/    # embedded manifests (CRDs, RBAC, samples)
+├── e2e/              # end-to-end test suites
+├── helm/ , install/  # install assets (Helm chart, Kustomize overlays)
+├── proposals/        # design proposals (.adoc)
+├── docs/             # Antora AsciiDoc docs + threat-model.md / .yaml
+└── script/           # Makefile and build scripts
+```
+
+## Build
+
+```bash
+make build          # codegen + resources + unit tests + kamel + e2e compile (full)
+make build-kamel    # build just the kamel CLI binary
+make generate       # regenerate codegen, CRDs, deepcopy, RBAC
+make update-docs    # regenerate autogenerated documentation (e.g. trait pages)
+make fmt goimport   # format Go code and imports
+make lint           # golangci-lint
+make check          # lint + vulnerability scan (govulncheck)
+```
+
+Do NOT parallelize resource-intensive build/test jobs.
+
+## Testing
+
+```bash
+make test           # unit tests
+make test-common    # common e2e suite (requires a cluster)
+make test-smoke     # smoke e2e suite
+# other suites: test-advanced, test-knative, test-kafka, test-gateway,
+# test-telemetry, test-install, test-quarkus-native, …
+```
+
+E2E suites need a reachable Kubernetes cluster and use Gomega `Eventually` for asynchronous
+assertions (see the async-testing rule above).
+
+## Conventions
+
+- Standard Go conventions: `gofmt`/`make fmt`, `go vet`, and `make lint` (golangci-lint,
+  see `.golangci.yml`) must pass.
+- Follow the existing **trait** pattern in `pkg/trait` and the **Action/state-machine**
+  controller pattern in `pkg/controller` rather than inventing new shapes.
+- Keep CRD Go types in `pkg/apis/camel/v1` in sync with generated CRDs/RBAC — run
+  `make generate` and commit the result.
+- Maintain backwards compatibility for public Go APIs and CRD fields; do not change CRD
+  field semantics without a justification and an upgrade note.
+- Deprecation: mark Go fields/traits with a `// Deprecated:` comment, reflect it in the CRD
+  schema/catalog, and document it in the upgrade notes. Deprecated surface is in *limited*
+  scope for security (documented migration is the primary remediation); removed surface is
+  out of scope.
+
+## Commits
+
+```
+Fix #<ISSUE_NUMBER>: Brief description     # bug/feature tied to a GitHub issue
+chore: Brief description                    # quick-fix / no issue
+ci: Brief description                       # CI-only change
+```
+
+Reference the GitHub issue (`Fixes #<n>`) when applicable so it closes on merge.
+
+## Links
+
+- https://camel.apache.org/camel-k/
+- https://github.com/apache/camel-k
+- https://github.com/apache/camel-k/issues
+- https://camel.apache.org/manual/security-model.html (umbrella Apache Camel Security Model)
+- dev@camel.apache.org
+- https://camel.zulipchat.com/