Skip to main content

Customizing Stacks

Learn how to customize KubeZero stacks for your specific requirements.

Overview​

KubeZero stacks are composable, allowing you to customize them to meet your specific needs.

Stack Structure​

A KubeZero stack consists of:

  • Base configuration: Core platform components
  • Modules: Optional feature additions
  • Customizations: Environment-specific settings
  • Overrides: Local modifications

Creating Custom Stacks​

Basic Stack Customization​

Start with a base stack and add customizations:

# stacks/my-custom-stack/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base/k8s-essentials
  - ../../modules/monitoring
  - ../../modules/security

patches:
  - target:
      kind: Deployment
      name: prometheus
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 3

Environment-Specific Stacks​

Create stacks for different environments:

# stacks/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../base-stack

patches:
  - target:
      kind: Ingress
    patch: |-
      - op: replace
        path: /metadata/annotations/cert-manager.io~1cluster-issuer
        value: letsencrypt-prod

Module Customization​

Enabling/Disabling Features​

Control which features are included:

# Custom module selection
modules:
  monitoring:
    enabled: true
    prometheus:
      retention: 30d
    grafana:
      persistence: true
  
  logging:
    enabled: true
    elasticsearch:
      replicas: 3
  
  service-mesh:
    enabled: false  # Disable if not needed

Custom Module Configuration​

Override module defaults:

# modules/monitoring/values.yaml
prometheus:
  server:
    retention: 15d
    resources:
      requests:
        memory: 512Mi
        cpu: 500m
      limits:
        memory: 2Gi
        cpu: 2000m

grafana:
  adminPassword: "${GRAFANA_ADMIN_PASSWORD}"
  persistence:
    enabled: true
    size: 10Gi

Configuration Management​

Using ConfigMaps​

Store configuration in ConfigMaps:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  database_url: "postgresql://db:5432/myapp"
  redis_url: "redis://redis:6379"
  log_level: "info"

Using Secrets​

Manage sensitive data with secrets:

apiVersion: v1
kind: Secret
metadata:
  name: app-secrets
type: Opaque
stringData:
  database_password: "${DATABASE_PASSWORD}"
  api_key: "${API_KEY}"

Advanced Customizations​

Custom Resource Definitions​

Add custom resources:

# Add CRDs to your stack
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: myresources.example.com
spec:
  group: example.com
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
          status:
            type: object

Custom Operators​

Include custom operators:

# Deploy custom operator
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-operator
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-operator
  template:
    metadata:
      labels:
        app: my-operator
    spec:
      containers:
      - name: operator
        image: my-org/my-operator:v1.0.0

Validation and Testing​

Stack Validation​

Validate your custom stack:

# Validate stack configuration
kubezero validate stack --path ./stacks/my-stack

# Dry run deployment
kubezero deploy --dry-run --stack my-stack

Testing Framework​

Test your customizations:

# Run stack tests
kubezero test stack --path ./stacks/my-stack

# Integration tests
kubezero test integration --suite custom-stack

Best Practices​

Stack Organization​

Organize your stacks effectively:

stacks/
├── base/                 # Base configurations
├── environments/         # Environment-specific
│   ├── development/
│   ├── staging/
│   └── production/
├── applications/         # Application stacks
└── custom/              # Custom components

Version Control​

Track stack changes:

  1. Git repository: Store stacks in Git
  2. Branching: Use branches for changes
  3. Tags: Tag stable versions
  4. Documentation: Document changes

Configuration Management​

Follow configuration best practices:

  1. Separation: Separate config from code
  2. Encryption: Encrypt sensitive data
  3. Validation: Validate configurations
  4. Testing: Test before deployment

Migration Strategy​

When updating stacks:

  1. Backup: Backup current configuration
  2. Test: Test in non-production environment
  3. Gradual rollout: Deploy incrementally
  4. Monitor: Monitor during deployment
  5. Rollback: Have rollback plan ready

For detailed customization examples, see the customization reference.