Update supervisor values.yaml to a schema doc. Make @nullable work

- see build.sh for documented script to run to generate:
   ytt --file concierge/config/values.yaml --data-values-schema-inspect --output openapi-v3 > concierge/schema-openapi.yml

deploy_carvel/build.sh

@@ -10,4 +10,4 @@
 # schema generation from values.yaml
 # TODO: figure out why this isn't working.
 ytt --file supervisor/config/values.yaml --data-values-schema-inspect --output openapi-v3 > supervisor/schema-openapi.yml
-# ytt --file concierge/config/values.yaml --data-values-schema-inspect --output openapi-v3 > concierge/schema-openapi.yml
+ytt --file concierge/config/values.yaml --data-values-schema-inspect --output openapi-v3 > concierge/schema-openapi.yml

deploy_carvel/concierge/config/values.yaml

@@ -3,14 +3,16 @@
 
 #@data/values-schema
 ---
-
+#@schema/desc "Namespace of pinniped-concierge"
 app_name: pinniped-concierge
 
-#! 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-concierge
 #! 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
+#@schema/desc "Overrides namespace.  This is actually confusingly worded. TODO: CAN WE REWRITE THIS ONE???"
+#@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
@@ -19,57 +21,58 @@ into_namespace: #! e.g. my-preexisting-namespace
 #! 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 "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."
 custom_labels: {} #! e.g. {myCustomLabelName: myCustomLabelValue, otherCustomLabelName: otherCustomLabelValue}
 
 #! 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
 
-#! Optionally specify a different image for the "kube-cert-agent" pod which is scheduled
+#@schema/desc 'Optionally specify a different image for the "kube-cert-agent" pod which is scheduled on the control plane. This image needs only to include `sleep` and `cat` binaries. By default, the same image specified for image_repo/image_digest/image_tag will be re-used.'
-#! on the control plane. This image needs only to include `sleep` and `cat` binaries.
+kube_cert_agent_image: projects.registry.vmware.com/pinniped/pinniped-server
-#! By default, the same image specified for image_repo/image_digest/image_tag will be re-used.
-kube_cert_agent_image:
 
 #! 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"}}}
+#@schema/desc "Specifies a secret to be used when pulling the above `image_repo` container image. Can be used when the image_repo is a private registry."
+#@schema/nullable
+image_pull_dockerconfigjson: {"auths":{"https://registry.example.com":{"username":"USERNAME","password":"PASSWORD","auth":"BASE64_ENCODED_USERNAME_COLON_PASSWORD"}}}
 
-#! Pinniped will try to guess the right K8s API URL for sharing that information with potential clients.
-#! This setting allows the guess to be overridden.
 #! Optional.
-discovery_url: #! e.g., https://example.com
+#@schema/desc "Pinniped will try to guess the right K8s API URL for sharing that information with potential clients. This setting allows the guess to be overridden."
+#@schema/nullable
+discovery_url: https://example.com
 
-#! Specify the duration and renewal interval for the API serving certificate.
+#@schema/desc "Specify the duration and renewal interval for the API serving certificate. The defaults are set to expire the cert about every 30 days, and to rotate it about every 25 days."
-#! The defaults are set to expire the cert about every 30 days, and to rotate it
-#! about every 25 days.
 api_serving_certificate_duration_seconds: 2592000
 api_serving_certificate_renew_before_seconds: 2160000
 
-#! Specify the verbosity of logging: info ("nice to know" information), debug (developer
+#@schema/desc '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.'
-#! information), trace (timing information), all (kitchen sink).
+#@schema/nullable
-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.
+log_level: info #! 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).
+#@schema/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."
-#! By default, when this value is left unset, logs are formatted in json.
+#@schema/nullable
-#! 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: json
-deprecated_log_format:
 
-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
+#@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_group: 65532 #! run_as_group specifies the group 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
+#@schema/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."
-#! 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: pinniped.dev
 
-#! Customize CredentialIssuer.spec.impersonationProxy to change how the concierge
+
-#! handles impersonation.
+
+#@schema/desc "Customize CredentialIssuer.spec.impersonationProxy to change how the concierge handles impersonation."
 impersonation_proxy_spec:
   #! options are "auto", "disabled" or "enabled".
   #! If auto, the impersonation proxy will run only if the cluster signing key is not available
@@ -77,11 +80,13 @@ impersonation_proxy_spec:
   #! If disabled, the impersonation proxy will never run, which could mean that the concierge
   #! doesn't work at all.
   #! If enabled, the impersonation proxy will always run regardless of other strategies available.
+  #@schema/desc 'options are "auto", "disabled" or "enabled".'
   mode: auto
   #! The endpoint which the client should use to connect to the impersonation proxy.
   #! If left unset, the client will default to connecting based on the ClusterIP or LoadBalancer
   #! endpoint.
-  external_endpoint:
+  #@schema/desc "The endpoint which the client should use to connect to the impersonation proxy."
+  external_endpoint: http://example.com
   service:
     #! Options are "LoadBalancer", "ClusterIP" and "None".
     #! LoadBalancer automatically provisions a Service of type LoadBalancer pointing at
@@ -91,17 +96,17 @@ impersonation_proxy_spec:
     #! impersonation proxy.
     #! None does not provision either and assumes that you have set the external_endpoint
     #! and set up your own ingress to connect to the impersonation proxy.
+    #@schema/desc 'Options are "LoadBalancer", "ClusterIP" and "None".'
     type: LoadBalancer
-    #! The annotations that should be set on the ClusterIP or LoadBalancer Service.
+    #@schema/desc "The annotations that should be set on the ClusterIP or LoadBalancer Service."
     annotations:
       {service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout: "4000"}
-    #! When mode LoadBalancer is set, this will set the LoadBalancer Service's Spec.LoadBalancerIP.
+    #@schema/desc "When mode LoadBalancer is set, this will set the LoadBalancer Service's Spec.LoadBalancerIP."
-    load_balancer_ip:
+    load_balancer_ip: 1.2.3.4
 
-#! Set the standard golang HTTPS_PROXY and NO_PROXY environment variables on the Concierge containers.
-#! These will be used when the Concierge makes backend-to-backend calls to authenticators using HTTPS,
-#! e.g. when the Concierge fetches discovery documents, JWKS keys, and POSTs to token webhooks.
-#! The Concierge never makes insecure HTTP calls, so there is no reason to set HTTP_PROXY.
 #! Optional.
-https_proxy: #! e.g. http://proxy.example.com
+#@schema/desc "Set the standard golang HTTPS_PROXY and NO_PROXY environment variables on the Concierge containers. These will be used when the Concierge makes backend-to-backend calls to authenticators using HTTPS, e.g. when the Concierge fetches discovery documents, JWKS keys, and POSTs to token webhooks. The Concierge never makes insecure HTTP calls, so there is no reason to set HTTP_PROXY."
-no_proxy: "$(KUBERNETES_SERVICE_HOST),169.254.169.254,127.0.0.1,localhost,.svc,.cluster.local" #! do not proxy Kubernetes endpoints
+#@schema/nullable
+https_proxy: http://proxy.example.com
+#@schema/desc "NO_PROXY environment variable. do not proxy Kubernetes endpoints"
+no_proxy: "$(KUBERNETES_SERVICE_HOST),169.254.169.254,127.0.0.1,localhost,.svc,.cluster.local"

deploy_carvel/concierge/schema-openapi.yml

@@ -6,5 +6,143 @@ paths: {}
 components:
   schemas:
     dataValues:
+      type: object
+      additionalProperties: false
+      properties:
+        app_name:
+          type: string
+          description: Namespace of pinniped-concierge
+          default: pinniped-concierge
+        namespace:
+          type: string
+          description: Creates a new namespace statically in yaml with the given name and installs the app into that namespace.
+          default: pinniped-concierge
+        into_namespace:
+          type: string
           nullable: true
+          description: 'Overrides namespace.  This is actually confusingly worded. TODO: CAN WE REWRITE THIS ONE???'
           default: null
+        custom_labels:
+          type: object
+          additionalProperties: false
+          description: '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.'
+          properties: {}
+        replicas:
+          type: integer
+          default: 2
+        image_repo:
+          type: string
+          description: Specify either an image_digest or an image_tag. If both are given, only image_digest will be used.
+          default: projects.registry.vmware.com/pinniped/pinniped-server
+        image_digest:
+          type: string
+          nullable: true
+          description: Specify either an image_digest or an image_tag. If both are given, only image_digest will be used.
+          default: null
+        image_tag:
+          type: string
+          description: Specify either an image_digest or an image_tag. If both are given, only image_digest will be used.
+          default: latest
+        kube_cert_agent_image:
+          type: string
+          description: Optionally specify a different image for the "kube-cert-agent" pod which is scheduled on the control plane. This image needs only to include `sleep` and `cat` binaries. By default, the same image specified for image_repo/image_digest/image_tag will be re-used.
+          default: projects.registry.vmware.com/pinniped/pinniped-server
+        image_pull_dockerconfigjson:
+          type: object
+          additionalProperties: false
+          nullable: true
+          description: Specifies a secret to be used when pulling the above `image_repo` container image. Can be used when the image_repo is a private registry.
+          properties:
+            auths:
+              type: object
+              additionalProperties: false
+              properties:
+                https://registry.example.com:
+                  type: object
+                  additionalProperties: false
+                  properties:
+                    username:
+                      type: string
+                      default: USERNAME
+                    password:
+                      type: string
+                      default: PASSWORD
+                    auth:
+                      type: string
+                      default: BASE64_ENCODED_USERNAME_COLON_PASSWORD
+        discovery_url:
+          type: string
+          nullable: true
+          description: Pinniped will try to guess the right K8s API URL for sharing that information with potential clients. This setting allows the guess to be overridden.
+          default: null
+        api_serving_certificate_duration_seconds:
+          type: integer
+          description: Specify the duration and renewal interval for the API serving certificate. The defaults are set to expire the cert about every 30 days, and to rotate it about every 25 days.
+          default: 2592000
+        api_serving_certificate_renew_before_seconds:
+          type: integer
+          default: 2160000
+        log_level:
+          type: string
+          nullable: true
+          description: '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.'
+          default: null
+        deprecated_log_format:
+          type: string
+          nullable: true
+          description: '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.'
+          default: null
+        run_as_user:
+          type: integer
+          description: run_as_user specifies the user ID that will own the process, see the Dockerfile for the reasoning behind this choice
+          default: 65532
+        run_as_group:
+          type: integer
+          description: run_as_group specifies the group ID that will own the process, see the Dockerfile for the reasoning behind this choice
+          default: 65532
+        api_group_suffix:
+          type: string
+          description: 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.
+          default: pinniped.dev
+        impersonation_proxy_spec:
+          type: object
+          additionalProperties: false
+          description: Customize CredentialIssuer.spec.impersonationProxy to change how the concierge handles impersonation.
+          properties:
+            mode:
+              type: string
+              description: options are "auto", "disabled" or "enabled".
+              default: auto
+            external_endpoint:
+              type: string
+              description: The endpoint which the client should use to connect to the impersonation proxy.
+              default: http://example.com
+            service:
+              type: object
+              additionalProperties: false
+              properties:
+                type:
+                  type: string
+                  description: Options are "LoadBalancer", "ClusterIP" and "None".
+                  default: LoadBalancer
+                annotations:
+                  type: object
+                  additionalProperties: false
+                  description: The annotations that should be set on the ClusterIP or LoadBalancer Service.
+                  properties:
+                    service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout:
+                      type: string
+                      default: "4000"
+                load_balancer_ip:
+                  type: string
+                  description: When mode LoadBalancer is set, this will set the LoadBalancer Service's Spec.LoadBalancerIP.
+                  default: 1.2.3.4
+        https_proxy:
+          type: string
+          nullable: true
+          description: Set the standard golang HTTPS_PROXY and NO_PROXY environment variables on the Concierge containers. These will be used when the Concierge makes backend-to-backend calls to authenticators using HTTPS, e.g. when the Concierge fetches discovery documents, JWKS keys, and POSTs to token webhooks. The Concierge never makes insecure HTTP calls, so there is no reason to set HTTP_PROXY.
+          default: null
+        no_proxy:
+          type: string
+          description: NO_PROXY environment variable. do not proxy Kubernetes endpoints
+          default: $(KUBERNETES_SERVICE_HOST),169.254.169.254,127.0.0.1,localhost,.svc,.cluster.local

deploy_carvel/supervisor/config/values.yaml

@@ -83,6 +83,7 @@ log_level: info #! By default, when this value is left unset, only warnings and
 #@schema/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/nullable
 deprecated_log_format: json
+
 #@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"
@@ -94,8 +95,9 @@ api_group_suffix: pinniped.dev
 #! Optional.
 #@schema/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."
 #@schema/nullable
-https_proxy: http://proxy.example.com #! e.g. http://proxy.example.com
+https_proxy: 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
+#@schema/desc "NO_PROXY environment variable. 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.
 #!

deploy_carvel/supervisor/schema-openapi.yml

@@ -140,6 +140,7 @@ components:
           default: null
         no_proxy:
           type: string
+          description: NO_PROXY environment variable. do not proxy Kubernetes endpoints
           default: $(KUBERNETES_SERVICE_HOST),169.254.169.254,127.0.0.1,localhost,.svc,.cluster.local
         endpoints:
           type: object