kms bootstrap

Automate the initial setup of a new Hanzo KMS instance for headless deployment and infrastructure-as-code workflows

kms bootstrap --domain=<domain> --email=<email> --password=<password> --organization=<organization>

Description

The kms bootstrap command is used when deploying Hanzo KMS in automated environments where manual UI setup is not feasible. It's ideal for:

Containerized deployments in Kubernetes or Docker environments

Infrastructure-as-code pipelines with Terraform or similar tools

Continuous deployment workflows

DevOps automation scenarios

The command initializes a fresh Hanzo KMS instance by creating an admin user, organization, and instance admin machine identity, enabling subsequent programmatic configuration without human intervention.

This command creates an instance admin machine identity with the highest level of privileges. The returned token should be treated with the utmost security, similar to a root credential. Unauthorized access to this token could compromise your entire Hanzo KMS instance.

Flags

The URL of your Hanzo KMS instance. This can be set using the INFISICAL_API_URL environment variable.

# Example
kms bootstrap --domain=https://your-kms-instance.com

This flag is required.

Email address for the admin user account that will be created. This can be set using the INFISICAL_ADMIN_EMAIL environment variable.

# Example
kms bootstrap --email=admin@example.com

This flag is required.

Password for the admin user account. This can be set using the INFISICAL_ADMIN_PASSWORD environment variable.

# Example
kms bootstrap --password=your-secure-password

This flag is required.

Name of the organization that will be created within the instance. This can be set using the INFISICAL_ADMIN_ORGANIZATION environment variable.

# Example
kms bootstrap --organization=your-org-name

This flag is required.

Whether to continue without error if the instance has already been bootstrapped. Useful for idempotent automation scripts.

# Example
kms bootstrap --ignore-if-bootstrapped

This flag is optional and defaults to false.

The type of output format for the bootstrap command. Supports k8-secret for Kubernetes secret integration. This flag is optional and defaults to "".

# Kubernetes secret output
kms bootstrap --output=k8-secret --k8-secret-template='{"data":{"token":"{{.Identity.Credentials.Token}}"}}' --k8-secret-name=kms-bootstrap --k8-secret-namespace=default

When using k8-secret, the command will create or update a Kubernetes secret directly in your cluster. Note that this option requires the command to be executed from within a Kubernetes pod with appropriate service account permissions.

The template to use for rendering the Kubernetes secret data/stringData section. Required when using --output=k8-secret. The template uses Go template syntax and has access to the bootstrap response data.

# Example template that stores the token
kms bootstrap --k8-secret-template='{"data":{"token":"{{.Identity.Credentials.Token}}"}}'

# Example template with multiple fields
kms bootstrap --k8-secret-template='{"stringData":{"token":"{{.Identity.Credentials.Token}}","org-id":"{{.Organization.ID}}","user-email":"{{.User.Email}}"}}'

Available template functions:

encodeBase64: Base64 encode a string

Available data fields:

.Identity.Credentials.Token: The machine identity token
.Identity.ID: The identity ID
.Identity.Name: The identity name
.Organization.ID: The organization ID
.Organization.Name: The organization name
.Organization.Slug: The organization slug
.User.Email: The admin user email
.User.ID: The admin user ID
.User.FirstName: The admin user first name
.User.LastName: The admin user last name

This flag is required when using k8-secret output.

The name of the Kubernetes secret to create or update. Required when using --output=k8-secret.

# Example
kms bootstrap --k8-secret-name=kms-bootstrap-credentials

This flag is required when using k8-secret output.

The namespace where the Kubernetes secret should be created or updated. Required when using --output=k8-secret.

# Example
kms bootstrap --k8-secret-namespace=kms-system

This flag is required when using k8-secret output.

Response

JSON Output (Default)

The command returns a JSON response with details about the created user, organization, and machine identity:

{
  "identity": {
    "credentials": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eUlkIjoiZGIyMjQ3OTItZWQxOC00Mjc3LTlkYWUtNTdlNzUyMzE1ODU0IiwiaWRlbnRpdHlBY2Nlc3NUb2tlbklkIjoiZmVkZmZmMGEtYmU3Yy00NjViLWEwZWEtZjM5OTNjMTg4OGRlIiwiYXV0aFRva2VuVHlwZSI6ImlkZW50aXR5QWNjZXNzVG9rZW4iLCJpYXQiOjE3NDIzMjI0ODl9.mqcZZqIFqER1e9ubrQXp8FbzGYi8nqqZwfMvz09g-8Y"
    },
    "id": "db224792-ed18-4277-9dae-57e752315854",
    "name": "Instance Admin Identity"
  },
  "message": "Successfully bootstrapped instance",
  "organization": {
    "id": "b56bece0-42f5-4262-b25e-be7bf5f84957",
    "name": "dog",
    "slug": "dog-v-e5l"
  },
  "user": {
    "email": "admin@example.com",
    "firstName": "Admin",
    "id": "a418f355-c8da-453c-bbc8-6c07208eeb3c",
    "lastName": "User",
    "superAdmin": true,
    "username": "admin@example.com"
  }
}

Kubernetes Secret Output

When using --output=k8-secret, the command creates or updates a Kubernetes secret in your cluster and logs the operation result. This is particularly useful for automated bootstrapping scenarios such as Kubernetes Jobs, GitOps workflows, or when you need to immediately store the admin credentials for use by other applications in your cluster.

Kubernetes Integration

Prerequisites for k8-secret Output

When running with --output=k8-secret, the command must be executed from within a Kubernetes pod with proper service account permissions. The command automatically:

Reads the service account token from /var/run/secrets/kubernetes.io/serviceaccount/token

Reads the CA certificate from /var/run/secrets/kubernetes.io/serviceaccount/ca.crt

Gets the Kubernetes API server URL from environment variables (KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT_HTTPS)

Required RBAC Permissions

Your service account needs the following permissions:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: kms-bootstrap
rules:
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "create", "update"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: kms-bootstrap
subjects:
  - kind: ServiceAccount
    name: your-service-account
roleRef:
  kind: Role
  name: kms-bootstrap
  apiGroup: rbac.authorization.k8s.io

Usage with Automation

For automation purposes, you can extract just the machine identity token from the response:

kms bootstrap --domain=https://your-kms-instance.com --email=admin@example.com --password=your-secure-password --organization=your-org-name | jq ".identity.credentials.token"

This extracts only the token, which can be captured in a variable or piped to other commands.

Example: Capture Token in a Variable

TOKEN=$(kms bootstrap --domain=https://your-kms-instance.com --email=admin@example.com --password=your-secure-password --organization=your-org-name | jq -r ".identity.credentials.token")

# Now use the token for further automation
echo "Token has been captured and can be used for authentication"

Notes

The bootstrap process can only be performed once on a fresh Hanzo KMS instance

All core flags (domain, email, password, organization) are required for the bootstrap process to complete successfully

Security controls prevent privilege escalation: instance admin identities cannot be managed by non-instance admin users and identities

The generated admin user account can be used to log in via the UI if needed

When using k8-secret output, the command must run within a Kubernetes pod with proper service account permissions

The --ignore-if-bootstrapped flag is useful for making bootstrap scripts idempotent

On this page