From c0cbeaf0d69e90b989f197fc2e641d87f086df22 Mon Sep 17 00:00:00 2001 From: MobarakHsn Date: Tue, 16 Jul 2024 13:14:32 +0600 Subject: [PATCH] update image Signed-off-by: MobarakHsn --- docs/guides/pgpool/concepts/pgpool.md | 4 +- docs/guides/pgpool/tls/_index.md | 10 + docs/guides/pgpool/tls/overview.md | 70 +++++ docs/guides/pgpool/tls/replicaset.md | 266 +++++++++++++++++ docs/guides/pgpool/tls/sharding.md | 274 ++++++++++++++++++ docs/guides/pgpool/tls/standalone.md | 245 ++++++++++++++++ docs/images/day-2-operation/pgpool/pp-tls.svg | 4 + 7 files changed, 871 insertions(+), 2 deletions(-) create mode 100755 docs/guides/pgpool/tls/_index.md create mode 100644 docs/guides/pgpool/tls/overview.md create mode 100644 docs/guides/pgpool/tls/replicaset.md create mode 100644 docs/guides/pgpool/tls/sharding.md create mode 100644 docs/guides/pgpool/tls/standalone.md create mode 100644 docs/images/day-2-operation/pgpool/pp-tls.svg diff --git a/docs/guides/pgpool/concepts/pgpool.md b/docs/guides/pgpool/concepts/pgpool.md index 9e0c443480..c713178cb9 100644 --- a/docs/guides/pgpool/concepts/pgpool.md +++ b/docs/guides/pgpool/concepts/pgpool.md @@ -159,8 +159,8 @@ secret "pgpool-auth" created ```yaml apiVersion: v1 data: - password: O9xE1mZZDAdBTbrV - username: jhon-doe + password: "O9xE1mZZDAdBTbrV" + username: "jhon-doe" kind: Secret metadata: name: pgpool-auth diff --git a/docs/guides/pgpool/tls/_index.md b/docs/guides/pgpool/tls/_index.md new file mode 100755 index 0000000000..a96cb50f0c --- /dev/null +++ b/docs/guides/pgpool/tls/_index.md @@ -0,0 +1,10 @@ +--- +title: Run pgpool with TLS +menu: + docs_{{ .version }}: + identifier: pp-tls + name: TLS/SSL Encryption + parent: pp-pgpool-guides + weight: 45 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/pgpool/tls/overview.md b/docs/guides/pgpool/tls/overview.md new file mode 100644 index 0000000000..633b54bd4c --- /dev/null +++ b/docs/guides/pgpool/tls/overview.md @@ -0,0 +1,70 @@ +--- +title: Pgpool TLS/SSL Encryption Overview +menu: + docs_{{ .version }}: + identifier: pp-tls-overview + name: Overview + parent: pp-tls + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Pgpool TLS/SSL Encryption + +**Prerequisite :** To configure TLS/SSL in `Pgpool`, `KubeDB` uses `cert-manager` to issue certificates. So first you have to make sure that the cluster has `cert-manager` installed. To install `cert-manager` in your cluster following steps [here](https://cert-manager.io/docs/installation/kubernetes/). + +To issue a certificate, the following crd of `cert-manager` is used: + +- `Issuer/ClusterIssuer`: Issuers, and ClusterIssuers represent certificate authorities (CAs) that are able to generate signed certificates by honoring certificate signing requests. All cert-manager certificates require a referenced issuer that is in a ready condition to attempt to honor the request. You can learn more details [here](https://cert-manager.io/docs/concepts/issuer/). + +- `Certificate`: `cert-manager` has the concept of Certificates that define a desired x509 certificate which will be renewed and kept up to date. You can learn more details [here](https://cert-manager.io/docs/concepts/certificate/). + +**Pgpool CRD Specification :** + +KubeDB uses following crd fields to enable SSL/TLS encryption in `Pgpool`. + +- `spec:` + - `sslMode` + - `tls:` + - `issuerRef` + - `certificates` + - `cientAuthMode` +Read about the fields in details from [pgpool concept](/docs/guides/pgpool/concepts/pgpool.md), + +When, `sslMode` is set to `require`, the users must specify the `tls.issuerRef` field. `KubeDB` uses the `issuer` or `clusterIssuer` referenced in the `tls.issuerRef` field, and the certificate specs provided in `tls.certificate` to generate certificate secrets using `Issuer/ClusterIssuers` specification. These certificates secrets including `ca.crt`, `tls.crt` and `tls.key` etc. are used to configure `Pgpool` server, exporter etc. respectively. + +## How TLS/SSL configures in Pgpool + +The following figure shows how `KubeDB` enterprise used to configure TLS/SSL in Pgpool. Open the image in a new tab to see the enlarged version. + +
+Deploy Pgpool with TLS/SSL +
Fig: Deploy Pgpool with TLS/SSL
+
+ +Deploying Pgpool with TLS/SSL configuration process consists of the following steps: + +1. At first, a user creates a `Issuer/ClusterIssuer` cr. + +2. Then the user creates a `Pgpool` cr which refers to the `Issuer/ClusterIssuer` cr that the user created in the previous step. + +3. `KubeDB` Provisioner operator watches for the `Pgpool` cr. + +4. When it finds one, it creates `Secret`, `Service`, etc. for the `Pgpool` database. + +5. `KubeDB` Ops-manager operator watches for `Pgpool`(5c), `Issuer/ClusterIssuer`(5b), `Secret` and `Service`(5a). + +6. When it finds all the resources(`Pgpool`, `Issuer/ClusterIssuer`, `Secret`, `Service`), it creates `Certificates` by using `tls.issuerRef` and `tls.certificates` field specification from `Pgpool` cr. + +7. `cert-manager` watches for certificates. + +8. When it finds one, it creates certificate secrets `tls-secrets`(server, client, exporter secrets etc.) that holds the actual certificate signed by the CA. + +9. `KubeDB` Provisioner operator watches for the Certificate secrets `tls-secrets`. + +10. When it finds all the tls-secret, it creates the related `StatefulSets` so that Pgpool database can be configured with TLS/SSL. + +In the next doc, we are going to show a step by step guide on how to configure a `Pgpool` database with TLS/SSL. \ No newline at end of file diff --git a/docs/guides/pgpool/tls/replicaset.md b/docs/guides/pgpool/tls/replicaset.md new file mode 100644 index 0000000000..3ff6a02879 --- /dev/null +++ b/docs/guides/pgpool/tls/replicaset.md @@ -0,0 +1,266 @@ +--- +title: MongoDB ReplicaSet TLS/SSL Encryption +menu: + docs_{{ .version }}: + identifier: mg-tls-replicaset + name: Replicaset + parent: mg-tls + weight: 30 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Run MongoDB with TLS/SSL (Transport Encryption) + +KubeDB supports providing TLS/SSL encryption (via, `sslMode` and `clusterAuthMode`) for MongoDB. This tutorial will show you how to use KubeDB to run a MongoDB database with TLS/SSL encryption. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Install [`cert-manger`](https://cert-manager.io/docs/installation/) v1.0.0 or later to your cluster to manage your SSL/TLS certificates. + +- Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). + +- To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + + ```bash + $ kubectl create ns demo + namespace/demo created + ``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/mongodb](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/mongodb) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Overview + +KubeDB uses following crd fields to enable SSL/TLS encryption in Mongodb. + +- `spec:` + - `sslMode` + - `tls:` + - `issuerRef` + - `certificate` + - `clusterAuthMode` + +Read about the fields in details in [mongodb concept](/docs/guides/mongodb/concepts/mongodb.md), + +`sslMode`, and `tls` is applicable for all types of MongoDB (i.e., `standalone`, `replicaset` and `sharding`), while `clusterAuthMode` provides [ClusterAuthMode](https://docs.mongodb.com/manual/reference/program/mongod/#cmdoption-mongod-clusterauthmode) for MongoDB clusters (i.e., `replicaset` and `sharding`). + +When, SSLMode is anything other than `disabled`, users must specify the `tls.issuerRef` field. KubeDB uses the `issuer` or `clusterIssuer` referenced in the `tls.issuerRef` field, and the certificate specs provided in `tls.certificate` to generate certificate secrets. These certificate secrets are then used to generate required certificates including `ca.crt`, `mongo.pem` and `client.pem`. + +The subject of `client.pem` certificate is added as `root` user in `$external` mongodb database. So, user can use this client certificate for `MONGODB-X509` `authenticationMechanism`. + +## Create Issuer/ ClusterIssuer + +We are going to create an example `Issuer` that will be used throughout the duration of this tutorial to enable SSL/TLS in MongoDB. Alternatively, you can follow this [cert-manager tutorial](https://cert-manager.io/docs/configuration/ca/) to create your own `Issuer`. + +- Start off by generating you ca certificates using openssl. + +```bash +openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ca.key -out ./ca.crt -subj "/CN=mongo/O=kubedb" +``` + +- Now create a ca-secret using the certificate files you have just generated. + +```bash +kubectl create secret tls mongo-ca \ + --cert=ca.crt \ + --key=ca.key \ + --namespace=demo +``` + +Now, create an `Issuer` using the `ca-secret` you have just created. The `YAML` file looks like this: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: mongo-ca-issuer + namespace: demo +spec: + ca: + secretName: mongo-ca +``` + +Apply the `YAML` file: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mongodb/tls/issuer.yaml +issuer.cert-manager.io/mongo-ca-issuer created +``` + +## TLS/SSL encryption in MongoDB Replicaset + +Below is the YAML for MongoDB Replicaset. Here, [`spec.sslMode`](/docs/guides/mongodb/concepts/mongodb.md#specsslMode) specifies `sslMode` for `replicaset` (which is `requireSSL`) and [`spec.clusterAuthMode`](/docs/guides/mongodb/concepts/mongodb.md#specclusterAuthMode) provides `clusterAuthMode` for mongodb replicaset nodes (which is `x509`). + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: MongoDB +metadata: + name: mgo-rs-tls + namespace: demo +spec: + version: "4.4.26" + sslMode: requireSSL + tls: + issuerRef: + apiGroup: "cert-manager.io" + kind: Issuer + name: mongo-ca-issuer + clusterAuthMode: x509 + replicas: 4 + replicaSet: + name: rs0 + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi +``` + +### Deploy MongoDB Replicaset + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mongodb/tls/mg-replicaset-ssl.yaml +mongodb.kubedb.com/mgo-rs-tls created +``` + +Now, wait until `mgo-rs-tls created` has status `Ready`. i.e, + +```bash +$ watch kubectl get mg -n demo +Every 2.0s: kubectl get mongodb -n demo +NAME VERSION STATUS AGE +mgo-rs-tls 4.4.26 Ready 4m10s +``` + +### Verify TLS/SSL in MongoDB Replicaset + +Now, connect to this database through [mongo-shell](https://docs.mongodb.com/v4.0/mongo/) and verify if `SSLMode` and `ClusterAuthMode` has been set up as intended. + +```bash +$ kubectl describe secret -n demo mgo-rs-tls-client-cert +Name: mgo-rs-tls-client-cert +Namespace: demo +Labels: +Annotations: cert-manager.io/alt-names: + cert-manager.io/certificate-name: mgo-rs-tls-client-cert + cert-manager.io/common-name: root + cert-manager.io/ip-sans: + cert-manager.io/issuer-group: cert-manager.io + cert-manager.io/issuer-kind: Issuer + cert-manager.io/issuer-name: mongo-ca-issuer + cert-manager.io/uri-sans: + +Type: kubernetes.io/tls + +Data +==== +ca.crt: 1147 bytes +tls.crt: 1172 bytes +tls.key: 1679 bytes +``` + +Now, Let's exec into a mongodb container and find out the username to connect in a mongo shell, + +```bash +$ kubectl exec -it mgo-rs-tls-0 -n demo bash +root@mgo-rs-tls-0:/$ ls /var/run/mongodb/tls +ca.crt client.pem mongo.pem +root@mgo-rs-tls-0:/$ openssl x509 -in /var/run/mongodb/tls/client.pem -inform PEM -subject -nameopt RFC2253 -noout +subject=CN=root,O=kubedb +``` + +Now, we can connect using `CN=root,O=kubedb` as root to connect to the mongo shell, + +```bash +root@mgo-rs-tls-0:/$ mongo --tls --tlsCAFile /var/run/mongodb/tls/ca.crt --tlsCertificateKeyFile /var/run/mongodb/tls/client.pem admin --host localhost --authenticationMechanism MONGODB-X509 --authenticationDatabase='$external' -u "CN=root,O=kubedb" --quiet +Welcome to the MongoDB shell. +For interactive help, type "help". +For more comprehensive documentation, see + http://docs.mongodb.org/ +Questions? Try the support group + http://groups.google.com/group/mongodb-user +rs0:PRIMARY> +``` + +We are connected to the mongo shell. Let's run some command to verify the sslMode and the user, + +```bash +rs0:PRIMARY> db.adminCommand({ getParameter:1, sslMode:1 }) +{ + "sslMode" : "requireSSL", + "ok" : 1, + "$clusterTime" : { + "clusterTime" : Timestamp(1599490676, 1), + "signature" : { + "hash" : BinData(0,"/wQ4pf4HVi1T7SOyaB3pXO56j64="), + "keyId" : NumberLong("6869759546676477954") + } + }, + "operationTime" : Timestamp(1599490676, 1) +} + +rs0:PRIMARY> use $external +switched to db $external + +rs0:PRIMARY> show users +{ + "_id" : "$external.CN=root,O=kubedb", + "userId" : UUID("9cebbcf4-74bf-47dd-a485-1604125058da"), + "user" : "CN=root,O=kubedb", + "db" : "$external", + "roles" : [ + { + "role" : "root", + "db" : "admin" + } + ], + "mechanisms" : [ + "external" + ] +} +> exit +bye +``` + +You can see here that, `sslMode` is set to `requireSSL` and a user is created in `$external` with name `"CN=root,O=kubedb"`. + +## Changing the SSLMode & ClusterAuthMode + +User can update `sslMode` & `ClusterAuthMode` if needed. Some changes may be invalid from mongodb end, like using `sslMode: disabled` with `clusterAuthMode: x509`. + +The good thing is, **KubeDB operator will throw error for invalid SSL specs while creating/updating the MongoDB object.** i.e., + +```bash +$ kubectl patch -n demo mg/mgo-rs-tls -p '{"spec":{"sslMode": "disabled","clusterAuthMode": "x509"}}' --type="merge" +Error from server (Forbidden): admission webhook "mongodb.validators.kubedb.com" denied the request: can't have disabled set to mongodb.spec.sslMode when mongodb.spec.clusterAuthMode is set to x509 +``` + +To **update from Keyfile Authentication to x.509 Authentication**, change the `sslMode` and `clusterAuthMode` in recommended sequence as suggested in [official documentation](https://docs.mongodb.com/manual/tutorial/update-keyfile-to-x509/). Each time after changing the specs, follow the procedure that is described above to verify the changes of `sslMode` and `clusterAuthMode` inside the database. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete mongodb -n demo mgo-rs-tls +kubectl delete issuer -n demo mongo-ca-issuer +kubectl delete ns demo +``` + +## Next Steps + +- Detail concepts of [MongoDB object](/docs/guides/mongodb/concepts/mongodb.md). +- [Backup and Restore](/docs/guides/mongodb/backup/overview/index.md) MongoDB databases using Stash. +- Initialize [MongoDB with Script](/docs/guides/mongodb/initialization/using-script.md). +- Monitor your MongoDB database with KubeDB using [out-of-the-box Prometheus operator](/docs/guides/mongodb/monitoring/using-prometheus-operator.md). +- Monitor your MongoDB database with KubeDB using [out-of-the-box builtin-Prometheus](/docs/guides/mongodb/monitoring/using-builtin-prometheus.md). +- Use [private Docker registry](/docs/guides/mongodb/private-registry/using-private-registry.md) to deploy MongoDB with KubeDB. +- Use [kubedb cli](/docs/guides/mongodb/cli/cli.md) to manage databases like kubectl for Kubernetes. +- Detail concepts of [MongoDB object](/docs/guides/mongodb/concepts/mongodb.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/pgpool/tls/sharding.md b/docs/guides/pgpool/tls/sharding.md new file mode 100644 index 0000000000..63b19ece57 --- /dev/null +++ b/docs/guides/pgpool/tls/sharding.md @@ -0,0 +1,274 @@ +--- +title: MongoDB Shard TLS/SSL Encryption +menu: + docs_{{ .version }}: + identifier: mg-tls-shard + name: Sharding + parent: mg-tls + weight: 40 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Run MongoDB with TLS/SSL (Transport Encryption) + +KubeDB supports providing TLS/SSL encryption (via, `sslMode` and `clusterAuthMode`) for MongoDB. This tutorial will show you how to use KubeDB to run a MongoDB database with TLS/SSL encryption. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Install [`cert-manger`](https://cert-manager.io/docs/installation/) v1.0.0 or later to your cluster to manage your SSL/TLS certificates. + +- Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). + +- To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + + ```bash + $ kubectl create ns demo + namespace/demo created + ``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/mongodb](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/mongodb) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Overview + +KubeDB uses following crd fields to enable SSL/TLS encryption in Mongodb. + +- `spec:` + - `sslMode` + - `tls:` + - `issuerRef` + - `certificate` + - `clusterAuthMode` + +Read about the fields in details in [mongodb concept](/docs/guides/mongodb/concepts/mongodb.md), + +`sslMode`, and `tls` is applicable for all types of MongoDB (i.e., `standalone`, `replicaset` and `sharding`), while `clusterAuthMode` provides [ClusterAuthMode](https://docs.mongodb.com/manual/reference/program/mongod/#cmdoption-mongod-clusterauthmode) for MongoDB clusters (i.e., `replicaset` and `sharding`). + +When, SSLMode is anything other than `disabled`, users must specify the `tls.issuerRef` field. KubeDB uses the `issuer` or `clusterIssuer` referenced in the `tls.issuerRef` field, and the certificate specs provided in `tls.certificate` to generate certificate secrets. These certificate secrets are then used to generate required certificates including `ca.crt`, `mongo.pem` and `client.pem`. + +The subject of `client.pem` certificate is added as `root` user in `$external` mongodb database. So, user can use this client certificate for `MONGODB-X509` `authenticationMechanism`. + +## Create Issuer/ ClusterIssuer + +We are going to create an example `Issuer` that will be used throughout the duration of this tutorial to enable SSL/TLS in MongoDB. Alternatively, you can follow this [cert-manager tutorial](https://cert-manager.io/docs/configuration/ca/) to create your own `Issuer`. + +- Start off by generating you ca certificates using openssl. + +```bash +openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ca.key -out ./ca.crt -subj "/CN=mongo/O=kubedb" +``` + +- Now create a ca-secret using the certificate files you have just generated. + +```bash +kubectl create secret tls mongo-ca \ + --cert=ca.crt \ + --key=ca.key \ + --namespace=demo +``` + +Now, create an `Issuer` using the `ca-secret` you have just created. The `YAML` file looks like this: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: mongo-ca-issuer + namespace: demo +spec: + ca: + secretName: mongo-ca +``` + +Apply the `YAML` file: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mongodb/tls/issuer.yaml +issuer.cert-manager.io/mongo-ca-issuer created +``` + +## TLS/SSL encryption in MongoDB Sharding + +Below is the YAML for MongoDB Sharding. Here, [`spec.sslMode`](/docs/guides/mongodb/concepts/mongodb.md#specsslMode) specifies `sslMode` for `sharding` and [`spec.clusterAuthMode`](/docs/guides/mongodb/concepts/mongodb.md#specclusterAuthMode) provides `clusterAuthMode` for sharding servers. + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: MongoDB +metadata: + name: mongo-sh-tls + namespace: demo +spec: + version: "4.4.26" + sslMode: requireSSL + tls: + issuerRef: + apiGroup: "cert-manager.io" + kind: Issuer + name: mongo-ca-issuer + clusterAuthMode: x509 + shardTopology: + configServer: + replicas: 2 + storage: + resources: + requests: + storage: 1Gi + storageClassName: standard + mongos: + replicas: 2 + shard: + replicas: 2 + shards: 2 + storage: + resources: + requests: + storage: 1Gi + storageClassName: standard + storageType: Durable + terminationPolicy: WipeOut +``` + +### Deploy MongoDB Sharding + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mongodb/tls/mg-shard-ssl.yaml +mongodb.kubedb.com/mongo-sh-tls created +``` + +Now, wait until `mongo-sh-tls created` has status `Ready`. ie, + +```bash +$ watch kubectl get mg -n demo +Every 2.0s: kubectl get mongodb -n demo +NAME VERSION STATUS AGE +mongo-sh-tls 4.4.26 Ready 4m24s +``` + +### Verify TLS/SSL in MongoDB Sharding + +Now, connect to `mongos` component of this database through [mongo-shell](https://docs.mongodb.com/v4.0/mongo/) and verify if `SSLMode` and `ClusterAuthMode` has been set up as intended. + +```bash +$ kubectl describe secret -n demo mongo-sh-tls-client-cert +Name: mongo-sh-tls-client-cert +Namespace: demo +Labels: +Annotations: cert-manager.io/alt-names: + cert-manager.io/certificate-name: mongo-sh-tls-client-cert + cert-manager.io/common-name: root + cert-manager.io/ip-sans: + cert-manager.io/issuer-group: cert-manager.io + cert-manager.io/issuer-kind: Issuer + cert-manager.io/issuer-name: mongo-ca-issuer + cert-manager.io/uri-sans: + +Type: kubernetes.io/tls + +Data +==== +ca.crt: 1147 bytes +tls.crt: 1172 bytes +tls.key: 1679 bytes +``` + +Now, Let's exec into a mongodb container and find out the username to connect in a mongo shell, + +```bash +$ kubectl exec -it mongo-sh-tls-mongos-0 -n demo bash +root@mongo-sh-tls-mongos-0:/$ ls /var/run/mongodb/tls +ca.crt client.pem mongo.pem +mongodb@mgo-sh-tls-mongos-0:/$ openssl x509 -in /var/run/mongodb/tls/client.pem -inform PEM -subject -nameopt RFC2253 -noout +subject=CN=root,O=kubedb +``` + +Now, we can connect using `CN=root,O=kubedb` as root to connect to the mongo shell, + +```bash +root@mongo-sh-tls-mongos-0:/# mongo --tls --tlsCAFile /var/run/mongodb/tls/ca.crt --tlsCertificateKeyFile /var/run/mongodb/tls/client.pem admin --host localhost --authenticationMechanism MONGODB-X509 --authenticationDatabase='$external' -u "CN=root,O=kubedb" --quiet +Welcome to the MongoDB shell. +For interactive help, type "help". +For more comprehensive documentation, see + http://docs.mongodb.org/ +Questions? Try the support group + http://groups.google.com/group/mongodb-user +mongos> +``` + +We are connected to the mongo shell. Let's run some command to verify the sslMode and the user, + +```bash +mongos> db.adminCommand({ getParameter:1, sslMode:1 }) +{ + "sslMode" : "requireSSL", + "ok" : 1, + "operationTime" : Timestamp(1599491398, 1), + "$clusterTime" : { + "clusterTime" : Timestamp(1599491398, 1), + "signature" : { + "hash" : BinData(0,"cn2Mhfy2blonon3jPz6Daen0nnc="), + "keyId" : NumberLong("6869760899591176209") + } + } +} +mongos> use $external +switched to db $external +mongos> show users +{ + "_id" : "$external.CN=root,O=kubedb", + "userId" : UUID("4865dda6-5e31-4b79-a085-7d6fea51c9be"), + "user" : "CN=root,O=kubedb", + "db" : "$external", + "roles" : [ + { + "role" : "root", + "db" : "admin" + } + ], + "mechanisms" : [ + "external" + ] +} +> exit +bye +``` + +You can see here that, `sslMode` is set to `requireSSL` and `clusterAuthMode` is set to `x509` and also an user is created in `$external` with name `"CN=root,O=kubedb"`. + +## Changing the SSLMode & ClusterAuthMode + +User can update `sslMode` & `ClusterAuthMode` if needed. Some changes may be invalid from mongodb end, like using `sslMode: disabled` with `clusterAuthMode: x509`. + +The good thing is, **KubeDB operator will throw error for invalid SSL specs while creating/updating the MongoDB object.** i.e., + +```bash +$ kubectl patch -n demo mg/mgo-sh-tls -p '{"spec":{"sslMode": "disabled","clusterAuthMode": "x509"}}' --type="merge" +Error from server (Forbidden): admission webhook "mongodb.validators.kubedb.com" denied the request: can't have disabled set to mongodb.spec.sslMode when mongodb.spec.clusterAuthMode is set to x509 +``` + +To **update from Keyfile Authentication to x.509 Authentication**, change the `sslMode` and `clusterAuthMode` in recommended sequence as suggested in [official documentation](https://docs.mongodb.com/manual/tutorial/update-keyfile-to-x509/). Each time after changing the specs, follow the procedure that is described above to verify the changes of `sslMode` and `clusterAuthMode` inside the database. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete mongodb -n demo mongo-sh-tls +kubectl delete issuer -n demo mongo-ca-issuer +kubectl delete ns demo +``` + +## Next Steps + +- Detail concepts of [MongoDB object](/docs/guides/mongodb/concepts/mongodb.md). +- [Backup and Restore](/docs/guides/mongodb/backup/overview/index.md) MongoDB databases using Stash. +- Initialize [MongoDB with Script](/docs/guides/mongodb/initialization/using-script.md). +- Monitor your MongoDB database with KubeDB using [out-of-the-box Prometheus operator](/docs/guides/mongodb/monitoring/using-prometheus-operator.md). +- Monitor your MongoDB database with KubeDB using [out-of-the-box builtin-Prometheus](/docs/guides/mongodb/monitoring/using-builtin-prometheus.md). +- Use [private Docker registry](/docs/guides/mongodb/private-registry/using-private-registry.md) to deploy MongoDB with KubeDB. +- Use [kubedb cli](/docs/guides/mongodb/cli/cli.md) to manage databases like kubectl for Kubernetes. +- Detail concepts of [MongoDB object](/docs/guides/mongodb/concepts/mongodb.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/pgpool/tls/standalone.md b/docs/guides/pgpool/tls/standalone.md new file mode 100644 index 0000000000..d5dd367ba8 --- /dev/null +++ b/docs/guides/pgpool/tls/standalone.md @@ -0,0 +1,245 @@ +--- +title: MongoDB Standalone TLS/SSL Encryption +menu: + docs_{{ .version }}: + identifier: mg-tls-standalone + name: Standalone + parent: mg-tls + weight: 20 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Run MongoDB with TLS/SSL (Transport Encryption) + +KubeDB supports providing TLS/SSL encryption (via, `sslMode` and `clusterAuthMode`) for MongoDB. This tutorial will show you how to use KubeDB to run a MongoDB database with TLS/SSL encryption. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Install [`cert-manger`](https://cert-manager.io/docs/installation/) v1.0.0 or later to your cluster to manage your SSL/TLS certificates. + +- Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). + +- To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + + ```bash + $ kubectl create ns demo + namespace/demo created + ``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/mongodb](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/mongodb) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Overview + +KubeDB uses following crd fields to enable SSL/TLS encryption in Mongodb. + +- `spec:` + - `sslMode` + - `tls:` + - `issuerRef` + - `certificate` + - `clusterAuthMode` + +Read about the fields in details in [mongodb concept](/docs/guides/mongodb/concepts/mongodb.md), + +`sslMode`, and `tls` is applicable for all types of MongoDB (i.e., `standalone`, `replicaset` and `sharding`), while `clusterAuthMode` provides [ClusterAuthMode](https://docs.mongodb.com/manual/reference/program/mongod/#cmdoption-mongod-clusterauthmode) for MongoDB clusters (i.e., `replicaset` and `sharding`). + +When, SSLMode is anything other than `disabled`, users must specify the `tls.issuerRef` field. KubeDB uses the `issuer` or `clusterIssuer` referenced in the `tls.issuerRef` field, and the certificate specs provided in `tls.certificate` to generate certificate secrets. These certificate secrets are then used to generate required certificates including `ca.crt`, `mongo.pem` and `client.pem`. + +The subject of `client.pem` certificate is added as `root` user in `$external` mongodb database. So, user can use this client certificate for `MONGODB-X509` `authenticationMechanism`. + +## Create Issuer/ ClusterIssuer + +We are going to create an example `Issuer` that will be used throughout the duration of this tutorial to enable SSL/TLS in MongoDB. Alternatively, you can follow this [cert-manager tutorial](https://cert-manager.io/docs/configuration/ca/) to create your own `Issuer`. + +- Start off by generating you ca certificates using openssl. + +```bash +openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ca.key -out ./ca.crt -subj "/CN=mongo/O=kubedb" +``` + +- Now create a ca-secret using the certificate files you have just generated. + +```bash +kubectl create secret tls mongo-ca \ + --cert=ca.crt \ + --key=ca.key \ + --namespace=demo +``` + +Now, create an `Issuer` using the `ca-secret` you have just created. The `YAML` file looks like this: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: mongo-ca-issuer + namespace: demo +spec: + ca: + secretName: mongo-ca +``` + +Apply the `YAML` file: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mongodb/tls/issuer.yaml +issuer.cert-manager.io/mongo-ca-issuer created +``` + +## TLS/SSL encryption in MongoDB Standalone + +Below is the YAML for MongoDB Standalone. Here, [`spec.sslMode`](/docs/guides/mongodb/concepts/mongodb.md#specsslMode) specifies `sslMode` for `standalone` (which is `requireSSL`). + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: MongoDB +metadata: + name: mgo-tls + namespace: demo +spec: + version: "4.4.26" + sslMode: requireSSL + tls: + issuerRef: + apiGroup: "cert-manager.io" + kind: Issuer + name: mongo-ca-issuer + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi +``` + +### Deploy MongoDB Standalone + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mongodb/tls/mg-standalone-ssl.yaml +mongodb.kubedb.com/mgo-tls created +``` + +Now, wait until `mgo-tls created` has status `Ready`. i.e, + +```bash +$ watch kubectl get mg -n demo +Every 2.0s: kubectl get mongodb -n demo +NAME VERSION STATUS AGE +mgo-tls 4.4.26 Ready 14s +``` + +### Verify TLS/SSL in MongoDB Standalone + +Now, connect to this database through [mongo-shell](https://docs.mongodb.com/v4.0/mongo/) and verify if `SSLMode` has been set up as intended (i.e, `requireSSL`). + +```bash +$ kubectl describe secret -n demo mgo-tls-client-cert +Name: mgo-tls-client-cert +Namespace: demo +Labels: +Annotations: cert-manager.io/alt-names: + cert-manager.io/certificate-name: mgo-tls-client-cert + cert-manager.io/common-name: root + cert-manager.io/ip-sans: + cert-manager.io/issuer-group: cert-manager.io + cert-manager.io/issuer-kind: Issuer + cert-manager.io/issuer-name: mongo-ca-issuer + cert-manager.io/uri-sans: + +Type: kubernetes.io/tls + +Data +==== +tls.crt: 1172 bytes +tls.key: 1679 bytes +ca.crt: 1147 bytes +``` + +Now, Let's exec into a mongodb container and find out the username to connect in a mongo shell, + +```bash +$ kubectl exec -it mgo-tls-0 -n demo bash +mongodb@mgo-tls-0:/$ ls /var/run/mongodb/tls +ca.crt client.pem mongo.pem +mongodb@mgo-tls-0:/$ openssl x509 -in /var/run/mongodb/tls/client.pem -inform PEM -subject -nameopt RFC2253 -noout +subject=CN=root,O=kubedb +``` + +Now, we can connect using `CN=root,O=kubedb` as root to connect to the mongo shell, + +```bash +mongodb@mgo-tls-0:/$ mongo --tls --tlsCAFile /var/run/mongodb/tls/ca.crt --tlsCertificateKeyFile /var/run/mongodb/tls/client.pem admin --host localhost --authenticationMechanism MONGODB-X509 --authenticationDatabase='$external' -u "CN=root,O=kubedb" --quiet +> +``` + +We are connected to the mongo shell. Let's run some command to verify the sslMode and the user, + +```bash +> db.adminCommand({ getParameter:1, sslMode:1 }) +{ "sslMode" : "requireSSL", "ok" : 1 } + +> use $external +switched to db $external + +> show users +{ + "_id" : "$external.CN=root,O=kubedb", + "userId" : UUID("d2ddf121-9398-400b-b477-0e8bcdd47746"), + "user" : "CN=root,O=kubedb", + "db" : "$external", + "roles" : [ + { + "role" : "root", + "db" : "admin" + } + ], + "mechanisms" : [ + "external" + ] +} +> exit +bye +``` + +You can see here that, `sslMode` is set to `requireSSL` and a user is created in `$external` with name `"CN=root,O=kubedb"`. + +## Changing the SSLMode & ClusterAuthMode + +User can update `sslMode` & `ClusterAuthMode` if needed. Some changes may be invalid from mongodb end, like using `sslMode: disabled` with `clusterAuthMode: x509`. + +The good thing is, **KubeDB operator will throw error for invalid SSL specs while creating/updating the MongoDB object.** i.e., + +```bash +$ kubectl patch -n demo mg/mgo-tls -p '{"spec":{"sslMode": "disabled","clusterAuthMode": "x509"}}' --type="merge" +Error from server (Forbidden): admission webhook "mongodb.validators.kubedb.com" denied the request: can't have disabled set to mongodb.spec.sslMode when mongodb.spec.clusterAuthMode is set to x509 +``` + +To **update from Keyfile Authentication to x.509 Authentication**, change the `sslMode` and `clusterAuthMode` in recommended sequence as suggested in [official documentation](https://docs.mongodb.com/manual/tutorial/update-keyfile-to-x509/). Each time after changing the specs, follow the procedure that is described above to verify the changes of `sslMode` and `clusterAuthMode` inside the database. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete mongodb -n demo mgo-tls +kubectl delete issuer -n demo mongo-ca-issuer +kubectl delete ns demo +``` + +## Next Steps + +- Detail concepts of [MongoDB object](/docs/guides/mongodb/concepts/mongodb.md). +- [Backup and Restore](/docs/guides/mongodb/backup/overview/index.md) MongoDB databases using Stash. +- Initialize [MongoDB with Script](/docs/guides/mongodb/initialization/using-script.md). +- Monitor your MongoDB database with KubeDB using [out-of-the-box Prometheus operator](/docs/guides/mongodb/monitoring/using-prometheus-operator.md). +- Monitor your MongoDB database with KubeDB using [out-of-the-box builtin-Prometheus](/docs/guides/mongodb/monitoring/using-builtin-prometheus.md). +- Use [private Docker registry](/docs/guides/mongodb/private-registry/using-private-registry.md) to deploy MongoDB with KubeDB. +- Use [kubedb cli](/docs/guides/mongodb/cli/cli.md) to manage databases like kubectl for Kubernetes. +- Detail concepts of [MongoDB object](/docs/guides/mongodb/concepts/mongodb.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/images/day-2-operation/pgpool/pp-tls.svg b/docs/images/day-2-operation/pgpool/pp-tls.svg new file mode 100644 index 0000000000..f238b998af --- /dev/null +++ b/docs/images/day-2-operation/pgpool/pp-tls.svg @@ -0,0 +1,4 @@ + + + +            Enterprise            Operator              Community            Operator
service
se...
secret
se...
tls-secret
tls-secret
Cert- manager
Cert- ma...
PetSet
Statef...
Issuer/Cluster Issuer
Issuer...
Pgpool
Pgpool
Certificates
Certif...
User
User
2.Create
2.Create
1.Create
1.Create
5a.Watch
5a.Watch
3.Watch
3.Watch
4.Create
4.Create
5c.Watch
5c.Watch
6.Create
6.Create
7.Watch
7.Watch
uses
uses
8.Create
8.Create
9.Watch
9.Watch
10.Create
10.Create
5b.Watch
5b.Watch
refers to
refers toText is not SVG - cannot display \ No newline at end of file