istio.io/docs/concepts/writing-config.md

title	headline	sidenav	bodyclass	layout	type
Writing Configuration	Writing Configuration	doc-side-concepts-nav.html	docs	docs	markdown

{% capture overview %} This document describes how to write configuration that conforms to Istio's schemas. All configuration schemas in Istio are defined as protobuf messages. When in doubt, search for the protos. {% endcapture %}

{% capture body %}

Translating to YAML

There is no canonical mapping between protobufs and YAML; instead protobuf defines a canonical mapping to JSON, and YAML defines a canonical mapping to JSON. To ingest YAML as a proto we convert it to JSON then to protobuf.

Important things to note:

• YAML fields are implicitly strings
• Proto repeated fields map to YAML lists; each element in a YAML list is prefixed by a dash (-)
• Proto messages map to JSON objects; in YAML objects are field names all at the same indentation level
• YAML is whitespace sensitive and must use spaces; tabs are never allowed

map and message fields

Proto	YAML
message Metric { string descriptor_name = 1; string value = 2; map labels = 3; }	descriptorName: request_count value: "1" labels: source: origin.ip target: target.service

Note that when numeric literals are used as strings (like value above) they must be enclosed in quotes. Quotation marks (") are optional for normal strings.

repeated fields

Proto	YAML
message Metric { string descriptor_name = 1; string value = 2; map labels = 3; } message MetricsParams { repeated Metric metrics = 1; }	metrics: - descriptorName: request_count value: "1" labels: source: origin.ip target: target.service - descriptorName: request_latency value: response.duration labels: source: origin.ip target: target.service </td>

enum fields

Proto	YAML
enum ValueType { STRING = 1; INT64 = 2; DOUBLE = 3; // more values omitted } message AttributeDescriptor { string name = 1; string description = 2; ValueType value_type = 3; }	name: request.duration value_type: INT64 or name: request.duration valueType: INT64 </td> </tr>

Note that YAML parsing will handle both snake_case and lowerCamelCase field names. lowerCamelCase is the canonical version in YAML.

Nested message fields

Proto	YAML
enum ValueType { STRING = 1; INT64 = 2; DOUBLE = 3; // more values omitted } message LabelDescriptor { string name = 1; string description = 2; ValueType value_type = 3; } message MonitoredResourceDescriptor { string name = 1; string description = 2; repeated LabelDescriptor labels = 3; }	name: My Monitored Resource labels: - name: label one valueType: STRING - name: second label valueType: DOUBLE </td> </tr>

{% endcapture %}

{% capture whatsnext %}

• TODO: link to overall mixer config concept guide (how the config pieces fit together) {% endcapture %}

{% include templates/concept.md %}