Your First Policy
Introduction
To simplify the process of creating policies in Aperture, the built-in blueprint system can be utilized. The Aperture repository contains several blueprints that can generate policies, and Grafana dashboards. These blueprints serve as starting points for creating new policies, or can be used as-is by providing the required parameters or customizations. The use-cases section showcases practical examples of blueprints in action.
To manage blueprints and generate policies, use the aperturectl CLI.
For advanced users interested in designing new policies, explore the example circuit created in the detecting overload use-case. This example serves as a valuable reference for understanding the process of creating custom policies in Aperture.
Listing Available Blueprints
The following command can be used to list available blueprints:
aperturectl blueprints list --version=v2.7.0
Which will output the following:
auto-scaling/pod-auto-scaler
load-ramping/base
load-scheduling/average-latency
load-scheduling/postgresql
load-scheduling/promql
quota-scheduling/base
rate-limiting/base
Customizing Blueprints
Blueprints use a configuration file to provide required fields and to customize the generated policy and dashboard files.
For example, to generate a policies/rate-limiting
policy, you can first
generate a values.yaml
file using the following command:
aperturectl blueprints values --name=policies/rate-limiting --version=v2.7.0 --output-file=values.yaml
You can then edit the values.yaml
to provide the required fields
(__REQUIRED_FIELD__
placeholder) as follows:
- Final/Edited Values
- Placeholder Values
# yaml-language-server: $schema=../../../../../blueprints/rate-limiting/base/gen/definitions.json
# Generated values file for rate-limiting/base blueprint
# Documentation/Reference for objects and parameters can be found at:
# https://docs.fluxninja.com/reference/blueprints/rate-limiting
policy:
# Name of the policy.
# Type: string
# Required: True
policy_name: rate-limiting
# List of additional circuit components.
# Type: []aperture.spec.v1.Component
components: []
# Additional resources.
# Type: aperture.spec.v1.Resources
resources:
flow_control:
classifiers: []
rate_limiter:
# Bucket capacity.
# Type: float64
# Required: True
bucket_capacity: 40
# Leak amount.
# Type: float64
# Required: True
fill_amount: 2
# Flow selectors to match requests against
# Type: []aperture.spec.v1.Selector
selectors:
- agent_group: default
service: service1-demo-app.demoapp.svc.cluster.local
control_point: ingress
# Parameters.
# Type: aperture.spec.v1.RateLimiterParameters
parameters:
# Flow label to use for rate limiting.
# Type: string
# Required: True
label_key: http.request.header.user_type
# Leak interval e.g. "1s".
# Type: string
# Required: True
interval: 1s
You can then run the following command to generate the blueprint:
# Generated values file for rate-limiting/base blueprint
# Documentation/Reference for objects and parameters can be found at:
# https://docs.fluxninja.com/reference/blueprints/rate-limiting/base
policy:
# List of additional circuit components.
# Type: []aperture.spec.v1.Component
components: []
# Name of the policy.
# Type: string
# Required: True
policy_name: __REQUIRED_FIELD__
# Additional resources.
# Type: aperture.spec.v1.Resources
resources:
flow_control:
classifiers: []
rate_limiter:
# Bucket capacity.
# Type: float64
# Required: True
bucket_capacity: __REQUIRED_FIELD__
# Fill amount.
# Type: float64
# Required: True
fill_amount: __REQUIRED_FIELD__
# Parameters.
# Type: aperture.spec.v1.RateLimiterParameters
# Required: True
parameters:
interval: __REQUIRED_FIELD__
label_key: ""
# Flow selectors to match requests against
# Type: []aperture.spec.v1.Selector
# Required: True
selectors:
- control_point: __REQUIRED_FIELD__
service: __REQUIRED_FIELD__
dashboard:
# Additional filters to pass to each query to Grafana datasource.
# Type: map[string]string
extra_filters: {}
# Refresh interval for dashboard panels.
# Type: string
refresh_interval: "15s"
# From time of dashboard.
# Type: string
time_from: "now-15m"
# To time of dashboard.
# Type: string
time_to: "now"
# Name of the main dashboard.
# Type: string
title: "Aperture Rate Limiter"
datasource:
# Datasource filter regex.
# Type: string
filter_regex: ""
# Datasource name.
# Type: string
name: "$datasource"
Generating Policies and Dashboards
Once the values.yaml
file is ready, you can generate the blueprint using the
following command:
aperturectl blueprints generate --name=policies/rate-limiting --values-file=values.yaml --output-dir=policy-gen --version=v2.7.0
The following directory structure will be generated:
policy-gen
├── dashboards
│ └── rate-limiting.json
├── graphs
│ ├── rate-limiting.dot
│ └── rate-limiting.mmd
└── policies
│ ├── rate-limiting-cr.yaml
│ └── rate-limiting.yaml
Applying Policies
The generated policies can be applied using aperturectl
or kubectl
.
- aperturectl
- kubectl
You can pass the --apply
flag with the aperturectl
to directly apply the
generated policies on a Kubernetes cluster in the namespace where the Aperture
Controller is installed.
aperturectl blueprints generate --name=policies/rate-limiting --values-file=values.yaml --apply --version=v2.7.0
It uses the default configuration for Kubernetes cluster under ~/.kube/config
.
You can pass the --kube-config
flag to pass any other path.
aperturectl blueprints generate --name=policies/rate-limiting --values-file=values.yaml --kube-config=/path/to/config --apply --version=v2.7.0
The policy YAML generated (Kubernetes Custom Resource) using the above example
can also be applied using kubectl
.
kubectl apply -f policy-gen/configuration/rate-limiting-cr.yaml -n aperture-controller
Run the following command to check if the policy was created.
kubectl get policies.fluxninja.com -n aperture-controller
The policy runtime can be visualized in Grafana or any other Prometheus compatible analytics tool. Refer to the Prometheus compatible metrics available from the controller and agent. Some policy blueprints come with recommended Grafana dashboards.
Deleting Policies
Run the following command to delete the above policy:
kubectl delete policies.fluxninja.com rate-limiting -n aperture-controller