Skip to content

fix: Minor corrections to the cert-manager certificate being used for the Agent in docs #673

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gnunn1 wants to merge 7 commits into
base: main
Choose a base branch
from
Open

fix: Minor corrections to the cert-manager certificate being used for the Agent in docs #673

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
6ffe63a
Suffix secret with -principal and don't hardcode the common-name to m…
gnunn1 Dec 3, 2025
5122431
Remove hard-coding of managed-cluster for <cluster-name>
gnunn1 Dec 3, 2025
7211209
Update to include unique query parameter for server URL
gnunn1 Dec 5, 2025
9d8c131
Include the label required by the agent, remove hard coded references…
gnunn1 Dec 5, 2025
a16c68e
Minor update for consistency
gnunn1 Dec 8, 2025
f506658
Fix issues identified by linting
gnunn1 Dec 8, 2025
b0cc22c
Add bash and yaml identifiers to code blocks
gnunn1 Dec 8, 2025
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
47 changes: 25 additions & 22 deletions docs/configuration/agent/pki-certificates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,18 +175,18 @@ but a consistent method should be used, for example `<cluster-name>.<CA-ROOT-DOM

Replace the `<cluster-name>` and `<Organizational Unit>` tokens to match your requirements:

```
```yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: <cluster-name>-principal
namespace: argocd
spec:
secretName: <cluster-name>
secretName: <cluster-name>-principal
issuerRef:
name: argocd-agent-ca
kind: Issuer
commonName: managed-cluster
commonName: <cluster-name>
subject:
organizationalUnits:
- <Organizational Unit>
Expand All @@ -199,7 +199,7 @@ but need to transpose it into the cluster secret.

Extract the fields we need into environment variables:

```
```bash
export PRINCIPAL_AGENT_CA=$(kubectl get secret <cluster-name>-principal -o jsonpath='{.data.ca\.crt}')
export PRINCIPAL_AGENT_TLS=$(kubectl get secret <cluster-name>-principal -o jsonpath='{.data.tls\.crt}')
export PRINCIPAL_AGENT_KEY=$(kubectl get secret <cluster-name>-principal -o jsonpath='{.data.tls\.key}')
Expand All @@ -208,11 +208,9 @@ export PRINCIPAL_AGENT_KEY=$(kubectl get secret <cluster-name>-principal -o json
To create the `<cluster-name>-cluster` secret that is needed we must first create the `config` block
with the certs:

```
```bash
cat << EOF > config
{
"username": "foo",
"password": "bar",
"tlsClientConfig": {
"insecure": false,
"certData": "${PRINCIPAL_AGENT_TLS}",
Expand All @@ -225,14 +223,19 @@ EOF

Now create the secret:

```bash
kubectl create secret generic <cluster-name>-cluster -n argocd --from-literal=name=<cluster-name> --from-literal=server=https://argocd-agent-resource-proxy:9090?agentName=<cluster-name> --from-file=config=./config
```
kubectl create secret generic <cluster-name>-cluster -n argocd --from-literal=name=<cluster-name> --from-literal=server=argocd-agent-resource-proxy.argocd.svc.cluster.local --from-file=config=./config
```

Then label the secret as a cluster secret:
!!! note "Add unique query parameter to server"
Argo CD caches cluster information based on the server URL in the cluster secret. This URL
must be unique otherwise cache collisions can arise. Since all Agents share the same
resource proxy it is recommended to add a unique query parameter identifying the agent
as shown in this example.

```
oc label secret <cluster-name>-cluster argocd.argoproj.io/secret-type=cluster
Then label the secret as a cluster secret and include the label to identify the matching agent:
```bash
kubectl label secret <cluster-name>-cluster argocd.argoproj.io/secret-type=cluster
kubectl label secret <cluster-name>-cluster argocd-agent.argoproj-labs.io/agent-name=<cluster-name>
```

### Step 2: Mint Certificate for Agent
Expand All @@ -247,7 +250,7 @@ be minted on the Principal where the Issuer is available and then moved to the A
the Agents will at times run in less secure locations/networks then the Principle so isolating
the CA to one location, the principal, is beneficial.

```
```yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
Expand All @@ -258,7 +261,7 @@ spec:
issuerRef:
name: argocd-agent-ca
kind: Issuer
commonName: managed-cluster
commonName: <cluster-name>
subject:
organizationalUnits:
- <Organizational Unit>
Expand All @@ -268,8 +271,8 @@ spec:

Output the secret to a file as we need to install it on the cluster where the Agent resides:

```
kubectl get secret managed-cluster-agent -o yaml -n argocd | oc neat > <cluster-name>-agent.yaml
```bash
kubectl get secret <cluster-name>-agent -o yaml -n argocd | kubectl neat > <cluster-name>-agent.yaml
```

!!! note "Using kubectl-neat"
Expand All @@ -282,21 +285,21 @@ the security reasons discussed earlier.
!!! note "Using yq"
The command `yq` is used to modify the secret, if `yq` is not available simply edit the secret as needed.

```
```bash
kubectl get secret argocd-agent-ca -o yaml -n argocd | yq 'del(.data.["tls.key"])' -y | oc neat > argocd-agent-ca.yaml
```

Change the secret type to `Opaque` since a Kubernetes TLS secret requires a key, additionally change the name of the exported secret from `<cluster-name>-agent` to
to `argocd-agent-client-tls`.

```
yq -i '.type = "Opaque"' ./argocd-agent-ca.yaml -y
yq -i '.metadata.name = "argocd-agent-client-tls"' <path-to-secret>/managed-cluster-agent.yaml -y
```bash
yq -i '.type = "Opaque"' argocd-agent-ca.yaml -y
yq -i '.metadata.name = "argocd-agent-client-tls"' <path-to-secret>/<cluster-name>-agent.yaml -y
Copy link

@coderabbitai coderabbitai bot Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Minor: Path placeholder inconsistency.

Line 298 uses <path-to-secret>/ as a placeholder for the directory path, but this is inconsistent with line 276, which shows the file is output to the current directory with ./. For clarity and consistency, this should either specify the full path or reference the current directory convention used above.

Apply this diff to improve clarity:

-yq -i '.metadata.name = "argocd-agent-client-tls"' <path-to-secret>/<cluster-name>-agent.yaml -y
+yq -i '.metadata.name = "argocd-agent-client-tls"' ./<cluster-name>-agent.yaml -y
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
yq -i '.metadata.name = "argocd-agent-client-tls"' <path-to-secret>/<cluster-name>-agent.yaml -y
yq -i '.metadata.name = "argocd-agent-client-tls"' ./<cluster-name>-agent.yaml -y
🤖 Prompt for AI Agents 
docs/configuration/agent/pki-certificates.md around line 298: the yq example
uses the placeholder "<path-to-secret>/" which is inconsistent with the earlier
examples that write files to the current directory using "./"; update the
placeholder to "./" (or otherwise match the convention used at line 276) so the
command reads consistently and clearly indicating the file in the current
directory.

```

On the Agent cluster apply the two secrets:

```
```bash
kubectl apply -f ./argocd-agent-ca.yaml
kubectl apply -f <cluster-name>-agent.yaml
```
Expand Down
14 changes: 7 additions & 7 deletions docs/configuration/principal/pki-certificates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,25 +156,25 @@ certificates on demand.

Create private key with openssl

```
```bash
openssl genrsa -out ca.key 4096
```

Create root certificate using the generated key:

```
```bash
openssl req -new -x509 -sha256 -days 3650 -key ca.key -out ca.crt
```

Create a CA secret in Kubernetes:

```
```bash
kubectl create secret tls argocd-agent-ca --cert=ca.crt --key=ca.key -n argocd
```

Create cert-manager issuer for the CA we generated previously:

```
```yaml
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
Expand All @@ -190,7 +190,7 @@ spec:
Generate the server certificate for the principal's gRPC service, `argocd-agent-principal-tls`, using cert-manager Certificate.
Make sure you update the `organizationalUnits` and `dnsNames` to reflect the values for your installation:

```
```yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
Expand All @@ -215,7 +215,7 @@ Next generate the certificate for the resource proxy, note the `dnsNames` may no
need to be changed here since it is an internal service unless you are using a different
namespace then `argocd`. However update your `organizationalUnits` as desired:

```
```yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
Expand All @@ -239,7 +239,7 @@ spec:
Confirm that the certificates have been deployed and are ready, `READY` should be `True` for both certs as
per this example:

```
```bash
$ kubectl get certificate -n argocd
NAME READY SECRET AGE
argocd-agent-principal-tls True argocd-agent-principal-tls 4m8s
Expand Down
Loading