From 7aeff0839ae3983ff70dbbd154c8b3f59a910533 Mon Sep 17 00:00:00 2001 From: Ferruh <63190600+ferruhcihan@users.noreply.github.com> Date: Fri, 1 Nov 2024 16:52:40 +0100 Subject: [PATCH] feat: age docs (#78) --- docs/for-ops/cli/deploying.md | 4 +- docs/for-ops/how-to/manage-age.md | 142 ++++++++++++++++++++++++++ docs/for-ops/how-to/overview.md | 2 + docs/get-started/installation/sops.md | 18 +++- sidebar-docs.js | 3 +- 5 files changed, 163 insertions(+), 6 deletions(-) create mode 100644 docs/for-ops/how-to/manage-age.md diff --git a/docs/for-ops/cli/deploying.md b/docs/for-ops/cli/deploying.md index 8977b2e9a..78768afb4 100644 --- a/docs/for-ops/cli/deploying.md +++ b/docs/for-ops/cli/deploying.md @@ -31,7 +31,7 @@ The minimum required input is found in the [chart values](https://github.com/red ::: -## 3. Configure credentials from a KMS (optional) +## 3. Configure credentials from a KMS/Age (optional) :::note No encryption needed? @@ -39,7 +39,7 @@ If you don't need encryption straight away please continue to the next step ::: -APL will encrypt any `secrets.*.yaml` files with [sops](https://github.com/mozilla/sops), but only if it finds `sops:` configuration details. In order to have access to the KMS credentials to encrypt/decrypt, a `.secrets` file needs to exist and have those credentials. Please `copy .secrets.sample .secrets` and fill it in with the KMS credentials. +APL will encrypt any `secrets.*.yaml` files with [sops](https://github.com/mozilla/sops), but only if it finds `sops:` configuration details. In order to have access to the KMS/Age credentials to encrypt/decrypt, a `.secrets` file needs to exist and have those credentials. Please `copy .secrets.sample .secrets` and fill it in with the KMS credentials. Then you can run `otomi bootstrap`, which will result in the encryption and decryption of the secrets files. diff --git a/docs/for-ops/how-to/manage-age.md b/docs/for-ops/how-to/manage-age.md new file mode 100644 index 000000000..8470635d2 --- /dev/null +++ b/docs/for-ops/how-to/manage-age.md @@ -0,0 +1,142 @@ +--- +slug: manage-age +title: Manage Age for Development, Security, and Recovery +sidebar_label: Manage Age +--- + +:::info +This documentation was written for SOPS that is using Age Encryption. Please check the SOPS page for other [KMS](/docs/get-started/installation/sops#use-sops-with-an-external-key-management-service-kms) providers. +::: + +## Prerequisites + +- Version >= `v3.1` + +## Local development setup + +### Steps + +1. Create a values folder: + +```bash +mkdir -p values-folder ~/workspace +``` + +2. Clone the values repo from Gitea: + +:::info +In case your TLS certificate is not trusted, set GIT_SSL_NO_VERIFY to clone the git repository: +```bash +export GIT_SSL_NO_VERIFY=true +``` +::: + +```bash +git clone gitea./otomi/values.git ~/workspace/values-folder +``` + +3. Copy SOPS_AGE_KEY secret: + +- Copy the `SOPS_AGE_KEY` secret, which is the private key for Age, from the cluster. It is located in the `otomi-pipelines` namespace in the `otomi-sops-secrets`, or in the `otomi` namespace in the `otomi-api` secret. + +- Create a `.secrets` file in the values-folder at the root level and insert the `SOPS_AGE_KEY` into it. + +:::info +Don't forget to use = instead of : +```bash +SOPS_AGE_KEY=AGE-SECRET-KEY-1XXX +``` +::: + +4. Export ENV_DIR: + +Export `ENV_DIR` in the core repository to use `otomi-cli`. + +```bash +export ENV_DIR=~/workspace/values-folder +``` + +5. Use `otomi-cli`: + +The local development environment is now ready to use [otomi-cli](/docs/for-ops/cli/installation) commands. + +## Age keys rotation + +:::info +Please follow the local development setup steps above and be prepared to use `otomi-cli`. +::: + +### Steps + +1. Decrypt files with the old key and credentials: + +```bash +docker run -it -v $ENV_DIR:/home/app/stack/env linode/apl-core binzx/otomi decrypt +``` + +:::info +The decrypted files have the `.dec` extension. +::: + +2. Change the following files + +- In the `env/settings.yaml` file update the `kms.sops.age.publicKey` property. + +- In the `env/secrets.settings.yaml.dec` file update the `kms.sops.age.privateKey` property. + +- In the `.secrets` file change the `SOPS_AGE_KEY` credential. + +3. Change the modification date of each `.dec` file + +This way we enforce encryption of all secret files. + +```bash +cd ~/workspace/values-folder && find . -name '*.dec' -type f -exec touch {} \; +``` + +4. Encrypt the `*.dec` files: + +```bash +docker run -it -v $ENV_DIR:/home/app/stack/env linode/apl-core binzx/otomi encrypt +``` + +5. Update the secrets in the cluster. + +Update the following secrets in the cluster for `SOPS_AGE_KEY`: + +- Update the `otomi-sops-secrets` secret in the `otomi-pipelines` namespace. + +- Update the `otomi-api` secret in the `otomi` namespace. + +:::info +These secrets and related applications are managed by Argo CD, so don’t forget to update the secret values via Argo CD. +It’s also possible to use a tool such as Kubernetes Lens to update Argo CD applications. +Alternatively, `otomi apply` can be used to update the secrets in the cluster before the next `git push`. +::: + +6. Push the values to the `otomi-values` repo in Gitea: + +```bash +cd ~/workspace/values-folder && git push +``` + +## Age disaster recovery + +:::info +For disaster recovery, users need the `SOPS_AGE_KEY`, which is the private key for Age. +Please make sure to store the `SOPS_AGE_KEY` in a secure place. +This key can be obtained from the `otomi-sops-secrets` secret in the `otomi-pipelines` namespace or from the `otomi-api` secret in the `otomi` namespace. +::: + +To configure Age public and private keys, add or update the following `kms` section in the values.yaml file when installing the Application Platform. + +```yaml +kms: + sops: + provider: age + age: + publicKey: + privateKey: +``` + +Make sure to replace `age-public-key` and `age-private-key` values with your actual (existing) Age public and private keys. diff --git a/docs/for-ops/how-to/overview.md b/docs/for-ops/how-to/overview.md index 5d1866760..696ef0868 100644 --- a/docs/for-ops/how-to/overview.md +++ b/docs/for-ops/how-to/overview.md @@ -20,3 +20,5 @@ sidebar_label: Overview ### [Clone the Platform configuration](clone-apl.md). +### [Manage Age for Development, Security, and Recovery](manage-age.md). + diff --git a/docs/get-started/installation/sops.md b/docs/get-started/installation/sops.md index 45dd5b783..e33325ea8 100644 --- a/docs/get-started/installation/sops.md +++ b/docs/get-started/installation/sops.md @@ -6,6 +6,21 @@ sidebar_label: SOPS If you would like sensitive information in the `values` repository to be encrypted, you will have to use [sops](https://github.com/mozilla/sops). +## Use SOPS with AGE + +[AGE](https://github.com/FiloSottile/age) is a simple, modern, and secure encryption tool (and Go library) with small explicit keys, no config options, and UNIX-style composability. + +To install with SOPS/Age, use the following values: + +```yaml +kms: + sops: + provider: "age" +# age: +# publicKey: '' +# privateKey: '' +``` + ## Use SOPS with an external Key Management Service (KMS) Find quickstart documentation below on how to setup KMS access per supported provider: @@ -40,6 +55,3 @@ kms: # token: '' ``` -## Use SOPS with AGE (comming soon!) - -[AGE](https://github.com/FiloSottile/age) is a simple, modern, and secure encryption tool (and Go library) with small explicit keys, no config options, and UNIX-style composability. \ No newline at end of file diff --git a/sidebar-docs.js b/sidebar-docs.js index e813321e1..0c18b884f 100644 --- a/sidebar-docs.js +++ b/sidebar-docs.js @@ -111,8 +111,9 @@ module.exports = { "for-ops/how-to/ingress-classes", "for-ops/how-to/use-team-admin", "for-ops/how-to/core-only", - "for-ops/how-to/clone-apl", "for-ops/how-to/backups", + "for-ops/how-to/clone-apl", + "for-ops/how-to/manage-age", ], }, {