Using: bosh create release --final --with-tarball --version <release version>
I get a package with the name <release version>.tgz.
However, it's not named as I desire and since the documentation is lacking in the use of the command line, and I didn't write the command to automate this, it would be helpful if someone could pick apart just exactly what these flags and commands do for me.
Googling again while I wait just in case I missed something!
$ bosh create release --help
Usage: bosh [options]
--force bypass git dirty state check
--final create final release
--with-tarball create release tarball
--dry-run stop before writing release manifest
--name NAME specify a custom release name
--version VERSION specify a custom version number (ex: 1.0.0 or 1.0-beta.2+dev.10)
A BOSH release is a way to package up software (source code and already-compiled binaries) to then be deployed in a distributed fashion and managed by a BOSH director, i.e. once you have a BOSH director running, you can give it a release (or multiple), and a manifest describing how you want the distributed deployment to look like (or multiple manifests) and the director will facilitate everything: deploying, upgrading, failure recovery, etc.
To create your own BOSH release, all your bits must live in a git repository that's structured in a special way. Given such a repo, you can run bosh create release from the root of the repository to produce the artifact you then later upload to the Director when you actually want to deploy.
--force: Normally the BOSH CLI will complain if your git repo is dirty, i.e. it thinks you're about to build a release with some unintentional changes. Use this flag to skip this check. Note that when you've uploaded a release to a Director, you can say bosh releases and it will tell you all the names, versions, and git commit SHAs of the uploaded releases. This can be nice if you have a release on a Director, you don't know exactly where it came from, but you can at least see the SHA so you can checkout the repo at that SHA. If you built the release from a dirty repo, you'll see a small + next to the SHA in the bosh releases output, so now you don't really know how that release was made.--with-tarball: The primary artifact created when you do bosh create release is a YAML file that describes all the packages and jobs that make up your release. When you do bosh upload release, it will determine which of these jobs and packages already exist on the director, put the rest in a tarball, and upload it to the Director. If you pass the --with-tarball flag during create release, it will put everything in a tarball. This is only useful if you want that tarball for some purpose other than immediately uploading to a Director, i.e. if you want to put the tarball in some shared location so that other people (or perhaps other steps in a CI pipeline) can use the tarball without having to re-run bosh create release or even check out the repo for that matter.--final: The YAML file described above is usually something you don't bother checking in. However, if you build a "final" release, it will place the YAML file in a different directory which you do want to check in. When creating a final release, it will make sure your blobs are also synced with a "final blobstore", so that someone checking out your repo will be able to deterministically build the same final release, because they will also get the "official" blobs from the final blobstore. Final release versions, blobs, etc. are meant to be globally unique, so that anyone using this release gets something deterministic when they use a final version of the release. "Final version" means something perhaps like "major version". This is in contrast with "Dev versions" where two developers could both be working with something called version 18+dev.20 and actually have totally different bits.--name: This is not the name of the generated file, it's the name of the release itself. I.e. it's a piece of metadata in the YAML file mentioned above. If you upload the release and do bosh releases, you will see this name. When you are writing a deployment manifest to actually deploy the stuff in the release, you will refer to it by this name.--version: Similar to name, this is the version of the release. If you don't specify your own version, BOSH will determine the version for you based on the previous version, plus whether or not you added the --final flag. If the previous version were 18+dev.20 then with --final the new version would be 19 and without, the new version would be 18+dev.21.The bosh create release command does not let you choose a location or name for the resulting tarball. You could open an issue here if that's a feature you need. However, in most use cases if you're just building the release in order to upload it to a Director, you don't need the file, bosh upload release will upload the right thing. In fact, you don't even need to pass --with-tarball in this case. On the other hand, if you need to know where the tarball is, because you're going to upload it to some shared location for instance, you can script it like this:
CF_RELEASE_OUT="${TMPDIR}/create-release.out"
bosh -n create release --with-tarball --version $VERSION | tee -a $CF_RELEASE_OUT
TARBALL=`grep -a "Release tarball" $CF_RELEASE_OUT | cut -d " " -f4`