docs: Add notice of deprecation for userpass auth (#626)

Signed-off-by: jannfis <[email protected]>

Author: jannfis

docs/configuration/agent/configuration.md

@@ -67,9 +67,9 @@ The recommended approach for production deployments is to use ConfigMap entries
 - **Default**: `""` (empty)
 - **Format**: `<method>:<configuration>`
 - **Valid Methods**:
-  - `userpass:/path/to/creds/file` - Username/password authentication
-  - `mtls:regex_pattern` - Mutual TLS authentication with agent ID extraction
-- **Example**: `"userpass:/app/config/creds/userpass.creds"`
+  - `userpass:/path/to/creds/file` - Username/password authentication **[DEPRECATED - not suited for use outside development environments]**
+  - `mtls:regex_pattern` - Mutual TLS authentication with agent ID extraction **(Recommended)**
+- **Example**: `"mtls:^CN=(.+)$"`
 
 ### TLS Configuration
 
@@ -314,7 +314,7 @@ data:
   agent.mode: "autonomous"
   agent.namespace: "argocd"
   agent.log.level: "info"
-  agent.creds: "userpass:/app/config/creds/userpass.creds"
+  agent.creds: "mtls:^CN=(.+)$"  # Use mTLS (recommended); userpass is deprecated
   agent.tls.client.insecure: "false"
   agent.tls.root-ca-secret-name: "argocd-agent-ca"
   agent.tls.secret-name: "argocd-agent-client-tls"

docs/configuration/agent/pki-certificates.md

@@ -10,10 +10,13 @@ The agent component uses certificates for two primary purposes:
 |----------------|---------|-------------|----------|
 | **CA Certificate** | Validates the principal's server certificate | `argocd-agent-ca` | ✅ |
 | **Client Certificate** | Authenticates the agent to the principal (mTLS) | `argocd-agent-client-tls` | ✅¹ |
-| **Authentication Credentials** | User/password authentication (alternative to mTLS) | `argocd-agent-agent-userpass` | ✅¹ |
+| **Authentication Credentials** | User/password authentication (alternative to mTLS) **[DEPRECATED]** | `argocd-agent-agent-userpass` | ✅¹ |
 
 ¹ Either client certificate (mTLS) or authentication credentials (userpass) is required, depending on the authentication method configured.
 
+!!! warning "Deprecation Notice"
+    The userpass authentication method is deprecated and not suited for use outside development environments. Use mTLS authentication for production deployments.
+
 ## Architecture Overview
 
 ```mermaid
@@ -51,13 +54,16 @@ graph TB
 
 The agent supports two authentication methods:
 
-### 1. UserPass Authentication (Default)
+### 1. UserPass Authentication (Default) [DEPRECATED]
+
+!!! warning "Deprecation Notice"
+    This authentication method is deprecated and not suited for use outside development environments. Use mTLS authentication for production deployments.
 
 - **Agent** presents username/password credentials
 - **Simpler setup** but requires credential management
 - **Client certificate** still needed for TLS encryption (optional validation)
 
-### 2. mTLS Authentication
+### 2. mTLS Authentication (Recommended)
 
 - **Agent** presents a client certificate for authentication
 - **More secure** as no passwords are transmitted
@@ -384,7 +390,10 @@ kubectl create secret tls argocd-agent-client-tls \
   --context <workload-cluster-context>
 ```
 
-#### Step 4: Create Authentication Credentials (UserPass Method)
+#### Step 4: Create Authentication Credentials (UserPass Method) [DEPRECATED]
+
+!!! warning "Deprecation Notice"
+    The userpass authentication method is deprecated and not suited for use outside development environments. Use mTLS authentication for production deployments.
 
 If using userpass authentication, create the credentials secret:
 
@@ -428,7 +437,10 @@ data:
   tls.key: <base64-encoded-client-private-key>
 ```
 
-#### Authentication Credentials Secret (`argocd-agent-agent-userpass`)
+#### Authentication Credentials Secret (`argocd-agent-agent-userpass`) [DEPRECATED]
+
+!!! warning "Deprecation Notice"
+    The userpass authentication method is deprecated and not suited for use outside development environments.
 
 ```yaml
 apiVersion: v1
@@ -499,7 +511,10 @@ data:
 
 ## Authentication Methods Configuration
 
-### UserPass Authentication
+### UserPass Authentication [DEPRECATED]
+
+!!! warning "Deprecation Notice"
+    The userpass authentication method is deprecated and not suited for use outside development environments. Use mTLS authentication for production deployments.
 
 Configure the agent to use username/password authentication:
 
@@ -562,13 +577,16 @@ argocd-agent agent \
 
 ### Authentication Security
 
-**UserPass Authentication:**
+**UserPass Authentication [DEPRECATED]:**
+
+!!! warning "Deprecation Notice"
+    The userpass authentication method is deprecated and not suited for use outside development environments.
 
 - Use strong, unique passwords for each agent
 - Rotate passwords regularly
 - Store passwords in encrypted secrets
 
-**mTLS Authentication:**
+**mTLS Authentication (Recommended):**
 
 - Use separate certificates for each agent
 - Implement certificate-based access control

docs/configuration/principal/configuration.md

@@ -256,8 +256,8 @@ The recommended approach for production deployments is to use ConfigMap entries
 - **Default**: `""` (empty)
 - **Format**: `<method>:<configuration>`
 - **Valid Methods**:
-  - `userpass:/path/to/creds/file` - Username/password authentication
-  - `mtls:regex_pattern` - Mutual TLS authentication with agent ID extraction
+  - `userpass:/path/to/creds/file` - Username/password authentication **[DEPRECATED - not suited for use outside development environments]**
+  - `mtls:regex_pattern` - Mutual TLS authentication with agent ID extraction **(Recommended)**
 - **Example**: `"mtls:CN=([^,]+)"`
 
 ### Logging and Debugging

docs/hack/quickstart.md

@@ -2,6 +2,9 @@
 
 This is **not** a guide to set-up argocd-agent for a production environment. It is rather a guide to help you get going with contributing to and hacking on argocd-agent. This guide does not intend to provide pure copy & paste instructions. Instead, it will assume a little bit of willingness to hackery on your side, as well as some core knowledge about the underlying technologies (JWT, TLS, etc)
 
+!!! warning "Important - Deprecation Notice"
+    This guide uses the userpass authentication method for simplicity in development environments. **The userpass authentication method is deprecated and not suited for use outside development environments.** For production deployments, use mTLS authentication instead.
+
 Please note that some resource names might be out-of-date (e.g. have changed names, or were removed and replaced by something else). If you notice something, please figure it out and submit a PR to this guide. Thanks!
 
 If you want to use [Open Cluster Management (OCM)](https://open-cluster-management.io/)
@@ -106,7 +109,7 @@ Keep the `ca.crt` file, as you will need it for the installation of agents, too.
 Create the principal user password secret; replace `<PASSWORD>` with the password of your choice:
 
 ```shell
-kubectl create -n argocd secret generic argocd-agent-principal-userpass --from-literal=passwd='<PASSWORD>'
+kubectl create -n argocd secret generic argocd-agent-principal-userpass --from-literal=passwd='<PASSWORD>'  # DEPRECATED: userpass auth not suited for production
 ```
 
 Now that the required secrets exist, it's time to apply the installation manifests and install the principal into the cluster:
@@ -149,7 +152,7 @@ we will use the `argocd` namespace to install all required resources into the cl
 Create the agent user password secret; replace `<CREDENTIALS>` with the credentials of your choice:
 
 ```shell
-kubectl create -n argocd secret generic argocd-agent-agent-userpass --from-literal=credentials='<CREDENTIALS>'
+kubectl create -n argocd secret generic argocd-agent-agent-userpass --from-literal=credentials='<CREDENTIALS>'  # DEPRECATED: userpass auth not suited for production
 ```
 
 Now that the required secrets exist, it's time to apply the installation manifests and install the agent into the cluster:

docs/user-guide/adding-agents.md

@@ -125,7 +125,10 @@ kubectl create namespace <agent-name> --context <control-plane-context>
 
 ### Option A: Using Kubernetes Manifests
 
-1. **Create Authentication Secret**:
+1. **Create Authentication Secret** (for userpass - deprecated):
+
+!!! warning "Deprecation Notice"
+    The userpass authentication method is deprecated and not suited for use outside development environments. Use mTLS authentication for production deployments.
 
 ```bash
 kubectl create secret generic argocd-agent-agent-userpass \
@@ -196,12 +199,15 @@ data:
 
 ### Authentication Methods
 
-**mTLS Authentication**:
+**mTLS Authentication (Recommended)**:
 ```yaml
 agent.creds: "mtls:^CN=(.+)$"  # Regex to extract agent ID from cert subject
 ```
 
-**UserPass Authentication** (deprecated):
+**UserPass Authentication [DEPRECATED]**:
+
+!!! warning "Deprecation Notice"
+    The userpass authentication method is deprecated and not suited for use outside development environments.
 
 ```yaml
 agent.creds: "userpass:/app/config/creds/userpass.creds"