forked from cloudfoundry/docs-dev-guide
-
Notifications
You must be signed in to change notification settings - Fork 0
/
sidecars.html.md.erb
249 lines (167 loc) · 10.2 KB
/
sidecars.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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
---
title: Pushing Apps with Sidecar Processes (Beta)
owner: CAPI
---
This topic describes sidecar processes and how to include them when you push your app.
<%= vars.capi_sidecar_req %>
## <a id="overview"></a> Overview
You can run additional processes in the same container as your app. These are called sidecar processes, or sidecars. An example of a sidecar is an Application Performance Monitoring (APM) tool.
When you provide a sidecar for your app, Cloud Foundry packages the required code and configuration needed to run the sidecar and app in the same droplet. It deploys this droplet in a single container on Diego. Both processes within the container are health checked independently.
For additional information about sidecars, see the _Sidecars_ section of the [CAPI v3 documentation](http://v3-apidocs.cloudfoundry.org/version/release-candidate/#sidecars).
## <a id="use-case"></a> Use Cases
You can use sidecars for processes that depend on each other or must run in the same container.
For example, you can use sidecars for processes that must do the following:
* Communicate over a Unix socket or through localhost
* Share the same filesystem
* Be scaled and placed together
* Have fast interprocess communication
## <a id="limitations"></a> Limitations
Sidecars have the following limitations:
* The start and stop order of app processes and their sidecars is undefined.
* App processes and sidecars are codependent. If either crashes or exits, the other will as well.
* Sidecars are currently not independently scalable. Sidecars share resources with the main app process and other sidecars within the container.
* Sidecars only support PID-based health checks. HTTP health-checks for sidecars are not currently supported.
## <a id="create"></a> Push an App with a Sidecar
This section provides instructions for pushing an app with a sidecar. For an example that you can try yourself, see the [Sidecar Tutorial](#tutorial) section below.
### <a id="prerequisite"></a> Prerequisites
Before you can push an app with a sidecar, you must have the following:
* An app that is currently running or ready to be pushed.
* A file that Cloud Foundry can execute inside the app container as a sidecar process. For example, an executable binary, a Java .jar file, or Ruby scripts.
### <a id="create"></a> Procedure
To push an app with a sidecar, do the following:
<p class="note"><strong>Note</strong>: This procedure uses <code>v3</code> commands because it requires the server-side manifest support in CAPI v3.</p>
1. Create an app. Or, use an existing app. Run the following command to create an app:
```
cf v3-create-app MY-APP
```
Where `MY-APP` is a name that you define for your app.
1. Create a manifest file in the root directory of your app, such as `manifest.yml`. Or, use an existing manifest file for your app. For more information, see [Deploying with App Manifests](./deploy-apps/manifest.html).
1. Add the following content to your app manifest file under the `applications` key:
```
sidecars:
- name: MY-SIDECAR
process_types: [ 'MY-PROCESS-TYPES' ]
command: MY-START-COMMAND
```
Where:
* `MY-SIDECAR` is a name that you define for your sidecar.
* `MY-PROCESS-TYPES` is a list of app processes for the sidecar to attach to, such as `web` or `worker`. You can attach multiple sidecars to each process type your app uses.
* `MY-START-COMMAND` is the command used to start the sidecar. For example, `./my-binary` or `java -jar my-java-file.jar`.
See the following example manifest file that includes multiple sidecars:
```
---
applications:
- name: my-app
sidecars:
- name: authenticator
process_types: [ 'web', 'worker' ]
command: bundle exec run-authenticator
- name: performance monitor
process_types: [ 'web' ]
command: bundle exec run-performance-monitor
```
1. Apply the manifest file to your app:
```
cf v3-apply-manifest -f PATH-TO-MANIFEST
```
1. Push your app:
```
cf v3-push MY-APP
```
## <a id="tutorial"></a> Sidecar Tutorial
You can explore sidecars using the app in the [capi-sidecar-samples](https://github.com/cloudfoundry-samples/capi-sidecar-samples) repository. The sections below describe the app, how to build and push the app, and some ways to observe the app and its processes after pushing.
### <a id="about"></a> About the Sample App
The [capi-sidecar-samples](https://github.com/cloudfoundry-samples/capi-sidecar-samples) repository contains the following:
* **A simple Ruby app**<br>This app is named `sidecar-dependent-app`. It includes a `/config` endpoint that calls to the sidecar and prints the response. See the following code snippet:
```
get '/config' do
puts "Sending a request to the config-server sidecar at localhost:#{ENV['CONFIG_SERVER_PORT']}/config/"
response = Typhoeus.get("localhost:#{ENV['CONFIG_SERVER_PORT']}/config/")
puts "Received #{response.body} from the config-server sidecar"
response.body
end
```
* **A Golang sidecar**<br>The `config-server-sidecar` produces a `config-server` binary. It provides apps with their required configuration over its `/config` endpoint. It also accepts connections only over localhost on the `CONFIG_SERVER_PORT` port. This means the sidecar must be co-located in the same container as the app, so that it shares the same network namespace as the main app.
The diagram below illustrates the app architecture:
### <a id="push"></a> Push the App and Sidecar
To push the app and sidecar, do the following:
1. In a terminal window, clone the git repository to your workspace:
```
git clone https://github.com/cloudfoundry-samples/capi-sidecar-samples.git
```
1. Navigate to the `config-server-sidecar` directory.
1. Build the binary for the sidecar by running the following command:
```
GOOS=linux GOARCH=amd64 go build -o config-server .
```
<p class="note"><strong>Note</strong>: If you do not have Go installed, download the <code>config-server_linux_x86-64</code> binary from the <a href="https://github.com/cloudfoundry-samples/capi-sidecar-samples/releases">Releases</a> section of the <code>capi-sidecar-samples</code> repository in GitHub.</p>
1. Create the app:
```
cf v3-create-app sidecar-dependent-app
```
1. Navigate to the `sidecar-dependent-app` directory.
1. Open and review the `manifest.yml` file. Under `sidecars`, the sidecar is specified with a name, process type, and start command. Under `env`, there is an environment variable that defines the port on which the app and sidecar communicate.
1. Apply the manifest to the app:
```
cf v3-apply-manifest
```
1. Push the app:
```
cf v3-push sidecar-dependent-app
```
After you push the app, you can further explore it in the following sections:
* [View the Processes Running in the Container](#view-processes)
* [View the Web URL and App Logs](#view-logs)
### <a id="view-processes"></a> View the Processes Running in the Container
To view the app and sidecar process running in the container, do the following:
1. SSH into the app container:
```
cf ssh sidecar-dependent-app
```
1. Run `ps aux` to see both processes running: The `rackup` process for the main app and `config-server` process for the sidecar. For example:
<pre class="terminal">
vcap@f00949bd-6601-4731-6f7e-e859:~$ ps aux
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
root 1 0.0 0.0 1120 0 ? S 22:17 0:00 /tmp/garden-init
vcap 7 0.0 0.0 106716 4508 ? S 22:17 0:00 ./config-server
vcap 13 0.0 0.1 519688 35412 ? S 22:17 0:00 /home/vcap/deps/0/vendor_bundle/ruby/2.4.0/bin/rackup config.ru -p 8080
vcap 24 0.0 0.0 116344 10792 ? S 22:17 0:00 /tmp/lifecycle/diego-sshd --allowedKeyExchanges= --address=0.0.0.0:2222 --allowUnauthenticatedClients=false --inhe
root 82 0.0 0.0 108012 4548 ? S 22:17 0:00 /etc/cf-assets/healthcheck/healthcheck -port=8080 -timeout=1000ms -liveness-interval=30s
vcap 215 0.3 0.0 70376 3756 pts/0 S 23:12 0:00 /bin/bash
vcap 227 0.0 0.0 86268 3116 pts/0 R 23:12 0:00 ps aux
</pre>
1. Run `lsof -i | grep $CONFIG_SERVER_PORT` to see that the sidecar is listening on the port specified by `CONFIG_SERVER_PORT` and that the main `ruby` process is connected to it. For example:
<pre class="terminal">
vcap@f00949bd-6601-4731-6f7e-e859:~$ lsof -i | grep $CONFIG_SERVER_PORT
config-se 7 vcap 3u IPv4 17265901 0t0 TCP *:8082 (LISTEN)
config-se 7 vcap 5u IPv4 17265992 0t0 TCP localhost:8082->localhost:42266 (ESTABLISHED)
<rp></rp>uby 13 vcap 11u IPv4 17274965 0t0 TCP localhost:42266->localhost:8082 (ESTABLISHED)
</pre>
### <a id="view-logs"></a> View the Web URL and App Logs
To view the Web URL and logs for the app, do the following:
1. In a browser, navigate to the `config` endpoint of the `sidecar-dependent-app`. For example: `https://sidecar-dependent-app.example.com/config`.
1. See that the browser displays `Scope` and `Password` information. This is the configuration that the app fetches from the `config-server` sidecar.
1. In a terminal window, run the following command to begin streaming logs for the app:
```
cf logs sidecar-dependent-app
```
1. In your browser, refresh the `/config` endpoint page and observe that the log stream in your terminal displays logs for both the sidecar and the main app process.
1. In a separate terminal window from your log stream, SSH into the app container:
```
cf ssh sidecar-dependent-app
```
1. Terminate the sidecar process:
```
kill -9 $(pgrep config-server)
```
1. View the output in the terminal window where you are streaming the app logs. The app logs indicate that the sidecar process crashed and that Diego restarted the app container. For example:
<pre class="terminal">
2019-04-17T16:48:55.41-0700 [API/0] OUT App instance exited with guid
21df1eb8-f25d-43b2-990b-c1a417310553 payload:
{"instance"=>"a8db0eed-7371-4805-5ad3-4596", "index"=>0,
"cell_id"=>"86808ce7-afc2-47da-9e79-522a62a48cff", "reason"=>"CRASHED",
"exit_description"=>"APP/PROC/WEB/SIDECAR/CONFIG-SERVER: Exited with status 137",
"crash_count"=>1, "crash_timestamp"=>1555544935367052708,
"version"=>"50892dcb-274d-4cf6-b944-3eda1e000283"}
</pre>