docs: Document agent self-registration#778
Open
jannfis wants to merge 5 commits into
Open
Conversation
Signed-off-by: jannfis <jann@mistrust.net> Assisted-by: Cursor
Contributor
📝 WalkthroughWalkthroughAdds experimental Agent self‑registration documentation: a new user guide, principal configuration entries, mkdocs navigation, and detailed argocd-agentctl JWT key CLI docs. All changes are documentation-only; no code or API surface modifications. Changes
Sequence Diagram(s)sequenceDiagram
participant Agent
participant Principal
participant ArgoCD_API as ArgoCD API
participant K8s as Kubernetes Secret Store
Agent->>Principal: Connect using shared client TLS cert + auth request
Principal->>Principal: Validate auth + check self-registration enabled
alt No manual cluster secret exists
Principal->>ArgoCD_API: Request create cluster secret for Agent
ArgoCD_API->>K8s: Persist cluster secret (labels/annotations)
ArgoCD_API-->>Principal: Acknowledge secret creation
else Manual cluster secret present
Principal-->>ArgoCD_API: Skip creation (use manual secret)
end
Principal-->>Agent: Return tokens (JWT) and client details
Note right of Agent: Token refresh occurs automatically when JWT keys rotate
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Signed-off-by: jannfis <jann@mistrust.net>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/configuration/reference/principal.md (1)
337-337: Consider adding a brief security note.Since self-registration allows agents to automatically create cluster secrets, it might be helpful to add a brief note about security implications (e.g., that this delegates trust to any agent with valid credentials, and operators should ensure proper certificate issuance controls). This could be here or in the referenced user guide.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/configuration/reference/principal.md` at line 337, Add a short security note to the experimental self-registration description that warns operators about the trust delegation and recommends controls: mention that enabling self-registration (requires --enable-resource-proxy and --self-registration-client-cert-secret) allows any agent with valid credentials to create cluster secrets, advise restricting certificate issuance, auditing registrations, and limiting scope/TTL of created secrets; place this note inline after the existing sentence or add a brief "Security" subsection and mirror a similar note in the referenced self-registration user guide.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/user-guide/adding-agents.md`:
- Around line 5-8: The repository references
docs/user-guide/self-registration.md but the file is missing; either add a new
docs/user-guide/self-registration.md with the intended content (matching the
cross-reference text used in adding-agents.md) or remove/update both references:
the inline link "./self-registration.md" in docs/user-guide/adding-agents.md and
the navigation entry "user-guide/self-registration.md" in mkdocs.yml so they no
longer point to a non-existent page; ensure the chosen fix keeps the wording
consistent with the tip label "Agent self-registration (Experimental)" in
adding-agents.md.
---
Nitpick comments:
In `@docs/configuration/reference/principal.md`:
- Line 337: Add a short security note to the experimental self-registration
description that warns operators about the trust delegation and recommends
controls: mention that enabling self-registration (requires
--enable-resource-proxy and --self-registration-client-cert-secret) allows any
agent with valid credentials to create cluster secrets, advise restricting
certificate issuance, auditing registrations, and limiting scope/TTL of created
secrets; place this note inline after the existing sentence or add a brief
"Security" subsection and mirror a similar note in the referenced
self-registration user guide.
Signed-off-by: jannfis <jann@mistrust.net>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/user-guide/self-registration.md`:
- Around line 151-154: Update the fenced code blocks in
docs/user-guide/self-registration.md so they declare a language: change the log
block containing "INFO Creating self-registered cluster secret for agent
agent=my-agent" / "INFO Successfully created self-registered cluster secret..."
to use a log/text fence (e.g., ```text or ```log) and change the label snippet
that contains argocd-agent.argoproj-labs.io/self-registered-cluster: "true" to
use a yaml fence (```yaml); locate the blocks by the shown log lines and the
label line and replace the opening ``` with the appropriate language-tagged
fence.
- Around line 96-100: Update the paragraph referencing the argocd-agentctl
command to explicitly note that argocd-agentctl pki issue agent requires both
--agent-context and --principal-context to be set (and that you must add
--same-context when the agent and principal are the same), or add a link to the
CLI docs showing these flags; mention the exact flags (--agent-context,
--principal-context, --same-context) and where to add them so users don’t omit
them when running argocd-agentctl pki issue agent.
- Around line 40-42: The docs mention "header-based" auth but lack a prominent
hardening warning; add a clearly marked warning block under "Security
Considerations" titled something like "Warning: Header-based authentication
hardening" that states the principal must never be externally reachable,
explains risks of header injection, and prescribes protecting the principal via
localhost-only binds or service-mesh (sidecar) policies; include explicit
guidance for localhost/service-mesh protection and Istio-specific caveats, and
add a link to the detailed principal authentication guidance page (the principal
auth guidance referenced in the repo) so readers can follow mitigation
steps—also replicate the same warning near the other mention of header-based
auth later in the document where header-based is discussed.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/operations/jwt-signing-keys.mddocs/user-guide/self-registration.md
✅ Files skipped from review due to trivial changes (1)
- docs/operations/jwt-signing-keys.md
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #778 +/- ##
==========================================
+ Coverage 47.48% 47.51% +0.02%
==========================================
Files 104 104
Lines 13344 13344
==========================================
+ Hits 6336 6340 +4
+ Misses 6404 6399 -5
- Partials 604 605 +1 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
mikeshng
reviewed
Mar 3, 2026
mikeshng
left a comment
mikeshng
left a comment
Collaborator
There was a problem hiding this comment.
This is a good doc. I was able to follow it and get it working. Some nits below:
| !!! important | ||
| The client certificate must be trusted by the resource proxy's CA. If you are | ||
| using the argocd-agent PKI, you can issue a client certificate with | ||
| `argocd-agentctl pki issue agent` and use its `tls.crt` and `tls.key` along |
Collaborator
There was a problem hiding this comment.
Do we need to reiterate this pki subcommand is not meant for production use here? No strong opinion either way.
|
|
||
| ```bash | ||
| ARGOCD_PRINCIPAL_ENABLE_SELF_CLUSTER_REGISTRATION=true | ||
| ARGOCD_PRINCIPAL_SELF_REGISTRATION_CLIENT_CERT_SECRET=argocd-agent-shared-client-cert |
Collaborator
There was a problem hiding this comment.
I guess this is meant for local dev env testing?
To do it for deployment we need to modify the principal configmap and/or deployment but I don't see available options in https://github.com/argoproj-labs/argocd-agent/tree/main/install/kubernetes/principal configured to be false etc.
Collaborator
Author
There was a problem hiding this comment.
Good catch, I think this was missed in the original PR. We need to fix that.
Co-authored-by: Mike Ng <ming@redhat.com> Signed-off-by: Jann Fischer <jann@mistrust.net>
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/user-guide/self-registration.md (1)
151-154:⚠️ Potential issue | 🟡 MinorAdd language identifiers to fenced code blocks (markdownlint MD040).
Line 151 and Line 177 use unlabeled fences; this will keep markdownlint warnings active.
Suggested doc diff
-``` +```text INFO Creating self-registered cluster secret for agent agent=my-agent INFO Successfully created self-registered cluster secret with shared client cert and bearer token-
+yaml
argocd-agent.argoproj-labs.io/self-registered-cluster: "true"Also applies to: 177-179
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/user-guide/self-registration.md` around lines 151 - 154, The two unlabeled fenced code blocks containing the log lines starting with "INFO Creating self-registered cluster secret for agent agent=my-agent" / "INFO Successfully created self-registered cluster secret ..." and the YAML block with "argocd-agent.argoproj-labs.io/self-registered-cluster: \"true\"" should be updated to include language identifiers; change the log block fences to ```text and the YAML block fences to ```yaml so markdownlint MD040 warnings are resolved and syntax highlighting is applied.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@docs/user-guide/self-registration.md`:
- Around line 151-154: The two unlabeled fenced code blocks containing the log
lines starting with "INFO Creating self-registered cluster secret for agent
agent=my-agent" / "INFO Successfully created self-registered cluster secret ..."
and the YAML block with "argocd-agent.argoproj-labs.io/self-registered-cluster:
\"true\"" should be updated to include language identifiers; change the log
block fences to ```text and the YAML block fences to ```yaml so markdownlint
MD040 warnings are resolved and syntax highlighting is applied.
Signed-off-by: Jann Fischer <jann@mistrust.net>
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/user-guide/self-registration.md (1)
149-152:⚠️ Potential issue | 🟡 MinorAdd explicit fence languages for Markdown lint compliance.
Line 149 and Line 175 still use unlabeled fenced blocks, which triggers MD040. Please annotate them (
textfor logs,yamlfor the label snippet).Suggested doc patch
-``` +```text INFO Creating self-registered cluster secret for agent agent=my-agent INFO Successfully created self-registered cluster secret with shared client cert and bearer token-
+yaml
argocd-agent.argoproj-labs.io/self-registered-cluster: "true"Also applies to: 175-177
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/user-guide/self-registration.md` around lines 149 - 152, The Markdown has unlabeled fenced code blocks; replace the fence before the log block that starts with "INFO Creating self-registered cluster secret for agent agent=my-agent" with a text-fenced block (use ```text) and replace the fence before the label snippet that contains 'argocd-agent.argoproj-labs.io/self-registered-cluster: "true"' with a yaml-fenced block (use ```yaml) — update both occurrences (the log example and the label snippet) so the fenced blocks include the appropriate language labels for MD040 compliance.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@docs/user-guide/self-registration.md`:
- Around line 149-152: The Markdown has unlabeled fenced code blocks; replace
the fence before the log block that starts with "INFO Creating self-registered
cluster secret for agent agent=my-agent" with a text-fenced block (use ```text)
and replace the fence before the label snippet that contains
'argocd-agent.argoproj-labs.io/self-registered-cluster: "true"' with a
yaml-fenced block (use ```yaml) — update both occurrences (the log example and
the label snippet) so the fenced blocks include the appropriate language labels
for MD040 compliance.
Collaborator
|
It's a detailed doc and covers everything about self agent registration feature. |
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
4 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.
Assisted-by: Cursor
What does this PR do / why we need it:
Document changes introduced by #736
Which issue(s) this PR fixes:
Fixes #?
How to test changes / Special notes to the reviewer:
Checklist
Summary by CodeRabbit