[improvement] Better documentation for stub generation about cf-deployment HOT 6 CLOSED

We have created an issue in Pivotal Tracker to manage this. You can view the current status of your issue at: https://www.pivotaltracker.com/story/show/107818544.

from cf-deployment.

Thanks @voelzmo

Does 4f3a5b3 adequately address your issue?

Best,
Amit

from cf-deployment.

Thanks @Amit-PivotalLabs those platform specific links are more helpful than the generic one.

However, looking at the stub for aws for example, I feel like there are a few aspects missing:

• You probably want to configure the instances of your jobs
• There are a bunch of properties set to null if you deploy using just instance configuration and the above aws stub (e.g. all the consul.*_cert and consul.*_key stuff)
  • What would be the process to discover potentially interesting properties for me as a user? Look through all null values in the generated manifest and check if I should be setting those?
  • Any recommendation which of the properties would I put where? I'm thinking about a threefold separation probably: 'normal' properties, credentials, and instance configuration. Does that sound reasonable? I know this might be highly subjective but it would be interesting to hear/see some guidance from you there.

from cf-deployment.

There is a tradeoff to be made in those stubs -- they should be simple enough that someone can edit a few obvious lines without having to know too much, and get something up and running, but they should also have some flexibility to make something suited to their environment. We err on the side of simplicity, as it's the only thing we have to offer the first-time user. We assume (for now) the power user knows how to modify the stub or the manifest to handle extra variations. We also don't want the example stubs to show you how to do every possible thing, because at some point you're basically just writing your own manifest from scratch.

In the long run, we want to improve manifest generation, and think outside the constraints of improving the stubs. In the short run, we should improve the stubs; that is outside the scope of this repo in particular, but thank you for raising it. I have a (long-running) story in flight to address this exactly: https://www.pivotaltracker.com/story/show/105805252

To answer your other questions:

What would be the process to discover potentially interesting properties for me as a user?

We unfortunately don't have a great story the user who is in between first-time and power user. The first-time user should not care. The power user who is using spiff could look at those null values. The even more powerful user could look at the job specs for all the jobs, that is the real source of truth for what is configurable.

Any recommendation which of the properties would I put where? I'm thinking about a threefold separation probably: 'normal' properties, credentials, and instance configuration. Does that sound reasonable?

You could try something like:

• non-credential properties
• credential properties
• instance counts
• persistent disk counts
• release versions (if you don't want to just use latest)
• additional colocated jobs and releases
• IaaS settings (any cloud properties, IP ranges, etc.)

Diego does some of this sort of separation: https://github.com/cloudfoundry-incubator/diego-release/blob/develop/scripts/generate-deployment-manifest

In the long run, what would be great is for some of these things to become primitives bosh knows about. Tell bosh directly about instance counts, rather than telling spiff to merge it into some template. What would also be great is some sort of static analysis to tell you whether you have all the required data, any extraneous data, etc. and have it not matter whether you've split things into separate files or one file; we should be able to programmatically validate your input agnostic to how you've actually organized it on the file system.

from cf-deployment.

@voelzmo

I believe the above comment answers your questions, but please feel free to re-open/open a new issue if not.

Cheers,
Amit

from cf-deployment.

Thanks @Amit-PivotalLabs for the thorough and detailed answer!

Totally agree on that we want static analysis of manifest data and that bosh should know about some of these settings as primitives.

from cf-deployment.