diff --git a/docs/concepts/catalog/mongodb.md b/docs/concepts/catalog/mongodb.md index 8ae30f9129..3f1227df1b 100644 --- a/docs/concepts/catalog/mongodb.md +++ b/docs/concepts/catalog/mongodb.md @@ -51,7 +51,7 @@ spec: We follow this convention for naming MongoDBVersion crd: -- Name format: `{Original PosgreSQL image verion}-{modification tag}` +- Name format: `{Original MongoDB image verion}-{modification tag}` We modify original MongoDB docker image to support MongoDB clustering and re-tag the image with v1, v2 etc. modification tag. An image with higher modification tag will have more feature than the images with lower modification tag. Hence, it is recommended to use MongoDBVersion crd with highest modification tag to enjoy the latest features. diff --git a/docs/concepts/catalog/redis.md b/docs/concepts/catalog/redis.md index 894edec65f..b273ff0c4b 100644 --- a/docs/concepts/catalog/redis.md +++ b/docs/concepts/catalog/redis.md @@ -47,7 +47,7 @@ spec: We follow this convention for naming RedisVersion crd: -- Name format: `{Original PosgreSQL image verion}-{modification tag}` +- Name format: `{Original Redis image verion}-{modification tag}` We modify original Redis docker image to support Redis clustering and re-tag the image with v1, v2 etc. modification tag. An image with higher modification tag will have more feature than the images with lower modification tag. Hence, it is recommended to use RedisVersion crd with highest modification tag to enjoy the latest features. diff --git a/docs/concepts/databases/elasticsearch.md b/docs/concepts/databases/elasticsearch.md index 8064c86ef3..e8fd746105 100644 --- a/docs/concepts/databases/elasticsearch.md +++ b/docs/concepts/databases/elasticsearch.md @@ -31,6 +31,7 @@ metadata: spec: version: "6.3-v1" replicas: 2 + maxUnavailable: 0 authPlugin: "SearchGuard" enableSSL: true certificateSecret: @@ -72,6 +73,7 @@ spec: annotations: passMe: ToStatefulSet spec: + serviceAccountName: my-service-account schedulerName: my-scheduler nodeSelector: disktype: ssd @@ -103,7 +105,7 @@ spec: ### spec.version -`spec.version` is a required field that specifies the name of the [ElasticsearchVersion](/docs/concepts/catalog/elasticsearch.md) crd where the docker images are specified. Currently, when you install KubeDB, it creates the following `ElasticsearchVersion` crd, +`spec.version` is a required field that specifies the name of the [ElasticsearchVersion](/docs/concepts/catalog/elasticsearch.md) crd where the docker images are specified. Currently, when you install KubeDB, it creates the following `ElasticsearchVersion` crds, - `5.6`, `5.6-v1`, `5.6.4`, `5.6.4-v1` - `6.2`, `6.2-v1`, `6.2.4`, `6.2.4-v1`, `6.3`, `6.3-v1`, `6.3.0`, `6.3.0-v1` @@ -119,16 +121,25 @@ You can specify the following things in `spec.topology` field, - `.prefix` is an optional field to be used as the prefix of StatefulSet name. - `.storage` is an optional field that specifies how much storage to use for `master` node. - `.resources` is an optional field that specifies how much compute resources to request for `master` node. + - `.maxUnavailable` is an optional field that specifies the exact number of pods that can be safely evicted before pod disruption budget kicks in. +KubeDB uses Pod Disruption Budget to ensure that desired number of replicas are available during [voluntary disruptions](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/#voluntary-and-involuntary-disruptions) so that no data loss is occurred. Users need to fill up `spec.topology.master.maxUnavailable` field to specify the exact number of replicas that can be evicted before pod disruption budget kicks in. + - `spec.topology.data` - `.replicas` is an optional field to specify how many pods we want as `data` node. If not set, this defaults to 1. - `.prefix` is an optional field to be used as the prefix of StatefulSet name. - `.storage` is an optional field that specifies how much storage to use for `data` node. - `.resources` is an optional field that specifies how much compute resources to request for `data` node. + - `.maxUnavailable` is an optional field that specifies the exact number of pods that can be safely evicted before pod disruption budget kicks in. +KubeDB uses Pod Disruption Budget to ensure that desired number of replicas are available during [voluntary disruptions](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/#voluntary-and-involuntary-disruptions) so that no data loss is occurred. Users need to fill up `spec.topology.data.maxUnavailable` field to specify the exact number of replicas that can be evicted before pod disruption budget kicks in. + - `spec.topology.client` - `.replicas` is an optional field to specify how many pods we want as `client` node. If not set, this defaults to 1. - `.prefix` is an optional field to be used as the prefix of StatefulSet name. - `.storage` is an optional field that specifies how much storage to use for `client` node. - `.resources` is an optional field that specifies how much compute resources to request for `client` node. + - `.maxUnavailable` is an optional field that specifies the exact number of pods that can be safely evicted before pod disruption budget kicks in. +KubeDB uses Pod Disruption Budget to ensure that desired number of replicas are available during [voluntary disruptions](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/#voluntary-and-involuntary-disruptions) so that no data loss is occurred. Users need to fill up `spec.topology.client.maxUnavailable` field to specify the exact number of replicas that can be evicted before pod disruption budget kicks in. + > Note: Any two of them can't have the same prefix. @@ -200,11 +211,16 @@ If you specify `spec.topology` field then you are not allowed to specify followi ### spec.replicas `spec.replicas` is an optional field that can be used if `spec.topology` is not specified. This field specifies the number of pods in the Elasticsearch cluster. The default value of this field is 1. +KubeDB uses Pod Disruption Budget to ensure that desired number of replicas are available during [voluntary disruptions](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/#voluntary-and-involuntary-disruptions) so that no data loss is occurred. Users need to fill up `spec.maxUnavailable` field to specify the exact number of replicas that can be evicted before pod disruption budget kicks in. ### spec.authPlugin `spec.authPlugin` is an optional field that specifies which plugin to use for authentication. Currently, this field accepts `None` or `SearchGuard`. By default, KubeDB uses [Search Guard](https://github.com/floragunncom/search-guard) for authentication. If you specify `None` in this field, KubeDB will disable Search Guard plugin and your database will not be protected anymore. +### spec.maxUnavailable + +`spec.maxUnavailable` is an optional field that is used to specify the exact number of cluster replicas that can be safely evicted before pod disruption budget kicks in to prevent unwanted data loss. + ### spec.enableSSL `spec.enableSSL` is an optional field that specifies whether to enable SSL for [Search Guard](https://github.com/floragunncom/search-guard). The default value of this field is `false`. @@ -241,7 +257,7 @@ Following keys are used for search-guard configuration - `sg_action_groups.yml:` define permission groups - `sg_roles.yml:` define the roles and the associated permissions -If not set, KubeDB operator creates a new Secret `{Elasticsearch name}-auth` with generated credentials and default search-guard configuration. If you want to use an existing secret, please specify that when creating Elasticsearch using `spec.databaseSecret.secretName`. +If not set, KubeDB operator creates a new Secret `{Elasticsearch name}-auth` with generated credentials and default search-guard configuration. If you want to use an existing secret, please specify that when creating Elasticsearch using `spec.databaseSecret.secretName`. Secrets provided by users are not managed by KubeDB, and therefore, won't be modified or garbage collected by the KubeDB operator (version 0.13.0 and higher). ### spec.storageType @@ -342,6 +358,7 @@ KubeDB accept following fields to set in `spec.podTemplate:` - imagePullSecrets - nodeSelector - affinity + - serviceAccountName - schedulerName - tolerations - priorityClassName @@ -420,6 +437,16 @@ At least one of the following was changed: `spec.podTemplate.spec.nodeSelector` is an optional field that specifies a map of key-value pairs. For the pod to be eligible to run on a node, the node must have each of the indicated key-value pairs as labels (it can have additional labels as well). To learn more, see [here](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector) . +#### spec.podTemplate.spec.serviceAccountName + + `serviceAccountName` is an optional field supported by KubeDB Operator (version 0.13.0 and higher) that can be used to specify a custom service account to fine tune role based access control. + + If this field is left empty, the KubeDB operator will create a service account name matching Elasticsearch crd name. Role and RoleBinding that provide necessary access permissions will also be generated automatically for this service account. + + If a service account name is given, but there's no existing service account by that name, the KubeDB operator will create one, and Role and RoleBinding that provide necessary access permissions will also be generated for this service account. + + If a service account name is given, and there's an existing service account by that name, the KubeDB operator will use that existing service account. Since this service account is not managed by KubeDB, users are responsible for providing necessary access permissions manually. Follow the guide [here](/docs/guides/elasticsearch/custom-rbac/using-custom-rbac.md) to grant necessary permissions in this scenario. + #### spec.podTemplate.spec.resources `spec.podTemplate.spec.resources` is an optional field. If you didn't specify `spec.topology` field then this can be used to request compute resources required by the database pods. To learn more, visit [here](http://kubernetes.io/docs/user-guide/compute-resources/). diff --git a/docs/concepts/databases/memcached.md b/docs/concepts/databases/memcached.md index 7b22cb96fc..4e506de3b4 100644 --- a/docs/concepts/databases/memcached.md +++ b/docs/concepts/databases/memcached.md @@ -48,6 +48,7 @@ spec: annotations: passMe: ToDeployment spec: + serviceAccountName: my-service-account schedulerName: my-scheduler nodeSelector: disktype: ssd @@ -83,6 +84,8 @@ spec: `spec.replicas` is an optional field that specifies the number of desired Instances/Replicas of Memcached server. If you do not specify .spec.replicas, then it defaults to 1. +KubeDB uses Pod Disruption Budget to ensure that majority of these replicas are available during [voluntary disruptions](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/#voluntary-and-involuntary-disruptions) so that quorum is maintained. + ### spec.version `spec.version` is a required field specifying the name of the [MemcachedVersion](/docs/concepts/catalog/memcached.md) crd where the docker images are specified. Currently, when you install KubeDB, it creates the following `MemcachedVersion` crd, @@ -118,6 +121,7 @@ KubeDB accept following fields to set in `spec.podTemplate:` - imagePullSecrets - nodeSelector - affinity + - serviceAccountName - schedulerName - tolerations - priorityClassName @@ -161,6 +165,16 @@ At least one of the following was changed: `spec.nodeSelector` is an optional field that specifies a map of key-value pairs. For the pod to be eligible to run on a node, the node must have each of the indicated key-value pairs as labels (it can have additional labels as well). To learn more, see [here](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector) . +#### spec.podTemplate.spec.serviceAccountName + + `serviceAccountName` is an optional field supported by KubeDB Operator (version 0.13.0 and higher) that can be used to specify a custom service account to fine tune role based access control. + + If this field is left empty, the KubeDB operator will create a service account name matching Memcached crd name. Role and RoleBinding that provide necessary access permissions will also be generated automatically for this service account. + + If a service account name is given, but there's no existing service account by that name, the KubeDB operator will create one, and Role and RoleBinding that provide necessary access permissions will also be generated for this service account. + + If a service account name is given, and there's an existing service account by that name, the KubeDB operator will use that existing service account. Since this service account is not managed by KubeDB, users are responsible for providing necessary access permissions manually. Follow the guide [here](/docs/guides/memcached/custom-rbac/using-custom-rbac.md) to grant necessary permissions in this scenario. + #### spec.podTemplate.spec.resources `spec.resources` is an optional field. This can be used to request compute resources required by the database pods. To learn more, visit [here](http://kubernetes.io/docs/user-guide/compute-resources/). diff --git a/docs/concepts/databases/mongodb.md b/docs/concepts/databases/mongodb.md index 00ff5196ed..d067ec63a1 100644 --- a/docs/concepts/databases/mongodb.md +++ b/docs/concepts/databases/mongodb.md @@ -99,6 +99,7 @@ spec: annotations: passMe: ToStatefulSet spec: + serviceAccountName: my-service-account schedulerName: my-scheduler nodeSelector: disktype: ssd @@ -132,7 +133,7 @@ spec: ### spec.version -`spec.version` is a required field specifying the name of the [MongoDBVersion](/docs/concepts/catalog/mongodb.md) crd where the docker images are specified. Currently, when you install KubeDB, it creates the following `MongoDBVersion` crd, +`spec.version` is a required field specifying the name of the [MongoDBVersion](/docs/concepts/catalog/mongodb.md) crd where the docker images are specified. Currently, when you install KubeDB, it creates the following `MongoDBVersion` crds, - `3.4-v4`, `3.4-v3`, `3.4-v2`, `3.4-v1`, `3.4` - `3.6-v4`, `3.6-v3`, `3.6-v2`, `3.6-v1`, `3.6` @@ -147,6 +148,8 @@ If `spec.shardTopology` is set, then `spec.replicas` needs to be empty. Instead If both `spec.replicaset` and `spec.shardTopology` is not set, then `spec.replicas` can be value `1`. +KubeDB uses Pod Disruption Budget to ensure that majority of these replicas are available during [voluntary disruptions](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/#voluntary-and-involuntary-disruptions) so that quorum is maintained. + ### spec.databaseSecret `spec.databaseSecret` is an optional field that points to a Secret used to hold credentials for `mongodb` superuser. If not set, KubeDB operator creates a new Secret `{mongodb-object-name}-auth` for storing the password for `mongodb` superuser for each MongoDB object. If you want to use an existing secret please specify that when creating the MongoDB object using `spec.databaseSecret.secretName`. @@ -175,6 +178,7 @@ metadata: ... type: Opaque ``` +Secrets provided by users are not managed by KubeDB, and therefore, won't be modified or garbage collected by the KubeDB operator (version 0.13.0 and higher). ### spec.certificateSecret @@ -239,6 +243,7 @@ When `spec.shardTopology` is set, the following fields needs to be empty, otherw - `spec.configSource` - `spec.storage` +KubeDB uses Pod Disruption Budget to ensure that majority of the replicas of these shard components are available during [voluntary disruptions](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/#voluntary-and-involuntary-disruptions) so that quorum and data integrity is maintained. #### spec.shardTopology.shard `shard` represents configuration for Shard component of mongodb. @@ -435,6 +440,7 @@ KubeDB accept following fields to set in `spec.podTemplate:` - imagePullSecrets - nodeSelector - affinity + - serviceAccountName - schedulerName - tolerations - priorityClassName @@ -492,6 +498,16 @@ for: "./mongodb.yaml": admission webhook "mongodb.validators.kubedb.com" denied `spec.podTemplate.spec.nodeSelector` is an optional field that specifies a map of key-value pairs. For the pod to be eligible to run on a node, the node must have each of the indicated key-value pairs as labels (it can have additional labels as well). To learn more, see [here](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector) . +#### spec.podTemplate.spec.serviceAccountName + + `serviceAccountName` is an optional field supported by KubeDB Operator (version 0.13.0 and higher) that can be used to specify a custom service account to fine tune role based access control. + + If this field is left empty, the KubeDB operator will create a service account name matching MongoDB crd name. Role and RoleBinding that provide necessary access permissions will also be generated automatically for this service account. + + If a service account name is given, but there's no existing service account by that name, the KubeDB operator will create one, and Role and RoleBinding that provide necessary access permissions will also be generated for this service account. + + If a service account name is given, and there's an existing service account by that name, the KubeDB operator will use that existing service account. Since this service account is not managed by KubeDB, users are responsible for providing necessary access permissions manually. Follow the guide [here](/docs/guides/mongodb/custom-rbac/using-custom-rbac.md) to grant necessary permissions in this scenario. + #### spec.podTemplate.spec.resources `spec.podTemplate.spec.resources` is an optional field. This can be used to request compute resources required by the database pods. To learn more, visit [here](http://kubernetes.io/docs/user-guide/compute-resources/). diff --git a/docs/concepts/databases/mysql.md b/docs/concepts/databases/mysql.md index a9efcbb683..a6f24b0c22 100644 --- a/docs/concepts/databases/mysql.md +++ b/docs/concepts/databases/mysql.md @@ -72,6 +72,7 @@ spec: annotations: passMe: ToStatefulSet spec: + serviceAccountName: my-service-account schedulerName: my-scheduler nodeSelector: disktype: ssd @@ -105,14 +106,14 @@ spec: ### spec.version -`spec.version` is a required field specifying the name of the [MySQLVersion](/docs/concepts/catalog/mysql.md) crd where the docker images are specified. Currently, when you install KubeDB, it creates the following `MySQLVersion` crd, +`spec.version` is a required field specifying the name of the [MySQLVersion](/docs/concepts/catalog/mysql.md) crd where the docker images are specified. Currently, when you install KubeDB, it creates the following `MySQLVersion` crds, - `8.0.14`, `8.0.3`, `8.0-v2`, `8.0-v1`, `8.0`, `8-v1`, `8` - `5.7.25`, `5.7-v2`, `5.7-v1`, `5.7`, `5-v1`, `5` ### spec.topology -`spec.topology` is an optional field that provides a way to configure HA, fault-tolerant MySQL cluster. This field enables you to specify the clustering mode. Currently, we support only MySQL Group Replication. +`spec.topology` is an optional field that provides a way to configure HA, fault-tolerant MySQL cluster. This field enables you to specify the clustering mode. Currently, we support only MySQL Group Replication. KubeDB uses Pod Disruption Budget to ensure that majority of the group replicas are available during [voluntary disruptions](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/#voluntary-and-involuntary-disruptions) so that quorum is maintained and no data loss is occurred. You can specify the following fields in `spec.topology` field, @@ -129,6 +130,8 @@ You can specify the following fields in `spec.topology` field, This secret contains a `user` key and a `password` key which contains the `username` and `password` respectively for `mysql` root user. Here, the value of `user` key is fixed to be `root`. +Secrets provided by users are not managed by KubeDB, and therefore, won't be modified or garbage collected by the KubeDB operator (version 0.13.0 and higher). + Example: ```console @@ -172,8 +175,8 @@ To learn how to configure `spec.storage`, please visit the links below: `spec.init` is an optional section that can be used to initialize a newly created MySQL database. MySQL databases can be initialized in one of two ways: - 1. Initialize from Script - 2. Initialize from Snapshot + 1. Initialize from Script + 2. Initialize from Snapshot #### Initialize via Script @@ -283,6 +286,7 @@ KubeDB accept following fields to set in `spec.podTemplate:` - imagePullSecrets - nodeSelector - affinity + - serviceAccountName - schedulerName - tolerations - priorityClassName @@ -337,6 +341,16 @@ for: "./mysql.yaml": admission webhook "mysql.validators.kubedb.com" denied the `spec.podTemplate.spec.nodeSelector` is an optional field that specifies a map of key-value pairs. For the pod to be eligible to run on a node, the node must have each of the indicated key-value pairs as labels (it can have additional labels as well). To learn more, see [here](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector) . +#### spec.podTemplate.spec.serviceAccountName + + `serviceAccountName` is an optional field supported by KubeDB Operator (version 0.13.0 and higher) that can be used to specify a custom service account to fine tune role based access control. + + If this field is left empty, the KubeDB operator will create a service account name matching MySQL crd name. Role and RoleBinding that provide necessary access permissions will also be generated automatically for this service account. + + If a service account name is given, but there's no existing service account by that name, the KubeDB operator will create one, and Role and RoleBinding that provide necessary access permissions will also be generated for this service account. + + If a service account name is given, and there's an existing service account by that name, the KubeDB operator will use that existing service account. Since this service account is not managed by KubeDB, users are responsible for providing necessary access permissions manually. Follow the guide [here](/docs/guides/mysql/custom-rbac/using-custom-rbac.md) to grant necessary permissions in this scenario. + #### spec.podTemplate.spec.resources `spec.podTemplate.spec.resources` is an optional field. This can be used to request compute resources required by the database pods. To learn more, visit [here](http://kubernetes.io/docs/user-guide/compute-resources/). diff --git a/docs/concepts/databases/redis.md b/docs/concepts/databases/redis.md index 292412dabc..d5d03c1e3e 100644 --- a/docs/concepts/databases/redis.md +++ b/docs/concepts/databases/redis.md @@ -58,6 +58,7 @@ spec: annotations: passMe: ToStatefulSet spec: + serviceAccountName: my-service-account schedulerName: my-scheduler nodeSelector: disktype: ssd @@ -91,7 +92,7 @@ spec: ### spec.version -`spec.version` is a required field specifying the name of the [RedisVersion](/docs/concepts/catalog/redis.md) crd where the docker images are specified. Currently, when you install KubeDB, it creates the following `RedisVersion` crd, +`spec.version` is a required field specifying the name of the [RedisVersion](/docs/concepts/catalog/redis.md) crd where the docker images are specified. Currently, when you install KubeDB, it creates the following `RedisVersion` crds, - `4.0.11`, `4.0.6-v2`, `4.0.6-v1`, `4.0.6`, `4.0-v2`, `4.0-v1`, `4.0`, `4-v1`, `4`, `5.0.3-v1`, `5.0.3`, `5.0-v1`, `5.0` @@ -110,6 +111,8 @@ If `spec.mode` is set to `"Cluster"`, users can optionally provide a cluster spe - `spec.cluster.master`: specifies the number of Redis master nodes. It must be greater or equal to 3. If not set, the operator set it to 3. - `spec.cluster.replicas`: specifies the number of replica nodes per master. It must be greater than 0. If not set, the operator set it to 1. +KubeDB uses Pod Disruption Budget to ensure that majority of these cluster replicas are available during [voluntary disruptions](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/#voluntary-and-involuntary-disruptions) so that quorum is maintained and no data loss is occurred. + > If `spec.mode` is set to `"Cluster"`, then `spec.replicas` field is ignored. ### spec.storage @@ -153,6 +156,7 @@ KubeDB accept following fields to set in `spec.podTemplate:` - imagePullSecrets - nodeSelector - affinity + - serviceAccountName - schedulerName - tolerations - priorityClassName @@ -196,6 +200,16 @@ spec.podTemplate.spec.env `spec.podTemplate.spec.nodeSelector` is an optional field that specifies a map of key-value pairs. For the pod to be eligible to run on a node, the node must have each of the indicated key-value pairs as labels (it can have additional labels as well). To learn more, see [here](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector) . +#### spec.podTemplate.spec.serviceAccountName + + `serviceAccountName` is an optional field supported by KubeDB Operator (version 0.13.0 and higher) that can be used to specify a custom service account to fine tune role based access control. + + If this field is left empty, the KubeDB operator will create a service account name matching Redis crd name. Role and RoleBinding that provide necessary access permissions will also be generated automatically for this service account. + + If a service account name is given, but there's no existing service account by that name, the KubeDB operator will create one, and Role and RoleBinding that provide necessary access permissions will also be generated for this service account. + + If a service account name is given, and there's an existing service account by that name, the KubeDB operator will use that existing service account. Since this service account is not managed by KubeDB, users are responsible for providing necessary access permissions manually. Follow the guide [here](/docs/guides/redis/custom-rbac/using-custom-rbac.md) to grant necessary permissions in this scenario. + #### spec.podTemplate.spec.resources `spec.podTemplate.spec.resources` is an optional field. This can be used to request compute resources required by the database pods. To learn more, visit [here](http://kubernetes.io/docs/user-guide/compute-resources/). diff --git a/docs/examples/elasticsearch/custom-rbac/es-custom-db-two.yaml b/docs/examples/elasticsearch/custom-rbac/es-custom-db-two.yaml new file mode 100644 index 0000000000..3ced874c45 --- /dev/null +++ b/docs/examples/elasticsearch/custom-rbac/es-custom-db-two.yaml @@ -0,0 +1,19 @@ +apiVersion: kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: minute-elasticsearch + namespace: demo +spec: + version: "8.0-v2" + storageType: Durable + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: DoNotTerminate diff --git a/docs/examples/elasticsearch/custom-rbac/es-custom-db.yaml b/docs/examples/elasticsearch/custom-rbac/es-custom-db.yaml new file mode 100644 index 0000000000..95a4cd18d5 --- /dev/null +++ b/docs/examples/elasticsearch/custom-rbac/es-custom-db.yaml @@ -0,0 +1,19 @@ +apiVersion: kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: quick-elasticsearch + namespace: demo +spec: + version: "8.0-v2" + storageType: Durable + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: DoNotTerminate diff --git a/docs/examples/elasticsearch/custom-rbac/es-custom-role.yaml b/docs/examples/elasticsearch/custom-rbac/es-custom-role.yaml new file mode 100644 index 0000000000..0291e50440 --- /dev/null +++ b/docs/examples/elasticsearch/custom-rbac/es-custom-role.yaml @@ -0,0 +1,14 @@ +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: my-custom-role + namespace: demo +rules: + - apiGroups: + - policy + resourceNames: + - elasticsearch-db + resources: + - podsecuritypolicies + verbs: + - use diff --git a/docs/examples/memcached/custom-rbac/mc-custom-db-two.yaml b/docs/examples/memcached/custom-rbac/mc-custom-db-two.yaml new file mode 100644 index 0000000000..6c14755dc4 --- /dev/null +++ b/docs/examples/memcached/custom-rbac/mc-custom-db-two.yaml @@ -0,0 +1,19 @@ +apiVersion: kubedb.com/v1alpha1 +kind: Memcached +metadata: + name: minute-memcached + namespace: demo +spec: + replicas: 3 + version: "1.5.4-v1" + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + resources: + limits: + cpu: 500m + memory: 128Mi + requests: + cpu: 250m + memory: 64Mi + terminationPolicy: DoNotTerminate diff --git a/docs/examples/memcached/custom-rbac/mc-custom-db.yaml b/docs/examples/memcached/custom-rbac/mc-custom-db.yaml new file mode 100644 index 0000000000..47096eee79 --- /dev/null +++ b/docs/examples/memcached/custom-rbac/mc-custom-db.yaml @@ -0,0 +1,19 @@ +apiVersion: kubedb.com/v1alpha1 +kind: Memcached +metadata: + name: quick-memcached + namespace: demo +spec: + replicas: 3 + version: "1.5.4-v1" + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + resources: + limits: + cpu: 500m + memory: 128Mi + requests: + cpu: 250m + memory: 64Mi + terminationPolicy: DoNotTerminate diff --git a/docs/examples/memcached/custom-rbac/mc-custom-role.yaml b/docs/examples/memcached/custom-rbac/mc-custom-role.yaml new file mode 100644 index 0000000000..a5b7ed6c45 --- /dev/null +++ b/docs/examples/memcached/custom-rbac/mc-custom-role.yaml @@ -0,0 +1,14 @@ +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: my-custom-role + namespace: demo +rules: + - apiGroups: + - policy + resourceNames: + - memcached-db + resources: + - podsecuritypolicies + verbs: + - use diff --git a/docs/examples/mongodb/custom-rbac/mg-custom-db-two.yaml b/docs/examples/mongodb/custom-rbac/mg-custom-db-two.yaml new file mode 100644 index 0000000000..da8383c0be --- /dev/null +++ b/docs/examples/mongodb/custom-rbac/mg-custom-db-two.yaml @@ -0,0 +1,19 @@ +apiVersion: kubedb.com/v1alpha1 +kind: MongoDB +metadata: + name: minute-mongodb + namespace: demo +spec: + version: "3.4-v3" + storageType: Durable + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: DoNotTerminate diff --git a/docs/examples/mongodb/custom-rbac/mg-custom-db.yaml b/docs/examples/mongodb/custom-rbac/mg-custom-db.yaml new file mode 100644 index 0000000000..3e8747285f --- /dev/null +++ b/docs/examples/mongodb/custom-rbac/mg-custom-db.yaml @@ -0,0 +1,19 @@ +apiVersion: kubedb.com/v1alpha1 +kind: MongoDB +metadata: + name: quick-mongodb + namespace: demo +spec: + version: "3.4-v3" + storageType: Durable + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: DoNotTerminate diff --git a/docs/examples/mongodb/custom-rbac/mg-custom-role.yaml b/docs/examples/mongodb/custom-rbac/mg-custom-role.yaml new file mode 100644 index 0000000000..cea2e81796 --- /dev/null +++ b/docs/examples/mongodb/custom-rbac/mg-custom-role.yaml @@ -0,0 +1,14 @@ +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: my-custom-role + namespace: demo +rules: + - apiGroups: + - policy + resourceNames: + - mongodb-db + resources: + - podsecuritypolicies + verbs: + - use diff --git a/docs/examples/mysql/custom-rbac/my-custom-db-two.yaml b/docs/examples/mysql/custom-rbac/my-custom-db-two.yaml new file mode 100644 index 0000000000..b545a79b39 --- /dev/null +++ b/docs/examples/mysql/custom-rbac/my-custom-db-two.yaml @@ -0,0 +1,19 @@ +apiVersion: kubedb.com/v1alpha1 +kind: MySQL +metadata: + name: minute-mysql + namespace: demo +spec: + version: "8.0-v2" + storageType: Durable + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: DoNotTerminate diff --git a/docs/examples/mysql/custom-rbac/my-custom-db.yaml b/docs/examples/mysql/custom-rbac/my-custom-db.yaml new file mode 100644 index 0000000000..88c45e4f72 --- /dev/null +++ b/docs/examples/mysql/custom-rbac/my-custom-db.yaml @@ -0,0 +1,19 @@ +apiVersion: kubedb.com/v1alpha1 +kind: MySQL +metadata: + name: quick-mysql + namespace: demo +spec: + version: "8.0-v2" + storageType: Durable + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: DoNotTerminate diff --git a/docs/examples/mysql/custom-rbac/my-custom-role.yaml b/docs/examples/mysql/custom-rbac/my-custom-role.yaml new file mode 100644 index 0000000000..e9b576585d --- /dev/null +++ b/docs/examples/mysql/custom-rbac/my-custom-role.yaml @@ -0,0 +1,14 @@ +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: my-custom-role + namespace: demo +rules: + - apiGroups: + - policy + resourceNames: + - postgres-db + resources: + - podsecuritypolicies + verbs: + - use diff --git a/docs/examples/redis/custom-rbac/rd-custom-db-two.yaml b/docs/examples/redis/custom-rbac/rd-custom-db-two.yaml new file mode 100644 index 0000000000..cad47b788f --- /dev/null +++ b/docs/examples/redis/custom-rbac/rd-custom-db-two.yaml @@ -0,0 +1,19 @@ +apiVersion: kubedb.com/v1alpha1 +kind: Redis +metadata: + name: minute-redis + namespace: demo +spec: + version: "4.0-v2" + storageType: Durable + storage: + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: DoNotTerminate diff --git a/docs/examples/redis/custom-rbac/rd-custom-db.yaml b/docs/examples/redis/custom-rbac/rd-custom-db.yaml new file mode 100644 index 0000000000..f782902b11 --- /dev/null +++ b/docs/examples/redis/custom-rbac/rd-custom-db.yaml @@ -0,0 +1,19 @@ +apiVersion: kubedb.com/v1alpha1 +kind: Redis +metadata: + name: quick-redis + namespace: demo +spec: + version: "4.0-v2" + storageType: Durable + storage: + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: DoNotTerminate diff --git a/docs/examples/redis/custom-rbac/rd-custom-role.yaml b/docs/examples/redis/custom-rbac/rd-custom-role.yaml new file mode 100644 index 0000000000..7ca000becb --- /dev/null +++ b/docs/examples/redis/custom-rbac/rd-custom-role.yaml @@ -0,0 +1,14 @@ +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: my-custom-role + namespace: demo +rules: + - apiGroups: + - policy + resourceNames: + - redis-db + resources: + - podsecuritypolicies + verbs: + - use diff --git a/docs/guides/elasticsearch/custom-rbac/_index.md b/docs/guides/elasticsearch/custom-rbac/_index.md new file mode 100755 index 0000000000..f5210a0f16 --- /dev/null +++ b/docs/guides/elasticsearch/custom-rbac/_index.md @@ -0,0 +1,10 @@ +--- +title: Run Elasticsearch with Custom RBAC resources +menu: + docs_0.12.0: + identifier: es-custom-rbac + name: Custom RBAC + parent: es-elasticsearch-guides + weight: 85 +menu_name: docs_0.12.0 +--- diff --git a/docs/guides/elasticsearch/custom-rbac/using-custom-rbac.md b/docs/guides/elasticsearch/custom-rbac/using-custom-rbac.md new file mode 100644 index 0000000000..beffab8d36 --- /dev/null +++ b/docs/guides/elasticsearch/custom-rbac/using-custom-rbac.md @@ -0,0 +1,328 @@ +--- +title: Run Elasticsearch with Custom RBAC resources +menu: + docs_0.12.0: + identifier: es-custom-rbac-quickstart + name: Custom RBAC + parent: es-custom-rbac + weight: 10 +menu_name: docs_0.12.0 +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/concepts/README.md). + +# Using Custom RBAC resources + +KubeDB (version 0.13.0 and higher) supports finer user control over role based access permissions provided to a Elasticsearch instance. This tutorial will show you how to use KubeDB to run Elasticsearch instance with custom RBAC resources. + +## 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 [minikube](https://github.com/kubernetes/minikube). + +Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/install.md). + +To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + +```console +$ kubectl create ns demo +namespace/demo created +``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/elasticsearch](https://github.com/kubedb/docs/tree/0.12.0/docs/examples/elasticsearch) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Overview + +KubeDB allows users to provide custom RBAC resources, namely, `ServiceAccount`, `Role`, and `RoleBinding` for Elasticsearch. This is provided via the `spec.podTemplate.spec.serviceAccountName` field in Elasticsearch crd. If this field is left empty, the KubeDB operator will create a service account name matching Elasticsearch crd name. Role and RoleBinding that provide necessary access permissions will also be generated automatically for this service account. + +If a service account name is given, but there's no existing service account by that name, the KubeDB operator will create one, and Role and RoleBinding that provide necessary access permissions will also be generated for this service account. + +If a service account name is given, and there's an existing service account by that name, the KubeDB operator will use that existing service account. Since this service account is not managed by KubeDB, users are responsible for providing necessary access permissions manually. + +This guide will show you how to create custom `Service Account`, `Role`, and `RoleBinding` for a Elasticsearch Database named `quick-elasticsearch` to provide the bare minimum access permissions. + +## Custom RBAC for Elasticsearch + +At first, let's create a `Service Acoount` in `demo` namespace. + +```console +$ kubectl create serviceaccount -n demo my-custom-serviceaccount +serviceaccount/my-custom-serviceaccount created +``` + +It should create a service account. + +```yaml +$ kubectl get serviceaccount -n demo my-custom-serviceaccount -o yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + creationTimestamp: "2019-05-31T08:43:48Z" + name: my-custom-serviceaccount + namespace: demo + resourceVersion: "12305" + selfLink: /api/v1/namespaces/demo/serviceaccounts/my-custom-serviceaccount + uid: 35550bca-8380-11e9-8efb-08002790c45e +secrets: +- name: my-custom-serviceaccount-token-6xj8k + +``` + +Now, we need to create a role that has necessary access permissions for the Elasticsearch instance named `quick-elasticsearch`. + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/0.12.0/docs/examples/elasticsearch/custom-rbac/es-custom-role.yaml +role.rbac.authorization.k8s.io/my-custom-role created +``` + +Below is the YAML for the Role we just created. + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: my-custom-role + namespace: demo +rules: +- apiGroups: + - policy + resourceNames: + - elasticsearch-db + resources: + - podsecuritypolicies + verbs: + - use +``` + +This permission is required for Elasticsearch pods running on PSP enabled clusters. + +Now create a `RoleBinding` to bind this `Role` with the already created service account. + +```console +$ kubectl create rolebinding my-custom-rolebinding --role=my-custom-role --serviceaccount=demo:my-custom-serviceaccount --namespace=demo +rolebinding.rbac.authorization.k8s.io/my-custom-rolebinding created + +``` + +It should bind `my-custom-role` and `my-custom-serviceaccount` successfully. + +```yaml +$ kubectl get rolebinding -n demo my-custom-rolebinding -o yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + creationTimestamp: "kubectl get rolebinding -n demo my-custom-rolebinding -o yaml" + name: my-custom-rolebinding + namespace: demo + resourceVersion: "1405" + selfLink: /apis/rbac.authorization.k8s.io/v1/namespaces/demo/rolebindings/my-custom-rolebinding + uid: 123afc02-8297-11e9-8d10-080027a8b217 +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: my-custom-role +subjects: +- kind: ServiceAccount + name: my-custom-serviceaccount + namespace: demo + +``` + +Now, create a Elasticsearch crd specifying `spec.podTemplate.spec.serviceAccountName` field to `my-custom-serviceaccount`. + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/0.12.0/docs/examples/elasticsearch/custom-rbac/es-custom-db.yaml +elasticsearch.kubedb.com/quick-elasticsearch created +``` + +Below is the YAML for the Elasticsearch crd we just created. + +```yaml +apiVersion: kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: quick-elasticsearch + namespace: demo +spec: + version: "8.0-v2" + storageType: Durable + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: DoNotTerminate + +``` + +Now, wait a few minutes. the KubeDB operator will create necessary PVC, statefulset, services, secret etc. If everything goes well, we should see that a pod with the name `quick-elasticsearch-0` has been created. + +Check that the statefulset's pod is running + +```console +$ kubectl get pod -n demo quick-elasticsearch-0 +NAME READY STATUS RESTARTS AGE +quick-elasticsearch-0 1/1 Running 0 14m +``` + +Check the pod's log to see if the database is ready + +```console +$ kubectl logs -f -n demo quick-elasticsearch-0 ++ set -o errexit ++ set -o pipefail ++ sync +... +Starting runit... +.................... +.................. +Search Guard Version: 6.3.0-23.1 +Connected as CN=sgadmin,O=Elasticsearch Operator +Contacting elasticsearch cluster 'elasticsearch' and wait for YELLOW clusterstate ... +Clustername: quick-elasticsearch +Clusterstate: GREEN +Number of nodes: 3 +Number of data nodes: 3 +searchguard index does not exists, attempt to create it ... done (0-all replicas) +Populate config from /elasticsearch/plugins/search-guard-6/sgconfig/ +Will update 'sg/config' with /elasticsearch/plugins/search-guard-6/sgconfig/sg_config.yml + SUCC: Configuration for 'config' created or updated +Will update 'sg/roles' with /elasticsearch/plugins/search-guard-6/sgconfig/sg_roles.yml + SUCC: Configuration for 'roles' created or updated +Will update 'sg/rolesmapping' with /elasticsearch/plugins/search-guard-6/sgconfig/sg_roles_mapping.yml + SUCC: Configuration for 'rolesmapping' created or updated +Will update 'sg/internalusers' with /elasticsearch/plugins/search-guard-6/sgconfig/sg_internal_users.yml + SUCC: Configuration for 'internalusers' created or updated +Will update 'sg/actiongroups' with /elasticsearch/plugins/search-guard-6/sgconfig/sg_action_groups.yml + SUCC: Configuration for 'actiongroups' created or updated +[2019-05-31T09:10:31,537][INFO ][c.f.s.c.IndexBaseConfigurationRepository] Search Guard License Info: No license needed because enterprise modules are not enabled +Done with success + +``` + +Once we see `Done with success` in the log, the database is ready. + +## Reusing Service Account + +An existing service account can be reused in another Elasticsearch Database. No new access permission is required to run the new Elasticsearch Database. + +Now, create Elasticsearch crd `minute-elasticsearch` using the existing service account name `my-custom-serviceaccount` in the `spec.podTemplate.spec.serviceAccountName` field. + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/0.12.0/docs/examples/elasticsearch/custom-rbac/es-custom-db-two.yaml +elasticsearch.kubedb.com/quick-elasticsearch created +``` + +Below is the YAML for the Elasticsearch crd we just created. + +```yaml +apiVersion: kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: minute-elasticsearch + namespace: demo +spec: + version: "8.0-v2" + storageType: Durable + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: DoNotTerminate + +``` + +Now, wait a few minutes. the KubeDB operator will create necessary PVC, statefulset, services, secret etc. If everything goes well, we should see that a pod with the name `minute-elasticsearch-0` has been created. + +Check that the statefulset's pod is running + +```console +$ kubectl get pod -n demo minute-elasticsearch-0 +NAME READY STATUS RESTARTS AGE +minute-elasticsearch-0 1/1 Running 0 14m +``` + +Check the pod's log to see if the database is ready + +```console +$ kubectl logs -f -n demo minute-elasticsearch-0 ++ set -o errexit ++ set -o pipefail ++ sync +... +Starting runit... +.................... +.................. +Search Guard Version: 6.3.0-23.1 +Connected as CN=sgadmin,O=Elasticsearch Operator +Contacting elasticsearch cluster 'elasticsearch' and wait for YELLOW clusterstate ... +Clustername: quick-elasticsearch +Clusterstate: GREEN +Number of nodes: 3 +Number of data nodes: 3 +searchguard index does not exists, attempt to create it ... done (0-all replicas) +Populate config from /elasticsearch/plugins/search-guard-6/sgconfig/ +Will update 'sg/config' with /elasticsearch/plugins/search-guard-6/sgconfig/sg_config.yml + SUCC: Configuration for 'config' created or updated +Will update 'sg/roles' with /elasticsearch/plugins/search-guard-6/sgconfig/sg_roles.yml + SUCC: Configuration for 'roles' created or updated +Will update 'sg/rolesmapping' with /elasticsearch/plugins/search-guard-6/sgconfig/sg_roles_mapping.yml + SUCC: Configuration for 'rolesmapping' created or updated +Will update 'sg/internalusers' with /elasticsearch/plugins/search-guard-6/sgconfig/sg_internal_users.yml + SUCC: Configuration for 'internalusers' created or updated +Will update 'sg/actiongroups' with /elasticsearch/plugins/search-guard-6/sgconfig/sg_action_groups.yml + SUCC: Configuration for 'actiongroups' created or updated +[2019-05-31T09:10:31,537][INFO ][c.f.s.c.IndexBaseConfigurationRepository] Search Guard License Info: No license needed because enterprise modules are not enabled +Done with success + +``` + +`Done with success` in the log signifies that the database is running successfully. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```console +kubectl patch -n demo es/quick-elasticsearch -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge" +kubectl delete -n demo es/quick-elasticsearch + +kubectl patch -n demo es/minute-elasticsearch -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge" +kubectl delete -n demo es/minute-elasticsearch + +kubectl delete -n demo role my-custom-role +kubectl delete -n demo rolebinding my-custom-rolebinding + +kubectl delete sa -n demo my-custom-serviceaccount + +kubectl delete ns demo +``` + +If you would like to uninstall the KubeDB operator, please follow the steps [here](/docs/setup/uninstall.md). + +## Next Steps + +- [Quickstart Elasticsearch](/docs/guides/elasticsearch/quickstart/quickstart.md) with KubeDB Operator. +- [Snapshot and Restore](/docs/guides/elasticsearch/snapshot/backup-and-restore.md) process of Elasticsearch instances using KubeDB. +- Take [Scheduled Snapshot](/docs/guides/elasticsearch/snapshot/scheduled-backup.md) of Elasticsearch instances using KubeDB. +- Initialize [Elasticsearch with Script](/docs/guides/elasticsearch/initialization/using-script.md). +- Initialize [Elasticsearch with Snapshot](/docs/guides/elasticsearch/initialization/using-snapshot.md). +- Monitor your Elasticsearch instance with KubeDB using [out-of-the-box CoreOS Prometheus Operator](/docs/guides/elasticsearch/monitoring/using-coreos-prometheus-operator.md). +- Monitor your Elasticsearch instance with KubeDB using [out-of-the-box builtin-Prometheus](/docs/guides/elasticsearch/monitoring/using-builtin-prometheus.md). +- Use [private Docker registry](/docs/guides/elasticsearch/private-registry/using-private-registry.md) to deploy Elasticsearch with KubeDB. +- Use [kubedb cli](/docs/guides/elasticsearch/cli/cli.md) to manage databases like kubectl for Kubernetes. +- Detail concepts of [Elasticsearch object](/docs/concepts/databases/elasticsearch.md). +- Detail concepts of [Snapshot object](/docs/concepts/snapshot.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). + diff --git a/docs/guides/memcached/custom-rbac/_index.md b/docs/guides/memcached/custom-rbac/_index.md new file mode 100755 index 0000000000..1ca4fc70a1 --- /dev/null +++ b/docs/guides/memcached/custom-rbac/_index.md @@ -0,0 +1,10 @@ +--- +title: Run Memcached with Custom RBAC resources +menu: + docs_0.12.0: + identifier: mc-custom-rbac + name: Custom RBAC + parent: mc-memcached-guides + weight: 85 +menu_name: docs_0.12.0 +--- diff --git a/docs/guides/memcached/custom-rbac/using-custom-rbac.md b/docs/guides/memcached/custom-rbac/using-custom-rbac.md new file mode 100644 index 0000000000..520d083f2e --- /dev/null +++ b/docs/guides/memcached/custom-rbac/using-custom-rbac.md @@ -0,0 +1,265 @@ +--- +title: Run Memcached with Custom RBAC resources +menu: + docs_0.12.0: + identifier: mc-custom-rbac-quickstart + name: Custom RBAC + parent: mc-custom-rbac + weight: 10 +menu_name: docs_0.12.0 +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/concepts/README.md). + +# Using Custom RBAC resources + +KubeDB (version 0.13.0 and higher) supports finer user control over role based access permissions provided to a Memcached instance. This tutorial will show you how to use KubeDB to run Memcached database with custom RBAC resources. + +## 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 [minikube](https://github.com/kubernetes/minikube). + +Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/install.md). + +To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + +```console +$ kubectl create ns demo +namespace/demo created +``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/memcached](https://github.com/kubedb/docs/tree/0.12.0/docs/examples/memcached) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Overview + +KubeDB allows users to provide custom RBAC resources, namely, `ServiceAccount`, `Role`, and `RoleBinding` for Memcached. This is provided via the `spec.podTemplate.spec.serviceAccountName` field in Memcached crd. If this field is left empty, the KubeDB operator will create a service account name matching Memcached crd name. Role and RoleBinding that provide necessary access permissions will also be generated automatically for this service account. + +If a service account name is given, but there's no existing service account by that name, the KubeDB operator will create one, and Role and RoleBinding that provide necessary access permissions will also be generated for this service account. + +If a service account name is given, and there's an existing service account by that name, the KubeDB operator will use that existing service account. Since this service account is not managed by KubeDB, users are responsible for providing necessary access permissions manually. + +This guide will show you how to create custom `Service Account`, `Role`, and `RoleBinding` for a Memcached instance named `quick-memcached` to provide the bare minimum access permissions. + +## Custom RBAC for Memcached + +At first, let's create a `Service Acoount` in `demo` namespace. + +```console +$ kubectl create serviceaccount -n demo my-custom-serviceaccount +serviceaccount/my-custom-serviceaccount created +``` + +It should create a service account. + +```yaml +$ kubectl get serviceaccount -n demo my-custom-serviceaccount -o yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + creationTimestamp: "2019-05-30T04:23:39Z" + name: my-custom-serviceaccount + namespace: demo + resourceVersion: "21657" + selfLink: /api/v1/namespaces/demo/serviceaccounts/myserviceaccount + uid: b2ec2b05-8292-11e9-8d10-080027a8b217 +secrets: +- name: myserviceaccount-token-t8zxd +``` + +Now, we need to create a role that has necessary access permissions for the Memcached instance named `quick-memcached`. + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/0.12.0/docs/examples/memcached/custom-rbac/mc-custom-role.yaml +role.rbac.authorization.k8s.io/my-custom-role created +``` + +Below is the YAML for the Role we just created. + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: my-custom-role + namespace: demo +rules: +- apiGroups: + - policy + resourceNames: + - memcached-db + resources: + - podsecuritypolicies + verbs: + - use +``` + +This permission is required for Memcached pods running on PSP enabled clusters. + +Now create a `RoleBinding` to bind this `Role` with the already created service account. + +```console +$ kubectl create rolebinding my-custom-rolebinding --role=my-custom-role --serviceaccount=demo:my-custom-serviceaccount --namespace=demo +rolebinding.rbac.authorization.k8s.io/my-custom-rolebinding created + +``` + +It should bind `my-custom-role` and `my-custom-serviceaccount` successfully. + +```yaml +$ kubectl get rolebinding -n demo my-custom-rolebinding -o yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + creationTimestamp: "kubectl get rolebinding -n demo my-custom-rolebinding -o yaml" + name: my-custom-rolebinding + namespace: demo + resourceVersion: "1405" + selfLink: /apis/rbac.authorization.k8s.io/v1/namespaces/demo/rolebindings/my-custom-rolebinding + uid: 123afc02-8297-11e9-8d10-080027a8b217 +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: my-custom-role +subjects: +- kind: ServiceAccount + name: my-custom-serviceaccount + namespace: demo + +``` + +Now, create a Memcached crd specifying `spec.podTemplate.spec.serviceAccountName` field to `my-custom-serviceaccount`. + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/0.12.0/docs/examples/memcached/custom-rbac/mc-custom-db.yaml +memcached.kubedb.com/quick-memcached created +``` + +Below is the YAML for the Memcached crd we just created. + +```yaml +apiVersion: kubedb.com/v1alpha1 +kind: Memcached +metadata: + name: quick-memcached + namespace: demo +spec: + replicas: 3 + version: "1.5.4-v1" + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + resources: + limits: + cpu: 500m + memory: 128Mi + requests: + cpu: 250m + memory: 64Mi + terminationPolicy: DoNotTerminate + +``` + +Now, wait a few minutes. the KubeDB operator will create necessary PVC, deployment, services, secret etc. If everything goes well, we should see that a pod with the name `quick-memcached-0` has been created. + +Check that the deployment's pod is running + +```console +$ kubectl get pods -n demo +NAME READY STATUS RESTARTS AGE +quick-memcached-d866d6d89-sdlkx 1/1 Running 0 5m52s +quick-memcached-d866d6d89-wpdz2 1/1 Running 0 5m52s +quick-memcached-d866d6d89-wvg7c 1/1 Running 0 5m52s + +$ kubectl get pod -n demo quick-memcached-0 +NAME READY STATUS RESTARTS AGE +quick-memcached-d866d6d89-wvg7c 1/1 Running 0 14m +``` + +## Reusing Service Account + +An existing service account can be reused in another Memcached instance. No new access permission is required to run the new Memcached instance. + +Now, create Memcached crd `minute-memcached` using the existing service account name `my-custom-serviceaccount` in the `spec.podTemplate.spec.serviceAccountName` field. + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/0.12.0/docs/examples/memcached/custom-rbac/mc-custom-db-two.yaml +memcached.kubedb.com/quick-memcached created +``` + +Below is the YAML for the Memcached crd we just created. + +```yaml +apiVersion: kubedb.com/v1alpha1 +kind: Memcached +metadata: + name: minute-memcached + namespace: demo +spec: + replicas: 3 + version: "1.5.4-v1" + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + resources: + limits: + cpu: 500m + memory: 128Mi + requests: + cpu: 250m + memory: 64Mi + terminationPolicy: DoNotTerminate + +``` + +Now, wait a few minutes. the KubeDB operator will create necessary PVC, deployment, services, secret etc. If everything goes well, we should see that a pod with the name `minute-memcached-0` has been created. + +Check that the deployment's pod is running + +```console +$ kubectl get pods -n demo +NAME READY STATUS RESTARTS AGE +minute-memcached-58798985f-47tm8 1/1 Running 0 5m52s +minute-memcached-58798985f-47tm8 1/1 Running 0 5m52s +minute-memcached-58798985f-47tm8 1/1 Running 0 5m52s + +$ kubectl get pod -n demo minute-memcached-0 +NAME READY STATUS RESTARTS AGE +minute-memcached-58798985f-47tm8 1/1 Running 0 14m +``` + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```console +kubectl patch -n demo mc/quick-memcached -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge" +kubectl delete -n demo mc/quick-memcached + +kubectl patch -n demo mc/minute-memcached -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge" +kubectl delete -n demo mc/minute-memcached + +kubectl delete -n demo role my-custom-role +kubectl delete -n demo rolebinding my-custom-rolebinding + +kubectl delete sa -n demo my-custom-serviceaccount + +kubectl delete ns demo +``` + +If you would like to uninstall the KubeDB operator, please follow the steps [here](/docs/setup/uninstall.md). + +## Next Steps + +- [Quickstart Memcached](/docs/guides/memcached/quickstart/quickstart.md) with KubeDB Operator. +- [Snapshot and Restore](/docs/guides/memcached/snapshot/backup-and-restore.md) process of Memcached databases using KubeDB. +- Take [Scheduled Snapshot](/docs/guides/memcached/snapshot/scheduled-backup.md) of Memcached databases using KubeDB. +- Initialize [Memcached with Script](/docs/guides/memcached/initialization/using-script.md). +- Initialize [Memcached with Snapshot](/docs/guides/memcached/initialization/using-snapshot.md). +- Monitor your Memcached database with KubeDB using [out-of-the-box CoreOS Prometheus Operator](/docs/guides/memcached/monitoring/using-coreos-prometheus-operator.md). +- Monitor your Memcached database with KubeDB using [out-of-the-box builtin-Prometheus](/docs/guides/memcached/monitoring/using-builtin-prometheus.md). +- Use [private Docker registry](/docs/guides/memcached/private-registry/using-private-registry.md) to deploy Memcached with KubeDB. +- Use [kubedb cli](/docs/guides/memcached/cli/cli.md) to manage databases like kubectl for Kubernetes. +- Detail concepts of [Memcached object](/docs/concepts/databases/memcached.md). +- Detail concepts of [Snapshot object](/docs/concepts/snapshot.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). + diff --git a/docs/guides/mongodb/custom-rbac/_index.md b/docs/guides/mongodb/custom-rbac/_index.md new file mode 100755 index 0000000000..a3c90e9254 --- /dev/null +++ b/docs/guides/mongodb/custom-rbac/_index.md @@ -0,0 +1,10 @@ +--- +title: Run MongoDB with Custom RBAC resources +menu: + docs_0.12.0: + identifier: mg-custom-rbac + name: Custom RBAC + parent: mg-mongodb-guides + weight: 85 +menu_name: docs_0.12.0 +--- diff --git a/docs/guides/mongodb/custom-rbac/using-custom-rbac.md b/docs/guides/mongodb/custom-rbac/using-custom-rbac.md new file mode 100644 index 0000000000..6819a5accc --- /dev/null +++ b/docs/guides/mongodb/custom-rbac/using-custom-rbac.md @@ -0,0 +1,291 @@ +--- +title: Run MongoDB with Custom RBAC resources +menu: + docs_0.12.0: + identifier: mg-custom-rbac-quickstart + name: Custom RBAC + parent: mg-custom-rbac + weight: 10 +menu_name: docs_0.12.0 +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/concepts/README.md). + +# Using Custom RBAC resources + +KubeDB (version 0.13.0 and higher) supports finer user control over role based access permissions provided to a MongoDB instance. This tutorial will show you how to use KubeDB to run MongoDB instance with custom RBAC resources. + +## 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 [minikube](https://github.com/kubernetes/minikube). + +Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/install.md). + +To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + +```console +$ 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/0.12.0/docs/examples/mongodb) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Overview + +KubeDB allows users to provide custom RBAC resources, namely, `ServiceAccount`, `Role`, and `RoleBinding` for MongoDB. This is provided via the `spec.podTemplate.spec.serviceAccountName` field in MongoDB crd. If this field is left empty, the KubeDB operator will create a service account name matching MongoDB crd name. Role and RoleBinding that provide necessary access permissions will also be generated automatically for this service account. + +If a service account name is given, but there's no existing service account by that name, the KubeDB operator will create one, and Role and RoleBinding that provide necessary access permissions will also be generated for this service account. + +If a service account name is given, and there's an existing service account by that name, the KubeDB operator will use that existing service account. Since this service account is not managed by KubeDB, users are responsible for providing necessary access permissions manually. + +This guide will show you how to create custom `Service Account`, `Role`, and `RoleBinding` for a MongoDB instance named `quick-postges` to provide the bare minimum access permissions. + +## Custom RBAC for MongoDB + +At first, let's create a `Service Acoount` in `demo` namespace. + +```console +$ kubectl create serviceaccount -n demo my-custom-serviceaccount +serviceaccount/my-custom-serviceaccount created +``` + +It should create a service account. + +```yaml +$ kubectl get serviceaccount -n demo my-custom-serviceaccount -o yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + creationTimestamp: "2019-05-30T04:23:39Z" + name: my-custom-serviceaccount + namespace: demo + resourceVersion: "21657" + selfLink: /api/v1/namespaces/demo/serviceaccounts/myserviceaccount + uid: b2ec2b05-8292-11e9-8d10-080027a8b217 +secrets: +- name: myserviceaccount-token-t8zxd +``` + +Now, we need to create a role that has necessary access permissions for the MongoDB instance named `quick-mongodb`. + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/0.12.0/docs/examples/mongodb/custom-rbac/mg-custom-role.yaml +role.rbac.authorization.k8s.io/my-custom-role created +``` + +Below is the YAML for the Role we just created. + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: my-custom-role + namespace: demo +rules: +- apiGroups: + - policy + resourceNames: + - mongodb-db + resources: + - podsecuritypolicies + verbs: + - use +``` + +This permission is required for MongoDB pods running on PSP enabled clusters. + +Now create a `RoleBinding` to bind this `Role` with the already created service account. + +```console +$ kubectl create rolebinding my-custom-rolebinding --role=my-custom-role --serviceaccount=demo:my-custom-serviceaccount --namespace=demo +rolebinding.rbac.authorization.k8s.io/my-custom-rolebinding created + +``` + +It should bind `my-custom-role` and `my-custom-serviceaccount` successfully. + +```yaml +$ kubectl get rolebinding -n demo my-custom-rolebinding -o yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + creationTimestamp: "kubectl get rolebinding -n demo my-custom-rolebinding -o yaml" + name: my-custom-rolebinding + namespace: demo + resourceVersion: "1405" + selfLink: /apis/rbac.authorization.k8s.io/v1/namespaces/demo/rolebindings/my-custom-rolebinding + uid: 123afc02-8297-11e9-8d10-080027a8b217 +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: my-custom-role +subjects: +- kind: ServiceAccount + name: my-custom-serviceaccount + namespace: demo + +``` + +Now, create a MongoDB crd specifying `spec.podTemplate.spec.serviceAccountName` field to `my-custom-serviceaccount`. + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/0.12.0/docs/examples/mongodb/custom-rbac/mg-custom-db.yaml +mongodb.kubedb.com/quick-mongodb created +``` + +Below is the YAML for the MongoDB crd we just created. + +```yaml +apiVersion: kubedb.com/v1alpha1 +kind: MongoDB +metadata: + name: quick-mongodb + namespace: demo +spec: + version: "3.4-v3" + storageType: Durable + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: DoNotTerminate + +``` + +Now, wait a few minutes. the KubeDB operator will create necessary PVC, deployment, statefulsets, services, secret etc. If everything goes well, we should see that a pod with the name `quick-mongodb-0` has been created. + +Check that the statefulset's pod is running + +```console +$ kubectl get pod -n demo quick-mongodb-0 +NAME READY STATUS RESTARTS AGE +quick-mongodb-0 1/1 Running 0 14m +``` + +Check the pod's log to see if the database is ready + +```console +$ kubectl logs -f -n demo quick-mongodb-0 +about to fork child process, waiting until server is ready for connections. +forked process: 17 +2019-06-10T08:56:45.259+0000 I CONTROL [main] ***** SERVER RESTARTED ***** +2019-06-10T08:56:45.263+0000 I CONTROL [initandlisten] MongoDB starting : pid=17 port=27017 dbpath=/data/db 64-bit host=quick-mongodb-0 +... +... +MongoDB init process complete; ready for start up. +... +.. +2019-06-10T08:56:49.287+0000 I NETWORK [thread1] waiting for connections on port 27017 +2019-06-10T08:56:57.179+0000 I NETWORK [thread1] connection accepted from 127.0.0.1:39214 #1 (1 connection now open) +``` + +Once we see `connection accepted` in the log, the database is ready. + +## Reusing Service Account + +An existing service account can be reused in another MongoDB instance. No new access permission is required to run the new MongoDB instance. + +Now, create MongoDB crd `minute-mongodb` using the existing service account name `my-custom-serviceaccount` in the `spec.podTemplate.spec.serviceAccountName` field. + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/0.12.0/docs/examples/mongodb/custom-rbac/mg-custom-db-two.yaml +mongodb.kubedb.com/quick-mongodb created +``` + +Below is the YAML for the MongoDB crd we just created. + +```yaml +apiVersion: kubedb.com/v1alpha1 +kind: MongoDB +metadata: + name: minute-mongodb + namespace: demo +spec: + version: "3.4-v3" + storageType: Durable + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: DoNotTerminate + +``` + +Now, wait a few minutes. the KubeDB operator will create necessary PVC, statefulset, deployment, services, secret etc. If everything goes well, we should see that a pod with the name `minute-mongodb-0` has been created. + +Check that the statefulset's pod is running + +```console +$ kubectl get pod -n demo minute-mongodb-0 +NAME READY STATUS RESTARTS AGE +minute-mongodb-0 1/1 Running 0 14m +``` + +Check the pod's log to see if the database is ready + +```console +$ kubectl logs -f -n demo minute-mongodb-0 +about to fork child process, waiting until server is ready for connections. +forked process: 17 +2019-06-10T08:56:45.259+0000 I CONTROL [main] ***** SERVER RESTARTED ***** +2019-06-10T08:56:45.263+0000 I CONTROL [initandlisten] MongoDB starting : pid=17 port=27017 dbpath=/data/db 64-bit host=quick-mongodb-0 +... +... +MongoDB init process complete; ready for start up. +... +.. +2019-06-10T08:56:49.287+0000 I NETWORK [thread1] waiting for connections on port 27017 +2019-06-10T08:56:57.179+0000 I NETWORK [thread1] connection accepted from 127.0.0.1:39214 #1 (1 connection now open) +``` + +`connection accepted` in the log signifies that the database is running successfully. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```console +kubectl patch -n demo mg/quick-mongodb -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge" +kubectl delete -n demo mg/quick-mongodb + +kubectl patch -n demo mg/minute-mongodb -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge" +kubectl delete -n demo mg/minute-mongodb + +kubectl delete -n demo role my-custom-role +kubectl delete -n demo rolebinding my-custom-rolebinding + +kubectl delete sa -n demo my-custom-serviceaccount + +kubectl delete ns demo +``` + +If you would like to uninstall the KubeDB operator, please follow the steps [here](/docs/setup/uninstall.md). + +## Next Steps + +- [Quickstart MongoDB](/docs/guides/mongodb/quickstart/quickstart.md) with KubeDB Operator. +- [Snapshot and Restore](/docs/guides/mongodb/snapshot/backup-and-restore.md) process of MongoDB instances using KubeDB. +- Take [Scheduled Snapshot](/docs/guides/mongodb/snapshot/scheduled-backup.md) of MongoDB instances using KubeDB. +- Initialize [MongoDB with Script](/docs/guides/mongodb/initialization/using-script.md). +- Initialize [MongoDB with Snapshot](/docs/guides/mongodb/initialization/using-snapshot.md). +- Monitor your MongoDB instance with KubeDB using [out-of-the-box CoreOS Prometheus Operator](/docs/guides/mongodb/monitoring/using-coreos-prometheus-operator.md). +- Monitor your MongoDB instance 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/concepts/databases/mongodb.md). +- Detail concepts of [Snapshot object](/docs/concepts/snapshot.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). + diff --git a/docs/guides/mysql/custom-rbac/_index.md b/docs/guides/mysql/custom-rbac/_index.md new file mode 100755 index 0000000000..7b59b4cece --- /dev/null +++ b/docs/guides/mysql/custom-rbac/_index.md @@ -0,0 +1,10 @@ +--- +title: Run MySQL with Custom RBAC resources +menu: + docs_0.12.0: + identifier: my-custom-rbac + name: Custom RBAC + parent: my-mysql-guides + weight: 85 +menu_name: docs_0.12.0 +--- diff --git a/docs/guides/mysql/custom-rbac/using-custom-rbac.md b/docs/guides/mysql/custom-rbac/using-custom-rbac.md new file mode 100644 index 0000000000..de930f853d --- /dev/null +++ b/docs/guides/mysql/custom-rbac/using-custom-rbac.md @@ -0,0 +1,314 @@ +--- +title: Run MySQL with Custom RBAC resources +menu: + docs_0.12.0: + identifier: my-custom-rbac-quickstart + name: Custom RBAC + parent: my-custom-rbac + weight: 10 +menu_name: docs_0.12.0 +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/concepts/README.md). + +# Using Custom RBAC resources + +KubeDB (version 0.13.0 and higher) supports finer user control over role based access permissions provided to a MySQL instance. This tutorial will show you how to use KubeDB to run MySQL instance with custom RBAC resources. + +## 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 [minikube](https://github.com/kubernetes/minikube). + +Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/install.md). + +To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + +```console +$ kubectl create ns demo +namespace/demo created +``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/mysql](https://github.com/kubedb/docs/tree/0.12.0/docs/examples/mysql) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Overview + +KubeDB allows users to provide custom RBAC resources, namely, `ServiceAccount`, `Role`, and `RoleBinding` for MySQL. This is provided via the `spec.podTemplate.spec.serviceAccountName` field in MySQL crd. If this field is left empty, the KubeDB operator will create a service account name matching MySQL crd name. Role and RoleBinding that provide necessary access permissions will also be generated automatically for this service account. + +If a service account name is given, but there's no existing service account by that name, the KubeDB operator will create one, and Role and RoleBinding that provide necessary access permissions will also be generated for this service account. + +If a service account name is given, and there's an existing service account by that name, the KubeDB operator will use that existing service account. Since this service account is not managed by KubeDB, users are responsible for providing necessary access permissions manually. + +This guide will show you how to create custom `Service Account`, `Role`, and `RoleBinding` for a MySQL instance named `quick-postges` to provide the bare minimum access permissions. + +## Custom RBAC for MySQL + +At first, let's create a `Service Acoount` in `demo` namespace. + +```console +$ kubectl create serviceaccount -n demo my-custom-serviceaccount +serviceaccount/my-custom-serviceaccount created +``` + +It should create a service account. + +```yaml +$ kubectl get serviceaccount -n demo my-custom-serviceaccount -o yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + creationTimestamp: "2019-05-30T04:23:39Z" + name: my-custom-serviceaccount + namespace: demo + resourceVersion: "21657" + selfLink: /api/v1/namespaces/demo/serviceaccounts/myserviceaccount + uid: b2ec2b05-8292-11e9-8d10-080027a8b217 +secrets: +- name: myserviceaccount-token-t8zxd +``` + +Now, we need to create a role that has necessary access permissions for the MySQL instance named `quick-mysql`. + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/0.12.0/docs/examples/mysql/custom-rbac/my-custom-role.yaml +role.rbac.authorization.k8s.io/my-custom-role created +``` + +Below is the YAML for the Role we just created. + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: my-custom-role + namespace: demo +rules: +- apiGroups: + - policy + resourceNames: + - mysql-db + resources: + - podsecuritypolicies + verbs: + - use +``` + +This permission is required for MySQL pods running on PSP enabled clusters. + +Now create a `RoleBinding` to bind this `Role` with the already created service account. + +```console +$ kubectl create rolebinding my-custom-rolebinding --role=my-custom-role --serviceaccount=demo:my-custom-serviceaccount --namespace=demo +rolebinding.rbac.authorization.k8s.io/my-custom-rolebinding created + +``` + +It should bind `my-custom-role` and `my-custom-serviceaccount` successfully. + +```yaml +$ kubectl get rolebinding -n demo my-custom-rolebinding -o yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + creationTimestamp: "kubectl get rolebinding -n demo my-custom-rolebinding -o yaml" + name: my-custom-rolebinding + namespace: demo + resourceVersion: "1405" + selfLink: /apis/rbac.authorization.k8s.io/v1/namespaces/demo/rolebindings/my-custom-rolebinding + uid: 123afc02-8297-11e9-8d10-080027a8b217 +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: my-custom-role +subjects: +- kind: ServiceAccount + name: my-custom-serviceaccount + namespace: demo + +``` + +Now, create a MySQL crd specifying `spec.podTemplate.spec.serviceAccountName` field to `my-custom-serviceaccount`. + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/0.12.0/docs/examples/mysql/custom-rbac/my-custom-db.yaml +mysql.kubedb.com/quick-mysql created +``` + +Below is the YAML for the MySQL crd we just created. + +```yaml +apiVersion: kubedb.com/v1alpha1 +kind: MySQL +metadata: + name: quick-mysql + namespace: demo +spec: + version: "8.0-v2" + storageType: Durable + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: DoNotTerminate + +``` + +Now, wait a few minutes. the KubeDB operator will create necessary PVC, statefulset, services, secret etc. If everything goes well, we should see that a pod with the name `quick-mysql-0` has been created. + +Check that the statefulset's pod is running + +```console +$ kubectl get pod -n demo quick-mysql-0 +NAME READY STATUS RESTARTS AGE +quick-mysql-0 1/1 Running 0 14m +``` + +Check the pod's log to see if the database is ready + +```console +$ kubectl logs -f -n demo quick-mysql-0 +Initializing database +2019-05-31T05:02:35.307699Z 0 [Warning] [MY-011070] [Server] 'Disabling symbolic links using --skip-symbolic-links (or equivalent) is the default. Consider not using this option as it' is deprecated and will be removed in a future release. +2019-05-31T05:02:35.307762Z 0 [System] [MY-013169] [Server] /usr/sbin/mysqld (mysqld 8.0.14) initializing of server in progress as process 29 +2019-05-31T05:02:47.346326Z 5 [Warning] [MY-010453] [Server] root@localhost is created with an empty password ! Please consider switching off the --initialize-insecure option. +2019-05-31T05:02:53.777918Z 0 [System] [MY-013170] [Server] /usr/sbin/mysqld (mysqld 8.0.14) initializing of server has completed +Database initialized +MySQL init process in progress... +MySQL init process in progress... +2019-05-31T05:02:56.656884Z 0 [Warning] [MY-011070] [Server] 'Disabling symbolic links using --skip-symbolic-links (or equivalent) is the default. Consider not using this option as it' is deprecated and will be removed in a future release. +2019-05-31T05:02:56.656953Z 0 [System] [MY-010116] [Server] /usr/sbin/mysqld (mysqld 8.0.14) starting as process 80 +2019-05-31T05:02:57.876853Z 0 [Warning] [MY-010068] [Server] CA certificate ca.pem is self signed. +2019-05-31T05:02:57.892774Z 0 [Warning] [MY-011810] [Server] Insecure configuration for --pid-file: Location '/var/run/mysqld' in the path is accessible to all OS users. Consider choosing a different directory. +2019-05-31T05:02:57.910391Z 0 [System] [MY-010931] [Server] /usr/sbin/mysqld: ready for connections. Version: '8.0.14' socket: '/var/run/mysqld/mysqld.sock' port: 0 MySQL Community Server - GPL. +2019-05-31T05:02:58.045050Z 0 [System] [MY-011323] [Server] X Plugin ready for connections. Socket: '/var/run/mysqld/mysqlx.sock' +Warning: Unable to load '/usr/share/zoneinfo/iso3166.tab' as time zone. Skipping it. +Warning: Unable to load '/usr/share/zoneinfo/leap-seconds.list' as time zone. Skipping it. +Warning: Unable to load '/usr/share/zoneinfo/zone.tab' as time zone. Skipping it. +Warning: Unable to load '/usr/share/zoneinfo/zone1970.tab' as time zone. Skipping it. + +2019-05-31T05:03:04.217396Z 0 [System] [MY-010910] [Server] /usr/sbin/mysqld: Shutdown complete (mysqld 8.0.14) MySQL Community Server - GPL. + +MySQL init process done. Ready for start up. +``` + +Once we see `MySQL init process done. Ready for start up.` in the log, the database is ready. + +## Reusing Service Account + +An existing service account can be reused in another MySQL instance. No new access permission is required to run the new MySQL instance. + +Now, create MySQL crd `minute-mysql` using the existing service account name `my-custom-serviceaccount` in the `spec.podTemplate.spec.serviceAccountName` field. + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/0.12.0/docs/examples/mysql/custom-rbac/my-custom-db-two.yaml +mysql.kubedb.com/quick-mysql created +``` + +Below is the YAML for the MySQL crd we just created. + +```yaml +apiVersion: kubedb.com/v1alpha1 +kind: MySQL +metadata: + name: minute-mysql + namespace: demo +spec: + version: "8.0-v2" + storageType: Durable + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: DoNotTerminate + +``` + +Now, wait a few minutes. the KubeDB operator will create necessary PVC, statefulset, services, secret etc. If everything goes well, we should see that a pod with the name `minute-mysql-0` has been created. + +Check that the statefulset's pod is running + +```console +$ kubectl get pod -n demo minute-mysql-0 +NAME READY STATUS RESTARTS AGE +minute-mysql-0 1/1 Running 0 14m +``` + +Check the pod's log to see if the database is ready + +```console +$ kubectl logs -f -n demo minute-mysql-0 +Initializing database +2019-05-31T05:09:12.165236Z 0 [Warning] [MY-011070] [Server] 'Disabling symbolic links using --skip-symbolic-links (or equivalent) is the default. Consider not using this option as it' is deprecated and will be removed in a future release. +2019-05-31T05:09:12.165298Z 0 [System] [MY-013169] [Server] /usr/sbin/mysqld (mysqld 8.0.14) initializing of server in progress as process 28 +2019-05-31T05:09:24.903995Z 5 [Warning] [MY-010453] [Server] root@localhost is created with an empty password ! Please consider switching off the --initialize-insecure option. +2019-05-31T05:09:30.857155Z 0 [System] [MY-013170] [Server] /usr/sbin/mysqld (mysqld 8.0.14) initializing of server has completed +Database initialized +MySQL init process in progress... +MySQL init process in progress... +2019-05-31T05:09:33.931254Z 0 [Warning] [MY-011070] [Server] 'Disabling symbolic links using --skip-symbolic-links (or equivalent) is the default. Consider not using this option as it' is deprecated and will be removed in a future release. +2019-05-31T05:09:33.931315Z 0 [System] [MY-010116] [Server] /usr/sbin/mysqld (mysqld 8.0.14) starting as process 79 +2019-05-31T05:09:34.819349Z 0 [Warning] [MY-010068] [Server] CA certificate ca.pem is self signed. +2019-05-31T05:09:34.834673Z 0 [Warning] [MY-011810] [Server] Insecure configuration for --pid-file: Location '/var/run/mysqld' in the path is accessible to all OS users. Consider choosing a different directory. +2019-05-31T05:09:34.850188Z 0 [System] [MY-010931] [Server] /usr/sbin/mysqld: ready for connections. Version: '8.0.14' socket: '/var/run/mysqld/mysqld.sock' port: 0 MySQL Community Server - GPL. +2019-05-31T05:09:35.064435Z 0 [System] [MY-011323] [Server] X Plugin ready for connections. Socket: '/var/run/mysqld/mysqlx.sock' +Warning: Unable to load '/usr/share/zoneinfo/iso3166.tab' as time zone. Skipping it. +Warning: Unable to load '/usr/share/zoneinfo/leap-seconds.list' as time zone. Skipping it. +Warning: Unable to load '/usr/share/zoneinfo/zone.tab' as time zone. Skipping it. +Warning: Unable to load '/usr/share/zoneinfo/zone1970.tab' as time zone. Skipping it. + +2019-05-31T05:09:41.236940Z 0 [System] [MY-010910] [Server] /usr/sbin/mysqld: Shutdown complete (mysqld 8.0.14) MySQL Community Server - GPL. + +MySQL init process done. Ready for start up. + +``` + +`MySQL init process done. Ready for start up.` in the log signifies that the database is running successfully. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```console +kubectl patch -n demo my/quick-mysql -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge" +kubectl delete -n demo my/quick-mysql + +kubectl patch -n demo my/minute-mysql -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge" +kubectl delete -n demo my/minute-mysql + +kubectl delete -n demo role my-custom-role +kubectl delete -n demo rolebinding my-custom-rolebinding + +kubectl delete sa -n demo my-custom-serviceaccount + +kubectl delete ns demo +``` + +If you would like to uninstall the KubeDB operator, please follow the steps [here](/docs/setup/uninstall.md). + +## Next Steps + +- [Quickstart MySQL](/docs/guides/mysql/quickstart/quickstart.md) with KubeDB Operator. +- [Snapshot and Restore](/docs/guides/mysql/snapshot/backup-and-restore.md) process of MySQL instances using KubeDB. +- Take [Scheduled Snapshot](/docs/guides/mysql/snapshot/scheduled-backup.md) of MySQL instances using KubeDB. +- Initialize [MySQL with Script](/docs/guides/mysql/initialization/using-script.md). +- Initialize [MySQL with Snapshot](/docs/guides/mysql/initialization/using-snapshot.md). +- Monitor your MySQL instance with KubeDB using [out-of-the-box CoreOS Prometheus Operator](/docs/guides/mysql/monitoring/using-coreos-prometheus-operator.md). +- Monitor your MySQL instance with KubeDB using [out-of-the-box builtin-Prometheus](/docs/guides/mysql/monitoring/using-builtin-prometheus.md). +- Use [private Docker registry](/docs/guides/mysql/private-registry/using-private-registry.md) to deploy MySQL with KubeDB. +- Use [kubedb cli](/docs/guides/mysql/cli/cli.md) to manage databases like kubectl for Kubernetes. +- Detail concepts of [MySQL object](/docs/concepts/databases/mysql.md). +- Detail concepts of [Snapshot object](/docs/concepts/snapshot.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). + diff --git a/docs/guides/postgres/custom-rbac/using-custom-rbac.md b/docs/guides/postgres/custom-rbac/using-custom-rbac.md index 9d4b3f03e5..1b91f1f87a 100644 --- a/docs/guides/postgres/custom-rbac/using-custom-rbac.md +++ b/docs/guides/postgres/custom-rbac/using-custom-rbac.md @@ -3,7 +3,7 @@ title: Run PostgreSQL with Custom RBAC resources menu: docs_0.12.0: identifier: pg-custom-rbac-quickstart - name: Quickstart + name: Custom RBAC parent: pg-custom-rbac weight: 10 menu_name: docs_0.12.0 @@ -14,7 +14,7 @@ section_menu_id: guides # Using Custom RBAC resources -KubeDB (version 0.13.0 and higher) supports finer user control over role based access permissions provided to a PostgreSQL instance. This tutorial will show you how to use KubeDB to run PostgreSQL database with custom RBAC resources. +KubeDB (version 0.13.0 and higher) supports finer user control over role based access permissions provided to a PostgreSQL instance. This tutorial will show you how to use KubeDB to run PostgreSQL instance with custom RBAC resources. ## Before You Begin @@ -33,9 +33,13 @@ namespace/demo created ## Overview -KubeDB allows users to provide custom RBAC resources, namely, `ServiceAccount`, `Role`, and `RoleBinding` for PostgreSQL. This is provided via the `spec.podTemplate.spec.serviceAccountName` field in Postgres CRD. If the name of a custom service account is given the user, the KubeDB operator will not dynamically gratn permissions to this service account and use existing access permissions associated with it to run that PosgreSQL database. +KubeDB allows users to provide custom RBAC resources, namely, `ServiceAccount`, `Role`, and `RoleBinding` for PostgreSQL. This is provided via the `spec.podTemplate.spec.serviceAccountName` field in Postgres CRD. If this field is left empty, the KubeDB operator will create a service account name matching Postgres crd name. Role and RoleBinding that provide necessary access permissions will also be generated automatically for this service account. -This guide will show you how to create custom `Service Account`, `Role`, and `RoleBinding` for a PosgreSQL Database named `quick-postges` to provide the bare minimum access permissions. +If a service account name is given, but there's no existing service account by that name, the KubeDB operator will create one, and Role and RoleBinding that provide necessary access permissions will also be generated for this service account. + +If a service account name is given, and there's an existing service account by that name, the KubeDB operator will use that existing service account. Since this service account is not managed by KubeDB, users are responsible for providing necessary access permissions manually. + +This guide will show you how to create custom `Service Account`, `Role`, and `RoleBinding` for a PostgreSQL instance named `quick-postges` to provide the bare minimum access permissions. ## Custom RBAC for PostgreSQL @@ -119,7 +123,7 @@ rules: - use ``` -Please note that resourceNames `quick-postgres` and `quick-postgres-leader-lock` are unique to `quick-postgres` PostgreSQL Database. Another database `quick-postgres-2`, for exmaple, will require these resourceNames to be `quick-postgres-2`, and `quick-postgres-2-leader-lock`. +Please note that resourceNames `quick-postgres` and `quick-postgres-leader-lock` are unique to `quick-postgres` PostgreSQL instance. Another database `quick-postgres-2`, for exmaple, will require these resourceNames to be `quick-postgres-2`, and `quick-postgres-2-leader-lock`. Now create a `RoleBinding` to bind this `Role` with the already created service account. @@ -132,7 +136,7 @@ rolebinding.rbac.authorization.k8s.io/my-custom-rolebinding created It should bind `my-custom-role` and `my-custom-serviceaccount` successfully. ```yaml -$ kc get rolebinding -n demo my-custom-rolebinding -o yaml +$ kubectl get rolebinding -n demo my-custom-rolebinding -o yaml apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: @@ -200,7 +204,7 @@ quick-postgres-0 1/1 Running 0 14m Check the pod's log to see if the database is ready ```console -$ kubectl logs -f -n demo custom-postgres-0 +$ kubectl logs -f -n demo quick-postgres-0 I0705 12:05:51.697190 1 logs.go:19] FLAG: --alsologtostderr="false" I0705 12:05:51.717485 1 logs.go:19] FLAG: --enable-analytics="true" I0705 12:05:51.717543 1 logs.go:19] FLAG: --help="false" @@ -210,9 +214,9 @@ I0705 12:05:51.717573 1 logs.go:19] FLAG: --logtostderr="false" I0705 12:05:51.717581 1 logs.go:19] FLAG: --stderrthreshold="0" I0705 12:05:51.717589 1 logs.go:19] FLAG: --v="0" I0705 12:05:51.717597 1 logs.go:19] FLAG: --vmodule="" -We want "custom-postgres-0" as our leader -I0705 12:05:52.753464 1 leaderelection.go:175] attempting to acquire leader lease demo/custom-postgres-leader-lock... -I0705 12:05:52.822093 1 leaderelection.go:184] successfully acquired lease demo/custom-postgres-leader-lock +We want "quick-postgres-0" as our leader +I0705 12:05:52.753464 1 leaderelection.go:175] attempting to acquire leader lease demo/quick-postgres-leader-lock... +I0705 12:05:52.822093 1 leaderelection.go:184] successfully acquired lease demo/quick-postgres-leader-lock Got leadership, now do your jobs Running as Primary sh: locale: not found @@ -335,9 +339,9 @@ I0705 12:05:51.717573 1 logs.go:19] FLAG: --logtostderr="false" I0705 12:05:51.717581 1 logs.go:19] FLAG: --stderrthreshold="0" I0705 12:05:51.717589 1 logs.go:19] FLAG: --v="0" I0705 12:05:51.717597 1 logs.go:19] FLAG: --vmodule="" -We want "custom-postgres-0" as our leader -I0705 12:05:52.753464 1 leaderelection.go:175] attempting to acquire leader lease demo/custom-postgres-leader-lock... -I0705 12:05:52.822093 1 leaderelection.go:184] successfully acquired lease demo/custom-postgres-leader-lock +We want "minute-postgres-0" as our leader +I0705 12:05:52.753464 1 leaderelection.go:175] attempting to acquire leader lease demo/minute-postgres-leader-lock... +I0705 12:05:52.822093 1 leaderelection.go:184] successfully acquired lease demo/minute-postgres-leader-lock Got leadership, now do your jobs Running as Primary sh: locale: not found @@ -382,11 +386,11 @@ If you would like to uninstall the KubeDB operator, please follow the steps [her ## Next Steps -- Learn about [taking instant backup](/docs/guides/postgres/snapshot/instant_backup.md) of PostgreSQL database using KubeDB Snapshot. -- Learn how to [schedule backup](/docs/guides/postgres/snapshot/scheduled_backup.md) of PostgreSQL database. +- Learn about [taking instant backup](/docs/guides/postgres/snapshot/instant_backup.md) of PostgreSQL instance using KubeDB Snapshot. +- Learn how to [schedule backup](/docs/guides/postgres/snapshot/scheduled_backup.md) of PostgreSQL instance. - Learn about initializing [PostgreSQL with Script](/docs/guides/postgres/initialization/script_source.md). - Learn about initializing [PostgreSQL from KubeDB Snapshot](/docs/guides/postgres/initialization/snapshot_source.md). - Want to setup PostgreSQL cluster? Check how to [configure Highly Available PostgreSQL Cluster](/docs/guides/postgres/clustering/ha_cluster.md) -- Monitor your PostgreSQL database with KubeDB using [built-in Prometheus](/docs/guides/postgres/monitoring/using-builtin-prometheus.md). -- Monitor your PostgreSQL database with KubeDB using [CoreOS Prometheus Operator](/docs/guides/postgres/monitoring/using-coreos-prometheus-operator.md). +- Monitor your PostgreSQL instance with KubeDB using [built-in Prometheus](/docs/guides/postgres/monitoring/using-builtin-prometheus.md). +- Monitor your PostgreSQL instance with KubeDB using [CoreOS Prometheus Operator](/docs/guides/postgres/monitoring/using-coreos-prometheus-operator.md). - Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/redis/custom-rbac/_index.md b/docs/guides/redis/custom-rbac/_index.md new file mode 100755 index 0000000000..9877832681 --- /dev/null +++ b/docs/guides/redis/custom-rbac/_index.md @@ -0,0 +1,10 @@ +--- +title: Run Redis with Custom RBAC resources +menu: + docs_0.12.0: + identifier: rd-custom-rbac + name: Custom RBAC + parent: rd-redis-guides + weight: 85 +menu_name: docs_0.12.0 +--- diff --git a/docs/guides/redis/custom-rbac/using-custom-rbac.md b/docs/guides/redis/custom-rbac/using-custom-rbac.md new file mode 100644 index 0000000000..6cced2713c --- /dev/null +++ b/docs/guides/redis/custom-rbac/using-custom-rbac.md @@ -0,0 +1,282 @@ +--- +title: Run Redis with Custom RBAC resources +menu: + docs_0.12.0: + identifier: rd-custom-rbac-quickstart + name: Custom RBAC + parent: rd-custom-rbac + weight: 10 +menu_name: docs_0.12.0 +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/concepts/README.md). + +# Using Custom RBAC resources + +KubeDB (version 0.13.0 and higher) supports finer user control over role based access permissions provided to a Redis instance. This tutorial will show you how to use KubeDB to run Redis instance with custom RBAC resources. + +## 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 [minikube](https://github.com/kubernetes/minikube). + +Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/install.md). + +To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + +```console +$ kubectl create ns demo +namespace/demo created +``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/redis](https://github.com/kubedb/docs/tree/0.12.0/docs/examples/redis) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Overview + +KubeDB allows users to provide custom RBAC resources, namely, `ServiceAccount`, `Role`, and `RoleBinding` for Redis. This is provided via the `spec.podTemplate.spec.serviceAccountName` field in Redis crd. If this field is left empty, the KubeDB operator will create a service account name matching Redis crd name. Role and RoleBinding that provide necessary access permissions will also be generated automatically for this service account. + +If a service account name is given, but there's no existing service account by that name, the KubeDB operator will create one, and Role and RoleBinding that provide necessary access permissions will also be generated for this service account. + +If a service account name is given, and there's an existing service account by that name, the KubeDB operator will use that existing service account. Since this service account is not managed by KubeDB, users are responsible for providing necessary access permissions manually. + +This guide will show you how to create custom `Service Account`, `Role`, and `RoleBinding` for a Redis instance named `quick-postges` to provide the bare minimum access permissions. + +## Custom RBAC for Redis + +At first, let's create a `Service Acoount` in `demo` namespace. + +```console +$ kubectl create serviceaccount -n demo my-custom-serviceaccount +serviceaccount/my-custom-serviceaccount created +``` + +It should create a service account. + +```yaml +$ kubectl get serviceaccount -n demo my-custom-serviceaccount -o yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + creationTimestamp: "2019-05-30T04:23:39Z" + name: my-custom-serviceaccount + namespace: demo + resourceVersion: "21657" + selfLink: /api/v1/namespaces/demo/serviceaccounts/myserviceaccount + uid: b2ec2b05-8292-11e9-8d10-080027a8b217 +secrets: +- name: myserviceaccount-token-t8zxd +``` + +Now, we need to create a role that has necessary access permissions for the Redis instance named `quick-redis`. + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/0.12.0/docs/examples/redis/custom-rbac/rd-custom-role.yaml +role.rbac.authorization.k8s.io/my-custom-role created +``` + +Below is the YAML for the Role we just created. + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: my-custom-role + namespace: demo +rules: +- apiGroups: + - policy + resourceNames: + - redis-db + resources: + - podsecuritypolicies + verbs: + - use +``` + +This permission is required for Redis pods running on PSP enabled clusters. + +Now create a `RoleBinding` to bind this `Role` with the already created service account. + +```console +$ kubectl create rolebinding my-custom-rolebinding --role=my-custom-role --serviceaccount=demo:my-custom-serviceaccount --namespace=demo +rolebinding.rbac.authorization.k8s.io/my-custom-rolebinding created + +``` + +It should bind `my-custom-role` and `my-custom-serviceaccount` successfully. + +```yaml +$ kubectl get rolebinding -n demo my-custom-rolebinding -o yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: my-custom-rolebinding + namespace: demo + resourceVersion: "1405" + selfLink: /apis/rbac.authorization.k8s.io/v1/namespaces/demo/rolebindings/my-custom-rolebinding + uid: 123afc02-8297-11e9-8d10-080027a8b217 +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: my-custom-role +subjects: +- kind: ServiceAccount + name: my-custom-serviceaccount + namespace: demo + +``` + +Now, create a Redis crd specifying `spec.podTemplate.spec.serviceAccountName` field to `my-custom-serviceaccount`. + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/0.12.0/docs/examples/redis/custom-rbac/rd-custom-db.yaml +redis.kubedb.com/quick-redis created +``` + +Below is the YAML for the Redis crd we just created. + +```yaml +apiVersion: kubedb.com/v1alpha1 +kind: Redis +metadata: + name: quick-redis + namespace: demo +spec: + version: "4.0-v2" + storageType: Durable + storage: + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: DoNotTerminate + +``` + +Now, wait a few minutes. the KubeDB operator will create necessary PVC, statefulset, services, secret etc. If everything goes well, we should see that a pod with the name `quick-redis-0` has been created. + +Check that the statefulset's pod is running + +```console +$ kubectl get pod -n demo quick-redis-0 +NAME READY STATUS RESTARTS AGE +quick-redis-0 1/1 Running 0 14m +``` + +Check the pod's log to see if the database is ready + +```console +$ kubectl logs -f -n demo quick-redis-0 +1:C 10 Jun 04:32:25.537 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo +1:C 10 Jun 04:32:25.537 # Redis version=4.0.11, bits=64, commit=00000000, modified=0, pid=1, just started +1:C 10 Jun 04:32:25.537 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf +1:M 10 Jun 04:32:25.537 * Running mode=standalone, port=6379. +1:M 10 Jun 04:32:25.537 # WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128. +1:M 10 Jun 04:32:25.537 # Server initialized +1:M 10 Jun 04:32:25.537 * Ready to accept connections +``` + +Once we see `Ready to accept connections` in the log, the database is ready. + +## Reusing Service Account + +An existing service account can be reused in another Redis instance. No new access permission is required to run the new Redis instance. + +Now, create Redis crd `minute-redis` using the existing service account name `my-custom-serviceaccount` in the `spec.podTemplate.spec.serviceAccountName` field. + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/0.12.0/docs/examples/redis/custom-rbac/rd-custom-db-two.yaml +redis.kubedb.com/quick-redis created +``` + +Below is the YAML for the Redis crd we just created. + +```yaml +apiVersion: kubedb.com/v1alpha1 +kind: Redis +metadata: + name: minute-redis + namespace: demo +spec: + version: "4.0-v2" + storageType: Durable + storage: + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: DoNotTerminate + +``` + +Now, wait a few minutes. the KubeDB operator will create necessary PVC, statefulset, services, secret etc. If everything goes well, we should see that a pod with the name `minute-redis-0` has been created. + +Check that the statefulset's pod is running + +```console +$ kubectl get pod -n demo minute-redis-0 +NAME READY STATUS RESTARTS AGE +minute-redis-0 1/1 Running 0 14m +``` + +Check the pod's log to see if the database is ready + +```console +$ kubectl logs -f -n demo minute-redis-0 +1:C 10 Jun 04:32:25.537 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo +1:C 10 Jun 04:32:25.537 # Redis version=4.0.11, bits=64, commit=00000000, modified=0, pid=1, just started +1:C 10 Jun 04:32:25.537 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf +1:M 10 Jun 04:32:25.537 * Running mode=standalone, port=6379. +1:M 10 Jun 04:32:25.537 # WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128. +1:M 10 Jun 04:32:25.537 # Server initialized +1:M 10 Jun 04:32:25.537 * Ready to accept connections +``` + +`Ready to accept connections` in the log signifies that the database is running successfully. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```console +kubectl patch -n demo rd/quick-redis -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge" +kubectl delete -n demo rd/quick-redis + +kubectl patch -n demo rd/minute-redis -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge" +kubectl delete -n demo rd/minute-redis + +kubectl delete -n demo role my-custom-role +kubectl delete -n demo rolebinding my-custom-rolebinding + +kubectl delete sa -n demo my-custom-serviceaccount + +kubectl delete ns demo +``` + +If you would like to uninstall the KubeDB operator, please follow the steps [here](/docs/setup/uninstall.md). + +## Next Steps + +- [Quickstart Redis](/docs/guides/redis/quickstart/quickstart.md) with KubeDB Operator. +- [Snapshot and Restore](/docs/guides/redis/snapshot/backup-and-restore.md) process of Redis instances using KubeDB. +- Take [Scheduled Snapshot](/docs/guides/redis/snapshot/scheduled-backup.md) of Redis instances using KubeDB. +- Initialize [Redis with Script](/docs/guides/redis/initialization/using-script.md). +- Initialize [Redis with Snapshot](/docs/guides/redis/initialization/using-snapshot.md). +- Monitor your Redis instance with KubeDB using [out-of-the-box CoreOS Prometheus Operator](/docs/guides/redis/monitoring/using-coreos-prometheus-operator.md). +- Monitor your Redis instance with KubeDB using [out-of-the-box builtin-Prometheus](/docs/guides/redis/monitoring/using-builtin-prometheus.md). +- Use [private Docker registry](/docs/guides/redis/private-registry/using-private-registry.md) to deploy Redis with KubeDB. +- Use [kubedb cli](/docs/guides/redis/cli/cli.md) to manage databases like kubectl for Kubernetes. +- Detail concepts of [Redis object](/docs/concepts/databases/redis.md). +- Detail concepts of [Snapshot object](/docs/concepts/snapshot.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). +