Coming Changes for App Manifest Simplification

By: | January 8, 2018
Share

Summary

The Cloud Foundry CLI team considered deprecating some App Manifest features in favor of alternative solutions that we believe better address customers’ needs. Before possibly implementing these changes, we contacted developers who use CF CLI to validate our assumptions and gain community support.

After receiving 135 survey responses, we see the community did not have strong objections to most of our proposed changes. In some cases, however, there were enough objections that we’ve decided to keep certain features.

We will deprecate three app manifest features (fewer than 20 percent objected to deprecation):

Feature to be deprecated Alternative
Promoted content (AKA global variables) YAML anchors
Inheritance Value substitution
(similar to BOSH/Concourse)
Route component attributes (domain, domains, host, no-hostname and hosts) route attributes

We will keep these app manifest features (more than 20 percent objected to deprecation):

  • Use “random-route” as an app manifest attribute
  • Ability to set attributes both in command line and in app manifest (app config, per-process config, routes, random-route)

Survey Content & Detailed Results

You can view the following documents for more details on this survey:

  • Read the full survey, including the explanation of existing app manifest features and the changes we were proposing, in this PDF.
  • Read the detailed results, including verbatim responses to each question, in this PDF.

Explanation of Changes

Here are how the three app manifest features will be deprecated in favor of existing options.


Change 1
: YAML Anchors Replace Promoted Content

Duplicated settings in YAML files are a problem that has a common solution already: YAML aliases.

The following example illustrates how to declare shared configuration using an anchor, which is then referred back to in app declarations by way of an alias.

---
defaults: &defaults
 buildpack: staticfile_buildpack
 memory: 1G

applications:
- name: bigapp
  <<: *defaults

- name: smallapp
  <<: *defaults
  memory: 256M

This approach is more verbose, as the anchors need to be assigned and the app­ level attributes with aliases need to be included in each app declaration. But this is also a benefit: it is explicit in each app’s declaration what attributes are specified when pushing the app.


Change 2
: Value Substitution May Replace Inheritance

We may introduce a value substitution feature that allows the user to use keys in attribute values of the manifest. The user would provide a separate file that defines the values for the keys. BOSH and Concourse support this approach, too.

The basic workflow would be:

$ cat manifest.yml ­­­
---
applications
-­ name: myapp
  env:
    APP_MODE: ((app­mode))

$ cat src/test/app­mode.yml
app­mode: debug

$ cf push ­--vars-file /src/test/app­mode.yml
Pushing app myapp to org myorg / space dev as admin...

Using manifest file manifest.yml
Getting app info...
Creating app with these attributes...
   name:             myapp
   instances:        1
   memory:           32M
   env:
+   APP_MODE
...

So when you push your app, you can use keys in double parentheses for values in the app manifest that you want to define outside the manifest. Because you provide the values of the keys in separate files, they can be reused. This is similar to parent manifests being reusable by different child manifests.

This approach is more verbose than app manifest inheritance, as keys need to be provided for each attribute whose value is externalized. But by being more verbose in this way, we can be more explicit and avoid the confusion caused by inheritance.


Change 3
: Attribute “route” Replaces “domain”, “domains”, “host”, “no-hostname” and “hosts”

Routes could be specified using their host(s) and/or domain(s) as below, or by using the “route” attribute with all the components at once.

---
applications
-­ name: webapp
  host: www
  domains:
­  - example.com
 ­ - example.io

The route component attributes above will be deprecated. You can specify routes by using the “route” attribute instead:

---
applications
-­ name: webapp
  routes:
  -­ route: www.example.com/foo 
  -­ route: tcp.example.com:1234

Survey Methodology

To help us decide which app manifest features we should or should not deprecate, we used a hypothesis that could be proven false for a given feature if too many app developers using CF CLI strongly objected. We defined “too many” as 20 percent or more. We worded most survey questions as “Would you strongly object if (we deprecated this feature)?”, which gave us a binary outcome of “no/not sure” or “yes” along with a separate space for qualitative feedback.

We emailed the app manifest survey to lists of developers we suspected were likely to include CF CLI app manifest users, giving them at least two weeks to reply. Those distribution lists included:

  • Cloud Foundry developer community (cf-dev@lists.cloudfoundry.org)
  • Pivotal developers (in Labs, Apps Transformation, and PCF Solutions)

Responses were collected anonymously. We gave respondents the option to provide their name and email address if they wanted us to follow up.

Feedback

We’d love your feedback on our approach with this survey and how we might improve future research with developers using Cloud Foundry CLI, such as:

  • Additional email lists or other ways to better reach the community
  • Improved experiment design (hypothesis formation, survey creation, results analysis)
  • Transparency, such as through this blog post

You can contact us on the #cli channel in Cloud Foundry Slack.

Dies Köper contributed to this post.

Jay Badenhope Profile Image

Jay Badenhope, AUTHOR

SEE ALL ARTICLES