There are two service broker behaviors that need to be updated in the docs:

• The policy structure documented in #2 will be created automatically if it doesn't exist when the service broker is provisioned in a CF space.

• By default, the service broker will also clean up these policy branches and layers when the service broker is de-provisioned from a space. This clean-up can be skipped to keep the policy structure intact by configuring the service broker with CONJUR_PRESERVE_POLICY=true.

  Per cyberark/conjur-service-broker#76 (comment):
  The value of this variable should be either true or false

Add info on new versions / platform version compatibility

Depends on cyberark/conjur-service-broker#103
Depends on cyberark/conjur-service-broker#104

Once it's possible to configure the service broker to use space-level Host identities (per the linked issues above) we should update the documentation to describe how to use this workflow. This will essentially boil down to:

1. Set ENABLE_SPACE_IDENTITY=true when deploying the Conjur service broker.
2. Pass the identity: space param when binding an app to the Conjur service

From #12 (comment)

We should include a general upgrade procedure for using the correct stemcell, or importing a new one if required.

For example, see the MySQL upgrade procedure: https://docs.pivotal.io/p-mysql/2-5/upgrade.html

The Conjur service broker can now be configured with the CONJUR_FOLLOWER_URL environment variable, which should be set to the URL of a load balancer managing Conjur followers when using a high availability cluster. During the bind request, it will be returned to the application as the URL with which to communicate with Conjur.

Add troubleshooting instructions such as:

If you encounter errors during run time, or more detailed logs are required, you can also collect logs from the deployed application. To find these logs, navigate to the VMware Tanzu Apps Manager tile. Find the organization and space for the CyberArk Conjur Service Broker, which is typically cyberark-conjur-org and cyberark-conjur-space. From there, you can view detailed application logs.

Which is modeled on the troubleshooting instructions here.

When the service broker bind context includes the the Organization GUID and Space GUID (PCF 2.0+), the service broker expects the cloudfoundry policy branch to include sub-policies and Layers for the Organizations and Spaces the service broker is added to.

When an application is bound, its Host is automatically added to the Layers for the Org and Space in which it is provisioned.

An example of this Org/Space policy is:

---
# Policy for the Organization
- !policy
  # Organization GUID from PCF.
  # This may be obtained by running `cf org --guid {org name}
  id: cbd7a05a-b304-42a9-8f66-6827ae6f78a1
  body:
    # Layer to allow privileging an entire organzation to a resource
    - !layer

    # Policy for the Spaceß
    - !policy
      # Space GUID from PCF.
      # This may be obtained by running `cf space --guid {spaceß name}
      id: 8bf39f4a-ebde-437b-9c38-3d234b80631a
      body:
        # Layer to allow privileging an entire space to a resource
        # The service broker will add applications to this layer automatically.
        - !layer

    # Grant to add the Space layer to the Org Layer
    - !grant
      role: !layer
      member: !layer 8bf39f4a-ebde-437b-9c38-3d234b80631a

This policy should be loaded into the CF Foundation branch in Conjur, for example:

conjur policy load cf/prod org_space_policy.yml

Review the CHANGELOGs for the service-broker and buildpack to determine if any additional features need to be documented. Also review cyberark/conjur-service-broker#248 to see if this needs to be documented.

AC TBA

Should include bullets / links to all relevant issues included in this release that require doc updates.

Service Broker Updates

• Version bumped to 1.0.0
• CONJUR_APPLIANCE_URL notes updated to include comment:

  When using an HA Conjur master cluster, this should be the URL of the master load balancer. This is the URL that the service broker will use to communicate with Conjur.

• New configuration option CONJUR_FOLLOWER_URL with description:

  (HA only): If using high availability, this should be the URL for a load balancer that manages the cluster's Follower instances. This is the URL that applications that bind to the service broker will use to communicate with Conjur.

• New configuration option CONJUR_PRESERVE_POLICY with description:

  By default, when the service broker is removed from a Space, it will clean up and remove the policy branches for the org and space from CONJUR_POLICY. Setting this environment variable to true will cause the org and space policy to remain in Conjur when removing the service broker.

• New functionality on provision where org / space layers are defined (see README.md) in repo for details)

For a summary of all changes made to the SB docs, see the README diff

Buildpack Updates

• Version bumped to 2.0.0
• Buildpack is converted to a supply buildpack and no longer requires the meta-buildpack; references to meta-buildpack in the documentation can be dropped

For a summary of all changes made to the BP docs, see the README diff

Supported version info

Conjur Versions Supported by Update: EE 5.0+, OSS 1.0+
PCF Versions Supported by Update: 2.0+
CF Versions Supported by Update:

• To use the auto org/space functionality your CF installation must have CAPI 1.30.0+
• To use multi-buildpack functionality your CF installation must have Diego 1.15.3+ and you must use CF CLI 6.38+
• To use OSB API 2.13 compatible service brokers, your CF installation should have CAPI 1.43.0+

We maintain support as described in the current documentation for v4.9.12.0+, but the new service broker changes will not apply - applications will continue to be added to the single app layer via a host factory.

Other info

• The documentation must be updated to refer appropriately to Conjur EE and OSS versions
• Features included in release include:
  • Service broker auto-creates org and space layers on service instance provisioin
  • Service broker auto-enrolls app hosts in org and space layers on bind
  • Service broker optionally provides URL of Conjur follower to applications
  • Buildpack is converted to a supply buildpack to support multi-buildpack usage