# `tare gateway config lint`

> Reference for tare gateway config lint, which validates a gcp-gateway.json or azure-gateway.json file before installation.

# `tare gateway config lint`

  Lint a gateway config file (<code>gcp-gateway.json</code> or <code>azure-gateway.json</code>)
  against the v1 rule set.

## Synopsis

```bash
tare gateway config lint [flags]
```

## Description

`tare gateway config lint` applies the registered lint rules to a
gateway config file. The engine is hermetic: it never contacts GCP,
Azure, or Kubernetes, so it is safe to run in pre-merge CI on a config
repo.

Rules cover correctness (required values, internally-consistent
references), safety (latent operational risks like ephemeral gateway
IPs), convention (env-mismatched resource names, identity/customer
divergence), and hygiene (deprecated fields). Provider-specific rules
self-gate on `--type` so an Azure config does not trip GCP-only rules
(e.g. TAREL010 only fires when the resolved provider is `gcp`).

## Flags

| Flag | Default | Description |
|---|---|---|
| `--type` | `gcp` | Gateway provider type (`gcp\|azure`). Controls which provider-gated rules fire. |
| `--config` | `gcp-gateway.json` | Path to the config file (`gcp-gateway.json` or `azure-gateway.json`). |
| `--identity` | _(unset)_ | Optional identity file. Enables identity-aware rules (e.g. TAREL021). |
| `--format` | `text` | Output format: `text` or `json`. |
| `--severity` | `info` | Minimum severity to display: `info`, `warn`, or `error`. |
| `--fail-on-warn` | `false` | Exit non-zero on warnings (CI gating). |
| `--list-rules` | `false` | Print the registered rules and exit 0. |

## Exit codes

- **0**: No findings, or only info/warn findings (use `--fail-on-warn`
  to promote warnings to non-zero exits in CI).
- **1**: At least one error finding.
- **2**: Misuse (bad flags, missing config file, etc.).

## Examples

```bash
# Default: text output, show all findings (GCP)
tare gateway config lint --config gcp-gateway.json

# Azure config
tare gateway config lint --type azure --config azure-gateway.json

# CI gating — fail the pipeline on warnings or errors
tare gateway config lint --config gcp-gateway.json --fail-on-warn

# JSON output for ingestion by other tooling
tare gateway config lint --config gcp-gateway.json --format json

# Identity-aware mode (enables TAREL021 customer-vs-identity check)
tare gateway config lint \
  --config gcp-gateway.json \
  --identity identity.json

# Inspect the rule registry
tare gateway config lint --list-rules
```

## v1 rule set

Six rules ship in v1. The seventh (`TAREL011`, wildcard intent) is
deferred to v1.1 pending a specification of the downstream wildcard
contract.

| ID | Severity | Category | What it catches |
|---|---|---|---|
| **TAREL001** | Error | Correctness | Required value cannot be resolved after merging flags + config + identity + defaults. |
| **TAREL002** | Error | Correctness | `certificateMap.name` set but `certificate.name` empty: cert-map-entry step will fail at GCP. |
| **TAREL010** | Warn | Safety | `gateway.staticIpName` empty: gateway gets an ephemeral address; customer DNS will eventually break. |
| **TAREL020** | Warn | Convention | Resource names embed an env-like substring (`stag`, `dev`, `test`) that disagrees with `environment`. |
| **TAREL021** | Warn | Convention | Config `customer` differs from `identity.customerId`: usually a wrong-identity-for-this-config install. |
| **TAREL030** | Info | Hygiene | Redundant/deprecated fields (e.g. `serveDomain == serveUrl`; legacy `proxy` in identity). |

Each rule has a docs anchor at
`https://docs.tetrate.ai/tare/lint/<RULE_ID>` and is overridable per
config via the `lint` block in `gcp-gateway.json`:

```json
{
  "lint": {
    "ignore": ["TAREL020"],
    "rules": {
      "TAREL021": { "expectedPattern": "^pocnt-(stag|prod)-" }
    }
  }
}
```

## Output formats

### Text (default)

```
⚠ [TAREL010] gateway.staticIpName — gateway will receive an ephemeral
             GCP forwarding-rule address; customer DNS A records may
             break on reschedule.
             Remediate: set gateway.staticIpName in gcp-gateway.json
                        or pass --static-ip-name on install.

Summary: 0 error, 1 warn, 0 info
```

### JSON

The JSON schema is a **public contract** versioned via the
`apiVersion: tare.tetrate.io/v1alpha1` header. CI integrations and
external tooling can depend on this shape; breaking changes will bump
the version.

```json
{
  "apiVersion": "tare.tetrate.io/v1alpha1",
  "kind": "LintReport",
  "config": "gcp-gateway.json",
  "summary": { "error": 0, "warn": 1, "info": 0 },
  "findings": [
    {
      "ruleId": "TAREL010",
      "severity": "warn",
      "field": "gateway.staticIpName",
      "message": "...",
      "remediate": "...",
      "docsUrl": "https://docs.tetrate.ai/tare/lint/TAREL010"
    }
  ]
}
```

Where to go next

  <Link to="/reference/tare-cli/gateway-config-init" className="tare-nav-card">
    tare gateway config init
    Generate a starter config file that passes these rules.
  </Link>
  <Link to="/reference/tare-cli/gcp-gateway-config" className="tare-nav-card">
    gcp-gateway.json schema
    Full field reference for the config file being linted.
  </Link>