yadunut/clan-core
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

documentation: improve secrets page

Browse Source
This commit is contained in:
a-kenji
2024-04-14 13:15:26 +02:00
parent bc7c3ad782
commit 4442ba777a
1 changed files with 19 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
docs/site/getting-started/secrets.md
View File

@@ -12,6 +12,7 @@ This documentation will guide you through managing secrets with the Clan CLI
To get started, you'll need to create **Your master keypair**. To get started, you'll need to create **Your master keypair**.
!!! info
Don't worry — if you've already made one before, this step won't change or overwrite it. Don't worry — if you've already made one before, this step won't change or overwrite it.
```bash ```bash
@@ -20,17 +21,19 @@ clan secrets key generate
**Output**: **Output**:
```bash ```{.console, .no-copy}
Public key: age1wkth7uhpkl555g40t8hjsysr20drq286netu8zptw50lmqz7j95sw2t3l7 Public key: age1wkth7uhpkl555g40t8hjsysr20drq286netu8zptw50lmqz7j95sw2t3l7
Generated age private key at '/home/joerg/.config/sops/age/keys.txt' for your user. Please back it up on a secure location or you will lose access to your secrets. Generated age private key at '/home/joerg/.config/sops/age/keys.txt' for your user. Please back it up on a secure location or you will lose access to your secrets.
Also add your age public key to the repository with 'clan secrets users add YOUR_USER age1wkth7uhpkl555g40t8hjsysr20drq286netu8zptw50lmqz7j95sw2t3l7' (replace YOUR_USER with your actual username) Also add your age public key to the repository with 'clan secrets users add YOUR_USER age1wkth7uhpkl555g40t8hjsysr20drq286netu8zptw50lmqz7j95sw2t3l7' (replace YOUR_USER with your actual username)
``` ```
⚠️ **Important**: Make sure to keep a safe backup of the private key you've just created. !!! warning
Make sure to keep a safe backup of the private key you've just created.
If it's lost, you won't be able to get to your secrets anymore because they all need the master key to be unlocked. If it's lost, you won't be able to get to your secrets anymore because they all need the master key to be unlocked.
> Note: It's safe to add any secrets created by the clan CLI and placed in your repository to version control systems like `git`. !!! note
It's safe to add any secrets created by the clan CLI and placed in your repository to version control systems like `git`.
### Add Your Public Key ### Add Your Public Key
@@ -38,11 +41,12 @@ If it's lost, you won't be able to get to your secrets anymore because they all
clan secrets users add <your_username> <your_public_key> clan secrets users add <your_username> <your_public_key>
``` ```
⚠️ **Important**: Choose the username same username as on your Setup/Source Machine that you use to control the deployment with. !!! note
Choose the same username as on your Setup/Source Machine that you use to control the deployment with.
Once run this will create the following files: Once run this will create the following files:
```bash ```{.console, .no-copy}
sops/ sops/
└── users/ └── users/
└── <your_username>/ └── <your_username>/
@@ -92,7 +96,8 @@ $ clan secrets set mysecret
Paste your secret: Paste your secret:
``` ```
> Note: As you type - your secret won't be displayed. Press Enter to save the secret. !!! note
As you type your secret won't be displayed. Press Enter to save the secret.
## 5. Retrieving Stored Secrets ## 5. Retrieving Stored Secrets
@@ -140,7 +145,7 @@ Here's how to get started:
Secrets in the repository follow this structure: Secrets in the repository follow this structure:
```bash ```{.console, .no-copy}
sops/ sops/
├── secrets/ ├── secrets/
│ └── <secret_name>/ │ └── <secret_name>/
@@ -157,9 +162,8 @@ By default, secrets are encrypted with your key to ensure readability.
A NixOS machine will automatically import all secrets that are encrypted for the A NixOS machine will automatically import all secrets that are encrypted for the
current machine. At runtime it will use the host key to decrypt all secrets into current machine. At runtime it will use the host key to decrypt all secrets into
a in-memory, non-persistent filesystem using an in-memory, non-persistent filesystem using [sops-nix](https://github.com/Mic92/sops-nix).
[sops-nix](https://github.com/Mic92/sops-nix). In your nixos configuration you In your nixos configuration you can get a path to secrets like this `config.sops.secrets.<name>.path`. For example:
can get a path to secrets like this `config.sops.secrets.<name>.path`. Example:
```nix ```nix
{ config, ...}: { { config, ...}: {
@@ -177,17 +181,16 @@ examples.
### Migration: Importing existing sops-based keys / sops-nix ### Migration: Importing existing sops-based keys / sops-nix
`clan secrets` stores each secrets in a single file, whereas [sops](https://github.com/Mic92/sops-nix) `clan secrets` stores each secret in a single file, whereas [sops](https://github.com/Mic92/sops-nix) commonly allows to put all secrets in a yaml or json document.
commonly allows to put all secrets in a yaml or json documents.
If you already happened to use sops-nix, you can migrate by using the `clan secrets import-sops` command by importing these documents: If you already happened to use sops-nix, you can migrate by using the `clan secrets import-sops` command by importing these files:
```bash ```bash
% clan secrets import-sops --prefix matchbox- --group admins --machine matchbox nixos/matchbox/secrets/secrets.yaml % clan secrets import-sops --prefix matchbox- --group admins --machine matchbox nixos/matchbox/secrets/secrets.yaml
``` ```
This will create secrets for each secret found in `nixos/matchbox/secrets/secrets.yaml` in a ./sops folder of your repository. This will create secrets for each secret found in `nixos/matchbox/secrets/secrets.yaml` in a ./sops folder of your repository.
Each member of the group `admins` will be able Each member of the group `admins` in this case will be able to decrypt the secrets with their respective key.
Since our clan secret module will auto-import secrets that are encrypted for a particular nixos machine, Since our clan secret module will auto-import secrets that are encrypted for a particular nixos machine,
you can now remove `sops.secrets.<secrets> = { };` unless you need to specify more options for the secret like owner/group of the secret file. you can now remove `sops.secrets.<secrets> = { };` unless you need to specify more options for the secret like owner/group of the secret file.