Pushing Apps with Sidecar Processes

  • Overview
  • Use Cases
  • Limitations
  • Requirements for Java Apps
    • Reserving Retentivity
    • Packaging Binaries
  • Push an App with a Sidecar Using an App Manifest
    • Prerequisites
    • Procedure
  • Sidecar Tutorial
    • About the Sample App
    • Push button the App and Sidecar
    • View the Processes Running in the Container
    • View the Web URL and App Logs

Page last updated:

This topic describes sidecar processes and how to include them when y'all push button your app.

Notation : This feature requires that your Cloud Foundry deployment uses capi-release 1.790 or afterwards.

Overview

You can run additional processes in the same container as your app. These additional processes are chosen sidecar processes, or sidecars. An case of a sidecar is an Awarding Operation Monitoring (APM) tool.

When you provide a sidecar for your app, Deject Foundry packages the required code and configuration needed to run the sidecar and app in the same droplet. It deploys this droplet in a unmarried container on Diego. Both processes within the container undergo health checks independently.

You can button sidecar processes with your app by using one of two methods:

  • Using an app manifest. For instructions, run across Button an App with a Sidecar Using an App Manifest below.
  • With a custom buildpack. For instructions, see Sidecar Buildpacks.

For additional data virtually sidecars, come across Sidecars in the Deject Foundry API (CAPI) documentation.

For sample apps that use sidecars, see the capi-sidecar-samples repository on GitHub. These sample apps employ an app manifest.

Use Cases

You can use sidecars for processes that depend on each other or must run in the same container.

For example, you tin use sidecars for processes that must:

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

Limitations

Sidecars have these limitations:

  • The starting time and end 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 non independently scalable. Sidecars share resources with the main app process and other sidecars within the container.

  • Sidecars but support PID-based health checks. HTTP health checks for sidecars are not currently supported.

Requirements for Java Apps

These sections describe several requirements that are specific to pushing sidecars with Java apps.

Reserving Memory

You must allocate retentivity to the sidecar. If yous do not, the Java buildpack allocates all of the bachelor memory to the app. As a consequence, the sidecar does non have enough memory and the app fails to start.

To allocate retentiveness to the sidecar, use the memory property in the app manifest. For example:

            sidecars: - name: SIDECAR-NAME     process_types: [ 'PROCESS-TYPES' ]     command: Showtime-COMMAND     memory: 256MB

Where:

  • SIDECAR-Proper noun is a proper name you give your sidecar.

  • PROCESS-TYPES is a list of app processes for the sidecar to adhere to, such as spider web or worker. Y'all can attach multiple sidecars to each process blazon your app uses.

  • START-Command is the command used to starting time the sidecar. For example, ./binary or java -jar java-file.jar.

Yous must also allocate memory to sidecars that you push with a custom buildpack. For more information, see Sidecar Buildpacks.

Packaging Binaries

If your sidecar is a binary file rather than a set of buildable source files, then you must parcel the binary file with your Java app.

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

To package the sidecar binary with the .jar file, run:

            zip JAR -u SIDECAR-BINARY

Where:

  • JAR is your .jar file.

  • SIDECAR-BINARY is your sidecar binary.

For more information about packaging assets with your Coffee app, see Tips for Coffee Developers.

Push an App with a Sidecar Using an App Manifest

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

Note: When pushing a Coffee app, ensure that you follow the requirements listed in Requirements for Java Apps to a higher place.

Prerequisites

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

  • An app that is currently running or set to exist pushed.

  • A file that Cloud Foundry can execute within the app container as a sidecar procedure. For example, an executable binary, a Coffee .jar file, or Ruby scripts.

Procedure

To push button an app with a sidecar:

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

    • If you are using cf CLI v7, run:

                          cf create-app APP-Proper name

      Where APP-Proper name is the proper name you give your app.

    • If you are using cf CLI v6, run:

                          cf v3-create-app APP-Proper noun

      Where APP-Proper noun is the name you requite your app.

      Note: This control is experimental and unsupported. Consider upgrading to cf CLI v7 to utilise a supported version of this control. To upgrade to cf CLI v7, see Install cf CLI v7 in Upgrading to cf CLI v7.

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

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

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

    Where:

    • SIDECAR-Name is a name you give your sidecar.
    • PROCESS-TYPES is a list of app processes for the sidecar to attach to, such equally web or worker. You can attach multiple sidecars to each process type your app uses.
    • START-Control is the command used to start the sidecar. For example, ./binary or java -jar java-file.jar.

      This instance manifest file includes multiple sidecars:

                    --- applications: - proper name: my-app   sidecars:    - name: authenticator      process_types: [ 'spider web', 'worker' ]      command: bundle exec run-authenticator    - name: performance monitor      process_types: [ 'web' ]      control: bundle exec run-performance-monitor

  4. To utilize the manifest file to your app:

    • If you are using cf CLI v7, run:

                          cf apply-manifest -f PATH-TO-MANIFEST

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

    • If you are using cf CLI v6, run:

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

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

      Note: This command is experimental and unsupported. Consider upgrading to cf CLI v7 to apply a supported version of this command. To upgrade to cf CLI v7, encounter Install cf CLI v7 in Upgrading to cf CLI v7.

  5. To button your app:

    • If y'all are using cf CLI v7, run:

                          cf push APP-NAME

      Where APP-Proper name is the name of your app.

    • If you are using cf CLI v6, run:

                          cf v3-button APP-NAME

      Where APP-NAME is the proper noun of your app.

      Note: This control is experimental and unsupported. Consider upgrading to cf CLI v7 to use a supported version of this control. To upgrade to cf CLI v7, see Install cf CLI v7 in Upgrading to cf CLI v7.

Sidecar Tutorial

Yous tin 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 means to observe the app and its processes after pushing.

Notation: This tutorial assumes that you are pushing the Ruby sample app. You can also follow this tutorial for a Java app using the sidecar-dependent-java-app and push_java_app_with_binary_sidecar.sh in the samples repository. When pushing a Java app, ensure that yous follow the requirements listed in Requirements for Java Apps above.

Virtually the Sample App

The capi-sidecar-samples repository contains:

  • A unproblematic Ruddy 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:

                    become '/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.torso end

  • A Golang sidecar: The config-server-sidecar produces a config-server binary. It provides apps with their required configuration over its /config endpoint. It as well accepts connections only over localhost on the CONFIG_SERVER_PORT port. This ways the sidecar must be co-located in the aforementioned container as the app, so that it shares the same network namespace every bit the main app.

The diagram below illustrates the app architecture:

Sidecar Diagram

Push the App and Sidecar

To button the app and sidecar:

  1. In a terminal window, clone the Git repository to your workspace past 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 become build -o config-server .

    Notation: If you practice non accept Go installed, download the config-server_linux_x86-64 binary from Releases in the capi-sidecar-samples repository in GitHub.

  4. To create the app:

    • If y'all are using cf CLI v7, run:

                          cf create-app sidecar-dependent-app

    • If you are using cf CLI v6, run:

                          cf v3-create-app sidecar-dependent-app

      Annotation: This control is experimental and unsupported. Consider upgrading to cf CLI v7 to apply a supported version of this command. To upgrade to cf CLI v7, see Install cf CLI v7 in Upgrading to cf CLI v7.

  5. Navigate to the sidecar-dependent-app directory.

  6. Open up and review the manifest.yml file. Under sidecars, the sidecar is specified with a name, process type, and kickoff command. Under env, in that location is an environment variable that defines the port on which the app and sidecar communicate.

  7. To use the manifest to the app:

    • If you are using cf CLI v7, run:

                          cf apply-manifest

    • If you lot are using cf CLI v6, run:

                          cf v3-apply-manifest

      Note: This command is experimental and unsupported. Consider upgrading to cf CLI v7 to use a supported version of this control. To upgrade to cf CLI v7, see Install cf CLI v7 in Upgrading to cf CLI v7.

  8. To push the app:

    • If y'all are using cf CLI v7, run:

                          cf button sidecar-dependent-app

    • If you lot are using cf CLI v6, run:

                          cf v3-push sidecar-dependent-app

      Note: This command is experimental and unsupported. Consider upgrading to cf CLI v7 to apply a supported version of this control. To upgrade to cf CLI v7, see Install cf CLI v7 in Upgrading to cf CLI v7.

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

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 procedure for the master 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 USER         PID %CPU %MEM    VSZ      RSS   TTY   STAT   Start Time  Command root           1 0.0  0.0     1120     0     ?     Southward      22:17 0:00  /tmp/garden-init vcap           7 0.0  0.0     106716   4508  ?     S      22:17 0:00  ./config-server vcap          thirteen 0.0  0.1     519688   35412 ?     South      22:17 0:00  /domicile/vcap/deps/0/vendor_bundle/ruby/ii.4.0/bin/rackup config.ru -p 8080 vcap          24 0.0  0.0     116344   10792 ?     South      22:17 0:00  /tmp/lifecycle/diego-sshd --allowedKeyExchanges= --address=0.0.0.0:2222 --allowUnauthenticatedClients=faux --inhe root          82 0.0  0.0     108012   4548  ?     South      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 South      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 come across that the sidecar is listening on the port specified by CONFIG_SERVER_PORT and that the main cherry process is connected to it, run:

                    lsof -i | grep $CONFIG_SERVER_PORT

    The output you meet should resemble the output beneath:

    vcap@f00949bd-6601-4731-6f7e-e859:~$ lsof -i | grep $CONFIG_SERVER_PORT config-se   7 vcap 3u  IPv4 17265901     0t0 TCP *:8082 (Heed) 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 Spider 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 Countersign 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 last 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 past running:

                    cf ssh sidecar-dependent-app

  6. Stop the sidecar process past running:

                    kill -9 $(pgrep config-server)

  7. View the output in the terminal window where y'all 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", "alphabetize"=>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"}
Create a pull request or raise an issue on the source for this page in GitHub