Skip to content

Commit

Permalink
Update TPR tp CRD in docs (#116)
Browse files Browse the repository at this point in the history
  • Loading branch information
tamalsaha authored Sep 26, 2017
1 parent d71da0e commit 0546054
Show file tree
Hide file tree
Showing 14 changed files with 32 additions and 22 deletions.
11 changes: 8 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,23 @@
# KubeDB
Running production quality database in Kubernetes can be tricky to say the least. In the early days of Kubernetes, replication controllers were used to run a single pod for a database. With the introduction of StatefulSet, it became easy to run a docker container for any database. But what about monitoring, taking periodic backups, restoring from backups or cloning from an existing database? KubeDB is a framework for writing operators for any database that support the following operational requirements:

- Create a database declaratively using TPR.
- Create a database declaratively using CRD.
- Take one-off backups or period backups to various cloud stores, eg, S3, GCS, etc.
- Restore from backup or clone any database.
- Native integration with Prometheus for monitoring via [CoreOS Prometheus Operator](https://github.com/coreos/prometheus-operator).
- Apply deletion lock to avoid accidental deletion of database.
- Keep track of deleted databases, cleanup prior snapshots with a single command.
- Use cli to manage databases like kubectl for Kubernetes.

KubeDB is developed at [AppsCode](https://twitter.com/AppsCodeHQ) to run their SAAS platform on Kubernetes. Currently we include complete implementations for Postgres and ElasticSearch database.

## Supported Versions
Kubernetes 1.5+
Please pick a version of KubeDB that matches your Kubernetes installation.

| KubeDB Version | Docs | Kubernetes Version |
|----------------------------------------------------------|------------------------------------------------------------|--------------------|
| [0.7.0](https://github.com/k8sdb/cli/releases/tag/0.7.0) | [User Guide](https://github.com/k8sdb/cli/tree/0.7.0/docs) | 1.7.x+ |
| [0.6.0](https://github.com/k8sdb/cli/releases/tag/0.6.0) | [User Guide](https://github.com/k8sdb/cli/tree/0.6.0/docs) | 1.5.x - 1.7.x |

## Installation
To install KubeDB, please follow the guide [here](/docs/install.md).
Expand Down
2 changes: 1 addition & 1 deletion ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,4 @@
## Versioning Policy
There are 2 parts to versioning policy:
- Operator & cli version: KubeDB follows semver versioning policy. Until 1.0 release is done, there might be breaking changes between point releases of the operator. Please always check the release notes for upgrade instructions.
- TPR version: `kubedb.com/v1alpha1` is considered in alpha. This means breaking changes to the YAML format might happen among different releases of the operator.
- CRD version: `kubedb.com/v1alpha1` is considered in alpha. This means breaking changes to the YAML format might happen among different releases of the operator.
11 changes: 8 additions & 3 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,23 @@
# KubeDB
Running production quality database in Kubernetes can be tricky to say the least. In the early days of Kubernetes, replication controllers were used to run a single pod for a database. With the introduction of StatefulSet, it became easy to run a docker container for any database. But what about monitoring, taking periodic backups, restoring from backups or cloning from an existing database? KubeDB is a framework for writing operators for any database that support the following operational requirements:

- Create a database declaratively using TPR.
- Create a database declaratively using CRD.
- Take one-off backups or period backups to various cloud stores, eg,, S3, GCS, etc.
- Restore from backup or clone any database.
- Native integration with Prometheus for monitoring via [CoreOS Prometheus Operator](https://github.com/coreos/prometheus-operator).
- Apply deletion lock to avoid accidental deletion of database.
- Keep track of deleted databases, cleanup prior snapshots with a single command.
- Use cli to manage databases like kubectl for Kubernetes.

KubeDB is developed at [AppsCode](https://twitter.com/AppsCodeHQ) to run their SAAS platform on Kubernetes. Currently we include complete implementations for Postgres and ElasticSearch database.

## Supported Versions
Kubernetes 1.5+
Please pick a version of KubeDB that matches your Kubernetes installation.

| KubeDB Version | Docs | Kubernetes Version |
|----------------------------------------------------------|------------------------------------------------------------|--------------------|
| [0.7.0](https://github.com/k8sdb/cli/releases/tag/0.7.0) | [User Guide](https://github.com/k8sdb/cli/tree/0.7.0/docs) | 1.7.x+ |
| [0.6.0](https://github.com/k8sdb/cli/releases/tag/0.6.0) | [User Guide](https://github.com/k8sdb/cli/tree/0.6.0/docs) | 1.5.x - 1.7.x |

## Installation
To install KubeDB, please follow the guide [here](/docs/install.md).
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/elasticsearch.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
# Elasticsearch

## What is Elasticsearch
A `Elasticsearch` is a Kubernetes `Third Party Object` (TPR). It provides declarative configuration for [Elasticsearch](https://www.elastic.co/products/elasticsearch) in a Kubernetes native way. You only need to describe the desired database configuration in a Elasticsearch object, and the KubeDB operator will create Kubernetes objects in the desired state for you.
A `Elasticsearch` is a Kubernetes `Third Party Object` (CRD). It provides declarative configuration for [Elasticsearch](https://www.elastic.co/products/elasticsearch) in a Kubernetes native way. You only need to describe the desired database configuration in a Elasticsearch object, and the KubeDB operator will create Kubernetes objects in the desired state for you.

## Elasticsearch Spec
As with all other Kubernetes objects, a Elasticsearch needs `apiVersion`, `kind`, and `metadata` fields. It also needs a `.spec` section. Below is an example Elasticsearch object.
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/monitoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ If enabled, a __side-car exporter pod__ is run with database pods to expose Prom

- `/kubedb.com/v1beta1/namespaces/:ns/(postgreses|elastics)/:name/metrics`: Scrape this endpoint to monitor database.

First deploy Prometheus operator so that Prometheus TPR groups are registered. Then, to monitor KubeDB databases by Prometheus, set following fields in `spec.monitor.prometheus`:
First deploy Prometheus operator so that Prometheus CRD groups are registered. Then, to monitor KubeDB databases by Prometheus, set following fields in `spec.monitor.prometheus`:

```yaml
spec:
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/postgres.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
# Postgres

## What is Postgres
A `Postgres` is a Kubernetes `Third Party Object` (TPR). It provides declarative configuration for [PostgreSQL](https://www.postgresql.org/) in a Kubernetes native way. You only need to describe the desired database configuration in a Postgres object, and the KubeDB operator will create Kubernetes objects in the desired state for you.
A `Postgres` is a Kubernetes `Third Party Object` (CRD). It provides declarative configuration for [PostgreSQL](https://www.postgresql.org/) in a Kubernetes native way. You only need to describe the desired database configuration in a Postgres object, and the KubeDB operator will create Kubernetes objects in the desired state for you.

## Postgres Spec
As with all other Kubernetes objects, a Postgres needs `apiVersion`, `kind`, and `metadata` fields. It also needs a `.spec` section. Below is an example Postgres object.
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/snapshot.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
# Snapshot

## What is Snapshot
A `Snapshot` is a Kubernetes `Third Party Object` (TPR). It provides declarative configuration for database snapshots in a Kubernetes native way.
A `Snapshot` is a Kubernetes `Third Party Object` (CRD). It provides declarative configuration for database snapshots in a Kubernetes native way.
You only need to describe the desired backup behavior in a Snapshot object. KubeDB operator will launch a Job to perform backup operation. Once the snapshot process is complete, it uploads the snapshot data to various cloud providers S3, GCS, Azure, OpenStack Swift and/or locally mounted volumes using [osm](https://github.com/appscode/osm).

## Snapshot Spec
Expand Down
4 changes: 2 additions & 2 deletions docs/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,9 +55,9 @@ $ 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 TPR groups have been registered by the operator, run the following command:
Now, to confirm CRD groups have been registered by the operator, run the following command:
```console
$ kubectl get thirdpartyresources -l app=kubedb
$ kubectl get crd -l app=kubedb
```

Now, you are ready to [create your first database](/docs/tutorials/README.md) using KubeDB.
Expand Down
4 changes: 2 additions & 2 deletions docs/tutorials/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ KubeDB comes with its own cli. It is called `kubedb` cli. `kubedb` can be used t

### How to Create objects

`kubedb create` creates a database tpr in `default` namespace by default. Following command will create a Postgres TPR as specified in `postgres.yaml`.
`kubedb create` creates a database tpr in `default` namespace by default. Following command will create a Postgres CRD as specified in `postgres.yaml`.

```console
$ kubedb create -f ./docs/examples/postgres/postgres.yaml
Expand Down Expand Up @@ -334,7 +334,7 @@ $ kubedb delete postgres -l postgres.kubedb.com/name=postgres-demo
To learn about various options of `delete` command, please visit [here](/docs/reference/kubedb_delete.md).

## Using Kubectl
Kubectl has limited support for TPRs in general. You can use Kubectl with KubeDB objects like any other TPRs. Below are some common examples of using Kubectl with KubeDB objects.
Kubectl has limited support for CRDs in general. You can use Kubectl with KubeDB objects like any other CRDs. Below are some common examples of using Kubectl with KubeDB objects.

```console
# List objects
Expand Down
2 changes: 1 addition & 1 deletion docs/tutorials/elasticsearch.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ kube-system Active 3m
```

## Create an Elasticsearch database
KubeDB implements a `Elasticsearch` TPR to define the specification of an Elasticsearch database. Below is the `Elasticsearch` object created in this tutorial.
KubeDB implements a `Elasticsearch` CRD to define the specification of an Elasticsearch database. Below is the `Elasticsearch` object created in this tutorial.

```yaml
apiVersion: kubedb.com/v1alpha1
Expand Down
6 changes: 3 additions & 3 deletions docs/tutorials/monitoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,14 @@ NAME READY STATUS RESTARTS AGE
prometheus-operator-449376836-4pkzn 1/1 Running 0 15s
^C⏎

$ kubectl get thirdpartyresources
$ kubectl get crd
NAME DESCRIPTION VERSION(S)
alertmanager.monitoring.coreos.com Managed Alertmanager cluster v1alpha1
prometheus.monitoring.coreos.com Managed Prometheus server v1alpha1
service-monitor.monitoring.coreos.com Prometheus monitoring for a service v1alpha1
```

Once the Prometheus operator TPRs are registered, run the following command to create a Prometheus.
Once the Prometheus operator CRDs are registered, run the following command to create a Prometheus.

```console
$ kubectl create -f ./docs/examples/monitoring/demo-1.yaml
Expand All @@ -46,7 +46,7 @@ $ minikube ip
Now, open your browser and go to the following URL: _http://{minikube-ip}:{prometheus-svc-nodeport}_ to visit Prometheus Dashboard. According to the above example, this URL will be [http://192.168.99.100:30900](http://192.168.99.100:30900).

## Create a PostgreSQL database
KubeDB implements a `Postgres` TPR to define the specification of a PostgreSQL database. Below is the `Postgres` object created in this tutorial.
KubeDB implements a `Postgres` CRD to define the specification of a PostgreSQL database. Below is the `Postgres` object created in this tutorial.

```yaml
apiVersion: kubedb.com/v1alpha1
Expand Down
2 changes: 1 addition & 1 deletion docs/tutorials/postgres.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ $ minikube ip
Now, open your browser and go to the following URL: _http://{minikube-ip}:{pgadmin-svc-nodeport}_. According to the above example, this URL will be [http://192.168.99.100:31188](http://192.168.99.100:31188). To log into the PGAdmin, use username __`admin`__ and password __`admin`__.

## Create a PostgreSQL database
KubeDB implements a `Postgres` TPR to define the specification of a PostgreSQL database. Below is the `Postgres` object created in this tutorial.
KubeDB implements a `Postgres` CRD to define the specification of a PostgreSQL database. Below is the `Postgres` object created in this tutorial.

```yaml
apiVersion: kubedb.com/v1alpha1
Expand Down
2 changes: 1 addition & 1 deletion docs/tutorials/rbac.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ $ minikube ip
Now, open your browser and go to the following URL: _http://{minikube-ip}:{pgadmin-svc-nodeport}_. According to the above example, this URL will be [http://192.168.99.100:31188](http://192.168.99.100:31188). To log into the PGAdmin, use username `admin` and password `admin`.

## Create a PostgreSQL database
KubeDB implements a `Postgres` TPR to define the specification of a PostgreSQL database. Below is the `Postgres` object created in this tutorial.
KubeDB implements a `Postgres` CRD to define the specification of a PostgreSQL database. Below is the `Postgres` object created in this tutorial.

```yaml
apiVersion: kubedb.com/v1alpha1
Expand Down
2 changes: 1 addition & 1 deletion docs/uninstall.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ kubectl delete snapshot.kubedb.com --all --cascade=false
kubectl delete dormant-database.kubedb.com --all --cascade=false
```

5. Delete the old TPR-registration.
5. Delete the old CRD-registration.
```console
kubectl delete thirdpartyresource -l app=kubedb
```

0 comments on commit 0546054

Please sign in to comment.