Intro tutorials for About API use cases

[lauralorenz]

Develop some vendor agnostic intro tutorials about the About API that can be easily digested as part of a generic documentation push. I think it would be useful to tie them to some common use cases as suggested below.

• About API for storing cluster name and sending as prometheus label in your metrics instrumentation
• About API for storing arbitrary, implementation specific cluster properties following the rules listed here and discussed on this slide, possibly a cluster's network name, region, etc

[lauralorenz]

/help

[k8s-ci-robot]

@lauralorenz:
This request has been marked as needing help from a contributor.

Guidelines

Please ensure that the issue body includes answers to the following questions:

• Why are we solving this issue?
• To address this issue, are there any code changes? If there are code changes, what needs to be done in the code and what places can the assignee treat as reference points?
• Does this issue have zero to low barrier of entry?
• How can the assignee reach out to you for help?

For more details on the requirements of such an issue, please see here and ensure that they are met.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.

In response to this:

/help

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[holgerson97]

/assign

[holgerson97]

Hello @lauralorenz,

regarding an example using metrics, should we present code snippets on how to append the ClusterProperty into the metrics via the Kubernetes Go-Client?

Would something like this be sufficient for the second point?

---

Simple Example for About-API

This example will guide you through the setup and usage, demonstrating how to effectively leverage ClusterProperty to enhance your Kubernetes operations.

Assume you are running multiple Kubernetes clusters. Each clusters has a main purpose e.g. ClusterBootstrapping via CAPI, running your business applications. In order to assign each clusters main purpose as ClusterProperty follow the below example.

ClusterProperty

When choosing a name for the ClusterProperty CR consider the following:

• Name must have a suffix as below
• Cannot use the reserved *k8s.io or *.kubernetes.io suffix
• Do not conflict with the well-known CluserProperties

# Simple Usecase Example
apiVersion: about.k8s.io/v1alpha1
kind: ClusterProperty
metadata:
  name: usecase.example.com
spec:
  value: webserver

Examples

# Owner Example
apiVersion: about-api.k8s.io/v1
kind: ClusterProperty
metadata:
  name: owner
spec:
  value: DevOps-Team

# Compliance Example
apiVersion: about-api.k8s.io/v1
kind: ClusterProperty
metadata:
  name: compliance
spec:
  value: PCI-DSS

# Environment Example
apiVersion: about-api.k8s.io/v1
kind: ClusterProperty
metadata:
  name: environment
spec:
  value: production

[lauralorenz]

/sig multicluster

@holgerson97 yes those are great examples!

I think you do also need to include the caveat inline with these examples from the KEP here:

Cluster operators are free to use non-namespaced properties (e.g. fingerprint) as they see fit, but any shared tooling should use appropriately namespaced names.

so it's clear that the three examples you've made one are ones for "cluster operators" with no expectation of being recognized by standard tooling, whereas suffix is required if you are an implementor of something that leverages About API or its derivatives (like the simple Usecase Example)