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:

```dockerfile
# 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:

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

Service file example (`/usr/lib/systemd/system/myapp.service`):
```ini
[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:

```yaml
# 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:

```dockerfile
# 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:

```dockerfile
# 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:

```yaml
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

```dockerfile
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:

```bash
# 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:

```dockerfile
# 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

```dockerfile
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.