Support annotations in function schema

[alexellis]

Description

We should consider adding annotations to the schema or using them to store labels with Kubernetes

Example

"label": {"value-with-json-meta": "data"}
Swarm: valid
Kubernetes: invalid

"Git-Deploy": "03/03/2018 10:10:00"
Swarm: valid
Kubernetes: invalid

"valid-for-both": "anything-that-123-looks-like-a.domain"
Swarm: valid
Kubernetes: valid

Problem/Issue

Kubernetes uses annotations to configure metadata for objects like Pods. With Docker Swarm we use labels which support almost any string - but the label schema for Kubernetes is very restrictive only allowing a value which is a valid DNS entry.

OpenFaaS Cloud and the event connectors make use of metadata for filtering so for a rich experience with Kubernetes we need to think about how to start accommodating this metadata.

For Swarm labels work well - for Kubernetes we may need to make use of annotations in addition to labels.

Proposal

Add new field to function schema named "annotations"

Format: map[string]string (same as label)

Kubernetes: implemented as annotations in deployment and CRD

Swarm: implemented as label with special name

This is a vertical slice going all the way from the CLI through to the gateway to the providers and into the container orchestration system. The work will require (copy/paste/rename) of where labels are mentioned, but the work will have to be tested (manual end-to-end testing) and well co-ordinated with project lead.

Acceptance

provider:
  name: faas
  gateway: http://127.0.0.1:8080

functions:
  slack-responder:
    lang: go
    handler: ./slack-responder
    image: alexellis2/slack-responder:0.1.0
    labels:
      source: git
   annotations:
      git: https://github.com/alexellis/super-pancake-fn.git
      topics: "arn:aws:sns:us-west-2:111122223333:MyTopic,arn:aws:sns:us-west-2:111122223333:My-Second-Topic"

Previously the above would not be supported in Kubernetes - storing complex metadata in the function, but this would have been supported in Swarm.

Labels vs Annotations in K8s:

Labels: allows for only a-z, (-) and (.) character
Annotations: any value.

[stefanprodan]

For Kubernetes we could use annotations instead of labels. This change only affects faas-netes and o6s.

[alexellis]

What about where people have used labels for node-selectors?

[stefanprodan]

The stack file has a dedicated field for node selectors, how would people use labels to target nodes in k8s?

[stantonxu]

Hi @alexellis @stefanprodan , do you mean label like below is invalid for Kubernetes? I got it from one of the yaml files of the faas-netes.

  labels:
    app: {{ template "openfaas.name" . }}

If we just simply move these labels to annotations, will that cause problem for label selector? Though I don't see any label selector in all the yaml files of faas-netes.

[alexellis]

No this is about where we store the labels for OpenFaaS functions when we create/update functions. It's not about the helm chart.

Look at the faas-netesd controller code where we store the labels from the request.

[stantonxu]

@alexellis , sorry just get time to look back at this thread. Do you mean the code under handlers in the faas-netes project? Or could you help me point out where the code is? I am still trying to get familiar with the code.

[alexellis]

Yes search for the word label and exclude the vendor folder. You'll see it then.

[alexellis]

@ewilde I've updated this issue with more details.

[ewilde]

@alexellis thanks for updating the issue description, seems clear, will begin working on this

[alexellis]

Great, thank you for the update.

[ewilde]

@alexellis i'm guessing we are adding the annotations support so that functions themselves can access this new meta-data? If so, how does the function access the meta-data?

[ewilde]

@alexellis I guess what i'm asking for is how to position annotations in the documentation / code comments? Currently labels are described as:

Labels are metadata for functions which may be used by the back-end for making scheduling or routing decisions

[alexellis]

The functions will not have access to the annotations, it will be used to manage and orchestrate them with things like automation, eventing and build.

[alexellis]

Derek set milestone: 0.8.7

[alexellis]

Derek close: released