Formation Filters allow you to quickly render and deploy parts of your application, while leaving other parts undisturbed.
Filters can be positive ("only include components that match X") or negative ("don't include anything with property Y") or a combination of both.
How Formation Filters work
Filters are simple logical tests against two properties:
You can create a filter to exclude or include any of the following Skycap components:
- Helm charts
...based on whether they match a filter. When you run a deployment command using Toolbelt, you can call a Filter to intelligently include and exclude components based on your rules. For example:
cx snapshots render --stack "Hello World" --snapshot "SNAPSHOT_ID" --formation "FORMATION_ID" --filter "dev-only.json"
...will use the Filter named
dev-only.json to select which components will be subject to the
render command. Filters are technically JSON formatted files, but the syntax for writing rules is not JSON-based (see below).
Filters are logical tests enclosed in round brackets. The operators currently supported are:
==for positive matches ("equals") - for tags this also supports partial matches ("contains")
!=for negative matches ("does not equal")
An common example of a Filter would be
(tag != "dev") - this would exclude any component tagged with "dev".
You can also make chains of conditional filters using:
&&- logical AND
||- logical OR
Adding filters to a Formation
Each Formation has its own set of Filters. To add a Filters for a Formation:
- Open your Cloud 66 Dashboard and click on the Skycap application in question
- Click on the name of the Formation
- Click the Create Filters link below the name of the Formation
- Click on the green + and then choose a template
- Give your filter a name and a description to help you identify it more easily
- Add your logical rules to any of the components as needed
- Click Save Formation Filter
Once a Filter has been saved, you can call it via the Toolbelt whenever you render or deploy components. You can find a handy example of this by clicking on the name of any Filter. You can call a filter using its name or it's UUID.
Using filters with Toolbelt (cx)
Filters are primarily used via the Cloud 66 Toolbelt (cx). This can be as simple as adding a filter argument to any cx command. For example:
cx formations deploy -s "My App" -f "my-formation"
...would deploy all the components of "My App" as configured under "my-formation", whereas:
cx formations deploy -s "My App" -f "my-formation" --filter "dev-only"
...would only deploy the components specified in the "dev-only" filter and ignore the rest.
You can automatically generate a filtered cx command via your Dashboard. To do this:
- Open the Formation detail page
- Use the dropdown below the Formation's name to select a filter (if the dropdown is missing you have no filters)
- Copy the command in the yellow block below your Services panel
You can find specific
cx commands for a filter by visiting its detail page. To do this:
- Open the Formation detail page
- Click Edit Filters (just under the Formation name and the snapshot date)
- Click on the name of the filter
- The example render command is listed at the bottom of the table. You'll notice that it automatically references the current Formation and the most recent Snapshot.
cx snapshots render --stack "My App" --snapshot "SNAPSHOT_ID" --formation "my-formation" --filter "filtername"