operator/charts/apps/AGENT.md

Agent Documentation

This document describes how to create a new application chart for the homelab operator.

Chart Structure

Each application has its own chart located in a directory under charts/apps. The chart should contain the following files:

• Chart.yaml: The chart metadata.
• values.yaml: The default values for the chart.
• templates/: A directory containing the Kubernetes resource templates.

Custom Resources

The homelab operator uses several custom resources to manage applications. These resources are defined in the templates directory of the chart.

PostgresDatabase

If the application requires a PostgreSQL database, you can create a PostgresDatabase resource. The operator will automatically create a database and a secret containing the connection details. The secret will have the same name as the release with a -pg-connection postfix.

Example:

# templates/database.yaml
apiVersion: homelab.mortenolsen.pro/v1
kind: PostgresDatabase
metadata:
  name: "{{ .Release.Name }}"
spec:
  environment: "{{ .Values.globals.environment }}"

The secret has the following values:

• database: name of the created database
• host: the hostname of the postgres server
• port: the port of the postgres server
• url: combined url in the format postgresql://{user}:{password}@{host}:{port}/{database}

OidcClient

If the application requires OIDC authentication, you can create an OidcClient resource. The operator will automatically create an OIDC client and a secret containing the client ID and secret. The secret will have the same name as the release with a -client postfix.

You need to specify the redirect URIs for the OIDC client. The subdomain is taken from the values.yaml file.

Example:

# templates/client.yaml
apiVersion: homelab.mortenolsen.pro/v1
kind: OidcClient
metadata:
  name: "{{ .Release.Name }}"
spec:
  environment: "{{ .Values.globals.environment }}"
  redirectUris:
    - path: /user/oauth2/Authentik/callback
      subdomain: "{{ .Values.subdomain }}"
      matchingMode: strict

The secret has the following value:

• authorization: Authorization endpoint
• clientId
• clientSecret
• configuration: autodiscovery endpoint
• configurationIssuer: issuer url
• endSession: end session endpoint
• jwks: jwks endpoint
• token: token endpoint
• userinfo: user info endpoint

HttpService and ExternalHttpService

To expose the application, you can use either an HttpService or an ExternalHttpService resource.

• HttpService: This will expose the application through the Istio gateway. This is for internal access only.
• ExternalHttpService: This will expose the application through a CloudFlare tunnel. This is for external access.

Both resources take a subdomain and a destination as parameters. The destination is the Kubernetes service to route traffic to.

Example of HttpService:

# templates/http-service.yaml
apiVersion: homelab.mortenolsen.pro/v1
kind: HttpService
metadata:
  name: "{{ .Release.Name }}"
spec:
  environment: "{{ .Values.globals.environment }}"
  subdomain: "{{ .Values.subdomain }}"
  destination:
    host: "{{ .Release.Name }}.{{ .Release.Namespace }}.svc.cluster.local"
    port:
      number: 80

Example of ExternalHttpService:

# templates/external-http-service.yaml
apiVersion: homelab.mortenolsen.pro/v1
kind: ExternalHttpService
metadata:
  name: "{{ .Release.Name }}"
spec:
  environment: "{{ .Values.globals.environment }}"
  subdomain: "{{ .Values.subdomain }}"
  destination:
    host: "{{ .Release.Name }}.{{ .Release.Namespace }}.svc.cluster.local"
    port:
      number: 80

values.yaml

The values.yaml file should contain the following values:

• globals.environment: The environment the application is running in (e.g., prod, dev).
• image.repository: The Docker image repository.
• image.tag: The Docker image tag.
• subdomain: The subdomain for the application.

Example:

# values.yaml
globals:
  environment: prod
image:
  repository: docker.gitea.com/gitea
  tag: latest
subdomain: gitea