You are looking at the documentation of a prior release. To read the documentation of the latest release, please visit here.

New to KubeDB? Please start here.

Installation Guide

There are 2 parts to installing KubeDB. You need to install a Kubernetes operator in your cluster using scripts or via Helm and download kubedb cli on your workstation. You can also use kubectl cli with KubeDB custom resource objects.

Install KubeDB Operator

To use kubedb, you will need to install KubeDB operator. KubeDB operator can be installed via a script or as a Helm chart.

Using Script

To install KubeDB in your Kubernetes cluster, run the following command:

$ curl -fsSL | bash

After successful installation, you should have a kubedb-operator-*** pod running in the kube-system namespace.

$ kubectl get pods -n kube-system | grep kubedb-operator
kubedb-operator-65d97f8cf9-8c9tj        2/2       Running   0          1m

Customizing Installer

The installer script and associated yaml files can be found in the /hack/deploy folder. You can see the full list of flags available to installer using -h flag.

$ curl -fsSL | bash -s -- -h - install kubedb operator [options]

-h, --help                             show brief help
-n, --namespace=NAMESPACE              specify namespace (default: kube-system)
    --rbac                             create RBAC roles and bindings (default: true)
    --docker-registry                  docker registry used to pull KubeDB images (default: appscode)
    --image-pull-secret                name of secret used to pull KubeDB operator images
    --run-on-master                    run KubeDB operator on master
    --enable-validating-webhook        enable/disable validating webhooks for KubeDB CRDs
    --enable-mutating-webhook          enable/disable mutating webhooks for KubeDB CRDs
    --bypass-validating-webhook-xray   if true, bypasses validating webhook xray checks
    --enable-status-subresource        if enabled, uses status sub resource for KubeDB crds
    --use-kubeapiserver-fqdn-for-aks   if true, uses kube-apiserver FQDN for AKS cluster to workaround (default true)
    --enable-analytics                 send usage events to Google Analytics (default: true)
    --install-catalog                  installs KubeDB database version catalog (default: all)
    --operator-name                    specify which KubeDB operator to deploy (default: operator)
    --uninstall                        uninstall KubeDB
    --purge                            purges KubeDB crd objects and crds

If you would like to run KubeDB operator pod in master instances, pass the --run-on-master flag:

$ curl -fsSL \
    | bash -s -- --run-on-master [--rbac]

KubeDB operator will be installed in a kube-system namespace by default. If you would like to run KubeDB operator pod in kubedb namespace, pass the --namespace=kubedb flag:

$ kubectl create namespace kubedb
$ curl -fsSL \
    | bash -s -- --namespace=kubedb [--run-on-master] [--rbac]

If you are using a private Docker registry, you need to pull required images from KubeDB’s Docker Hub account.

To pass the address of your private registry and optionally a image pull secret use flags --docker-registry and --image-pull-secret respectively.

$ kubectl create namespace kubedb
$ curl -fsSL \
    | bash -s -- --docker-registry=MY_REGISTRY [--image-pull-secret=SECRET_NAME] [--rbac]

KubeDB implements validating and mutating admission webhooks for KubeDB CRDs. This is enabled by default for Kubernetes 1.9.0 or later releases. To disable this feature, pass the --enable-validating-webhook=false and --enable-mutating-webhook=false flag respectively.

$ curl -fsSL \
    | bash -s -- --enable-validating-webhook=false --enable-mutating-webhook=false [--rbac]

KubeDB 0.11.0 or later releases can use status sub resource for CustomResourceDefintions. This is enabled by default for Kubernetes 1.11.0 or later releases. To disable this feature, pass the --enable-status-subresource=false flag.

KubeDB 0.11.0 or later installs a catalog of database versions. To disable this pass the --install-catalog=false flag.

$ curl -fsSL \
    | bash -s -- --install-catalog=false [--rbac]

Using Helm

KubeDB can be installed via Helm using the chart from AppsCode Charts Repository. To install the chart with the release name my-release:

$ helm repo add appscode
$ helm repo update
$ helm search appscode/kubedb
appscode/kubedb        	0.12.0 	0.12.0	KubeDB by AppsCode - Production ready databases on Kubern...
appscode/kubedb-catalog	0.12.0 	0.12.0	KubeDB Catalog by AppsCode - Catalog for database versions

# Step 1: Install kubedb operator chart
$ helm install appscode/kubedb --name kubedb-operator --version 0.12.0 \
  --namespace kube-system

# Step 2: wait until crds are registered
$ kubectl get crds -l app=kubedb -w
NAME                               AGE        6s         12s   8s                   8s            8s              6s       6s                7s         6s                  7s           7s              8s        7s                 6s           6s               6s

# Step 3(a): Install KubeDB catalog of database versions
$ helm install appscode/kubedb-catalog --name kubedb-catalog --version 0.12.0 \
  --namespace kube-system

# Step 3(b): Or, if previously installed, upgrade KubeDB catalog of database versions
$ helm upgrade kubedb-catalog appscode/kubedb-catalog --version 0.12.0 \
  --namespace kube-system

To see the detailed configuration options, visit here.

Installing in GKE Cluster

If you are installing KubeDB on a GKE cluster, you will need cluster admin permissions to install KubeDB operator. Run the following command to grant admin permision to the cluster.

$ kubectl create clusterrolebinding "cluster-admin-$(whoami)" \
  --clusterrole=cluster-admin \
  --user="$(gcloud config get-value core/account)"

Verify operator installation

To check if KubeDB operator pods have started, run the following command:

$ kubectl get pods --all-namespaces -l app=kubedb --watch

Once the operator pods are running, you can cancel the above command by typing Ctrl+C.

Now, to confirm CRD groups have been registered by the operator, run the following command:

$ kubectl get crd -l app=kubedb

Now, you are ready to create your first database using KubeDB.

Install KubeDB CLI

KubeDB provides a CLI to work with database objects. Download pre-built binaries from kubedb/cli Github releases and put the binary to some directory in your PATH. To install on Linux 64-bit and MacOS 64-bit you can run the following commands:

# Linux amd 64-bit
wget -O kubedb \
  && chmod +x kubedb \
  && sudo mv kubedb /usr/local/bin/

# Mac 64-bit
wget -O kubedb \
  && chmod +x kubedb \
  && sudo mv kubedb /usr/local/bin/

If you prefer to install KubeDB cli from source code, you will need to set up a GO development environment following these instructions. Then, install kubedb CLI using go get from source code.

go get

Please note that this will install KubeDB cli from master branch which might include breaking and/or undocumented changes.

Configuring RBAC

KubeDB installer will create 3 user facing cluster roles:

ClusterRoleAggregates ToDesription
kubedb:core:adminadminAllows edit access to all KubeDB CRDs, intended to be granted within a namespace using a RoleBinding. This grants ability to wipeout dormant database and delete their record.
kubedb:core:editeditAllows edit access to all KubeDB CRDs except DormantDatabase CRD, intended to be granted within a namespace using a RoleBinding.
kubedb:core:viewviewAllows read-only access to KubeDB CRDs, intended to be granted within a namespace using a RoleBinding.

These user facing roles supports ClusterRole Aggregation feature in Kubernetes 1.9 or later clusters.

Upgrade KubeDB

To upgrade KubeDB cli, just replace the old cli with the new version. To upgrade KubeDB operator, please follow the instruction for the corresponding release.