Add docs/principles.md for operator design principles#4496
Merged
caseydavenport merged 4 commits intotigera:masterfrom Mar 5, 2026
Merged
Add docs/principles.md for operator design principles#4496caseydavenport merged 4 commits intotigera:masterfrom
caseydavenport merged 4 commits intotigera:masterfrom
Conversation
Codifies the key architecture and design principles we follow when developing in this repo — API design, user input handling, component isolation, controller patterns, security, and certificate conventions. Also refactors dev_guidelines.md to focus on workflow and reference principles.md for design guidance.
Controller pattern, certificates/secrets, and design principle highlights are now in principles.md — no need to maintain them in two places. Also fixes the project overview to reflect the calico-system namespace default.
rene-dekker
reviewed
Mar 5, 2026
docs/principles.md
Outdated
|
|
||
| ## Security | ||
|
|
||
| - **Component-to-component communication must use mTLS.** All internal communication between operator-managed components must be secured with mutual TLS. |
Member
There was a problem hiding this comment.
We use a combination of mTLS and TLS + token auth.
Member
Author
There was a problem hiding this comment.
@rene-dekker Where is TLS + token authz used? And what would be the guiding principle on when / where to use one vs. the other?
Member
There was a problem hiding this comment.
I would think mTLS is preferred, but both are secure.
If components would talk to components outside of the cluster then mTLS has the advantage that we can have identity being managed at a higher level than the cluster signer of JWTs. I'm thinking of technologies like Spiffe/Spire.
There are some places where service accounts talk directly to servers using their own JWT, like Manager -> Queryserver, prometheus server.
rene-dekker
reviewed
Mar 5, 2026
rene-dekker
reviewed
Mar 5, 2026
- Security: mTLS isn't the only pattern, also TLS + token auth - Certs: remove inaccurate Passthrough claim and outdated naming conventions
Not just secrets — any object the operator creates should have an OwnerReference, with exceptions for things like CRDs where cascading deletion would be catastrophic.
rene-dekker
approved these changes
Mar 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a new
docs/principles.mdthat codifies the key architecture and design principles for developing in this repo:calico-system(separate namespaces only when specifically needed)Also refactors
docs/dev_guidelines.mdto focus on workflow (code structure, code generation, cherry-picks, common tasks) and referenceprinciples.mdfor design guidance. Moves the code generation section from principles into dev_guidelines where it fits better.Adds a
.claude/CLAUDE.mdwith project-specific context for AI-assisted development.