147 lines
4.3 KiB
Markdown
147 lines
4.3 KiB
Markdown
# Secrets Management Refactoring
|
|
|
|
## Summary of Changes
|
|
|
|
This refactoring moves secrets management from the usda-vision flake to athenix (the parent infrastructure flake), following the principle that secrets should be managed centrally at the infrastructure level, not in application flakes.
|
|
|
|
## What Changed
|
|
|
|
### 1. Removed ragenix from usda-vision flake
|
|
|
|
**Before:** usda-vision/flake.nix included ragenix as an input and provided tools for local secret management.
|
|
|
|
**After:** usda-vision/flake.nix is now purely for package definitions. Ragenix is removed from inputs.
|
|
|
|
**Files modified:**
|
|
- [usda-vision/flake.nix](usda-vision/flake.nix)
|
|
|
|
### 2. Updated default.nix to accept secret file paths
|
|
|
|
**Before:** The module used hardcoded paths and copied .env.example files.
|
|
|
|
**After:** The module accepts `envFile` and `azureEnvFile` parameters pointing to ragenix-managed secrets from athenix.
|
|
|
|
**Files modified:**
|
|
- [default.nix](default.nix)
|
|
|
|
**New parameters:**
|
|
```nix
|
|
{ usda-vision-packages ? null
|
|
, envFile ? null # NEW: Path to ragenix-managed .env
|
|
, azureEnvFile ? null # NEW: Path to ragenix-managed .env.azure
|
|
, ...
|
|
}
|
|
```
|
|
|
|
### 3. Removed hardcoded .env path transformations
|
|
|
|
**Before:** package.nix used sed to rewrite env_file paths in docker-compose.yml
|
|
|
|
**After:** Paths are not rewritten; secrets are copied to the working directory by the systemd service
|
|
|
|
**Files modified:**
|
|
- [usda-vision/package.nix](usda-vision/package.nix)
|
|
|
|
### 4. Updated integration documentation
|
|
|
|
**Files modified:**
|
|
- [ATHENIX_INTEGRATION.md](ATHENIX_INTEGRATION.md)
|
|
|
|
## How to Use in Athenix
|
|
|
|
### Step 1: Create secrets in athenix
|
|
|
|
```bash
|
|
cd ~/athenix
|
|
mkdir -p secrets/usda-vision
|
|
|
|
# Edit the main environment file
|
|
ragenix -e secrets/usda-vision/env.age
|
|
|
|
# Edit the Azure OAuth configuration
|
|
ragenix -e secrets/usda-vision/azure-env.age
|
|
```
|
|
|
|
### Step 2: Configure age secrets in athenix
|
|
|
|
```nix
|
|
# In athenix flake or NixOS configuration
|
|
{
|
|
age.secrets.usda-vision-env = {
|
|
file = ./secrets/usda-vision/env.age;
|
|
mode = "0644";
|
|
owner = "root";
|
|
group = "root";
|
|
};
|
|
|
|
age.secrets.usda-vision-azure-env = {
|
|
file = ./secrets/usda-vision/azure-env.age;
|
|
mode = "0644";
|
|
owner = "root";
|
|
group = "root";
|
|
};
|
|
}
|
|
```
|
|
|
|
### Step 3: Pass secret paths to usda-dash-config module
|
|
|
|
```nix
|
|
# In inventory.nix or wherever you import usda-dash-config
|
|
{ config, usda-vision-packages, ... }:
|
|
|
|
{
|
|
imports = [
|
|
(import /path/to/usda-dash-config/default.nix {
|
|
inherit usda-vision-packages;
|
|
envFile = config.age.secrets.usda-vision-env.path;
|
|
azureEnvFile = config.age.secrets.usda-vision-azure-env.path;
|
|
})
|
|
];
|
|
}
|
|
```
|
|
|
|
## Benefits
|
|
|
|
1. **Centralized secret management**: All infrastructure secrets are managed in athenix using ragenix
|
|
2. **No hardcoded transformations**: The derivation doesn't modify env file paths
|
|
3. **Flexible deployment**: Different secrets can be passed for dev/staging/prod environments
|
|
4. **Pure builds**: No need for `--impure` flag since secrets aren't built into the derivation
|
|
5. **Security**: Secrets are encrypted at rest in athenix and only decrypted on the target system
|
|
6. **Clean separation of concerns**:
|
|
- usda-vision flake: Package definitions only
|
|
- athenix: Infrastructure and secrets management
|
|
- usda-dash-config: NixOS module configuration
|
|
|
|
## Migration for Existing Deployments
|
|
|
|
If you have existing deployments using the old approach:
|
|
|
|
1. Create the secret files in athenix as shown above
|
|
2. Copy the content from your existing `.env` files into the ragenix-managed secrets
|
|
3. Update your inventory.nix to pass the secret file paths
|
|
4. Rebuild with `nixos-rebuild switch`
|
|
5. Verify the secrets are correctly copied to `/var/lib/usda-vision/.env`
|
|
|
|
## Fallback Behavior
|
|
|
|
If `envFile` is not provided (e.g., for local testing), the module will:
|
|
1. Print a warning
|
|
2. Copy `.env.example` to `/var/lib/usda-vision/.env`
|
|
3. Remind you to configure secrets in athenix
|
|
|
|
This allows the module to work standalone for development, but production deployments should always provide proper secrets.
|
|
|
|
## Local Development
|
|
|
|
For local development in the usda-vision directory, you can still use:
|
|
|
|
```bash
|
|
cd usda-vision
|
|
nix develop
|
|
cp .env.example .env
|
|
# Edit .env with your local configuration
|
|
docker-compose up
|
|
```
|
|
|
|
The flake.nix still provides a development shell with all necessary tools, but ragenix should be installed from athenix if needed for secret management.
|