HomepageSC

HomepageSC provides Kubernetes Ingress support to Homepage by Ben Phelps.

Running as a side car container to your HomePage container, this side car enumerates all Ingresses in your Kubernetes cluster, building a service.yaml fully populated with all your endpoints.

Usage

Deploy Homepage and HomepageSC in a single deployment with a shared volume for them to exchange their configuration.

## Deploy Homepage and HomepageSC with a shared config volume
apiVersion: apps/v1
kind: Deployment
metadata:
  name: homepage
  namespace: homepage
  labels:
    app: homepage
spec:
  selector:
    matchLabels:
      app: homepage
  template:
    metadata:
      labels:
        app: homepage
    spec:
      volumes:
        - name: shared-data
          emptyDir: {}
      serviceAccountName: homepage-discovery
      containers:
        - name: homepage
          image: 'ghcr.io/benphelps/homepage:latest'
          imagePullPolicy: Always
          ports:
            - name: http
              containerPort: 3000
              protocol: TCP
          volumeMounts:
            - mountPath: "/app/config" # Mount the shared config directory
              name: shared-data
        - name: homepagesc
          image: 'ghcr.io/uatec/homepagesc:latest'
          volumeMounts:
            - mountPath: "/app/config" # Mount the shared config directory
              name: shared-data
          env:
            - name: OUTPUTLOCATION # Tell HomepageSC to output services in to the shared directory
              value: "/app/config/services.yaml"
            - name: INCLUSTER # Use kubeconfig provided by the cluster itself
              value: "true"


# Grant HomepageSC permission to discover ingresses and widget secrets
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: homepage-discovery
  namespace: homepage
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: homepage-discovery
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: ServiceAccount
  name: homepage-discovery
  namespace: homepage

Configure how your ingress appears with annotations to give Homepage further information about them.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ghost
  namespace: publishing
  annotations:
    homepagesc.neutrino.io/appName: Awesome Blog
    homepagesc.neutrino.io/group: Publishing
    homepagesc.neutrino.io/healthCheck: http://ghost.publish.svc.cluster.local:2368/ghost/api/v3/admin/site
    homepagesc.neutrino.io/icon: https://github.com/walkxcode/dashboard-icons/raw/main/png/ghost.png
spec:
  rules:
  - host: www.awesomeblog.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: web
            port:
              name: http

Annotations

HomepageSC exposes extra Homepage configuration options using ingress annotations. These annotations broadly mirror the service configuration of Homepage.

Annotation	Description
`homepagesc.neutrino.io/enable`	Override the default enabling behaviour by setting this to `true` to show your service or `false` to hide it.
`homepagesc.neutrino.io/appName`	A custom name for your application. Use if you don't want to use the name of the ingress.
`homepagesc.neutrino.io/group`	A custom group name. Use if you want the application to show in a different group than the namespace it is running in.
`homepagesc.neutrino.io/icon`	Services may have an icon attached to them, you can use icons from Dashboard Icons automatically, by passing the name of the icon, with, or without `.png`. You can also specify icons from material design icons with `mdi-XX`. If you would like to load a remote icon, you may pass the URL to it. If you would like to load a local icon, first create a Docker mount to `/app/public/icons` and then reference your icon as `/icons/myicon.png`.
`homepagesc.neutrino.io/description`	Use to provide a subtitle or other additional info to the service tile.
`homepagesc.neutrino.io/target`	Changes the behaviour of links on the homepage. Possible options include `_blank`, `_self`, and `_top`. Use _blank to open links in a new tab, _self to open links in the same tab, and _top to open links in a new window.
`homepagesc.neutrino.io/healthCheck`	Services may have an optional ping property that allows you to monitor the availability of an endpoint you chose and have the response time displayed. You do not need to set your ping URL equal to your href URL.
`homepagesc.neutrino.io/widget_type`	Use to specify the type of widget to be rendered for this service. Widget's are documented on the service widget page.
`homepagesc.neutrino.io/widget_secret`	Specify a widget secret to be added to the `key` field of the widget config. The secret locator format is `{namespace}/{secretName}/{secretField}`.

Settings

HomepageSC or global service settings can be configured using environment variables or command line parameters.

Env Var	Command Line	Default	Description
`INCLUSTER`	`--InCluster` or `--InCluster=[true,false]`	`FALSE`	By default HomepageSC runs in development mode, using your configured kubeconfig. Set this to tell HomepageSC to retrieve config from the cluster it is running in.
`INCLUDEBYDEFAULT`	`--IncludeByDefault` or `--IncludeByDefault=[true,false]`	`true`	Defines the behaviour for ingresses which do not have the `homepagesc.neutrino.io/enable` annotation. Set to false to require services to be explicitly enabled.
`OUTPUTLOCATION`	`--OutputLocation=/app/config/service.yaml`	`undefined`	Instruct HomepageSC to write configuration to a location on disk. This should be `service.yaml` within the HomePage configuration directory. Default behaviour is to write config to stdout to validation.
`DEFAULTTARGET`	`--DefaultTarget=[_blank,_self,_top]`	`undefined`	Change the behaviour of links for all services (which do not specify their own `homepagesc.neutrino.io/target` annotation).

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT