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

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 https://github.com/kubedb/cli/releases/download/0.8.0-beta.2/kubedb-linux-amd64 \
  && chmod +x kubedb \
  && sudo mv kubedb /usr/local/bin/

# Mac 64-bit
wget -O kubedb https://github.com/kubedb/cli/releases/download/0.8.0-beta.2/kubedb-darwin-amd64 \
  && 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 github.com/kubedb/cli/...

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

Install KubeDB Operator

To use kubedb, you will need to install KubeDB operator.

Using YAML

KubeDB can be installed via installer script included in the /hack/deploy folder.

$ curl -fsSL https://raw.githubusercontent.com/kubedb/cli/0.8.0-beta.2/hack/deploy/kubedb.sh | bash -s -- -h
kubedb.sh - install kubedb operator

kubedb.sh [options]

options:
-h, --help                         show brief help
-n, --namespace=NAMESPACE          specify namespace (default: kube-system)
    --rbac                         create RBAC roles and bindings
    --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-admission-webhook     configure admission webhook for kubedb CRDs
    --uninstall                    uninstall kubedb

# install without RBAC roles
$ curl -fsSL https://raw.githubusercontent.com/kubedb/cli/0.8.0-beta.2/hack/deploy/kubedb.sh \
    | bash

# Install with RBAC roles
$ curl -fsSL https://raw.githubusercontent.com/kubedb/cli/0.8.0-beta.2/hack/deploy/kubedb.sh \
    | bash -s -- --rbac

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

$ curl -fsSL https://raw.githubusercontent.com/kubedb/cli/0.8.0-beta.2/hack/deploy/kubedb.sh \
    | 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 https://raw.githubusercontent.com/kubedb/cli/0.8.0-beta.2/hack/deploy/kubedb.sh \
    | 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 https://raw.githubusercontent.com/kubedb/cli/0.8.0-beta.2/hack/deploy/kubedb.sh \
    | bash -s -- --docker-registry=MY_REGISTRY [--image-pull-secret=SECRET_NAME] [--rbac]

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

$ curl -fsSL https://raw.githubusercontent.com/kubedb/cli/0.8.0-beta.2/hack/deploy/kubedb.sh \
    | bash -s -- --enable-admission-webhook [--rbac]

Using Helm

KubeDB can be installed via Helm using the chart included in this repository. To install the chart with the release name my-release:

# Mac OSX amd64:
curl -fsSL -o onessl https://github.com/kubepack/onessl/releases/download/0.1.0/onessl-darwin-amd64 \
  && chmod +x onessl \
  && sudo mv onessl /usr/local/bin/

# Linux amd64:
curl -fsSL -o onessl https://github.com/kubepack/onessl/releases/download/0.1.0/onessl-linux-amd64 \
  && chmod +x onessl \
  && sudo mv onessl /usr/local/bin/

# Linux arm64:
curl -fsSL -o onessl https://github.com/kubepack/onessl/releases/download/0.1.0/onessl-linux-arm64 \
  && chmod +x onessl \
  && sudo mv onessl /usr/local/bin/

# Kubernetes 1.8.x
$ helm repo update
$ helm install stable/kubedb --name my-release

# Kubernetes 1.9.0 or later
$ helm repo update
$ helm install stable/kubedb --name my-release \
  --set apiserver.ca="$(onessl get kube-ca)" \
  --set apiserver.enableAdmissionWebhook=true

To see the detailed configuration options, visit here.

Verify 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.

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.