From 8434b299e01841ae0ca4c191585378e4ee8c1e1c Mon Sep 17 00:00:00 2001 From: Joseph Palermo Date: Mon, 20 Jan 2025 12:13:02 -0800 Subject: [PATCH] Bosh Release Property Validation RFC --- ...ft-add-bosh-release-property-validation.md | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 toc/rfc/rfc-draft-add-bosh-release-property-validation.md diff --git a/toc/rfc/rfc-draft-add-bosh-release-property-validation.md b/toc/rfc/rfc-draft-add-bosh-release-property-validation.md new file mode 100644 index 00000000..a8a1fea9 --- /dev/null +++ b/toc/rfc/rfc-draft-add-bosh-release-property-validation.md @@ -0,0 +1,57 @@ +# Meta +[meta]: #meta +- Name: Bosh Release Property Validation +- Start Date: 2024-01-20 +- Author(s): jpalermo +- Status: Draft +- RFC Pull Request: [community#1049](/~https://github.com/cloudfoundry/community/pull/1049) + +## Summary + +Introduce a new optional component of bosh releases that allows release authors to specify the schema for their properties. +The bosh director, prior to rendering templates, will check for the schema, and if it exists, validate the deployment +properties against it, erroring if any are not valid. + +## Problem + +Bosh currently provides no property validation mechanism, so many release authors instead perform this validation +using ruby during template rendering. We discovered in the [draft RFC for a new templating language](/~https://github.com/cloudfoundry/community/pull/1004) +that there is a large need for property validation. + +## Proposal + +We adopt [JSON Schema](https://json-schema.org/), specifically the latest draft of the schema which is 2020-12. + +Release authors would be able to place a `properties_schema.json` within a `job` folder. The bosh director +would then validate the deployment properties against the schema. + +We may also duplicate this functionality within the bosh cli so `bosh create-env` deployments would also be able +to validate the deployment properties correctly. + +JSON Schema defines several types, such as `string`, `number` and `object`. `object` allowing complex objects, the properties +of which can of their own type declarations and validations. + +The various types also have type specific keywords that can be used for additional validation such as `minLength` or +`pattern` which matches a string against a Regular Expression. `format` is another useful keyword, forcing a string to +match a built in format such as `email` or `ipv4`. + +[dependentRequired](https://json-schema.org/understanding-json-schema/reference/conditionals#dependentRequired) allows +certain properties to only be validated if other properties are present. There is also complicated [if-then-else](https://json-schema.org/understanding-json-schema/reference/conditionals#ifthenelse) +logic available within the Schema. + +Something missing natively within JSON Schema is any sort of "Certificate" type. JSON Schema has extension points +although we probably don't want to use their more common "meta schemas" and define an actual schema for our certificate +validations. We performed a proof of concept and it was simple to simply add a new "Certificate" type and implement +custom validation of that data. + +We do need help determining what custom validations to build. +- Validating a single Certificate? +- Validating a Certificate and Private Key match each other? +- Validating a single property has multiple Certificates and they are all valid? +- Validating particular attributes such as SAN match a specific value? + +There are some existing property validations that may go beyond the scope of this effort though. For example, the +[gorouter job](/~https://github.com/cloudfoundry/routing-release/blob/937bcd3cd96a75e0886fcc207f4fc38cdccf96ba/jobs/gorouter/spec#L617) +has the ability currently for the deployer to pass in validation rules for certificates. Those rules are then applied against +a different property entirely. This is probably possible to implement on the bosh director side in a custom certificate validator, +but it doesn't seem like something that would benefit more than this singular job.