Skip to main content
Version: 2.8.0

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.

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.8.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=rate-limiting/base --version=v2.8.0 --output-file=values.yaml

You can then edit the values.yaml to provide the required fields (__REQUIRED_FIELD__ placeholder) as follows:

# 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

Generating Policies and Dashboards​

Once the values.yaml file is ready, you can generate the blueprint using the following command:

aperturectl blueprints generate --name=rate-limiting/base --values-file=values.yaml --output-dir=policy-gen --version=v2.8.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.

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=rate-limiting/base --values-file=values.yaml --apply --version=v2.8.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=rate-limiting/base --values-file=values.yaml --kube-config=/path/to/config --apply --version=v2.8.0

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