AUTO: Sync Helm Charts docs to ScalarDL docs site repo (#321)

Co-authored-by: josh-wong <[email protected]>
scalar-labs · Jun 10, 2024 · 18a27fe · 18a27fe
1 parent 3574861
commit 18a27fe
Show file tree

Hide file tree

Showing 10 changed files with 2,117 additions and 151 deletions.
diff --git a/versioned_docs/version-3.8/helm-charts/configure-custom-values-envoy.mdx b/versioned_docs/version-3.8/helm-charts/configure-custom-values-envoy.mdx
@@ -1,3 +1,6 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Configure a custom values file for Scalar Envoy
 
 This document explains how to create your custom values file for the Scalar Envoy chart. If you want to know the details of the parameters, please refer to the [README](https://github.com/scalar-labs/helm-charts/blob/main/charts/envoy/README.md) of the Scalar Envoy chart.
@@ -146,8 +149,8 @@ envoy:
 
 If you're using AWS or Azure, please refer to the following documents for more details:
 
-* [How to install Scalar products through AWS Marketplace](https://github.com/scalar-labs/scalar-kubernetes/blob/master/docs/AwsMarketplaceGuide.md)
-* [How to install Scalar products through Azure Marketplace](https://github.com/scalar-labs/scalar-kubernetes/blob/master/docs/AzureMarketplaceGuide.md)
+* [How to install Scalar products through AWS Marketplace](../scalar-kubernetes/AwsMarketplaceGuide.mdx)
+* [How to install Scalar products through Azure Marketplace](../scalar-kubernetes/AzureMarketplaceGuide.mdx)
 
 ### TLS configurations (optional based on your environment)
 
@@ -156,10 +159,66 @@ You can enable TLS in:
 - Downstream connections between the client and Scalar Envoy.
 - Upstream connections between Scalar Envoy and Scalar products.
 
+In addition, you have several options from the following two perspectives:
+
+1. Management of private key and certificate files
+   1. Manage your private key and certificate files automatically by using [cert-manager](https://cert-manager.io/docs/).
+      - You can reduce maintenance or operation costs. For example, cert-manager automatically renews certificates before they expire and Scalar Helm Chart automatically mounts private key and certificate files on the Scalar product pods.
+      - You cannot use a CA that cert-manager does not support. You can see the supported issuer in the [cert-manager documentation](https://cert-manager.io/docs/configuration/issuers/).
+   1. Manage your private key and certificate files manually.
+      - You can issue and manage your private key and certificate files by using your preferred method on your own.
+      - You can use any certificate even if cert-manager does not support it.
+      - You must update secret resources when certificates expire.
+1. Kinds of certificates
+   1. Use a trusted CA (signed certificate by third party).
+      - You can use trusted certificates from a third-party certificate issuer.
+      - You can encrypt packets.
+      - You must pay costs to issue trusted certificates.
+   1. Use self-signed certificates.
+      - You can reduce costs to issue certificates.
+      - Reliability of certificates is lower than a trusted CA, but you can encrypt packets.
+
+In other words, you have the following four options:
+
+1. Use a self-signed CA with automatic management.
+1. Use a trusted CA with automatic management.
+1. Use a self-signed CA with manual management.
+1. Use a trusted CA with manual management.
+
+You should consider which method you use based on your security requirements. For guidance and related documentation for each method, refer to the following decision tree:
+
+```mermaid
+flowchart TD
+  A[Do you want to use <br /><a href='https://cert-manager.io/docs/'>cert-manager</a> to manage your <br />private key and certificate <br />files automatically?]
+  A -->|Yes, I want to manage my <br />certificates automatically.| B
+  A -->|No, I want to manage my <br />certificates manually by myself.| C
+  B[Do you want to use a <br />self-signed CA or a trusted CA?]
+  C[Do you want to use a <br />self-signed CA or a trusted CA?]
+  B -->|I want to use a <br />self-signed CA.| D
+  B -->|I want to use a <br />trusted CA.| E
+  C -->|I want to use a <br />self-signed CA.| F
+  C -->|I want to use a <br />trusted CA.| G
+  D[See the <a href='#use-a-self-signed-ca-with-cert-manager-to-manage-your-private-key-and-certificate-files'>Use a self-signed <br />CA with cert-manager to <br />manage your private key and <br />certificate files</a> section.]
+  E[See the <a href='#use-a-trusted-ca-with-cert-manager-to-manage-your-private-key-and-certificate-files'>Use a trusted <br />CA with cert-manager to <br />manage private key and <br />certificate files</a> section.]
+  F[See the <a href='#use-your-private-key-and-certificate-files'>Use your private <br />key and certificate files</a> <br />section, and use the self-signed <br />certificate you generated.]
+  G[See the <a href='#use-your-private-key-and-certificate-files'>Use your private key <br />and certificate files</a> section, <br />and use the trusted certificate <br />generated by the third party.]
+```
+
 #### Enable TLS in downstream connections
 
 You can enable TLS in downstream connections by using the following configurations:
 
+```yaml
+envoy:
+  tls:
+    downstream:
+      enabled: true
+```
+
+##### Use your private key and certificate files
+
+You can set your private key and certificate files by using the following configurations:
+
 ```yaml
 envoy:
   tls:
@@ -169,15 +228,67 @@ envoy:
       privateKeySecret: "envoy-tls-key"
 ```
 
-In this case, you have to create secret resources that include private key and certificate files for Scalar Envoy as follows:
+In this case, you have to create secret resources that include private key and certificate files for Scalar Envoy as follows, replacing the contents in the angle brackets as described:
 
 ```console
-kubectl create secret generic envoy-tls-cert --from-file=cert-chain=/path/to/your/certificate/file -n <NAMESPACE>
-kubectl create secret generic envoy-tls-key --from-file=private-key=/path/to/your/private/key/file -n <NAMESPACE>
+kubectl create secret generic envoy-tls-cert --from-file=tls.crt=/<PATH_TO_YOUR_CERTIFICATE_FILE_FOR_SCALAR_ENVOY> -n <NAMESPACE>
+kubectl create secret generic envoy-tls-key --from-file=tls.key=/<PATH_TO_YOUR_PRIVATE_KEY_FILE_FOR_SCALAR_ENVOY> -n <NAMESPACE>
 ```
 
 For more details on how to prepare private key and certificate files, see [How to create private key and certificate files for Scalar products](../scalar-kubernetes/HowToCreateKeyAndCertificateFiles.mdx).
 
+##### Use a trusted CA with cert-manager to manage your private key and certificate files
+
+You can manage your private key and certificate files with cert-manager by using the following configurations, replacing the content in the angle brackets as described:
+
+:::note
+
+* If you want to use cert-manager, you must deploy cert-manager and prepare the `Issuers` resource. For details, see the cert-manager documentation, [Installation](https://cert-manager.io/docs/installation/) and [Issuer Configuration](https://cert-manager.io/docs/configuration/).
+* By default, Scalar Helm Chart creates a `Certificate` resource that satisfies the certificate requirements of Scalar products. The default certificate configuration is recommended, but if you use a custom certificate configuration, you must satisfy the certificate requirements of Scalar products. For details, see [How to create private key and certificate files for Scalar products](../scalar-kubernetes/HowToCreateKeyAndCertificateFiles.mdx#certificate-requirements).
+
+:::
+
+```yaml
+envoy:
+  tls:
+    downstream:
+      enabled: true
+      certManager:
+        enabled: true
+        issuerRef:
+          name: <YOUR_TRUSTED_CA>
+        dnsNames:
+          - envoy.scalar.example.com
+```
+
+In this case, cert-manager issues your private key and certificate files by using your trusted issuer. By using cert-manager, you don't need to mount your private key and certificate files manually.
+
+##### Use a self-signed CA with cert-manager to manage your private key and certificate files
+
+You can manage your private key and self-signed certificate files with cert-manager by using the following configurations:
+
+:::note
+
+* If you want to use cert-manager, you must deploy cert-manager. For details, see the cert-manager documentation, [Installation](https://cert-manager.io/docs/installation/).
+* By default, Scalar Helm Chart creates a `Certificate` resource that satisfies the certificate requirements of Scalar products. The default certificate configuration is recommended, but if you use a custom certificate configuration, you must satisfy the certificate requirements of Scalar products. For details, see [How to create private key and certificate files for Scalar products](../scalar-kubernetes/HowToCreateKeyAndCertificateFiles.mdx#certificate-requirements).
+
+:::
+
+```yaml
+envoy:
+  tls:
+    downstream:
+      enabled: true
+      certManager:
+        enabled: true
+        selfSigned:
+          enabled: true
+        dnsNames:
+          - envoy.scalar.example.com
+```
+
+In this case, Scalar Helm Charts and cert-manager issue your private key and self-signed certificate files. You don't need to mount your private key and certificate files manually.
+
 #### Enable TLS in upstream connections
 
 You can enable TLS in upstream connections by using the following configurations:
@@ -187,33 +298,67 @@ envoy:
   tls:
     upstream:
       enabled: true
-      overrideAuthority: "cluster.scalardb.example.com"
-      caRootCertSecret: "scalardb-cluster-tls-ca"
 ```
 
-In this case, you have to create secret resources that include CA certificate files as follows. You must set the root CA certificate file based on the upstream that you use (ScalarDB Cluster, ScalarDL Ledger, or ScalarDL Auditor).
+Also, you must set root CA certificate file of upstream Scalar products. To determine which approach you should take, refer to the following decision tree:
+
+```mermaid
+flowchart TD
+  A[Are you using <a href='https://cert-manager.io/docs/'>cert-manager</a>?]
+  A -->|Yes| B
+  A -->|No| D
+  B[Are you using a <a href='#use-a-self-signed-ca-with-cert-manager-to-manage-your-private-key-and-certificate-files'>self-signed CA with cert-manager</a>?]
+  B -->|No| C[Are you using the same <a href='#use-a-trusted-ca-with-cert-manager-to-manage-your-private-key-and-certificate-files'>trusted CA</a> for Envoy and <br />upstream Scalar products with cert-manager?]
+  C -->|No| D[You must <a href='#set-your-root-ca-certificate-file-of-upstream-scalar-products'>set upstream Scalar products' <br />root CA certificate</a> manually.]
+  C ---->|Yes| E[Scalar Helm Chart automatically sets the root CA certificate. You <br />don't need to set `envoy.tls.upstream.caRootCertSecret` explicitly.]
+  B ---->|Yes| E
+```
 
-* ScalarDB Cluster
+##### Set your root CA certificate file of upstream Scalar products
 
-  ```console
-  kubectl create secret generic scalardb-cluster-tls-ca --from-file=ca-root-cert=/path/to/root/ca/cert/file/for/scalardb-cluster -n <NAMESPACE>
-  ```
+You can set your root CA certificate file by using the following configurations:
 
-* ScalarDL Ledger
+```yaml
+envoy:
+  tls:
+    upstream:
+      enabled: true
+      caRootCertSecret: "envoy-upstream-scalardb-cluster-root-ca"
+```
 
-  ```console
-  kubectl create secret generic scalardl-ledger-tls-ca --from-file=ca-root-cert=/path/to/root/ca/cert/file/for/scalardl-ledger -n <NAMESPACE>
-  ```
+In this case, you have to create secret resources that include CA certificate files as follows. You must set the root CA certificate file based on the upstream that you use (ScalarDB Cluster, ScalarDL Ledger, or ScalarDL Auditor). Be sure to replace the contents in the angle brackets as described.
+
+<Tabs>
+  <TabItem value="ScalarDB_Cluster" label="ScalarDB Cluster" default>
+    ```console
+    kubectl create secret generic envoy-upstream-scalardb-cluster-root-ca --from-file=ca.crt=/<PATH_TO_ROOT_CA_CERTIFICATE_FILE_FOR_SCALARDB_CLUSTER> -n <NAMESPACE>
+    ```
+  </TabItem>
+  <TabItem value="ScalarDL_Ledger" label="ScalarDL Ledger">
+    ```console
+    kubectl create secret generic envoy-upstream-scalardl-ledger-root-ca --from-file=ca.crt=/<PATH_TO_ROOT_CA_CERTIFICATE_FILE_FOR_SCALARDL_LEDGER> -n <NAMESPACE>
+    ```
+  </TabItem>
+  <TabItem value="ScalarDB_Auditor" label="ScalarDL Auditor">
+    ```console
+    kubectl create secret generic envoy-upstream-scalardl-auditor-root-ca --from-file=ca.crt=/<PATH_TO_ROOT_CA_CERTIFICATE_FILE_FOR_SCALARDL_AUDITOR> -n <NAMESPACE>
+    ```
+  </TabItem>
+</Tabs>
 
-* ScalarDL Auditor
+For more details on how to prepare private key and certificate files, see [How to create key and certificate files for Scalar products](../scalar-kubernetes/HowToCreateKeyAndCertificateFiles.mdx).
 
-  ```console
-  kubectl create secret generic scalardl-auditor-tls-ca --from-file=ca-root-cert=/path/to/root/ca/cert/file/for/scalardl-auditor -n <NAMESPACE>
-  ```
+##### Set custom authority for TLS communications
 
-For more details on how to prepare private key and certificate files, see [How to create key and certificate files for Scalar products](../scalar-kubernetes/HowToCreateKeyAndCertificateFiles.mdx).
+You can set the custom authority for TLS communications by using `envoy.tls.upstream.overrideAuthority`. This value doesn't change what host is actually connected. This value is intended for testing but may safely be used outside of tests as an alternative to DNS overrides. For example, you can specify the hostname presented in the certificate chain file that you set by using `scalardbCluster.tls.certChainSecret`, `ledger.tls.certChainSecret`, or `auditor.tls.certChainSecret`, depending on which product you're using. Envoy uses this value for verifying the certificate of the TLS connection with ScalarDB Cluster or ScalarDL.
 
-Also, you can set the custom authority for TLS communication by using `envoy.tls.upstream.overrideAuthority`. This value doesn't change what host is actually connected. This value is intended for testing but may safely be used outside of tests as an alternative to DNS overrides. For example, you can specify the hostname presented in the certificate chain file that you set by using `scalardbCluster.tls.certChainSecret`, `ledger.tls.certChainSecret`, or `auditor.tls.certChainSecret`, depending on which product you're using. Envoy uses this value for verifying the certificate of the TLS connection with ScalarDB Cluster or ScalarDL.
+```yaml
+envoy:
+  tls:
+    upstream:
+      enabled: true
+      overrideAuthority: "cluster.scalardb.example.com"
+```
 
 ### Replica configurations (Optional based on your environment)