kubricate@0.22.0

Release Notes

Type-Safe Secrets, New Provider TLS, SSH Auth and CustomType, and EnvConnector Improved

TL;DR

🚀 Exciting Announcement — Kubricate v0.22 Released!

We’re thrilled to announce the release of Kubricate v0.22, delivering major improvements in type safety, security, and developer experience across multiple packages:

• kubricate@0.22.0 — Enhanced CLI stability and important security fixes.
• core@0.22.0 — Added stronger type-safe interfaces for providers using key-based fields (e.g., BasicAuth, TLS, SshAuth).
• plugin-env@0.22.0 — ⚠️ Breaking: EnvConnector no longer applies the default KUBRICATE_SECRET_ prefix to environment variables.
• plugin-kubernetes@0.22.0 — Introduced new type-safe providers: TlsSecretProvider, SshAuthSecretProvider, and CustomTypeSecretProvider for user-defined secret types.
• kubernetes-model@0.1.2 — Improved stability and consistency for Kubernetes resource models.

🧠 Summary

Kubricate v0.22 establishes a stronger foundation for type-safe, secure, and extensible secret management, improving developer experience and aligning with modern Kubernetes best practices.
It also introduces a key breaking change to decouple environment variable handling from secret-centric design.

This release includes:

• Type-safe environment key injection for all providers
• Three new specialized providers: TLS and SSH Auth
• A new flexible provider: CustomTypeSecretProvider for user-defined Secret types
• Breaking change: EnvConnector no longer applies a default prefix
• Security improvements: dry-run censorship and automatic temp-file cleanup

✨ What’s Included

1️⃣ Type-Safe Environment Key Injection (#150)

All Secret providers now declare valid keys for env injection, enabling IDE autocompletion and compile-time safety.

Benefits

• Prevents key typos at build time
• Enhances developer productivity with autocomplete
• Ensures consistent validation across providers

Example

// IDE autocomplete + type-checked key
secrets().inject('env', { key: 'username' });

2️⃣ TlsSecretProvider — kubernetes.io/tls (#147)

Generates TLS Secrets with canonical keys (tls.crt, tls.key), ideal for cert-manager, Ingress, or certificate-based workloads.

new TlsSecretProvider({
  name: 'ingress-tls',
  namespace: 'production',
});

3️⃣ SshAuthSecretProvider — kubernetes.io/ssh-auth (#146)

Handles SSH-based authentication secrets (ssh-privatekey, optional known_hosts), designed for private Git, CI/CD, and deployment keys.

new SshAuthSecretProvider({
  name: 'deploy-key',
  namespace: 'ci',
});

4️⃣ CustomTypeSecretProvider — User-Defined Secret Types (#158)

A flexible new provider that supports any Kubernetes Secret type, extending Kubricate beyond standard Opaque secrets.

Key Features

• Accepts any secretType (e.g. vendor.com/custom)
• Accepts dynamic key/value data (Record<string, string>)
• Supports env and envFrom strategies
• Auto base64-encodes values
• Optional validation via allowedKeys and keyPolicy

Example

new CustomTypeSecretProvider({
  name: 'vendor-api-token',
  namespace: 'production',
  secretType: 'vendor.com/custom',
  allowedKeys: ['api_key', 'endpoint'],
});

⚠️ Breaking: EnvConnector No Longer Applies a Default Prefix (#173)

EnvConnector no longer auto-prefixes environment variables with KUBRICATE_SECRET_.
This decouples environment handling from secret management, allowing more flexible use for configuration and metadata.
If your project relied on the implicit prefix, explicitly set it via new EnvConnector({ prefix: 'KUBRICATE_SECRET_' }).

🔐 Security & Maintenance Fixes

fix(kubricate): Censor Secret Values in Dry-Run Mode (#171)

Fixed a security issue where secret values appeared in dry-run logs. All secret data is now censored with ***.

fix(kubricate): Ensure Temporary File Cleanup After Applying Secrets (#172)

Fixed a security vulnerability where temporary secret files were left in /tmp. Files are now automatically deleted to prevent unauthorized access.

🧭 Migration Notes (v0.21 → v0.22)

🔸 EnvConnector Default Prefix Removed

Impact: Breaking change
Action Required:
If your environment variable setup depends on the implicit KUBRICATE_SECRET_ prefix, you must now define it explicitly.

Before

new EnvConnector();

After

new EnvConnector({
  prefix: 'KUBRICATE_SECRET_',
});

If you previously referenced environment variables such as KUBRICATE_SECRET_DB_PASSWORD, they will now appear as DB_PASSWORD unless you reintroduce the prefix manually.

✅ Final Summary

Kubricate v0.22 delivers a cleaner, more secure, and type-aware model for Kubernetes Secret and environment handling.
This version concludes the pre-v1 modernization phase, ensuring a stable, maintainable foundation for future releases.

What's Changed

• type: Type-Safe Strategy Env Key Support for Secret Injection by @mildronize in #150
• feat: Add SshAuthSecretProvider for SSH authentication secrets by @mildronize in #149
• feat: Implement TlsSecretProvider for type-safe TLS certificate management by @mildronize in #153
• test: add test cases by @mildronize in #157
• chore: decouple stacks package from kubricate framework by @mildronize in #167
• refactor(kubricate): Extract domain logic for testability by @mildronize in #168
• feat(plugin-kubernetes): Add CustomTypeSecretProvider for user-defined Kubernetes Secret types by @mildronize in #169
• docs: setup standard and project structure to support working with AI by @mildronize in #170
• fix(plugin-env)!: Remove default prefix env of EnvConnector by @kitimark in #173
• fix(kubricate): ensure temporary file cleanup after applying secrets by @mildronize in #172
• fix(kubricate): censor secret values in dry-run mode for security by @mildronize in #171
• Release Kubricate v0.22 — Type-Safe Secrets, New Provider TLS, SSH Auth and CustomType, and EnvConnector Improved by @mildronize in #175
• Version Packages by @github-actions[bot] in #176

Full Changelog: https://github.com/thaitype/kubricate/compare/kubricate@0.21.1...kubricate@0.22.0

---

Minor Changes

• 765020b: introduces type-safe secret management, new specialized providers (TLS, SSH, CustomType), and a breaking change removing the default EnvConnector prefix — delivering stronger security, cleaner extensibility, and a more consistent developer experience.

Patch Changes

• Updated dependencies [765020b]
  • @kubricate/core@0.22.0

@kubricate/stacks@0.22.0

Minor Changes

• 765020b: introduces type-safe secret management, new specialized providers (TLS, SSH, CustomType), and a breaking change removing the default EnvConnector prefix — delivering stronger security, cleaner extensibility, and a more consistent developer experience.

Patch Changes

• Updated dependencies [765020b]
  • @kubricate/core@0.22.0
  • @kubricate/kubernetes-models@0.1.2

@kubricate/plugin-kubernetes@0.22.0

Minor Changes

• 765020b: introduces type-safe secret management, new specialized providers (TLS, SSH, CustomType), and a breaking change removing the default EnvConnector prefix — delivering stronger security, cleaner extensibility, and a more consistent developer experience.

Patch Changes

• Updated dependencies [765020b]
  • @kubricate/core@0.22.0

@kubricate/plugin-env@0.22.0

Minor Changes

• 765020b: introduces type-safe secret management, new specialized providers (TLS, SSH, CustomType), and a breaking change removing the default EnvConnector prefix — delivering stronger security, cleaner extensibility, and a more consistent developer experience.

Patch Changes

• Updated dependencies [765020b]
  • @kubricate/core@0.22.0

@kubricate/kubernetes-models@0.1.2

Patch Changes

• 765020b: introduces type-safe secret management, new specialized providers (TLS, SSH, CustomType), and a breaking change removing the default EnvConnector prefix — delivering stronger security, cleaner extensibility, and a more consistent developer experience.

@kubricate/core@0.22.0

Minor Changes

• 765020b: introduces type-safe secret management, new specialized providers (TLS, SSH, CustomType), and a breaking change removing the default EnvConnector prefix — delivering stronger security, cleaner extensibility, and a more consistent developer experience.

kubricate@0.21.1

Patch Changes

• b2e0450: fix: Show help when no command, thanks for @kitimark

kubricate@0.21.0

New Feature: Kubernetes Basic Auth Secret Support

We're excited to announce support for Kubernetes kubernetes.io/basic-auth secrets through the new BasicAuthSecretProvider!

What's New

BasicAuthSecretProvider enables type-safe management of HTTP Basic Authentication credentials in your Kubernetes deployments with two injection patterns:

1. Individual Key Injection - Inject username and password as separate environment variables
2. Bulk Injection - Inject all credentials at once with optional prefix

Quick Start

Installation

BasicAuthSecretProvider is included in @kubricate/plugin-kubernetes:

npm install @kubricate/plugin-kubernetes

Basic Usage

import { BasicAuthSecretProvider } from '@kubricate/plugin-kubernetes';

const secretManager = new SecretManager()
  .addProvider('BasicAuthProvider', new BasicAuthSecretProvider({
    name: 'api-credentials',
    namespace: 'default',
  }))
  .addSecret({ name: 'API_CREDENTIALS', provider: 'BasicAuthProvider' });

Injection Patterns

Pattern 1: Individual Keys

Perfect when you need custom environment variable names:

c.secrets('API_CREDENTIALS')
  .forName('API_USERNAME')
  .inject('env', { key: 'username' });

c.secrets('API_CREDENTIALS')
  .forName('API_PASSWORD')
  .inject('env', { key: 'password' });

Results in:

env:
  - name: API_USERNAME
    valueFrom:
      secretKeyRef:
        name: api-credentials
        key: username

Pattern 2: Bulk Injection with Prefix

Inject all credentials at once:

c.secrets('DB_CREDENTIALS')
  .inject('envFrom', { prefix: 'DB_' });

Results in:

envFrom:
  - prefix: DB_
    secretRef:
      name: db-credentials

Environment variables: DB_username, DB_password

Pattern 3: Bulk Injection without Prefix

c.secrets('API_CREDENTIALS')
  .inject('envFrom');

Environment variables: username, password

Key Features

• ✅ Type-Safe - Full TypeScript support with proper type inference
• ✅ Validated - Runtime validation ensures username and password are present
• ✅ Flexible - Choose between individual or bulk injection
• ✅ Standards-Compliant - Generates proper kubernetes.io/basic-auth Secret type
• ✅ Fail-Fast - Clear error messages with actionable guidance

Important Notes

One Provider = One Secret

Each BasicAuthSecretProvider instance creates one Kubernetes Secret resource. When managing multiple credential sets, create separate provider instances:

// ✅ Correct - separate providers
.addProvider('ApiProvider', new BasicAuthSecretProvider({
  name: 'api-credentials'
}))
.addProvider('DbProvider', new BasicAuthSecretProvider({
  name: 'db-credentials'
}))
.addSecret({ name: 'API_CREDENTIALS', provider: 'ApiProvider' })
.addSecret({ name: 'DB_CREDENTIALS', provider: 'DbProvider' })

// ❌ Incorrect - reusing same provider
.addProvider('BasicAuth', new BasicAuthSecretProvider({
  name: 'credentials'
}))
.addSecret({ name: 'API_CREDENTIALS' })
.addSecret({ name: 'DB_CREDENTIALS' })  // Error: conflict!

Secret Format

Secrets must be JSON objects with username and password keys:

{
  "username": "your-username",
  "password": "your-password"
}

Use Cases

Perfect for:

• 🔌 REST API authentication
• 🗄️ Database connections (MySQL, PostgreSQL)
• 🔐 Internal service authentication
• 📡 HTTP proxy credentials
• 🌐 Legacy system integration

Type System Improvements

This release also includes enhanced type inference for injection strategies. TypeScript now correctly narrows strategy options based on the kind parameter:

// TypeScript knows 'key' is available for 'env' strategy
.inject('env', { key: 'username' })  // ✅ Type-safe

// TypeScript knows 'prefix' is available for 'envFrom' strategy
.inject('envFrom', { prefix: 'DB_' })  // ✅ Type-safe

Examples

Check out the complete working example:

• examples/with-basic-auth-secret

Demonstrates all three injection patterns with detailed explanations.

Migration Guide

From No Basic Auth Support → BasicAuthSecretProvider

This is a new feature. No migration needed for existing code.

Breaking Changes

None. This release is fully backward compatible.

Validation & Security

This feature has undergone comprehensive security review:

• ✅ 35 unit tests
• ✅ Multiple validation layers prevent data corruption
• ✅ Fail-fast error handling with clear messages
• ✅ Production-ready with high confidence

Known Limitations

• Fixed schema (username + password only) - use OpaqueSecretProvider for arbitrary keys
• One provider instance per secret resource
• Cannot mix env and envFrom strategies for the same secret

Community

Found a bug? Have a question?

• 🐛 Report issues on GitHub
• 📖 Read the docs
• 💬 Discussions

Minor Changes

• 31074cc: feat: Add BasicAuthSecretProvider for Kubernetes basic-auth secrets
• 0d42e09: feat: Add BasicAuthSecretProvider for Kubernetes basic-auth secrets

Patch Changes

• Updated dependencies [31074cc]
• Updated dependencies [0d42e09]
  • @kubricate/core@0.21.0

@kubricate/stacks@0.21.0

Minor Changes

• 31074cc: feat: Add BasicAuthSecretProvider for Kubernetes basic-auth secrets

Patch Changes

• Updated dependencies [31074cc]
• Updated dependencies [0d42e09]
  • @kubricate/core@0.21.0
  • kubricate@0.21.0

@kubricate/plugin-kubernetes@0.21.0

Minor Changes

• 31074cc: feat: Add BasicAuthSecretProvider for Kubernetes basic-auth secrets
• 0d42e09: feat: Add BasicAuthSecretProvider for Kubernetes basic-auth secrets

Patch Changes

• Updated dependencies [31074cc]
• Updated dependencies [0d42e09]
  • @kubricate/core@0.21.0