Enhance ./deploy/supervisor values.yaml as schema

deploy/supervisor/values.yaml

@@ -1,39 +1,48 @@
 #! Copyright 2020-2022 the Pinniped contributors. All Rights Reserved.
 #! SPDX-License-Identifier: Apache-2.0
 
-#@data/values
+#@data/values-schema
 ---
-
+#@schema/desc "Namespace of pinniped-supervisor."
 app_name: pinniped-supervisor
 
-#! Creates a new namespace statically in yaml with the given name and installs the app into that namespace.
+#@schema/desc "Creates a new namespace statically in yaml with the given name and installs the app into that namespace."
 namespace: pinniped-supervisor
-#! If specified, assumes that a namespace of the given name already exists and installs the app into that namespace.
-#! If both `namespace` and `into_namespace` are specified, then only `into_namespace` is used.
-into_namespace: #! e.g. my-preexisting-namespace
+#@ into_namespace_desc = "If specified, assumes that a namespace of the given name already exists and installs the app into that namespace. \
+#@ If both `namespace` and `into_namespace` are specified, then only `into_namespace` is used."
+#@schema/desc into_namespace_desc
+#@schema/nullable
+into_namespace: my-preexisting-namespace
 
-#! All resources created statically by yaml at install-time and all resources created dynamically
-#! by controllers at runtime will be labelled with `app: $app_name` and also with the labels
-#! specified here. The value of `custom_labels` must be a map of string keys to string values.
-#! The app can be uninstalled either by:
-#! 1. Deleting the static install-time yaml resources including the static namespace, which will cascade and also delete
-#!    resources that were dynamically created by controllers at runtime
-#! 2. Or, deleting all resources by label, which does not assume that there was a static install-time yaml namespace.
-custom_labels: {} #! e.g. {myCustomLabelName: myCustomLabelValue, otherCustomLabelName: otherCustomLabelValue}
+#@ custom_labels_desc = "All resources created statically by yaml at install-time and all resources created dynamically \
+#@ by controllers at runtime will be labelled with `app: $app_name` and also with the labels \
+#@ specified here. The value of `custom_labels` must be a map of string keys to string values. \
+#@ The app can be uninstalled either by: \
+#@ 1. Deleting the static install-time yaml resources including the static namespace, which will cascade and also delete \
+#@    resources that were dynamically created by controllers at runtime \
+#@ 2. Or, deleting all resources by label, which does not assume that there was a static install-time yaml namespace."
+#@schema/desc custom_labels_desc
+#@schema/nullable
+custom_labels: {myCustomLabelName: myCustomLabelValue, otherCustomLabelName: otherCustomLabelValue}
 
-#! Specify how many replicas of the Pinniped server to run.
+#@schema/desc "Specify how many replicas of the Pinniped server to run."
 replicas: 2
 
-#! Specify either an image_digest or an image_tag. If both are given, only image_digest will be used.
+#@schema/desc "Specify either an image_digest or an image_tag. If both are given, only image_digest will be used."
 image_repo: projects.registry.vmware.com/pinniped/pinniped-server
-image_digest: #! e.g. sha256:f3c4fdfd3ef865d4b97a1fd295d94acc3f0c654c46b6f27ffad5cf80216903c8
+#@schema/desc "Specify either an image_digest or an image_tag. If both are given, only image_digest will be used."
+#@schema/nullable
+image_digest: sha256:f3c4fdfd3ef865d4b97a1fd295d94acc3f0c654c46b6f27ffad5cf80216903c8
+#@schema/desc "Specify either an image_digest or an image_tag. If both are given, only image_digest will be used."
 image_tag: latest
 
-#! Specifies a secret to be used when pulling the above `image_repo` container image.
-#! Can be used when the above image_repo is a private registry.
-#! Typically the value would be the output of: kubectl create secret docker-registry x --docker-server=https://example.io --docker-username="USERNAME" --docker-password="PASSWORD" --dry-run=client -o json | jq -r '.data[".dockerconfigjson"]'
-#! Optional.
-image_pull_dockerconfigjson: #! e.g. {"auths":{"https://registry.example.com":{"username":"USERNAME","password":"PASSWORD","auth":"BASE64_ENCODED_USERNAME_COLON_PASSWORD"}}}
+#@ image_pull_dockerconfigjson_desc = "Specifies a secret to be used when pulling the above `image_repo` container image. \
+#@ Can be used when the above image_repo is a private registry. \
+#@ Typically the value would be the output of: kubectl create secret docker-registry x --docker-server=https://example.io --docker-username='USERNAME' --docker-password='PASSWORD' --dry-run=client -o json | jq -r '.data['.dockerconfigjson']' \
+#@ Optional."
+#@schema/desc image_pull_dockerconfigjson_desc
+#@schema/nullable
+image_pull_dockerconfigjson: {"auths":{"https://registry.example.com":{"username":"USERNAME","password":"PASSWORD","auth":"BASE64_ENCODED_USERNAME_COLON_PASSWORD"}}}
 
 #! Specify how to expose the Supervisor app's HTTPS port as a Service.
 #! Typically, you would set a value for only one of the following service types.
@@ -41,43 +50,70 @@ image_pull_dockerconfigjson: #! e.g. {"auths":{"https://registry.example.com":{"
 #! Note that all port numbers should be numbers (not strings), i.e. use ytt's `--data-value-yaml` instead of `--data-value`.
 #! Several of these values have been deprecated and will be removed in a future release. Their names have been changed to
 #! mark them as deprecated and to make it obvious upon upgrade to anyone who was using them that they have been deprecated.
-deprecated_service_http_nodeport_port: #! will be removed in a future release; when specified, creates a NodePort Service with this `port` value, with port 8080 as its `targetPort`; e.g. 31234
-deprecated_service_http_nodeport_nodeport: #! will be removed in a future release; the `nodePort` value of the NodePort Service, optional when `deprecated_service_http_nodeport_port` is specified; e.g. 31234
-deprecated_service_http_loadbalancer_port: #! will be removed in a future release; when specified, creates a LoadBalancer Service with this `port` value, with port 8080 as its `targetPort`; e.g. 8443
-deprecated_service_http_clusterip_port: #! will be removed in a future release; when specified, creates a ClusterIP Service with this `port` value, with port 8080 as its `targetPort`; e.g. 8443
-service_https_nodeport_port: #! when specified, creates a NodePort Service with this `port` value, with port 8443 as its `targetPort`; e.g. 31243
-service_https_nodeport_nodeport: #! the `nodePort` value of the NodePort Service, optional when `service_https_nodeport_port` is specified; e.g. 31243
-service_https_loadbalancer_port: #! when specified, creates a LoadBalancer Service with this `port` value, with port 8443 as its `targetPort`; e.g. 8443
-service_https_clusterip_port: #! when specified, creates a ClusterIP Service with this `port` value, with port 8443 as its `targetPort`; e.g. 8443
-#! The `loadBalancerIP` value of the LoadBalancer Service.
-#! Ignored unless service_https_loadbalancer_port is provided.
-#! Optional.
-service_loadbalancer_ip: #! e.g. 1.2.3.4
+#@schema/desc "will be removed in a future release; when specified, creates a NodePort Service with this `port` value, with port 8080 as its `targetPort`"
+#@schema/nullable
+deprecated_service_http_nodeport_port: 31234
+#@schema/desc "will be removed in a future release; the `nodePort` value of the NodePort Service, optional when `deprecated_service_http_nodeport_port` is specified"
+#@schema/nullable
+deprecated_service_http_nodeport_nodeport: 31234
+#@schema/desc "will be removed in a future release; when specified, creates a LoadBalancer Service with this `port` value, with port 8080 as its `targetPort`"
+#@schema/nullable
+deprecated_service_http_loadbalancer_port: 8443
+#@schema/desc "#! will be removed in a future release; when specified, creates a ClusterIP Service with this `port` value, with port 8080 as its `targetPort`"
+#@schema/nullable
+deprecated_service_http_clusterip_port: 8443
+#@schema/desc "#! when specified, creates a NodePort Service with this `port` value, with port 8443 as its `targetPort`"
+#@schema/nullable
+service_https_nodeport_port: 31243
+#@schema/desc "#! the `nodePort` value of the NodePort Service, optional when `service_https_nodeport_port` is specified"
+#@schema/nullable
+service_https_nodeport_nodeport: 31243
+#@schema/desc "#! when specified, creates a LoadBalancer Service with this `port` value, with port 8443 as its `targetPort`"
+#@schema/nullable
+service_https_loadbalancer_port: 8443
+#@schema/desc "#! when specified, creates a ClusterIP Service with this `port` value, with port 8443 as its `targetPort`"
+#@schema/nullable
+service_https_clusterip_port: 8443
+#@ service_loadbalancer_ip_desc="The `loadBalancerIP` value of the LoadBalancer Service. \
+#@ Ignored unless service_https_loadbalancer_port is provided."
+#@schema/desc service_loadbalancer_ip_desc
+#@schema/nullable
+service_loadbalancer_ip: 1.2.3.4
 
 #! Specify the verbosity of logging: info ("nice to know" information), debug (developer information), trace (timing information),
 #! or all (kitchen sink). Do not use trace or all on production systems, as credentials may get logged.
-log_level: #! By default, when this value is left unset, only warnings and errors are printed. There is no way to suppress warning and error logs.
-#! Specify the format of logging: json (for machine parsable logs) and text (for legacy klog formatted logs).
-#! By default, when this value is left unset, logs are formatted in json.
-#! This configuration is deprecated and will be removed in a future release at which point logs will always be formatted as json.
-deprecated_log_format:
+#@schema/desc "default, when this value is left unset, only warnings and errors are printed. There is no way to suppress warning and error logs."
+#@schema/nullable
+log_level: info
+#@ deprecated_log_format_desc = "Specify the format of logging: json (for machine parsable logs) and text (for legacy klog formatted logs). \
+#@ By default, when this value is left unset, logs are formatted in json. \
+#@ This configuration is deprecated and will be removed in a future release at which point logs will always be formatted as json."
+#@schema/desc deprecated_log_format_desc
+#@schema/nullable
+deprecated_log_format: json
 
-run_as_user: 65532 #! run_as_user specifies the user ID that will own the process, see the Dockerfile for the reasoning behind this choice
-run_as_group: 65532 #! run_as_group specifies the group ID that will own the process, see the Dockerfile for the reasoning behind this choice
+#@schema/desc "run_as_user specifies the user ID that will own the process, see the Dockerfile for the reasoning behind this choice"
+run_as_user: 65532
+#@schema/desc "run_as_group specifies the group ID that will own the process, see the Dockerfile for the reasoning behind this choice"
+run_as_group: 65532
 
-#! Specify the API group suffix for all Pinniped API groups. By default, this is set to
-#! pinniped.dev, so Pinniped API groups will look like foo.pinniped.dev,
-#! authentication.concierge.pinniped.dev, etc. As an example, if this is set to tuna.io, then
-#! Pinniped API groups will look like foo.tuna.io. authentication.concierge.tuna.io, etc.
+#@ api_group_suffix_desc = "Specify the API group suffix for all Pinniped API groups. By default, this is set to \
+#@ pinniped.dev, so Pinniped API groups will look like foo.pinniped.dev, \
+#@ authentication.concierge.pinniped.dev, etc. As an example, if this is set to tuna.io, then \
+#@ Pinniped API groups will look like foo.tuna.io. authentication.concierge.tuna.io, etc."
+#@schema/desc api_group_suffix_desc
 api_group_suffix: pinniped.dev
 
-#! Set the standard golang HTTPS_PROXY and NO_PROXY environment variables on the Supervisor containers.
-#! These will be used when the Supervisor makes backend-to-backend calls to upstream identity providers using HTTPS,
-#! e.g. when the Supervisor fetches discovery documents, JWKS keys, and tokens from an upstream OIDC Provider.
-#! The Supervisor never makes insecure HTTP calls, so there is no reason to set HTTP_PROXY.
-#! Optional.
-https_proxy: #! e.g. http://proxy.example.com
-no_proxy: "$(KUBERNETES_SERVICE_HOST),169.254.169.254,127.0.0.1,localhost,.svc,.cluster.local" #! do not proxy Kubernetes endpoints
+#@ https_proxy_desc = "Set the standard golang HTTPS_PROXY and NO_PROXY environment variables on the Supervisor containers. \
+#@ These will be used when the Supervisor makes backend-to-backend calls to upstream identity providers using HTTPS, \
+#@ e.g. when the Supervisor fetches discovery documents, JWKS keys, and tokens from an upstream OIDC Provider. \
+#@ The Supervisor never makes insecure HTTP calls, so there is no reason to set HTTP_PROXY. \
+#@ Optional."
+#@schema/desc https_proxy_desc
+#@schema/nullable
+https_proxy: http://proxy.example.com
+#@schema/desc "do not proxy Kubernetes endpoints"
+no_proxy: "$(KUBERNETES_SERVICE_HOST),169.254.169.254,127.0.0.1,localhost,.svc,.cluster.local"
 
 #! Control the HTTP and HTTPS listeners of the Supervisor.
 #!
@@ -118,16 +154,22 @@ no_proxy: "$(KUBERNETES_SERVICE_HOST),169.254.169.254,127.0.0.1,localhost,.svc,.
 #! Changing the HTTPS port number must be accompanied by matching changes to the service and deployment
 #! manifests. Changes to the HTTPS listener must be coordinated with the deployment health checks.
 #!
-#! Optional.
+#@schema/desc "Control the HTTP and HTTPS listeners of the Supervisor."
+#@schema/nullable
 endpoints:
+  https:
+    network: tcp
+    address: 1.2.3.4:5678
 
-#! Optionally override the validation on the endpoints.http value which checks that only loopback interfaces are used.
-#! When deprecated_insecure_accept_external_unencrypted_http_requests is true, the HTTP listener is allowed to bind to any
-#! interface, including interfaces that are listening for traffic from outside the pod. This value is being introduced
-#! to ease the transition to the new loopback interface validation for the HTTP port for any users who need more time
-#! to change their ingress strategy to avoid using plain HTTP into the Supervisor pods.
-#! This value is immediately deprecated upon its introduction. It will be removed in some future release, at which time
-#! traffic from outside the pod will need to be sent to the HTTPS listener instead, with no simple workaround available.
-#! Allowed values are true (boolean), "true" (string), false (boolean), and "false" (string). The default is false.
-#! Optional.
+#! deprecated_insecure_accept_external_unencrypted_http_requests_desc = "Optionally override the validation on the endpoints. \
+#! http value which checks that only loopback interfaces are used. \
+#! When deprecated_insecure_accept_external_unencrypted_http_requests is true, the HTTP listener is allowed to bind to any \
+#! interface, including interfaces that are listening for traffic from outside the pod. This value is being introduced \
+#! to ease the transition to the new loopback interface validation for the HTTP port for any users who need more time \
+#! to change their ingress strategy to avoid using plain HTTP into the Supervisor pods. \
+#! This value is immediately deprecated upon its introduction. It will be removed in some future release, at which time \
+#! traffic from outside the pod will need to be sent to the HTTPS listener instead, with no simple workaround available. \
+#! Allowed values are true (boolean), "true" (string), false (boolean), and "false" (string). The default is false. \
+#! Optional."
+#@schema/desc https_proxy_desc
 deprecated_insecure_accept_external_unencrypted_http_requests: false