/
using-vol-services.html.md.erb
109 lines (92 loc) · 6.56 KB
/
using-vol-services.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
---
title: Using an External File System (Volume Services)
owner: Core Services
---
This topic describes how <%= vars.first_product_name %> app developers can read and write to a mounted file system from their apps. In <%= vars.product_name %>, a volume service provides a volume so your app can read or write to a reliable, non-ephemeral file system.
## <a id="pre"></a> Prerequisite
Before you can use a volume service with your app, <%= vars.admin %> must add a volume service to your deployment. <%= vars.add_volumes_link %>
You can run the Cloud Foundry Command Line Interface (cf CLI) `cf marketplace` command to determine if any volume services are available. See the following example output of the NFS volume service:
<pre class="terminal">
$ cf marketplace
service plans description
nfs Existing Service for connecting to NFS volumes
</pre>
If no volume service that fits your requirements exists, contact <%= vars.admin %>.
## <a id="create"></a> Create and Bind a Service Instance
To use a volume service deployed by <%= vars.admin %>, you must first create an instance of the specific volume service that you need. Follow the instructions below to create this service instance.
1. In a terminal window, run `cf create-service SERVICE-NAME PLAN SERVICE-INSTANCE -c SHARE-JSON` to create a service instance. Replace the following with the specified values:
* `SERVICE`: The name of the volume service that you want to use.
* `PLAN`: The name of the service plan. Service plans are a way for providers to offer varying levels of resources or features for the same service.
* `SERVICE-INSTANCE`: A name you provide for your service instance. Use any series of alpha-numeric characters, hyphens, and underscores. You can rename the instance at any time.
* `SHARE-JSON` (NFS Only): If you create an instance of the NFS volume service, you must supply an extra parameter, `share`, by using the `-c` flag with a JSON string, in-line or in a file. This parameter forwards information to the broker about the NFS server and share required for the service.
The following example shows creating an instance of the "Existing" NFS
service plan, passing an in-line JSON string:
<pre class="terminal">$ cf create-service nfs Existing nfs\_service\_instance -c '{"share": "10.10.10.10/export/myshare"}'</pre>
1. Run `cf bind-service YOUR-APP SERVICE-NAME -c GID-AND-UID-JSON MOUNT-PATH READ-ONLY-TRUE` to bind your service instance to an app. Replace the following with the specified values:
* `YOUR-APP`: The name of the <%= vars.product_name %> app for which you want to use the volume service.
* `SERVICE-NAME`: The name of the volume service instance you created in the previous step.
* `GID-AND-UID-JSON` (NFS only): If you bind an instance of the NFS volume service, you must supply two extra parameters, `gid` and `uid`. You can specify these parameters with the `-c` flag and a JSON string, in-line or from a file. This parameter specifies the `gid` and `uid` to use when mounting the share to the app.
* `MOUNT-PATH` (Optional): To mount the volume to a particular path within your app rather than the default path, you supply the `mount` parameter. Choose a path with a root-level folder that already exists in the container, such as `/home`, `/usr`, or `/var`.
* `READ-ONLY-TRUE` (Optional): When you issue the `cf bind-service` command, Volume Services mounts a read-write file system by default. You can specify a read-only mount by adding `"readonly":true` to the bind configuration JSON string.
<p class='note warning'><strong>Warning</strong>: Due to an underlying kernel defect, read-only NFS mounts show as <code>"mode": "rw"</code>, not <code>"mode": "ro"</code>.</p>
The following example shows binding `my-app` to the `nfs_service_instance` and specifying a read-only volume to be mounted to `/var/volume1`,
passing an in-line JSON string:
<pre class="terminal">$ cf bind-service my-app nfs\_service\_instance -c '{"uid":"1000","gid":"1000","mount":"/var/volume1","readonly":true}'</pre>
If you use an LDAP server, you must specify `username` and `password` instead of a UID and GID in this command. For example:
<pre class="terminal">$ cf bind-service my-app nfs\_service\_instance -c '{"username":"user1000","password":"secret","mount":"/var/volume1","readonly":true}'</pre>
1. Run `cf restage YOUR-APP` to complete the service binding by restaging your app. Replace `YOUR-APP` with the name of your app.
<pre class="terminal">$ cf restage my-app</pre>
## <a id='app'></a> Access the Volume Service from your App
To access the volume service from your app, you must know which file path to use in your code. You can view the file path in the details of the service binding, which are available from the [VCAP_SERVICES](../deploy-apps/environment-variable.html#view-env) environment variable. Follow the steps below.
1. Run `cf env YOUR-APP` to view environment variables for your app. Replace `YOUR-APP` with the name of your app.
<pre class="terminal">
$ cf env my-app
"VCAP\_SERVICES": {
"nfs": [
{
"credentials": {},
"label": "nfs",
"name": "nfs\_service\_instance",
"plan": "Existing",
"provider": null,
"syslog\_drain\_url": null,
"tags": [
"nfs"
],
"volume\_mounts": [
{
"container\_dir": "/var/vcap/data/153e3c4b-1151-4cf7-b311-948dd77fce64",
"device\_type": "shared",
"mode": "rw"
}
]
}
]
}
</pre>
<p class='note warning'><strong>Warning</strong>: Due to an underlying kernel defect, read-only NFS mounts show as <code>"mode": "rw"</code>, not <code>"mode": "ro"</code>.</p>
2. Use the properties under `volume_mounts` for any information your app needs. Refer to the following table:
<table>
<tr>
<th>
Property
</th>
<th>
Description
</th>
</tr>
<tr>
<td><code>container\_dir</code></td>
<td>String containing the path to the mounted volume that you bound to your app.</td>
</tr>
<tr>
<td><code>device\_type</code></td>
<td>The NFS volume release. This currently only supports `shared` devices. A `shared` device represents a distributed file system that can mount on all app instances simultaneously.</td>
</tr>
<tr>
<td><code>mode</code></td>
<td>String that informs what type of access your app has to NFS, either read-only, <code>ro</code>, or read and write, <code>rw</code>.<br><br>
Due to an underlying kernel defect, read-only NFS mounts show as <code>"mode": "rw"</code>.
</td>
</tr>
</table>