Skip to content

Aegis Policy Controller

A Kubernetes admission controller that enforces and validates policies for your Kubernetes cluster through integration with the Aegis AI server.

Overview

The Aegis Policy Controller is a dynamic policy enforcement system that provides a validation webhook for Kubernetes resources. It integrates with the Aegis AI server to evaluate policies and make decisions about resource admission and modification.

Prerequisites

  • A running Kubernetes cluster (v1.16+ recommended)
  • Access to the Aegis AI server
  • TLS certificates for secure webhook communication (provided as Kubernetes secrets)
  • kubectl access to your cluster

Deployment Guide

You can download all required deployment manifests directly from this documentation site:

Note: These files are provided as samples. Update the secrets and configuration as needed for your environment.

1. Prepare TLS Certificates and Secrets

Place the required certificates and tokens as Kubernetes secrets:

  • CA certificate in a secret named aegis-ca-config (key: cacert)
  • Server TLS certificate and key in a secret named aegis-tls-secret (keys: tls.crt, tls.key)
  • API auth token in a secret named aegis-policy-auth (key: token)

See the sample manifest: secret.yaml

2. Apply Manifests

Deploy the controller and webhook configuration:

kubectl apply -f assets/policy-controller/secret.yaml
kubectl apply -f assets/policy-controller/deployment.yaml
kubectl apply -f assets/policy-controller/service.yaml
kubectl apply -f assets/policy-controller/manifests.yaml

Configuration

The Aegis Policy Controller can be configured via command-line flags or environment variables.

Command-Line Flags

Flag Description Default
--config, -c Config file $HOME/.pegasys/policy.yml
--port, -p Controller server port 5443
--ca-cert-dir Directory containing CA certificates /etc/pegasys/tls/cacert
--tls-cert-dir Directory containing TLS certificate and key /etc/pegasys/tls
--server Aegis API server URL http://localhost:8000
--auth-token Aegis API server auth token (bearer) -
--policy-name Aegis API server policy name kubernetes
--v Log level (0–5) 1

Environment Variables

All flags can also be set via environment variables prefixed with AEGIS_POLICY_. For example, AEGIS_POLICY_CONFIG corresponds to --config.

Health and Metrics

The controller exposes health probe endpoints for liveness/readiness checks and a Prometheus-format metrics endpoint.

Usage

Once deployed, the controller automatically intercepts and processes Kubernetes API requests based on the configured webhook rules. It will:

  1. Validate resources against defined policies
  2. Provide detailed feedback for policy violations
  3. Include warnings for potential issues

Example

To test policy enforcement using the sample NGINX resource:

kubectl apply -f deploy/examples/nginx.yml

Updating or Removing

Update

Edit and reapply the deployment manifest:

kubectl apply -f deploy/webhook/deployment.yaml

Remove

kubectl delete -f deploy/webhook/manifests.yaml
kubectl delete -f deploy/webhook/deployment.yaml
kubectl delete -f deploy/webhook/service.yaml
kubectl delete -f deploy/webhook/secret.yaml

Troubleshooting

  • Ensure the webhook service is reachable from the Kubernetes API server.
  • Verify certificate validity and CA bundle configuration.
  • Check controller logs for errors or policy violations.
  • Confirm all referenced secrets are present and mounted correctly.

Alternative Installation: Helm

You can also install the Aegis Policy Controller using Helm and the provided install.sh script. All required deployment scripts are available as a zip file for download:

Download and extract this zip file before proceeding with the installation steps below.

Prerequisites

  • Helm installed and configured
  • OpenSSL installed and available in your PATH
  • Access to your Kubernetes API server (URL and API token)
  • Bash shell (Linux or macOS)

Installation Guide

1. Download and Extract the Deployment Scripts

Download the aegis.zip file and save it to your local machine. Then extract its contents to a folder of your choice:

# download via browser
unzip aegis.zip -d aegis-deploy
cd aegis-deploy

Replace <URL_TO_DOCS> with the base URL of this documentation site if downloading via command line, or simply download and unzip manually.

2. Run the Installation Script

In the extracted folder, execute the installation script:

./install.sh

You will be prompted to enter: - API server URL: The URL of your Kubernetes API server - API token: A valid API token for authentication

3. What the Script Does

The script will:

  • Generate TLS certificates using OpenSSL and store them in the tls/ directory
  • Install or upgrade the Aegis Helm chart, passing the generated certificates and API credentials as values

4. Verify the Installation

Check that the Aegis Policy Controller is running:

kubectl get pods -n aegis

You should see pods for the Aegis Policy Controller.

Uninstallation

To remove the Aegis Policy Controller installed via Helm:

helm uninstall aegis

Troubleshooting

  • Ensure you have sufficient permissions to install Helm charts and create resources in your cluster
  • If you encounter certificate errors, verify that OpenSSL is installed and accessible
  • For API authentication issues, confirm your API server URL and token are correct

References