support-ssl-in-operator (#2095) (#2102)

Co-authored-by: abby.huang <78209557+abby-cyber@users.noreply.github.com>

docs-2.0/nebula-operator/8.custom-cluster-configurations/8.5.enable-ssl.md

@@ -0,0 +1,182 @@
+# Enable SSL Encryption in Nebula Graph
+
+SSL encryption is a commonly used network security technology that ensures secure communication between the client and server. Its working principle is mainly to protect data transmitted over the network by using encryption algorithms to prevent data interception or tampering during transmission. During the SSL connection establishment process, the server sends a digital certificate containing a public key and some identity information to the client. This certificate is issued by a trusted third-party Certification Authority (CA). The client verifies this digital certificate to confirm the identity of the server. In the NebulaGraph environment running in Kubernetes, you can enable SSL encryption, and both the client and server need to verify their identities to ensure secure communication between the client and server, and also between servers. This article explains how to enable SSL encryption in NebulaGraph running in K8s.
+
+## Prerequisites
+
+- NebulaGraph Operator has been installed.
+- A NebulaGraph cluster has been created. For details, see [ Create a NebulaGraph cluster with kubectl](../3.deploy-nebula-graph-cluster/3.1create-cluster-with-kubectl.md) or [ Create a NebulaGraph cluster with Helm](../3.deploy-nebula-graph-cluster/3.2create-cluster-with-helm.md).
+- Certificates and their corresponding private keys have been generated for the client and server, and the CA certificate has been generated. For details, see [Generate Certificates Manually](https://kubernetes.io/docs/tasks/administer-cluster/certificates/).
+
+
+## Configure certifications
+
+Operator provides the `sslCerts` field to specify the encrypted certificates. The `sslCerts` field contains three subfields: `serverSecret`, `clientSecret`, and `caSecret`. These three fields are used to specify the Secret names of the NebulaGraph server certificate, client certificate, and CA certificate, respectively. When the user specifies these three fields, Operator reads the certificate content from the corresponding Secret and mounts it into the cluster's Pod.
+
+In a K8s cluster, SSL type Secrets use `tls.crt `and `tls.key` as the default names for the server or client certificate file and private key file, and the default name for the CA certificate file is `ca.crt` (the CA certificate does not need to configure a private key). If you change the names of the certificate file and private key, you need to add corresponding subfields in the `sslCerts` field to specify the new certificate and private key names, and specify the new names when creating the Secret.
+
+```yaml
+sslCerts:
+  # Name of the Secret containing the server certificate.
+  serverSecret: "server-cert"
+  # Name of the server certificate file. Defaults to tls.crt. No configuration is needed when using the default name.
+  serverPublicKey: ""
+  # Name of the server private key file. Defaults to tls.key. No configuration is needed when using the default name.
+  serverPrivateKey: ""
+  # Name of the Secret containing the client certificate.
+  clientSecret: "client-cert"
+  # Name of the client certificate file. Defaults to tls.crt. No configuration is needed when using the default name.
+  clientPublicKey: ""
+  # Name of the client private key file. Defaults to tls.key. No configuration is needed when using the default name.
+  clientPrivateKey: ""
+  # Name of the Secret containing the CA certificate.
+  caSecret: "ca-cert"
+  # Name of the CA certificate file. Defaults to ca.crt. No configuration is needed when using the default name.
+  caPublicKey: ""
+```
+
+You can use the `insecureSkipVerify` field to decide whether the client will verify the server's certificate chain and hostname. In production environments, it is recommended to set this to `false` to ensure the security of communication. If set to `true`, the client will not verify the server's certificate chain and hostname.
+
+```yaml
+sslCerts:
+  # Determines whether the client needs to verify the server's certificate when establishing an SSL connection.
+  insecureSkipVerify: false 
+```
+
+When the certificates are approaching expiration, they can be automatically updated by installing [cert-manager](https://cert-manager.io/docs/installation/supported-releases/). NebulaGraph will monitor changes to the certificate directory files, and once a change is detected, it will load the new certificate content into memory. 
+
+## Encryption strategies
+
+NebulaGraph offers three encryption strategies that you can choose and configure according to your needs.
+
+- Encryption of all inter-service communication
+
+  If you want to encrypt all data transmission between the client, Graph service, Meta service, and Storage service, you need to add the `enable_ssl = true` field to each service.
+
+  Here is an example configuration:
+
+  ```yaml
+  apiVersion: apps.nebula-graph.io/v1alpha1
+  kind: NebulaCluster
+  metadata:
+    name: nebula
+    namespace: default
+  spec:
+    sslCerts:
+      serverSecret: "server-cert"
+      clientSecret: "client-cert"
+      caSecret: "ca-cert"
+    graphd:
+      config:
+        enable_ssl: "true"
+    metad:
+      config:
+        enable_ssl: "true"
+    storaged:
+      config:
+        enable_ssl: "true"
+  ```
+
+- Encryption of only Graph service communication
+
+  If the K8s cluster is deployed in the same data center and only the port of the Graph service is exposed externally, you can choose to encrypt only data transmission between the client and the Graph service. In this case, other services can communicate internally without encryption. Just add the `enable_graph_ssl = true` field to the Graph service.
+
+  Here is an example configuration:
+
+  ```yaml
+  apiVersion: apps.nebula-graph.io/v1alpha1
+  kind: NebulaCluster
+  metadata:
+    name: nebula
+    namespace: default
+  spec:
+    sslCerts:
+      serverSecret: "server-cert"
+      caSecret: "ca-cert"
+    graphd:
+      config:
+        enable_graph_ssl: "true"
+  ```
+
+- Encryption of only Meta service communication
+
+  If you need to transmit confidential information to the Meta service, you can choose to encrypt data transmission related to the Meta service. In this case, you need to add the `enable_meta_ssl = true` configuration to each component.
+
+  Here is an example configuration:
+
+  ```yaml
+  apiVersion: apps.nebula-graph.io/v1alpha1
+  kind: NebulaCluster
+  metadata:
+    name: nebula
+    namespace: default
+  spec:
+    sslCerts:
+      serverSecret: "server-cert"
+      clientSecret: "client-cert"
+      caSecret: "ca-cert"
+    graphd:
+      config:
+        enable_meta_ssl: "true"
+    metad:
+      config:
+        enable_meta_ssl: "true"
+    storaged:
+      config:
+        enable_meta_ssl: "true"
+  ```
+
+## Steps
+
+1. Use the pre-generated server and client certificates and private keys, and the CA certificate to create a Secret for each.
+
+  - Examples to create an SSL type Secret for the server or client:
+
+    ```yaml
+    kubectl create secret tls <client/server-cert-secret> --key=<client/server.key> --cert=<client/server.crt>
+    ```
+
+    - `tls`: Indicates that the type of secret being created is TLS, which is used to store SSL/TLS certificates.
+    - `<client/server-cert-secret>`: Specifies the name of the new secret being created, which can be customized.
+    - `--key=<client/server.key>`: Specifies the path to the private key file of the SSL/TLS certificate to be stored in the secret.
+    - `--cert=<client/server.crt>`: Specifies the path to the public key certificate file of the SSL/TLS certificate to be stored in the secret.
+
+  - Create an encrypted CA certificate secret without specifying the private key of the CA.
+
+    ```yaml
+    kubectl create secret tls <ca-cert-secret> --key --cert=<ca.crt>
+    ```
+
+    - `<ca-cert-secret>`: The name of the Secret to be created.
+    - `<ca.crt>`: The path to the CA certificate file stored in the Secret. 
+
+
+2. Add server certificate, client certificate, CA certificate configuration, and encryption policy configuration in the corresponding cluster instance YAML file.
+
+  For example, add encryption configuration for transmission data between client, Graph service, Meta service, and Storage service.
+
+  ```yaml
+  apiVersion: apps.nebula-graph.io/v1alpha1
+  kind: NebulaCluster
+  metadata:
+    name: nebula
+    namespace: default
+  spec:
+    sslCerts:
+      serverSecret: "server-cert"  // The name of the server Certificate Secret.
+      clientSecret: "client-cert"  // The name of the client Certificate Secret.
+      caSecret: "ca-cert"          // The name of the CA Certificate Secret.
+    graphd:
+      config:
+        enable_ssl: "true"
+    metad:
+      config:
+        enable_ssl: "true"
+    storaged:
+      config:
+        enable_ssl: "true"
+  ```
+
+3. Use `kubectl apply -f` to apply the file to the Kubernetes cluster.
+
+This will enable SSL encryption in NebulaGraph and enhance the security of the data.

mkdocs.yml

@@ -718,6 +718,7 @@ nav:
 #ent
         - Balance storage data after scaling out: nebula-operator/8.custom-cluster-configurations/8.3.balance-data-when-scaling-storage.md
         - Manage cluster logs: nebula-operator/8.custom-cluster-configurations/8.4.manage-running-logs.md
+        - Enable SSL encryption: nebula-operator/8.custom-cluster-configurations/8.5.enable-ssl.md
       - Upgrade NebulaGraph clusters: nebula-operator/9.upgrade-nebula-cluster.md
       - Specify a rolling update strategy: nebula-operator/11.rolling-update-strategy.md
 #ent