VoxKube

Puppet, run by Kubernetes.

VoxKube is an operator for OpenVox, the open-source Puppet 8. Describe your Puppet server and the machines it manages in YAML; the operator runs the CA, the compilers and PuppetDB, deploys your code from Git, and keeps it all that way.

$ helm upgrade --install voxkube-operator \
    oci://ghcr.io/yboikov/charts/voxkube-operator \
    --namespace openvox --create-namespace
voxcluster.yamlPoint at a field to read its spec
apiVersion: voxkube.io/v1alpha1
kind: VoxCluster
metadata:
  name: production
  namespace: openvox
spec:
  code:
    mode: git
    git:
      remote: https://github.com/acme/puppet-control.git
      authType: githubApp
      githubApp:
        appID: 123456
        installationID: 98765432
        privateKeySecretRef:            # synced from your vault by ESO
          name: github-app
          key: private-key.pem
      pollInterval: 60s
  ca:
    autosignMode: voxnode               # approve machines with VoxNode
  server:
    replicas: 2
    autoscaling:
      enabled: true
      maxReplicas: 6
  database:
    postgres:
      mode: external                    # e.g. CloudNativePG
      host: openvox-pg-rw
      credentialsSecretRef: openvox-pg-app
  networking:
    server:
      externalHostname: puppet.example.com
      openShiftRoute:
        enabled: true
    ca:
      externalHostname: puppet-ca.example.com
      openShiftRoute:
        enabled: true

Three resources, one installation

Everything is configured through three custom resources. Each one is a YAML file you can keep in Git.

VoxClusterkubectl get vc
The Puppet server

Creates and runs the whole OpenVox stack: a CA, a pool of stateless compilers, OpenVox DB (PuppetDB) on your PostgreSQL, and your control repo deployed from Git. One per Puppet installation.

VoxNodekubectl get vn
One managed machine

Approves the machine's certificate and decides what Puppet applies to it. It can also hand the machine TLS certificates from cert-manager and secrets through Hiera, mute its alerts, and retire it cleanly.

VoxDiscoverykubectl get vd
Machines for Prometheus

Asks OpenVox DB which machines exist, for example every machine that runs profile::node_exporter, and publishes them as Prometheus targets with labels like their Puppet role.

How a machine joins

From a fresh VM to a monitored, configured machine, without logging in to the CA.

  1. The agent asks for a certificate

    The new machine sends a certificate request to the CA.

  2. A VoxNode appears

    The operator creates a VoxNode waiting for approval, unless you added one to Git first.

  3. You approve it

    Set state: Active and the machine's role. The operator signs the certificate.

  4. Puppet configures it

    The agent gets its catalog from the compilers, built from your Git code and the VoxNode's role.

  5. OpenVox DB knows it

    Facts and run reports land in PuppetDB; the VoxNode shows the last run.

  6. Prometheus scrapes it

    A VoxDiscovery picks the machine up and publishes it as a scrape target.

Made for OpenShift and GitOps

OpenShift Routes included

Every pod runs under the default restricted-v2 SCC. Turn on a Route and the operator creates a TLS-passthrough Route for the compilers or the CA, adds the hostname to the certificate and reports the URL agents should use. Agents outside the cluster connect on port 443.

networking:
  server:
    externalHostname: puppet.example.com
    openShiftRoute:
      enabled: true

Code from Git, as a GitHub App

Every branch of your control repo becomes a Puppet environment, deployed with g10k. Authenticate as a GitHub App, and the operator renews its short-lived tokens itself; SSH keys and HTTPS tokens work too. The operator polls Git, so no webhook has to get through your firewall.

code:
  mode: git
  git:
    authType: githubApp   # or sshKey, httpsToken