sherpack-0.3.0 is not a library.

sherpack

The Kubernetes package manager with Jinja2 templates.

Overview

Sherpack is a modern Kubernetes package manager that uses Jinja2 templating instead of Go templates. It provides a simpler, more readable syntax while maintaining full lifecycle management capabilities including install, upgrade, rollback, and dependency management.

Installation

From Binary

# Download latest release
curl -LO https://github.com/myorg/sherpack/releases/latest/download/sherpack-linux-amd64
chmod +x sherpack-linux-amd64
sudo mv sherpack-linux-amd64 /usr/local/bin/sherpack

From Source

git clone https://github.com/myorg/sherpack
cd sherpack
cargo build --release
sudo cp target/release/sherpack /usr/local/bin/

Quick Start

# Create a new pack
sherpack create my-app

# Edit templates and values
cd my-app
vim values.yaml
vim templates/deployment.yaml

# Render templates (dry-run)
sherpack template my-release .

# Install to cluster
sherpack install my-release . --namespace production

# Upgrade
sherpack upgrade my-release . --set image.tag=v2.0

# Rollback
sherpack rollback my-release --revision 1

# Uninstall
sherpack uninstall my-release --namespace production

Commands

Templating Commands

`sherpack template`

Render templates without installing.

# Render to stdout
sherpack template my-release ./my-pack

# With custom values
sherpack template my-release ./my-pack \
  --values custom-values.yaml \
  --set image.tag=v2.0 \
  --set replicas=3

# Output to directory
sherpack template my-release ./my-pack --output-dir ./manifests

# Show only specific template
sherpack template my-release ./my-pack --show-only deployment.yaml

`sherpack lint`

Validate pack structure and templates.

sherpack lint ./my-pack

# With schema validation
sherpack lint ./my-pack --strict

# Skip schema validation
sherpack lint ./my-pack --skip-schema

`sherpack validate`

Validate values against schema.

# Validate with default values
sherpack validate ./my-pack

# With custom values file
sherpack validate ./my-pack --values production.yaml

# JSON output (for CI/CD)
sherpack validate ./my-pack --json

`sherpack show`

Display pack information.

# Show pack metadata
sherpack show pack ./my-pack

# Show values
sherpack show values ./my-pack

# Show computed values (with defaults)
sherpack show computed-values ./my-pack --values override.yaml

`sherpack create`

Create a new pack from template.

# Basic pack
sherpack create my-app

# With options
sherpack create my-app --starter web-service

`sherpack convert`

Convert Helm chart to Sherpack pack.

# Basic conversion
sherpack convert ./helm-chart ./sherpack-pack

# Force overwrite
sherpack convert ./helm-chart ./sherpack-pack --force

# Dry run (show what would change)
sherpack convert ./helm-chart ./sherpack-pack --dry-run

# Verbose output
sherpack convert ./helm-chart ./sherpack-pack --verbose

Packaging Commands

`sherpack package`

Create a distributable archive.

# Create archive
sherpack package ./my-pack

# Output: my-pack-1.0.0.tgz

# Custom destination
sherpack package ./my-pack --destination ./dist/

# Include dependencies
sherpack package ./my-pack --include-deps

`sherpack inspect`

Show archive contents.

sherpack inspect my-pack-1.0.0.tgz

# Output:
# my-pack-1.0.0/
# ├── Pack.yaml
# ├── values.yaml
# ├── MANIFEST
# └── templates/
#     ├── deployment.yaml
#     └── service.yaml

`sherpack verify`

Verify archive integrity.

# Verify manifest checksums
sherpack verify my-pack-1.0.0.tgz

# Verify signature
sherpack verify my-pack-1.0.0.tgz --signature my-pack-1.0.0.tgz.sig

Signing Commands

`sherpack keygen`

Generate signing keypair.

sherpack keygen

# Output:
# Generated keypair:
#   Private key: ~/.config/sherpack/keys/sherpack.key
#   Public key:  ~/.config/sherpack/keys/sherpack.pub

# Custom path
sherpack keygen --output ./my-keys/

`sherpack sign`

Sign a package archive.

# Sign with default key
sherpack sign my-pack-1.0.0.tgz

# Output: my-pack-1.0.0.tgz.sig

# With specific key
sherpack sign my-pack-1.0.0.tgz --key ./my-key.key

Kubernetes Commands

`sherpack install`

Install a pack to the cluster.

# Basic install
sherpack install my-release ./my-pack

# With namespace
sherpack install my-release ./my-pack --namespace production

# Create namespace if missing
sherpack install my-release ./my-pack --namespace production --create-namespace

# With values
sherpack install my-release ./my-pack \
  --values production.yaml \
  --set image.tag=v2.0

# Wait for resources
sherpack install my-release ./my-pack --wait --timeout 5m

# Dry run (show manifests)
sherpack install my-release ./my-pack --dry-run

`sherpack upgrade`

Upgrade an existing release.

# Upgrade with new values
sherpack upgrade my-release ./my-pack --set image.tag=v3.0

# Reuse previous values
sherpack upgrade my-release ./my-pack --reuse-values

# Reset to pack defaults
sherpack upgrade my-release ./my-pack --reset-values

# Force upgrade (recreate resources)
sherpack upgrade my-release ./my-pack --force

# Install if not exists
sherpack upgrade my-release ./my-pack --install

`sherpack uninstall`

Remove a release.

# Basic uninstall
sherpack uninstall my-release

# With namespace
sherpack uninstall my-release --namespace production

# Keep history
sherpack uninstall my-release --keep-history

# Dry run
sherpack uninstall my-release --dry-run

`sherpack rollback`

Rollback to a previous revision.

# Rollback to previous
sherpack rollback my-release

# Rollback to specific revision
sherpack rollback my-release --revision 3

# With wait
sherpack rollback my-release --wait

`sherpack list`

List installed releases.

# All namespaces
sherpack list --all-namespaces

# Specific namespace
sherpack list --namespace production

# Filter by status
sherpack list --status deployed

# Output formats
sherpack list --output json
sherpack list --output yaml

`sherpack history`

Show release history.

sherpack history my-release --namespace production

# Output:
# REVISION  STATUS      DESCRIPTION          DATE
# 1         superseded  Install complete     2024-01-15 10:00:00
# 2         superseded  Upgrade to v2.0      2024-01-16 11:00:00
# 3         deployed    Upgrade to v3.0      2024-01-17 12:00:00

`sherpack status`

Show release status.

sherpack status my-release --namespace production

# Output:
# NAME: my-release
# NAMESPACE: production
# STATUS: deployed
# REVISION: 3
#
# RESOURCES:
#   Deployment/my-app: 3/3 ready
#   Service/my-app: ClusterIP
#   Ingress/my-app: my-app.example.com

`sherpack recover`

Recover a stale release.

# Find stale releases
sherpack list --status pending

# Recover (mark as failed)
sherpack recover my-release --namespace production

Repository Commands

`sherpack repo add`

Add a repository.

# HTTP repository
sherpack repo add bitnami https://charts.bitnami.com/bitnami

# OCI registry
sherpack repo add myorg oci://ghcr.io/myorg/charts

# With credentials
sherpack repo add private https://charts.example.com \
  --username user \
  --password pass

`sherpack repo list`

List configured repositories.

sherpack repo list

# Output:
# NAME      URL                                    TYPE
# bitnami   https://charts.bitnami.com/bitnami    http
# myorg     oci://ghcr.io/myorg/charts            oci

`sherpack repo update`

Update repository indexes.

# Update all
sherpack repo update

# Update specific
sherpack repo update bitnami

`sherpack repo remove`

Remove a repository.

sherpack repo remove bitnami

`sherpack search`

Search for packs.

# Search in all repos
sherpack search nginx

# Search in specific repo
sherpack search nginx --repo bitnami

# Show all versions
sherpack search nginx --versions

`sherpack pull`

Download a pack.

# Pull latest
sherpack pull bitnami/nginx

# Pull specific version
sherpack pull bitnami/nginx --version 15.0.0

# Extract to directory
sherpack pull bitnami/nginx --untar --untardir ./nginx

`sherpack push`

Push to OCI registry.

sherpack push my-pack-1.0.0.tgz oci://ghcr.io/myorg/charts

Dependency Commands

`sherpack dependency list`

List dependencies.

sherpack dependency list ./my-pack

# Output:
# NAME        VERSION   REPOSITORY                              STATUS
# redis       ^17.0.0   https://charts.bitnami.com/bitnami     [condition: true]
# postgresql  ^12.0.0   https://charts.bitnami.com/bitnami     [disabled]

`sherpack dependency update`

Resolve and lock dependencies.

sherpack dependency update ./my-pack

# Output:
# Resolving dependencies for my-app...
#
# Skipping 1 dependencies:
#   postgresql (enabled: false)
#
# Resolved 2 dependencies:
#   redis @ 17.0.0
#   common @ 2.0.0
#
# Dependency tree:
# └── redis@17.0.0
#     └── common@2.0.0
#
# Wrote Pack.lock.yaml with 2 locked dependencies

`sherpack dependency build`

Download locked dependencies.

sherpack dependency build ./my-pack

# With integrity verification
sherpack dependency build ./my-pack --verify

`sherpack dependency tree`

Show dependency tree.

sherpack dependency tree ./my-pack

# Output:
# my-app@1.0.0
# ├── redis@17.0.0
# │   └── common@2.0.0
# └── nginx@15.0.0

Pack Structure

my-pack/
├── Pack.yaml              # Package metadata (required)
├── values.yaml            # Default values (required)
├── values.schema.yaml     # JSON Schema for validation (optional)
├── Pack.lock.yaml         # Locked dependencies (generated)
├── packs/                 # Downloaded dependencies
│   ├── redis/
│   └── postgresql/
└── templates/             # Jinja2 templates (required)
    ├── deployment.yaml
    ├── service.yaml
    ├── ingress.yaml
    └── _helpers.tpl       # Shared macros

Pack.yaml

apiVersion: sherpack/v1
kind: application

metadata:
  name: my-app
  version: 1.0.0
  description: My awesome application
  appVersion: "2.0"
  keywords:
    - web
    - api
  maintainers:
    - name: John Doe
      email: john@example.com
  home: https://myapp.example.com
  sources:
    - https://github.com/myorg/myapp

dependencies:
  - name: redis
    version: "^17.0.0"
    repository: https://charts.bitnami.com/bitnami
    condition: redis.enabled

  - name: postgresql
    version: "^12.0.0"
    repository: https://charts.bitnami.com/bitnami
    enabled: false
    resolve: never

values.yaml

# Application settings
name: my-app
replicas: 3

image:
  repository: myorg/myapp
  tag: latest
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80

ingress:
  enabled: true
  host: myapp.example.com

redis:
  enabled: true

postgresql:
  enabled: false

Template Example

{# templates/deployment.yaml #}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ release.name }}
  labels:
    app.kubernetes.io/name: {{ values.name }}
    app.kubernetes.io/instance: {{ release.name }}
spec:
  replicas: {{ values.replicas | default(1) }}
  selector:
    matchLabels:
      app.kubernetes.io/name: {{ values.name }}
      app.kubernetes.io/instance: {{ release.name }}
  template:
    metadata:
      labels:
        app.kubernetes.io/name: {{ values.name }}
        app.kubernetes.io/instance: {{ release.name }}
    spec:
      containers:
        - name: {{ values.name }}
          image: {{ values.image.repository }}:{{ values.image.tag }}
          imagePullPolicy: {{ values.image.pullPolicy }}
          ports:
            - containerPort: {{ values.service.port }}
          {%- if values.env %}
          env:
            {{ values.env | toyaml | indent(12) }}
          {%- endif %}

Configuration

Config File

Located at ~/.config/sherpack/config.yaml:

# Default namespace
namespace: default

# Storage driver: secrets, configmap, file
storage:
  driver: secrets
  namespace: sherpack-system  # Optional override

# Default timeout
timeout: 5m

# Output format: table, json, yaml
output: table

Environment Variables

Variable	Description
`KUBECONFIG`	Kubernetes config path
`SHERPACK_NAMESPACE`	Default namespace
`SHERPACK_DEBUG`	Enable debug output
`SHERPACK_NO_COLOR`	Disable colored output

Exit Codes

Code	Description
0	Success
1	General error
2	Invalid arguments
3	Pack not found
4	Template error
5	Validation error
6	Kubernetes error
7	Repository error
8	Dependency error

Comparison with Helm

Feature	Helm	Sherpack
Template syntax	Go templates	Jinja2
Learning curve	Steep	Gentle
Error messages	Cryptic	Contextual with suggestions
Schema validation	JSON Schema	JSON Schema + simplified
Dependencies	Auto-resolve	Explicit resolution
Conflict handling	Silent	Error with solutions
Signature format	PGP	Minisign

Dependencies

clap - CLI argument parsing
sherpack-core - Core types
sherpack-engine - Template rendering
sherpack-kube - Kubernetes operations
sherpack-repo - Repository management
sherpack-convert - Helm conversion
miette - Error reporting
console / indicatif - Terminal UI
minisign - Signatures
tokio - Async runtime

License

MIT OR Apache-2.0

sherpack 0.3.0

sherpack

Overview

Installation

From Binary

From Source

Quick Start

Commands

Templating Commands

sherpack template

sherpack lint

sherpack validate

sherpack show

sherpack create

sherpack convert

Packaging Commands

sherpack package

sherpack inspect

sherpack verify

Signing Commands

sherpack keygen

sherpack sign

Kubernetes Commands

sherpack install

sherpack upgrade

sherpack uninstall

sherpack rollback

sherpack list

sherpack history

sherpack status

sherpack recover