add Description and validation properties to EnvVar in the REST API so that environment variables can have better tooling #4210

jstrachan · 2015-02-06T08:53:33Z

Environment variables are one of the main configuration mechanisms in docker & kubernetes. It would be nice if we could export a little more metadata about the environment variables so that its easier for folks working across all kubernetes pods to be able to understand the configuration and for tools to be able to better visualise the configuration and allow editing in nicer forms with richer controls and validation. e.g. a description could be used in a web UI or CLI tool to describe the environment variables.

It might be nice to add JSON Schema validation properties too (e.g. Type field (for things line integer, number, uri, date-time, email etc), MinLength, MaxLength, Pattern etc) so that tools can generate an automatic editor of the environment variables.

e.g. if folks want to allow a pod definition to be visually edited by a tool, it'd be nice to be able from the Pod JSON to be able to generate a nice validating form with tooltips.

Then folks generating a Pod JSON/YAML file who have deeper knowledge about the internals of a docker container image could then export richer metadata about the environment variables so that generic kubernetes tooling would provide a richer experience.

bgrant0607 · 2015-02-06T15:17:50Z

@jstrachan I understand why you'd want this, but we don't have a suitable object in the Kubernetes API on which to hang this information. Our objects are fully concrete. What you want is a parameterized template. This info more properly belongs here:
https://github.com/openshift/origin/blob/master/pkg/template/api/v1beta1/types.go

jstrachan · 2015-04-07T10:33:43Z

How'd swagger be aware of pod-specific environment variable names, types and validation?

I still don't grok why a couple more optional properties on the existing EnvVar type isn't an option.

The next best thing would be optional annotations on the Pod I guess?

bgrant0607 · 2015-04-07T15:41:42Z

Sorry, updated wrong issue. Deleted comment.

I don't understand how you'd use the properties at this level of the API. The values of the environment variables would need to be set already when the pod, pod template, or replication controller were created. Isn't that too late for validation?

bgrant0607 · 2015-04-08T01:11:21Z

Example template object:
https://raw.githubusercontent.com/ianmiell/javaee7-hol/master/application-template-jeebuild.json

  "parameters": [
    {
      "name": "MYSQL_USER",
      "description": "administrator username",
      "value": "mysql"
    },
    {
      "name": "MYSQL_PASSWORD",
      "description": "administrator password",
      "value": "mysql"
    },
    {
      "name": "MYSQL_ROOT_PASSWORD",
      "description": "database password",
      "value": "supersecret"
    },
    {
      "name": "MYSQL_DATABASE",
      "description": "database name",
      "value": "sample"
    }
  ],
...
                    "env": [
                      {
                        "name": "MYSQL_USER",
                        "value": "${MYSQL_USER}"
                      },
                      {
                        "name": "MYSQL_PASSWORD",
                        "value": "${MYSQL_PASSWORD}"
                      },
                      {
                        "name": "MYSQL_ROOT_PASSWORD",
                        "value": "${MYSQL_ROOT_PASSWORD}"
                      },
                      {
                        "name": "MYSQL_DATABASE",
                        "value": "${MYSQL_DATABASE}"
                      },
                      {
                        "name": "MYSQL_DB_NAME",
                        "value": "${MYSQL_DATABASE}"
                      }
                    ],

I think the parameter block would be the right place to put additional information about application-level parameters.

smarterclayton · 2015-11-04T23:13:41Z

Some additional parameterization examples

{
  ...
  "parameters": [
    {
      "name": "DATABASE_SERVICE_NAME",
      "description": "Database service name",
      "value": "mysql",
      "required": true
    },
    {
      "name": "MYSQL_USER",
      "description": "Username for MySQL user that will be used for accessing the database",
      "generate": "expression",
      "from": "user[A-Z0-9]{3}",
      "required": true
    },
    {
      "name": "MYSQL_PASSWORD",
      "description": "Password for the MySQL user",
      "generate": "expression",
      "from": "[a-zA-Z0-9]{16}",
      "required": true
    },
    {
      "name": "MYSQL_DATABASE",
      "description": "Database name",
      "value": "sampledb",
      "required": true
    },
    {
      "name": "VOLUME_CAPACITY",
      "description": "Volume space available for data, e.g. 512Mi, 2Gi",
      "value": "512Mi",
      "required": true
    }
  ],
  "labels": {
    "template": "mysql-persistent-template"
  }
}

I would like to use a different substitution mechanism than ${VAR} - either JSON path identification in the parameters, or mustache style expansion. The one problem with mustache is that it can't be valid JSON in the structure when changing types.

jstrachan · 2015-11-11T09:45:25Z

My initial motivation for this issue was the idea of tooling so that folks could configure an app/chart/package that was installed in kubernetes (and so editing the RC / DC / pod) using automated tooling which grokked the shape of the configuration (mostly env vars really). Particularly with the idea of consuming OOTB apps (e.g. with things like Helm) or moving apps between environments and making configuration changes along the way and so forth.

Since the emergence of the Config Resource proposal: #6477 - I'm wondering if its maybe simpler for this kind of use case for the Config Resource to be editable via tools; by it having an optional, say, JSON Schema annotation which a tool could use to let users edit the configuration. So these parameters could be defined by the Config Resource and the Config Resource can then either contain or reference a schema file?

smarterclayton · 2017-06-01T16:58:35Z

Going to close this due to age and a general unwillingness (:)) to grow this particular API more. I think Helm, Templates, or other higher level tools can take on more of the burden now. I think experimentation could be done via a swagger schema link on a config map annotation?

bgrant0607 · 2017-07-07T23:41:36Z

@smarterclayton Is this along the lines of what you were thinking?

apiVersion: v1
kind: ConfigMap
metadata:
  name: vars-123
  annotations:
    idk.k8s.io/schema: vars-schema
data:
  VAR1: foo
  VAR2: bar
---
# This is a custom resource
apiVersion: idk.k8s.io/v1
kind: ConfigMapSchema
metadata:
  name: vars-schema
spec:
  title: some-vars
  type: object
  properties:
    VAR1:
      description: A typical parameter
      type: string
    VAR2:
      description: Another typical parameter
      type: string
      default: zanzibar
  required:
  - VAR1

bgrant0607 added area/app-lifecycle and removed kind/documentation Categorizes issue or PR as related to documentation. labels Feb 6, 2015

bgrant0607 mentioned this issue Apr 6, 2015

Facilitate automatic form and client generation #6487

Closed

bgrant0607 mentioned this issue Apr 10, 2015

Deployment resource (was Evaluate adoption of OpenShift template configs and/or deployments) #1743

Closed

bgrant0607 mentioned this issue May 12, 2015

Add validation constraints to API struct tags #8116

Closed

This was referenced Jun 20, 2015

"v2" API (API/client redesign umbrella issue) #8190

Closed

Config Resource Proposal #6477

Merged

bgrant0607 mentioned this issue Aug 20, 2015

PetSet (was nominal services) #260

Closed

bgrant0607 mentioned this issue Sep 26, 2015

Config template parameterization #11492

Closed

bgrant0607 mentioned this issue Nov 4, 2015

Add a custom generator that uses template files #14918

Closed

bparees mentioned this issue Dec 4, 2015

initial template and parameterization proposal #18215

Merged

smarterclayton closed this as completed Jun 1, 2017

bgrant0607 mentioned this issue May 22, 2022

Develop a way to handle application configuration kptdev/kpt#3210

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add Description and validation properties to EnvVar in the REST API so that environment variables can have better tooling #4210

add Description and validation properties to EnvVar in the REST API so that environment variables can have better tooling #4210

jstrachan commented Feb 6, 2015

bgrant0607 commented Feb 6, 2015

jstrachan commented Apr 7, 2015

bgrant0607 commented Apr 7, 2015

bgrant0607 commented Apr 8, 2015

smarterclayton commented Nov 4, 2015

jstrachan commented Nov 11, 2015

smarterclayton commented Jun 1, 2017

bgrant0607 commented Jul 7, 2017

add Description and validation properties to EnvVar in the REST API so that environment variables can have better tooling #4210

add Description and validation properties to EnvVar in the REST API so that environment variables can have better tooling #4210

Comments

jstrachan commented Feb 6, 2015

bgrant0607 commented Feb 6, 2015

jstrachan commented Apr 7, 2015

bgrant0607 commented Apr 7, 2015

bgrant0607 commented Apr 8, 2015

smarterclayton commented Nov 4, 2015

jstrachan commented Nov 11, 2015

smarterclayton commented Jun 1, 2017

bgrant0607 commented Jul 7, 2017