Static Analyzer
The Traefik Hub Static Analyzer is a tool designed to analyze your Traefik Hub manifests, ensuring they adhere to best practices and avoid common pitfalls.
Introduction
When developing APIs, managing configurations, or integrating changes into your CI/CD pipelines, this tool can be a go-to solution for maintaining the quality and consistency of Traefik Hub-based projects.
The Static Analyzer can validate Traefik Hub resources with Custom Resource Definitions (CRDs), lint custom resources, and generate diff change reports.
By integrating it into development workflows, one can catch issues early, streamline collaboration, and ensure the reliability of a change.
Install
The tool can be downloaded for Linux, Mac and Windows in traefik/hub releases
Lint
Evaluate resources and check common sources of misconfiguration.
hub-static-analyzer lint --path [path/to/manifests]
The linter evaluates different rules against your manifests. By default, all rules are enabled.
| Name | Description |
|---|---|
| apikeysecret | Check API Key Secrets contain the required "key" field |
| apikeytitle | Check API Keys title |
| appid | Check resources with duplicate appID |
| auth-coverage | Check APIAuth chains that do not cover every operation |
| childless | Check childless resources |
| duplicate | Check duplicate resources and resource references |
| ineffective | Check ineffective resources |
| insecureskipverify | Check insecureSkipVerify is not enabled on auth resources |
| keyless | Check API that use keyless authentication |
| operation-set | Check for unknown operation sets |
| orphan | Check orphan resources |
| reference | Check invalid resource references |
| regex | Check invalid regex |
| release | Check duplicate releases of a given API |
| resource | Check resource definitions |
| selector | Check selector definitions |
| uplink | Check Uplink configuration conflicts |
A rule can be turned off using the --rule.<name>=false flag. The resource rule also validates manifests against the Traefik Hub CRD schemas before any rule runs, and can't be disabled.
The command exits with:
0: no issue was found.1: at least one issue was found.
By default, it outputs results in Unix format:
manifests/02-api.yaml:1:1 service port :8081 defined on field "service.openApiSpec.port" in resource petstore/my-petstore-api (API) is not found in petstore/petstore (Service) [service-port]
manifests/02-api.yaml:1:1: Operation set "public-operations" accepts authentication from multiple APIAuth; APIAuth "my-ns/my-keyless-auth" is a keyless method, so the operations are public [keyless]
A different output format can be specified using the flag --format:
jsonsarifcheckstyleunix
Diff
Analyze the differences between two revisions. This command generates change reports to better understand the impact of a manifest update.
hub-static-analyzer diff --path [path/to/manifests] [<commit>...<commit>]
The following analyzers are run against both revisions:
| Name | Description |
|---|---|
| api | Report the authentication methods available on each API, down to the operation level |
| application | Report the access, plans and authentication methods gained or lost by applications |
| portal | Report the visibility and plans gained or lost by portal groups |
| version | Report added and decommissioned API versions |
# Gateway 1:
Groups gained access:
| GROUP | API | BUNDLE | PLAN |
|----------|----------|-----------|-----------------------------|
| my-group | my-ns/my-api-2 | my-bundle | gold (rl: 1/1s, q: 1/750h) |
Groups lost access:
| GROUP | API | BUNDLE |
|----------|---------|-----------|
| my-group | my-ns/old-api | my-bundle |
Plans has changed for groups:
| GROUP | API | BUNDLE | PLAN |
|----------|--------------|-----------|----------------------------|
| my-group | my-ns/my-api | my-bundle | gold (rl: 1/1s, q: 1/750h) |
API versions have been added:
| API | VERSION | CURRENT |
|--------|--------------------|---------|
| my-api | my-api-v2 (v2.0.0) | true |
APIs current version have changed:
| API | BEFORE | AFTER |
|--------|--------------------|--------------------|
| my-api | my-api-v1 (v1.0.0) | my-api-v2 (v2.0.0) |
Authentication has been added on:
| API | VERSION | OPERATION SET | AUTH |
|------------------------|---------------------------|----------------|----------------------|
| demo/notification-api | demo/notification-api-v1 | - | demo/jwt-auth (jwt) |
| demo/order-api | demo/order-api-v2 | - | demo/jwt-auth (jwt) |
| demo/user-api | demo/user-api-v2 | - | demo/jwt-auth (jwt) |
Authentication has been removed from:
| API | VERSION | OPERATION SET | AUTH |
|------------------|----------------------|----------------|------------------------------|
| demo/legacy-api | demo/legacy-api-v1 | - | demo/default-auth (apiKey) |
Authentication has changed on:
| API | VERSION | OPERATION SET | BEFORE | AFTER |
|-------------------|---------------------|----------------|------------------------------|----------------------|
| demo/order-api | demo/order-api-v1 | - | demo/default-auth (apiKey) | demo/jwt-auth (jwt) |
| demo/payment-api | - | - | demo/default-auth (apiKey) | demo/jwt-auth (jwt) |
| demo/user-api | demo/user-api-v1 | - | demo/default-auth (apiKey) | demo/jwt-auth (jwt) |
Kustomize
hub-static-analyzer analyzes the content of raw manifests.
Therefore, when using Kustomize, you must first generate your final manifest.
To use Kustomize with an overlay, point your --path to the overlay directory.
This can be achieved by running the following command:
kubectl kustomize /path/to/manifests -o /tmp/kustomized
hub-static-analyzer lint -p /tmp/kustomized
When using Flux, you may rely on variable substitutions.
hub-static-analyzer will fail to analyze your files if they contain such variables.
In this case, you'll need to substitute variables before running the static analysis:
go install github.com/drone/envsubst/cmd/envsubst@latest
# Or install the `gettext-base` package on Debian/Ubuntu or `gettext` on CentOS/RHEL/Fedora/Arch
export MY_VARIABLE=MY_VALUE
kubectl kustomize /path/to/manifests -o /tmp/kustomized | $GOPATH/bin/envsubst | yq --split-exp '.metadata.name + "." + $index + ".yaml"' --no-doc
hub-static-analyzer lint -p /tmp/kustomized
