docs: Add docs for cert-manager PKI (#620)

Signed-off-by: Gerald Nunn <[email protected]>

Author: gnunn1

docs/configuration/agent/pki-certificates.md

@@ -20,28 +20,28 @@ The agent component uses certificates for two primary purposes:
 graph TB
     Principal[Principal<br/>argocd-agent-principal-tls]
     CA[Certificate Authority<br/>argocd-agent-ca]
-    
+
     Agent1[Agent 1<br/>Workload Cluster 1]
     Agent2[Agent 2<br/>Workload Cluster 2]
-    
+
     CA --> Agent1CA[CA Certificate<br/>argocd-agent-ca]
     CA --> Agent2CA[CA Certificate<br/>argocd-agent-ca]
-    
+
     CA --> Agent1Cert[Client Certificate<br/>argocd-agent-client-tls]
     CA --> Agent2Cert[Client Certificate<br/>argocd-agent-client-tls]
-    
+
     Agent1CA --> Agent1
     Agent1Cert --> Agent1
     Agent2CA --> Agent2
     Agent2Cert --> Agent2
-    
+
     Agent1 -.->|TLS Connection| Principal
     Agent2 -.->|TLS Connection| Principal
-    
+
     classDef agent fill:#e1f5fe
     classDef cert fill:#f3e5f5
     classDef ca fill:#e8f5e8
-    
+
     class Agent1,Agent2 agent
     class Agent1Cert,Agent2Cert cert
     class CA,Agent1CA,Agent2CA ca
@@ -153,6 +153,148 @@ argocd-agent-ca                           Opaque            1      5m
 argocd-agent-client-tls                   kubernetes.io/tls 2      4m
 ```
 
+## Using cert-manager
+
+The cert-manager operator can be used to manage PKI certificates, this section assumes the steps
+for the Principal PKI using cert-manager have been completed.
+
+To register Agents, Agent specific certificates for both the Principal and Agent need to be minted for
+use with [Mutual TLS](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/)
+
+### Step 1: Register the Agent on the Principal
+
+To register the Agent on the Principal a certificate must be minted for the Principal to provide
+to the Agent as part of mTLS. Note the `dnsNames` used is not important
+but a consistent method should be used, for example `<cluster-name>.<CA-ROOT-DOMAIN>`
+
+Replace the `<cluster-name>` and `<Organizational Unit>` tokens to match your requirements:
+
+```
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: <cluster-name>-principal
+  namespace: argocd
+spec:
+  secretName: <cluster-name>
+  issuerRef:
+    name: argocd-agent-ca
+    kind: Issuer
+  commonName: managed-cluster
+  subject:
+    organizationalUnits:
+      - <Organizational Unit>
+  dnsNames:
+  - <cluster-name>.<CA-ROOT-DOMAIN>
+```
+
+Create the cluster secret, note that you cannot directly use the previously created certificate
+but need to transpose it into the cluster secret.
+
+Extract the fields we need into environment variables:
+
+```
+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}')
+```
+
+To create the `<cluster-name>-cluster` secret that is needed we must first create the `config` block
+with the certs:
+
+```
+cat << EOF > config
+{
+    "username": "foo",
+    "password": "bar",
+    "tlsClientConfig": {
+        "insecure": false,
+        "certData": "${PRINCIPAL_AGENT_TLS}",
+        "keyData": "${PRINCIPAL_AGENT_KEY}",
+        "caData": "${PRINCIPAL_AGENT_CA}"
+    }
+}
+EOF
+```
+
+Now create the secret:
+
+```
+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:
+
+```
+oc label secret <cluster-name>-cluster argocd.argoproj.io/secret-type=cluster
+```
+
+### Step 2: Mint Certificate for Agent
+
+The Agent requires it's own certificate which will be provided to the Principal for mTLS, this will
+be minted on the Principal where the Issuer is available and then moved to the Agent.
+
+!!!note
+  It is possible to mint this certificate on the Agent itself by simply using cert-manager
+  with the identical CA secret on the Agent. However this has security implications since
+  if any cluster is compromised the CA with its key could be retrieved and a hacker could mint their own certs. Generally
+  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.
+
+```
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: <cluster-name>-agent
+  namespace: argocd
+spec:
+  secretName: <cluster-name>-agent
+  issuerRef:
+    name: argocd-agent-ca
+    kind: Issuer
+  commonName: managed-cluster
+  subject:
+    organizationalUnits:
+      - <Organizational Unit>
+  dnsNames:
+  - <cluster-name>.<CA-ROOT-DOMAIN>
+```
+
+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
+```
+
+!!!note
+  The [kubectl-neat](https://github.com/itaysk/kubectl-neat) plugin is used to clean the YAML, if you do not have access to this simply omit it
+  and edit the secret after it is exported to remove the cruft:
+
+The secret `argocd-agent-ca` is also required for the Agent however want it without the key for
+the security reasons discussed earlier.
+
+!!!note
+  The command `yq` is used to modify the secret, if `yq` is not available simply edit the secret as needed.
+
+```
+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
+```
+
+On the Agent cluster apply the two secrets:
+
+```
+kubectl apply -f ./argocd-agent-ca.yaml
+kubectl apply -f <cluster-name>-agent.yaml
+```
+
 ## Manual Certificate Management
 
 For production environments or when integrating with existing PKI infrastructure, you can manually create and manage the required certificates and secrets.
@@ -346,10 +488,10 @@ data:
   agent.tls.secret-name: "argocd-agent-client-tls"
   agent.tls.client.cert-path: ""
   agent.tls.client.key-path: ""
-  
+
   # Authentication
   agent.creds: "userpass:/app/config/creds/userpass.creds"
-  
+
   # Connection
   agent.server.address: "<principal-address>"
   agent.server.port: "8443"
@@ -672,4 +814,4 @@ spec:
 ## Related Documentation
 
 - [Principal PKI Configuration](../principal/pki-certificates.md) - PKI setup for the principal component
-- [Adding New Agents](../../user-guide/adding-agents.md) - Complete agent setup guide
+- [Adding New Agents](../../user-guide/adding-agents.md) - Complete agent setup guide

docs/configuration/principal/pki-certificates.md

@@ -21,13 +21,13 @@ graph TB
     CA --> PrincipalCert[Principal gRPC Server<br/>argocd-agent-principal-tls]
     CA --> ProxyCert[Resource Proxy Server<br/>argocd-agent-resource-proxy-tls]
     CA --> AgentCert[Agent Client Certificates<br/>argocd-agent-client-tls]
-    
+
     JWT[JWT Signing Key<br/>argocd-agent-jwt]
-    
+
     PrincipalCert --> Agent1[Agent 1]
     PrincipalCert --> Agent2[Agent 2]
     ProxyCert --> ArgoCD[Argo CD Server]
-    
+
     AgentCert --> Agent1
     JWT --> Agent1
     JWT --> Agent2
@@ -146,6 +146,106 @@ argocd-agent-resource-proxy-tls           kubernetes.io/tls     2      3m
 argocd-agent-jwt                          Opaque                1      2m
 ```
 
+## Using cert-manager
+
+The [cert-manager](https://cert-manager.io/docs/) operator can be used to manage the Argo CD Agent PKI requirements
+with a [Certificate Authority (CA) issuer](https://cert-manager.io/docs/configuration/ca/). This is where a custom CA is used to issue
+certificates on demand.
+
+### Step 1: Initialize the PKI
+
+Create private key with openssl
+
+```
+openssl genrsa -out ca.key 4096
+```
+
+Create root certificate using the generated key:
+
+```
+openssl req -new -x509 -sha256 -days 3650 -key ca.key -out ca.crt
+```
+
+Create a CA secret in Kubernetes:
+
+```
+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:
+
+```
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: argocd-agent-ca
+  namespace: argocd
+spec:
+  ca:
+    secretName: argocd-agent-ca
+```
+
+### Step 2: Issue Principal gRPC Server Certificate
+
+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:
+
+```
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: argocd-agent-principal-tls
+  namespace: argocd
+spec:
+  secretName: argocd-agent-principal-tls
+  issuerRef:
+    name: argocd-agent-ca
+    kind: Issuer
+  commonName: principal
+  subject:
+    organizationalUnits:
+      - <Organizational Unit>
+  dnsNames:
+  - <dns-name>
+```
+
+### Step 3: Issue Resource Proxy Certificate
+
+Next generate the certificate for the resource proxy, note the `dnsNames` may not
+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:
+
+```
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: argocd-agent-resource-proxy-tls
+  namespace: argocd
+spec:
+  secretName: argocd-agent-resource-proxy-tls
+  issuerRef:
+    name: argocd-agent-ca
+    kind: Issuer
+  commonName: resource-proxy
+  subject:
+    organizationalUnits:
+      - <Organizational Unit>
+  dnsNames:
+  - argocd-agent-resource-proxy.argocd.svc.cluster.local
+```
+
+### Step 4: Validate the certificates
+
+Confirm that the certificates have been deployed and are ready, `READY` should be `True` for both certs as
+per this example:
+
+```
+$ kubectl get certificate -n argocd
+NAME                              READY   SECRET                            AGE
+argocd-agent-principal-tls        True    argocd-agent-principal-tls        4m8s
+argocd-agent-resource-proxy-tls   True    argocd-agent-resource-proxy-tls   64s
+```
+
 ## Manual Certificate Management
 
 For production environments or when integrating with existing PKI infrastructure, you can manually create and manage the required certificates and secrets.
@@ -473,7 +573,7 @@ Rotate certificates by re-issuing them with the `--upsert` flag:
 # Rotate principal certificate
 argocd-agentctl pki issue principal --upsert
 
-# Rotate resource proxy certificate  
+# Rotate resource proxy certificate
 argocd-agentctl pki issue resource-proxy --upsert
 
 # Rotate JWT signing key
@@ -500,4 +600,4 @@ kubectl rollout restart deployment argocd-agent-principal -n argocd
 
 ## Related Documentation
 
-- [Adding New Agents](../../user-guide/adding-agents.md) - How to create and configure agents
+- [Adding New Agents](../../user-guide/adding-agents.md) - How to create and configure agents