Takipi Agent Framework

This change adds the Takipi agent framework to the buildpack. This framework
supports both the local and remote collector approaches for using the Takipi
agent.

[#472]

Author: chook

README.md

@@ -98,6 +98,7 @@ To learn how to configure various properties of the buildpack, follow the "Confi
   * [ProtectApp Security Provider](docs/framework-protect_app_security_provider.md) ([Configuration](docs/framework-protect_app_security_provider.md#configuration))
   * [Spring Auto Reconfiguration](docs/framework-spring_auto_reconfiguration.md) ([Configuration](docs/framework-spring_auto_reconfiguration.md#configuration))
   * [Spring Insight](docs/framework-spring_insight.md)
+  * [Takipi Agent](docs/framework-takipi_agent.md) ([Configuration](docs/framework-takipi_agent.md#configuration))
   * [YourKit Profiler](docs/framework-your_kit_profiler.md) ([Configuration](docs/framework-your_kit_profiler.md#configuration))
 * Standard JREs
   * [Azul Zulu](docs/jre-zulu_jre.md) ([Configuration](docs/jre-zulu_jre.md#configuration))

config/components.yml

@@ -63,5 +63,6 @@ frameworks:
   - "JavaBuildpack::Framework::SpringAutoReconfiguration"
   - "JavaBuildpack::Framework::SpringInsight"
   - "JavaBuildpack::Framework::YourKitProfiler"
+  - "JavaBuildpack::Framework::TakipiAgent"
   - "JavaBuildpack::Framework::SecurityProviders"
   - "JavaBuildpack::Framework::JavaOpts"

config/takipi_agent.yml

@@ -0,0 +1,21 @@
+# Cloud Foundry Java Buildpack
+# Copyright 2013-2017 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Configuration for the Takipi framework
+---
+version: 4.+
+repository_root: http://get.takipi.com/cloudfoundry
+node_name_prefix: node
+application_name:

docs/framework-takipi_agent.md

@@ -0,0 +1,49 @@
+# Takipi Agent Framework
+The Takipi Agent Framework causes an application to be automatically configured to work with [OverOps Service][].
+
+<table>
+  <tr>
+    <td><strong>Detection Criterion</strong></td><td>Existence of a single bound Takipi service. The existence of an Takipi service defined by the <a href="http://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES"><code>VCAP_SERVICES</code></a> payload containing a service name, label or tag with <code>app-dynamics</code> or <code>takipi</code> as a substring.
+</td>
+  </tr>
+  <tr>
+    <td><strong>Tags</strong></td><td><tt>takipi-agent=&lt;version&gt;</tt></td>
+  </tr>
+</table>
+Tags are printed to standard output by the buildpack detect script
+
+## User-Provided Service
+When binding Takipi using a user-provided service, it must have name or tag with `takipi` in it.
+The credential payload can contain the following entries. 
+
+| Name | Description
+| ---- | -----------
+| `secret_key` | (Optional) The agent installation key
+| `collector_host` | (Optional) The remote collector hostname or IP 
+| `collector_port` | (Optional) the remote collector port
+
+Setting `secret_key` will run a local collector alongside the agent. Setting `collector_host` will use a remote collector. More information can be found in [OverOps Remote Collector][]
+
+## Configuration
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
+
+The framework can be configured by modifying the [`config/takipi_agent.yml`][] file. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
+
+| Name | Description
+| ---- | -----------
+| `node_name_prefix` | Node name prefix, will be concatenated with `-` and instance index
+| `application_name` | Override the Cloudfoundry default application name
+
+## Logs
+
+Currently, you can get the Takipi agent logs using `cf files` command:
+```
+cf files app_name app/.java-buildpack/takipi_agent/log/
+```
+
+[`config/takipi_agent.yml`]: ../config/takipi_agent.yml
+[Configuration and Extension]: ../README.md#configuration-and-extension
+[repositories]: extending-repositories.md
+[version syntax]: extending-repositories.md#version-syntax-and-ordering
+[OverOps Remote Collector]: https://support.overops.com/hc/en-us/articles/227109628-Remote-Daemon-Process-
+[OverOps Service]: https://www.overops.com

lib/java_buildpack/framework/takipi_agent.rb

@@ -0,0 +1,104 @@
+# Cloud Foundry Java Buildpack
+#
+# Copyright 2013-2017 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'fileutils'
+require 'java_buildpack/component/versioned_dependency_component'
+require 'java_buildpack/framework'
+require 'java_buildpack/util/qualify_path'
+
+module JavaBuildpack
+  module Framework
+
+    # Encapsulates the functionality for enabling zero-touch OverOps (fka Takipi) support.
+    class TakipiAgent < JavaBuildpack::Component::VersionedDependencyComponent
+      include JavaBuildpack::Util
+
+      # (see JavaBuildpack::Component::BaseComponent#compile)
+      def compile
+        download_tar
+        @droplet.copy_resources
+      end
+
+      # (see JavaBuildpack::Component::BaseComponent#release)
+      def release
+        java_opts = @droplet.java_opts
+        java_opts.add_agentpath(@droplet.sandbox + 'lib/libTakipiAgent.so')
+        application_name java_opts
+        default_env_vars
+        credentials = @application.services.find_service(FILTER)['credentials']
+        config_env_vars credentials
+      end
+
+      protected
+
+      # (see JavaBuildpack::Component::VersionedDependencyComponent#supports?)
+      def supports?
+        @application.services.one_service? FILTER, [SECRET_KEY, COLLECTOR_HOST]
+      end
+
+      private
+
+      FILTER = /takipi/
+
+      SECRET_KEY = 'secret_key'.freeze
+
+      COLLECTOR_HOST = 'collector_host'.freeze
+
+      private_constant :FILTER
+
+      def jvm_lib_file
+        @droplet.java_home.root + 'lib/amd64/server/libjvm.so'
+      end
+
+      def default_env_vars
+        env = @droplet.environment_variables
+        sandbox = @droplet.sandbox
+
+        env.add_environment_variable(
+          'LD_LIBRARY_PATH',
+          "$LD_LIBRARY_PATH:#{qualify_path(sandbox + 'lib', @droplet.root)}"
+        )
+        env.add_environment_variable('JVM_LIB_FILE', jvm_lib_file)
+        env.add_environment_variable('TAKIPI_HOME', sandbox)
+        env.add_environment_variable('TAKIPI_MACHINE_NAME', node_name)
+      end
+
+      def config_env_vars(credentials)
+        env = @droplet.environment_variables
+
+        secret_key = credentials['secret_key']
+        env.add_environment_variable 'TAKIPI_SECRET_KEY', secret_key if secret_key
+
+        collector_host = credentials['collector_host']
+        env.add_environment_variable 'TAKIPI_MASTER_HOST', collector_host if collector_host
+
+        collector_port = credentials['collector_port']
+        env.add_environment_variable 'TAKIPI_MASTER_PORT', collector_port if collector_port
+      end
+
+      def application_name(java_opts)
+        app_name = @configuration['application_name'] || @application.details['application_name']
+        java_opts.add_system_property('takipi.name', app_name)
+      end
+
+      def node_name
+        "#{@configuration['node_name_prefix']}-$CF_INSTANCE_INDEX"
+      end
+
+    end
+
+  end
+end

spec/fixtures/stub-takipi-agent.tar.gz

@@ -0,0 +1,105 @@
+# Cloud Foundry Java Buildpack
+# Copyright 2013-2017 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'spec_helper'
+require 'component_helper'
+require 'java_buildpack/framework/takipi_agent'
+require 'java_buildpack/util/find_single_directory'
+
+describe JavaBuildpack::Framework::TakipiAgent do
+  include_context 'component_helper'
+
+  let(:configuration) do
+    {
+      'node_name_prefix' => nil
+    }
+  end
+
+  it 'does not detect without takipi-n/a service' do
+    expect(component.detect).to be_nil
+  end
+
+  context do
+
+    let(:credentials) { {} }
+
+    before do
+      allow(services).to receive(:one_service?).with(/takipi/, %w[secret_key collector_host]).and_return(true)
+      allow(services).to receive(:find_service).and_return('credentials' => credentials)
+    end
+
+    it 'expands Takipi agent tarball',
+       cache_fixture: 'stub-takipi-agent.tar.gz' do
+
+      component.compile
+
+      expect(sandbox + 'lib/libTakipiAgent.so').to exist
+    end
+
+    it 'preserves find_single_directory results',
+       cache_fixture: 'stub-takipi-agent.tar.gz',
+       app_fixture: 'container_play_2.1_dist' do
+      component.compile
+      component.send(:extend, JavaBuildpack::Util)
+      expect(component.send(:find_single_directory)).not_to be_nil
+    end
+
+    context do
+      let(:credentials) { { 'collector_host' => 'test-host' } }
+
+      it 'updates default environment variables' do
+        component.release
+
+        expect(environment_variables)
+          .to include('LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PWD/.java-buildpack/takipi_agent/lib')
+        expect(environment_variables).to include('JVM_LIB_FILE=$PWD/.test-java-home/lib/amd64/server/libjvm.so')
+        expect(environment_variables).to include('TAKIPI_HOME=$PWD/.java-buildpack/takipi_agent')
+      end
+
+      it 'updates user environment variables' do
+        component.release
+
+        expect(environment_variables).to include('TAKIPI_MASTER_HOST=test-host')
+      end
+
+      context 'secret key' do
+        let(:credentials) { super().merge 'secret_key' => 'test-key' }
+
+        it 'secret key set' do
+          component.release
+
+          expect(environment_variables).to include('TAKIPI_SECRET_KEY=test-key')
+        end
+      end
+
+      context 'configuration overrides' do
+
+        let(:configuration) do
+          { 'node_name_prefix' => 'test-name',
+            'application_name' => 'test-name' }
+        end
+
+        it 'update application name' do
+          component.release
+          expect(java_opts).to include('-agentpath:$PWD/.java-buildpack/takipi_agent/lib/libTakipiAgent.so')
+          expect(java_opts).to include('-Dtakipi.name=test-name')
+        end
+
+      end
+    end
+
+  end
+
+end