sidecars.html.md.erb

---
title: Pushing Apps with Sidecar Processes (Beta)
owner: CAPI
---

This topic describes sidecar processes and how to include them when you push your app. 

<div class="note">
<strong>Note:</strong>
This topic includes references to cf CLI v7 beta commands. Consider the following when using these commands:
<ul>
<li> cf CLI v7 beta and CAPI v3 are both in active development and subject to change. </li>
<li> cf CLI v7 beta is developed and tested against the latest CAPI release candidate. </li>
<li> cf CLI v7 beta does not yet use CAPI v3 for all commands. Some commands still use CAPI v2 during beta. </li>
</ul>
For more information, see <a href="../../cf-cli/v7.html">Upgrading to cf CLI v7 (Beta)</a>. 
</div>

<%= 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. 

<p class="note"><strong>Note</strong>: When pushing a Java app, ensure that you follow <a href="#java">Requirements for Java Apps</a>.</p>

### <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 CLI v7**

		```
		cf7 create-app MY-APP
		```
	* **cf CLI v6**

		```
		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 CLI v7**

		```
		cf7 apply-manifest -f PATH-TO-MANIFEST
		```
	* **cf CLI v6**
	
		```
		cf v3-apply-manifest -f PATH-TO-MANIFEST
		```

1. Push your app:
	* **cf CLI v7**

		```
		cf7 push MY-APP
		```
	* **cf CLI v6**

		```
		cf v3-push MY-APP
		```

## <a id="java"></a> Requirements for Java Apps

This section describes several requirements that are specific to Java apps. 

### <a id="java-sidecar-memory"></a> Reserving Memory

You must allocate memory to the sidecar. If you do not, the Java buildpack allocates all of the available memory to the app. 
As a result, the sidecar does not have enough memory and the app fails to start.

To allocate memory to the sidecar, use the `memory` property in the app manifest. See the following example: 

```
sidecars:
- name: my-sidecar
	process_types: [ 'my-process-types' ]
	command: my-start-command
	memory: 256MB
```

### <a id="java-sidecar-packaging"></a> Packaging Binaries 

The Java buildpack requires you to push a `.jar` file in some cases. If this is the case with your app, you must include the sidecar binary in the `.jar` file. 

To package the sidecar binary with the `.jar` file, run following command and replace the values for `MY-JAR` and `MY-SIDECAR-BINARY`:

```
zip MY-JAR -u MY-SIDECAR-BINARY
```

For more information about packaging assets with your Java app, see [Tips for Java Developers](https://docs.cloudfoundry.org/buildpacks/java/java-tips.html). 

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

<p class="note"><strong>Note</strong>: This tutorial assumes that you are pushing the Ruby sample app. You can also follow this tutorial for a Java app using the <code>sidecar-dependent-java-app</code> and <code>push_java_app_with_binary_sidecar.sh</code> in the samples repository. When pushing a Java app, ensure that you follow <a href="#java">Requirements for Java Apps</a>.</p>

### <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:

![Sidecar Diagram](sidecar-diagram.png)



### <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 CLI v7**

		```
		cf7 create-app sidecar-dependent-app
		```
	* **cf CLI v6**

		```
		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 CLI v7**

		```
		cf7 apply-manifest
		```
	* **cf CLI v6**

		```
		cf v3-apply-manifest
		```

1. Push the app: 
	* **cf CLI v7**

		```
		cf7 push sidecar-dependent-app
		```
	* **cf CLI v6**
	
		```
		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>