# Istio APIs and Common Configuration Definitions

This repository defines component-level APIs and common configuration formats for the Istio
platform. These definitions are specified using the [protobuf](https://github.com/google/protobuf)
syntax.

This repository depends only on the [tools](https://github.com/istio/tools) repository for tools used during build. This repository *will not* depend on any
other repositories. Except for tools, all other Istio repositories can take a dependency on the api repository.

## API Guidelines

When making changes to the protos in this repository, your changes **must** comply with the [API guidelines](./GUIDELINES.md).

## Updating

After the [protobuf](https://github.com/google/protobuf) definitions
are updated, the corresponding `*pb.go`, `_pb2.py`, `*.json` and
Kubernetes Custom Resource Definition files must be
generated by running `make gen` and submitted as
part of the same PR as the updated definitions. Also `make
gen` will update the proto.lock file with new changes.

## Backwards Incompatible Changes

If a PR tries to make backwards incompatible changes, it will be blocked by `buf breaking`.
If there are legitimate reasons to make these breaking changes forever, the configuration in [`buf.yaml`](buf.yaml) can be changed.
If it is a one-off case, the PR can be force approved skipping the test.