Extending a Pipeline to Install a Product
This how-to-guide will teach you how to add a product to an existing pipeline. This includes downloading the product from Pivnet, extracting configuration, and installing the configured product. If you don't already have an Ops Manager and deployed Director, check out Installing Ops Manager and Deploying the Director respectively.
- A pipeline, such as one created in Installing Ops Manager or Upgrading an Existing Ops Manager.
- A fully configured Ops Manager and Director.
- The Platform Automation Toolkit Docker Image imported and ready to run.
- A glob pattern uniquely matching one product file on Tanzu Network.
Assumptions About Your Existing Pipeline
This guide assumes you're working from one of the pipelines created in previous guides, but you don't have to have exactly that pipeline. If your pipeline is different, though, you may run into trouble with some of our assumptions.
- Resource declarations for
- A pivnet token stored in Credhub as a credential named
- A previous job responsible for deploying the director
- You have created an
env.ymlfrom the Configuring Env how-to guide. This file exists in the
- You have a
control-planewith an existing pipeline called
- You have a source control repo that contains the
You should be able to use the pipeline YAML in this document with any pipeline, as long as you make sure the above names match up with what's in your pipeline, either by changing the example YAML or your pipeline.
Download Upload And Stage Product to Ops Manager
For this guide, we're going to add the TAS product.
Before setting the pipeline, we will have to
create a config file for
in order to download TAS from Tanzu Network.
1 2 3 4 5 6
1 2 3 4 5 6
1 2 3 4 5 6
1 2 3 4 5 6
1 2 3 4 5 6
Add and commit this file to the same directory as the previous guides.
This file should be accessible from the
1 2 3
Now that we have a config file,
we can add a new
download-upload-and-stage-tas job in your
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
Now that we have a runnable job, let's make a commit
Then we can set the pipeline
If the pipeline sets without errors, run a
git push of the config.
If fly set-pipeline returns an error
Fix any and all errors until the pipeline can be set. When the pipeline can be set properly, run
1 2 3
Testing Your Pipeline
We generally want to try things out right away to see if they're working right. However, in this case, if you have a very slow internet connection and/or multiple Concourse workers, you might want to hold off until we've got the job doing more, so that if it works, you don't have to wait for the download again.
Upload and Stage
We have a product downloaded and (potentially) cached on a Concourse worker. The next step is to upload and stage that product to Ops Manager.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
Then we can re-set the pipeline
and if all is well, make a commit and push
1 2 3
Before automating the configuration and install of the product, we need a config file. The simplest way is to choose your config options in the Ops Manager UI, then pull its resulting configuration.
Advanced Tile Config Option
For an alternative that generates the configuration from the product file, using ops files to select options, see the Config Template section.
Pulling Configuration from Ops Manager
Once the product is fully configured, apply changes in the Ops Manager UI, and then continue this guide.
If You Do Not Apply Changes
Ops Manager cannot generate credentials for you
until you have applied changes (at least once).
You can still go through this process without an initial applying changes,
but you will be unable to use
om staged-config with
and may have an incomplete configuration at the end of this process.
Most products will contain the following top-level keys:
The command can be run directly using Docker.
We'll need to download the image to our local workstation, import it into Docker,
and then run
staged-config for the Tanzu Application Service product.
For more information on Running Commands Locally,
see the corresponding How-to Guide.
After the image has been downloaded from Tanzu Network
we're going to need the product name recognized by Ops Manager.
This can be found using
om, but first we should import the image
Then, we can run
om staged-products to find the name of the product in Ops Manager.
The result should be a table that looks like the following
1 2 3 4 5 6
p-bosh is the name of the director.
cf is the only other product on our Ops Manager,
we can safely assume that this is the product name for TAS.
Using the product name
let's extract the current configuration from Ops Manager.
We have a configuration file for our tile ready to back up! Almost. There are a few more steps required before we're ready to commit.
Parameterizing the Config
Look through your
tas-config.yml for any sensitive values.
These values should be
and saved off in a secrets store (in this example, we'll use Credhub).
You should still be logged into Credhub. If not, login. Be sure to note the space at the beginning of the line. This will ensure your valuable secrets are not saved in terminal history.
1 2 3 4
Logging in to credhub
Depending on your credential type,
you may need to pass
as we do above,
We use the
client approach because that's the credential type
that automation should usually be working with.
Nominally, a username represents a person,
and a client represents a system;
this isn't always exactly how things are in practice.
Use whichever type of credential you have in your case.
Note that if you exclude either set of flags,
Credhub will interactively prompt for
and hide the characters of your password when you type them.
This method of entry can be better in some situations.
The example list of some sensitive values from our
tas-config.yml are as follows,
note that this is intentionally incomplete.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
We'll start with the Cloud Controller encrypt key.
As this is a value that you might wish to rotate at some point,
we're going to store it off as a
password type into Credhub.
1 2 3 4 5
To validate that we set this correctly, we should run.
and expect an output like
1 2 3 4 5
We are then going to store off the Networking POE certs
certificate type in Credhub.
But first, we're going to save off the certificate and private key
as plain text files to simplify this process.
We named these files
There should be no formatting or indentation in these files, only new lines.
1 2 3 4 5 6
And again, we're going to validate that we set this correctly
and expect and output like
1 2 3 4 5 6 7 8 9 10 11 12 13
Remove Credentials from Disk
Once we've validated that the certs are set correctly in Credhub,
remember to delete
poe-private-key.txt from your working directory.
This will prevent a potential security leak,
or an accidental commit of those credentials.
Repeat this process for all sensitive values found in your
Once completed, we can remove those secrets from
and replace them with
The parameterized value name should match the name in Credhub.
For our example, we parameterized the config like:
1 2 3 4 5 6 7 8 9 10
tas-config.yml is parameterized to your liking,
we can finally commit the config file.
1 2 3
Configure and Apply
With the hard part out of the way, we can now configure the product and apply changes.
First, we need to update the pipeline to have a configure-product step.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82
This new job will configure the TAS product with the config file we previously created.
Next, we need to add an apply-changes job so that these changes will be applied by the Ops Manager.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60
Adding Multiple Products
When adding multiple products, you can add the configure jobs as passed constraints to the apply-changes job so that they all are applied at once. Ops Manager will handle any inter-product dependency ordering. This will speed up your apply changes when compared with running an apply changes for each product separately.
passed: [configure-tas, configure-tas-windows, configure-healthwatch]
Set the pipeline one final time, run the job, and see it pass.
Commit the final changes to your repository.
1 2 3
You have now successfully added a product to your automation pipeline.
An alternative to the staged-config workflow
outlined in the how-to guide is
config-template is an
om command that creates a base config file with optional ops files
from a given tile or pivnet slug.
This section will assume TAS, like the how-to guide above.
Generate the Config Template Directory
1 2 3 4 5 6 7
This will create or update a directory at
cd into the directory to get started creating your config.
Interpolate a Config
The directory will contain a
This is the template for the product configuration you're about to build.
Open it in an editor of your choice.
Get familiar with what's in there.
The values will be variables intended to be interpolated from other sources,
designated with the
You can find the value for any property with a default in the
This file serves as a good example of a variable source.
You'll need to create a vars file of your own for variables without default values.
For the base template, you can get a list of required variables by running
1 2 3 4 5 6
Put all those vars in a file and give them the appropriate values.
Once you've included all the variables,
the output will be the finished template.
For the rest of this guide,
we will refer to these vars as
There may be situations that call for splitting your vars across multiple files. This can be useful if there are vars that need to be interpolated when you apply the configuration, rather than when you create the final template. You might consider creating a separate vars file for each of the following cases:
- credentials (these vars can then be persisted separately/securely)
- foundation-specific variables when using the same template for multiple foundations
You can use the
--skip-missing flag when creating your final template
om interpolate to leave such vars to be rendered later.
If you're having trouble figuring out what the values should be, here are some approaches you can use:
- Look in the template where the variable appears for some additional context of its value.
- Look at the tile's online documentation
Upload the tile to an Ops Manager and visit the tile in the Ops Manager UI to see if that provides any hints.
If you are still struggling, inspecting the html of the Ops Manager webpage can more accurately map the value names to the associated UI element.
When Using The Ops Manager Docs and UI
Be aware that the field names in the UI do not necessarily map directly to property names.
The above process will get you a default installation, with no optional features or variables, that is entirely deployed in a single Availability Zone (AZ).
In order to provide non-required variables, use multiple AZs, or make non-default selections for some options, you'll need to use some of the ops files in one of the following four directories:
|features||allow the enabling of selectors for a product. For example, enabling/disabling of an s3 bucket|
|network||contains options for enabling 2-3 availability zones for network configuration|
|optional||contains optional properties without defaults. For optional values that can be provided more than once, there's an ops file for each param count|
|resource||contains configuration that can be applied to resource configuration. For example, BOSH VM extensions|
For more information on BOSH VM Extensions, refer to the Creating a Director Config File How-to Guide.
To use an ops file, add
with the path to the ops file you want to use to your
So, to enable TCP routing in Tanzu Application Service, you would add
For the rest of this guide, the vars for this feature
are referred to as
If you run your complete command, you should again get a list of any newly-required variables.
1 2 3 4 5 6 7 8 9
Finalize Your Configuration
Once you've selected your ops files and created your vars files, decide which vars you want in the template and which you want to have interpolated later.
Create a final template and write it to a file,
using only the vars you want to in the template,
--skip-missing to allow the rest to remain as variables.
1 2 3 4 5 6 7 8 9 10 11
You can check-in the resulting configuration to a git repo. For vars that do not include credentials, you can check those vars files in, as well. Handle vars that are secret more carefully.
You can then dispose of the config template directory.
Using Ops Files for Multi-Foundation
There are two recommended ways to support multiple foundation workflows: using secrets management or ops files. This section will explain how to support multiple foundations using ops files.
Starting with an incomplete Tanzu Application Service config from vSphere as an example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
For a single foundation deploy, leaving values such as
".cloud_controller.apps_domain" as-is would work fine. For multiple
foundations, this value will be different per deployed foundation. Other values,
.cloud_controller.encrypt_key have a secret that
already have a placeholder from
om. If different foundations have different
load requirements, even the values in
resource-config can be edited using
Using the example above, let's try filling in the existing placeholder for
cloud_controller.apps_domain in our first foundation.
1 2 3 4
To test that the ops file will work in your
base.yml, this can be done locally using
This will output
base.yml with the replaced(interpolated) values:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
Anything that needs to be different per deployment can be replaced via ops files as long as the
path: is correct.
Upgrading products to new patch versions:
- Configuration settings should not differ between successive patch versions within the same minor version line. Underlying properties or property names may change, but the tile's upgrade process automatically translates properties to the new fields and values.
- VMware cannot guarantee the functionality of upgrade scripts in third-party products.
Replicating configuration settings from one product to the same product on a different foundation:
- Because properties and property names can change between patch versions of a product, you can only safely apply configuration settings across products if their versions exactly match.