istio
/
istio.io
mirror of https://github.com/istio/istio.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
istio.io/archive/v0.1/docs/reference/writing-config.html

95 lines
23 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html><html lang="en" itemscope itemtype="https://schema.org/WebPage" style="overflow-y: scroll;"><head><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="title" content="Writing Configuration"><meta name="og:title" content="Writing Configuration"><meta name="og:image" content="/v0.1/img/logo.png"/><meta name="description" content="How to write Istio config YAML content."><meta name="og:description" content="How to write Istio config YAML content."><title>Istioldie 0.1 / Writing Configuration</title><script> window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date; ga('create', 'UA-98480406-2', 'auto'); ga('send', 'pageview'); </script> <script async src='https://www.google-analytics.com/analytics.js'></script><link href='https://fonts.googleapis.com/css?family=Roboto:400,100,100italic,300,300italic,400italic,500,500italic,700,700italic,900,900italic' rel='stylesheet' type='text/css'><link rel="alternate" type="application/rss+xml" title="Istio Blog RSS" href="/v0.1/feed.xml"><link rel="apple-touch-icon" href="/v0.1/favicons/apple-touch-icon.png" sizes="180x180"><link rel="icon" type="image/png" href="/v0.1/favicons/android-chrome-96x96.png" sizes="96x96" ><link rel="icon" type="image/png" href="/v0.1/favicons/favicon-32x32.png" sizes="32x32"><link rel="icon" type="image/png" href="/v0.1/favicons/favicon-16x16.png" sizes="16x16"><link rel="manifest" href="/v0.1/favicons/manifest.json"><link rel="mask-icon" href="/v0.1/favicons/safari-pinned-tab.svg" color="#2DA6B0"><meta name="msapplication-TileColor" content="#ffffff"><meta name="msapplication-TileImage" content="/v0.1/favicons/mstile-150x150.png"><link href="//maxcdn.bootstrapcdn.com/bootstrap/3.3.1/css/bootstrap.min.css" rel="stylesheet"><link rel="stylesheet" href="/v0.1/css/all.css"><link rel="stylesheet" href="/v0.1/css/prism.css"><link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css"> <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script></head><body class="language-unknown"><div class="nav-hero-container" style="z-index: 200000;"><nav id="header-nav" class="navbar navbar-inverse" role="navigation"><div class="container"><div class="row"><div class="col-md-11 nofloat center-block "><div class="navbar-header"> <button type="button" class="hamburger navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar-collapse-1" aria-expanded="false"> <span class="sr-only">Toggle navigation</span> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button> <a class="navbar-brand" href="/v0.1/"><div> <img src="/v0.1/img/logo.png" alt="Istio" width="36px" height="54px"/> <span class="brand-name">Istioldie 0.1</span></div></a></div><div class="collapse navbar-collapse" id="navbar-collapse-1"><ul class="nav navbar-nav navbar-right"><li><a href="/v0.1/about/" >About</a></li><li><a href="/v0.1/docs/" class='current'>Docs</a></li><li><a href="/v0.1/blog/" >Blog</a></li><li><a href="/v0.1/community/" >Community</a></li><li><a href="/v0.1/faq/" >FAQ</a></li><li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown" href=""> <i class='fa fa-lg fa-cog'></i> <span class="caret"></span> </a><ul class="dropdown-menu"><h6 class="dropdown-header">Other versions of this site</h6><li> <a href="https://istio.io">Current Release</a></li><li> <a href="https://preliminary.istio.io">Next Release</a></li><li> <a href="https://archive.istio.io">Older Releases</a></li></ul></li><li><form name="cse" id="searchbox_demo" class="navbar-form navbar-right" role="search"> <input type="hidden" name="cx" value="013699703217164175118:iwwf17ikgf4" /> <input type="hidden" name="ie" value="utf-8" /> <input type="hidden" name="hl" value="en" /><div class="form-group"><div class="input-group"> <input name="q" class="form-control" type="text" size="30" /><div class="input-group-addon"> <span class="btn-search glyphicon glyphicon-search"></span></div></div></div></form> <script type="text/javascript" src="https://www.google.com/cse/brand?form=searchbox_demo"></script></li></ul></div></div></div></div></nav></div><div class="container"><div class="row"><div class="col-md-11 nofloat center-block" style="margin-top: 3px;"><ul class="col-sm-10 nav nav-tabs"><li role="presentation" ><a href="/v0.1/docs/index.html">Welcome</a></li><li role="presentation" ><a href="/v0.1/docs/concepts/index.html">Concepts</a></li><li role="presentation" ><a href="/v0.1/docs/tasks/index.html">Tasks</a></li><li role="presentation" ><a href="/v0.1/docs/samples/index.html">Samples</a></li><li role="presentation" class='active'><a href="/v0.1/docs/reference/index.html">Reference</a></li></ul></div></div></div><script src="/v0.1/js/navtree.js"></script><div class="container docs"><div class="row"><div class="col-md-11 nofloat center-block"><div class="row"><div id="sidebar-container" class="col-sm-3"><ul class="doc-side-nav"><li><h5 class='doc-side-nav-title'>Reference</h5></li><script type="text/javascript"> var docs = []; docs.push({path: [ "api", "index.md", ], url: "/docs/reference/api/index.html", title: "API", order: 21, overview: "Detailed information on API parameters."}); docs.push({path: [ "api", "mixer", "index.md", ], url: "/docs/reference/api/mixer/index.html", title: "Mixer", order: 10, overview: "Detailed information on configuration and API exposed by Mixer."}); docs.push({path: [ "api", "mixer", "mixer-service.md", ], url: "/docs/reference/api/mixer/mixer-service.html", title: "Mixer Service", order: 1200, overview: "Mixer's API Surface"}); docs.push({path: [ "api", "mixer", "status.md", ], url: "/docs/reference/api/mixer/status.html", title: "Status RPC", order: 40, overview: "Google's rpc.Status proto"}); docs.push({path: [ "commands", "index.md", ], url: "/docs/reference/commands/index.html", title: "CLI", order: 30, overview: "Describes usage and options of the Istio CLI and other utilities."}); docs.push({path: [ "commands", "istioctl.md", ], url: "/docs/reference/commands/istioctl.html", title: "istioctl", order: 1, overview: "Istio control interface"}); docs.push({path: [ "commands", "mixc.md", ], url: "/docs/reference/commands/mixc.html", title: "mixc", order: 101, overview: "Utility to trigger direct calls to Mixer's API."}); docs.push({path: [ "commands", "mixs.md", ], url: "/docs/reference/commands/mixs.html", title: "mixs", order: 201, overview: "Mixer is Istio's abstraction on top of infrastructure backends."}); docs.push({path: [ "config", "index.md", ], url: "/docs/reference/config/index.html", title: "Configuration", order: 22, overview: "Detailed information on configuration options."}); docs.push({path: [ "config", "mixer", "adapters", "denychecker.md", ], url: "/docs/reference/config/mixer/adapters/denyChecker.html", title: "denyChecker", order: 0, overview: "denyChecker adapter configuration schema"}); docs.push({path: [ "config", "mixer", "adapters", "genericlistchecker.md", ], url: "/docs/reference/config/mixer/adapters/genericListChecker.html", title: "genericListChecker", order: 10, overview: "genericListChecker adapter configuration schema"}); docs.push({path: [ "config", "mixer", "adapters", "index.md", ], url: "/docs/reference/config/mixer/adapters/index.html", title: "Adapters", order: 2000, overview: "Mixer's adapter configuration schemas."}); docs.push({path: [ "config", "mixer", "adapters", "iplistchecker.md", ], url: "/docs/reference/config/mixer/adapters/ipListChecker.html", title: "ipListChecker", order: 20, overview: "ipListChecker adapter configuration schema"}); docs.push({path: [ "config", "mixer", "adapters", "kubernetes.md", ], url: "/docs/reference/config/mixer/adapters/kubernetes.html", title: "kubernetes", order: 30, overview: "kubernetes adapter configuration schema"}); docs.push({path: [ "config", "mixer", "adapters", "memquota.md", ], url: "/docs/reference/config/mixer/adapters/memQuota.html", title: "memQuota", order: 40, overview: "memQuota adapter configuration schema"}); docs.push({path: [ "config", "mixer", "adapters", "prometheus.md", ], url: "/docs/reference/config/mixer/adapters/prometheus.html", title: "prometheus", order: 50, overview: "prometheus adapter configuration schema"}); docs.push({path: [ "config", "mixer", "adapters", "redisquota.md", ], url: "/docs/reference/config/mixer/adapters/redisquota.html", title: "redisquota", order: 60, overview: "redisquota adapter configuration schema"}); docs.push({path: [ "config", "mixer", "adapters", "statsd.md", ], url: "/docs/reference/config/mixer/adapters/statsd.html", title: "statsd", order: 70, overview: "statsd adapter configuration schema"}); docs.push({path: [ "config", "mixer", "adapters", "stdiologger.md", ], url: "/docs/reference/config/mixer/adapters/stdioLogger.html", title: "stdioLogger", order: 80, overview: "stdioLogger adapter configuration schema"}); docs.push({path: [ "config", "mixer", "aspects", "accesslogs.md", ], url: "/docs/reference/config/mixer/aspects/accessLogs.html", title: "accessLogs", order: 1120, overview: "accessLogs aspect configuration schema"}); docs.push({path: [ "config", "mixer", "aspects", "applicationlogs.md", ], url: "/docs/reference/config/mixer/aspects/applicationLogs.html", title: "applicationLogs", order: 1130, overview: "applicationLogs aspect configuration schema"}); docs.push({path: [ "config", "mixer", "aspects", "attributes.md", ], url: "/docs/reference/config/mixer/aspects/attributes.html", title: "attributes", order: 1140, overview: "attributes aspect configuration schema"}); docs.push({path: [ "config", "mixer", "aspects", "denials.md", ], url: "/docs/reference/config/mixer/aspects/denials.html", title: "denials", order: 1150, overview: "denials aspect configuration schema"}); docs.push({path: [ "config", "mixer", "aspects", "index.md", ], url: "/docs/reference/config/mixer/aspects/index.html", title: "Aspects", order: 2000, overview: "Generated documentation for Mixer's aspects."}); docs.push({path: [ "config", "mixer", "aspects", "lists.md", ], url: "/docs/reference/config/mixer/aspects/lists.html", title: "lists", order: 1160, overview: "lists aspect configuration schema"}); docs.push({path: [ "config", "mixer", "aspects", "metrics.md", ], url: "/docs/reference/config/mixer/aspects/metrics.html", title: "metrics", order: 1170, overview: "metrics aspect configuration schema"}); docs.push({path: [ "config", "mixer", "aspects", "quotas.md", ], url: "/docs/reference/config/mixer/aspects/quotas.html", title: "quotas", order: 1180, overview: "quotas aspect configuration schema"}); docs.push({path: [ "config", "mixer", "attribute-vocabulary.md", ], url: "/docs/reference/config/mixer/attribute-vocabulary.html", title: "Attribute Vocabulary", order: 10, overview: "Describes the base attribute vocabulary used for policy and control."}); docs.push({path: [ "config", "mixer", "expression-language.md", ], url: "/docs/reference/config/mixer/expression-language.html", title: "Expression Language", order: 43, overview: "Mixer config expression language reference."}); docs.push({path: [ "config", "mixer", "index.md", ], url: "/docs/reference/config/mixer/index.html", title: "Mixer", order: 10, overview: "Detailed information on configuration and API exposed by Mixer."}); docs.push({path: [ "config", "mixer", "mixer-config.md", ], url: "/docs/reference/config/mixer/mixer-config.html", title: "Mixer", order: 1190, overview: "Mixer's configuration schema"}); docs.push({path: [ "config", "service-mesh.md", ], url: "/docs/reference/config/service-mesh.html", title: "Service Mesh", order: 30, overview: "Global configuration schema"}); docs.push({path: [ "config", "traffic-rules", "destination-policies.md", ], url: "/docs/reference/config/traffic-rules/destination-policies.html", title: "Destination Policies", order: 30, overview: "Client-side traffic management policies configuration schema"}); docs.push({path: [ "config", "traffic-rules", "index.md", ], url: "/docs/reference/config/traffic-rules/index.html", title: "Traffic Management Rules", order: 10, overview: "Detailed information on rules configuration and API exposed by Pilot for managing them."}); docs.push({path: [ "config", "traffic-rules", "routing-rules.md", ], url: "/docs/reference/config/traffic-rules/routing-rules.html", title: "Routing Rules", order: 20, overview: "Traffic routing rule configuration schema"}); docs.push({path: [ "contribute", "creating-a-pull-request.md", ], url: "/docs/reference/contribute/creating-a-pull-request.html", title: "Creating a Pull Request", order: 20, overview: "Shows you how to create a GitHub pull request in order to submit your docs for approval."}); docs.push({path: [ "contribute", "editing.md", ], url: "/docs/reference/contribute/editing.html", title: "Editing Docs", order: 10, overview: "Lets you start editing this site's documentation."}); docs.push({path: [ "contribute", "index.md", ], url: "/docs/reference/contribute/index.html", title: "Contributing to the Docs", order: 100, overview: "Learn how to contribute to improve and expand the Istio documentation."}); docs.push({path: [ "contribute", "reviewing-doc-issues.md", ], url: "/docs/reference/contribute/reviewing-doc-issues.html", title: "Doc Issues", order: 60, overview: "Explains the process involved in accepting documentation updates."}); docs.push({path: [ "contribute", "staging-your-changes.md", ], url: "/docs/reference/contribute/staging-your-changes.html", title: "Staging Your Changes", order: 40, overview: "Explains how to test your changes locally before submitting them."}); docs.push({path: [ "contribute", "style-guide.md", ], url: "/docs/reference/contribute/style-guide.html", title: "Style Guide", order: 70, overview: "Explains the dos and donts of writing Istio docs."}); docs.push({path: [ "contribute", "writing-a-new-topic.md", ], url: "/docs/reference/contribute/writing-a-new-topic.html", title: "Writing a New Topic", order: 30, overview: "Explains the mechanics of creating new documentation pages."}); docs.push({path: [ "glossary.md", ], url: "/docs/reference/glossary.html", title: "Glossary", order: 40, overview: "A glossary of common Istio terms."}); docs.push({path: [ "index.md", ], url: "/docs/reference/index.html", title: "Reference", order: 40, overview: "The Reference section contains detailed authoritative reference material such as command-line options, configuration options, and API calling parameters."}); docs.push({path: [ "release-notes.md", ], url: "/docs/reference/release-notes.html", title: "Release Notes", order: 50, overview: "What's been happening with Istio."}); docs.push({path: [ "release-roadmap.md", ], url: "/docs/reference/release-roadmap.html", title: "Roadmap", order: 60, overview: "What Istio will become in the coming months."}); docs.push({path: [ "writing-config.md", ], url: "/docs/reference/writing-config.html", title: "Writing Configuration", order: 70, overview: "How to write Istio config YAML content."}); genNavBarTree(docs) </script></ul></div><div id="tab-container" class="col-xs-1 tab-neg-margin pull-left"> <a id="sidebar-tab" class="glyphicon glyphicon-chevron-left" href="javascript:void 0;"></a></div><div id="content-container" class="thin-left-border col-sm-9 markdown"><div id="toc" class="toc"></div><div id="doc-content"><h1>Writing Configuration</h1><p>This page describes how to write configuration that conforms to Istio’s schemas. All configuration schemas in Istio are defined as <a href="https://developers.google.com/protocol-buffers/docs/proto3">protobuf messages</a>. When in doubt, search for the protos.</p><h2 id="translating-to-yaml">Translating to YAML</h2><p>There’s an implicit mapping from protobuf to YAML using <a href="https://developers.google.com/protocol-buffers/docs/proto3#json">protobuf’s mapping to JSON</a>. Below are a few examples showing common mappings you’ll encounter writing configuration in Istio.</p><p><strong>Important things to note:</strong></p><ul><li>YAML fields are implicitly strings</li><li>Proto <code>repeated</code> fields map to YAML lists; each element in a YAML list is prefixed by a dash (<code>-</code>)</li><li>Proto <code>message</code>s map to objects; in YAML objects are field names all at the same indentation level</li><li>YAML is whitespace sensitive and must use spaces; tabs are never allowed</li></ul><h3 id="map-and-message-fields"><code>map</code> and <code>message</code> fields</h3><table><tbody><tr><th>Proto</th><th>YAML</th></tr><tr><td><pre>
message Metric {
string descriptor_name = 1;
string value = 2;
map&lt;string, string&gt; labels = 3;
}
</pre></td><td><pre>
descriptorName: request_count
value: "1"
labels:
source: origin.ip
target: target.service
</pre></td></tr></tbody></table><p><em>Note that when numeric literals are used as strings (like <code>value</code> above) they must be enclosed in quotes. Quotation marks (<code>"</code>) are optional for normal strings.</em></p><h3 id="repeated-fields"><code>repeated</code> fields</h3><table><tbody><tr><th>Proto</th><th>YAML</th></tr><tr><td><pre>
message Metric {
string descriptor_name = 1;
string value = 2;
map&lt;string, string&gt; labels = 3;
}
message MetricsParams {
repeated Metric metrics = 1;
}
</pre></td><td><pre>
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
</pre></td></tr></tbody></table><h3 id="enum-fields"><code>enum</code> fields</h3><table><tbody><tr><th>Proto</th><th>YAML</th></tr><tr><td><pre>
enum ValueType {
STRING = 1;
INT64 = 2;
DOUBLE = 3;
// more values omitted
}
message AttributeDescriptor {
string name = 1;
string description = 2;
ValueType value_type = 3;
}
</pre></td><td><pre>
name: request.duration
value_type: INT64
</pre>or<pre>
name: request.duration
valueType: INT64
</pre></td></tr></tbody></table><p><em>Note that YAML parsing will handle both <code>snake_case</code> and <code>lowerCamelCase</code> field names. <code>lowerCamelCase</code> is the canonical version in YAML.</em></p><h3 id="nested-message-fields">Nested <code>message</code> fields</h3><table><tbody><tr><th>Proto</th><th>YAML</th></tr><tr><td><pre>
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;
}
</pre></td><td><pre>
name: My Monitored Resource
labels:
- name: label one
valueType: STRING
- name: second label
valueType: DOUBLE
</pre></td></tr></tbody></table><h3 id="timestamp-duration-and-64-bit-integer-fields"><code>Timestamp</code>, <code>Duration</code>, and 64 bit integer fields</h3><p>The protobuf spec special cases the JSON/YAML representations of a few well-known protobuf messages. 64 bit integer types are also special due to the fact that JSON numbers are implicitly doubles, which cannot represent all valid 64 bit integer values.</p><table><tbody><tr><th>Proto</th><th>YAML</th></tr><tr><td><pre>
message Quota {
string descriptor_name = 1;
map&lt;string, string&gt; labels = 2;
int64 max_amount = 3;
google.protobuf.Duration expiration = 4;
}
</pre></td><td><pre>
descriptorName: RequestCount
labels:
label one: STRING
second label: DOUBLE
maxAmount: "7"
expiration: 1.000340012s
</pre></td></tr></tbody></table><p>Specifically, the <a href="https://developers.google.com/protocol-buffers/docs/proto3#json">protobuf spec declares</a>:</p><table><thead><tr><th>Proto</th><th>JSON/YAML</th><th>Example</th><th>Notes</th></tr></thead><tbody><tr><td>Timestamp</td><td>string</td><td>“1972-01-01T10:00:20.021Z”</td><td>Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits.</td></tr><tr><td>Duration</td><td>string</td><td>“1.000340012s”, “1s”</td><td>Generated output always contains 0, 3, 6, or 9 fractional digits, depending on required precision. Accepted are any fractional digits (also none) as long as they fit into nano-seconds precision.</td></tr><tr><td>int64, fixed64, uint64</td><td>string</td><td>“1”, “-10”</td><td>JSON value will be a decimal string. Either numbers or strings are accepted.</td></tr></tbody></table><h2 id="whats-next">What’s next</h2><ul><li>TODO: link to overall mixer config concept guide (how the config pieces fit together)</li></ul></div></div></div></div></div></div><script src="/v0.1/js/sidemenu.js"></script><footer><div class="container"><div class="row"><div class="col-md-2"></div><div class="col-md-3 col-sm-4 col-xs-12 center-block"><ul class="toggle"><p class="header">Docs</p><li><a href="/v0.1/docs/">Welcome</a></li><li><a href="/v0.1/docs/concepts">Concepts</a></li><li><a href="/v0.1/docs/tasks">Tasks</a></li><li><a href="/v0.1/docs/samples">Samples</a></li><li><a href="/v0.1/docs/reference">Reference</a></li></ul></div><hr class="footer-sections" /><div class="col-md-3 col-sm-4 col-xs-12 center-block"><ul class="toggle"><p class="header">Resources</p><li><a href="/v0.1/faq">Frequently Asked Questions</a></li><li><a href="/v0.1/troubleshooting">Troubleshooting Guide</a></li><li><a href="/v0.1/bugs">Report a Bug</a></li><li><a href="https://github.com/istio/istio.github.io/issues/new?title=Issue with _docs/reference/writing-config.md">Report a Doc Issue</a></li><li><a href="https://github.com/istio/istio.github.io/edit/master/_docs/reference/writing-config.md">Edit This Page on GitHub</a></li></ul></div><hr class="footer-sections" /><div class="col-md-3 col-sm-4 col-xs-12 center-block"><ul class="toggle"><p class="header">Community</p><li><a href="https://groups.google.com/forum/#!forum/istio-users" target="_blank"><span class="group">User</span></a> | <a href="https://groups.google.com/forum/#!forum/istio-dev" target="_blank">Dev Mailing Lists</a></li><li><a href="https://twitter.com/IstioMesh" target="_blank"><span class="twitter">Twitter</span></a></li><li><a href="https://github.com/istio/istio" target="_blank"><span class="github">GitHub</span></a></li></ul></div><div class="col-md-1"></div></div><div class="row"><p class="description small text-center"> Copyright &copy; 2017 Istio Authors<br> Istio 0.1<br> Archived on 20-Jul-2017</p></div></div></footer><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-validate/1.15.0/jquery.validate.min.js"></script> <script src="/v0.1/js/jquery.form.min.js"></script> <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.1/js/bootstrap.min.js"></script> <script src="/v0.1/js/slick.min.js"></script> <script src="/v0.1/js/jquery.visible.min.js"></script> <script src="/v0.1/js/common.js" type="text/javascript" charset="utf-8"></script> <script src="/v0.1/js/buttons.js"></script> <script src="/v0.1/js/search.js"></script> <script src="/v0.1/js/prism.js"></script></body></html>
Reference in New Issue View Git Blame Copy Permalink