From dfa60bbafd448b3c4e09fe398afff0de52662421 Mon Sep 17 00:00:00 2001 From: "Benjamin A. Petersen" Date: Mon, 21 Aug 2023 16:54:00 -0400 Subject: [PATCH] WIP: update the schema gen for supervisor the ./build.sh for the ytt invocation for this. there is more work to do here, this gets us started. many of our multiline descriptions need to be assessed. do we want both? the description and also the schema text? --- deploy_carvel/supervisor/config/values.yaml | 65 +++++++++++---------- deploy_carvel/supervisor/schema-openapi.yml | 24 +++++++- 2 files changed, 58 insertions(+), 31 deletions(-) diff --git a/deploy_carvel/supervisor/config/values.yaml b/deploy_carvel/supervisor/config/values.yaml index 1d562781..05700183 100644 --- a/deploy_carvel/supervisor/config/values.yaml +++ b/deploy_carvel/supervisor/config/values.yaml @@ -9,7 +9,7 @@ app_name: pinniped-supervisor 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. -#@schema/desc "Overrides namespace. This is actually confusingly worded." +#@schema/desc "Overrides namespace. This is actually confusingly worded. TODO: CAN WE REWRITE THIS ONE???" #@schema/nullable into_namespace: my-preexisting-namespace @@ -20,21 +20,25 @@ into_namespace: 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. +#@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 +#@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. +#@schema/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." #@schema/nullable image_pull_dockerconfigjson: {"auths":{"https://registry.example.com":{"username":"USERNAME","password":"PASSWORD","auth":"BASE64_ENCODED_USERNAME_COLON_PASSWORD"}}} @@ -44,52 +48,51 @@ image_pull_dockerconfigjson: {"auths":{"https://registry.example.com":{"username #! 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. +#@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`; e.g. 31234" #@schema/nullable -deprecated_service_http_nodeport_port: 31234 #! 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_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; e.g. 31234" #@schema/nullable -deprecated_service_http_nodeport_nodeport: 31234 #! 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_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`; e.g. 8443" #@schema/nullable -deprecated_service_http_loadbalancer_port: 8443 #! 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_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`; e.g. 8443" #@schema/nullable -deprecated_service_http_clusterip_port: 8443 #! 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 +deprecated_service_http_clusterip_port: 8443 +#@schema/desc "when specified, creates a NodePort Service with this `port` value, with port 8443 as its `targetPort`; e.g. 31243" #@schema/nullable -service_https_nodeport_port: 31243 #! when specified, creates a NodePort Service with this `port` value, with port 8443 as its `targetPort`; e.g. 31243 +service_https_nodeport_port: 31243 +#@schema/desc "the `nodePort` value of the NodePort Service, optional when `service_https_nodeport_port` is specified; e.g. 31243" #@schema/nullable -service_https_nodeport_nodeport: 31243 #! the `nodePort` value of the NodePort Service, optional when `service_https_nodeport_port` is specified; e.g. 31243 +service_https_nodeport_nodeport: 31243 +#@schema/desc "when specified, creates a LoadBalancer Service with this `port` value, with port 8443 as its `targetPort`; e.g. 8443" #@schema/nullable -service_https_loadbalancer_port: 8443 #! when specified, creates a LoadBalancer Service with this `port` value, with port 8443 as its `targetPort`; e.g. 8443 +service_https_loadbalancer_port: 8443 +#@schema/desc "when specified, creates a ClusterIP Service with this `port` value, with port 8443 as its `targetPort`; e.g. 8443" #@schema/nullable -service_https_clusterip_port: 8443 #! 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. +service_https_clusterip_port: 8443 #! Optional. +#@schema/desc "The `loadBalancerIP` value of the LoadBalancer Service. Ignored unless service_https_loadbalancer_port is provided. e.g. 1.2.3.4" #@schema/nullable -service_loadbalancer_ip: 1.2.3.4 #! e.g. 1.2.3.4 +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. +#@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.' #@schema/nullable 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). -#! 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 "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" +run_as_group: 65532 -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 - -#! 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 "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: 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. +#@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 no_proxy: "$(KUBERNETES_SERVICE_HOST),169.254.169.254,127.0.0.1,localhost,.svc,.cluster.local" #! do not proxy Kubernetes endpoints @@ -134,6 +137,7 @@ no_proxy: "$(KUBERNETES_SERVICE_HOST),169.254.169.254,127.0.0.1,localhost,.svc,. #! 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: @@ -149,4 +153,5 @@ endpoints: #! 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 "Optionally override the validation on the endpoints.http value which checks that only loopback interfaces are used." deprecated_insecure_accept_external_unencrypted_http_requests: false diff --git a/deploy_carvel/supervisor/schema-openapi.yml b/deploy_carvel/supervisor/schema-openapi.yml index a0f25b19..439bd741 100644 --- a/deploy_carvel/supervisor/schema-openapi.yml +++ b/deploy_carvel/supervisor/schema-openapi.yml @@ -20,24 +20,29 @@ components: into_namespace: type: string nullable: true - description: Overrides namespace. This is actually confusingly worded. + 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 + description: Specify how many replicas of the Pinniped server to run. 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 image_pull_dockerconfigjson: type: object @@ -64,59 +69,74 @@ components: deprecated_service_http_nodeport_port: type: integer nullable: true + description: 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 default: null deprecated_service_http_nodeport_nodeport: type: integer nullable: true + description: 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 default: null deprecated_service_http_loadbalancer_port: type: integer nullable: true + description: 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 default: null deprecated_service_http_clusterip_port: type: integer nullable: true + description: 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 default: null service_https_nodeport_port: type: integer nullable: true + description: when specified, creates a NodePort Service with this `port` value, with port 8443 as its `targetPort`; e.g. 31243 default: null service_https_nodeport_nodeport: type: integer nullable: true + description: the `nodePort` value of the NodePort Service, optional when `service_https_nodeport_port` is specified; e.g. 31243 default: null service_https_loadbalancer_port: type: integer nullable: true + description: when specified, creates a LoadBalancer Service with this `port` value, with port 8443 as its `targetPort`; e.g. 8443 default: null service_https_clusterip_port: type: integer nullable: true + description: when specified, creates a ClusterIP Service with this `port` value, with port 8443 as its `targetPort`; e.g. 8443 default: null service_loadbalancer_ip: type: string nullable: true + description: The `loadBalancerIP` value of the LoadBalancer Service. Ignored unless service_https_loadbalancer_port is provided. e.g. 1.2.3.4 default: null 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 https_proxy: type: string nullable: true + description: 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. default: null no_proxy: type: string @@ -125,6 +145,7 @@ components: type: object additionalProperties: false nullable: true + description: Control the HTTP and HTTPS listeners of the Supervisor. properties: https: type: object @@ -138,4 +159,5 @@ components: default: host:port when network=tcp or /pinniped_socket/socketfile.sock when network=unix deprecated_insecure_accept_external_unencrypted_http_requests: type: boolean + description: Optionally override the validation on the endpoints.http value which checks that only loopback interfaces are used. default: false