github.com/argoproj/argo-cd/v3@v3.2.1/docs/operator-manual/tls.md (about) 1 # TLS configuration 2 3 Argo CD provides three inbound TLS endpoints that can be configured: 4 5 * The user-facing endpoint of the `argocd-server` workload, which serves the UI 6 and the API 7 * The endpoint of the `argocd-repo-server`, which is accessed by `argocd-server` 8 and `argocd-application-controller` workloads to request repository 9 operations. 10 * The endpoint of the `argocd-dex-server`, which is accessed by `argocd-server` 11 to handle OIDC authentication. 12 13 By default, and without further configuration, these endpoints will be 14 set up to use an automatically generated, self-signed certificate. However, 15 most users will want to explicitly configure the certificates for these TLS 16 endpoints, possibly using automated means such as `cert-manager` or using 17 their own dedicated Certificate Authority. 18 19 ## TLS Configuration Quick Reference 20 21 ### Certificate Configuration Overview 22 23 | Component | Secret Name | Hot Reload | Default Cert | Required SAN Entries | 24 |-----------|-------------|------------|---------------|---------------------| 25 | `argocd-server` | `argocd-server-tls` | ✅ Yes | Self-signed | External hostname (e.g., `argocd.example.com`) | 26 | `argocd-repo-server` | `argocd-repo-server-tls` | ❌ Restart required | Self-signed | `DNS:argocd-repo-server`, `DNS:argocd-repo-server.argocd.svc` | 27 | `argocd-dex-server` | `argocd-dex-server-tls` | ❌ Restart required | Self-signed | `DNS:argocd-dex-server`, `DNS:argocd-dex-server.argocd.svc` | 28 29 ### Inter-Component TLS 30 31 | Connection | Strict TLS Parameter | Plain Text Parameter | Default Behavior | 32 |------------|---------------------|---------------------|------------------| 33 | `argocd-server` → `argocd-repo-server` | `--repo-server-strict-tls` | `--repo-server-plaintext` | Non-validating TLS | 34 | `argocd-application-controller` → `argocd-repo-server` | `--repo-server-strict-tls` | `--repo-server-plaintext` | Non-validating TLS | 35 | `argocd-server` → `argocd-dex-server` | `--dex-server-strict-tls` | `--dex-server-plaintext` | Non-validating TLS | 36 37 ### Certificate Priority (argocd-server only) 38 39 1. `argocd-server-tls` secret (recommended) 40 2. `argocd-secret` secret (deprecated) 41 3. Auto-generated self-signed certificate 42 43 ## Configuring TLS for argocd-server 44 45 ### Inbound TLS options for argocd-server 46 47 You can configure certain TLS options for the `argocd-server` workload by 48 setting command line parameters. The following parameters are available: 49 50 |Parameter|Default|Description| 51 |---------|-------|-----------| 52 |`--insecure`|`false`|Disables TLS completely| 53 |`--tlsminversion`|`1.2`|The minimum TLS version to be offered to clients| 54 |`--tlsmaxversion`|`1.3`|The maximum TLS version to be offered to clients| 55 |`--tlsciphers`|`TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384:TLS_RSA_WITH_AES_256_GCM_SHA384`|A colon separated list of TLS cipher suites to be offered to clients| 56 57 ### TLS certificates used by argocd-server 58 59 There are two ways to configure the TLS certificates used by `argocd-server`: 60 61 * Setting the `tls.crt` and `tls.key` keys in the `argocd-server-tls` secret 62 to hold PEM data of the certificate and the corresponding private key. The 63 `argocd-server-tls` secret may be of type `tls`, but does not have to be. 64 * Setting the `tls.crt` and `tls.key` keys in the `argocd-secret` secret to 65 hold PEM data of the certificate and the corresponding private key. This 66 method is considered deprecated and only exists for purposes of backwards 67 compatibility. Changing `argocd-secret` should not be used to override the 68 TLS certificate anymore. 69 70 Argo CD decides which TLS certificate to use for the endpoint of 71 `argocd-server` as follows: 72 73 * If the `argocd-server-tls` secret exists and contains a valid key pair in the 74 `tls.crt` and `tls.key` keys, this will be used for the certificate of the 75 endpoint of `argocd-server`. 76 * Otherwise, if the `argocd-secret` secret contains a valid key pair in the 77 `tls.crt` and `tls.key` keys, this will be used as the certificate for the 78 endpoint of `argocd-server`. 79 * If no `tls.crt` and `tls.key` keys are found in neither of the two mentioned 80 secrets, Argo CD will generate a self-signed certificate and persist it in 81 the `argocd-secret` secret. 82 83 The `argocd-server-tls` secret contains only information for TLS configuration 84 to be used by `argocd-server` and is safe to be managed via third-party tools 85 such as `cert-manager` or `SealedSecrets` 86 87 To create this secret manually from an existing key pair, you can use `kubectl`: 88 89 ```shell 90 kubectl create -n argocd secret tls argocd-server-tls \ 91 --cert=/path/to/cert.pem \ 92 --key=/path/to/key.pem 93 ``` 94 95 Argo CD will pick up changes to the `argocd-server-tls` secret automatically 96 and will not require restarting to use a renewed certificate. 97 98 ## Configuring inbound TLS for argocd-repo-server 99 100 ### Inbound TLS options for argocd-repo-server 101 102 You can configure certain TLS options for the `argocd-repo-server` workload by 103 setting command line parameters. The following parameters are available: 104 105 |Parameter|Default|Description| 106 |---------|-------|-----------| 107 |`--disable-tls`|`false`|Disables TLS completely| 108 |`--tlsminversion`|`1.2`|The minimum TLS version to be offered to clients| 109 |`--tlsmaxversion`|`1.3`|The maximum TLS version to be offered to clients| 110 |`--tlsciphers`|`TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384:TLS_RSA_WITH_AES_256_GCM_SHA384`|A colon-separated list of TLS cipher suites to be offered to clients| 111 112 ### Inbound TLS certificates used by argocd-repo-server 113 114 To configure the TLS certificate used by the `argocd-repo-server` workload, 115 create a secret named `argocd-repo-server-tls` in the namespace where Argo CD 116 is running in with the certificate's key pair stored in `tls.crt` and 117 `tls.key` keys. If this secret does not exist, `argocd-repo-server` will 118 generate and use a self-signed certificate. 119 120 To create this secret, you can use `kubectl`: 121 122 ```shell 123 kubectl create -n argocd secret tls argocd-repo-server-tls \ 124 --cert=/path/to/cert.pem \ 125 --key=/path/to/key.pem 126 ``` 127 128 If the certificate is self-signed, you will also need to add `ca.crt` to the secret 129 with the contents of your CA certificate. 130 131 Please note, that as opposed to `argocd-server`, the `argocd-repo-server` is 132 not able to pick up changes to this secret automatically. If you create (or 133 update) this secret, the `argocd-repo-server` pods need to be restarted. 134 135 Also note, that the certificate should be issued with the correct SAN entries 136 for the `argocd-repo-server`, containing at least the entries for 137 `DNS:argocd-repo-server` and `DNS:argocd-repo-server.argo-cd.svc` depending 138 on how your workloads connect to the repository server. 139 140 ## Configuring inbound TLS for argocd-dex-server 141 142 ### Inbound TLS options for argocd-dex-server 143 144 You can configure certain TLS options for the `argocd-dex-server` workload by 145 setting command line parameters. The following parameters are available: 146 147 |Parameter|Default|Description| 148 |---------|-------|-----------| 149 |`--disable-tls`|`false`|Disables TLS completely| 150 151 ### Inbound TLS certificates used by argocd-dex-server 152 153 To configure the TLS certificate used by the `argocd-dex-server` workload, 154 create a secret named `argocd-dex-server-tls` in the namespace where Argo CD 155 is running in with the certificate's key pair stored in `tls.crt` and 156 `tls.key` keys. If this secret does not exist, `argocd-dex-server` will 157 generate and use a self-signed certificate. 158 159 To create this secret, you can use `kubectl`: 160 161 ```shell 162 kubectl create -n argocd secret tls argocd-dex-server-tls \ 163 --cert=/path/to/cert.pem \ 164 --key=/path/to/key.pem 165 ``` 166 167 If the certificate is self-signed, you will also need to add `ca.crt` to the secret 168 with the contents of your CA certificate. 169 170 Please note, that as opposed to `argocd-server`, the `argocd-dex-server` is 171 not able to pick up changes to this secret automatically. If you create (or 172 update) this secret, the `argocd-dex-server` pods need to be restarted. 173 174 Also note, that the certificate should be issued with the correct SAN entries 175 for the `argocd-dex-server`, containing at least the entries for 176 `DNS:argocd-dex-server` and `DNS:argocd-dex-server.argo-cd.svc` depending 177 on how your workloads connect to the repository server. 178 179 ## Configuring TLS between Argo CD components 180 181 ### Configuring TLS to argocd-repo-server 182 183 Both `argocd-server` and `argocd-application-controller` communicate with the 184 `argocd-repo-server` using a gRPC API over TLS. By default, 185 `argocd-repo-server` generates a non-persistent, self-signed certificate 186 to use for its gRPC endpoint on startup. Because the `argocd-repo-server` has 187 no means to connect to the K8s control plane API, this certificate is not available 188 to outside consumers for verification. Both, 189 `argocd-server` and `argocd-application-server` will use a non-validating 190 connection to the `argocd-repo-server` for this reason. 191 192 To change this behavior to be more secure by having the `argocd-server` and 193 `argocd-application-controller` validate the TLS certificate of the 194 `argocd-repo-server` endpoint, the following steps need to be performed: 195 196 * Create a persistent TLS certificate to be used by `argocd-repo-server`, as 197 shown above 198 * Restart the `argocd-repo-server` pod(s) 199 * Modify the pod startup parameters for `argocd-server` and 200 `argocd-application-controller` to include the `--repo-server-strict-tls` 201 parameter. 202 203 The `argocd-server` and `argocd-application-controller` workloads will now 204 validate the TLS certificate of the `argocd-repo-server` by using the 205 certificate stored in the `argocd-repo-server-tls` secret. 206 207 !!!note "Certificate expiry" 208 Please make sure that the certificate has a proper lifetime. Remember, 209 when replacing certificates, all workloads must be restarted to pick up 210 the certificate and work properly. 211 212 ### Configuring TLS to argocd-dex-server 213 214 `argocd-server` communicates with the `argocd-dex-server` using an HTTPS API 215 over TLS. By default, `argocd-dex-server` generates a non-persistent, self-signed 216 certificate for its HTTPS endpoint on startup. Because `argocd-dex-server` 217 has no means to connect to the K8s control plane API, this certificate is not 218 available to outside consumers for verification. `argocd-server` will use a 219 non-validating connection to `argocd-dex-server` for this reason. 220 221 To change this behavior to be more secure by having the `argocd-server` validate 222 the TLS certificate of the `argocd-dex-server` endpoint, the following steps need 223 to be performed: 224 225 * Create a persistent TLS certificate to be used by `argocd-dex-server`, as 226 shown above 227 * Restart the `argocd-dex-server` pod(s) 228 * Modify the pod startup parameters for `argocd-server` to include the 229 `--dex-server-strict-tls` parameter. 230 231 The `argocd-server` workload will now validate the TLS certificate of the 232 `argocd-dex-server` by using the certificate stored in the `argocd-dex-server-tls` 233 secret. 234 235 !!!note "Certificate expiry" 236 Please make sure that the certificate has a proper lifetime. Remember, 237 when replacing certificates, all workloads must be restarted to pick up 238 the certificate and work properly. 239 240 ### Disabling TLS to argocd-repo-server 241 242 In some scenarios where mTLS through sidecar proxies is involved (e.g. 243 in a service mesh), you may want to configure the connections between the 244 `argocd-server` and `argocd-application-controller` to `argocd-repo-server` 245 to not use TLS at all. 246 247 In this case, you will need to: 248 249 * Configure `argocd-repo-server` with TLS on the gRPC API disabled by specifying 250 the `--disable-tls` parameter to the pod container's startup arguments. 251 Also, consider restricting listening addresses to the loopback interface by specifying 252 `--listen 127.0.0.1` parameter, so that the insecure endpoint is not exposed on 253 the pod's network interfaces, but still available to the sidecar container. 254 * Configure `argocd-server` and `argocd-application-controller` to not use TLS 255 for connections to the `argocd-repo-server` by specifying the parameter 256 `--repo-server-plaintext` to the pod container's startup arguments 257 * Configure `argocd-server` and `argocd-application-controller` to connect to 258 the sidecar instead of directly to the `argocd-repo-server` service by 259 specifying its address via the `--repo-server <address>` parameter 260 261 After this change, `argocd-server` and `argocd-application-controller` will 262 use a plain text connection to the sidecar proxy, which will handle all aspects 263 of TLS to `argocd-repo-server`'s TLS sidecar proxy. 264 265 ### Disabling TLS to argocd-dex-server 266 267 In some scenarios where mTLS through sidecar proxies is involved (e.g. 268 in a service mesh), you may want to configure the connections between 269 `argocd-server` to `argocd-dex-server` to not use TLS at all. 270 271 In this case, you will need to: 272 273 * Configure `argocd-dex-server` with TLS on the HTTPS API disabled by specifying 274 the `--disable-tls` parameter to the pod container's startup arguments 275 * Configure `argocd-server` to not use TLS for connections to `argocd-dex-server` 276 by specifying the parameter `--dex-server-plaintext` to the pod container's startup 277 arguments 278 * Configure `argocd-server` to connect to the sidecar instead of directly to the 279 `argocd-dex-server` service by specifying its address via the `--dex-server <address>` 280 parameter 281 282 After this change, `argocd-server` will use a plain text connection to the sidecar 283 proxy, that will handle all aspects of TLS to the `argocd-dex-server`'s TLS sidecar proxy. 284