bootc-docs/building/secrets.md

Secrets

Managing secrets in bootc systems requires careful consideration of security and operational requirements. This document covers various approaches for handling secrets in Debian bootc images.

Overview

Secrets in bootc systems can be managed through several approaches:

• Build-time secrets: Embedded in the container image (not recommended for production)
• Runtime secrets: Injected at deployment time
• External secret management: Using external systems like HashiCorp Vault, Kubernetes secrets, etc.

Build-time Secrets (Not Recommended)

While it's possible to embed secrets directly in the container image, this is generally not recommended for production use:

# NOT RECOMMENDED for production
RUN echo "secret-password" > /etc/myapp/password

Runtime Secret Injection

systemd Credentials

systemd provides a credentials system for securely passing secrets to services:

# Create a service that uses credentials
COPY myapp.service /usr/lib/systemd/system/

Service file example (/usr/lib/systemd/system/myapp.service):

[Unit]
Description=My Application

[Service]
ExecStart=/usr/bin/myapp
LoadCredential=password:/etc/myapp/password
LoadCredential=api-key:/etc/myapp/api-key

cloud-init Integration

For cloud deployments, use cloud-init to inject secrets:

# cloud-init configuration
#cloud-config
write_files:
  - path: /etc/myapp/config
    content: |
      password: ${PASSWORD}
      api_key: ${API_KEY}
    permissions: '0600'
    owner: root:root

Environment Variables

Use systemd environment files for secrets:

# Create environment file template
COPY myapp.env.template /usr/lib/systemd/system/myapp.env.template

External Secret Management

HashiCorp Vault Integration

Create a service that fetches secrets from Vault:

# Install Vault client
RUN apt update && \
    apt install -y vault && \
    apt clean && \
    rm -rf /var/lib/apt/lists/*

# Create Vault service
COPY vault-fetch.service /usr/lib/systemd/system/
COPY fetch-secrets.sh /usr/local/bin/

Kubernetes Secrets

For Kubernetes deployments, use Kubernetes secrets:

apiVersion: v1
kind: Secret
metadata:
  name: myapp-secrets
type: Opaque
data:
  password: <base64-encoded-password>
  api-key: <base64-encoded-api-key>

Debian-Specific Considerations

Debian Secret Management Tools

Debian provides several tools for secret management:

• gnupg: For encryption/decryption
• openssl: For certificate management
• keyutils: For kernel keyring management

Example Debian Secret Management

FROM debian:bookworm-slim

# Install secret management tools
RUN apt update && \
    apt install -y gnupg openssl keyutils && \
    apt clean && \
    rm -rf /var/lib/apt/lists/*

# Create secret management service
COPY secret-manager.service /usr/lib/systemd/system/
COPY secret-manager.sh /usr/local/bin/

# Set up proper permissions
RUN chmod 700 /usr/local/bin/secret-manager.sh

Debian Keyring Integration

Use Debian's keyring system for managing secrets:

# Add secret to kernel keyring
echo "my-secret" | keyctl padd user myapp-secret @u

# Retrieve secret in application
SECRET=$(keyctl print user:myapp-secret)

AppArmor Considerations

When using AppArmor with secrets:

# Create AppArmor profile for secret access
COPY usr.bin.myapp /etc/apparmor.d/
RUN aa-enforce /etc/apparmor.d/usr.bin.myapp

Best Practices

Security Guidelines

1. Never embed secrets in images: Use external secret management
2. Use least privilege: Only grant access to secrets that are needed
3. Rotate secrets regularly: Implement secret rotation policies
4. Audit secret access: Log all secret access and usage
5. Use encryption: Encrypt secrets at rest and in transit

Operational Guidelines

1. Use templates: Create secret templates that can be filled at runtime
2. Validate secrets: Check that secrets are valid before use
3. Handle failures gracefully: Plan for secret retrieval failures
4. Monitor secret usage: Track secret access patterns

Example Implementation

FROM debian:bookworm-slim

# Install dependencies
RUN apt update && \
    apt install -y curl jq gnupg && \
    apt clean && \
    rm -rf /var/lib/apt/lists/*

# Create secret management system
COPY secret-manager.service /usr/lib/systemd/system/
COPY secret-manager.sh /usr/local/bin/
COPY secret-templates/ /etc/secret-templates/

# Set up proper permissions
RUN chmod 700 /usr/local/bin/secret-manager.sh && \
    chmod 600 /etc/secret-templates/*

# Enable secret manager
RUN systemctl enable secret-manager.service

---

The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.