Skip to content

Quick Start

This guide will get you up and running with Genifest in just a few minutes using the included guestbook example.

Prerequisites

  • Genifest installed (Installation Guide)
  • Basic familiarity with Kubernetes YAML files
  • Text editor of your choice

Your First Genifest Project

Step 1: Explore the Example

Genifest comes with a complete guestbook example. Let's explore it:

# Navigate to the example
cd examples/guestbook

# Look at the project structure
tree

You'll see a structure like this:

examples/guestbook/
├── genifest.yaml          # Root configuration
├── files/                 # Template files
│   └── guestbook/
│       └── app.yaml
├── manifests/            # Kubernetes manifests
│   ├── guestbook/
│   │   ├── genifest.yaml
│   │   ├── backend-deployment.yaml
│   │   ├── frontend-deployment.yaml
│   │   └── ...
│   └── postgres/
│       ├── deployment.yaml
│       ├── service.yaml
│       └── ...
└── scripts/              # Custom scripts

Step 2: Examine the Configuration

Look at the root configuration:

cat genifest.yaml

metadata:
  cloudHome: "."
  paths:
    - path: "scripts"
      scripts: true
      depth: 0
    - path: "manifests"
      files: true
      depth: 1
    - path: "files"
      files: true
      depth: 1

functions:
  - name: "get-replicas"
    params:
      - name: "environment"
        required: true
    valueFrom:
      default:
        value: "2"

This defines:

  • Metadata: Directory paths with their capabilities and depths
  • Functions: Reusable value generators

Now consider the configuration in manifests/guestbook/genifest.yaml:

cat manifests/guestbook/genifest.yaml

files:
  include:
    - backend-deployment.yaml
    - backend-service.yaml
    - configmap.yaml
    - frontend-deployment.yaml
    - frontend-service.yaml
    - ingress.yaml
    - secret.yaml

changes:
   - tag: "production"
     fileSelector: "*-deployment.yaml"
     keySelector: ".spec.replicas"
     valueFrom:
        call:
           function: "get-replicas"
           args:
              - name: "environment"
                valueFrom:
                   default:
                      value: "production"

# ... plus more changes

This defines:

  • Files: The files that Genifest is allowed to work with in this directory.
  • Changes: A set of change orders to apply to the YAML files.

Step 3: Validate the Configuration

Before applying changes, validate everything is correct:

genifest validate

You can also try different output modes:

# Plain text output (good for logs)
genifest validate --output=plain

# Markdown output (good for documentation)
genifest validate --output=markdown

Expected output: 

✅ Configuration validation successful
  • 3 function definitions validated
  • 13 files found and accessible
  • 3 change definitions validated

Step 4: Explore Available Commands

# Show all available tags
genifest tags

# Display the merged configuration (see below)
genfiest config

# Show help for any command
genifest run --help

Step 5: Apply Changes

Now apply the changes to see Genifest in action:

genifest run

You'll see detailed output like: 

🔍 Configuration loaded:
  • 3 total change definition(s) found
  • 3 change definition(s) will be processed (all changes)
  • 13 file(s) to examine

  ✏️  manifests/guestbook/backend-deployment.yaml -> document[0] -> .spec.replicas: 1 → 2
  ✓  manifests/guestbook/frontend-deployment.yaml -> document[0] -> .spec.replicas: 2 (no change)
📝 Updated file: manifests/guestbook/backend-deployment.yaml (1 changes)

✅ Successfully completed processing:
  • 2 change application(s) processed
  • 1 change application(s) resulted in actual modifications
  • 1 file(s) were updated

Step 6: Try Groups-Based Selection

The guestbook example includes predefined groups. Try using different groups:

# Apply only production-tagged changes
genifest run production

# View available tags
genifest tags

# Try plain output (useful for CI/CD)
genifest run production --output=plain

This demonstrates the groups-based tag selection system.

Understanding What Happened

Configuration Discovery

Genifest discovered configurations in this order:

  1. Root config (genifest.yaml) - Defined metadata and functions
  2. Subdirectory configs - Found manifests/guestbook/genifest.yaml with specific changes
  3. Synthetic configs - Created automatic configs for directories without genifest.yaml

Run genifest config to see the merged result.

Value Generation

The changes used the get-replicas function to set replica counts:

changes:
  - tag: "production"
    fileSelector: "*-deployment.yaml"
    keySelector: ".spec.replicas"
    valueFrom:
      call:
        function: "get-replicas"
        args:
          - name: "environment"
            valueFrom:
              default:
                value: "production"

Next Steps: Create Your Own Project

1. Create a Basic Project

mkdir my-k8s-project
cd my-k8s-project

# Create the root configuration
cat > genifest.yaml << EOF
metadata:
  cloudHome: "."
  paths:
    - path: "k8s"
      files: true
      depth: 0

functions:
  - name: "get-replicas"
    params:
      - name: "env"
        required: true
    valueFrom:
      default:
        value: "2"

changes:
  - fileSelector: "*-deployment.yaml"
    keySelector: ".spec.replicas"
    valueFrom:
      call:
        function: "get-replicas"
        args:
          - name: "env"
            valueFrom:
              default:
                value: "dev"
EOF

2. Add Kubernetes Manifests

mkdir -p k8s
cat > k8s/app-deployment.yaml << EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 1  # This will be updated by genifest
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: app
        image: nginx:latest
EOF

3. Test Your Configuration

# Validate
genifest validate

# See what would change
genifest run

# Check the result
cat k8s/app-deployment.yaml

Common Patterns

Environment-Specific Values

functions:
  - name: "get-image-tag"
    params:
      - name: "environment"
        required: true
    valueFrom:
      template:
        string: "myapp:${environment}-latest"
        variables:
          - name: "environment"
            valueFrom:
              argRef:
                name: "environment"

changes:
  - tag: "staging"
    fileSelector: "*-deployment.yaml"
    keySelector: ".spec.template.spec.containers[0].image"
    valueFrom:
      call:
        function: "get-image-tag"
        args:
          - name: "environment"
            valueFrom:
              default:
                value: "staging"

Multiple Environments

Use groups to target specific environments:

# Development (assuming you have a 'dev' group defined)
genifest run dev

# Staging
genifest run staging

# Production
genifest run production

# Add additional tag expressions to any group
genifest run --tag "!secret-*" production

Troubleshooting

Common Issues

  1. "Configuration file not found" 

    # Make sure you're in the directory with genifest.yaml
ls genifest.yaml
    Or run the command with the directory you want to use as root: 
    genifest run myproject/deployments

  2. "No changes applied" 

    # Check if your file selectors match your files
genifest config  # Shows merged config
genifest validate  # Validates everything

  3. "Function not found" 

    # Verify function definitions in config
genifest config | grep -A5 functions

What's Next?

Next: Configuration Guide →