The Kubernetes connectivity has the following requirements:

• Kubernetes 1.19+
• Metrics Service
• An Ingress controller
  • Optionally: Gateway-API

The Kubernetes connection is configured in the kubernetes.yaml file. There are 3 modes to choose from:

• disabled - disables kubernetes connectivity
• default - uses the default kubeconfig resolution
• cluster - uses a service account inside the cluster

mode: default

To configure Kubernetes gateway-api, ingress or ingressRoute service discovery, add one or multiple of the following settings.

Example settings:

ingress: true # default, enable ingress only

or

ingress: true # default, enable ingress
traefik: true # enable traefik ingressRoute
gateway: true # enable gateway-api

Services#

Once the Kubernetes connection is configured, individual services can be configured to pull statistics. Only CPU and Memory are currently supported.

Inside of the service you'd like to connect to a pod:

- Emby:
  icon: emby.png
  href: "http://emby.home/"
  description: Media server
  namespace: media # The kubernetes namespace the app resides in
  app: emby # The name of the deployed app

The app field is used to create a label selector, in this example case it would match pods with the label: app.kubernetes.io/name=emby.

Sometimes this is insufficient for complex or atypical application deployments. In these cases, the podSelector field can be used. Any field selector can be used with it, so it allows for some very powerful selection capabilities.

For instance, it can be utilized to roll multiple underlying deployments under one application to see a high-level aggregate:

- Element Chat:
    icon: matrix-light.png
    href: https://chat.example.com
    description: Matrix Synapse Powered Chat
    app: matrix-element
    namespace: comms
    podSelector: >-
      app.kubernetes.io/instance in (
          matrix-element,
          matrix-media-repo,
          matrix-media-repo-postgresql,
          matrix-synapse
      )

!!! note

A blank string as a podSelector does not deactivate it, but will actually select all pods in the namespace. This is a useful way to capture the resource usage of a complex application siloed to a single namespace, like Longhorn.

Automatic Service Discovery#

Homepage features automatic service discovery by Ingress annotations. All configuration options can be applied using typical annotation syntax, beginning with gethomepage.dev/.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: emby
  annotations:
    gethomepage.dev/enabled: "true"
    gethomepage.dev/description: Media Server
    gethomepage.dev/group: Media
    gethomepage.dev/icon: emby.png
    gethomepage.dev/name: Emby
    gethomepage.dev/widget.type: "emby"
    gethomepage.dev/widget.url: "https://emby.example.com"
    gethomepage.dev/widget.headers.X-Auth-Key: "your-secret-here"
    gethomepage.dev/pod-selector: ""
    gethomepage.dev/weight: 10 # optional
    gethomepage.dev/instance: "public" # optional
spec:
  rules:
    - host: emby.example.com
      http:
        paths:
          - backend:
              service:
                name: emby
                port:
                  number: 8080
            path: /
            pathType: Prefix

When the Kubernetes cluster connection has been properly configured, this service will be automatically discovered and added to your Homepage. You do not need to specify the namespace or app values, as they will be automatically inferred.

If you are using multiple instances of homepage, an instance annotation can be specified to limit services to a specific instance. If no instance is provided, the service will be visible on all instances.

If you have a single service that needs to be shown on multiple specific instances of homepage (but not on all of them), the service can be annotated by multiple instance.name annotations, where name can be the names of your specific multiple homepage instances. For example, a service that is annotated with gethomepage.dev/instance.public: "" and gethomepage.dev/instance.internal: "" will be shown on public and internal homepage instances.

Use the gethomepage.dev/pod-selector selector to specify the pod used for the health check. For example, a service that is annotated with gethomepage.dev/pod-selector: app.kubernetes.io/name=deployment would link to a pod with the label app.kubernetes.io/name: deployment.

Traefik IngressRoute support#

If enabled (with traefik: true in kubernetes.yaml), homepage can also read ingresses defined using the Traefik IngressRoute custom resource definition. Due to the complex nature of Traefik routing rules, it is required for the gethomepage.dev/href annotation to be set:

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: emby
  annotations:
    gethomepage.dev/href: "https://emby.example.com"
    gethomepage.dev/enabled: "true"
    gethomepage.dev/description: Media Server
    gethomepage.dev/group: Media
    gethomepage.dev/icon: emby.png
    gethomepage.dev/app: emby-app # optional, may be needed if app.kubernetes.io/name != ingress metadata.name
    gethomepage.dev/name: Emby
    gethomepage.dev/widget.type: "emby"
    gethomepage.dev/widget.url: "https://emby.example.com"
    gethomepage.dev/pod-selector: ""
    gethomepage.dev/weight: 10 # optional
    gethomepage.dev/instance: "public" # optional
spec:
  entryPoints:
    - websecure
  routes:
    - kind: Rule
      match: Host(`emby.example.com`)
      services:
        - kind: Service
          name: emby
          namespace: emby
          port: 8080
          scheme: http
          strategy: RoundRobin
          weight: 10

If the href attribute is not present, Homepage will ignore the specific IngressRoute.

Gateway API HttpRoute support#

Homepage also features automatic service discovery for Gateway API. Service definitions are read by annotating the HttpRoute custom resource definition and are indentical to the Ingress example as defined in Automatic Service Discovery.

To enable Gateway API HttpRoute update kubernetes.yaml to include:

gateway: true # enable gateway-api

Using the unoffocial helm chart?#

If you are using the unofficial helm chart ensure that the ClusterRole has required permissions for gateway.networking.k8s.io.

See ClusterRole and ClusterRoleBinding

Caveats#

Similarly to Docker service discovery, there currently is no rigid ordering to discovered services and discovered services will be displayed above those specified in the services.yaml.

Adding extra configuration files#

Some Homepage features (for example, Proxmox) require additional configuration files such as proxmox.yaml.
When running Homepage on Kubernetes, these files must be provided via a ConfigMap and mounted into the container at /app/config.

ConfigMap example#

apiVersion: v1
kind: ConfigMap
metadata:
  name: homepage
data:
  proxmox.yaml: |
    pve:
      url: https://proxmox.host.or.ip:8006
      token: username@pam!Token ID
      secret: secret

Mount the file into /app/config by updating the Deployment:

volumeMounts:
  - mountPath: /app/config/proxmox.yaml
    name: homepage-config
    subPath: proxmox.yaml