aegis

README

Status of This Software

This project is a work in progress (WIP) and has yet to be ready for production consumption. Use it at your own risk.

A Video Is Worth a Lot of Thousands of Words

Here is a short video introduction to Aegis.

There is also aegis.z2h.dev, the project’s website.

About Aegis

Aegis is a Kubernetes-native, lightweight, secrets management solution that keeps your secrets secret.

With Aegis, you can rest assured that your sensitive data is always secure and protected.

Aegis is perfect for securely storing arbitrary configuration information at a central location and securely dispatching it to workloads.

Aegis ensures that your secrets are only accessible to authorized workloads, helping you safeguard your business and protect against data breaches.

If you haven’t watched this six-minute introductory video yet, now might be a good time 🙂.

System Requirements

Aegis has been recently tested with the following Kubernetes version:

Client Version: v1.26.0
Kustomize Version: v4.5.7
Server Version: v1.25.3

Although not explicitly tested, any recent Kubernetes installation will likely work just fine.

As in any secrets management solution, your compute and memory requirements will depend on several factors, such as:

• The number of workloads in the cluster
• The number of secrets Safe (Aegis’ Secrets Store) has to manage (see architecture details)
• The amount of workloads interacting with Safe (see architecture details)
• Sidecar poll frequency (see architecture details)
• etc.

We recommend you benchmark with a realistic production-like cluster and allocate your resources accordingly.

Installation

You need a Kubernetes cluster and sufficient admin rights on that cluster to install Aegis.

As of now, the only installation option is to clone the project and install it using make as follows:

# Clone the repo and cd into it:
git clone https://github.com/zerotohero-dev/aegis.git

# Clean former deployment, if any:
make clean

# Install SPIRE, Safe, and Sentinel:
make install

# Optionally, install a demo workload to test the system:
make demo

To verify installation check out the aegis-system namespace:

kubectl get deployment -n aegis-system

# Output:
#
# NAME             READY   UP-TO-DATE   AVAILABLE
# aegis-safe       1/1     1            1
# aegis-sentinel   1/1     1            1

Registering a Secret to a Workload

You can use Sentinel to add a secret to a workload:

# Change `aegis-sentinel-aabbccdd11223344` with the name of the Sentinel
# pod.
kubectl exec -it aegis-sentinel-aabbccdd11223344 -n aegis-system \
-- /bin/sentinel \ 
-w demo-workload # Name of the workload \
-s '{"username":"root@admin-db", \
"password":"KeepYourSecrets!."}' # The secret to bind to the workload.

Sentinel is the only entry point that an operator can register secrets to the system.

How Do I Get the Root Token? Where Do I Store It?

Unlike some other secret vaults, you do not need an admin token to operate Aegis 🙂.

Benefits of this approach is: It helps the Ops team #sleepmore, since everything is automated, and you won’t have to manually unlock Aegis upon a system crash, for example.

However, there’s no free lunch, and as the operator of a production system, your homework is to secure access to Sentinel.

Aegis leverages Kubernetes security primitives and modern cryptography to secure access to secrets. And Sentinel is the only system part that has direct write access to the secrets store. Therefore, once you secure your access toSentinel with proper RBAC and policies, you secure your access to your secrets.

We believe that this approach is Kubernetes-native, convenient, simpler, and delightfully secure (as opposed to being “annoyingly secure”).

Design Decisions

Keeping Aegis, Kubernetes-native, slim, secure, and boringly-easy to install and operate are the pillars of the project.

Check out the Design Decisions document for a deeper discussion about how we maintain the architectural balance in Aegis.

Where Not To Use Aegis

Aegis is not a Database, nor is it a distributed caching layer. Of course, you may tweak it to act like one if you try hard enough, yet, that is generally not a good use of the tool.

Aegis is suitable for storing secrets and dispatching them; however, it is a terrible idea to use it as a centralized database to store everything but the kitchen sink.

Use Aegis to store service keys, database credentials, access tokens, etc.

Technologies Used

Without these technologies, implementing Aegis would have been a very hard, time-consuming, and error-prone endeavor.

• SPIFFE and SPIRE for establishing an Identity Control Plane.
• Netshoot for creating the “development” version of Sentinel.
• Mozilla Sops (in design phase) to enable integration with cloud secrets stores, such as AWS KMS, GCP KMS, Azure KeyVault, and even HashiCorp Vault.
• Age Encryption (in design phase) to enable out-of-memory encrypted backup of the secrets store for disaster recovery.

Architecture Details

Check out this Architecture document for detailed information about Aegis’s project folder structure, system design, sequence diagrams, workflows, and internal operating principles.

One More Thing… How Do I Pronounce “Aegis”?

“Aegis” is a word of Greek origin and is pronounced EE-jiss.

Here’s a YouTube pronunciation guide.

Aegis has two definitions:

1. (Classical Mythology) The shield or breastplate of Zeus or Athena, bearing at its center the head of the Gorgon.
2. Protection; support.

Here’s an image of an aegis (shield) as depicted in Greek mythology:

What’s Coming Up Next?

You can see the project’s progress in this Aegis MDP board.

The board outlines what are the current outstanding work items, and what is currently being worked on.

There is also this Aegis v1.0.0 board that contains longer-term goals that we’ll start once the MDP board is mostly done.

There is also a text file that is a more free-form list of issues. I sometimes jot things down there before creating more detailed GitHub issues.

Code Of Conduct

Be a nice citizen.

Contributing

It’s a bit chaotic around here, yet if you want to lend a hand, here are the contributing guidelines.

Maintainers

As of now, I, Volkan Özçelik, am the sole maintainer of Aegis.

Please send your feedback, suggestions, recommendations, and comments to me@volkan.io. I’d love to have them.