github.com/argoproj/argo-cd/v2@v2.10.9/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  ## Configuring TLS for argocd-server
    20  
    21  ### Inbound TLS options for argocd-server
    22  
    23  You can configure certain TLS options for the `argocd-server` workload by
    24  setting command line parameters. The following parameters are available:
    25  
    26  |Parameter|Default|Description|
    27  |---------|-------|-----------|
    28  |`--insecure`|`false`|Disables TLS completely|
    29  |`--tlsminversion`|`1.2`|The minimum TLS version to be offered to clients|
    30  |`--tlsmaxversion`|`1.3`|The maximum TLS version to be offered to clients|
    31  |`--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|
    32  
    33  ### TLS certificates used by argocd-server
    34  
    35  There are two ways to configure the TLS certificates used by `argocd-server`:
    36  
    37  * Setting the `tls.crt` and `tls.key` keys in the `argocd-server-tls` secret
    38    to hold PEM data of the certificate and the corresponding private key. The
    39    `argocd-server-tls` secret may be of type `tls`, but does not have to be.
    40  * Setting the `tls.crt` and `tls.key` keys in the `argocd-secret` secret to
    41    hold PEM data of the certificate and the corresponding private key. This
    42    method is considered deprecated, and only exists for purposes of backwards
    43    compatibility. Changing `argocd-secret` should not be used to override the
    44    TLS certificate anymore.
    45  
    46  Argo CD decides which TLS certificate to use for the endpoint of
    47  `argocd-server` as follows:
    48  
    49  * If the `argocd-server-tls` secret exists and contains a valid key pair in the
    50    `tls.crt` and `tls.key` keys, this will be used for the certificate of the
    51    endpoint of `argocd-server`.
    52  * Otherwise, if the `argocd-secret` secret contains a valid key pair in the
    53   `tls.crt` and `tls.key` keys, this will be used as certificate for the
    54    endpoint of `argocd-server`.
    55  * If no `tls.crt` and `tls.key` keys are found in neither of the two mentioned
    56    secrets, Argo CD will generate a self-signed certificate and persist it in
    57    the `argocd-secret` secret.
    58  
    59  The `argocd-server-tls` secret contains only information for TLS configuration
    60  to be used by `argocd-server` and is safe to be managed via third-party tools
    61  such as `cert-manager` or `SealedSecrets`
    62  
    63  To create this secret manually from an existing key pair, you can use `kubectl`:
    64  
    65  ```shell
    66  kubectl create -n argocd secret tls argocd-server-tls \
    67    --cert=/path/to/cert.pem \
    68    --key=/path/to/key.pem
    69  ```
    70  
    71  Argo CD will pick up changes to the `argocd-server-tls` secret automatically
    72  and will not require restart of the pods to use a renewed certificate.
    73  
    74  ## Configuring inbound TLS for argocd-repo-server
    75  
    76  ### Inbound TLS options for argocd-repo-server
    77  
    78  You can configure certain TLS options for the `argocd-repo-server` workload by
    79  setting command line parameters. The following parameters are available:
    80  
    81  |Parameter|Default|Description|
    82  |---------|-------|-----------|
    83  |`--disable-tls`|`false`|Disables TLS completely|
    84  |`--tlsminversion`|`1.2`|The minimum TLS version to be offered to clients|
    85  |`--tlsmaxversion`|`1.3`|The maximum TLS version to be offered to clients|
    86  |`--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|
    87  
    88  ### Inbound TLS certificates used by argocd-repo-server
    89  
    90  To configure the TLS certificate used by the `argocd-repo-server` workload,
    91  create a secret named `argocd-repo-server-tls` in the namespace where Argo CD
    92  is running in with the certificate's key pair stored in `tls.crt` and
    93  `tls.key` keys. If this secret does not exist, `argocd-repo-server` will
    94  generate and use a self-signed certificate.
    95  
    96  To create this secret, you can use `kubectl`:
    97  
    98  ```shell
    99  kubectl create -n argocd secret tls argocd-repo-server-tls \
   100    --cert=/path/to/cert.pem \
   101    --key=/path/to/key.pem
   102  ```
   103  
   104  If the certificate is self-signed, you will also need to add `ca.crt` to the secret
   105  with the contents of your CA certificate.
   106  
   107  Please note, that as opposed to `argocd-server`, the `argocd-repo-server` is
   108  not able to pick up changes to this secret automatically. If you create (or
   109  update) this secret, the `argocd-repo-server` pods need to be restarted.
   110  
   111  Also note, that the certificate should be issued with the correct SAN entries
   112  for the `argocd-repo-server`, containing at least the entries for
   113  `DNS:argocd-repo-server` and `DNS:argocd-repo-server.argo-cd.svc` depending
   114  on how your workloads connect to the repository server.
   115  
   116  ## Configuring inbound TLS for argocd-dex-server
   117  
   118  ### Inbound TLS options for argocd-dex-server
   119  
   120  You can configure certain TLS options for the `argocd-dex-server` workload by
   121  setting command line parameters. The following parameters are available:
   122  
   123  |Parameter|Default|Description|
   124  |---------|-------|-----------|
   125  |`--disable-tls`|`false`|Disables TLS completely|
   126  
   127  ### Inbound TLS certificates used by argocd-dex-server
   128  
   129  To configure the TLS certificate used by the `argocd-dex-server` workload,
   130  create a secret named `argocd-dex-server-tls` in the namespace where Argo CD
   131  is running in with the certificate's key pair stored in `tls.crt` and
   132  `tls.key` keys. If this secret does not exist, `argocd-dex-server` will
   133  generate and use a self-signed certificate.
   134  
   135  To create this secret, you can use `kubectl`:
   136  
   137  ```shell
   138  kubectl create -n argocd secret tls argocd-dex-server-tls \
   139    --cert=/path/to/cert.pem \
   140    --key=/path/to/key.pem
   141  ```
   142  
   143  If the certificate is self-signed, you will also need to add `ca.crt` to the secret
   144  with the contents of your CA certificate.
   145  
   146  Please note, that as opposed to `argocd-server`, the `argocd-dex-server` is
   147  not able to pick up changes to this secret automatically. If you create (or
   148  update) this secret, the `argocd-dex-server` pods need to be restarted.
   149  
   150  Also note, that the certificate should be issued with the correct SAN entries
   151  for the `argocd-dex-server`, containing at least the entries for
   152  `DNS:argocd-dex-server` and `DNS:argocd-dex-server.argo-cd.svc` depending
   153  on how your workloads connect to the repository server.
   154  
   155  ## Configuring TLS between Argo CD components
   156  
   157  ### Configuring TLS to argocd-repo-server
   158  
   159  Both `argocd-server` and `argocd-application-controller` communicate with the
   160  `argocd-repo-server` using a gRPC API over TLS. By default,
   161  `argocd-repo-server` generates a non-persistent, self signed certificate
   162  to use for its gRPC endpoint on startup. Because the `argocd-repo-server` has
   163  no means to connect to the K8s control plane API, this certificate is not
   164  being available to outside consumers for verification. Both, the
   165  `argocd-server` and `argocd-application-server` will use a non-validating
   166  connection to the `argocd-repo-server` for this reason.
   167  
   168  To change this behavior to be more secure by having the `argocd-server` and
   169  `argocd-application-controller` validate the TLS certificate of the
   170  `argocd-repo-server` endpoint, the following steps need to be performed:
   171  
   172  * Create a persistent TLS certificate to be used by `argocd-repo-server`, as
   173    shown above
   174  * Restart the `argocd-repo-server` pod(s)
   175  * Modify the pod startup parameters for `argocd-server` and
   176    `argocd-application-controller` to include the `--repo-server-strict-tls`
   177    parameter.
   178  
   179  The `argocd-server` and `argocd-application-controller` workloads will now
   180  validate the TLS certificate of the `argocd-repo-server` by using the
   181  certificate stored in the `argocd-repo-server-tls` secret.
   182  
   183  !!!note "Certificate expiry"
   184      Please make sure that the certificate has a proper life time. Keep in
   185      mind that when you have to replace the certificate, all workloads have
   186      to be restarted in order to properly work again.
   187  
   188  ### Configuring TLS to argocd-dex-server
   189  
   190  `argocd-server` communicates with the `argocd-dex-server` using an HTTPS API
   191  over TLS. By default, `argocd-dex-server` generates a non-persistent, self
   192  signed certificate to use for its HTTPS endpoint on startup. Because the 
   193  `argocd-dex-server` has no means to connect to the K8s control plane API,
   194  this certificate is not being available to outside consumers for verification.
   195  The `argocd-server` will use a non-validating connection to the `argocd-dex-server`
   196  for this reason.
   197  
   198  To change this behavior to be more secure by having the `argocd-server` validate 
   199  the TLS certificate of the `argocd-dex-server` endpoint, the following steps need
   200  to be performed:
   201  
   202  * Create a persistent TLS certificate to be used by `argocd-dex-server`, as
   203    shown above
   204  * Restart the `argocd-dex-server` pod(s)
   205  * Modify the pod startup parameters for `argocd-server` to include the 
   206  `--dex-server-strict-tls` parameter.
   207  
   208  The `argocd-server` workload will now validate the TLS certificate of the
   209  `argocd-dex-server` by using the certificate stored in the `argocd-dex-server-tls`
   210  secret.
   211  
   212  !!!note "Certificate expiry"
   213      Please make sure that the certificate has a proper life time. Keep in
   214      mind that when you have to replace the certificate, all workloads have
   215      to be restarted in order to properly work again.
   216  
   217  ### Disabling TLS to argocd-repo-server
   218  
   219  In some scenarios where mTLS through side-car proxies is involved (e.g.
   220  in a service mesh), you may want configure the connections between the
   221  `argocd-server` and `argocd-application-controller` to `argocd-repo-server`
   222  to not use TLS at all.
   223  
   224  In this case, you will need to:
   225  
   226  * Configure `argocd-repo-server` with TLS on the gRPC API disabled by specifying
   227    the `--disable-tls` parameter to the pod container's startup arguments.
   228    Also, consider restricting listening addresses to the loopback interface by specifying
   229    `--listen 127.0.0.1` parameter, so that insecure endpoint is not exposed on
   230    the pod's network interfaces, but still available to the side-car container.
   231  * Configure `argocd-server` and `argocd-application-controller` to not use TLS
   232    for connections to the `argocd-repo-server` by specifying the parameter
   233    `--repo-server-plaintext` to the pod container's startup arguments
   234  * Configure `argocd-server` and `argocd-application-controller` to connect to
   235    the side-car instead of directly to the `argocd-repo-server` service by
   236    specifying its address via the `--repo-server <address>` parameter
   237  
   238  After this change, the `argocd-server` and `argocd-application-controller` will
   239  use a plain text connection to the side-car proxy, that will handle all aspects
   240  of TLS to the `argocd-repo-server`'s TLS side-car proxy.
   241  
   242  ### Disabling TLS to argocd-dex-server
   243  
   244  In some scenarios where mTLS through side-car proxies is involved (e.g.
   245  in a service mesh), you may want configure the connections between
   246  `argocd-server` to `argocd-dex-server` to not use TLS at all.
   247  
   248  In this case, you will need to:
   249  
   250  * Configure `argocd-dex-server` with TLS on the HTTPS API disabled by specifying
   251    the `--disable-tls` parameter to the pod container's startup arguments
   252  * Configure `argocd-server` to not use TLS for connections to the `argocd-dex-server` 
   253    by specifying the parameter `--dex-server-plaintext` to the pod container's startup
   254    arguments
   255  * Configure `argocd-server` to connect to the side-car instead of directly to the 
   256    `argocd-dex-server` service by specifying its address via the `--dex-server <address>`
   257    parameter
   258  
   259  After this change, the `argocd-server` will use a plain text connection to the side-car 
   260  proxy, that will handle all aspects of TLS to the `argocd-dex-server`'s TLS side-car proxy.
   261