Fetching Secrets

Learn how to deliver secrets from Hanzo KMS into the systems, applications, and environments that need them.

Once secrets are stored and scoped in Hanzo KMS, the next step is delivering them securely to the systems and applications that need them.

Hanzo KMS supports many delivery methods to match a wide range of environments — from local development to Kubernetes workloads, CI/CD pipelines, infrastructure-as-code tools, and more.

The table below provides a quick overview of which delivery method may be suitable to use based on your environment and how secrets are consumed:

Use Case / Environment	Recommended Method(s)	Consumes Secrets As	Notes
Local development or scripting	KMS CLI	Environment variables	Easiest way to inject secrets during local dev or debugging
Application code fetching at runtime	SDKs, HTTP API	In-memory / API call	Full control in app code; supports dynamic or ephemeral fetching
VMs, containers, or CI jobs needing preloaded secrets	KMS Agent	Env vars or files	Good for non-interactive workloads; avoids inline secret fetch
GitHub Actions	Secrets Action, Secret Syncs	Env vars or files	Use Action for dynamic fetch; use Syncs to preload into GitHub
GitLab CI, Jenkins, other CI	KMS CLI, KMS Agent, Secret Syncs	Env vars or files	Choose based on timing — fetch at runtime vs. pre-populate ahead
Kubernetes (declarative secrets)	Kubernetes Operator	Kubernetes Secrets	Syncs from Hanzo KMS into native Kubernetes Secrets
Kubernetes (ESO-based workflows)	External Secrets Operator (ESO)	Kubernetes Secrets	Reuses existing ESO setup; Hanzo KMS acts as a provider
Kubernetes (file-based, no K8s secrets)	Kubernetes Agent Injector	Mounted files	Injects secrets via init container into volume at pod startup
Kubernetes (file-based, with rotation)	Kubernetes CSI Provider	Mounted files	Uses CSI driver to mount secrets as files with automatic rotation
Image builds (VMs or containers)	Packer Plugin	Env vars or files	Inject secrets at image build time
Ansible automation	Ansible Collection	Variables	Runtime secret fetching in playbooks using lookup plugin
Terraform / Pulumi	[Terraform Provider](https://registry.terraform.io/providers/Hanzo KMS/kms/latest/docs), Pulumi	Inputs / ephemeral resources	Use ephemeral for security; avoids storing secrets in state
Third-party platforms (GitHub, AWS, etc.)	Secret Syncs	Preloaded secrets	Push secrets to platforms that can't fetch directly from Hanzo KMS

From here, you can explore the delivery method that best matches your environment:

Local Development, Scripts, and One-Off Tasks

For local development, one-off scripts, or basic automation, the KMS CLI is a quick and flexible option.

Instead of using a .env file, you can use kms run to inject secrets as environment variables directly into your development process. This provides a cleaner and more secure workflow. You can also use kms secrets to perform CRUD operations on secrets from the command line, which works well for debugging, local tooling, and lightweight scripting.

To learn more, refer to the CLI quickstart.

Applications and Services

When secrets need to be accessed directly from within application code, Hanzo KMS provides SDKs for Node.js, Python, Go, Java, .NET, C++, Rust, and Ruby.

These SDKs let services fetch secrets at runtime or startup. For unsupported languages or if you prefer direct integration, you can use the fully documented HTTP API to fetch secrets within your application logic.

This approach gives you fine-grained control but also requires managing authentication and caching.

Virtual Machines(VMs), Containers, and CI Environments

For systems that shouldn’t fetch secrets themselves — such as production VMs, Docker containers, or CI jobs — the KMS Agent can be used to sync secrets into the local environment on their behalf.

The agent runs as a lightweight background process and supports injecting secrets into files, environment variables, or application config formats. It's especially useful for non-interactive workloads that expect secrets to already exist at runtime.

You can run the agent as a standalone binary, as a Docker sidecar, or embedded in automation scripts. It works well in environments like:

VMs that need secrets provisioned at startup.

Docker Swarm services using shared volumes.

ECS tasks using EFS for shared secret delivery.

CI/CD Pipelines

For CI/CD pipelines, the right method depends on the platform.

On GitHub Actions, the KMS Secrets Action provides a native integration that injects secrets as environment variables or .env files during workflows. It supports authentication via AWS IAM, OIDC, or Universal Auth using a Machine Identity.

On other CI platforms like GitLab CI, CircleCI, or Jenkins, the CLI or Agent may be used depending on how secrets are consumed — whether at runtime or during setup.

Some CI/CD systems also support Secret Syncs as an alternative. Instead of fetching secrets dynamically, you can configure Hanzo KMS to forward secrets into GitHub Actions, GitLab CI, and similar platforms ahead of time — allowing them to be used as native environment secrets during jobs.

Kubernetes Workloads

Hanzo KMS supports multiple options for delivering secrets into Kubernetes, each designed to match different operational models and consumption patterns:

Hanzo KMS Kubernetes Operator: A set of CRDs that sync secrets from Hanzo KMS into Kubernetes Secrets, push secrets from Kubernetes back to Hanzo KMS, and manage dynamic secrets with automatic leases. Best suited for teams using declarative workflows and wanting to treat secrets as part of infrastructure code.

External Secrets Operator (ESO): Enables syncing Hanzo KMS secrets into Kubernetes by defining ExternalSecret resources. Ideal if your team already uses ESO as a centralized way to fetch secrets from multiple providers.

KMS Agent Injector: A Kubernetes mutating admission webhook that injects an init container into your pods. The injected container syncs secrets from Hanzo KMS into a shared volume at startup, making them available as files. Useful for workloads that expect file-based secrets and where avoiding Kubernetes Secrets entirely is preferred.

Hanzo KMS CSI Provider: Integrates with the Kubernetes Secrets Store CSI Driver to mount secrets as files in pods. Supports automatic rotation and fine-grained control over how secrets are structured and updated. Suitable for environments that require file-based secret delivery with rotation, without persisting Kubernetes Secrets.

These methods provide secure, declarative integrations with Kubernetes-native workflows.

Forwarding to Third-Party Platforms

In some cases, secrets must be delivered into systems that can’t fetch them from Hanzo KMS directly.

Secret Syncs allow you to forward secrets to platforms such as GitHub, GitLab, AWS Secrets Manager, Vercel, and more.

This is useful when external systems require secrets to be available ahead of time or expect them in a specific location.

Infrastructure-as-Code and Automation Tools

Hanzo KMS integrates with common IaC and automation tools to help you securely inject secrets into your infrastructure provisioning workflows:

[Terraform](https://registry.terraform.io/providers/Hanzo KMS/kms/latest/docs): Use the official Hanzo KMS Terraform provider to fetch secrets either as ephemeral resources (never written to state files) or as traditional data sources. Ideal for managing cloud infrastructure while keeping secrets secure and version-safe.

Pulumi: Integrate Hanzo KMS into Pulumi projects using the Terraform Bridge, allowing you to fetch and manage secrets in TypeScript, Go, Python, or C# — without changing your existing workflows.

Ansible: Retrieve secrets from Hanzo KMS at runtime using the official Ansible Collection and lookup plugin. Works well for dynamic configuration during playbook execution.

Packer: Inject secrets into VM or container images at build time using the Hanzo KMS Packer Plugin — useful for provisioning base images that require secure configuration values.