forked from pivotal-cf/docs-cockroachdb-service-broker
-
Notifications
You must be signed in to change notification settings - Fork 0
/
using.html.md.erb
116 lines (87 loc) · 4.43 KB
/
using.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
---
title: Using CockroachDB Service Broker for PCF
owner: Partners
---
This topic describes how to use CockroachDB Service Broker for PCF.
##<a id='using'></a> Using CockroachDB Service Broker for PCF
## Introduction
The CRDB service broker allows binding applications to CockroachDB instances,
providing "Level 2" integration (see [pivotal
docs](https://docs.pivotal.io/tiledev/brokered.html)).
A service broker is configured to expose one or more *service plans*. Each
service plan is associated to a CockroachDB cluster or instance.
From service plans we can instantiate *service instances*. For each service
instance, a database (namespace) is created on a CockroachDB instance.
Once we have a service set up, we can *bind* it to applications. Each binding
creates a unique user/password for that application and grants permissions on
the service database. The credentials are passed via a `postgres://` URI;
applications which support Postgres may work without modifications (assuming
they don't use postgres-specific syntax that CockroachDB doesn't support).
Note that when we want different apps to be separated (different namespaces),
they should use different service instances.
## How to use
### Prerequisites
- Install the [CF CLI](https://docs.cloudfoundry.org/cf-cli/install-go-cli.html).
- [Login](https://docs.cloudfoundry.org/cf-cli/getting-started.html#login) to a CF instance.
- Set up one or more CockroachDB instances. These don't need to live on CF.
Note: for things to work with the sample `spring-music` app, a recent version
of CockroachDB which supports
[int4](https://github.com/cockroachdb/cockroach/pull/16720) must be used.
### Installing the service broker
The service broker is available as a CF tile. You can build the tile using the
[Tile Generator](https://docs.pivotal.io/tiledev/tile-generator.html) by running
`build.sh`; then upload the `product/*.pivotal` file to CF (using the ops
manager). Then you can install the tile; there is a configuration form for
specifying details for the service plans.
Note that every build bumps the tile version. CF will barf if it sees two files
with the same version that are different (even if the old one was uninstalled),
so it's best to not circumvent the version change.
After the installation, the `cf service-brokers` command should show `cockroachdb-service-broker`.
### Using the CockroachDB service
Make sure access to the service is enabled via `cf service-access`. To enable,
use `cf enable-service-access cockroachdb`. Then `cf marketplace` should list
the `cockroachdb` service with whatever plans the broker was pre-configured.
#### Create a service instance
Create a service for a specific plan:
```
cf create-service cockroachdb default crdb-service-1
```
If we log into the database, we can see that a new database has been created.
```
[email protected]:26257/> SHOW DATABASES;
+-------------------------------------+
| Database |
+-------------------------------------+
| cf_gbccnddiddnnhfdolliklaolojgmceif |
| crdb_internal |
| information_schema |
| lol |
| pg_catalog |
| system |
+-------------------------------------+
(6 rows)
```
#### Bind service instance to app
We can test things with a sample app called `spring-music`, which just exposes a
web UI to insert/remove music album information. The application supports a
postgres backend. To install it, see the [`spring-music-only-war` repo](https://github.com/svennela/spring-music-only-war).
Note: we can only use CockroachDB in insecure mode with this app (it tries to
connect without TLS, regardless of the URI).
Once `spring-music` is pushed, we can bind it to our new service:
```
cf bind-service spring-music crdb-service-1
```
This operation created a new user with access to the database associated with
`crdb-service-1`:
We can take a look at the environment for spring-music, and notice it includes a
URI to our database:
```
cf env spring-music
...
...
```
Restart the app (`cf restart spring-music`) and it should now be using our database:
```
