Please put the cloud controller job spec in the conventional location

[shalako]

Issue

I need to reference the cloud controller job spec to discover the use of a manifest property. I expect to find it in /jobs/cloud_controller_ng. Instead I must trace the thread through to cloud_controller's own repo and find the job spec hidden in /bosh/jobs/cloud_controller_ng/spec.

First, the job spec is a BOSH release artifact, and has no meaning in the context of a standalone component.

Second, this location his highly unconventional and so challenging to find.

Third, the job spec should be considered your configuration documentation for the component within the context of the BOSH release. Putting it in the conventional place enables operators to understand how to configure the component via a BOSH manifest.

Steps to Reproduce

1. Look for the CAPI job spec
2. Spend much longer finding it than it should take

Expected result

Find the CAPI job spec at https://github.com/cloudfoundry/capi-release/blob/master/jobs/cloud_controller_ng/spec

Current result

1. Find that https://github.com/cloudfoundry/capi-release/blob/develop/jobs/cloud_controller_ng is a link to ../src/cloud_controller_ng/bosh/jobs/cloud_controller_ng.
2. Retrace your steps up the tree and back down through /src/cloud_controller_ng @ 4423884 which takes you to the CC repo
3. Get lost, try looking through several directories, before going back to https://github.com/cloudfoundry/capi-release/blob/develop/jobs/cloud_controller_ng to remind yourself of the unconventional path
4. Eventually find your way to https://github.com/cloudfoundry/cloud_controller_ng/blob/b44ae3cb312841b7dd8f8b3cf39eab6fe95ede55/bosh/jobs/cloud_controller_ng/spec

Possible Fix

Put the spec in the expected location: capi-release under /jobs/cloud_controller_ng/spec

[cf-gitbot]

We have created an issue in Pivotal Tracker to manage this:

https://www.pivotaltracker.com/story/show/149204143

The labels on this github issue will be updated when the story is started.

[ljfranklin]

@Gerg I think this seems reasonable as it nicely groups all our bosh stuff together although the team would have to re-learn a bit of muscle memory. WDYT?

[cppforlife]

+2 for me and james m

…

Sent from my iPhone

On Aug 31, 2017, at 5:55 PM, Lyle Franklin ***@***.***> wrote: @Gerg I think this seems reasonable as it nicely groups all our bosh stuff together although the team would have to re-learn a bit of muscle memory. WDYT? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[Gerg]

We discussed this as a team, and we agreed that it makes sense to move these files to their conventional locations. That said, we have other engineering priorities currently, so we will probably not work on this in the near future.

[rainmaker]

Hi Shannon,

Thanks for bringing this up. Legibility of our release is important to us, and this is a positive change in that direction. Just an FYI that we've committed these changes to develop, and they should be rolling onto master at our next release, provided that we don't see any unforeseen consequences of moving the job specs around. Hopefully it's more discoverable now.

We also realize that the shared_job_templates directory is still somewhat unconventional, since it's now stored at the top-level of the bosh release and results in symlinks being located under jobs/cloud_controller*/templates/. It seemed like much of your concern was around the location of the job spec file, so maybe this isn't as much of an issue for you. If you feel strongly about it, let us know.

Thanks for your recommendation!

Raina