Pushing Apps with Sidecar Processes (Beta)

Page last updated:

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


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, PCF 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 undergo health checks independently.

For additional information about sidecars, see the Sidecars section of the CAPI v3 documentation.

For sample apps that use sidecars, see the capi-sidecar-samples repository on GitHub. This topic shows you how to push one of these sample apps.

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:

  • Communicate over a Unix socket or through localhost
  • Share the same filesystem
  • Be scaled and placed together
  • Have fast interprocess communication


Sidecars have these limitations:

  • Sidecars do not work with Java apps.
  • 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 does also.

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

Push an App with a Sidecar

These sections explain how to push an app with a sidecar. For an example that you can try yourself, see Sidecar Tutorial.


Before you can push an app with a sidecar, you must have:

  • An app that is currently running or ready to be pushed.

  • A file that PCF can execute inside the app container as a sidecar process. For example, an executable binary, a Java .jar file, or Ruby scripts.


To push an app with a sidecar:

Note: This procedure uses v3 commands because it requires the server-side manifest support in CAPI v3.

  1. Create an app or use an existing app. To create an app, run:

    cf v3-create-app APP-NAME

    Where APP-NAME is the name you give your app.

  2. Create a manifest file in the root directory of your app, such as manifest.yml. Otherwise, use an existing manifest file for your app. For more information, see Deploying with App Manifests.

  3. Add the values below to your app manifest file under the applications key:

      - name: SIDECAR-NAME
        process_types: [ 'PROCESS-TYPES' ]
        command: START-COMMAND


    • SIDECAR-NAME is a name you give your sidecar.
    • 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.
    • START-COMMAND is the command used to start the sidecar. For example, ./binary or java -jar java-file.jar.

      This example manifest file includes multiple sidecars:
    - name: my-app
       - name: authenticator
         process_types: [ 'web', 'worker' ]
         command: bundle exec run-authenticator
       - name: performance monitor
         process_types: [ 'web' ]
         command: bundle exec run-performance-monitor
  4. Apply the manifest file to your app by running:

    cf v3-apply-manifest -f PATH-TO-MANIFEST

    Where PATH-TO-MANIFEST is the path to your manifest file.

  5. Push your app by running:

    cf v3-push APP-NAME

    Where APP-NAME is the name of your app.

Sidecar Tutorial

You can explore sidecars using the app in the capi-sidecar-samples repository on GitHub. 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.

About the Sample App

The capi-sidecar-samples repository contains:

  • A simple Ruby app: This app is named sidecar-dependent-app. It includes a /config endpoint that calls to the sidecar and prints the response, as shown in this 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"
  • A Golang sidecar: 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

Push the App and Sidecar

To push the app and sidecar:

  1. In a terminal window, clone the Git repository to your workspace by running:

    git clone https://github.com/cloudfoundry-samples/capi-sidecar-samples.git
  2. Navigate to the config-server-sidecar directory.

  3. Build the binary for the sidecar by running:

    GOOS=linux GOARCH=amd64 go build -o config-server .

    Note: If you do not have Go installed, download the config-server_linux_x86-64 binary from the Releases section of the capi-sidecar-samples repository in GitHub.

  4. Create the app by running:

    cf v3-create-app sidecar-dependent-app
  5. Navigate to the sidecar-dependent-app directory.

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

  7. Apply the manifest to the app by running:

    cf v3-apply-manifest
  8. Push the app by running:

    cf v3-push sidecar-dependent-app

After you push the app, you can further explore it in View the Processes Running in the Container and View the Web URL and App Logs.

View the Processes Running in the Container

To view the app and sidecar process running in the container:

  1. SSH into the app container by running:

    cf ssh sidecar-dependent-app
  2. To see both the rackup process for the main app and config-server process for the sidecar, run:

    ps aux

    The output you see should resemble the output below:

    vcap@f00949bd-6601-4731-6f7e-e859:~$ ps aux
    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= --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    
  3. 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, run:

    lsof -i | grep $CONFIG_SERVER_PORT

    The output you see should resemble the output below:

    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)
    uby       13 vcap 11u  IPv4 17274965    0t0 TCP localhost:42266->localhost:8082 (ESTABLISHED)

View the Web URL and App Logs

To view the Web URL and logs for the app:

  1. In a browser, navigate to the config endpoint of the sidecar-dependent-app. For example: https://sidecar-dependent-app.example.com/config.

  2. See that the browser displays Scope and Password information. This is the configuration that the app fetches from the config-server sidecar.

  3. In a terminal window, begin streaming logs for the app by running:

    cf logs sidecar-dependent-app
  4. 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.

  5. In a separate terminal window from your log stream, SSH into the app container by running:

    cf ssh sidecar-dependent-app
  6. Terminate the sidecar process by running:

    kill -9 $(pgrep config-server)
  7. 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:

    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,