This is an automated email from the ASF dual-hosted git repository.
oscerd pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-k.git
The following commit(s) were added to refs/heads/main by this push:
new ca8a63769 chore: add AGENTS.md, CLAUDE.md and SECURITY.md (#6635)
ca8a63769 is described below
commit ca8a63769b824ae1f24bcc217f698e770a0ee013
Author: Andrea Cosentino <[email protected]>
AuthorDate: Tue May 19 09:14:45 2026 +0200
chore: add AGENTS.md, CLAUDE.md and SECURITY.md (#6635)
* chore: add AGENTS.md, CLAUDE.md and SECURITY.md
Adds repository-root AGENTS.md (AI agent guidelines), CLAUDE.md (identical
content, mirroring apache/camel's layout), and SECURITY.md (the entry point
GitHub and security tooling expect), modeled on apache/camel but adapted for
Camel K:
- Go/Make toolchain and real targets (make build/test/lint/generate/
update-docs), not Maven.
- GitHub Issues workflow and the project's branch/commit conventions,
not JIRA.
- Go async-testing guidance (Gomega Eventually, no time.Sleep).
- Security Model section wired to docs/threat-model.md as the additive
Camel-K sub-project expansion of the umbrella Apache Camel Security Model;
SECURITY.md points to it for scope and to the ASF process for private
disclosure.
Note: SECURITY.md and AGENTS.md reference docs/threat-model.md, added by
PR #6634; those repo-relative links resolve once #6634 merges.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* chore: address review feedback on AGENTS.md
squakez: don't hardcode the Camel K version and Go version in the agent
guidelines (they go stale). Instruct the agent to read them from the
authoritative sources instead: version from pkg/util/defaults/defaults.go
(or 'make get-version'), Go from the go directive in go.mod. Applied
identically to CLAUDE.md to keep the two files in sync.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
---
AGENTS.md | 357 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
CLAUDE.md | 357 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
SECURITY.md | 35 ++++++
3 files changed, 749 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..81cd04824
--- /dev/null
+++ b/AGENTS.md
@@ -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)
+- [email protected]
+- https://camel.zulipchat.com/
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..81cd04824
--- /dev/null
+++ b/CLAUDE.md
@@ -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)
+- [email protected]
+- https://camel.zulipchat.com/
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 000000000..f8c5d1d6c
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,35 @@
+# Security Policy
+
+## Supported Versions
+
+Apache Camel K is released and supported under the Apache Camel umbrella. For
the currently
+supported versions and their compatibility, see the
+[Camel K release
page](https://camel.apache.org/camel-k/next/installation/installation.html)
+and the [GitHub releases](https://github.com/apache/camel-k/releases).
+
+## Reporting a Vulnerability
+
+Apache Camel K follows the Apache Software Foundation security process. For
information on how
+to report a new security problem please see
[here](https://camel.apache.org/security/).
+
+**Do not** open a public GitHub issue, pull request, or discussion for a
suspected
+vulnerability — report it privately through the ASF process above
([email protected]).
+
+## Security Model
+
+Before submitting a report, please read the project's
+[Threat Model](docs/threat-model.md). It documents who is trusted, where the
trust boundaries
+sit, which findings count as a Camel K vulnerability, and which categories are
out of scope —
+e.g. a CR author running code in their own namespace (by design),
platform-admin actions, a
+hostile Maven repository / registry / base image / remote Kamelet catalog the
deployer chose
+to trust, the deployed route's own runtime behaviour (Apache Camel core's
model), behaviour
+reachable only under a discouraged non-default knob, and
shipped-but-unsupported code.
+
+The Camel K threat model is the additive 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
documented by
+Camel K's own threat model. A `docs/threat-model.yaml` sidecar mirrors the
triage-relevant
+facts for automated tooling.
+
+Reports outside the documented scope will be closed with a reference to that
document.
