diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..7b63a99 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,5 @@ +/node_modules/ +/.github/ +/.vscode/ +/chart/ +/.env \ No newline at end of file diff --git a/.github/release-drafter-config.yml b/.github/release-drafter-config.yml new file mode 100644 index 0000000..321e15f --- /dev/null +++ b/.github/release-drafter-config.yml @@ -0,0 +1,48 @@ +name-template: "$RESOLVED_VERSION 🌈" +tag-template: "v$RESOLVED_VERSION" +categories: + - title: "🚀 Features" + labels: + - "feature" + - "enhancement" + - title: "🐛 Bug Fixes" + labels: + - "fix" + - "bugfix" + - "bug" + - title: "🧰 Maintenance" + label: "chore" +change-template: "- $TITLE @$AUTHOR (#$NUMBER)" +change-title-escapes: '\<*_&' # You can add # and @ to disable mentions, and add ` to disable code blocks. +version-resolver: + major: + labels: + - "major" + minor: + labels: + - "minor" + patch: + labels: + - "patch" + default: patch +autolabeler: + - label: "chore" + files: + - "*.md" + branch: + - '/docs{0,1}\/.+/' + - label: "bug" + branch: + - '/fix\/.+/' + title: + - "/fix/i" + - label: "enhancement" + branch: + - '/feature\/.+/' + - '/feat\/.+/' + title: + - "/feat:.+/" +template: | + ## Changes + + $CHANGES \ No newline at end of file diff --git a/.github/workflows/auto-labeler.yml b/.github/workflows/auto-labeler.yml new file mode 100644 index 0000000..03d5366 --- /dev/null +++ b/.github/workflows/auto-labeler.yml @@ -0,0 +1,21 @@ +name: Auto Labeler +on: + pull_request: + types: [opened, reopened, synchronize] + +permissions: + contents: read + +jobs: + auto-labeler: + permissions: + contents: write + pull-requests: write + runs-on: ubuntu-latest + steps: + - uses: release-drafter/release-drafter@v6 + with: + config-name: release-drafter-config.yml + disable-releaser: true + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml new file mode 100644 index 0000000..83586da --- /dev/null +++ b/.github/workflows/main.yml @@ -0,0 +1,79 @@ +name: Build, tag and release + +on: + push: + branches: + - main + pull_request: + types: + - opened + - synchronize + +env: + environment: test + release_channel: latest + DO_NOT_TRACK: "1" + NODE_VERSION: "23.x" + DOCKER_REGISTRY: ghcr.io + IMAGE_NAME: ${{ github.repository }} + PNPM_VERSION: 10.6.0 + +permissions: + contents: read + packages: read + +jobs: + build: + name: Build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: "${{ env.NODE_VERSION }}" + registry-url: "${{ env.NODE_REGISTRY }}" + + - uses: pnpm/action-setup@v4 + name: Install pnpm + with: + version: ${{ env.PNPM_VERSION }} + run_install: false + + - name: Get pnpm store directory + shell: bash + run: | + echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV + + - uses: actions/cache@v4 + name: Setup pnpm cache + with: + path: ${{ env.STORE_PATH }} + key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }} + restore-keys: | + ${{ runner.os }}-pnpm-store- + + - name: Install dependencies + run: pnpm install + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + + - name: Run tests + run: pnpm test + + update-release-draft: + name: Update release drafter + if: github.ref == 'refs/heads/main' + permissions: + contents: write + pull-requests: write + needs: build + environment: release + runs-on: ubuntu-latest + steps: + - uses: release-drafter/release-drafter@v6 + with: + config-name: release-drafter-config.yml + publish: true + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/publish-tag.yml b/.github/workflows/publish-tag.yml new file mode 100644 index 0000000..89a8855 --- /dev/null +++ b/.github/workflows/publish-tag.yml @@ -0,0 +1,65 @@ +name: Publish tag + +on: + push: + branches: + - 'main' + tags: + - "v[0-9]+.[0-9]+.[0-9]+" + +env: + environment: test + release_channel: latest + DO_NOT_TRACK: "1" + NODE_VERSION: "23.x" + DOCKER_REGISTRY: ghcr.io + IMAGE_NAME: ${{ github.repository }} + PNPM_VERSION: 10.6.0 + +permissions: + contents: read + packages: read + +jobs: + release: + permissions: + contents: read + packages: write + attestations: write + id-token: write + pages: write + name: Release + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Log in to the Container registry + uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1 + with: + registry: ${{ env.DOCKER_REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Extract metadata (tags, labels) for Docker + id: meta + uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7 + with: + images: ${{ env.DOCKER_REGISTRY }}/${{ env.IMAGE_NAME }} + + - name: Build and push Docker image + id: push + uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4 + with: + context: . + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + + - name: Generate artifact attestation + uses: actions/attest-build-provenance@v2 + with: + subject-name: ${{ env.DOCKER_REGISTRY }}/${{ env.IMAGE_NAME}} + subject-digest: ${{ steps.push.outputs.digest }} + push-to-registry: true \ No newline at end of file diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..3f3e99c --- /dev/null +++ b/Dockerfile @@ -0,0 +1,6 @@ +FROM node:23-alpine +RUN corepack enable +COPY package.json pnpm-lock.yaml ./ +RUN pnpm install --frozen-lockfile --prod +COPY . . +CMD ["node", "src/index.ts"] \ No newline at end of file diff --git a/README.md b/README.md index 1818e46..113cc9b 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,282 @@ # homelab-operator -To install dependencies: +A Kubernetes operator designed for homelab environments that simplifies the +management of PostgreSQL databases and Kubernetes secrets. Built with TypeScript +and designed to run efficiently in resource-constrained environments. + +## Features + +- **PostgreSQL Database Management**: Automatically create and manage PostgreSQL + databases and roles +- **Secret Management**: Generate and manage Kubernetes secrets with + configurable data +- **Owner References**: Automatic cleanup when resources are deleted +- **Status Tracking**: Comprehensive status conditions and error reporting +- **Lightweight**: Minimal resource footprint suitable for homelab environments + +## Architecture + +The operator manages two main Custom Resource Definitions (CRDs): + +### PostgresDatabase + +Manages PostgreSQL databases and their associated roles: + +- Creates a PostgreSQL role with a secure random password +- Creates a database owned by that role +- Generates a Kubernetes secret containing database credentials +- Ensures proper cleanup through owner references + +### SecretRequest + +Generates Kubernetes secrets with configurable data: + +- Supports custom secret names +- Configurable data fields with various encodings +- Automatic secret lifecycle management + +## Installation + +### Prerequisites + +- Kubernetes cluster (1.20+) +- PostgreSQL instance accessible from the cluster +- Helm 3.x (for chart-based installation) + +### Using Helm Chart + +1. Clone the repository: ```bash -bun install +git clone +cd homelab-operator ``` -To run: +2. Install using Helm: ```bash -bun run index.ts +helm install homelab-operator ./chart \ + --set-string env.POSTGRES_HOST= \ + --set-string env.POSTGRES_USER= \ + --set-string env.POSTGRES_PASSWORD= ``` -This project was created using `bun init` in bun v1.2.16. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime. +### Using kubectl + +1. Build and push the Docker image: + +```bash +docker build -t your-registry/homelab-operator:latest . +docker push your-registry/homelab-operator:latest +``` + +2. Apply the Kubernetes manifests: + +```bash +kubectl apply -f chart/templates/ +``` + +## Configuration + +The operator is configured through environment variables: + +| Variable | Description | Required | Default | +| ------------------- | ---------------------------------------- | -------- | ------- | +| `POSTGRES_HOST` | PostgreSQL server hostname | Yes | - | +| `POSTGRES_USER` | PostgreSQL admin username | Yes | - | +| `POSTGRES_PASSWORD` | PostgreSQL admin password | Yes | - | +| `POSTGRES_PORT` | PostgreSQL server port | No | 5432 | +| `LOG_LEVEL` | Logging level (debug, info, warn, error) | No | info | + +## Usage + +### PostgreSQL Database + +Create a PostgreSQL database with an associated role: + +```yaml +apiVersion: homelab.mortenolsen.pro/v1 +kind: PostgresDatabase +metadata: + name: my-app-db + namespace: my-namespace +spec: {} +``` + +This will create: + +- A PostgreSQL role named `my-app-db` +- A PostgreSQL database named `my-namespace_my-app-db` owned by the role +- A Kubernetes secret `postgres-database-my-app-db` containing: + - `name`: Base64-encoded database name + - `user`: Base64-encoded username + - `password`: Base64-encoded password + +### Secret Request + +Generate a Kubernetes secret with custom data: + +```yaml +apiVersion: homelab.mortenolsen.pro/v1 +kind: SecretRequest +metadata: + name: my-secret + namespace: my-namespace +spec: + secretName: app-config + data: + - key: api-key + value: "my-api-key" + encoding: base64 + - key: database-url + value: "postgresql://user:pass@host:5432/db" + - key: random-token + length: 32 + chars: "abcdefghijklmnopqrstuvwxyz0123456789" +``` + +### Accessing Created Resources + +To retrieve database credentials: + +```bash +# Get the secret +kubectl get secret postgres-database-my-app-db -o jsonpath='{.data.user}' | base64 -d +kubectl get secret postgres-database-my-app-db -o jsonpath='{.data.password}' | base64 -d +kubectl get secret postgres-database-my-app-db -o jsonpath='{.data.name}' | base64 -d +``` + +## Development + +### Prerequisites + +- [Bun](https://bun.sh/) runtime +- [pnpm](https://pnpm.io/) package manager +- Docker (for building images) +- Access to a Kubernetes cluster for testing + +### Setup + +1. Clone the repository: + +```bash +git clone +cd homelab-operator +``` + +2. Install dependencies: + +```bash +pnpm install +``` + +3. Set up development environment: + +```bash +cp .env.example .env +# Edit .env with your PostgreSQL connection details +``` + +### Running Locally + +For development, you can run the operator locally against a remote cluster: + +```bash +# Ensure kubectl is configured for your development cluster +export KUBECONFIG=~/.kube/config + +# Set PostgreSQL connection environment variables +export POSTGRES_HOST=localhost +export POSTGRES_USER=postgres +export POSTGRES_PASSWORD=yourpassword + +# Run the operator +bun run src/index.ts +``` + +### Development with Docker Compose + +A development environment with PostgreSQL is provided: + +```bash +docker-compose -f docker-compose.dev.yaml up -d +``` + +### Building + +Build the Docker image: + +```bash +docker build -t homelab-operator:latest . +``` + +### Testing + +```bash +# Run linting +pnpm run test:lint + +# Apply test resources +kubectl apply -f test.yaml +``` + +## Contributing + +1. Fork the repository +2. Create a feature branch: `git checkout -b feature/new-feature` +3. Make your changes and add tests +4. Run linting: `pnpm run test:lint` +5. Commit your changes: `git commit -am 'Add new feature'` +6. Push to the branch: `git push origin feature/new-feature` +7. Submit a pull request + +## Project Structure + +``` +├── chart/ # Helm chart for deployment +├── src/ +│ ├── crds/ # Custom Resource Definitions +│ │ ├── postgres/ # PostgreSQL database management +│ │ └── secrets/ # Secret generation +│ ├── custom-resource/ # Base CRD framework +│ ├── database/ # Database migrations +│ ├── services/ # Core services +│ │ ├── config/ # Configuration management +│ │ ├── k8s.ts # Kubernetes API client +│ │ ├── log/ # Logging service +│ │ ├── postgres/ # PostgreSQL service +│ │ └── secrets/ # Secret management +│ └── utils/ # Utilities and constants +├── Dockerfile # Container build configuration +└── docker-compose.dev.yaml # Development environment +``` + +## License + +This project is licensed under the MIT License - see the LICENSE file for +details. + +## Support + +For support and questions: + +- Create an issue in the GitHub repository +- Check existing issues for similar problems +- Review the logs using `kubectl logs -l app=homelab-operator` + +## Status Monitoring + +Monitor the operator status: + +```bash +# Check operator logs +kubectl logs -l app=homelab-operator -f + +# Check CRD status +kubectl get postgresdatabases +kubectl get secretrequests + +# Describe resources for detailed status +kubectl describe postgresdatabase my-app-db +kubectl describe secretrequest my-secret +``` diff --git a/chart/Chart.yaml b/chart/Chart.yaml new file mode 100644 index 0000000..8112c70 --- /dev/null +++ b/chart/Chart.yaml @@ -0,0 +1,6 @@ +apiVersion: v2 +name: homelab-operator +description: A Helm chart for deploying the homelab-operator +type: application +version: 0.1.0 +appVersion: "1.0.0" # This is the version of the app being deployed diff --git a/chart/templates/_helpers.tpl b/chart/templates/_helpers.tpl new file mode 100644 index 0000000..57652c0 --- /dev/null +++ b/chart/templates/_helpers.tpl @@ -0,0 +1,55 @@ +{{/* +Expand the name of the chart. +*/}} +{{- define "homelab-operator.name" -}} +{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }} +{{- end }} + +{{/* +Create a default fully qualified app name. +We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec). +If release name contains chart name it will be used as a full name. +*/}} +{{- define "homelab-operator.fullname" -}} +{{- if .Values.fullnameOverride }} +{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }} +{{- else }} +{{- $name := default .Chart.Name .Values.nameOverride }} +{{- if contains $name .Release.Name }} +{{- .Release.Name | trunc 63 | trimSuffix "-" }} +{{- else }} +{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }} +{{- end }} +{{- end }} +{{- end }} + +{{/* +Create chart-level labels to be applied to every resource that comes from this chart. +*/}} +{{- define "homelab-operator.labels" -}} +helm.sh/chart: {{ include "homelab-operator.name" . }} +{{ include "homelab-operator.selectorLabels" . }} +{{- if .Chart.AppVersion }} +app.kubernetes.io/version: {{ .Chart.AppVersion | quote }} +{{- end }} +app.kubernetes.io/managed-by: {{ .Release.Service }} +{{- end }} + +{{/* +Selector labels +*/}} +{{- define "homelab-operator.selectorLabels" -}} +app.kubernetes.io/name: {{ include "homelab-operator.name" . }} +app.kubernetes.io/instance: {{ .Release.Name }} +{{- end }} + +{{/* +Create the name of the service account to use +*/}} +{{- define "homelab-operator.serviceAccountName" -}} +{{- if .Values.serviceAccount.create }} +{{- default (include "homelab-operator.fullname" .) .Values.serviceAccount.name }} +{{- else }} +{{- default "default" .Values.serviceAccount.name }} +{{- end }} +{{- end }} diff --git a/chart/templates/clusterrole.yaml b/chart/templates/clusterrole.yaml new file mode 100644 index 0000000..271ae62 --- /dev/null +++ b/chart/templates/clusterrole.yaml @@ -0,0 +1,14 @@ +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: {{ include "homelab-operator.fullname" . }} +rules: +- apiGroups: [""] + resources: ["secrets"] + verbs: ["create", "get", "watch", "list"] +- apiGroups: ["*"] + resources: ["*"] + verbs: ["get", "watch", "list", "patch"] +- apiGroups: ["apiextensions.k8s.io"] + resources: ["customresourcedefinitions"] + verbs: ["get", "create", "replace"] diff --git a/chart/templates/clusterrolebinding.yaml b/chart/templates/clusterrolebinding.yaml new file mode 100644 index 0000000..636defe --- /dev/null +++ b/chart/templates/clusterrolebinding.yaml @@ -0,0 +1,12 @@ +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: {{ include "homelab-operator.fullname" . }} +subjects: +- kind: ServiceAccount + name: {{ include "homelab-operator.serviceAccountName" . }} + namespace: {{ .Release.Namespace }} +roleRef: + kind: ClusterRole + name: {{ include "homelab-operator.fullname" . }} + apiGroup: rbac.authorization.k8s.io diff --git a/chart/templates/deployment.yaml b/chart/templates/deployment.yaml new file mode 100644 index 0000000..c44c51e --- /dev/null +++ b/chart/templates/deployment.yaml @@ -0,0 +1,47 @@ +apiVersion: apps/v1 +kind: Deployment +metadata: + name: {{ include "homelab-operator.fullname" . }} + labels: + {{- include "homelab-operator.labels" . | nindent 4 }} +spec: + replicas: 1 + selector: + matchLabels: + {{- include "homelab-operator.selectorLabels" . | nindent 6 }} + template: + metadata: + {{- with .Values.podAnnotations }} + annotations: + {{- toYaml . | nindent 8 }} + {{- end }} + labels: + {{- include "homelab-operator.selectorLabels" . | nindent 8 }} + spec: + {{- with .Values.imagePullSecrets }} + imagePullSecrets: + {{- toYaml . | nindent 8 }} + {{- end }} + serviceAccountName: {{ include "homelab-operator.serviceAccountName" . }} + securityContext: + {{- toYaml .Values.podSecurityContext | nindent 8 }} + containers: + - name: {{ .Chart.Name }} + securityContext: + {{- toYaml .Values.securityContext | nindent 12 }} + image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}" + imagePullPolicy: {{ .Values.image.pullPolicy }} + resources: + {{- toYaml .Values.resources | nindent 12 }} + {{- with .Values.nodeSelector }} + nodeSelector: + {{- toYaml . | nindent 8 }} + {{- end }} + {{- with .Values.affinity }} + affinity: + {{- toYaml . | nindent 8 }} + {{- end }} + {{- with .Values.tolerations }} + tolerations: + {{- toYaml . | nindent 8 }} + {{- end }} diff --git a/chart/templates/serviceaccount.yaml b/chart/templates/serviceaccount.yaml new file mode 100644 index 0000000..313fd84 --- /dev/null +++ b/chart/templates/serviceaccount.yaml @@ -0,0 +1,12 @@ +{{- if .Values.serviceAccount.create -}} +apiVersion: v1 +kind: ServiceAccount +metadata: + name: {{ include "homelab-operator.serviceAccountName" . }} + labels: + {{- include "homelab-operator.labels" . | nindent 4 }} + {{- with .Values.serviceAccount.annotations }} + annotations: + {{- toYaml . | nindent 4 }} + {{- end }} +{{- end }} diff --git a/chart/values.yaml b/chart/values.yaml new file mode 100644 index 0000000..f14bf5e --- /dev/null +++ b/chart/values.yaml @@ -0,0 +1,53 @@ +# Default values for homelab-operator. +# This is a YAML-formatted file. +# Declare variables to be passed into your templates. + +image: + repository: ghcr.io/morten-olsen/homelab-operator + pullPolicy: IfNotPresent + # Overrides the image tag whose default is the chart appVersion. + tag: "" + +imagePullSecrets: [] +nameOverride: "" +fullnameOverride: "" + +serviceAccount: + # Specifies whether a service account should be created + create: true + # Annotations to add to the service account + annotations: {} + # The name of the service account to use. + # If not set and create is true, a name is generated using the fullname template + name: "" + +podAnnotations: {} + +podSecurityContext: {} + # fsGroup: 2000 + +securityContext: {} + # capabilities: + # drop: + # - ALL + # readOnlyRootFilesystem: true + # runAsNonRoot: true + # runAsUser: 1000 + +resources: {} + # We usually recommend not to specify default resources and to leave this as a conscious + # choice for the user. This also increases chances charts run on environments with little + # resources, such as Minikube. If you do want to specify resources, uncomment the following + # lines, adjust them as necessary, and remove the curly braces after 'resources:'. + # limits: + # cpu: 100m + # memory: 128Mi + # requests: + # cpu: 100m + # memory: 128Mi + +nodeSelector: {} + +tolerations: [] + +affinity: {} diff --git a/package.json b/package.json index 593bd44..8ca67d8 100644 --- a/package.json +++ b/package.json @@ -27,13 +27,14 @@ "pg": "^8.16.3", "sqlite3": "^5.1.7" }, - "packageManager": "pnpm@10.6.0+sha512.df0136e797db0cfa7ec1084e77f3bdf81bacbae9066832fbf95cba4c2140ad05e64f316cde51ce3f99ea00a91ffc702d6aedd3c0f450f895e3e7c052fe573cd8", + "packageManager": "pnpm@10.6.0", "pnpm": { "onlyBuiltDependencies": [ "sqlite3" ] }, "scripts": { + "test": "echo 'No tests'", "test:lint": "eslint" } } diff --git a/src/crds/secrets/secrets.request.ts b/src/crds/secrets/secrets.request.ts index f2d2f3f..15ea538 100644 --- a/src/crds/secrets/secrets.request.ts +++ b/src/crds/secrets/secrets.request.ts @@ -51,7 +51,7 @@ class SecretRequest extends CustomResource { } } if (current) { - console.log('secret already exists', current); + services.log.debug('secret already exists', { current }); // TODO: Add update logic return; } diff --git a/src/custom-resource/custom-resource.registry.ts b/src/custom-resource/custom-resource.registry.ts index 543c5b2..bb73535 100644 --- a/src/custom-resource/custom-resource.registry.ts +++ b/src/custom-resource/custom-resource.registry.ts @@ -51,7 +51,6 @@ class CustomResourceRegistry { }; #onResourceEvent = async (type: string, obj: any) => { - console.log(type, this.kinds); const { kind } = obj; const crd = this.getByKind(kind); if (!crd) { diff --git a/src/utils/service.ts b/src/utils/service.ts index c0439e2..e624d12 100644 --- a/src/utils/service.ts +++ b/src/utils/service.ts @@ -4,9 +4,6 @@ type Dependency = new (services: Services) => T; class Services { #instances = new Map, unknown>(); - constructor() { - console.log('Constructor', 'bar'); - } public get log() { return this.get(LogService);