Skip to main content

Addon System

This document covers addon lifecycle management, installation flows, and custom addon creation. For an introduction to addon types and the three addon CRDs, see Concepts: Addons.

AddonDefinition​

AddonDefinitions are cluster-scoped resources that define available addons.

apiVersion: butler.butlerlabs.dev/v1alpha1
kind: AddonDefinition
metadata:
  name: cilium
spec:
  displayName: "Cilium"
  description: "eBPF-based networking, observability, and security"
  category: networking
  platform: true  # Required for cluster operation
  
  chart:
    repository: https://helm.cilium.io
    name: cilium
    defaultVersion: "1.17.0"
    
  # Default values applied to all installations
  defaultValues:
    operator:
      replicas: 1
    hubble:
      enabled: true
      relay:
        enabled: true
        
  # Values that can be overridden by users
  configurableValues:
    - path: hubble.enabled
      description: "Enable Hubble observability"
      type: boolean
    - path: operator.replicas
      description: "Number of operator replicas"
      type: integer
      
  # Dependencies on other addons
  dependencies: []
  
  # Incompatible addons
  conflicts:
    - calico
    - flannel

AddonDefinition Fields​

FieldDescription
displayNameHuman-readable name
descriptionAddon description
categoryCategory (networking, storage, monitoring, etc.)
platformIf true, required for cluster operation
chartHelm chart details
defaultValuesDefault Helm values
configurableValuesUser-overridable values
dependenciesRequired addons
conflictsIncompatible addons

TenantAddon​

TenantAddons represent addon installations on tenant clusters.

apiVersion: butler.butlerlabs.dev/v1alpha1
kind: TenantAddon
metadata:
  name: my-cluster-prometheus
  namespace: team-a
spec:
  clusterRef:
    name: my-cluster
  addon: prometheus
  version: "25.0.0"
  values:
    server:
      retention: 30d
    alertmanager:
      enabled: true

Lifecycle​

Installation Flow​

ManagementAddon​

ManagementAddons install addons on the management cluster itself.

apiVersion: butler.butlerlabs.dev/v1alpha1
kind: ManagementAddon
metadata:
  name: victoria-metrics
spec:
  addon: victoria-metrics
  version: "0.25.0"
  values:
    server:
      retentionPeriod: 90d

ManagementAddons are cluster-scoped and managed by platform administrators.

Built-in Addons​

Butler ships with these AddonDefinitions:

Networking​

AddonDescriptionDefault Version
ciliumeBPF-based CNI with Hubble1.17.0
metallbLoadBalancer for bare metal0.14.9

Storage​

AddonDescriptionDefault Version
longhornDistributed block storage1.7.2

Certificates​

AddonDescriptionDefault Version
cert-managerCertificate management1.16.2

Ingress​

AddonDescriptionDefault Version
traefikIngress controller34.3.0

Monitoring​

AddonDescriptionDefault Version
prometheusMonitoring and alerting25.0.0
victoria-metricsLong-term metrics storage0.25.0

Custom Addons​

Organizations can add custom AddonDefinitions for internal applications.

Creating a Custom Addon​

apiVersion: butler.butlerlabs.dev/v1alpha1
kind: AddonDefinition
metadata:
  name: internal-app
spec:
  displayName: "Internal Application"
  description: "Company internal application"
  category: application
  
  chart:
    repository: https://charts.internal.company.com
    name: internal-app
    defaultVersion: "2.1.0"
    
  defaultValues:
    replicaCount: 2
    
  configurableValues:
    - path: replicaCount
      description: "Number of replicas"
      type: integer
      minimum: 1
      maximum: 10

Private Helm Repositories​

For private repositories, create a Secret:

apiVersion: v1
kind: Secret
metadata:
  name: internal-helm-repo
  namespace: butler-system
type: Opaque
stringData:
  username: helm-user
  password: secret-password

Reference in AddonDefinition:

spec:
  chart:
    repository: https://charts.internal.company.com
    credentialsRef:
      name: internal-helm-repo
      namespace: butler-system

See Also​