Merge pull request #19 from cyberark/supply-buildpack

Buildpack is converted to a supply buildpack

CHANGELOG.md

@@ -6,26 +6,34 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+## [2.0.0] - 2019-02-15
+
+### Changed
+- Buildpack is converted to a supply buildpack to support multi-buildpack usage
+- Conjur-env binary dependencies are updated
+- Conjur-env binary converted to use Go modules
+
 ## [1.0.0] - 2018-03-01
 
 ### Changed
-Buildpack uses `conjur-env` binary built from the guts of `summon` and `conjur-api-go` instead of installing Summon and Summon-Conjur each time it is invoked.
+- Buildpack uses `conjur-env` binary built from the guts of `summon` and `conjur-api-go` instead of installing Summon and Summon-Conjur each time it is invoked.
 
 ## [0.3.0] - 2018-02-13
 
 ### Added
-Added support for v4 Conjur
+- Added support for v4 Conjur
 
 ## [0.2.0] - 2018-01-29
 
 ### Added
-Added supporting files and documentation for the custom buildpack use case
+- Added supporting files and documentation for the custom buildpack use case
 
 ## 0.1.0 - 2018-01-24
 
 The first tagged version.
 
 [Unreleased]: https://github.com/cyberark/cloudfoundry-conjur-buildpack/compare/v1.0.0...HEAD
+[2.0.0]: https://github.com/cyberark/cloudfoundry-conjur-buildpack/compare/v1.0.0...v2.0.0
 [1.0.0]: https://github.com/cyberark/cloudfoundry-conjur-buildpack/compare/v0.3.0...v1.0.0
 [0.3.0]: https://github.com/cyberark/cloudfoundry-conjur-buildpack/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/cyberark/cloudfoundry-conjur-buildpack/compare/v0.1.0...v0.2.0

CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing to the Conjur Buildpack
+
+Thanks for your interest in contributing to the Conjur Buildpack! Here
+are some guidelines on how to get started.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Pull Request Workflow](#pull-request-workflow)
+- [Updating the `conjur-env` Binary](#updating-the-conjur-env-binary)
+- [Testing](#testing)
+- [Releasing](#releasing)
+
+## Prerequisites
+
+Before getting started, you should install some developer tools. These are not required to deploy the Conjur Buildpack but they will let you develop using a standardized, expertly configured environment.
+
+1. [git][get-git] to manage source code
+2. [Docker][get-docker] to manage dependencies and runtime environments
+3. [Docker Compose][get-docker-compose] to orchestrate Docker environments
+
+[get-docker]: https://docs.docker.com/engine/installation
+[get-git]: https://git-scm.com/downloads
+[get-docker-compose]: https://docs.docker.com/compose/install
+
+In addition, if you will be making changes to the `conjur-env` binary, you should
+ensure you have [Go installed](https://golang.org/doc/install#install) locally.
+Our project uses Go modules, so you will want to install version 1.11+.
+
+### Pull Request Workflow
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+Make sure your Pull Request includes an update to the [CHANGELOG](https://github.com/cyberark/cloudfoundry-conjur-buildpack/blob/master/CHANGELOG.md) describing your changes.
+
+### Updating the `conjur-env` Binary
+
+The `conjur-env` binary uses Go modules to manage dependencies. To update the versions of `summon` / `conjur-api-go` that are included in the `conjur-env` binary in the buildpack, make sure you have Go installed locally (at least version 1.11) and run:
+
+```
+$ cd conjur-env/
+$ go get github.com/cyberark/[repo]@v[version]
+```
+
+This will automatically update go.mod and go.sum.
+
+Commit your changes, and the next time `./package.sh` is run the `vendor/conjur-env` directory will be created with updated dependencies.
+
+### Testing
+
+To test the usage of the Conjur Service Broker within a CF deployment, you can
+follow the demo scripts in the [Cloud Foundry demo repo](https://github.com/conjurinc/cloudfoundry-conjur-demo).
+
+To run the test suite on your local machine:
+```
+$ ./package.sh   # Create the conjur-env binary in the vendor dir and a ZIP of the project contents
+$ ./test.sh      # Run the test suite
+```
+
+### Releasing
+
+1. Based on the unreleased content, determine the new version number and update the [VERSION](VERSION) file. This project uses [semantic versioning](https://semver.org/).
+1. Ensure the [changelog](CHANGELOG.md) is up to date with the changes included in the release.
+1. Commit these changes - `Bump version to x.y.z` is an acceptable commit message.
+1. Once your changes have been reviewed and merged into master, tag the version
+   using `git tag -s v0.1.1`. Note this requires you to be  able to sign releases.
+   Consult the [github documentation on signing commits](https://help.github.com/articles/signing-commits-with-gpg/)
+   on how to set this up. `vx.y.z` is an acceptable tag message.
+1. Push the tag: `git push vx.y.z` (or `git push origin vx.y.z` if you are working
+   from your local machine).
+1. From a **clean checkout of master** run `./package.sh` to generate the release ZIP. Upload this to the GitHub
+   release.
+
+   **IMPORTANT** Do not upload any artifacts besides the ZIP to the GitHub release. At this time, the tile build
+   assumes the project ZIP is the only artifact.

README.md

@@ -1,39 +1,30 @@
-The CyberArk Conjur Buildpack is a [decorator buildpack](https://github.com/cf-platform-eng/meta-buildpack#what-is-a-decorator) that provides convenient and secure access to secrets stored in Conjur.
+The CyberArk Conjur Buildpack is a [supply buildpack](https://docs.cloudfoundry.org/buildpacks/custom.html#contract) that provides convenient and secure access to secrets stored in Conjur.
 
-The buildpack carries out the following:
+The buildpack supplies scripts to your application that do the following:
 
-+ Examines your app to determine the secrets to fetch using a [`secrets.yml`](https://cyberark.github.io/summon/#secrets.yml) file in the app root folder.
-+ Utilizes credentials stored in your app's [`VCAP_SERVICES`](https://docs.run.pivotal.io/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES) environment variable to communicate with the bound `cyberark-conjur` service.
-+ The buildpack will authenticate using the aforementioned credentials, fetch the relevant secrets and inject them into the session environment variables at the start of the app. This means the secrets are only available to the app process.
-
-Internally, the Conjur Buildpack uses [Summon](https://cyberark.github.io/summon/) to load secrets into the environment of CF-deployed applications based on the app's `secrets.yml` file.
++ Examine your app to determine the secrets to fetch using a [`secrets.yml`](https://cyberark.github.io/summon/#secrets.yml) file in the app root folder.
++ Retrieve credentials stored in your app's [`VCAP_SERVICES`](https://docs.run.pivotal.io/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES) environment variable to communicate with the bound `cyberark-conjur` service.
++ Authenticate using the Conjur credentials, fetch the relevant secrets from Conjur, and inject them into the session environment variables at the start of the app. The secrets are only available to the app process.
 
 ## Requirements
 
-+ The Conjur Buildpack requires the meta-buildpack. If you are unable to use the meta-buildpack (because you are using a custom buildpack, for example), see the [instructions below](#custom-buildpack-usage) for manually loading the buildpack scripts.
-
-+ Ensure that your app is bound to a Conjur service instance. For more information on binding your application to a Conjur service instance, see the [Conjur Service Broker documentation](https://github.com/conjurinc/conjur-service-broker#binding-your-application-to-the-conjur-service)
-
-+ A `secrets.yml` file exists within the root folder of your app
-
-## How does the buildpack work ?
++ Your app must be bound to a Conjur service instance. For more information on binding your application to a Conjur service instance, see the [Conjur Service Broker documentation](https://github.com/cyberark/conjur-service-broker#bind-your-application-to-the-conjur-service)
 
-### `meta-buildpack`
++ Your app must have a `secrets.yml` file in its root directory when deployed
 
-`meta-buildpack` makes it possible to "decorate" the application with the ability to retrieve secrets on startup. Please read [`meta-buildpack` documentation](https://github.com/cf-platform-eng/meta-buildpack#how-it-works) for a quick run through of how `meta-buildpack` works.
+## How Does the Buildpack Work ?
 
-`meta-buildpack` relies on automatic detection of the language buildpack. The first language buildpack in buildpack index order to detect and claim the build will be used to build the droplet and run the application. For `meta-buildpack` to be invoked, it must be at the top
-of the buildpack index and your application must automatically detect the appropriate buildpack on `cf push`. If your application requires you to specify a buildpack on `cf push`, you can follow the [instructions for apps with custom buildpacks](#custom-buildpack-usage) to benefit from the convenience of the Conjur Buildpack without having to rely on the `meta-buildpack` for it to be invoked.
+The buildpack uses a [supply script](https://docs.cloudfoundry.org/buildpacks/understand-buildpacks.html#supply-script) to copy files into the application's dependency directory under a subdirectory corresponding to the buildpack's index. The `lib/0001_retrieve-secrets.sh` script is copied into a `.profile.d` subdirectory so that it will run automatically when the app starts and the `conjur-env` binary is copied to a `vendor` subdirectory. In other words, your application will end up with the following two files:
 
-### Lifecycle scripts
-
-The buildpack is comprised of the [3 lifecycle scripts](https://github.com/cf-platform-eng/meta-buildpack#how-to-write-a-decorator) that are required for decorator buildpacks.
+```
+- $DEPS_DIR/$BUILDPACK_INDEX/.profile.d/0001-retrieve-secrets.sh
+- $DEPS_DIR/$BUILDPACK_INDEX/vendor/conjur-env
+```
 
-+ Detect script always returns a non-zero exit status.
-+ Compile script copies the `conjur-env` binary into your application's `vendor` directory and the `lib/0001_retrieve-secrets.sh` script into your application's `.profile.d` directory.
-+ Decorate script returns a 0 when `secrets.yml` exists in the root folder of your app and the "cyberark-conjur" key is present in `VCAP_SERVICES`, otherwise non-zero exit status
+The `.profile.d` script is run automatically when the application starts and is responsible for retrieving secrets and injecting them into the app's session environment variables.
 
-The `.profile.d` script is responsible for retrieving secrets and injecting them into the session environment variables at the start of the app.
+The `conjur-env` binary leverages the [Conjur Go API](https://github.com/cyberark/conjur-api-go) and [Summon](https://github.com/cyberark/summon)
+to authenticate with Conjur and retrieve secrets.
 
 The buildpack has a cucumber test suite. This validates the functionality and also offers great insight into the intended functionality of the buildpack. Please see `./ci/features`.
 
@@ -43,30 +34,26 @@ The buildpack has a cucumber test suite. This validates the functionality and al
 
 **Before you begin, ensure you are logged into your CF deployment via the CF CLI.**
 
-Install the [`meta-buildpack`](https://github.com/cf-platform-eng/meta-buildpack):
-```
-git clone [email protected]:cf-platform-eng/meta-buildpack
-cd meta-buildpack
-./build
-./upload
-```
-
-To install the Conjur Buildpack, download a ZIP of a release (at least version 1.x), unzip the release into its own directory, and run the `upload.sh` script:
+To install the Conjur Buildpack, download a ZIP of [the latest release](https://github.com/cyberark/cloudfoundry-conjur-buildpack/releases),
+unzip the release into its own directory, and run the `upload.sh` script:
 ```
 mkdir conjur-buildpack
 cd conjur-buildpack/
-curl -L $(curl -s https://api.github.com/repos/cyberark/cloudfoundry-conjur-buildpack/releases/latest | grep browser_download_url | grep zip | awk '{print $NF}' | sed 's/",*//g') > conjur-buildpack.zip
+curl -L $(curl -s https://api.github.com/repos/cyberark/cloudfoundry-conjur-buildpack/releases/latest | \
+          jq .assets[0].browser_download_url | \
+          sed 's/"//g') \
+          > conjur-buildpack.zip
 unzip conjur-buildpack.zip
 ./upload.sh
 ```
 
 Earlier versions of the Conjur Buildpack (v0.x) may be installed by cloning the repository and running `./upload.sh`.
 
-### Buildpack Usage
+### Using the Conjur Buildpack
 
-#### Create a `secrets.yml` file
+#### Create a `secrets.yml` File
 
-To use the Conjur Buildpack with a CF-deployed application, a `secrets.yml` file is required. The `secrets.yml` file gives a mapping of **environment variable name** to a **location where a secret is stored in Conjur**. For more information about creating this file, [see the Summon documentation](https://cyberark.github.io/summon/#secrets.yml). There are no sensitive values in the file itself, so it can safely be checked into source control.
+For each application that will be using the Conjur Buildpack you must create a `secrets.yml` file. The `secrets.yml` file gives a mapping of **environment variable name** to a **location where a secret is stored in Conjur**. For more information about creating this file, [see the Summon documentation](https://cyberark.github.io/summon/#secrets.yml). There are no sensitive values in the file itself, so it can safely be checked into source control.
 
 The following is an example of a `secrets.yml` file
 
@@ -86,66 +73,21 @@ AWS_REGION: us-east-1
 SSL_CERT: /tmp/ssl-cert.pem
 ```
 
-#### Push with `meta-buildpack`
-
-Before running `cf push`, ensure that:
-
-+ `meta-buildpack` is installed and at the top of list of buildpacks
-+ No buildpack is specified in your application's manifest
-+ You will not specify a buildpack with the `-b` flag on `cf push`
-
-If any of these conditions are not met, follow the [alternate usage directions](#custom-buildpack-usage) below.
-
-Once you run `cf push`, assuming the app is bound to a Conjur service instance, the `meta-buildpack` will first invoke the appropriate language buildpack and then any decorator buildpacks (including the Conjur Buildpack). The secrets specified in the `secrets.yml` file will be available in the session environment variables at the start of the app.
+#### Invoke the Buildpack at Deploy Time
 
-#### <a name="custom-buildpack-usage"></a>Usage for users with custom buildpacks
+When you deploy your application, ensure it is bound to a Conjur service instance and add the Conjur Buildpack to your `cf push` command:
 
-To retrieve secrets without using `meta-buildpack` you can simply:
-
-+ copy the contents of the `./lib` directory in a release to the `./.profile.d` directory relative to your app's root directory.
-+ copy the contents of the `./vendor` directory in a release to the `./vendor` directory relative to your app's root directory.
-
-When your application starts the secrets specified in the `secrets.yml` file will now be available in the session environment variables at the start of the app.
-
-## Development
-
-Before getting started, you should install some developer tools. These are not required to deploy the Conjur Service Broker but they will let you develop using a standardized, expertly configured environment.
-
-1. [git][get-git] to manage source code
-2. [Docker][get-docker] to manage dependencies and runtime environments
-3. [Docker Compose][get-docker-compose] to orchestrate Docker environments
-
-[get-docker]: https://docs.docker.com/engine/installation
-[get-git]: https://git-scm.com/downloads
-[get-docker-compose]: https://docs.docker.com/compose/install
-
-To test the usage of the Conjur Service Broker within a CF deployment, you can
-follow the demo scripts in the [Cloud Foundry demo repo](https://github.com/conjurinc/cloudfoundry-conjur-demo).
-
-To prepare to run the test suite on your local machine, call `./package.sh` to build the `summon` and `conjur-api-go` binaries and place them in the `vendor/` directory. Once you have done this, simply call `./test.sh`. The `test.sh` script will stand up the needed containers and run the full suite of rspec and cucumber tests.
-
-When you generate a new release, run `./package.sh` to generate a new release ZIP file and upload the ZIP file to include it with the release.
-
-### Updating the `summon` and `conjur-api-go` binaries
-
-To update the versions of `summon` / `conjur-api-go` that are included in the buildpack, update to the appropriate version number in `conjur-env/Gopkg.toml`. To update `conjur-env/vendor/` and `conjur-env/Gopkg.lock`, start up a `conjur-env` container and run `dep ensure`:
 ```
-$ docker-compose -f conjur-env/docker-compose.yml run --entrypoint bash conjur-env-builder
-# dep ensure
+cf push my-app -b conjur-buildpack -b final-buildpack
 ```
-You can verify that the correct dependencies are being used by running `dep status` from within the container before exiting and committing your changes.
-
-Once you have done this, the next time `./package.sh` is run the `vendor/conjur-env` directory will be created with updated dependencies.
 
-### Contributing
+When your application starts, the Conjur Buildpack will inject the secrets specified in the `secrets.yml` file into the application process as environment variables.
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+## Development
 
-Make sure your Pull Request includes an update to the [CHANGELOG](https://github.com/cyberark/cloudfoundry-conjur-buildpack/blob/master/CHANGELOG.md) describing your changes.
+We welcome contributions of all kinds to the Conjur Buildpack. For instructions on
+how to get started and descriptions of our development workflows, please see our
+[contributing guide](CONTRIBUTING.md). 
 
 ## License
 

VERSION

@@ -1 +1 @@
-1.0.0
+2.0.0

bin/compile

@@ -1,14 +1,5 @@
-#!/bin/bash -e
-# bin/compile <build-dir>
+#!/bin/bash
 
-echo "[cyberark-conjur-buildpack]: compiling"
+# bin/compile is currently required, even though it's deprecated. This is likely a bug.
 
-BUILD_DIR=$1
-BIN_DIR=$(cd $(dirname $0); pwd)
-BUILDPACK_DIR=$(dirname $BIN_DIR)
-
-pushd ${BUILD_DIR}
-  mkdir -p .profile.d vendor
-  cp ${BUILDPACK_DIR}/vendor/conjur-env ./vendor/conjur-env
-  cp ${BUILDPACK_DIR}/lib/0001_retrieve-secrets.sh ./.profile.d/0001_retrieve-secrets.sh
-popd
+exit