well-known/README.md

Well-known

A tiny service collecting and aggregating well-known data from services in the same Kubernetes namespace. The data is merged and exposed as JSON object or plain text.

We support one subdirectory level, which is not according to spec, but required by some applications.

Usage

Add an annotation to a service:

annotation	directory	description
well-known.252.no/[file]	.well-known/[file]	filename/key
well-known.252.no/directory	.well-known/[directory]/[file]	subdirectory
well-known.252.no/format	-	json or text

Installation

Find the Helm OCI for Kubernetes in charts/well-known.

Examples

Nostr

apiVersion: v1
kind: Service
metadata:
  name: well-known-nostr
  annotations:
    well-known.252.no/nostr.json: |
      {
        "names":  { "${NOSTR_NICK}": "${NOSTR_PUBLIC_KEY_HEX}" },
        "relays": {"${NOSTR_PUBLIC_KEY_HEX}": [ "wss://nostr.${PUBLIC_DOMAIN}" ] }
      }      
spec:
  selector:
    app: dummy-app
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080

security.txt

apiVersion: v1
kind: Service
metadata:
  name: well-known-securitytxt
  annotations:
    well-known.252.no/security.txt: |
      -----BEGIN PGP SIGNED MESSAGE-----
      Hash: SHA512


      Canonical: https://252.no/.well-known/security.txt

      # In case of security issue, please contact:
      Contact: mailto:tommy@252.no
      Encryption: openpgp4fpr:088194F806EBADEE1B48B1CBC0A38C49BB2258E8
      Preferred-Languages: en, no
      # other means of encryption at: https://keyoxide.org/tommy@252.no

      Expires: 2025-09-25T08:00:00.000Z


      -----BEGIN PGP SIGNATURE-----

      iHUEARYKAB0WIQQIgZT4Buut7htIscvAo4xJuyJY6AUCZvOjwQAKCRDAo4xJuyJY
      6JHoAQC2o7ABiFi0EdYtw/2YdFvBvVG9lv6ZK2PYS7GlGGsN/QD9Ee82Fd0/yiCO
      kDSN/3PhZqnWAHIltG3Fnshf/x0NDAg=
      =Meg5
      -----END PGP SIGNATURE-----      
spec:
  selector:
    app: dummy-app
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080

Matrix Synapse

apiVersion: v1
kind: Service
metadata:
  name: well-known-matrix
  annotations:
    well-known.252.no/directory: matrix
    well-known.252.no/format: json
    well-known.252.no/client: |
      {
        "m.homeserver": {
            "base_url": "https://synapse.${PUBLIC_DOMAIN}"
        },
        "org.matrix.msc3575.proxy": {
          "url": "https://slidingsync.${PUBLIC_DOMAIN}"
        },
        "org.matrix.msc2965.authentication": {
          "issuer": "https://auth.matrix.${PUBLIC_DOMAIN}/",
          "account": "https://auth.matrix.${PUBLIC_DOMAIN}/account/"
        }
      }      
    well-known.252.no/server: |
      {"m.server":"synapse.${PUBLIC_DOMAIN}:443"}      
spec:
  selector:
    app: dummy-app
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: webfinger-oidc
  annotations:
    well-known.252.no/webfinger.json: |
      {
        "subject": "acct:${PUBLIC_EMAIL}",
        "links": [
          {
            "rel": "http://openid.net/specs/connect/1.0/issuer",
            "href": "https://auth.${PUBLIC_DOMAIN}"
          }
        ]
      }      
spec:
  selector:
    app: dummy-app
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080

Query Example

curl https://[ingress]/.well-known/test.json

{
    "example": "value"
}

Gratitude

This version of well-known is based on the work by Stenic.