Your First Policy

Introduction

The easiest way to get started with policies in Aperture is to use the built-in blueprint system. The Aperture repository contains several blueprints that can be used to generate policies and Grafana dashboards. Blueprints can be used both as a guide for creating new policies, or used as-is by providing required parameters or customizations.

To manage blueprints and generate policies, you can use the aperturectl CLI tool, by following the installation steps first.

Advanced users can learn about designing new policies by following the example circuit created in

Detecting overload tutorial.

flowchart TD subgraph generation["Blueprints System"] aperturectl["aperturectl"] repository[("Blueprints")] values[/"value.yaml"/] policies[/"Policies"/] controller["Controller"] repository --> |pull| aperturectl aperturectl --> |values| values values --> |generate| policies policies --> |apply| controller end

Listing Available Blueprints

The following command can be used to list available blueprints:

aperturectl blueprints list --version=v2.6.0

Which will output the following:

dashboards/auto-scale
dashboards/flow-control/adaptive-load-scheduler
dashboards/flow-control/load-ramp
dashboards/flow-control/quota-scheduler
dashboards/flow-control/rate-limiter
dashboards/signals
policies/auto-scaling/pod-auto-scaler
policies/feature-rollout/average-latency
policies/feature-rollout/base
policies/feature-rollout/ema-latency
policies/feature-rollout/percentile-latency
policies/feature-rollout/promql
policies/quota-scheduler
policies/rate-limiting
policies/service-protection/average-latency
policies/service-protection/postgresql
policies/service-protection/promql

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.6.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

# yaml-language-server: $schema=../../../../../blueprints/policies/rate-limiting/gen/definitions.json
# Generated values file for policies/rate-limiting blueprint
# Documentation/Reference for objects and parameters can be found at:
# https://docs.fluxninja.com/reference/blueprints/policies/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:

Placeholder Values

# Generated values file for policies/rate-limiting blueprint
# Documentation/Reference for objects and parameters can be found at:
# https://docs.fluxninja.com/reference/blueprints/policies/rate-limiting

policy:
  # Name of the policy.
  # Type: string
  # Required: True
  policy_name: __REQUIRED_FIELD__
  # 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: __REQUIRED_FIELD__
    # Fill amount.
    # Type: float64
    # Required: True
    fill_amount: __REQUIRED_FIELD__
    # Flow selectors to match requests against
    # Type: []aperture.spec.v1.Selector
    selectors:
      - control_point: __REQUIRED_FIELD__
        service: __REQUIRED_FIELD__
    # Parameters.
    # Type: aperture.spec.v1.RateLimiterParameters
    parameters:
      # Flow label key to use for rate limiting. If not specified, then all requests matching the selector will be rate limited.
      # Type: string
      label_key: ""
      # Fill interval e.g. "1s".
      # Type: string
      # Required: True
      interval: __REQUIRED_FIELD__

dashboard:
  # Refresh interval for dashboard panels.
  # Type: string
  refresh_interval: "10s"
  # Additional filters to pass to each query to Grafana datasource.
  # Type: map[string]string
  extra_filters: {}
  # Name of the main dashboard.
  # Type: string
  title: "Aperture Rate Limiter"
  datasource:
    # Datasource name.
    # Type: string
    name: "$datasource"
    # Datasource filter regex.
    # Type: string
    filter_regex: ""

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.6.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

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.6.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.6.0

kubectl

The policy YAML generated (Kubernetes Custom Resource) using the above example can also be applied using kubectl.

kubectl apply -f policy-gen/policies/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