13081 lines
590 KiB
HTML
13081 lines
590 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="generator" content="Asciidoctor 1.5.2">
|
|
<title>Spring Cloud</title>
|
|
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400">
|
|
<style>
|
|
/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
|
|
/* Remove the comments around the @import statement below when using this as a custom stylesheet */
|
|
/*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400";*/
|
|
article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block}
|
|
audio,canvas,video{display:inline-block}
|
|
audio:not([controls]){display:none;height:0}
|
|
[hidden],template{display:none}
|
|
script{display:none!important}
|
|
html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
|
|
body{margin:0}
|
|
a{background:transparent}
|
|
a:focus{outline:thin dotted}
|
|
a:active,a:hover{outline:0}
|
|
h1{font-size:2em;margin:.67em 0}
|
|
abbr[title]{border-bottom:1px dotted}
|
|
b,strong{font-weight:bold}
|
|
dfn{font-style:italic}
|
|
hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
|
|
mark{background:#ff0;color:#000}
|
|
code,kbd,pre,samp{font-family:monospace;font-size:1em}
|
|
pre{white-space:pre-wrap}
|
|
q{quotes:"\201C" "\201D" "\2018" "\2019"}
|
|
small{font-size:80%}
|
|
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
|
|
sup{top:-.5em}
|
|
sub{bottom:-.25em}
|
|
img{border:0}
|
|
svg:not(:root){overflow:hidden}
|
|
figure{margin:0}
|
|
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
|
|
legend{border:0;padding:0}
|
|
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
|
|
button,input{line-height:normal}
|
|
button,select{text-transform:none}
|
|
button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
|
|
button[disabled],html input[disabled]{cursor:default}
|
|
input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
|
|
input[type="search"]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}
|
|
input[type="search"]::-webkit-search-cancel-button,input[type="search"]::-webkit-search-decoration{-webkit-appearance:none}
|
|
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
|
|
textarea{overflow:auto;vertical-align:top}
|
|
table{border-collapse:collapse;border-spacing:0}
|
|
*,*:before,*:after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
|
|
html,body{font-size:100%}
|
|
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto}
|
|
a:hover{cursor:pointer}
|
|
img,object,embed{max-width:100%;height:auto}
|
|
object,embed{height:100%}
|
|
img{-ms-interpolation-mode:bicubic}
|
|
#map_canvas img,#map_canvas embed,#map_canvas object,.map_canvas img,.map_canvas embed,.map_canvas object{max-width:none!important}
|
|
.left{float:left!important}
|
|
.right{float:right!important}
|
|
.text-left{text-align:left!important}
|
|
.text-right{text-align:right!important}
|
|
.text-center{text-align:center!important}
|
|
.text-justify{text-align:justify!important}
|
|
.hide{display:none}
|
|
.antialiased,body{-webkit-font-smoothing:antialiased}
|
|
img{display:inline-block;vertical-align:middle}
|
|
textarea{height:auto;min-height:50px}
|
|
select{width:100%}
|
|
p.lead,.paragraph.lead>p,#preamble>.sectionbody>.paragraph:first-of-type p{font-size:1.21875em;line-height:1.6}
|
|
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
|
|
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}
|
|
a{color:#2156a5;text-decoration:underline;line-height:inherit}
|
|
a:hover,a:focus{color:#1d4b8f}
|
|
a img{border:none}
|
|
p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
|
|
p aside{font-size:.875em;line-height:1.35;font-style:italic}
|
|
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
|
|
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
|
|
h1{font-size:2.125em}
|
|
h2{font-size:1.6875em}
|
|
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
|
|
h4,h5{font-size:1.125em}
|
|
h6{font-size:1em}
|
|
hr{border:solid #ddddd8;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
|
|
em,i{font-style:italic;line-height:inherit}
|
|
strong,b{font-weight:bold;line-height:inherit}
|
|
small{font-size:60%;line-height:inherit}
|
|
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
|
|
ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
|
|
ul,ol,ul.no-bullet,ol.no-bullet{margin-left:1.5em}
|
|
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
|
|
ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
|
|
ul.square{list-style-type:square}
|
|
ul.circle{list-style-type:circle}
|
|
ul.disc{list-style-type:disc}
|
|
ul.no-bullet{list-style:none}
|
|
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
|
|
dl dt{margin-bottom:.3125em;font-weight:bold}
|
|
dl dd{margin-bottom:1.25em}
|
|
abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
|
|
abbr{text-transform:none}
|
|
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
|
|
blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
|
|
blockquote cite:before{content:"\2014 \0020"}
|
|
blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
|
|
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
|
|
@media only screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
|
|
h1{font-size:2.75em}
|
|
h2{font-size:2.3125em}
|
|
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
|
|
h4{font-size:1.4375em}}table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
|
|
table thead,table tfoot{background:#f7f8f7;font-weight:bold}
|
|
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
|
|
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
|
|
table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7}
|
|
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}
|
|
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
|
|
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
|
|
.clearfix:before,.clearfix:after,.float-group:before,.float-group:after{content:" ";display:table}
|
|
.clearfix:after,.float-group:after{clear:both}
|
|
*:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
|
|
pre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;text-rendering:optimizeSpeed}
|
|
.keyseq{color:rgba(51,51,51,.8)}
|
|
kbd{display:inline-block;color:rgba(0,0,0,.8);font-size:.75em;line-height:1.4;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:-.15em .15em 0 .15em;padding:.2em .6em .2em .5em;vertical-align:middle;white-space:nowrap}
|
|
.keyseq kbd:first-child{margin-left:0}
|
|
.keyseq kbd:last-child{margin-right:0}
|
|
.menuseq,.menu{color:rgba(0,0,0,.8)}
|
|
b.button:before,b.button:after{position:relative;top:-1px;font-weight:400}
|
|
b.button:before{content:"[";padding:0 3px 0 2px}
|
|
b.button:after{content:"]";padding:0 2px 0 3px}
|
|
p a>code:hover{color:rgba(0,0,0,.9)}
|
|
#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
|
|
#header:before,#header:after,#content:before,#content:after,#footnotes:before,#footnotes:after,#footer:before,#footer:after{content:" ";display:table}
|
|
#header:after,#content:after,#footnotes:after,#footer:after{clear:both}
|
|
#content{margin-top:1.25em}
|
|
#content:before{content:none}
|
|
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
|
|
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #ddddd8}
|
|
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #ddddd8;padding-bottom:8px}
|
|
#header .details{border-bottom:1px solid #ddddd8;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}
|
|
#header .details span:first-child{margin-left:-.125em}
|
|
#header .details span.email a{color:rgba(0,0,0,.85)}
|
|
#header .details br{display:none}
|
|
#header .details br+span:before{content:"\00a0\2013\00a0"}
|
|
#header .details br+span.author:before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
|
|
#header .details br+span#revremark:before{content:"\00a0|\00a0"}
|
|
#header #revnumber{text-transform:capitalize}
|
|
#header #revnumber:after{content:"\00a0"}
|
|
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #ddddd8;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
|
|
#toc{border-bottom:1px solid #efefed;padding-bottom:.5em}
|
|
#toc>ul{margin-left:.125em}
|
|
#toc ul.sectlevel0>li>a{font-style:italic}
|
|
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
|
|
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
|
|
#toc a{text-decoration:none}
|
|
#toc a:active{text-decoration:underline}
|
|
#toctitle{color:#7a2518;font-size:1.2em}
|
|
@media only screen and (min-width:768px){#toctitle{font-size:1.375em}
|
|
body.toc2{padding-left:15em;padding-right:0}
|
|
#toc.toc2{margin-top:0!important;background-color:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #efefed;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
|
|
#toc.toc2 #toctitle{margin-top:0;font-size:1.2em}
|
|
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
|
|
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
|
|
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
|
|
body.toc2.toc-right{padding-left:0;padding-right:15em}
|
|
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #efefed;left:auto;right:0}}@media only screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
|
|
#toc.toc2{width:20em}
|
|
#toc.toc2 #toctitle{font-size:1.375em}
|
|
#toc.toc2>ul{font-size:.95em}
|
|
#toc.toc2 ul ul{padding-left:1.25em}
|
|
body.toc2.toc-right{padding-left:0;padding-right:20em}}#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
|
|
#content #toc>:first-child{margin-top:0}
|
|
#content #toc>:last-child{margin-bottom:0}
|
|
#footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em}
|
|
#footer-text{color:rgba(255,255,255,.8);line-height:1.44}
|
|
.sect1{padding-bottom:.625em}
|
|
@media only screen and (min-width:768px){.sect1{padding-bottom:1.25em}}.sect1+.sect1{border-top:1px solid #efefed}
|
|
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
|
|
#content h1>a.anchor:before,h2>a.anchor:before,h3>a.anchor:before,#toctitle>a.anchor:before,.sidebarblock>.content>.title>a.anchor:before,h4>a.anchor:before,h5>a.anchor:before,h6>a.anchor:before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
|
|
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
|
|
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
|
|
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
|
|
.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
|
|
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
|
|
table.tableblock>caption.title{white-space:nowrap;overflow:visible;max-width:0}
|
|
.paragraph.lead>p,#preamble>.sectionbody>.paragraph:first-of-type p{color:rgba(0,0,0,.85)}
|
|
table.tableblock #preamble>.sectionbody>.paragraph:first-of-type p{font-size:inherit}
|
|
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
|
|
.admonitionblock>table td.icon{text-align:center;width:80px}
|
|
.admonitionblock>table td.icon img{max-width:none}
|
|
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
|
|
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #ddddd8;color:rgba(0,0,0,.6)}
|
|
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
|
|
.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}
|
|
.exampleblock>.content>:first-child{margin-top:0}
|
|
.exampleblock>.content>:last-child{margin-bottom:0}
|
|
.sidebarblock{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
|
|
.sidebarblock>:first-child{margin-top:0}
|
|
.sidebarblock>:last-child{margin-bottom:0}
|
|
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
|
|
.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
|
|
.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8}
|
|
.sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1}
|
|
.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;padding:1em;font-size:.8125em}
|
|
.literalblock pre.nowrap,.literalblock pre[class].nowrap,.listingblock pre.nowrap,.listingblock pre[class].nowrap{overflow-x:auto;white-space:pre;word-wrap:normal}
|
|
@media only screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}}@media only screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}}.literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)}
|
|
.listingblock pre.highlightjs{padding:0}
|
|
.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
|
|
.listingblock pre.prettyprint{border-width:0}
|
|
.listingblock>.content{position:relative}
|
|
.listingblock code[data-lang]:before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:#999}
|
|
.listingblock:hover code[data-lang]:before{display:block}
|
|
.listingblock.terminal pre .command:before{content:attr(data-prompt);padding-right:.5em;color:#999}
|
|
.listingblock.terminal pre .command:not([data-prompt]):before{content:"$"}
|
|
table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none}
|
|
table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0}
|
|
table.pyhltable td.code{padding-left:.75em;padding-right:0}
|
|
pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #ddddd8}
|
|
pre.pygments .lineno{display:inline-block;margin-right:.25em}
|
|
table.pyhltable .linenodiv{background:none!important;padding-right:0!important}
|
|
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
|
|
.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em}
|
|
.quoteblock blockquote,.quoteblock blockquote p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
|
|
.quoteblock blockquote{margin:0;padding:0;border:0}
|
|
.quoteblock blockquote:before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
|
|
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
|
|
.quoteblock .attribution{margin-top:.5em;margin-right:.5ex;text-align:right}
|
|
.quoteblock .quoteblock{margin-left:0;margin-right:0;padding:.5em 0;border-left:3px solid rgba(0,0,0,.6)}
|
|
.quoteblock .quoteblock blockquote{padding:0 0 0 .75em}
|
|
.quoteblock .quoteblock blockquote:before{display:none}
|
|
.verseblock{margin:0 1em 1.25em 1em}
|
|
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
|
|
.verseblock pre strong{font-weight:400}
|
|
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
|
|
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
|
|
.quoteblock .attribution br,.verseblock .attribution br{display:none}
|
|
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.05em;color:rgba(0,0,0,.6)}
|
|
.quoteblock.abstract{margin:0 0 1.25em 0;display:block}
|
|
.quoteblock.abstract blockquote,.quoteblock.abstract blockquote p{text-align:left;word-spacing:0}
|
|
.quoteblock.abstract blockquote:before,.quoteblock.abstract blockquote p:first-of-type:before{display:none}
|
|
table.tableblock{max-width:100%;border-collapse:separate}
|
|
table.tableblock td>.paragraph:last-child p>p:last-child,table.tableblock th>p:last-child,table.tableblock td>p:last-child{margin-bottom:0}
|
|
table.spread{width:100%}
|
|
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
|
|
table.grid-all th.tableblock,table.grid-all td.tableblock{border-width:0 1px 1px 0}
|
|
table.grid-all tfoot>tr>th.tableblock,table.grid-all tfoot>tr>td.tableblock{border-width:1px 1px 0 0}
|
|
table.grid-cols th.tableblock,table.grid-cols td.tableblock{border-width:0 1px 0 0}
|
|
table.grid-all *>tr>.tableblock:last-child,table.grid-cols *>tr>.tableblock:last-child{border-right-width:0}
|
|
table.grid-rows th.tableblock,table.grid-rows td.tableblock{border-width:0 0 1px 0}
|
|
table.grid-all tbody>tr:last-child>th.tableblock,table.grid-all tbody>tr:last-child>td.tableblock,table.grid-all thead:last-child>tr>th.tableblock,table.grid-rows tbody>tr:last-child>th.tableblock,table.grid-rows tbody>tr:last-child>td.tableblock,table.grid-rows thead:last-child>tr>th.tableblock{border-bottom-width:0}
|
|
table.grid-rows tfoot>tr>th.tableblock,table.grid-rows tfoot>tr>td.tableblock{border-width:1px 0 0 0}
|
|
table.frame-all{border-width:1px}
|
|
table.frame-sides{border-width:0 1px}
|
|
table.frame-topbot{border-width:1px 0}
|
|
th.halign-left,td.halign-left{text-align:left}
|
|
th.halign-right,td.halign-right{text-align:right}
|
|
th.halign-center,td.halign-center{text-align:center}
|
|
th.valign-top,td.valign-top{vertical-align:top}
|
|
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
|
|
th.valign-middle,td.valign-middle{vertical-align:middle}
|
|
table thead th,table tfoot th{font-weight:bold}
|
|
tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
|
|
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
|
|
p.tableblock>code:only-child{background:none;padding:0}
|
|
p.tableblock{font-size:1em}
|
|
td>div.verse{white-space:pre}
|
|
ol{margin-left:1.75em}
|
|
ul li ol{margin-left:1.5em}
|
|
dl dd{margin-left:1.125em}
|
|
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
|
|
ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
|
|
ul.unstyled,ol.unnumbered,ul.checklist,ul.none{list-style-type:none}
|
|
ul.unstyled,ol.unnumbered,ul.checklist{margin-left:.625em}
|
|
ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1em;font-size:.85em}
|
|
ul.checklist li>p:first-child>input[type="checkbox"]:first-child{width:1em;position:relative;top:1px}
|
|
ul.inline{margin:0 auto .625em auto;margin-left:-1.375em;margin-right:0;padding:0;list-style:none;overflow:hidden}
|
|
ul.inline>li{list-style:none;float:left;margin-left:1.375em;display:block}
|
|
ul.inline>li>*{display:block}
|
|
.unstyled dl dt{font-weight:400;font-style:normal}
|
|
ol.arabic{list-style-type:decimal}
|
|
ol.decimal{list-style-type:decimal-leading-zero}
|
|
ol.loweralpha{list-style-type:lower-alpha}
|
|
ol.upperalpha{list-style-type:upper-alpha}
|
|
ol.lowerroman{list-style-type:lower-roman}
|
|
ol.upperroman{list-style-type:upper-roman}
|
|
ol.lowergreek{list-style-type:lower-greek}
|
|
.hdlist>table,.colist>table{border:0;background:none}
|
|
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
|
|
td.hdlist1{padding-right:.75em;font-weight:bold}
|
|
td.hdlist1,td.hdlist2{vertical-align:top}
|
|
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
|
|
.colist>table tr>td:first-of-type{padding:0 .75em;line-height:1}
|
|
.colist>table tr>td:last-of-type{padding:.25em 0}
|
|
.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}
|
|
.imageblock.left,.imageblock[style*="float: left"]{margin:.25em .625em 1.25em 0}
|
|
.imageblock.right,.imageblock[style*="float: right"]{margin:.25em 0 1.25em .625em}
|
|
.imageblock>.title{margin-bottom:0}
|
|
.imageblock.thumb,.imageblock.th{border-width:6px}
|
|
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
|
|
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
|
|
.image.left{margin-right:.625em}
|
|
.image.right{margin-left:.625em}
|
|
a.image{text-decoration:none}
|
|
span.footnote,span.footnoteref{vertical-align:super;font-size:.875em}
|
|
span.footnote a,span.footnoteref a{text-decoration:none}
|
|
span.footnote a:active,span.footnoteref a:active{text-decoration:underline}
|
|
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
|
|
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em 0;border-width:1px 0 0 0}
|
|
#footnotes .footnote{padding:0 .375em;line-height:1.3;font-size:.875em;margin-left:1.2em;text-indent:-1.2em;margin-bottom:.2em}
|
|
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none}
|
|
#footnotes .footnote:last-of-type{margin-bottom:0}
|
|
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
|
|
.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
|
|
.gist .file-data>table td.line-data{width:99%}
|
|
div.unbreakable{page-break-inside:avoid}
|
|
.big{font-size:larger}
|
|
.small{font-size:smaller}
|
|
.underline{text-decoration:underline}
|
|
.overline{text-decoration:overline}
|
|
.line-through{text-decoration:line-through}
|
|
.aqua{color:#00bfbf}
|
|
.aqua-background{background-color:#00fafa}
|
|
.black{color:#000}
|
|
.black-background{background-color:#000}
|
|
.blue{color:#0000bf}
|
|
.blue-background{background-color:#0000fa}
|
|
.fuchsia{color:#bf00bf}
|
|
.fuchsia-background{background-color:#fa00fa}
|
|
.gray{color:#606060}
|
|
.gray-background{background-color:#7d7d7d}
|
|
.green{color:#006000}
|
|
.green-background{background-color:#007d00}
|
|
.lime{color:#00bf00}
|
|
.lime-background{background-color:#00fa00}
|
|
.maroon{color:#600000}
|
|
.maroon-background{background-color:#7d0000}
|
|
.navy{color:#000060}
|
|
.navy-background{background-color:#00007d}
|
|
.olive{color:#606000}
|
|
.olive-background{background-color:#7d7d00}
|
|
.purple{color:#600060}
|
|
.purple-background{background-color:#7d007d}
|
|
.red{color:#bf0000}
|
|
.red-background{background-color:#fa0000}
|
|
.silver{color:#909090}
|
|
.silver-background{background-color:#bcbcbc}
|
|
.teal{color:#006060}
|
|
.teal-background{background-color:#007d7d}
|
|
.white{color:#bfbfbf}
|
|
.white-background{background-color:#fafafa}
|
|
.yellow{color:#bfbf00}
|
|
.yellow-background{background-color:#fafa00}
|
|
span.icon>.fa{cursor:default}
|
|
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
|
|
.admonitionblock td.icon .icon-note:before{content:"\f05a";color:#19407c}
|
|
.admonitionblock td.icon .icon-tip:before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
|
|
.admonitionblock td.icon .icon-warning:before{content:"\f071";color:#bf6900}
|
|
.admonitionblock td.icon .icon-caution:before{content:"\f06d";color:#bf3400}
|
|
.admonitionblock td.icon .icon-important:before{content:"\f06a";color:#bf0000}
|
|
.conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
|
|
.conum[data-value] *{color:#fff!important}
|
|
.conum[data-value]+b{display:none}
|
|
.conum[data-value]:after{content:attr(data-value)}
|
|
pre .conum[data-value]{position:relative;top:-.125em}
|
|
b.conum *{color:inherit!important}
|
|
.conum:not([data-value]):empty{display:none}
|
|
h1,h2{letter-spacing:-.01em}
|
|
dt,th.tableblock,td.content{text-rendering:optimizeLegibility}
|
|
p,td.content{letter-spacing:-.01em}
|
|
p strong,td.content strong{letter-spacing:-.005em}
|
|
p,blockquote,dt,td.content{font-size:1.0625rem}
|
|
p{margin-bottom:1.25rem}
|
|
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
|
|
.exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
|
|
.print-only{display:none!important}
|
|
@media print{@page{margin:1.25cm .75cm}
|
|
*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
|
|
a{color:inherit!important;text-decoration:underline!important}
|
|
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
|
|
a[href^="http:"]:not(.bare):after,a[href^="https:"]:not(.bare):after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
|
|
abbr[title]:after{content:" (" attr(title) ")"}
|
|
pre,blockquote,tr,img{page-break-inside:avoid}
|
|
thead{display:table-header-group}
|
|
img{max-width:100%!important}
|
|
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
|
|
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
|
|
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
|
|
#toc{border-bottom:1px solid #ddddd8!important;padding-bottom:0!important}
|
|
.sect1{padding-bottom:0!important}
|
|
.sect1+.sect1{border:0!important}
|
|
#header>h1:first-child{margin-top:1.25rem}
|
|
body.book #header{text-align:center}
|
|
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em 0}
|
|
body.book #header .details{border:0!important;display:block;padding:0!important}
|
|
body.book #header .details span:first-child{margin-left:0!important}
|
|
body.book #header .details br{display:block}
|
|
body.book #header .details br+span:before{content:none!important}
|
|
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
|
|
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
|
|
.listingblock code[data-lang]:before{display:block}
|
|
#footer{background:none!important;padding:0 .9375em}
|
|
#footer-text{color:rgba(0,0,0,.6)!important;font-size:.9em}
|
|
.hide-on-print{display:none!important}
|
|
.print-only{display:block!important}
|
|
.hide-for-print{display:none!important}
|
|
.show-for-print{display:inherit!important}}
|
|
</style>
|
|
</head>
|
|
<body class="book toc2 toc-left">
|
|
<div id="header">
|
|
<h1>Spring Cloud</h1>
|
|
<div id="toc" class="toc2">
|
|
<div id="toctitle">Table of Contents</div>
|
|
<ul class="sectlevel1">
|
|
<li><a href="#_features">Features</a></li>
|
|
<li><a href="#_cloud_native_applications">Cloud Native Applications</a>
|
|
<ul class="sectlevel1">
|
|
<li><a href="#_spring_cloud_context_application_context_services">Spring Cloud Context: Application Context Services</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_the_bootstrap_application_context">The Bootstrap Application Context</a></li>
|
|
<li><a href="#_application_context_hierarchies">Application Context Hierarchies</a></li>
|
|
<li><a href="#customizing-bootstrap-properties">Changing the Location of Bootstrap Properties</a></li>
|
|
<li><a href="#overriding-bootstrap-properties">Overriding the Values of Remote Properties</a></li>
|
|
<li><a href="#_customizing_the_bootstrap_configuration">Customizing the Bootstrap Configuration</a></li>
|
|
<li><a href="#customizing-bootstrap-property-sources">Customizing the Bootstrap Property Sources</a></li>
|
|
<li><a href="#_environment_changes">Environment Changes</a></li>
|
|
<li><a href="#_refresh_scope">Refresh Scope</a></li>
|
|
<li><a href="#_encryption_and_decryption">Encryption and Decryption</a></li>
|
|
<li><a href="#_endpoints">Endpoints</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_spring_cloud_commons_common_abstractions">Spring Cloud Commons: Common Abstractions</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_spring_resttemplate_as_a_load_balancer_client">Spring RestTemplate as a Load Balancer Client</a></li>
|
|
<li><a href="#_multiple_resttemplate_objects">Multiple RestTemplate objects</a></li>
|
|
<li><a href="#ignore-network-interfaces">Ignore Network Interfaces</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_spring_cloud_config">Spring Cloud Config</a>
|
|
<ul class="sectlevel1">
|
|
<li><a href="#_quick_start">Quick Start</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_client_side_usage">Client Side Usage</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_spring_cloud_config_server">Spring Cloud Config Server</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_environment_repository">Environment Repository</a></li>
|
|
<li><a href="#_health_indicator">Health Indicator</a></li>
|
|
<li><a href="#_security">Security</a></li>
|
|
<li><a href="#_encryption_and_decryption_2">Encryption and Decryption</a></li>
|
|
<li><a href="#_key_management">Key Management</a></li>
|
|
<li><a href="#_creating_a_key_store_for_testing">Creating a Key Store for Testing</a></li>
|
|
<li><a href="#_using_multiple_keys_and_key_rotation">Using Multiple Keys and Key Rotation</a></li>
|
|
<li><a href="#_serving_encrypted_properties">Serving Encrypted Properties</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_serving_alternative_formats">Serving Alternative Formats</a></li>
|
|
<li><a href="#_serving_plain_text">Serving Plain Text</a></li>
|
|
<li><a href="#_embedding_the_config_server">Embedding the Config Server</a></li>
|
|
<li><a href="#_push_notifications_and_spring_cloud_bus">Push Notifications and Spring Cloud Bus</a></li>
|
|
<li><a href="#_spring_cloud_config_client">Spring Cloud Config Client</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#config-first-bootstrap">Config First Bootstrap</a></li>
|
|
<li><a href="#discovery-first-bootstrap">Discovery First Bootstrap</a></li>
|
|
<li><a href="#config-client-fail-fast">Config Client Fail Fast</a></li>
|
|
<li><a href="#config-client-retry">Config Client Retry</a></li>
|
|
<li><a href="#_locating_remote_configuration_resources">Locating Remote Configuration Resources</a></li>
|
|
<li><a href="#_security_2">Security</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_spring_cloud_netflix">Spring Cloud Netflix</a>
|
|
<ul class="sectlevel1">
|
|
<li><a href="#_service_discovery_eureka_clients">Service Discovery: Eureka Clients</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_registering_with_eureka">Registering with Eureka</a></li>
|
|
<li><a href="#_authenticating_with_the_eureka_server">Authenticating with the Eureka Server</a></li>
|
|
<li><a href="#_status_page_and_health_indicator">Status Page and Health Indicator</a></li>
|
|
<li><a href="#_registering_a_secure_application">Registering a Secure Application</a></li>
|
|
<li><a href="#_eureka_s_health_checks">Eureka’s Health Checks</a></li>
|
|
<li><a href="#_eureka_metadata_for_instances_and_clients">Eureka Metadata for Instances and Clients</a></li>
|
|
<li><a href="#_using_the_eurekaclient">Using the EurekaClient</a></li>
|
|
<li><a href="#_alternatives_to_the_native_netflix_eurekaclient">Alternatives to the native Netflix EurekaClient</a></li>
|
|
<li><a href="#_why_is_it_so_slow_to_register_a_service">Why is it so Slow to Register a Service?</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#spring-cloud-eureka-server">Service Discovery: Eureka Server</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_high_availability_zones_and_regions">High Availability, Zones and Regions</a></li>
|
|
<li><a href="#_standalone_mode">Standalone Mode</a></li>
|
|
<li><a href="#_peer_awareness">Peer Awareness</a></li>
|
|
<li><a href="#_prefer_ip_address">Prefer IP Address</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_circuit_breaker_hystrix_clients">Circuit Breaker: Hystrix Clients</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_propagating_the_security_context_or_using_spring_scopes">Propagating the Security Context or using Spring Scopes</a></li>
|
|
<li><a href="#_health_indicator_2">Health Indicator</a></li>
|
|
<li><a href="#_hystrix_metrics_stream">Hystrix Metrics Stream</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_circuit_breaker_hystrix_dashboard">Circuit Breaker: Hystrix Dashboard</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_turbine">Turbine</a></li>
|
|
<li><a href="#_turbine_stream">Turbine Stream</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#spring-cloud-ribbon">Client Side Load Balancer: Ribbon</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_customizing_the_ribbon_client">Customizing the Ribbon Client</a></li>
|
|
<li><a href="#_using_ribbon_with_eureka">Using Ribbon with Eureka</a></li>
|
|
<li><a href="#spring-cloud-ribbon-without-eureka">Example: How to Use Ribbon Without Eureka</a></li>
|
|
<li><a href="#_example_disable_eureka_use_in_ribbon">Example: Disable Eureka use in Ribbon</a></li>
|
|
<li><a href="#_using_the_ribbon_api_directly">Using the Ribbon API Directly</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#spring-cloud-feign">Declarative REST Client: Feign</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#spring-cloud-feign-overriding-defaults">Overriding Feign Defaults</a></li>
|
|
<li><a href="#spring-cloud-feign-hystrix">Feign Hystrix Support</a></li>
|
|
<li><a href="#spring-cloud-feign-hystrix-fallback">Feign Hystrix Fallbacks</a></li>
|
|
<li><a href="#spring-cloud-feign-inheritance">Feign Inheritance Support</a></li>
|
|
<li><a href="#_feign_request_response_compression">Feign request/response compression</a></li>
|
|
<li><a href="#_feign_logging">Feign logging</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_external_configuration_archaius">External Configuration: Archaius</a></li>
|
|
<li><a href="#_router_and_filter_zuul">Router and Filter: Zuul</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#netflix-zuul-reverse-proxy">Embedded Zuul Reverse Proxy</a></li>
|
|
<li><a href="#_cookies_and_sensitive_headers">Cookies and Sensitive Headers</a></li>
|
|
<li><a href="#_the_routes_endpoint">The Routes Endpoint</a></li>
|
|
<li><a href="#_strangulation_patterns_and_local_forwards">Strangulation Patterns and Local Forwards</a></li>
|
|
<li><a href="#_uploading_files_through_zuul">Uploading Files through Zuul</a></li>
|
|
<li><a href="#_plain_embedded_zuul">Plain Embedded Zuul</a></li>
|
|
<li><a href="#_disable_zuul_filters">Disable Zuul Filters</a></li>
|
|
<li><a href="#_polyglot_support_with_sidecar">Polyglot support with Sidecar</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#netflix-rxjava-springmvc">RxJava with Spring MVC</a></li>
|
|
<li><a href="#netflix-metrics">Metrics: Spectator, Servo, and Atlas</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_dimensional_vs_hierarchical_metrics">Dimensional vs. Hierarchical Metrics</a></li>
|
|
<li><a href="#_default_metrics_collection">Default Metrics Collection</a></li>
|
|
<li><a href="#netflix-metrics-spectator">Metrics Collection: Spectator</a></li>
|
|
<li><a href="#netflix-metrics-servo">Metrics Collection: Servo</a></li>
|
|
<li><a href="#netflix-metrics-atlas">Metrics Backend: Atlas</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_spring_cloud_stream">Spring Cloud Stream</a>
|
|
<ul class="sectlevel1">
|
|
<li><a href="#_introducing_spring_cloud_stream">Introducing Spring Cloud Stream</a></li>
|
|
<li><a href="#_main_concepts">Main Concepts</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_application_model">Application Model</a></li>
|
|
<li><a href="#_the_binder_abstraction">The Binder Abstraction</a></li>
|
|
<li><a href="#_persistent_publish_subscribe_support">Persistent Publish-Subscribe Support</a></li>
|
|
<li><a href="#consumer-groups">Consumer Groups</a></li>
|
|
<li><a href="#partitioning">Partitioning Support</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_programming_model">Programming Model</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_declaring_and_binding_channels">Declaring and Binding Channels</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_binders">Binders</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_producers_and_consumers">Producers and Consumers</a></li>
|
|
<li><a href="#_binder_spi">Binder SPI</a></li>
|
|
<li><a href="#_binder_detection">Binder Detection</a></li>
|
|
<li><a href="#multiple-binders">Multiple Binders on the Classpath</a></li>
|
|
<li><a href="#multiple-systems">Connecting to Multiple Systems</a></li>
|
|
<li><a href="#_binder_configuration_properties">Binder configuration properties</a></li>
|
|
<li><a href="#_implementation_strategies">Implementation strategies</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_configuration_options">Configuration Options</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_spring_cloud_stream_properties">Spring Cloud Stream Properties</a></li>
|
|
<li><a href="#binding-properties">Binding Properties</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#binder-specific-configuration">Binder-Specific Configuration</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_rabbit_specific_settings">Rabbit-Specific Settings</a></li>
|
|
<li><a href="#_kafka_specific_settings">Kafka-Specific Settings</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#contenttypemanagement">Content Type and Transformation</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#mime-types">MIME types</a></li>
|
|
<li><a href="#mime-types-and-java-types">MIME types and Java types</a></li>
|
|
<li><a href="#__code_streamlistener_code_and_message_conversion"><code>`@StreamListener</code> and Message Conversion</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_inter_application_communication">Inter-Application Communication</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_connecting_multiple_application_instances">Connecting Multiple Application Instances</a></li>
|
|
<li><a href="#_instance_index_and_instance_count">Instance Index and Instance Count</a></li>
|
|
<li><a href="#_partitioning">Partitioning</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_testing">Testing</a></li>
|
|
<li><a href="#_health_indicator_3">Health Indicator</a></li>
|
|
<li><a href="#_samples">Samples</a></li>
|
|
<li><a href="#_getting_started">Getting Started</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_spring_cloud_bus">Spring Cloud Bus</a>
|
|
<ul class="sectlevel1">
|
|
<li><a href="#_quick_start_2">Quick Start</a></li>
|
|
<li><a href="#_addressing_an_instance">Addressing an Instance</a></li>
|
|
<li><a href="#_addressing_all_instances_of_a_service">Addressing all instances of a service</a></li>
|
|
<li><a href="#_application_context_id_must_be_unique">Application Context ID must be unique</a></li>
|
|
<li><a href="#_customizing_the_message_broker">Customizing the Message Broker</a></li>
|
|
<li><a href="#_tracing_bus_events">Tracing Bus Events</a></li>
|
|
<li><a href="#_broadcasting_your_own_events">Broadcasting Your Own Events</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_spring_cloud_sleuth">Spring Cloud Sleuth</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_terminology">Terminology</a></li>
|
|
<li><a href="#_purpose">Purpose</a></li>
|
|
<li><a href="#_adding_to_the_project">Adding to the project</a></li>
|
|
<li><a href="#_features_2">Features</a></li>
|
|
<li><a href="#_sampling">Sampling</a></li>
|
|
<li><a href="#_instrumentation">Instrumentation</a></li>
|
|
<li><a href="#_span_lifecycle">Span lifecycle</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#creating-and-closing-spans">Creating and closing spans</a></li>
|
|
<li><a href="#continuing-spans">Continuing spans</a></li>
|
|
<li><a href="#creating-spans-with-explicit-parent">Creating spans with an explicit parent</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_naming_spans">Naming spans</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#__spanname_annotation">@SpanName annotation</a></li>
|
|
<li><a href="#_tostring_method">toString() method</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_customizations">Customizations</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_spring_integration">Spring Integration</a></li>
|
|
<li><a href="#_http">HTTP</a></li>
|
|
<li><a href="#_example">Example</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_span_data_as_messages">Span Data as Messages</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_zipkin_consumer">Zipkin Consumer</a></li>
|
|
<li><a href="#_custom_consumer">Custom Consumer</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_metrics">Metrics</a></li>
|
|
<li><a href="#_integrations">Integrations</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_runnable_and_callable">Runnable and Callable</a></li>
|
|
<li><a href="#_hystrix">Hystrix</a></li>
|
|
<li><a href="#_rxjava">RxJava</a></li>
|
|
<li><a href="#_http_integration">HTTP integration</a></li>
|
|
<li><a href="#_http_client_integration">HTTP client integration</a></li>
|
|
<li><a href="#_feign">Feign</a></li>
|
|
<li><a href="#_asynchronous_communication">Asynchronous communication</a></li>
|
|
<li><a href="#_messaging">Messaging</a></li>
|
|
<li><a href="#_zuul">Zuul</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_running_examples">Running examples</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_spring_cloud_consul">Spring Cloud Consul</a>
|
|
<ul class="sectlevel1">
|
|
<li><a href="#spring-cloud-consul-install">Install Consul</a></li>
|
|
<li><a href="#spring-cloud-consul-agent">Consul Agent</a></li>
|
|
<li><a href="#spring-cloud-consul-discovery">Service Discovery with Consul</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_registering_with_consul">Registering with Consul</a></li>
|
|
<li><a href="#_http_health_check">HTTP Health Check</a></li>
|
|
<li><a href="#_using_the_discoveryclient">Using the DiscoveryClient</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#spring-cloud-consul-config">Distributed Configuration with Consul</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_how_to_activate">How to activate</a></li>
|
|
<li><a href="#_customizing">Customizing</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#spring-cloud-consul-config-format">YAML or Properties with Config</a></li>
|
|
<li><a href="#spring-cloud-consul-config-git2consul">git2consul with Config</a></li>
|
|
<li><a href="#spring-cloud-consul-failfast">Fail Fast</a></li>
|
|
<li><a href="#spring-cloud-consul-retry">Consul Retry</a></li>
|
|
<li><a href="#spring-cloud-consul-bus">Spring Cloud Bus with Consul</a></li>
|
|
<li><a href="#spring-cloud-consul-hystrix">Circuit Breaker with Hystrix</a></li>
|
|
<li><a href="#spring-cloud-consul-turbine">Hystrix metrics aggregation with Turbine and Consul</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_spring_cloud_zookeeper">Spring Cloud Zookeeper</a>
|
|
<ul class="sectlevel1">
|
|
<li><a href="#spring-cloud-zookeeper-install">Install Zookeeper</a></li>
|
|
<li><a href="#spring-cloud-zookeeper-discovery">Service Discovery with Zookeeper</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_how_to_activate_2">How to activate</a></li>
|
|
<li><a href="#_registering_with_zookeeper">Registering with Zookeeper</a></li>
|
|
<li><a href="#_using_the_discoveryclient_2">Using the DiscoveryClient</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#spring-cloud-zookeeper-dependencies">Zookeeper Dependencies</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_using_the_zookeeper_dependencies">Using the Zookeeper Dependencies</a></li>
|
|
<li><a href="#_how_to_activate_zookeeper_dependencies">How to activate Zookeeper Dependencies</a></li>
|
|
<li><a href="#_setting_up_zookeeper_dependencies">Setting up Zookeeper Dependencies</a></li>
|
|
<li><a href="#_configuring_spring_cloud_zookeeper_dependencies">Configuring Spring Cloud Zookeeper Dependencies</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#spring-cloud-zookeeper-dependency-watcher">Spring Cloud Zookeeper Dependency Watcher</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_how_to_activate_3">How to activate</a></li>
|
|
<li><a href="#_registering_a_listener">Registering a listener</a></li>
|
|
<li><a href="#_presence_checker">Presence Checker</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#spring-cloud-zookeeper-config">Distributed Configuration with Zookeeper</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_how_to_activate_4">How to activate</a></li>
|
|
<li><a href="#_customizing_2">Customizing</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_spring_boot_cloud_cli">Spring Boot Cloud CLI</a>
|
|
<ul class="sectlevel1">
|
|
<li><a href="#_installation">Installation</a></li>
|
|
<li><a href="#_writing_groovy_scripts_and_running_applications">Writing Groovy Scripts and Running Applications</a></li>
|
|
<li><a href="#_encryption_and_decryption_3">Encryption and Decryption</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_spring_cloud_security">Spring Cloud Security</a>
|
|
<ul class="sectlevel1">
|
|
<li><a href="#_quickstart">Quickstart</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_oauth2_single_sign_on">OAuth2 Single Sign On</a></li>
|
|
<li><a href="#_oauth2_protected_resource">OAuth2 Protected Resource</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_more_detail">More Detail</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_single_sign_on">Single Sign On</a></li>
|
|
<li><a href="#_token_relay">Token Relay</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_configuring_authentication_downstream_of_a_zuul_proxy">Configuring Authentication Downstream of a Zuul Proxy</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_spring_cloud_for_cloud_foundry">Spring Cloud for Cloud Foundry</a>
|
|
<ul class="sectlevel1">
|
|
<li><a href="#_discovery">Discovery</a></li>
|
|
<li><a href="#_single_sign_on_2">Single Sign On</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_spring_cloud_cluster">Spring Cloud Cluster</a>
|
|
<ul class="sectlevel1">
|
|
<li><a href="#_leader_election">Leader Election</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#spring-cloud-cluster-leaderelection-zookeeper">Zookeeper</a></li>
|
|
<li><a href="#spring-cloud-cluster-leaderelection-hazelcast">Hazelcast</a></li>
|
|
<li><a href="#spring-cloud-cluster-leaderelection-etcd">Etcd</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_appendix_compendium_of_configuration_properties">Appendix: Compendium of Configuration Properties</a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div id="content">
|
|
<div id="preamble">
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Spring Cloud provides tools for developers to quickly build some of
|
|
the common patterns in distributed systems (e.g. configuration
|
|
management, service discovery, circuit breakers, intelligent routing,
|
|
micro-proxy, control bus, one-time tokens, global locks, leadership
|
|
election, distributed sessions, cluster state). Coordination of
|
|
distributed systems leads to boiler plate patterns, and using Spring
|
|
Cloud developers can quickly stand up services and applications that
|
|
implement those patterns. They will work well in any distributed
|
|
environment, including the developer’s own laptop, bare metal data
|
|
centres, and managed platforms such as Cloud Foundry.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Version: Brixton.BUILD-SNAPSHOT</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_features">Features</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Spring Cloud focuses on providing good out of box experience for typical use cases
|
|
and extensibility mechanism to cover others.</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>Distributed/versioned configuration</p>
|
|
</li>
|
|
<li>
|
|
<p>Service registration and discovery</p>
|
|
</li>
|
|
<li>
|
|
<p>Routing</p>
|
|
</li>
|
|
<li>
|
|
<p>Service-to-service calls</p>
|
|
</li>
|
|
<li>
|
|
<p>Load balancing</p>
|
|
</li>
|
|
<li>
|
|
<p>Circuit Breakers</p>
|
|
</li>
|
|
<li>
|
|
<p>Global locks</p>
|
|
</li>
|
|
<li>
|
|
<p>Leadership election and cluster state</p>
|
|
</li>
|
|
<li>
|
|
<p>Distributed messaging</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<h1 id="_cloud_native_applications" class="sect0">Cloud Native Applications</h1>
|
|
<div class="openblock partintro">
|
|
<div class="content">
|
|
<div class="paragraph">
|
|
<p><a href="http://pivotal.io/platform-as-a-service/migrating-to-cloud-native-application-architectures-ebook">Cloud Native</a> is a style of application development that encourages easy adoption of best practices in the areas of continuous delivery and value-driven development. A related discipline is that of building <a href="http://12factor.net/">12-factor Apps</a> in which development practices are aligned with delivery and operations goals, for instance by using declarative programming and management and monitoring. Spring Cloud facilitates these styles of development in a number of specific ways and the starting point is a set of features that all components in a distributed system either need or need easy access to when required.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Many of those features are covered by <a href="http://projects.spring.io/spring-boot">Spring Boot</a>, which we build on in Spring Cloud. Some more are delivered by Spring Cloud as two libraries: Spring Cloud Context and Spring Cloud Commons. Spring Cloud Context provides utilities and special services for the <code>ApplicationContext</code> of a Spring Cloud application (bootstrap context, encryption, refresh scope and environment endpoints). Spring Cloud Commons is a set of abstractions and common classes used in different Spring Cloud implementations (eg. Spring Cloud Netflix vs. Spring Cloud Consul).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you are getting an exception due to "Illegal key size" and you are using Sun’s JDK, you need to install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. See the following links for more information:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><a href="http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html">Java 6 JCE</a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html">Java 7 JCE</a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html">Java 8 JCE</a></p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Extract files into JDK/jre/lib/security folder (whichever version of JRE/JDK x64/x86 you are using).</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
Spring Cloud is released under the non-restrictive Apache 2.0 license. If you would like to contribute to this section of the documentation or if you find an error, please find the source code and issue trackers in the project at <a href="https://github.com/spring-cloud/spring-cloud-commons/tree/master/docs/src/main/asciidoc">github</a>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_spring_cloud_context_application_context_services">Spring Cloud Context: Application Context Services</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Spring Boot has an opinionated view of how to build an application
|
|
with Spring: for instance it has conventional locations for common
|
|
configuration file, and endpoints for common management and monitoring
|
|
tasks. Spring Cloud builds on top of that and adds a few features that
|
|
probably all components in a system would use or occasionally need.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_the_bootstrap_application_context">The Bootstrap Application Context</h3>
|
|
<div class="paragraph">
|
|
<p>A Spring Cloud application operates by creating a "bootstrap"
|
|
context, which is a parent context for the main application. Out of
|
|
the box it is responsible for loading configuration properties from
|
|
the external sources, and also decrypting properties in the local
|
|
external configuration files. The two contexts share an <code>Environment</code>
|
|
which is the source of external properties for any Spring
|
|
application. Bootstrap properties are added with high precedence, so
|
|
they cannot be overridden by local configuration, by default.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The bootstrap context uses a different convention for locating
|
|
external configuration than the main application context, so instead
|
|
of <code>application.yml</code> (or <code>.properties</code>) you use <code>bootstrap.yml</code>,
|
|
keeping the external configuration for bootstrap and main context
|
|
nicely separate. Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">bootstrap.yml</div>
|
|
<div class="content">
|
|
<pre>spring:
|
|
application:
|
|
name: foo
|
|
cloud:
|
|
config:
|
|
uri: ${SPRING_CONFIG_URI:http://localhost:8888}</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>It is a good idea to set the <code>spring.application.name</code> (in
|
|
<code>bootstrap.yml</code> or <code>application.yml</code>) if your application needs any
|
|
application-specific configuration from the server.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can disable the bootstrap process completely by setting
|
|
<code>spring.cloud.bootstrap.enabled=false</code> (e.g. in System properties).</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_application_context_hierarchies">Application Context Hierarchies</h3>
|
|
<div class="paragraph">
|
|
<p>If you build an application context from <code>SpringApplication</code> or
|
|
<code>SpringApplicationBuilder</code>, then the Bootstrap context is added as a
|
|
parent to that context. It is a feature of Spring that child contexts
|
|
inherit property sources and profiles from their parent, so the "main"
|
|
application context will contain additional property sources, compared
|
|
to building the same context without Spring Cloud Config. The
|
|
additional property sources are:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>"bootstrap": an optional <code>CompositePropertySource</code> appears with high
|
|
priority if any <code>PropertySourceLocators</code> are found in the Bootstrap
|
|
context, and they have non-empty properties. An example would be
|
|
properties from the Spring Cloud Config Server. See
|
|
<a href="#customizing-bootstrap-property-sources">below</a> for instructions
|
|
on how to customize the contents of this property source.</p>
|
|
</li>
|
|
<li>
|
|
<p>"applicationConfig: [classpath:bootstrap.yml]" (and friends if
|
|
Spring profiles are active). If you have a <code>bootstrap.yml</code> (or
|
|
properties) then those properties are used to configure the Bootstrap
|
|
context, and then they get added to the child context when its parent
|
|
is set. They have lower precedence than the <code>application.yml</code> (or
|
|
properties) and any other property sources that are added to the child
|
|
as a normal part of the process of creating a Spring Boot
|
|
application. See <a href="#customizing-bootstrap-properties">below</a> for
|
|
instructions on how to customize the contents of these property
|
|
sources.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Because of the ordering rules of property sources the "bootstrap"
|
|
entries take precedence, but note that these do not contain any data
|
|
from <code>bootstrap.yml</code>, which has very low precedence, but can be used
|
|
to set defaults.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can extend the context hierarchy by simply setting the parent
|
|
context of any <code>ApplicationContext</code> you create, e.g. using its own
|
|
interface, or with the <code>SpringApplicationBuilder</code> convenience methods
|
|
(<code>parent()</code>, <code>child()</code> and <code>sibling()</code>). The bootstrap context will be
|
|
the parent of the most senior ancestor that you create yourself.
|
|
Every context in the hierarchy will have its own "bootstrap" property
|
|
source (possibly empty) to avoid promoting values inadvertently from
|
|
parents down to their descendants. Every context in the hierarchy can
|
|
also (in principle) have a different <code>spring.application.name</code> and
|
|
hence a different remote property source if there is a Config
|
|
Server. Normal Spring application context behaviour rules apply to
|
|
property resolution: properties from a child context override those in
|
|
the parent, by name and also by property source name (if the child has
|
|
a property source with the same name as the parent, the one from the
|
|
parent is not included in the child).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Note that the <code>SpringApplicationBuilder</code> allows you to share an
|
|
<code>Environment</code> amongst the whole hierarchy, but that is not the
|
|
default. Thus, sibling contexts in particular do not need to have the
|
|
same profiles or property sources, even though they will share common
|
|
things with their parent.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="customizing-bootstrap-properties">Changing the Location of Bootstrap Properties</h3>
|
|
<div class="paragraph">
|
|
<p>The <code>bootstrap.yml</code> (or <code>.properties</code>) location can be specified using
|
|
<code>spring.cloud.bootstrap.name</code> (default "bootstrap") or
|
|
<code>spring.cloud.bootstrap.location</code> (default empty), e.g. in System
|
|
properties. Those properties behave like the <code>spring.config.*</code>
|
|
variants with the same name, in fact they are used to set up the
|
|
bootstrap <code>ApplicationContext</code> by setting those properties in its
|
|
<code>Environment</code>. If there is an active profile (from
|
|
<code>spring.profiles.active</code> or through the <code>Environment</code> API in the
|
|
context you are building) then properties in that profile will be
|
|
loaded as well, just like in a regular Spring Boot app, e.g. from
|
|
<code>bootstrap-development.properties</code> for a "development" profile.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="overriding-bootstrap-properties">Overriding the Values of Remote Properties</h3>
|
|
<div class="paragraph">
|
|
<p>The property sources that are added to you application by the
|
|
bootstrap context are often "remote" (e.g. from a Config Server), and
|
|
by default they cannot be overridden locally, except on the command
|
|
line. If you want to allow your applications to override the remote
|
|
properties with their own System properties or config files, the
|
|
remote property source has to grant it permission by setting
|
|
<code>spring.cloud.config.allowOverride=true</code> (it doesn’t work to set this
|
|
locally). Once that flag is set there are some finer grained settings
|
|
to control the location of the remote properties in relation to System
|
|
properties and the application’s local configuration:
|
|
<code>spring.cloud.config.overrideNone=true</code> to override with any local
|
|
property source, and
|
|
<code>spring.cloud.config.overrideSystemProperties=false</code> if only System
|
|
properties and env vars should override the remote settings, but not
|
|
the local config files.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_customizing_the_bootstrap_configuration">Customizing the Bootstrap Configuration</h3>
|
|
<div class="paragraph">
|
|
<p>The bootstrap context can be trained to do anything you like by adding
|
|
entries to <code>/META-INF/spring.factories</code> under the key
|
|
<code>org.springframework.cloud.bootstrap.BootstrapConfiguration</code>. This is
|
|
a comma-separated list of Spring <code>@Configuration</code> classes which will
|
|
be used to create the context. Any beans that you want to be available
|
|
to the main application context for autowiring can be created here,
|
|
and also there is a special contract for <code>@Beans</code> of type
|
|
<code>ApplicationContextInitializer</code>. Classes can be marked with an <code>@Order</code>
|
|
if you want to control the startup sequence (the default order is
|
|
"last").</p>
|
|
</div>
|
|
<div class="admonitionblock warning">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Warning</div>
|
|
</td>
|
|
<td class="content">
|
|
Be careful when adding custom <code>BootstrapConfiguration</code> that the
|
|
classes you add are not <code>@ComponentScanned</code> by mistake into your
|
|
"main" application context, where they might not be needed.
|
|
Use a separate package name for boot configuration classes that is
|
|
not already covered by your <code>@ComponentScan</code> or <code>@SpringBootApplication</code>
|
|
annotated configuration classes.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The bootstrap process ends by injecting initializers into the main
|
|
<code>SpringApplication</code> instance (i.e. the normal Spring Boot startup
|
|
sequence, whether it is running as a standalone app or deployed in an
|
|
application server). First a bootstrap context is created from the
|
|
classes found in <code>spring.factories</code> and then all <code>@Beans</code> of type
|
|
<code>ApplicationContextInitializer</code> are added to the main
|
|
<code>SpringApplication</code> before it is started.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="customizing-bootstrap-property-sources">Customizing the Bootstrap Property Sources</h3>
|
|
<div class="paragraph">
|
|
<p>The default property source for external configuration added by the
|
|
bootstrap process is the Config Server, but you can add additional
|
|
sources by adding beans of type <code>PropertySourceLocator</code> to the
|
|
bootstrap context (via <code>spring.factories</code>). You could use this to
|
|
insert additional properties from a different server, or from a
|
|
database, for instance.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>As an example, consider the following trivial custom locator:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Configuration
|
|
public class CustomPropertySourceLocator implements PropertySourceLocator {
|
|
|
|
@Override
|
|
public PropertySource<?> locate(Environment environment) {
|
|
return new MapPropertySource("customProperty",
|
|
Collections.<String, Object>singletonMap("property.from.sample.custom.source", "worked as intended"));
|
|
}
|
|
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>Environment</code> that is passed in is the one for the
|
|
<code>ApplicationContext</code> about to be created, i.e. the one that we are
|
|
supplying additional property sources for. It will already have its
|
|
normal Spring Boot-provided property sources, so you can use those to
|
|
locate a property source specific to this <code>Environment</code> (e.g. by
|
|
keying it on the <code>spring.application.name</code>, as is done in the default
|
|
Config Server property source locator).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you create a jar with this class in it and then add a
|
|
<code>META-INF/spring.factories</code> containing:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>org.springframework.cloud.bootstrap.BootstrapConfiguration=sample.custom.CustomPropertySourceLocator</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>then the "customProperty" <code>PropertySource</code> will show up in any
|
|
application that includes that jar on its classpath.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_environment_changes">Environment Changes</h3>
|
|
<div class="paragraph">
|
|
<p>The application will listen for an <code>EnvironmentChangedEvent</code> and react
|
|
to the change in a couple of standard ways (additional
|
|
<code>ApplicationListeners</code> can be added as <code>@Beans</code> by the user in the
|
|
normal way). When an <code>EnvironmentChangedEvent</code> is observed it will
|
|
have a list of key values that have changed, and the application will
|
|
use those to:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>Re-bind any <code>@ConfigurationProperties</code> beans in the context</p>
|
|
</li>
|
|
<li>
|
|
<p>Set the logger levels for any properties in <code>logging.level.*</code></p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Note that the Config Client does not by default poll for changes in
|
|
the <code>Environment</code>, and generally we would not recommend that approach
|
|
for detecting changes (although you could set it up with a
|
|
<code>@Scheduled</code> annotation). If you have a scaled-out client application
|
|
then it is better to broadcast the <code>EnvironmentChangedEvent</code> to all
|
|
the instances instead of having them polling for changes (e.g. using
|
|
the <a href="https://github.com/spring-cloud/spring-cloud-bus">Spring Cloud
|
|
Bus</a>).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>EnvironmentChangedEvent</code> covers a large class of refresh use
|
|
cases, as long as you can actually make a change to the <code>Environment</code>
|
|
and publish the event (those APIs are public and part of core
|
|
Spring). You can verify the changes are bound to
|
|
<code>@ConfigurationProperties</code> beans by visiting the <code>/configprops</code>
|
|
endpoint (normal Spring Boot Actuator feature). For instance a
|
|
<code>DataSource</code> can have its <code>maxPoolSize</code> changed at runtime (the
|
|
default <code>DataSource</code> created by Spring Boot is an
|
|
<code>@ConfigurationProperties</code> bean) and grow capacity
|
|
dynamically. Re-binding <code>@ConfigurationProperties</code> does not cover
|
|
another large class of use cases, where you need more control over the
|
|
refresh, and where you need a change to be atomic over the whole
|
|
<code>ApplicationContext</code>. To address those concerns we have
|
|
<code>@RefreshScope</code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_refresh_scope">Refresh Scope</h3>
|
|
<div class="paragraph">
|
|
<p>A Spring <code>@Bean</code> that is marked as <code>@RefreshScope</code> will get special
|
|
treatment when there is a configuration change. This addresses the
|
|
problem of stateful beans that only get their configuration injected
|
|
when they are initialized. For instance if a <code>DataSource</code> has open
|
|
connections when the database URL is changed via the <code>Environment</code>, we
|
|
probably want the holders of those connections to be able to complete
|
|
what they are doing. Then the next time someone borrows a connection
|
|
from the pool he gets one with the new URL.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Refresh scope beans are lazy proxies that initialize when they are
|
|
used (i.e. when a method is called), and the scope acts as a cache of
|
|
initialized values. To force a bean to re-initialize on the next
|
|
method call you just need to invalidate its cache entry.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>RefreshScope</code> is a bean in the context and it has a public method
|
|
<code>refreshAll()</code> to refresh all beans in the scope by clearing the
|
|
target cache. There is also a <code>refresh(String)</code> method to refresh an
|
|
individual bean by name. This functionality is exposed in the
|
|
<code>/refresh</code> endpoint (over HTTP or JMX).</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
<code>@RefreshScope</code> works (technically) on an <code>@Configuration</code>
|
|
class, but it might lead to surprising behaviour: e.g. it does <strong>not</strong>
|
|
mean that all the <code>@Beans</code> defined in that class are themselves
|
|
<code>@RefreshScope</code>. Specifically, anything that depends on those beans
|
|
cannot rely on them being updated when a refresh is initiated, unless
|
|
it is itself in <code>@RefreshScope</code> (in which it will be rebuilt on a
|
|
refresh and its dependencies re-injected, at which point they will be
|
|
re-initialized from the refreshed <code>@Configuration</code>).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_encryption_and_decryption">Encryption and Decryption</h3>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud has an <code>Environment</code> pre-processor for decrypting
|
|
property values locally. It follows the same rules as the Config
|
|
Server, and has the same external configuration via <code>encrypt.*</code>. Thus
|
|
you can use encrypted values in the form <code>{cipher}*</code> and as long as
|
|
there is a valid key then they will be decrypted before the main
|
|
application context gets the <code>Environment</code>. To use the encryption
|
|
features in an application you need to include Spring Security RSA in
|
|
your classpath (Maven co-ordinates
|
|
"org.springframework.security:spring-security-rsa") and you also need
|
|
the full strength JCE extensions in your JVM.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you are getting an exception due to "Illegal key size" and you are using Sun’s JDK, you need to install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. See the following links for more information:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><a href="http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html">Java 6 JCE</a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html">Java 7 JCE</a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html">Java 8 JCE</a></p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Extract files into JDK/jre/lib/security folder (whichever version of JRE/JDK x64/x86 you are using).</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_endpoints">Endpoints</h3>
|
|
<div class="paragraph">
|
|
<p>For a Spring Boot Actuator application there are some additional management endpoints:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>POST to <code>/env</code> to update the <code>Environment</code> and rebind <code>@ConfigurationProperties</code> and log levels</p>
|
|
</li>
|
|
<li>
|
|
<p><code>/refresh</code> for re-loading the boot strap context and refreshing the <code>@RefreshScope</code> beans</p>
|
|
</li>
|
|
<li>
|
|
<p><code>/restart</code> for closing the <code>ApplicationContext</code> and restarting it (disabled by default)</p>
|
|
</li>
|
|
<li>
|
|
<p><code>/pause</code> and <code>/resume</code> for calling the <code>Lifecycle</code> methods (<code>stop()</code> and <code>start()</code> on the <code>ApplicationContext</code>)</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_spring_cloud_commons_common_abstractions">Spring Cloud Commons: Common Abstractions</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Patterns such as service discovery, load balancing and circuit breakers lend themselves to a common abstraction layer that can be consumed by all Spring Cloud clients, independent of the implementation (e.g. discovery via Eureka or Consul).</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_spring_resttemplate_as_a_load_balancer_client">Spring RestTemplate as a Load Balancer Client</h3>
|
|
<div class="paragraph">
|
|
<p><code>RestTemplate</code> can be automatically configured to use ribbon. To create a load balanced <code>RestTemplate</code> create a <code>RestTemplate</code> <code>@Bean</code> and use the <code>@LoadBalanced</code> qualifier.</p>
|
|
</div>
|
|
<div class="admonitionblock warning">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Warning</div>
|
|
</td>
|
|
<td class="content">
|
|
A <code>RestTemplate</code> bean is no longer created via auto configuration. It must be created by individual applications.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Configuration
|
|
public class MyConfiguration {
|
|
|
|
@LoadBalanced
|
|
@Bean
|
|
RestTemplate restTemplate() {
|
|
return new RestTemplate();
|
|
}
|
|
}
|
|
|
|
public class MyClass {
|
|
@Autowired
|
|
private RestTemplate restTemplate;
|
|
|
|
public String doOtherStuff() {
|
|
String results = restTemplate.getForObject("http://stores/stores", String.class);
|
|
return results;
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The URI needs to use a virtual host name (ie. service name, not a host name).
|
|
The Ribbon client is used to create a full physical address. See
|
|
<a href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/ribbon/RibbonAutoConfiguration.java">RibbonAutoConfiguration</a>
|
|
for details of how the <code>RestTemplate</code> is set up.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_multiple_resttemplate_objects">Multiple RestTemplate objects</h3>
|
|
<div class="paragraph">
|
|
<p>If you want a <code>RestTemplate</code> that is not load balanced, create a <code>RestTemplate</code>
|
|
bean and inject it as normal. To access the load balanced <code>RestTemplate use
|
|
the `@LoadBalanced</code> qualifier when you create your <code>@Bean</code>.</p>
|
|
</div>
|
|
<div class="admonitionblock important">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Important</div>
|
|
</td>
|
|
<td class="content">
|
|
Notice the <code>@Primary</code> annotation on the plain <code>RestTemplate</code> declaration in the example below, to disambiguate the unqualified <code>@Autowired</code> injection.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Configuration
|
|
public class MyConfiguration {
|
|
|
|
@LoadBalanced
|
|
@Bean
|
|
RestTemplate loadBalanced() {
|
|
return new RestTemplate();
|
|
}
|
|
|
|
@Primary
|
|
@Bean
|
|
RestTemplate restTemplate() {
|
|
return new RestTemplate();
|
|
}
|
|
}
|
|
|
|
public class MyClass {
|
|
@Autowired
|
|
private RestTemplate restTemplate;
|
|
|
|
@Autowired
|
|
@LoadBalanced
|
|
private RestTemplate loadBalanced;
|
|
|
|
public String doOtherStuff() {
|
|
return loadBalanced.getForObject("http://stores/stores", String.class);
|
|
}
|
|
|
|
public String doStuff() {
|
|
return restTemplate.getForObject("http://example.com", String.class);
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Tip</div>
|
|
</td>
|
|
<td class="content">
|
|
If you see errors like <code>java.lang.IllegalArgumentException: Can not set org.springframework.web.client.RestTemplate field com.my.app.Foo.restTemplate to com.sun.proxy.$Proxy89</code> try injecting <code>RestOperations</code> instead or setting <code>spring.aop.proxyTargetClass=true</code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="ignore-network-interfaces">Ignore Network Interfaces</h3>
|
|
<div class="paragraph">
|
|
<p>Sometimes it is useful to ignore certain named network interfaces so they can be excluded from Service Discovery registration (eg. running in a Docker container). A list of regular expressions can be set that will cause the desired network interfaces to be ignored. The following configuration will ignore the "docker0" interface and all interfaces that start with "veth".</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>spring:
|
|
cloud:
|
|
inetutils:
|
|
ignoredInterfaces:
|
|
- docker0
|
|
- veth.*</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<h1 id="_spring_cloud_config" class="sect0">Spring Cloud Config</h1>
|
|
<div class="openblock partintro">
|
|
<div class="content">
|
|
Spring Cloud Config provides server and client-side support for externalized configuration in a distributed system. With the Config Server you have a central place to manage external properties for applications across all environments. The concepts on both client and server map identically to the Spring <code>Environment</code> and <code>PropertySource</code> abstractions, so they fit very well with Spring applications, but can be used with any application running in any language. As an application moves through the deployment pipeline from dev to test and into production you can manage the configuration between those environments and be certain that applications have everything they need to run when they migrate. The default implementation of the server storage backend uses git so it easily supports labelled versions of configuration environments, as well as being accessible to a wide range of tooling for managing the content. It is easy to add alternative implementations and plug them in with Spring configuration.
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_quick_start">Quick Start</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Start the server:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>$ cd spring-cloud-config-server
|
|
$ mvn spring-boot:run</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The server is a Spring Boot application so you can run it from your
|
|
IDE instead if you prefer (the main class is
|
|
<code>ConfigServerApplication</code>). Then try out a client:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>$ curl localhost:8888/foo/development
|
|
{"name":"development","label":"master","propertySources":[
|
|
{"name":"https://github.com/scratches/config-repo/foo-development.properties","source":{"bar":"spam"}},
|
|
{"name":"https://github.com/scratches/config-repo/foo.properties","source":{"foo":"bar"}}
|
|
]}</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The default strategy for locating property sources is to clone a git
|
|
repository (at <code>spring.cloud.config.server.git.uri</code>) and use it to
|
|
initialize a mini <code>SpringApplication</code>. The mini-application’s
|
|
<code>Environment</code> is used to enumerate property sources and publish them
|
|
via a JSON endpoint.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The HTTP service has resources in the form:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>/{application}/{profile}[/{label}]
|
|
/{application}-{profile}.yml
|
|
/{label}/{application}-{profile}.yml
|
|
/{application}-{profile}.properties
|
|
/{label}/{application}-{profile}.properties</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>where the "application" is injected as the <code>spring.config.name</code> in the
|
|
<code>SpringApplication</code> (i.e. what is normally "application" in a regular
|
|
Spring Boot app), "profile" is an active profile (or comma-separated
|
|
list of properties), and "label" is an optional git label (defaults to
|
|
"master".)</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Config Server pulls configuration for remote clients
|
|
from a git repository (which must be provided):</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
cloud:
|
|
config:
|
|
server:
|
|
git:
|
|
uri: https://github.com/spring-cloud-samples/config-repo</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_client_side_usage">Client Side Usage</h3>
|
|
<div class="paragraph">
|
|
<p>To use these features in an application, just build it as a Spring
|
|
Boot application that depends on spring-cloud-config-client (e.g. see
|
|
the test cases for the config-client, or the sample app). The most
|
|
convenient way to add the dependency is via a Spring Boot starter
|
|
<code>org.springframework.cloud:spring-cloud-starter-config</code>. There is also a
|
|
parent pom and BOM (<code>spring-cloud-starter-parent</code>) for Maven users and a
|
|
Spring IO version management properties file for Gradle and Spring CLI
|
|
users. Example Maven configuration:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">pom.xml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-xml" data-lang="xml"><parent>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-starter-parent</artifactId>
|
|
<version>1.3.5.RELEASE</version>
|
|
<relativePath /> <!-- lookup parent from repository -->
|
|
</parent>
|
|
|
|
<dependencyManagement>
|
|
<dependencies>
|
|
<dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-dependencies</artifactId>
|
|
<version>Brixton.RELEASE</version>
|
|
<type>pom</type>
|
|
<scope>import</scope>
|
|
</dependency>
|
|
</dependencies>
|
|
</dependencyManagement>
|
|
|
|
<dependencies>
|
|
<dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-starter-config</artifactId>
|
|
</dependency>
|
|
<dependency>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-starter-test</artifactId>
|
|
<scope>test</scope>
|
|
</dependency>
|
|
</dependencies>
|
|
|
|
<build>
|
|
<plugins>
|
|
<plugin>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-maven-plugin</artifactId>
|
|
</plugin>
|
|
</plugins>
|
|
</build>
|
|
|
|
<!-- repositories also needed for snapshots and milestones --></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Then you can create a standard Spring Boot application, like this simple HTTP server:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>@SpringBootApplication
|
|
@RestController
|
|
public class Application {
|
|
|
|
@RequestMapping("/")
|
|
public String home() {
|
|
return "Hello World!";
|
|
}
|
|
|
|
public static void main(String[] args) {
|
|
SpringApplication.run(Application.class, args);
|
|
}
|
|
|
|
}</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>When it runs it will pick up the external configuration from the
|
|
default local config server on port 8888 if it is running. To modify
|
|
the startup behaviour you can change the location of the config server
|
|
using <code>bootstrap.properties</code> (like <code>application.properties</code> but for
|
|
the bootstrap phase of an application context), e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>spring.cloud.config.uri: http://myconfigserver.com</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The bootstrap properties will show up in the <code>/env</code> endpoint as a
|
|
high-priority property source, e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>$ curl localhost:8080/env
|
|
{
|
|
"profiles":[],
|
|
"configService:https://github.com/spring-cloud-samples/config-repo/bar.properties":{"foo":"bar"},
|
|
"servletContextInitParams":{},
|
|
"systemProperties":{...},
|
|
...
|
|
}</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>(a property source called "configService:<URL of remote
|
|
repository>/<file name>" contains the property "foo" with value
|
|
"bar" and is highest priority).</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
the URL in the property source name is the git repository not
|
|
the config server URL.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_spring_cloud_config_server">Spring Cloud Config Server</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>The Server provides an HTTP, resource-based API for external
|
|
configuration (name-value pairs, or equivalent YAML content). The
|
|
server is easily embeddable in a Spring Boot application using the
|
|
<code>@EnableConfigServer</code> annotation. So this app is a config server:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">ConfigServer.java</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@SpringBootApplication
|
|
@EnableConfigServer
|
|
public class ConfigServer {
|
|
public static void main(String[] args) {
|
|
SpringApplication.run(ConfigServer.class, args);
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Like all Spring Boot apps it runs on port 8080 by default, but you
|
|
can switch it to the conventional port 8888 in various ways. The
|
|
easiest, which also sets a default configuration repository,
|
|
is by launching it with <code>spring.config.name=configserver</code> (there
|
|
is a <code>configserver.yml</code> in the Config Server jar). Another is
|
|
to use your own <code>application.properties</code>, e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.properties</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-properties" data-lang="properties">server.port: 8888
|
|
spring.cloud.config.server.git.uri: file://${user.home}/config-repo</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>where <code>${user.home}/config-repo</code> is a git repository containing
|
|
YAML and properties files.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
in Windows you need an extra "/" in the file URL if it is
|
|
absolute with a drive prefix, e.g. <code><a href="file:///${user.home}/config-repo" class="bare">file:///${user.home}/config-repo</a></code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Tip</div>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>Here’s a recipe for creating the git repository in the example
|
|
above:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>$ cd $HOME
|
|
$ mkdir config-repo
|
|
$ cd config-repo
|
|
$ git init .
|
|
$ echo info.foo: bar > application.properties
|
|
$ git add -A .
|
|
$ git commit -m "Add application.properties"</pre>
|
|
</div>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="admonitionblock warning">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Warning</div>
|
|
</td>
|
|
<td class="content">
|
|
using the local filesystem for your git repository is
|
|
intended for testing only. Use a server to host your
|
|
configuration repositories in production.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="admonitionblock warning">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Warning</div>
|
|
</td>
|
|
<td class="content">
|
|
the initial clone of your configuration repository will
|
|
be quick and efficient if you only keep text files in it. If you start
|
|
to store binary files, especially large ones, you may experience
|
|
delays on the first request for configuration and/or out of memory
|
|
errors in the server.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_environment_repository">Environment Repository</h3>
|
|
<div class="paragraph">
|
|
<p>Where do you want to store the configuration data for the Config
|
|
Server? The strategy that governs this behaviour is the
|
|
<code>EnvironmentRepository</code>, serving <code>Environment</code> objects. This
|
|
<code>Environment</code> is a shallow copy of the domain from the Spring
|
|
<code>Environment</code> (including <code>propertySources</code> as the main feature). The
|
|
<code>Environment</code> resources are parametrized by three variables:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><code>{application}</code> maps to "spring.application.name" on the client side;</p>
|
|
</li>
|
|
<li>
|
|
<p><code>{profile}</code> maps to "spring.profiles.active" on the client (comma separated list); and</p>
|
|
</li>
|
|
<li>
|
|
<p><code>{label}</code> which is a server side feature labelling a "versioned" set of config files.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Repository implementations generally behave just like a Spring Boot
|
|
application loading configuration files from a "spring.config.name"
|
|
equal to the <code>{application}</code> parameter, and "spring.profiles.active"
|
|
equal to the <code>{profiles}</code> parameter. Precedence rules for profiles are
|
|
also the same as in a regular Boot application: active profiles take
|
|
precedence over defaults, and if there are multiple profiles the last
|
|
one wins (like adding entries to a <code>Map</code>).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Example: a client application has this bootstrap configuration:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">bootstrap.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
application:
|
|
name: foo
|
|
profiles:
|
|
active: dev,mysql</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>(as usual with a Spring Boot application, these properties could also
|
|
be set as environment variables or command line arguments).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If the repository is file-based, the server will create an
|
|
<code>Environment</code> from <code>application.yml</code> (shared between all clients), and
|
|
<code>foo.yml</code> (with <code>foo.yml</code> taking precedence). If the YAML files have
|
|
documents inside them that point to Spring profiles, those are applied
|
|
with higher precedence (in order of the profiles listed), and if
|
|
there are profile-specific YAML (or properties) files these are also
|
|
applied with higher precedence than the defaults. Higher precedence
|
|
translates to a <code>PropertySource</code> listed earlier in the
|
|
<code>Environment</code>. (These are the same rules as apply in a standalone
|
|
Spring Boot application.)</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_git_backend">Git Backend</h4>
|
|
<div class="paragraph">
|
|
<p>The default implementation of <code>EnvironmentRepository</code> uses a Git
|
|
backend, which is very convenient for managing upgrades and physical
|
|
environments, and also for auditing changes. To change the location of
|
|
the repository you can set the "spring.cloud.config.server.git.uri"
|
|
configuration property in the Config Server (e.g. in
|
|
<code>application.yml</code>). If you set it with a <code>file:</code> prefix it should work
|
|
from a local repository so you can get started quickly and easily
|
|
without a server, but in that case the server operates directly on the
|
|
local repository without cloning it (it doesn’t matter if it’s not
|
|
bare because the Config Server never makes changes to the "remote"
|
|
repository). To scale the Config Server up and make it highly
|
|
available, you would need to have all instances of the server pointing
|
|
to the same repository, so only a shared file system would work. Even
|
|
in that case it is better to use the <code>ssh:</code> protocol for a shared
|
|
filesystem repository, so that the server can clone it and use a local
|
|
working copy as a cache.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This repository implementation maps the <code>{label}</code> parameter of the
|
|
HTTP resource to a git label (commit id, branch name or tag). If the
|
|
git branch or tag name contains a slash ("/") then the label in the
|
|
HTTP URL should be specified with the special string "(_)" instead (to
|
|
avoid ambiguity with other URL paths). Be careful with the brackets in
|
|
the URL if you are using a command line client like curl (e.g. escape
|
|
them from the shell with quotes '').</p>
|
|
</div>
|
|
<div class="sect4">
|
|
<h5 id="_placeholders_in_git_uri">Placeholders in Git URI</h5>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Config Server supports a git repository URL with
|
|
placeholders for the <code>{application}</code> and <code>{profile}</code> (and <code>{label}</code> if
|
|
you need it, but remember that the label is applied as a git label
|
|
anyway). So you can easily support a "one repo per application" policy
|
|
using (for example):</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
cloud:
|
|
config:
|
|
server:
|
|
git:
|
|
uri: https://github.com/myorg/{application}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>or a "one repo per profile" policy using a similar pattern but with
|
|
<code>{profile}</code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect4">
|
|
<h5 id="_pattern_matching_and_multiple_repositories">Pattern Matching and Multiple Repositories</h5>
|
|
<div class="paragraph">
|
|
<p>There is also support for more complex requirements with pattern
|
|
matching on the application and profile name. The pattern format is a
|
|
comma-separated list of <code>{application}/{profile}</code> names with wildcards
|
|
(where a pattern beginning with a wildcard may need to be
|
|
quoted). Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
cloud:
|
|
config:
|
|
server:
|
|
git:
|
|
uri: https://github.com/spring-cloud-samples/config-repo
|
|
repos:
|
|
simple: https://github.com/simple/config-repo
|
|
special:
|
|
pattern: special*/dev*,*special*/dev*
|
|
uri: https://github.com/special/config-repo
|
|
local:
|
|
pattern: local*
|
|
uri: file:/home/configsvc/config-repo</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If <code>{application}/{profile}</code> does not match any of the patterns, it
|
|
will use the default uri defined under
|
|
"spring.cloud.config.server.git.uri". In the above example, for the
|
|
"simple" repository, the pattern is <code>simple/*</code> (i.e. it only matches
|
|
one application named "simple" in all profiles). The "local"
|
|
repository matches all application names beginning with "local" in all
|
|
profiles (the <code>/*</code> suffix is added automatically to any pattern that
|
|
doesn’t have a profile matcher).</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
the "one-liner" short cut used in the "simple" example above can
|
|
only be used if the only property to be set is the URI. If you need to
|
|
set anything else (credentials, pattern, etc.) you need to use the full
|
|
form.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>pattern</code> property in the repo is actually an array, so you can
|
|
use a YAML array (or <code>[0]</code>, <code>[1]</code>, etc. suffixes in properties files)
|
|
to bind to multiple patterns. You may need to do this if you are going
|
|
to run apps with multiple profiles. Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
cloud:
|
|
config:
|
|
server:
|
|
git:
|
|
uri: https://github.com/spring-cloud-samples/config-repo
|
|
repos:
|
|
development:
|
|
pattern:
|
|
- */development
|
|
- */staging
|
|
uri: https://github.com/development/config-repo
|
|
staging:
|
|
pattern:
|
|
- */qa
|
|
- */production
|
|
uri: https://github.com/staging/config-repo</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
Spring Cloud will guess that a pattern containing a profile that
|
|
doesn’t end in <code>*</code> implies that you actually want to match a list of
|
|
profiles starting with this pattern (so <code>*/staging</code> is a shortcut for
|
|
<code>["*/staging", "*/staging,*"]</code>). This is common where you need to run
|
|
apps in the "development" profile locally but also the "cloud" profile
|
|
remotely, for instance.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Every repository can also optionally store config files in
|
|
sub-directories, and patterns to search for those directories can be
|
|
specified as <code>searchPaths</code>. For example at the top level:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
cloud:
|
|
config:
|
|
server:
|
|
git:
|
|
uri: https://github.com/spring-cloud-samples/config-repo
|
|
searchPaths: foo,bar*</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In this example the server searches for config files in the top level
|
|
and in the "foo/" sub-directory and also any sub-directory whose name
|
|
begins with "bar".</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>By default the server clones remote repositories when configuration
|
|
is first requested. The server can be configured to clone the repositories
|
|
at startup. For example at the top level:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
cloud:
|
|
config:
|
|
server:
|
|
git:
|
|
uri: https://git/common/config-repo.git
|
|
repos:
|
|
team-a:
|
|
pattern: team-a-*
|
|
cloneOnStart: true
|
|
uri: http://git/team-a/config-repo.git
|
|
team-b:
|
|
pattern: team-b-*
|
|
cloneOnStart: false
|
|
uri: http://git/team-b/config-repo.git
|
|
team-c:
|
|
pattern: team-c-*
|
|
uri: http://git/team-a/config-repo.git</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In this example the server clones team-a’s config-repo on startup before it
|
|
accepts any requests. All other repositories will not be cloned until
|
|
configuration from the repository is requested.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To use HTTP basic authentication on the remote repository add the
|
|
"username" and "password" properties separately (not in the URL),
|
|
e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
cloud:
|
|
config:
|
|
server:
|
|
git:
|
|
uri: https://github.com/spring-cloud-samples/config-repo
|
|
username: trolley
|
|
password: strongpassword</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you don’t use HTTPS and user credentials, SSH should also work out
|
|
of the box when you store keys in the default directories (<code>~/.ssh</code>)
|
|
and the uri points to an SSH location,
|
|
e.g. "<a href="mailto:git@github.com">git@github.com</a>:configuration/cloud-configuration". The
|
|
repository is accessed using JGit, so any documentation you find on
|
|
that should be applicable. HTTPS proxy settings can be set in
|
|
<code>~/.git/config</code> or in the same way as for any other JVM process via
|
|
system properties (<code>-Dhttps.proxyHost</code> and <code>-Dhttps.proxyPort</code>).</p>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Tip</div>
|
|
</td>
|
|
<td class="content">
|
|
If you don’t know where your <code>~/.git</code> directory is us <code>git config
|
|
--global</code> to manipulate the settings (e.g. <code>git config --global
|
|
http.sslVerify false</code>).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect4">
|
|
<h5 id="_placeholders_in_git_search_paths">Placeholders in Git Search Paths</h5>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Config Server also supports a search path with
|
|
placeholders for the <code>{application}</code> and <code>{profile}</code> (and <code>{label}</code> if
|
|
you need it). Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
cloud:
|
|
config:
|
|
server:
|
|
git:
|
|
uri: https://github.com/spring-cloud-samples/config-repo
|
|
searchPaths: '{application}'</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>searches the repository for files in the same name as the directory
|
|
(as well as the top level). Wildcards are also valid in a search
|
|
path with placeholders (any matching directory is included in the
|
|
search).</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_file_system_backend">File System Backend</h4>
|
|
<div class="paragraph">
|
|
<p>There is also a "native" profile in the Config Server that doesn’t use
|
|
Git, but just loads the config files from the local classpath or file
|
|
system (any static URL you want to point to with
|
|
"spring.cloud.config.server.native.searchLocations"). To use the
|
|
native profile just launch the Config Server with
|
|
"spring.profiles.active=native".</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
Remember to use the <code>file:</code> prefix for file resources (the
|
|
default without a prefix is usually the classpath). Just as with any
|
|
Spring Boot configuration you can embed <code>${}</code>-style environment
|
|
placeholders, but remember that absolute paths in Windows require an
|
|
extra "/", e.g. <code><a href="file:///${user.home}/config-repo" class="bare">file:///${user.home}/config-repo</a></code>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="admonitionblock warning">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Warning</div>
|
|
</td>
|
|
<td class="content">
|
|
The default value of the <code>searchLocations</code> is identical to a
|
|
local Spring Boot application (so <code>[classpath:/, classpath:/config,
|
|
file:./, file:./config]</code>). This does not expose the
|
|
<code>application.properties</code> from the server to all clients because any
|
|
property sources present in the server are removed before being sent
|
|
to the client.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Tip</div>
|
|
</td>
|
|
<td class="content">
|
|
A filesystem backend is great for getting started quickly and
|
|
for testing. To use it in production you need to be sure that the
|
|
file system is reliable, and shared across all instances of the
|
|
Config Server.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The search locations can contain placeholders for <code>{application}</code>,
|
|
<code>{profile}</code> and <code>{label}</code>. In this way you can segregate the
|
|
directories in the path, and choose a strategy that makes sense for
|
|
you (e.g. sub-directory per application, or sub-directory per
|
|
profile).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you don’t use placeholders in the search locations, this repository
|
|
also appends the <code>{label}</code> parameter of the HTTP resource to a suffix
|
|
on the search path, so properties files are loaded from each search
|
|
location <strong>and</strong> a subdirectory with the same name as the label (the
|
|
labelled properties take precedence in the Spring Environment). Thus
|
|
the default behaviour with no placeholders is the same as adding a
|
|
search location ending with <code>/{label}/. For example `file:/tmp/config</code>
|
|
is the same as <code>file:/tmp/config,file:/tmp/config/{label}</code></p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_sharing_configuration_with_all_applications">Sharing Configuration With All Applications</h4>
|
|
<div class="paragraph">
|
|
<p>With file-based (i.e. git, svn and native) repositories, resources
|
|
with file names in <code>application*</code> are shared between all client
|
|
applications (so <code>application.properties</code>, <code>application.yml</code>,
|
|
<code>application-*.properties</code> etc.). You can use resources with these
|
|
file names to configure global defaults and have them overridden by
|
|
application-specific files as necessary.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The #_property_overrides[property overrides] feature can also be used
|
|
for setting global defaults, and with placeholders applications are
|
|
allowed to override them locally.</p>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Tip</div>
|
|
</td>
|
|
<td class="content">
|
|
With the "native" profile (local file system backend) it is
|
|
recommended that you use an explicit search location that isn’t part
|
|
of the server’s own configuration. Otherwise the <code>application*</code>
|
|
resources in the default search locations are removed because they are
|
|
part of the server.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_property_overrides">Property Overrides</h4>
|
|
<div class="paragraph">
|
|
<p>The Config Server has an "overrides" feature that allows the operator
|
|
to provide configuration properties to all applications that cannot be
|
|
accidentally changed by the application using the normal Spring Boot
|
|
hooks. To declare overrides just add a map of name-value pairs to
|
|
<code>spring.cloud.config.server.overrides</code>. For example</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
cloud:
|
|
config:
|
|
server:
|
|
overrides:
|
|
foo: bar</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>will cause all applications that are config clients to read <code>foo=bar</code>
|
|
independent of their own configuration. (Of course an application can
|
|
use the data in the Config Server in any way it likes, so overrides
|
|
are not enforceable, but they do provide useful default behaviour if
|
|
they are Spring Cloud Config clients.)</p>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Tip</div>
|
|
</td>
|
|
<td class="content">
|
|
Normal, Spring environment placeholders with "${}" can be escaped
|
|
(and resolved on the client) by using backslash ("\") to escape the
|
|
"$" or the "{", e.g. <code>\${app.foo:bar}</code> resolves to "bar" unless the
|
|
app provides its own "app.foo". Note that in YAML you don’t need to
|
|
escape the backslash itself, but in properties files you do, when you
|
|
configure the overrides on the server.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can change the priority of all overrides in the client to be more
|
|
like default values, allowing applications to supply their own values
|
|
in environment variables or System properties, by setting the flag `</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_health_indicator">Health Indicator</h3>
|
|
<div class="paragraph">
|
|
<p>Config Server comes with a Health Indicator that checks if the configured
|
|
<code>EnvironmentRepository</code> is working. By default it asks the <code>EnvironmentRepository</code>
|
|
for an application named <code>app</code>, the <code>default</code> profile and the default
|
|
label provided by the <code>EnvironmentRepository</code> implementation.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can configure the Health Indicator to check more applications
|
|
along with custom profiles and custom labels, e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
cloud:
|
|
config:
|
|
server:
|
|
health:
|
|
repositories:
|
|
myservice:
|
|
label: mylabel
|
|
myservice-dev:
|
|
name: myservice
|
|
profiles: development</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can disable the Health Indicator by setting <code>spring.cloud.config.server.health.enabled=false</code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_security">Security</h3>
|
|
<div class="paragraph">
|
|
<p>You are free to secure your Config Server in any way that makes sense
|
|
to you (from physical network security to OAuth2 bearer
|
|
tokens), and Spring Security and Spring Boot make it easy to do pretty
|
|
much anything.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To use the default Spring Boot configured HTTP Basic security, just
|
|
include Spring Security on the classpath (e.g. through
|
|
<code>spring-boot-starter-security</code>). The default is a username of "user"
|
|
and a randomly generated password, which isn’t going to be very useful
|
|
in practice, so we recommend you configure the password (via
|
|
<code>security.user.password</code>) and encrypt it (see below for instructions
|
|
on how to do that).</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_encryption_and_decryption_2">Encryption and Decryption</h3>
|
|
<div class="admonitionblock important">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Important</div>
|
|
</td>
|
|
<td class="content">
|
|
<strong>Prerequisites:</strong> to use the encryption and decryption features
|
|
you need the full-strength JCE installed in your JVM (it’s not there by default).
|
|
You can download the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files"
|
|
from Oracle, and follow instructions for installation (essentially replace the 2 policy files
|
|
in the JRE lib/security directory with the ones that you downloaded).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If the remote property sources contain encrypted content (values
|
|
starting with <code>{cipher}</code>) they will be decrypted before sending to
|
|
clients over HTTP. The main advantage of this set up is that the
|
|
property values don’t have to be in plain text when they are "at rest"
|
|
(e.g. in a git repository). If a value cannot be decrypted it is
|
|
removed from the property source and an additional property is added
|
|
with the same key, but prefixed with "invalid." and a value that means
|
|
"not applicable" (usually "<n/a>"). This is largely to prevent cipher
|
|
text being used as a password and accidentally leaking.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you are setting up a remote config repository for config client
|
|
applications it might contain an <code>application.yml</code> like this, for
|
|
instance:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
datasource:
|
|
username: dbuser
|
|
password: '{cipher}FKSAJDFGYOS8F7GLHAKERGFHLSAJ'</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Encrypted values in a .properties file must not be wrapped in quotes, otherwise the value will not be decrypted:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.properties</div>
|
|
<div class="content">
|
|
<pre>spring.datasource.username: dbuser
|
|
spring.datasource.password: {cipher}FKSAJDFGYOS8F7GLHAKERGFHLSAJ</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can safely push this plain text to a shared git repository and the
|
|
secret password is protected.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The server also exposes <code>/encrypt</code> and <code>/decrypt</code> endpoints (on the
|
|
assumption that these will be secured and only accessed by authorized
|
|
agents). If you are editing a remote config file you can use the Config Server
|
|
to encrypt values by POSTing to the <code>/encrypt</code> endpoint, e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>$ curl localhost:8888/encrypt -d mysecret
|
|
682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The inverse operation is also available via <code>/decrypt</code> (provided the server is
|
|
configured with a symmetric key or a full key pair):</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>$ curl localhost:8888/decrypt -d 682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
|
|
mysecret</pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Tip</div>
|
|
</td>
|
|
<td class="content">
|
|
If you are testing like this with curl, then use
|
|
<code>--data-urlencode</code> (instead of <code>-d</code>) or set an explicit <code>Content-Type:
|
|
text/plain</code> to make sure curl encodes the data correctly when there
|
|
are special characters ('+' is particularly tricky).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Take the encrypted value and add the <code>{cipher}</code> prefix before you put
|
|
it in the YAML or properties file, and before you commit and push it
|
|
to a remote, potentially insecure store.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>/encrypt</code> and <code>/decrypt</code> endpoints also both accept paths of the
|
|
form <code>/*/{name}/{profiles}</code> which can be used to control cryptography
|
|
per application (name) and profile when clients call into the main
|
|
Environment resource.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
to control the cryptography in this granular way you must also
|
|
provide a <code>@Bean</code> of type <code>TextEncryptorLocator</code> that creates a
|
|
different encryptor per name and profiles. The one that is provided
|
|
by default does not do this (so all encryptions use the same key).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>spring</code> command line client (with Spring Cloud CLI extensions
|
|
installed) can also be used to encrypt and decrypt, e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>$ spring encrypt mysecret --key foo
|
|
682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
|
|
$ spring decrypt --key foo 682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
|
|
mysecret</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To use a key in a file (e.g. an RSA public key for encryption) prepend
|
|
the key value with "@" and provide the file path, e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>$ spring encrypt mysecret --key @${HOME}/.ssh/id_rsa.pub
|
|
AQAjPgt3eFZQXwt8tsHAVv/QHiY5sI2dRcR+...</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The key argument is mandatory (despite having a <code>--</code> prefix).</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_key_management">Key Management</h3>
|
|
<div class="paragraph">
|
|
<p>The Config Server can use a symmetric (shared) key or an asymmetric
|
|
one (RSA key pair). The asymmetric choice is superior in terms of
|
|
security, but it is often more convenient to use a symmetric key since
|
|
it is just a single property value to configure.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To configure a symmetric key you just need to set <code>encrypt.key</code> to a
|
|
secret String (or use an enviroment variable <code>ENCRYPT_KEY</code> to keep it
|
|
out of plain text configuration files).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To configure an asymmetric key you can either set the key as a
|
|
PEM-encoded text value (in <code>encrypt.key</code>), or via a keystore (e.g. as
|
|
created by the <code>keytool</code> utility that comes with the JDK). The
|
|
keystore properties are <code>encrypt.keyStore.*</code> with <code>*</code> equal to</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><code>location</code> (a <code>Resource</code> location),</p>
|
|
</li>
|
|
<li>
|
|
<p><code>password</code> (to unlock the keystore) and</p>
|
|
</li>
|
|
<li>
|
|
<p><code>alias</code> (to identify which key in the store is to be
|
|
used).</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The encryption is done with the public key, and a private key is
|
|
needed for decryption. Thus in principle you can configure only the
|
|
public key in the server if you only want to do encryption (and are
|
|
prepared to decrypt the values yourself locally with the private
|
|
key). In practice you might not want to do that because it spreads the
|
|
key management process around all the clients, instead of
|
|
concentrating it in the server. On the other hand it’s a useful option
|
|
if your config server really is relatively insecure and only a
|
|
handful of clients need the encrypted properties.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_creating_a_key_store_for_testing">Creating a Key Store for Testing</h3>
|
|
<div class="paragraph">
|
|
<p>To create a keystore for testing you can do something like this:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>$ keytool -genkeypair -alias mytestkey -keyalg RSA \
|
|
-dname "CN=Web Server,OU=Unit,O=Organization,L=City,S=State,C=US" \
|
|
-keypass changeme -keystore server.jks -storepass letmein</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Put the <code>server.jks</code> file in the classpath (for instance) and then in
|
|
your <code>application.yml</code> for the Config Server:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">encrypt:
|
|
keyStore:
|
|
location: classpath:/server.jks
|
|
password: letmein
|
|
alias: mytestkey
|
|
secret: changeme</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_using_multiple_keys_and_key_rotation">Using Multiple Keys and Key Rotation</h3>
|
|
<div class="paragraph">
|
|
<p>In addition to the <code>{cipher}</code> prefix in encrypted property values, the
|
|
Config Server looks for <code>{name:value}</code> prefixes (zero or many) before
|
|
the start of the (Base64 encoded) cipher text. The keys are passed to
|
|
a <code>TextEncryptorLocator</code> which can do whatever logic it needs to
|
|
locate a <code>TextEncryptor</code> for the cipher. If you have configured a
|
|
keystore (<code>encrypt.keystore.location</code>) the default locator will look
|
|
for keys in the store with aliases as supplied by the "key" prefix,
|
|
i.e. with a cipher text like this:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">foo:
|
|
bar: `{cipher}{key:testkey}...`</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>the locator will look for a key named "testkey". A secret can also be
|
|
supplied via a <code>{secret:…​}</code> value in the prefix, but if it is not
|
|
the default is to use the keystore password (which is what you get
|
|
when you build a keytore and don’t specify a secret). If you <strong>do</strong>
|
|
supply a secret it is recommended that you also encrypt the secrets
|
|
using a custom <code>SecretLocator</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Key rotation is hardly ever necessary on cryptographic grounds if the
|
|
keys are only being used to encrypt a few bytes of configuration data
|
|
(i.e. they are not being used elsewhere), but occasionally you might
|
|
need to change the keys if there is a security breach for instance. In
|
|
that case all the clients would need to change their source config
|
|
files (e.g. in git) and use a new <code>{key:…​}</code> prefix in all the
|
|
ciphers, checking beforehand of course that the key alias is available
|
|
in the Config Server keystore.</p>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Tip</div>
|
|
</td>
|
|
<td class="content">
|
|
the <code>{name:value}</code> prefixes can also be added to plaintext posted
|
|
to the <code>/encrypt</code> endpoint, if you want to let the Config Server
|
|
handle all encryption as well as decryption.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_serving_encrypted_properties">Serving Encrypted Properties</h3>
|
|
<div class="paragraph">
|
|
<p>Sometimes you want the clients to decrypt the configuration locally,
|
|
instead of doing it in the server. In that case you can still have
|
|
/encrypt and /decrypt endpoints (if you provide the <code>encrypt.*</code>
|
|
configuration to locate a key), but you need to explicitly switch off
|
|
the decryption of outgoing properties using
|
|
<code>spring.cloud.config.server.encrypt.enabled=false</code>. If you don’t care
|
|
about the endpoints, then it should work if you configure neither the
|
|
key nor the enabled flag.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_serving_alternative_formats">Serving Alternative Formats</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>The default JSON format from the environment endpoints is perfect for
|
|
consumption by Spring applications because it maps directly onto the
|
|
<code>Environment</code> abstraction. If you prefer you can consume the same data
|
|
as YAML or Java properties by adding a suffix to the resource path
|
|
(".yml", ".yaml" or ".properties"). This can be useful for consumption
|
|
by applications that do not care about the structure of the JSON
|
|
endpoints, or the extra metadata they provide, for example an
|
|
application that is not using Spring might benefit fro mthe simplicity
|
|
of this approach.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The YAML and properties representations have an additional flag
|
|
(provided as a boolean query parameter <code>resolvePlaceholders</code>) to
|
|
signal that placeholders in the source documents, in the standard
|
|
Spring <code>${…​}</code> form, should be resolved in the output where possible
|
|
before rendering. This is a useful feature for consumers that don’t
|
|
know about the Spring placeholder conventions.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
there are limitations in using the YAML or properties formats,
|
|
mainly in relation to the loss of metadata. The JSON is structured as
|
|
an ordered list of property sources, for example, with names that
|
|
correlate with the source. The YAML and properties forms are coalesced
|
|
into a single map, even if the origin of the values has multiple
|
|
sources, and the names of the original source files are lost. The YAML
|
|
representation is not necessarily a faithful representation of the
|
|
YAML source in a backing repository either: it is constructed from a
|
|
list of flat property sources, and assumptions have to be made about
|
|
the form of the keys.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_serving_plain_text">Serving Plain Text</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Instead of using the <code>Environment</code> abstraction (or one of the
|
|
alternative representations of it in YAML or properties format) your
|
|
applications might need generic plain text configuration files,
|
|
tailored to their environment. The Config Server provides these
|
|
through an additional endpoint at <code>/{name}/{profile}/{label}/{path}</code>
|
|
where "name", "profile" and "label" have the same meaning as the
|
|
regular environment endpoint, but "path" is a file name
|
|
(e.g. <code>log.xml</code>). The source files for this endpoint are located in
|
|
the same way as for the environment endpoints: the same search path is
|
|
used as for properties or YAML files, but instead of aggregating all
|
|
matching resources, only the first one to match is returned.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>After a resource is located, placeholders in the normal format
|
|
(<code>${…​}</code>) are resolved using the effective <code>Environment</code> for the
|
|
application name, profile and label supplied. In this way the resource
|
|
endpoint is tightly integrated with the environment
|
|
endpoints. Example, if you have this layout for a GIT (or SVN)
|
|
repository:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>application.yml
|
|
nginx.conf</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>where <code>nginx.conf</code> looks like this:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>server {
|
|
listen 80;
|
|
server_name ${nginx.server.name};
|
|
}</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>and <code>application.yml</code> like this:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">nginx:
|
|
server:
|
|
name: example.com
|
|
---
|
|
spring:
|
|
profiles: development
|
|
nginx:
|
|
server:
|
|
name: develop.com</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>then the <code>/foo/default/master/nginx.conf</code> resource looks like this:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>server {
|
|
listen 80;
|
|
server_name example.com;
|
|
}</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>and <code>/foo/development/master/nginx.conf</code> like this:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>server {
|
|
listen 80;
|
|
server_name develop.com;
|
|
}</pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
just like the source files for environment configuration, the
|
|
"profile" is used to resolve the file name, so if you want a
|
|
profile-specific file then <code>/*/development/*/logback.xml</code> will be
|
|
resolved by a file called <code>logback-development.xml</code> (in preference
|
|
to <code>logback.xml</code>).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_embedding_the_config_server">Embedding the Config Server</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>The Config Server runs best as a standalone application, but if you
|
|
need to you can embed it in another application. Just use the
|
|
<code>@EnableConfigServer</code> annotation. An optional property that can be
|
|
useful in this case is <code>spring.cloud.config.server.bootstrap</code> which is
|
|
a flag to indicate that the server should configure itself from its
|
|
own remote repository. The flag is off by default because it can delay
|
|
startup, but when embedded in another application it makes sense to
|
|
initialize the same way as any other application.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
It should be obvious, but remember that if you use the bootstrap
|
|
flag the config server will need to have its name and repository URI
|
|
configured in <code>bootstrap.yml</code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To change the location of the server endpoints you can (optionally)
|
|
set <code>spring.cloud.config.server.prefix</code>, e.g. "/config", to serve the
|
|
resources under a prefix. The prefix should start but not end with a
|
|
"/". It is applied to the <code>@RequestMappings</code> in the Config Server
|
|
(i.e. underneath the Spring Boot prefixes <code>server.servletPath</code> and
|
|
<code>server.contextPath</code>).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you want to read the configuration for an application directly from
|
|
the backend repository (instead of from the config server) that’s
|
|
basically an embedded config server with no endpoints. You can switch
|
|
off the endpoints entirely if you don’t use the <code>@EnableConfigServer</code>
|
|
annotation (just set <code>spring.cloud.config.server.bootstrap=true</code>).</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_push_notifications_and_spring_cloud_bus">Push Notifications and Spring Cloud Bus</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Many source code repository providers (like Github, Gitlab or Bitbucket
|
|
for instance) will notify you of changes in a repository through a
|
|
webhook. You can configure the webhook via the provider’s user
|
|
interface as a URL and a set of events in which you are
|
|
interested. For instance
|
|
<a href="https://developer.github.com/v3/activity/events/types/#pushevent">Github</a>
|
|
will POST to the webhook with a JSON body containing a list of
|
|
commits, and a header "X-Github-Event" equal to "push". If you add a
|
|
dependency on the <code>spring-cloud-config-monitor</code> library and activate
|
|
the Spring Cloud Bus in your Config Server, then a "/monitor" endpoint
|
|
is enabled.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>When the webhook is activated the Config Server will send a
|
|
<code>RefreshRemoteApplicationEvent</code> targeted at the applications it thinks
|
|
might have changed. The change detection can be strategized, but by
|
|
default it just looks for changes in files that match the application
|
|
name (e.g. "foo.properties" is targeted at the "foo" application, and
|
|
"application.properties" is targeted at all applications). The strategy
|
|
if you want to override the behaviour is <code>PropertyPathNotificationExtractor</code>
|
|
which accepts the request headers and body as parameters and returns a list
|
|
of file paths that changed.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The default configuration works out of the box with Github, Gitlab or
|
|
Bitbucket. In addition to the JSON notifications from Github, Gitlab
|
|
or Bitbucket you can trigger a change notification by POSTing to
|
|
"/monitor" with a form-encoded body parameters <code>path={name}</code>. This will
|
|
broadcast to applications matching the "{name}" pattern (can contain
|
|
wildcards).</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
the <code>RefreshRemoteApplicationEvent</code> will only be transmitted if
|
|
the <code>spring-cloud-bus</code> is activated in the Config Server and in the
|
|
client application.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
the default configuration also detects filesystem changes in
|
|
local git repositories (the webhook is not used in that case but as
|
|
soon as you edit a config file a refresh will be broadcast).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_spring_cloud_config_client">Spring Cloud Config Client</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>A Spring Boot application can take immediate advantage of the Spring
|
|
Config Server (or other external property sources provided by the
|
|
application developer), and it will also pick up some additional
|
|
useful features related to <code>Environment</code> change events.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="config-first-bootstrap">Config First Bootstrap</h3>
|
|
<div class="paragraph">
|
|
<p>This is the default behaviour for any application which has the Spring
|
|
Cloud Config Client on the classpath. When a config client starts up
|
|
it binds to the Config Server (via the bootstrap configuration
|
|
property <code>spring.cloud.config.uri</code>) and initializes Spring
|
|
<code>Environment</code> with remote property sources.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The net result of this is that all client apps that want to consume
|
|
the Config Server need a <code>bootstrap.yml</code> (or an environment variable)
|
|
with the server address in <code>spring.cloud.config.uri</code> (defaults to
|
|
"http://localhost:8888").</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="discovery-first-bootstrap">Discovery First Bootstrap</h3>
|
|
<div class="paragraph">
|
|
<p>If you are using a `DiscoveryClient implementation, such as Spring Cloud Netflix
|
|
and Eureka Service Discovery or Spring Cloud Consul (Spring Cloud Zookeeper does
|
|
not support this yet), then you can have the Config Server register with the
|
|
Discovery Service if you want to, but in the default "Config First" mode,
|
|
clients won’t be able to take advantage of the registration.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you prefer to use <code>DiscoveryClient</code> to locate the Config Server, you can do
|
|
that by setting <code>spring.cloud.config.discovery.enabled=true</code> (default
|
|
"false"). The net result of that is that client apps all need a
|
|
<code>bootstrap.yml</code> (or an environment variable) with the appropriate discovery
|
|
configuration. For example, with Spring Cloud Netflix, you need to define the
|
|
Eureka server address, e.g. in <code>eureka.client.serviceUrl.defaultZone</code>. The
|
|
price for using this option is an extra network round trip on start up to
|
|
locate the service registration. The benefit is that the Config Server
|
|
can change its co-ordinates, as long as the Discovery Service is a fixed point. The
|
|
default service id is "configserver" but you can change that on the
|
|
client with <code>spring.cloud.config.discovery.serviceId</code> (and on the server
|
|
in the usual way for a service, e.g. by setting <code>spring.application.name</code>).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The discovery client implementations all support some kind of metadata
|
|
map (e.g. for Eureka we have <code>eureka.instance.metadataMap</code>). Some
|
|
additional properties of the Config Server may need to be configured
|
|
in its service registration metadata so that clients can connect
|
|
correctly. If the Config Server is secured with HTTP Basic you can
|
|
configure the credentials as "username" and "password". And if the
|
|
Config Server has a context path you can set "configPath". Example,
|
|
for a Config Server that is a Eureka client:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">bootstrap.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">eureka:
|
|
instance:
|
|
...
|
|
metadataMap:
|
|
user: osufhalskjrtl
|
|
password: lviuhlszvaorhvlo5847
|
|
configPath: /config</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="config-client-fail-fast">Config Client Fail Fast</h3>
|
|
<div class="paragraph">
|
|
<p>In some cases, it may be desirable to fail startup of a service if
|
|
it cannot connect to the Config Server. If this is the desired
|
|
behavior, set the bootstrap configuration property
|
|
<code>spring.cloud.config.failFast=true</code> and the client will halt with
|
|
an Exception.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="config-client-retry">Config Client Retry</h3>
|
|
<div class="paragraph">
|
|
<p>If you expect that the config server may occasionally be unavailable when
|
|
your app starts, you can ask it to keep trying after a failure. First you need
|
|
to set <code>spring.cloud.config.failFast=true</code>, and then you need to add
|
|
<code>spring-retry</code> and <code>spring-boot-starter-aop</code> to your classpath. The default
|
|
behaviour is to retry 6 times with an initial backoff interval of 1000ms and an
|
|
exponential multiplier of 1.1 for subsequent backoffs. You can configure these
|
|
properties (and others) using <code>spring.cloud.config.retry.*</code> configuration properties.</p>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Tip</div>
|
|
</td>
|
|
<td class="content">
|
|
To take full control of the retry add a <code>@Bean</code> of type
|
|
<code>RetryOperationsInterceptor</code> with id "configServerRetryInterceptor". Spring
|
|
Retry has a <code>RetryInterceptorBuilder</code> that makes it easy to create one.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_locating_remote_configuration_resources">Locating Remote Configuration Resources</h3>
|
|
<div class="paragraph">
|
|
<p>The Config Service serves property sources from <code>/{name}/{profile}/{label}</code>, where the default bindings in the client app are</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>"name" = <code>${spring.application.name}</code></p>
|
|
</li>
|
|
<li>
|
|
<p>"profile" = <code>${spring.profiles.active}</code> (actually <code>Environment.getActiveProfiles()</code>)</p>
|
|
</li>
|
|
<li>
|
|
<p>"label" = "master"</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>All of them can be overridden by setting <code>spring.cloud.config.*</code>
|
|
(where <code>*</code> is "name", "profile" or "label"). The "label" is useful for
|
|
rolling back to previous versions of configuration; with the default
|
|
Config Server implementation it can be a git label, branch name or
|
|
commit id. Label can also be provided as a comma-separated list, in
|
|
which case the items in the list are tried on-by-one until one succeeds.
|
|
This can be useful when working on a feature branch, for instance,
|
|
when you might want to align the config label with your branch, but
|
|
make it optional (e.g. <code>spring.cloud.config.label=myfeature,develop</code>).</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_security_2">Security</h3>
|
|
<div class="paragraph">
|
|
<p>If you use HTTP Basic security on the server then clients just need to
|
|
know the password (and username if it isn’t the default). You can do
|
|
that via the config server URI, or via separate username and password
|
|
properties, e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">bootstrap.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
cloud:
|
|
config:
|
|
uri: https://user:secret@myconfig.mycompany.com</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>or</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">bootstrap.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
cloud:
|
|
config:
|
|
uri: https://myconfig.mycompany.com
|
|
username: user
|
|
password: secret</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>spring.cloud.config.password</code> and <code>spring.cloud.config.username</code>
|
|
values override anything that is provided in the URI.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you deploy your apps on Cloud Foundry then the best way to provide
|
|
the password is through service credentials, e.g. in the URI, since
|
|
then it doesn’t even need to be in a config file. An example which
|
|
works locally and for a user-provided service on Cloud Foundry named
|
|
"configserver":</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">bootstrap.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
cloud:
|
|
config:
|
|
uri: ${vcap.services.configserver.credentials.uri:http://user:password@localhost:8888}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you use another form of security you might need to provide a
|
|
<code>RestTemplate</code> to the <code>ConfigServicePropertySourceLocator</code> (e.g. by
|
|
grabbing it in the bootstrap context and injecting one).</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<h1 id="_spring_cloud_netflix" class="sect0">Spring Cloud Netflix</h1>
|
|
<div class="openblock partintro">
|
|
<div class="content">
|
|
This project provides Netflix OSS integrations for Spring Boot apps through autoconfiguration
|
|
and binding to the Spring Environment and other Spring programming model idioms. With a few
|
|
simple annotations you can quickly enable and configure the common patterns inside your
|
|
application and build large distributed systems with battle-tested Netflix components. The
|
|
patterns provided include Service Discovery (Eureka), Circuit Breaker (Hystrix),
|
|
Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon).
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_service_discovery_eureka_clients">Service Discovery: Eureka Clients</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Service Discovery is one of the key tenets of a microservice based architecture. Trying to hand configure each client or some form of convention can be very difficult to do and can be very brittle. Eureka is the Netflix Service Discovery Server and Client. The server can be configured and deployed to be highly available, with each server replicating state about the registered services to the others.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_registering_with_eureka">Registering with Eureka</h3>
|
|
<div class="paragraph">
|
|
<p>When a client registers with Eureka, it provides meta-data about itself
|
|
such as host and port, health indicator URL, home page etc. Eureka
|
|
receives heartbeat messages from each instance belonging to a service.
|
|
If the heartbeat fails over a configurable timetable, the instance is
|
|
normally removed from the registry.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Example eureka client:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Configuration
|
|
@ComponentScan
|
|
@EnableAutoConfiguration
|
|
@EnableEurekaClient
|
|
@RestController
|
|
public class Application {
|
|
|
|
@RequestMapping("/")
|
|
public String home() {
|
|
return "Hello world";
|
|
}
|
|
|
|
public static void main(String[] args) {
|
|
new SpringApplicationBuilder(Application.class).web(true).run(args);
|
|
}
|
|
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>(i.e. utterly normal Spring Boot app). In this example we use
|
|
<code>@EnableEurekaClient</code> explicitly, but with only Eureka available you
|
|
could also use <code>@EnableDiscoveryClient</code>. Configuration is required to
|
|
locate the Eureka server. Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>eureka:
|
|
client:
|
|
serviceUrl:
|
|
defaultZone: http://localhost:8761/eureka/</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>where "defaultZone" is a magic string fallback value that provides the
|
|
service URL for any client that doesn’t express a preference
|
|
(i.e. it’s a useful default).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The default application name (service ID), virtual host and non-secure
|
|
port, taken from the <code>Environment</code>, are <code>${spring.application.name}</code>,
|
|
<code>${spring.application.name}</code> and <code>${server.port}</code> respectively.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><code>@EnableEurekaClient</code> makes the app into both a Eureka "instance"
|
|
(i.e. it registers itself) and a "client" (i.e. it can query the
|
|
registry to locate other services). The instance behaviour is driven
|
|
by <code>eureka.instance.*</code> configuration keys, but the defaults will be
|
|
fine if you ensure that your application has a
|
|
<code>spring.application.name</code> (this is the default for the Eureka service
|
|
ID, or VIP).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>See <a href="http://github.com/spring-cloud/spring-cloud-netflix/tree/master/spring-cloud-netflix-eureka-client/src/main/java/org/springframework/cloud/netflix/eureka/EurekaInstanceConfigBean.java">EurekaInstanceConfigBean</a> and <a href="http://github.com/spring-cloud/spring-cloud-netflix/tree/master/spring-cloud-netflix-eureka-client/src/main/java/org/springframework/cloud/netflix/eureka/EurekaClientConfigBean.java">EurekaClientConfigBean</a> for more details of the configurable options.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_authenticating_with_the_eureka_server">Authenticating with the Eureka Server</h3>
|
|
<div class="paragraph">
|
|
<p>HTTP basic authentication will be automatically added to your eureka
|
|
client if one of the <code>eureka.client.serviceUrl.defaultZone</code> URLs has
|
|
credentials embedded in it (curl style, like
|
|
<code><a href="http://user:password@localhost:8761/eureka" class="bare">http://user:password@localhost:8761/eureka</a></code>). For more complex needs
|
|
you can create a <code>@Bean</code> of type <code>DiscoveryClientOptionalArgs</code> and
|
|
inject <code>ClientFilter</code> instances into it, all of which will be applied
|
|
to the calls from the client to the server.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
Because of a limitation in Eureka it isn’t possible to support
|
|
per-server basic auth credentials, so only the first set that are
|
|
found will be used.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_status_page_and_health_indicator">Status Page and Health Indicator</h3>
|
|
<div class="paragraph">
|
|
<p>The status page and health indicators for a Eureka instance default to
|
|
"/info" and "/health" respectively, which are the default locations of
|
|
useful endpoints in a Spring Boot Actuator application. You need to
|
|
change these, even for an Actuator application if you use a
|
|
non-default context path or servlet path
|
|
(e.g. <code>server.servletPath=/foo</code>) or management endpoint path
|
|
(e.g. <code>management.contextPath=/admin</code>). Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>eureka:
|
|
instance:
|
|
statusPageUrlPath: ${management.context-path}/info
|
|
healthCheckUrlPath: ${management.context-path}/health</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>These links show up in the metadata that is consumed by clients, and
|
|
used in some scenarios to decide whether to send requests to your
|
|
application, so it’s helpful if they are accurate.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_registering_a_secure_application">Registering a Secure Application</h3>
|
|
<div class="paragraph">
|
|
<p>If your app wants to be contacted over HTTPS you can set two flags in
|
|
the <code>EurekaInstanceConfig</code>, <em>viz</em>
|
|
<code>eureka.instance.[nonSecurePortEnabled,securePortEnabled]=[false,true]</code>
|
|
respectively. This will make Eureka publish instance information
|
|
showing an explicit preference for secure communication. The Spring
|
|
Cloud <code>DiscoveryClient</code> will always return an <code><a href="https://…​" class="bare">https://…​</a>;</code> URI for a
|
|
service configured this way, and the Eureka (native) instance
|
|
information will have a secure health check URL.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Because of the way
|
|
Eureka works internally, it will still publish a non-secure URL for
|
|
status and home page unless you also override those explicitly.
|
|
You can use placeholders to configure the eureka instance urls,
|
|
e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>eureka:
|
|
instance:
|
|
statusPageUrl: https://${eureka.hostname}/info
|
|
healthCheckUrl: https://${eureka.hostname}/health
|
|
homePageUrl: https://${eureka.hostname}/</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>(Note that <code>${eureka.hostname}</code> is a native placeholder only available
|
|
in later versions of Eureka. You could achieve the same thing with
|
|
Spring placeholders as well, e.g. using <code>${eureka.instance.hostName}</code>.)</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
If your app is running behind a proxy, and the SSL termination
|
|
is in the proxy (e.g. if you run in Cloud Foundry or other platforms
|
|
as a service) then you will need to ensure that the proxy "forwarded"
|
|
headers are intercepted and handled by the application. An embedded
|
|
Tomcat container in a Spring Boot app does this automatically if it
|
|
has explicit configuration for the 'X-Forwarded-\*` headers. A sign
|
|
that you got this wrong will be that the links rendered by your app to
|
|
itself will be wrong (the wrong host, port or protocol).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_eureka_s_health_checks">Eureka’s Health Checks</h3>
|
|
<div class="paragraph">
|
|
<p>By default, Eureka uses the client heartbeat to determine if a client is up.
|
|
Unless specified otherwise the Discovery Client will not propagate the
|
|
current health check status of the application per the Spring Boot Actuator. Which means
|
|
that after successful registration Eureka will always announce that the
|
|
application is in 'UP' state. This behaviour can be altered by enabling
|
|
Eureka health checks, which results in propagating application status
|
|
to Eureka. As a consequence every other application won’t be sending
|
|
traffic to application in state other then 'UP'.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>eureka:
|
|
client:
|
|
healthcheck:
|
|
enabled: true</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you require more control over the health checks, you may consider
|
|
implementing your own <code>com.netflix.appinfo.HealthCheckHandler</code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_eureka_metadata_for_instances_and_clients">Eureka Metadata for Instances and Clients</h3>
|
|
<div class="paragraph">
|
|
<p>It’s worth spending a bit of time understanding how the Eureka metadata works, so you can use it in a way that makes sense in your platform. There is standard metadata for things like hostname, IP address, port numbers, status page and health check. These are published in the service registry and used by clients to contact the services in a straightforward way. Additional metadata can be added to the instance registration in the <code>eureka.instance.metadataMap</code>, and this will be accessible in the remote clients, but in general will not change the behaviour of the client, unless it is made aware of the meaning of the metadata. There are a couple of special cases described below where Spring Cloud already assigns meaning to the metadata map.</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_using_eureka_on_cloudfoundry">Using Eureka on Cloudfoundry</h4>
|
|
<div class="paragraph">
|
|
<p>Cloudfoundry has a global router so that all instances of the same app have the same hostname (it’s the same in other PaaS solutions with a similar architecture). This isn’t necessarily a barrier to using Eureka, but if you use the router (recommended, or even mandatory depending on the way your platform was set up), you need to explicitly set the hostname and port numbers (secure or non-secure) so that they use the router. You might also want to use instance metadata so you can distinguish between the instances on the client (e.g. in a custom load balancer). By default, the <code>eureka.instance.instanceId</code> is <code>vcap.application.instance_id</code>. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>eureka:
|
|
instance:
|
|
hostname: ${vcap.application.uris[0]}
|
|
nonSecurePort: 80</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Depending on the way the security rules are set up in your Cloudfoundry instance, you might be able to register and use the IP address of the host VM for direct service-to-service calls. This feature is not (yet) available on Pivotal Web Services (<a href="https://run.pivotal.io">PWS</a>).</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_using_eureka_on_aws">Using Eureka on AWS</h4>
|
|
<div class="paragraph">
|
|
<p>If the application is planned to be deployed to an AWS cloud, then the Eureka instance will have to be configured to be Amazon aware and this can be done by customizing the <a href="http://github.com/spring-cloud/spring-cloud-netflix/tree/master/spring-cloud-netflix-eureka-client/src/main/java/org/springframework/cloud/netflix/eureka/EurekaInstanceConfigBean.java">EurekaInstanceConfigBean</a> the following way:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Bean
|
|
@Profile("!default")
|
|
public EurekaInstanceConfigBean eurekaInstanceConfig() {
|
|
EurekaInstanceConfigBean b = new EurekaInstanceConfigBean();
|
|
AmazonInfo info = AmazonInfo.Builder.newBuilder().autoBuild("eureka");
|
|
b.setDataCenterInfo(info);
|
|
return b;
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_changing_the_eureka_instance_id">Changing the Eureka Instance ID</h4>
|
|
<div class="paragraph">
|
|
<p>A vanilla Netflix Eureka instance is registered with an ID that is equal to its host name (i.e. only one service per host). Spring Cloud Eureka provides a sensible default that looks like this: <code>${spring.cloud.client.hostname}:${spring.application.name}:${spring.application.instance_id:${server.port}}}</code>. For example <code>myhost:myappname:8080</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Using Spring Cloud you can override this by providing a unique identifier in <code>eureka.instance.instanceId</code>. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>eureka:
|
|
instance:
|
|
instanceId: ${spring.application.name}:${spring.application.instance_id:${random.value}}</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>With this metadata, and multiple service instances deployed on
|
|
localhost, the random value will kick in there to make the instance
|
|
unique. In Cloudfoundry the <code>spring.application.instance_id</code> will be
|
|
populated automatically in a Spring Boot Actuator application, so the
|
|
random value will not be needed.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_using_the_eurekaclient">Using the EurekaClient</h3>
|
|
<div class="paragraph">
|
|
<p>Once you have an app that is <code>@EnableDiscoveryClient</code> (or <code>@EnableEurekaClient</code>) you can use it to
|
|
discover service instances from the <a href="#spring-cloud-eureka-server">Eureka Server</a>. One way to do that is to use the native
|
|
<code>com.netflix.discovery.EurekaClient</code> (as opposed to the Spring
|
|
Cloud <code>DiscoveryClient</code>), e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>@Autowired
|
|
private EurekaClient discoveryClient;
|
|
|
|
public String serviceUrl() {
|
|
InstanceInfo instance = discoveryClient.getNextServerFromEureka("STORES", false);
|
|
return instance.getHomePageUrl();
|
|
}</pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Tip</div>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>Don’t use the <code>EurekaClient</code> in <code>@PostConstruct</code> method or in a
|
|
<code>@Scheduled</code> method (or anywhere where the <code>ApplicationContext</code> might
|
|
not be started yet). It is initialized in a <code>SmartLifecycle</code> (with
|
|
<code>phase=0</code>) so the earliest you can rely on it being available is in
|
|
another <code>SmartLifecycle</code> with higher phase.</p>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_alternatives_to_the_native_netflix_eurekaclient">Alternatives to the native Netflix EurekaClient</h3>
|
|
<div class="paragraph">
|
|
<p>You don’t have to use the raw Netflix <code>EurekaClient</code> and usually it
|
|
is more convenient to use it behind a wrapper of some sort. Spring
|
|
Cloud has support for <a href="#spring-cloud-feign">Feign</a> (a REST client
|
|
builder) and also <a href="#spring-cloud-ribbon">Spring <code>RestTemplate</code></a> using
|
|
the logical Eureka service identifiers (VIPs) instead of physical
|
|
URLs. To configure Ribbon with a fixed list of physical servers you
|
|
can simply set <code><client>.ribbon.listOfServers</code> to a comma-separated
|
|
list of physical addresses (or hostnames), where <code><client></code> is the ID
|
|
of the client.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can also use the <code>org.springframework.cloud.client.discovery.DiscoveryClient</code>
|
|
which provides a simple API for discovery clients that is not specific
|
|
to Netflix, e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>@Autowired
|
|
private DiscoveryClient discoveryClient;
|
|
|
|
public String serviceUrl() {
|
|
List<ServiceInstance> list = discoveryClient.getInstances("STORES");
|
|
if (list != null && list.size() > 0 ) {
|
|
return list.get(0).getUri();
|
|
}
|
|
return null;
|
|
}</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_why_is_it_so_slow_to_register_a_service">Why is it so Slow to Register a Service?</h3>
|
|
<div class="paragraph">
|
|
<p>Being an instance also involves a periodic heartbeat to the registry
|
|
(via the client’s <code>serviceUrl</code>) with default duration 30 seconds. A
|
|
service is not available for discovery by clients until the instance,
|
|
the server and the client all have the same metadata in their local
|
|
cache (so it could take 3 heartbeats). You can change the period using
|
|
<code>eureka.instance.leaseRenewalIntervalInSeconds</code> and this will speed up
|
|
the process of getting clients connected to other services. In
|
|
production it’s probably better to stick with the default because
|
|
there are some computations internally in the server that make
|
|
assumptions about the lease renewal period.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-eureka-server">Service Discovery: Eureka Server</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Example eureka server (e.g. using spring-cloud-starter-eureka-server to set up the classpath):</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@SpringBootApplication
|
|
@EnableEurekaServer
|
|
public class Application {
|
|
|
|
public static void main(String[] args) {
|
|
new SpringApplicationBuilder(Application.class).web(true).run(args);
|
|
}
|
|
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The server has a home page with a UI, and HTTP API endpoints per the
|
|
normal Eureka functionality under <code>/eureka/*</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Eureka background reading: see <a href="https://github.com/cfregly/fluxcapacitor/wiki/NetflixOSS-FAQ#eureka-service-discovery-load-balancer">flux capacitor</a> and <a href="https://groups.google.com/forum/?fromgroups#!topic/eureka_netflix/g3p2r7gHnN0">google group discussion</a>.</p>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Tip</div>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>Due to Gradle’s dependency resolution rules and the lack of a parent bom feature, simply depending on spring-cloud-starter-eureka-server can cause failures on application startup. To remedy this the Spring Boot Gradle plugin must be added and the Spring cloud starter parent bom must be imported like so:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">build.gradle</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">buildscript {
|
|
dependencies {
|
|
classpath("org.springframework.boot:spring-boot-gradle-plugin:1.3.5.RELEASE")
|
|
}
|
|
}
|
|
|
|
apply plugin: "spring-boot"
|
|
|
|
dependencyManagement {
|
|
imports {
|
|
mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_high_availability_zones_and_regions">High Availability, Zones and Regions</h3>
|
|
<div class="paragraph">
|
|
<p>The Eureka server does not have a backend store, but the service
|
|
instances in the registry all have to send heartbeats to keep their
|
|
registrations up to date (so this can be done in memory). Clients also
|
|
have an in-memory cache of eureka registrations (so they don’t have to
|
|
go to the registry for every single request to a service).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>By default every Eureka server is also a Eureka client and requires
|
|
(at least one) service URL to locate a peer. If you don’t provide it
|
|
the service will run and work, but it will shower your logs with a lot
|
|
of noise about not being able to register with the peer.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>See also <a href="#spring-cloud-ribbon">below for details of Ribbon
|
|
support</a> on the client side for Zones and Regions.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_standalone_mode">Standalone Mode</h3>
|
|
<div class="paragraph">
|
|
<p>The combination of the two caches (client and server) and the
|
|
heartbeats make a standalone Eureka server fairly resilient to
|
|
failure, as long as there is some sort of monitor or elastic runtime
|
|
keeping it alive (e.g. Cloud Foundry). In standalone mode, you might
|
|
prefer to switch off the client side behaviour, so it doesn’t keep
|
|
trying and failing to reach its peers. Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml (Standalone Eureka Server)</div>
|
|
<div class="content">
|
|
<pre>server:
|
|
port: 8761
|
|
|
|
eureka:
|
|
instance:
|
|
hostname: localhost
|
|
client:
|
|
registerWithEureka: false
|
|
fetchRegistry: false
|
|
serviceUrl:
|
|
defaultZone: http://${eureka.instance.hostname}:${server.port}/eureka/</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Notice that the <code>serviceUrl</code> is pointing to the same host as the local
|
|
instance.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_peer_awareness">Peer Awareness</h3>
|
|
<div class="paragraph">
|
|
<p>Eureka can be made even more resilient and available by running
|
|
multiple instances and asking them to register with each other. In
|
|
fact, this is the default behaviour, so all you need to do to make it
|
|
work is add a valid <code>serviceUrl</code> to a peer, e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml (Two Peer Aware Eureka Servers)</div>
|
|
<div class="content">
|
|
<pre>---
|
|
spring:
|
|
profiles: peer1
|
|
eureka:
|
|
instance:
|
|
hostname: peer1
|
|
client:
|
|
serviceUrl:
|
|
defaultZone: http://peer2/eureka/
|
|
|
|
---
|
|
spring:
|
|
profiles: peer2
|
|
eureka:
|
|
instance:
|
|
hostname: peer2
|
|
client:
|
|
serviceUrl:
|
|
defaultZone: http://peer1/eureka/</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In this example we have a YAML file that can be used to run the same
|
|
server on 2 hosts (peer1 and peer2), by running it in different
|
|
Spring profiles. You could use this configuration to test the peer
|
|
awareness on a single host (there’s not much value in doing that in
|
|
production) by manipulating <code>/etc/hosts</code> to resolve the host names. In
|
|
fact, the <code>eureka.instance.hostname</code> is not needed if you are running
|
|
on a machine that knows its own hostname (it is looked up using
|
|
<code>java.net.InetAddress</code> by default).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can add multiple peers to a system, and as long as they are all
|
|
connected to each other by at least one edge, they will synchronize
|
|
the registrations amongst themselves. If the peers are physically
|
|
separated (inside a data centre or between multiple data centres) then
|
|
the system can in principle survive split-brain type failures.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_prefer_ip_address">Prefer IP Address</h3>
|
|
<div class="paragraph">
|
|
<p>In some cases, it is preferable for Eureka to advertise the IP Adresses
|
|
of services rather than the hostname. Set <code>eureka.instance.preferIpAddress</code>
|
|
to <code>true</code> and when the application registers with eureka, it will use its
|
|
IP Address rather than its hostname.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_circuit_breaker_hystrix_clients">Circuit Breaker: Hystrix Clients</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Netflix has created a library called <a href="https://github.com/Netflix/Hystrix">Hystrix</a> that implements the <a href="http://martinfowler.com/bliki/CircuitBreaker.html">circuit breaker pattern</a>. In a microservice architecture it is common to have multiple layers of service calls.</p>
|
|
</div>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<img src="images/HystrixGraph.png" alt="HystrixGraph">
|
|
</div>
|
|
<div class="title">Figure 1. Microservice Graph</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>A service failure in the lower level of services can cause cascading failure all the way up to the user. When calls to a particular service reach a certain threshold (20 failures in 5 seconds is the default in Hystrix), the circuit opens and the call is not made. In cases of error and an open circuit a fallback can be provided by the developer.</p>
|
|
</div>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<img src="images/HystrixFallback.png" alt="HystrixFallback">
|
|
</div>
|
|
<div class="title">Figure 2. Hystrix fallback prevents cascading failures</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Having an open circuit stops cascading failures and allows overwhelmed or failing services time to heal. The fallback can be another Hystrix protected call, static data or a sane empty value. Fallbacks may be chained so the first fallback makes some other business call which in turn falls back to static data.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Example boot app:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>@SpringBootApplication
|
|
@EnableCircuitBreaker
|
|
public class Application {
|
|
|
|
public static void main(String[] args) {
|
|
new SpringApplicationBuilder(Application.class).web(true).run(args);
|
|
}
|
|
|
|
}
|
|
|
|
@Component
|
|
public class StoreIntegration {
|
|
|
|
@HystrixCommand(fallbackMethod = "defaultStores")
|
|
public Object getStores(Map<String, Object> parameters) {
|
|
//do stuff that might fail
|
|
}
|
|
|
|
public Object defaultStores(Map<String, Object> parameters) {
|
|
return /* something useful */;
|
|
}
|
|
}</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>@HystrixCommand</code> is provided by a Netflix contrib library called
|
|
<a href="https://github.com/Netflix/Hystrix/tree/master/hystrix-contrib/hystrix-javanica">"javanica"</a>.
|
|
Spring Cloud automatically wraps Spring beans with that
|
|
annotation in a proxy that is connected to the Hystrix circuit
|
|
breaker. The circuit breaker calculates when to open and close the
|
|
circuit, and what to do in case of a failure.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To configure the <code>@HystrixCommand</code> you can use the <code>commandProperties</code>
|
|
attribute with a list of <code>@HystrixProperty</code> annotations. See
|
|
<a href="https://github.com/Netflix/Hystrix/tree/master/hystrix-contrib/hystrix-javanica#configuration">here</a>
|
|
for more details. See the <a href="https://github.com/Netflix/Hystrix/wiki/Configuration">Hystrix wiki</a>
|
|
for details on the properties available.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_propagating_the_security_context_or_using_spring_scopes">Propagating the Security Context or using Spring Scopes</h3>
|
|
<div class="paragraph">
|
|
<p>If you want some thread local context to propagate into a <code>@HystrixCommand</code> the default declaration will not work because it executes the command in a thread pool (in case of timeouts). You can switch Hystrix to use the same thread as the caller using some configuration, or directly in the annotation, by asking it to use a different "Isolation Strategy". For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@HystrixCommand(fallbackMethod = "stubMyService",
|
|
commandProperties = {
|
|
@HystrixProperty(name="execution.isolation.strategy", value="SEMAPHORE")
|
|
}
|
|
)
|
|
...</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The same thing applies if you are using <code>@SessionScope</code> or <code>@RequestScope</code>. You will know when you need to do this because of a runtime exception that says it can’t find the scoped context.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_health_indicator_2">Health Indicator</h3>
|
|
<div class="paragraph">
|
|
<p>The state of the connected circuit breakers are also exposed in the
|
|
<code>/health</code> endpoint of the calling application.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-json" data-lang="json">{
|
|
"hystrix": {
|
|
"openCircuitBreakers": [
|
|
"StoreIntegration::getStoresByLocationLink"
|
|
],
|
|
"status": "CIRCUIT_OPEN"
|
|
},
|
|
"status": "UP"
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_hystrix_metrics_stream">Hystrix Metrics Stream</h3>
|
|
<div class="paragraph">
|
|
<p>To enable the Hystrix metrics stream include a dependency on <code>spring-boot-starter-actuator</code>. This will expose the <code>/hystrix.stream</code> as a management endpoint.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-xml" data-lang="xml"> <dependency>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-starter-actuator</artifactId>
|
|
</dependency></code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_circuit_breaker_hystrix_dashboard">Circuit Breaker: Hystrix Dashboard</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>One of the main benefits of Hystrix is the set of metrics it gathers about each HystrixCommand. The Hystrix Dashboard displays the health of each circuit breaker in an efficient manner.</p>
|
|
</div>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<img src="images/Hystrix.png" alt="Hystrix">
|
|
</div>
|
|
<div class="title">Figure 3. Hystrix Dashboard</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To run the Hystrix Dashboard annotate your Spring Boot main class with <code>@EnableHystrixDashboard</code>. You then visit <code>/hystrix</code> and point the dashboard to an individual instances <code>/hystrix.stream</code> endpoint in a Hystrix client application.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_turbine">Turbine</h3>
|
|
<div class="paragraph">
|
|
<p>Looking at an individual instances Hystrix data is not very useful in terms of the overall health of the system. <a href="https://github.com/Netflix/Turbine">Turbine</a> is an application that aggregates all of the relevant <code>/hystrix.stream</code> endpoints into a combined <code>/turbine.stream</code> for use in the Hystrix Dashboard. Individual instances are located via Eureka. Running Turbine is as simple as annotating your main class with the <code>@EnableTurbine</code> annotation (e.g. using spring-cloud-starter-turbine to set up the classpath). All of the documented configuration properties from <a href="https://github.com/Netflix/Turbine/wiki/Configuration-(1.x)">the Turbine 1 wiki</a> apply. The only difference is that the <code>turbine.instanceUrlSuffix</code> does not need the port prepended as this is handled automatically unless <code>turbine.instanceInsertPort=false</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The configuration key <code>turbine.appConfig</code> is a list of eureka serviceIds that turbine will use to lookup instances. The turbine stream is then used in the Hystrix dashboard using a url that looks like: <code><a href="http://my.turbine.sever:8080/turbine.stream?cluster=<CLUSTERNAME>" class="bare">http://my.turbine.sever:8080/turbine.stream?cluster=<CLUSTERNAME></a>;</code> (the cluster parameter can be omitted if the name is "default"). The <code>cluster</code> parameter must match an entry in <code>turbine.aggregator.clusterConfig</code>. Values returned from eureka are uppercase, thus we expect this example to work if there is an app registered with Eureka called "customers":</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>turbine:
|
|
aggregator:
|
|
clusterConfig: CUSTOMERS
|
|
appConfig: customers</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>clusterName</code> can be customized by a SPEL expression in <code>turbine.clusterNameExpression</code> with root an instance of <code>InstanceInfo</code>. The default value is <code>appName</code>, which means that the Eureka serviceId ends up as the cluster key (i.e. the <code>InstanceInfo</code> for customers has an <code>appName</code> of "CUSTOMERS"). A different example would be <code>turbine.clusterNameExpression=aSGName</code>, which would get the cluster name from the AWS ASG name. Another example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>turbine:
|
|
aggregator:
|
|
clusterConfig: SYSTEM,USER
|
|
appConfig: customers,stores,ui,admin
|
|
clusterNameExpression: metadata['cluster']</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In this case, the cluster name from 4 services is pulled from their metadata map, and is expected to have values that include "SYSTEM" and "USER".</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To use the "default" cluster for all apps you need a string literal expression (with single quotes, and escaped with double quotes if it is in YAML as well):</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>turbine:
|
|
appConfig: customers,stores
|
|
clusterNameExpression: "'default'"</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud provides a <code>spring-cloud-starter-turbine</code> that has all the dependencies you need to get a Turbine server running. Just create a Spring Boot application and annotate it with <code>@EnableTurbine</code>.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
by default the native Netflix behaviour built into Turbine does <em>not</em> allow multiple processes per host, per cluster (the key to the instance id is the hostname). Spring Cloud generalizes this a bit, allowing the host and port to be used as the key, but only if you set the property <code>turbine.combineHostPort=true</code>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_turbine_stream">Turbine Stream</h3>
|
|
<div class="paragraph">
|
|
<p>In some environments (e.g. in a PaaS setting), the classic Turbine model of pulling metrics from all the distributed Hystrix commands doesn’t work. In that case you might want to have your Hystrix commands push metrics to Turbine, and Spring Cloud enables that with messaging. All you need to do on the client is add a dependency to <code>spring-cloud-netflix-hystrix-stream</code> and the <code>spring-cloud-starter-stream-*</code> of your choice (see Spring Cloud Stream documentation for details on the brokers, and how to configure the client credentials, but it should work out of the box for a local broker).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>On the server side Just create a Spring Boot application and annotate it with <code>@EnableTurbineStream</code> and by default it will come up on port 8989 (point your Hystrix dashboard to that port, any path). You can customize the port using either <code>server.port</code> or <code>turbine.stream.port</code>. If you have <code>spring-boot-starter-web</code> and <code>spring-boot-starter-actuator</code> on the classpath as well, then you can open up the Actuator endpoints on a separate port (with Tomcat by default) by providing a <code>management.port</code> which is different.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can then point the Hystrix Dashboard to the Turbine Stream Server instead of individual Hystrix streams. If Turbine Stream is running on port 8989 on myhost, then put <code><a href="http://myhost:8989" class="bare">http://myhost:8989</a></code> in the stream input field in the Hystrix Dashboard. Circuits will be prefixed by their respective serviceId, followed by a dot, then the circuit name.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud provides a <code>spring-cloud-starter-turbine-stream</code> that has all the dependencies you need to get a Turbine Stream server running - just add the Stream binder of your choice, e.g. <code>spring-cloud-starter-stream-rabbit</code>. You need Java 8 to run the app because it is Netty-based.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-ribbon">Client Side Load Balancer: Ribbon</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Ribbon is a client side load balancer which gives you a lot of control
|
|
over the behaviour of HTTP and TCP clients. Feign already uses Ribbon,
|
|
so if you are using <code>@FeignClient</code> then this section also applies.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>A central concept in Ribbon is that of the named client. Each load
|
|
balancer is part of an ensemble of components that work together to
|
|
contact a remote server on demand, and the ensemble has a name that
|
|
you give it as an application developer (e.g. using the <code>@FeignClient</code>
|
|
annotation). Spring Cloud creates a new ensemble as an
|
|
<code>ApplicationContext</code> on demand for each named client using
|
|
<code>RibbonClientConfiguration</code>. This contains (amongst other things) an
|
|
<code>ILoadBalancer</code>, a <code>RestClient</code>, and a <code>ServerListFilter</code>.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_customizing_the_ribbon_client">Customizing the Ribbon Client</h3>
|
|
<div class="paragraph">
|
|
<p>You can configure some bits of a Ribbon client using external
|
|
properties in <code><client>.ribbon.*</code>, which is no different than using
|
|
the Netflix APIs natively, except that you can use Spring Boot
|
|
configuration files. The native options can
|
|
be inspected as static fields in <code>CommonClientConfigKey</code> (part of
|
|
ribbon-core).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud also lets you take full control of the client by
|
|
declaring additional configuration (on top of the
|
|
<code>RibbonClientConfiguration</code>) using <code>@RibbonClient</code>. Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Configuration
|
|
@RibbonClient(name = "foo", configuration = FooConfiguration.class)
|
|
public class TestConfiguration {
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In this case the client is composed from the components already in
|
|
<code>RibbonClientConfiguration</code> together with any in <code>FooConfiguration</code>
|
|
(where the latter generally will override the former).</p>
|
|
</div>
|
|
<div class="admonitionblock warning">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Warning</div>
|
|
</td>
|
|
<td class="content">
|
|
The <code>FooConfiguration</code> has to be <code>@Configuration</code> but take
|
|
care that it is not in a <code>@ComponentScan</code> for the main application
|
|
context, otherwise it will be shared by all the <code>@RibbonClients</code>. If
|
|
you use <code>@ComponentScan</code> (or <code>@SpringBootApplication</code>) you need to
|
|
take steps to avoid it being included (for instance put it in a
|
|
separate, non-overlapping package, or specify the packages to scan
|
|
explicitly in the <code>@ComponentScan</code>).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Netflix provides the following beans by default for ribbon
|
|
(<code>BeanType</code> beanName: <code>ClassName</code>):</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><code>IClientConfig</code> ribbonClientConfig: <code>DefaultClientConfigImpl</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>IRule</code> ribbonRule: <code>ZoneAvoidanceRule</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>IPing</code> ribbonPing: <code>NoOpPing</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>ServerList<Server></code> ribbonServerList: <code>ConfigurationBasedServerList</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>ServerListFilter<Server></code> ribbonServerListFilter: <code>ZonePreferenceServerListFilter</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>ILoadBalancer</code> ribbonLoadBalancer: <code>ZoneAwareLoadBalancer</code></p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Creating a bean of one of those type and placing it in a <code>@RibbonClient</code>
|
|
configuration (such as <code>FooConfiguration</code> above) allows you to override each
|
|
one of the beans described. Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Configuration
|
|
public class FooConfiguration {
|
|
@Bean
|
|
public IPing ribbonPing(IClientConfig config) {
|
|
return new PingUrl();
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This replaces the <code>NoOpPing</code> with <code>PingUrl</code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_using_ribbon_with_eureka">Using Ribbon with Eureka</h3>
|
|
<div class="paragraph">
|
|
<p>When Eureka is used in conjunction with Ribbon the <code>ribbonServerList</code>
|
|
is overridden with an extension of <code>DiscoveryEnabledNIWSServerList</code>
|
|
which populates the list of servers from Eureka. It also replaces the
|
|
<code>IPing</code> interface with <code>NIWSDiscoveryPing</code> which delegates to Eureka
|
|
to determine if a server is up. The <code>ServerList</code> that is installed by
|
|
default is a <code>DomainExtractingServerList</code> and the purpose of this is
|
|
to make physical metadata available to the load balancer without using
|
|
AWS AMI metadata (which is what Netflix relies on). By default the
|
|
server list will be constructed with "zone" information as provided in
|
|
the instance metadata (so on the remote clients set
|
|
<code>eureka.instance.metadataMap.zone</code>), and if that is missing it can use
|
|
the domain name from the server hostname as a proxy for zone (if the
|
|
flag <code>approximateZoneFromHostname</code> is set). Once the zone information
|
|
is available it can be used in a <code>ServerListFilter</code>. By default it
|
|
will be used to locate a server in the same zone as the client because
|
|
the default is a <code>ZonePreferenceServerListFilter</code>. The zone of the
|
|
client is determined the same way as the remote instances by default,
|
|
i.e. via <code>eureka.instance.metadataMap.zone</code>.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
The orthodox "archaius" way to set the client zone is via a
|
|
configuration property called "@zone", and Spring Cloud will use that
|
|
in preference to all other settings if it is available (note that the
|
|
key will have to be quoted in YAML configuration).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
If there is no other source of zone data then a guess is made
|
|
based on the client configuration (as opposed to the instance
|
|
configuration). We take <code>eureka.client.availabilityZones</code>, which is a
|
|
map from region name to a list of zones, and pull out the first zone
|
|
for the instance’s own region (i.e. the <code>eureka.client.region</code>, which
|
|
defaults to "us-east-1" for comatibility with native Netflix).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="spring-cloud-ribbon-without-eureka">Example: How to Use Ribbon Without Eureka</h3>
|
|
<div class="paragraph">
|
|
<p>Eureka is a convenient way to abstract the discovery of remote servers
|
|
so you don’t have to hard code their URLs in clients, but if you
|
|
prefer not to use it, Ribbon and Feign are still quite
|
|
amenable. Suppose you have declared a <code>@RibbonClient</code> for "stores",
|
|
and Eureka is not in use (and not even on the classpath). The Ribbon
|
|
client defaults to a configured server list, and you can supply the
|
|
configuration like this</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>stores:
|
|
ribbon:
|
|
listOfServers: example.com,google.com</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_example_disable_eureka_use_in_ribbon">Example: Disable Eureka use in Ribbon</h3>
|
|
<div class="paragraph">
|
|
<p>Setting the property <code>ribbon.eureka.enabled = false</code> will explicitly
|
|
disable the use of Eureka in Ribbon.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>ribbon:
|
|
eureka:
|
|
enabled: false</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_using_the_ribbon_api_directly">Using the Ribbon API Directly</h3>
|
|
<div class="paragraph">
|
|
<p>You can also use the <code>LoadBalancerClient</code> directly. Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">public class MyClass {
|
|
@Autowired
|
|
private LoadBalancerClient loadBalancer;
|
|
|
|
public void doStuff() {
|
|
ServiceInstance instance = loadBalancer.choose("stores");
|
|
URI storesUri = URI.create(String.format("http://%s:%s", instance.getHost(), instance.getPort()));
|
|
// ... do something with the URI
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-feign">Declarative REST Client: Feign</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p><a href="https://github.com/Netflix/feign">Feign</a> is a declarative web service client. It makes writing web service clients easier. To use Feign create an interface and annotate it. It has pluggable annotation support including Feign annotations and JAX-RS annotations. Feign also supports pluggable encoders and decoders. Spring Cloud adds support for Spring MVC annotations and for using the same <code>HttpMessageConverters</code> used by default in Spring Web. Spring Cloud integrates Ribbon and Eureka to provide a load balanced http client when using Feign.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Example spring boot app</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Configuration
|
|
@ComponentScan
|
|
@EnableAutoConfiguration
|
|
@EnableEurekaClient
|
|
@EnableFeignClients
|
|
public class Application {
|
|
|
|
public static void main(String[] args) {
|
|
SpringApplication.run(Application.class, args);
|
|
}
|
|
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">StoreClient.java</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@FeignClient("stores")
|
|
public interface StoreClient {
|
|
@RequestMapping(method = RequestMethod.GET, value = "/stores")
|
|
List<Store> getStores();
|
|
|
|
@RequestMapping(method = RequestMethod.POST, value = "/stores/{storeId}", consumes = "application/json")
|
|
Store update(@PathVariable("storeId") Long storeId, Store store);
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In the <code>@FeignClient</code> annotation the String value ("stores" above) is
|
|
an arbitrary client name, which is used to create a Ribbon load
|
|
balancer (see <a href="#spring-cloud-ribbon">below for details of Ribbon
|
|
support</a>). You can also specify a URL using the <code>url</code> attribute
|
|
(absolute value or just a hostname). The name of the bean in the application context is the fully qualified name of the interface. An alias is also created which is the 'name' attribute plus 'FeignClient'. For the example above, <code>@Qualifier("storesFeignClient")</code> could be used to reference the bean.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The Ribbon client above will want to discover the physical addresses
|
|
for the "stores" service. If your application is a Eureka client then
|
|
it will resolve the service in the Eureka service registry. If you
|
|
don’t want to use Eureka, you can simply configure a list of servers
|
|
in your external configuration (see
|
|
<a href="#spring-cloud-ribbon-without-eureka">above for example</a>).</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="spring-cloud-feign-overriding-defaults">Overriding Feign Defaults</h3>
|
|
<div class="paragraph">
|
|
<p>A central concept in Spring Cloud’s Feign support is that of the named client. Each feign client is part of an ensemble of components that work together to contact a remote server on demand, and the ensemble has a name that you give it as an application developer using the <code>@FeignClient</code> annotation. Spring Cloud creates a new ensemble as an
|
|
<code>ApplicationContext</code> on demand for each named client using <code>FeignClientsConfiguration</code>. This contains (amongst other things) an <code>feign.Decoder</code>, a <code>feign.Encoder</code>, and a <code>feign.Contract</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud lets you take full control of the feign client by declaring additional configuration (on top of the <code>FeignClientsConfiguration</code>) using <code>@FeignClient</code>. Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@FeignClient(name = "stores", configuration = FooConfiguration.class)
|
|
public interface StoreClient {
|
|
//..
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In this case the client is composed from the components already in <code>FeignClientsConfiguration</code> together with any in <code>FooConfiguration</code> (where the latter will override the former).</p>
|
|
</div>
|
|
<div class="admonitionblock warning">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Warning</div>
|
|
</td>
|
|
<td class="content">
|
|
The <code>FooConfiguration</code> has to be <code>@Configuration</code> but take care that it is not in a <code>@ComponentScan</code> for the main application context, otherwise it will be used for every <code>@FeignClient</code>. If you use <code>@ComponentScan</code> (or <code>@SpringBootApplication</code>) you need to take steps to avoid it being included (for instance put it in a separate, non-overlapping package, or specify the packages to scan explicitly in the <code>@ComponentScan</code>).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
The <code>serviceId</code> attribute is now deprecated in favor of the <code>name</code> attribute.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="admonitionblock warning">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Warning</div>
|
|
</td>
|
|
<td class="content">
|
|
Previously, using the <code>url</code> attribute, did not require the <code>name</code> attribute. Using <code>name</code> is now required.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Placeholders are supported in the <code>name</code> and <code>url</code> attributes.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@FeignClient(name = "${feign.name}", url = "${feign.url}")
|
|
public interface StoreClient {
|
|
//..
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Netflix provides the following beans by default for feign (<code>BeanType</code> beanName: <code>ClassName</code>):</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><code>Decoder</code> feignDecoder: <code>ResponseEntityDecoder</code> (which wraps a <code>SpringDecoder</code>)</p>
|
|
</li>
|
|
<li>
|
|
<p><code>Encoder</code> feignEncoder: <code>SpringEncoder</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>Logger</code> feignLogger: <code>Slf4jLogger</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>Contract</code> feignContract: <code>SpringMvcContract</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>Feign.Builder</code> feignBuilder: <code>HystrixFeign.Builder</code></p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Netflix <em>does not</em> provide the following beans by default for feign, but still looks up beans of these types from the application context to create the feign client:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><code>Logger.Level</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>Retryer</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>ErrorDecoder</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>Request.Options</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>Collection<RequestInterceptor></code></p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Creating a bean of one of those type and placing it in a <code>@FeignClient</code> configuration (such as <code>FooConfiguration</code> above) allows you to override each one of the beans described. Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Configuration
|
|
public class FooConfiguration {
|
|
@Bean
|
|
public Contract feignContract() {
|
|
return new feign.Contract.Default();
|
|
}
|
|
|
|
@Bean
|
|
public BasicAuthRequestInterceptor basicAuthRequestInterceptor() {
|
|
return new BasicAuthRequestInterceptor("user", "password");
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This replaces the <code>SpringMvcContract</code> with <code>feign.Contract.Default</code> and adds a <code>RequestInterceptor</code> to the collection of <code>RequestInterceptor</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Default configurations can be specified in the <code>@EnableFeignClients</code> attribute <code>defaultConfiguration</code> in a similar manner as described above. The difference is that this configuration will apply to <em>all</em> feign clients.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="spring-cloud-feign-hystrix">Feign Hystrix Support</h3>
|
|
<div class="paragraph">
|
|
<p>If Hystrix is on the classpath, by default Feign will wrap all methods with a circuit breaker. Returning a <code>com.netflix.hystrix.HystrixCommand</code> is also available. This lets you use reactive patterns (with a call to <code>.toObservable()</code> or <code>.observe()</code> or asynchronous use (with a call to <code>.queue()</code>).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To disable Hystrix support for Feign, set <code>feign.hystrix.enabled=false</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To disable Hystrix support on a per-client basis create a vanilla <code>Feign.Builder</code> with the "prototype" scope, e.g.:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Configuration
|
|
public class FooConfiguration {
|
|
@Bean
|
|
@Scope("prototype")
|
|
public Feign.Builder feignBuilder() {
|
|
return Feign.builder();
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="spring-cloud-feign-hystrix-fallback">Feign Hystrix Fallbacks</h3>
|
|
<div class="paragraph">
|
|
<p>Hystrix supports the notion of a fallback: a default code path that is executed when they circuit is open or there is an error. To enable fallbacks for a given <code>@FeignClient</code> set the <code>fallback</code> attribute to the class name that implements the fallback.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@FeignClient(name = "hello", fallback = HystrixClientFallback.class)
|
|
protected interface HystrixClient {
|
|
@RequestMapping(method = RequestMethod.GET, value = "/hello")
|
|
Hello iFailSometimes();
|
|
}
|
|
|
|
static class HystrixClientFallback implements HystrixClient {
|
|
@Override
|
|
public Hello iFailSometimes() {
|
|
return new Hello("fallback");
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock warning">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Warning</div>
|
|
</td>
|
|
<td class="content">
|
|
There is a limitation with the implementation of fallbacks in Feign and how Hystrix fallbacks work. Fallbacks are currently not supported for methods that return <code>com.netflix.hystrix.HystrixCommand</code> and <code>rx.Observable</code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="spring-cloud-feign-inheritance">Feign Inheritance Support</h3>
|
|
<div class="paragraph">
|
|
<p>Feign supports boilerplate apis via single-inheritance interfaces.
|
|
This allows grouping common operations into convenient base interfaces.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">UserService.java</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">public interface UserService {
|
|
|
|
@RequestMapping(method = RequestMethod.GET, value ="/users/{id}")
|
|
User getUser(@PathVariable("id") long id);
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">UserResource.java</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@RestController
|
|
public class UserResource implements UserService {
|
|
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">UserClient.java</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">package project.user;
|
|
|
|
@FeignClient("users")
|
|
public interface UserClient extends UserService {
|
|
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
It is generally not advisable to share an interface between a
|
|
server and a client. It introduces tight coupling, and also actually
|
|
doesn’t work with Spring MVC in its current form (method parameter
|
|
mapping is not inherited).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_feign_request_response_compression">Feign request/response compression</h3>
|
|
<div class="paragraph">
|
|
<p>You may consider enabling the request or response GZIP compression for your
|
|
Feign requests. You can do this by enabling one of the properties:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">feign.compression.request.enabled=true
|
|
feign.compression.response.enabled=true</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Feign request compression gives you settings similar to what you may set for your web server:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">feign.compression.request.enabled=true
|
|
feign.compression.request.mime-types=text/xml,application/xml,application/json
|
|
feign.compression.request.min-request-size=2048</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>These properties allow you to be selective about the compressed media types and minimum request threshold length.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_feign_logging">Feign logging</h3>
|
|
<div class="paragraph">
|
|
<p>A logger is created for each Feign client created. By default the name of the logger is the full class name of the interface used to create the Feign client. Feign logging only responds to the <code>DEBUG</code> level.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">logging.level.project.user.UserClient: DEBUG</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>Logger.Level</code> object that you may configure per client, tells Feign how much to log. Choices are:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><code>NONE</code>, No logging (<strong>DEFAULT</strong>).</p>
|
|
</li>
|
|
<li>
|
|
<p><code>BASIC</code>, Log only the request method and URL and the response status code and execution time.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>HEADERS</code>, Log the basic information along with request and response headers.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>FULL</code>, Log the headers, body, and metadata for both requests and responses.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>For example, the following would set the <code>Logger.Level</code> to <code>FULL</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Configuration
|
|
public class FooConfiguration {
|
|
@Bean
|
|
Logger.Level feignLoggerLevel() {
|
|
return Logger.Level.FULL;
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_external_configuration_archaius">External Configuration: Archaius</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p><a href="https://github.com/Netflix/archaius">Archaius</a> is the Netflix client side configuration library. It is the library used by all of the Netflix OSS components for configuration. Archaius is an extension of the <a href="http://commons.apache.org/proper/commons-configuration">Apache Commons Configuration</a> project. It allows updates to configuration by either polling a source for changes or for a source to push changes to the client. Archaius uses Dynamic<Type>Property classes as handles to properties.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">Archaius Example</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">class ArchaiusTest {
|
|
DynamicStringProperty myprop = DynamicPropertyFactory
|
|
.getInstance()
|
|
.getStringProperty("my.prop");
|
|
|
|
void doSomething() {
|
|
OtherClass.someMethod(myprop.get());
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Archaius has its own set of configuration files and loading priorities. Spring applications should generally not use Archaius directly, but the need to configure the Netflix tools natively remains. Spring Cloud has a Spring Environment Bridge so Archaius can read properties from the Spring Environment. This allows Spring Boot projects to use the normal configuration toolchain, while allowing them to configure the Netflix tools, for the most part, as documented.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_router_and_filter_zuul">Router and Filter: Zuul</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Routing in an integral part of a microservice architecture. For example, <code>/</code> may be mapped to your web application, <code>/api/users</code> is mapped to the user service and <code>/api/shop</code> is mapped to the shop service. <a href="https://github.com/Netflix/zuul">Zuul</a> is a JVM based router and server side load balancer by Netflix.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><a href="http://www.slideshare.net/MikeyCohen1/edge-architecture-ieee-international-conference-on-cloud-engineering-32240146/27">Netflix uses Zuul</a> for the following:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>Authentication</p>
|
|
</li>
|
|
<li>
|
|
<p>Insights</p>
|
|
</li>
|
|
<li>
|
|
<p>Stress Testing</p>
|
|
</li>
|
|
<li>
|
|
<p>Canary Testing</p>
|
|
</li>
|
|
<li>
|
|
<p>Dynamic Routing</p>
|
|
</li>
|
|
<li>
|
|
<p>Service Migration</p>
|
|
</li>
|
|
<li>
|
|
<p>Load Shedding</p>
|
|
</li>
|
|
<li>
|
|
<p>Security</p>
|
|
</li>
|
|
<li>
|
|
<p>Static Response handling</p>
|
|
</li>
|
|
<li>
|
|
<p>Active/Active traffic management</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Zuul’s rule engine allows rules and filters to be written in essentially any JVM language, with built in support for Java and Groovy.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
The configuration property <code>zuul.max.host.connections</code> has been replaced by two new properties, <code>zuul.host.maxTotalConnections</code> and <code>zuul.host.maxPerRouteConnections</code> which default to 200 and 20 respectively.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="netflix-zuul-reverse-proxy">Embedded Zuul Reverse Proxy</h3>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud has created an embedded Zuul proxy to ease the
|
|
development of a very common use case where a UI application wants to
|
|
proxy calls to one or more back end services. This feature is useful
|
|
for a user interface to proxy to the backend services it requires,
|
|
avoiding the need to manage CORS and authentication concerns
|
|
independently for all the backends.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To enable it, annotate a Spring Boot main class with
|
|
<code>@EnableZuulProxy</code>, and this forwards local calls to the appropriate
|
|
service. By convention, a service with the ID "users", will
|
|
receive requests from the proxy located at <code>/users</code> (with the prefix
|
|
stripped). The proxy uses Ribbon to locate an instance to forward to
|
|
via discovery, and all requests are executed in a hystrix command, so
|
|
failures will show up in Hystrix metrics, and once the circuit is open
|
|
the proxy will not try to contact the service.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
the Zuul starter does not include a discovery client, so for
|
|
routes based on service IDs you need to provide one of those
|
|
on the classpath as well (e.g. Eureka is one choice).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To skip having a service automatically added, set
|
|
<code>zuul.ignored-services</code> to a list of service id patterns. If a service
|
|
matches a pattern that is ignored, but also included in the explicitly
|
|
configured routes map, then it will be unignored. Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml"> zuul:
|
|
ignoredServices: '*'
|
|
routes:
|
|
users: /myusers/**</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In this example, all services are ignored <strong>except</strong> "users".</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To augment or change
|
|
the proxy routes, you can add external configuration like the
|
|
following:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml"> zuul:
|
|
routes:
|
|
users: /myusers/**</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This means that http calls to "/myusers" get forwarded to the "users"
|
|
service (for example "/myusers/101" is forwarded to "/101").</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To get more fine-grained control over a route you can specify the path
|
|
and the serviceId independently:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml"> zuul:
|
|
routes:
|
|
users:
|
|
path: /myusers/**
|
|
serviceId: users_service</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This means that http calls to "/myusers" get forwarded to the
|
|
"users_service" service. The route has to have a "path" which can be
|
|
specified as an ant-style pattern, so "/myusers/*" only matches one
|
|
level, but "/myusers/**" matches hierarchically.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The location of the backend can be specified as either a "serviceId"
|
|
(for a service from discovery) or a "url" (for a physical location), e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml"> zuul:
|
|
routes:
|
|
users:
|
|
path: /myusers/**
|
|
url: http://example.com/users_service</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>These simple url-routes don’t get executed as a <code>HystrixCommand</code> nor can you loadbalance multiple URLs with Ribbon.
|
|
To achieve this, specify a service-route and configure a Ribbon client for the
|
|
serviceId (this currently requires disabling Eureka support in Ribbon:
|
|
see <a href="#spring-cloud-ribbon-without-eureka">above for more information</a>), e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">zuul:
|
|
routes:
|
|
users:
|
|
path: /myusers/**
|
|
serviceId: users
|
|
|
|
ribbon:
|
|
eureka:
|
|
enabled: false
|
|
|
|
users:
|
|
ribbon:
|
|
listOfServers: example.com,google.com</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can provide convention between serviceId and routes using
|
|
regexmapper. It uses regular expression named groups to extract
|
|
variables from serviceId and inject them into a route pattern.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">ApplicationConfiguration.java</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Bean
|
|
public PatternServiceRouteMapper serviceRouteMapper() {
|
|
return new PatternServiceRouteMapper(
|
|
"(?<name>^.+)-(?<version>v.+$)",
|
|
"${version}/${name}");
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This means that a serviceId "myusers-v1" will be mapped to route
|
|
"/v1/myusers/**". Any regular expression is accepted but all named
|
|
groups must be present in both servicePattern and routePattern. If
|
|
servicePattern does not match a serviceId, the default behavior is
|
|
used. In the example above, a serviceId "myusers" will be mapped to route
|
|
"/myusers/**" (no version detected) This feature is disable by
|
|
default and only applies to discovered services.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To add a prefix to all mappings, set <code>zuul.prefix</code> to a value, such as
|
|
<code>/api</code>. The proxy prefix is stripped from the request before the
|
|
request is forwarded by default (switch this behaviour off with
|
|
<code>zuul.stripPrefix=false</code>). You can also switch off the stripping of
|
|
the service-specific prefix from individual routes, e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml"> zuul:
|
|
routes:
|
|
users:
|
|
path: /myusers/**
|
|
stripPrefix: false</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In this example, requests to "/myusers/101" will be forwarded to "/myusers/101" on the "users" service.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>zuul.routes</code> entries actually bind to an object of type <code>ZuulProperties</code>. If you
|
|
look at the properties of that object you will see that it also has a "retryable" flag.
|
|
Set that flag to "true" to have the Ribbon client automatically retry failed requests
|
|
(and if you need to you can modify the parameters of the retry operations using
|
|
the Ribbon client configuration).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>X-Forwarded-Host</code> header is added to the forwarded requests by
|
|
default. To turn it off set <code>zuul.addProxyHeaders = false</code>. The
|
|
prefix path is stripped by default, and the request to the backend
|
|
picks up a header "X-Forwarded-Prefix" ("/myusers" in the examples
|
|
above).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>An application with <code>@EnableZuulProxy</code> could act as a standalone
|
|
server if you set a default route ("/"), for example <code>zuul.route.home:
|
|
/</code> would route all traffic (i.e. "/**") to the "home" service.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If more fine-grained ignoring is needed, you can specify specific patterns to ignore.
|
|
These patterns are evaluated at the start of the route location process, which
|
|
means prefixes should be included in the pattern to warrant a match. Ignored patterns
|
|
span all services and supersede any other route specification.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml"> zuul:
|
|
ignoredPatterns: /**/admin/**
|
|
routes:
|
|
users: /myusers/**</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This means that all calls such as "/myusers/101" will be forwarded to "/101" on the "users" service.
|
|
But calls including "/admin/" will not resolve.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_cookies_and_sensitive_headers">Cookies and Sensitive Headers</h3>
|
|
<div class="paragraph">
|
|
<p>It’s OK to share headers between services in the same system, but you
|
|
probably don’t want sensitive headers leaking downstream into external
|
|
servers. You can specify a list of ignored headers as part of the
|
|
route configuration. Cookies play a special role because they have
|
|
well-defined semantics in browsers, and they are always to be treated
|
|
as sensitive. If the consumer of your proxy is a browser, then cookies
|
|
for downstream services also cause problems for the user because they
|
|
all get jumbled up (all downstream services look like they come from
|
|
the same place).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you are careful with the design of your services, for example if
|
|
only one of the downstream services sets cookies, then you might be
|
|
able to let them flow from the backend all the way up to the
|
|
caller. Also, if your proxy sets cookies and all your back end
|
|
services are part of the same system, it can be natural to simply
|
|
share them (and for instance use Spring Session to link them up to some
|
|
shared state). Other than that, any cookies that get set by downstream
|
|
services are likely to be not very useful to the caller, so it is
|
|
recommended that you make (at least) "Set-Cookie" and "Cookie" into
|
|
sensitive headers for routes that are not part of your domain. Even
|
|
for routes that <strong>are</strong> part of your domain, try to think carefully
|
|
about what it means before allowing cookies to flow between them and
|
|
the proxy.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The sensitive headers can be configured as a comma-separated list per
|
|
route, e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml"> zuul:
|
|
routes:
|
|
users:
|
|
path: /myusers/**
|
|
sensitiveHeaders: Cookie,Set-Cookie,Authorization
|
|
url: https://downstream</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Sensitive headers can also be set globally by setting <code>zuul.sensitiveHeaders</code>. If <code>sensitiveHeaders</code> is set on a route, this will override the global <code>sensitiveHeaders</code> setting.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
this is the default value for <code>sensitiveHeaders</code>, so you don’t
|
|
need to set it unless you want it to be different. N.B. this is new in
|
|
Spring Cloud Netflix 1.1 (in 1.0 the user had no control over headers
|
|
and all cookies flow in both directions).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In addition to the per-route sensitive headers, you can set a global
|
|
value for <code>zuul.ignoredHeaders</code> for values that should be discarded
|
|
(both request and response) during interactions with downstream
|
|
services. By default these are empty, if Spring Security is not on the
|
|
classpath, and otherwise they are initialized to a set of well-known
|
|
"security" headers (e.g. involving caching) as specified by Spring
|
|
Security. The assumption in this case is that the downstream services
|
|
might add these headers too, and we want the values from the proxy.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_the_routes_endpoint">The Routes Endpoint</h3>
|
|
<div class="paragraph">
|
|
<p>If you are using <code>@EnableZuulProxy</code> with tha Spring Boot Actuator you
|
|
will enable (by default) an additional endpoint, available via HTTP as
|
|
<code>/routes</code>. A GET to this endpoint will return a list of the mapped
|
|
routes. A POST will force a refresh of the existing routes (e.g. in
|
|
case there have been changes in the service catalog).</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
the routes should respond automatically to changes in the
|
|
service catalog, but the POST to /routes is a way to force the change
|
|
to happen immediately.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_strangulation_patterns_and_local_forwards">Strangulation Patterns and Local Forwards</h3>
|
|
<div class="paragraph">
|
|
<p>A common pattern when migrating an existing application or API is to
|
|
"strangle" old endpoints, slowly replacing them with different
|
|
implementations. The Zuul proxy is a useful tool for this because you
|
|
can use it to handle all traffic from clients of the old endpoints,
|
|
but redirect some of the requests to new ones.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Example configuration:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml"> zuul:
|
|
routes:
|
|
first:
|
|
path: /first/**
|
|
url: http://first.example.com
|
|
second:
|
|
path: /second/**
|
|
url: forward:/second
|
|
third:
|
|
path: /third/**
|
|
url: forward:/3rd
|
|
legacy:
|
|
path: /**
|
|
url: http://legacy.example.com</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In this example we are strangling the "legacy" app which is mapped to
|
|
all requests that do not match one of the other patterns. Paths in
|
|
<code>/first/**</code> have been extracted into a new service with an external
|
|
URL. And paths in <code>/second/**</code> are forwared so they can be handled
|
|
locally, e.g. with a normal Spring <code>@RequestMapping</code>. Paths in
|
|
<code>/third/**</code> are also forwarded, but with a different prefix
|
|
(i.e. <code>/third/foo</code> is forwarded to <code>/3rd/foo</code>).</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
The ignored patterns aren’t completely ignored, they just
|
|
aren’t handled by the proxy (so they are also effectively forwarded
|
|
locally).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_uploading_files_through_zuul">Uploading Files through Zuul</h3>
|
|
<div class="paragraph">
|
|
<p>If you <code>@EnableZuulProxy</code> you can use the proxy paths to
|
|
upload files and it should just work as long as the files
|
|
are small. For large files there is an alternative path
|
|
which bypasses the Spring <code>DispatcherServlet</code> (to
|
|
avoid multipart processing) in "/zuul/*". I.e. if
|
|
<code>zuul.routes.customers=/customers/**</code> then you can
|
|
POST large files to "/zuul/customers/*". The servlet
|
|
path is externalized via <code>zuul.servletPath</code>. Extremely
|
|
large files will also require elevated timeout settings
|
|
if the proxy route takes you through a Ribbon load
|
|
balancer, e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">hystrix.command.default.execution.isolation.thread.timeoutInMilliseconds: 60000
|
|
ribbon:
|
|
ConnectTimeout: 3000
|
|
ReadTimeout: 60000</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Note that for streaming to work with large files, you need to use chunked encoding in the request (which some browsers
|
|
do not do by default). E.g. on the command line:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>$ curl -v -H "Transfer-Encoding: chunked" \
|
|
-F "file=@mylarge.iso" localhost:9999/zuul/simple/file</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_plain_embedded_zuul">Plain Embedded Zuul</h3>
|
|
<div class="paragraph">
|
|
<p>You can also run a Zuul server without the proxying, or switch on parts of the proxying platform selectively, if you
|
|
use <code>@EnableZuulServer</code> (instead of <code>@EnableZuulProxy</code>). Any beans that you add to the application of type <code>ZuulFilter</code>
|
|
will be installed automatically, as they are with <code>@EnableZuulProxy</code>, but without any of the proxy filters being added
|
|
automatically.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In this case the routes into the Zuul server are still specified by
|
|
configuring "zuul.routes.*", but there is no service
|
|
discovery and no proxying, so the "serviceId" and "url" settings are
|
|
ignored. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml"> zuul:
|
|
routes:
|
|
api: /api/**</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>maps all paths in "/api/**" to the Zuul filter chain.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_disable_zuul_filters">Disable Zuul Filters</h3>
|
|
<div class="paragraph">
|
|
<p>Zuul for Spring Cloud comes with a number of <code>ZuulFilter</code> beans enabled by default
|
|
in both proxy and server mode. See <a href="https://github.com/spring-cloud/spring-cloud-netflix/tree/master/spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/zuul/filters">the zuul filters package</a> for the
|
|
possible filters that are enabled. If you want to disable one, simply set
|
|
<code>zuul.<SimpleClassName>.<filterType>.disable=true</code>. By convention, the package after
|
|
<code>filters</code> is the Zuul filter type. For example to disable
|
|
<code>org.springframework.cloud.netflix.zuul.filters.post.SendResponseFilter</code> set
|
|
<code>zuul.SendResponseFilter.post.disable=true</code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_polyglot_support_with_sidecar">Polyglot support with Sidecar</h3>
|
|
<div class="paragraph">
|
|
<p>Do you have non-jvm languages you want to take advantage of Eureka, Ribbon and
|
|
Config Server? The Spring Cloud Netflix Sidecar was inspired by
|
|
<a href="https://github.com/Netflix/Prana">Netflix Prana</a>. It includes a simple http api
|
|
to get all of the instances (ie host and port) for a given service. You can
|
|
also proxy service calls through an embedded Zuul proxy which gets its route
|
|
entries from Eureka. The Spring Cloud Config Server can be accessed directly
|
|
via host lookup or through the Zuul Proxy. The non-jvm app should implement
|
|
a health check so the Sidecar can report to eureka if the app is up or down.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To enable the Sidecar, create a Spring Boot application with <code>@EnableSidecar</code>.
|
|
This annotation includes <code>@EnableCircuitBreaker</code>, <code>@EnableDiscoveryClient</code>,
|
|
and <code>@EnableZuulProxy</code>. Run the resulting application on the same host as the
|
|
non-jvm application.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To configure the side car add <code>sidecar.port</code> and <code>sidecar.health-uri</code> to <code>application.yml</code>.
|
|
The <code>sidecar.port</code> property is the port the non-jvm app is listening on. This
|
|
is so the Sidecar can properly register the app with Eureka. The <code>sidecar.health-uri</code>
|
|
is a uri accessible on the non-jvm app that mimicks a Spring Boot health
|
|
indicator. It should return a json document like the following:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">health-uri-document</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-json" data-lang="json">{
|
|
"status":"UP"
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Here is an example application.yml for a Sidecar application:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">server:
|
|
port: 5678
|
|
spring:
|
|
application:
|
|
name: sidecar
|
|
|
|
sidecar:
|
|
port: 8000
|
|
health-uri: http://localhost:8000/health.json</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The api for the <code>DiscoveryClient.getInstances()</code> method is <code>/hosts/{serviceId}</code>.
|
|
Here is an example response for <code>/hosts/customers</code> that returns two instances on
|
|
different hosts. This api is accessible to the non-jvm app (if the sidecar is
|
|
on port 5678) at <code><a href="http://localhost:5678/hosts/{serviceId}" class="bare">http://localhost:5678/hosts/{serviceId}</a></code>.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">/hosts/customers</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-json" data-lang="json">[
|
|
{
|
|
"host": "myhost",
|
|
"port": 9000,
|
|
"uri": "http://myhost:9000",
|
|
"serviceId": "CUSTOMERS",
|
|
"secure": false
|
|
},
|
|
{
|
|
"host": "myhost2",
|
|
"port": 9000,
|
|
"uri": "http://myhost2:9000",
|
|
"serviceId": "CUSTOMERS",
|
|
"secure": false
|
|
}
|
|
]</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The Zuul proxy automatically adds routes for each service known in eureka to
|
|
<code>/<serviceId></code>, so the customers service is available at <code>/customers</code>. The
|
|
Non-jvm app can access the customer service via <code><a href="http://localhost:5678/customers" class="bare">http://localhost:5678/customers</a></code>
|
|
(assuming the sidecar is listening on port 5678).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If the Config Server is registered with Eureka, non-jvm application can access
|
|
it via the Zuul proxy. If the serviceId of the ConfigServer is <code>configserver</code>
|
|
and the Sidecar is on port 5678, then it can be accessed at
|
|
<a href="http://localhost:5678/configserver" class="bare">http://localhost:5678/configserver</a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Non-jvm app can take advantage of the Config Server’s ability to return YAML
|
|
documents. For example, a call to <a href="http://sidecar.local.spring.io:5678/configserver/default-master.yml" class="bare">http://sidecar.local.spring.io:5678/configserver/default-master.yml</a>
|
|
might result in a YAML document like the following</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">eureka:
|
|
client:
|
|
serviceUrl:
|
|
defaultZone: http://localhost:8761/eureka/
|
|
password: password
|
|
info:
|
|
description: Spring Cloud Samples
|
|
url: https://github.com/spring-cloud-samples</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="netflix-rxjava-springmvc">RxJava with Spring MVC</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Netflix includes the <a href="https://github.com/ReactiveX/RxJava">RxJava</a>.</p>
|
|
</div>
|
|
<div class="quoteblock">
|
|
<blockquote>
|
|
<div class="paragraph">
|
|
<p>RxJava is a Java VM implementation of <a href="http://reactivex.io/">Reactive Extensions</a>: a library for composing asynchronous and event-based programs by using observable sequences.</p>
|
|
</div>
|
|
</blockquote>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Netflix provides support for returning <code>rx.Single</code> objects from Spring MVC Controllers. It also supports using <code>rx.Observable</code> objects for <a href="https://en.wikipedia.org/wiki/Server-sent_events">Server-sent events (SSE)</a>. This can be very convenient if your internal APIs are already built using RxJava (see <a href="#spring-cloud-feign-hystrix">Feign Hystrix Support</a> for examples).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Here are some examples of using <code>rx.Single</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@RequestMapping(method = RequestMethod.GET, value = "/single")
|
|
public Single<String> single() {
|
|
return Single.just("single value");
|
|
}
|
|
|
|
@RequestMapping(method = RequestMethod.GET, value = "/singleWithResponse")
|
|
public ResponseEntity<Single<String>> singleWithResponse() {
|
|
return new ResponseEntity<>(Single.just("single value"), HttpStatus.NOT_FOUND);
|
|
}
|
|
|
|
@RequestMapping(method = RequestMethod.GET, value = "/throw")
|
|
public Single<Object> error() {
|
|
return Single.error(new RuntimeException("Unexpected"));
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you have an <code>Observable</code>, rather than a single, you can use <code>.toSingle()</code> or <code>.toList().toSingle()</code>. Here are some examples:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@RequestMapping(method = RequestMethod.GET, value = "/single")
|
|
public Single<String> single() {
|
|
return Observable.just("single value").toSingle();
|
|
}
|
|
|
|
@RequestMapping(method = RequestMethod.GET, value = "/multiple")
|
|
public Single<List<String>> multiple() {
|
|
return Observable.just("multiple", "values").toList().toSingle();
|
|
}
|
|
|
|
@RequestMapping(method = RequestMethod.GET, value = "/responseWithObservable")
|
|
public ResponseEntity<Single<String>> responseWithObservable() {
|
|
|
|
Observable<String> observable = Observable.just("single value");
|
|
HttpHeaders headers = new HttpHeaders();
|
|
headers.setContentType(APPLICATION_JSON_UTF8);
|
|
return new ResponseEntity<>(observable.toSingle(), headers, HttpStatus.CREATED);
|
|
}
|
|
|
|
@RequestMapping(method = RequestMethod.GET, value = "/timeout")
|
|
public Observable<String> timeout() {
|
|
return Observable.timer(1, TimeUnit.MINUTES).map(new Func1<Long, String>() {
|
|
@Override
|
|
public String call(Long aLong) {
|
|
return "single value";
|
|
}
|
|
});
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you have a streaming endpoint and client, SSE could be an option. To convert <code>rx.Observable</code> to a Spring <code>SseEmitter</code> use <code>RxResponse.sse()</code>. Here are some examples:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@RequestMapping(method = RequestMethod.GET, value = "/sse")
|
|
public SseEmitter single() {
|
|
return RxResponse.sse(Observable.just("single value"));
|
|
}
|
|
|
|
@RequestMapping(method = RequestMethod.GET, value = "/messages")
|
|
public SseEmitter messages() {
|
|
return RxResponse.sse(Observable.just("message 1", "message 2", "message 3"));
|
|
}
|
|
|
|
@RequestMapping(method = RequestMethod.GET, value = "/events")
|
|
public SseEmitter event() {
|
|
return RxResponse.sse(APPLICATION_JSON_UTF8, Observable.just(
|
|
new EventDto("Spring io", getDate(2016, 5, 19)),
|
|
new EventDto("SpringOnePlatform", getDate(2016, 8, 1))
|
|
));
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="netflix-metrics">Metrics: Spectator, Servo, and Atlas</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>When used together, Spectator/Servo and Atlas provide a near real-time operational insight platform.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spectator and Servo are Netflix’s metrics collection libraries. Atlas is a Netflix metrics backend to manage dimensional time series data.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Servo served Netflix for several years and is still usable, but is gradually being phased out in favor of Spectator, which is only designed to work with Java 8. Spring Cloud Netflix provides support for both, but Java 8 based applications are encouraged to use Spectator.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_dimensional_vs_hierarchical_metrics">Dimensional vs. Hierarchical Metrics</h3>
|
|
<div class="paragraph">
|
|
<p>Spring Boot Actuator metrics are hierarchical and metrics are separated only by name. These names often follow a naming convention that embeds key/value attribute pairs (dimensions) into the name separated by periods. Consider the following metrics for two endpoints, root and star-star:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-json" data-lang="json">{
|
|
"counter.status.200.root": 20,
|
|
"counter.status.400.root": 3,
|
|
"counter.status.200.star-star": 5,
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The first metric gives us a normalized count of successful requests against the root endpoint per unit of time. But what if the system had 20 endpoints and you want to get a count of successful requests against all the endpoints? Some hierarchical metrics backends would allow you to specify a wild card such as <code>counter.status.200.<strong></code> that would read all 20 metrics and aggregate the results. Alternatively, you could provide a <code>HandlerInterceptorAdapter</code> that intercepts and records a metric like <code>counter.status.200.all</code> for all successful requests irrespective of the endpoint, but now you must write 20+1 different metrics. Similarly if you want to know the total number of successful requests for all endpoints in the service, you could specify a wild card such as <code>counter.status.2</strong>.*</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Even in the presence of wildcarding support on a hierarchical metrics backend, naming consistency can be difficult. Specifically the position of these tags in the name string can slip with time, breaking queries. For example, suppose we add an additional dimension to the hierarchical metrics above for HTTP method. Then <code>counter.status.200.root</code> becomes <code>counter.status.200.method.get.root</code>, etc. Our <code>counter.status.200.*</code> suddenly no longer has the same semantic meaning. Furthermore, if the new dimension is not applied uniformly across the codebase, certain queries may become impossible. This can quickly get out of hand.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Netflix metrics are tagged (a.k.a. dimensional). Each metric has a name, but this single named metric can contain multiple statistics and 'tag' key/value pairs that allows more querying flexibility. In fact, the statistics themselves are recorded in a special tag.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Recorded with Netflix Servo or Spectator, a timer for the root endpoint described above contains 4 statistics per status code, where the count statistic is identical to Spring Boot Actuator’s counter. In the event that we have encountered an HTTP 200 and 400 thus far, there will be 8 available data points:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-json" data-lang="json">{
|
|
"root(status=200,stastic=count)": 20,
|
|
"root(status=200,stastic=max)": 0.7265630630000001,
|
|
"root(status=200,stastic=totalOfSquares)": 0.04759702862580789,
|
|
"root(status=200,stastic=totalTime)": 0.2093076914666667,
|
|
"root(status=400,stastic=count)": 1,
|
|
"root(status=400,stastic=max)": 0,
|
|
"root(status=400,stastic=totalOfSquares)": 0,
|
|
"root(status=400,stastic=totalTime)": 0,
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_default_metrics_collection">Default Metrics Collection</h3>
|
|
<div class="paragraph">
|
|
<p>Without any additional dependencies or configuration, a Spring Cloud based service will autoconfigure a Servo <code>MonitorRegistry</code> and begin collecting metrics on every Spring MVC request. By default, a Servo timer with the name <code>rest</code> will be recorded for each MVC request which is tagged with:</p>
|
|
</div>
|
|
<div class="olist arabic">
|
|
<ol class="arabic">
|
|
<li>
|
|
<p>HTTP method</p>
|
|
</li>
|
|
<li>
|
|
<p>HTTP status (e.g. 200, 400, 500)</p>
|
|
</li>
|
|
<li>
|
|
<p>URI (or "root" if the URI is empty), sanitized for Atlas</p>
|
|
</li>
|
|
<li>
|
|
<p>The exception class name, if the request handler threw an exception</p>
|
|
</li>
|
|
<li>
|
|
<p>The caller, if a request header with a key matching <code>netflix.metrics.rest.callerHeader</code> is set on the request. There is no default key for <code>netflix.metrics.rest.callerHeader</code>. You must add it to your application properties if you wish to collect caller information.</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Set the <code>netflix.metrics.rest.metricName</code> property to change the name of the metric from <code>rest</code> to a name you provide.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If Spring AOP is enabled and <code>org.aspectj:aspectjweaver</code> is present on your runtime classpath, Spring Cloud will also collect metrics on every client call made with <code>RestTemplate</code>. A Servo timer with the name of <code>restclient</code> will be recorded for each MVC request which is tagged with:</p>
|
|
</div>
|
|
<div class="olist arabic">
|
|
<ol class="arabic">
|
|
<li>
|
|
<p>HTTP method</p>
|
|
</li>
|
|
<li>
|
|
<p>HTTP status (e.g. 200, 400, 500), "CLIENT_ERROR" if the response returned null, or "IO_ERROR" if an <code>IOException</code> occurred during the execution of the <code>RestTemplate</code> method</p>
|
|
</li>
|
|
<li>
|
|
<p>URI, sanitized for Atlas</p>
|
|
</li>
|
|
<li>
|
|
<p>Client name</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="netflix-metrics-spectator">Metrics Collection: Spectator</h3>
|
|
<div class="paragraph">
|
|
<p>To enable Spectator metrics, include a dependency on <code>spring-boot-starter-spectator</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-xml" data-lang="xml"> <dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-starter-spectator</artifactId>
|
|
</dependency></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In Spectator parlance, a meter is a named, typed, and tagged configuration and a metric represents the value of a given meter at a point in time. Spectator meters are created and controlled by a registry, which currently has several different implementations. Spectator provides 4 meter types: counter, timer, gauge, and distribution summary.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Spectator integration configures an injectable <code>com.netflix.spectator.api.Registry</code> instance for you. Specifically, it configures a <code>ServoRegistry</code> instance in order to unify the collection of REST metrics and the exporting of metrics to the Atlas backend under a single Servo API. Practically, this means that your code may use a mixture of Servo monitors and Spectator meters and both will be scooped up by Spring Boot Actuator <code>MetricReader</code> instances and both will be shipped to the Atlas backend.</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_spectator_counter">Spectator Counter</h4>
|
|
<div class="paragraph">
|
|
<p>A counter is used to measure the rate at which some event is occurring.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">// create a counter with a name and a set of tags
|
|
Counter counter = registry.counter("counterName", "tagKey1", "tagValue1", ...);
|
|
counter.increment(); // increment when an event occurs
|
|
counter.increment(10); // increment by a discrete amount</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The counter records a single time-normalized statistic.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_spectator_timer">Spectator Timer</h4>
|
|
<div class="paragraph">
|
|
<p>A timer is used to measure how long some event is taking. Spring Cloud automatically records timers for Spring MVC requests and conditionally <code>RestTemplate</code> requests, which can later be used to create dashboards for request related metrics like latency:</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<div class="title">Request Latency</div>
|
|
<p>image::RequestLatency.png []</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">// create a timer with a name and a set of tags
|
|
Timer timer = registry.timer("timerName", "tagKey1", "tagValue1", ...);
|
|
|
|
// execute an operation and time it at the same time
|
|
T result = timer.record(() -> fooReturnsT());
|
|
|
|
// alternatively, if you must manually record the time
|
|
Long start = System.nanoTime();
|
|
T result = fooReturnsT();
|
|
timer.record(System.nanoTime() - start, TimeUnit.NANOSECONDS);</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The timer simultaneously records 4 statistics: count, max, totalOfSquares, and totalTime. The count statistic will always match the single normalized value provided by a counter if you had called <code>increment()</code> once on the counter for each time you recorded a timing, so it is rarely necessary to count and time separately for a single operation.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>For <a href="https://github.com/Netflix/spectator/wiki/Timer-Usage#longtasktimer">long running operations</a>, Spectator provides a special <code>LongTaskTimer</code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_spectator_gauge">Spectator Gauge</h4>
|
|
<div class="paragraph">
|
|
<p>Gauges are used to determine some current value like the size of a queue or number of threads in a running state. Since gauges are sampled, they provide no information about how these values fluctuate between samples.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The normal use of a gauge involves registering the gauge once in initialization with an id, a reference to the object to be sampled, and a function to get or compute a numeric value based on the object. The reference to the object is passed in separately and the Spectator registry will keep a weak reference to the object. If the object is garbage collected, then Spectator will automatically drop the registration. See <a href="https://github.com/Netflix/spectator/wiki/Gauge-Usage#using-lambda">the note</a> in Spectator’s documentation about potential memory leaks if this API is misused.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">// the registry will automatically sample this gauge periodically
|
|
registry.gauge("gaugeName", pool, Pool::numberOfRunningThreads);
|
|
|
|
// manually sample a value in code at periodic intervals -- last resort!
|
|
registry.gauge("gaugeName", Arrays.asList("tagKey1", "tagValue1", ...), 1000);</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_spectator_distribution_summaries">Spectator Distribution Summaries</h4>
|
|
<div class="paragraph">
|
|
<p>A distribution summary is used to track the distribution of events. It is similar to a timer, but more general in that the size does not have to be a period of time. For example, a distribution summary could be used to measure the payload sizes of requests hitting a server.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">// the registry will automatically sample this gauge periodically
|
|
DistributionSummary ds = registry.distributionSummary("dsName", "tagKey1", "tagValue1", ...);
|
|
ds.record(request.sizeInBytes());</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="netflix-metrics-servo">Metrics Collection: Servo</h3>
|
|
<div class="admonitionblock warning">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Warning</div>
|
|
</td>
|
|
<td class="content">
|
|
If your code is compiled on Java 8, please use Spectator instead of Servo as Spectator is destined to replace Servo entirely in the long term.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In Servo parlance, a monitor is a named, typed, and tagged configuration and a metric represents the value of a given monitor at a point in time. Servo monitors are logically equivalent to Spectator meters. Servo monitors are created and controlled by a <code>MonitorRegistry</code>. In spite of the above warning, Servo does have a <a href="https://github.com/Netflix/servo/wiki/Getting-Started">wider array</a> of monitor options than Spectator has meters.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud integration configures an injectable <code>com.netflix.servo.MonitorRegistry</code> instance for you. Once you have created the appropriate <code>Monitor</code> type in Servo, the process of recording data is wholly similar to Spectator.</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_creating_servo_monitors">Creating Servo Monitors</h4>
|
|
<div class="paragraph">
|
|
<p>If you are using the Servo <code>MonitorRegistry</code> instance provided by Spring Cloud (specifically, an instance of <code>DefaultMonitorRegistry</code>), Servo provides convenience classes for retrieving <a href="https://github.com/Netflix/spectator/wiki/Servo-Comparison#dynamiccounter">counters</a> and <a href="https://github.com/Netflix/spectator/wiki/Servo-Comparison#dynamictimer">timers</a>. These convenience classes ensure that only one <code>Monitor</code> is registered for each unique combination of name and tags.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To manually create a Monitor type in Servo, especially for the more exotic monitor types for which convenience methods are not provided, instantiate the appropriate type by providing a <code>MonitorConfig</code> instance:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">MonitorConfig config = MonitorConfig.builder("timerName").withTag("tagKey1", "tagValue1").build();
|
|
|
|
// somewhere we should cache this Monitor by MonitorConfig
|
|
Timer timer = new BasicTimer(config);
|
|
monitorRegistry.register(timer);</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="netflix-metrics-atlas">Metrics Backend: Atlas</h3>
|
|
<div class="paragraph">
|
|
<p>Atlas was developed by Netflix to manage dimensional time series data for near real-time operational insight. Atlas features in-memory data storage, allowing it to gather and report very large numbers of metrics, very quickly.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Atlas captures operational intelligence. Whereas business intelligence is data gathered for analyzing trends over time, operational intelligence provides a picture of what is currently happening within a system.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud provides a <code>spring-cloud-starter-atlas</code> that has all the dependencies you need. Then just annotate your Spring Boot application with <code>@EnableAtlas</code> and provide a location for your running Atlas server with the <code>netflix.atlas.uri</code> property.</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_global_tags">Global tags</h4>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud enables you to add tags to every metric sent to the Atlas backend. Global tags can be used to separate metrics by application name, environment, region, etc.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Each bean implementing <code>AtlasTagProvider</code> will contribute to the global tag list:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Bean
|
|
AtlasTagProvider atlasCommonTags(
|
|
@Value("${spring.application.name}") String appName) {
|
|
return () -> Collections.singletonMap("app", appName);
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_using_atlas">Using Atlas</h4>
|
|
<div class="paragraph">
|
|
<p>To bootstrap a in-memory standalone Atlas instance:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-bash" data-lang="bash">$ curl -LO https://github.com/Netflix/atlas/releases/download/v1.4.2/atlas-1.4.2-standalone.jar
|
|
$ java -jar atlas-1.4.2-standalone.jar</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Tip</div>
|
|
</td>
|
|
<td class="content">
|
|
An Atlas standalone node running on an r3.2xlarge (61GB RAM) can handle roughly 2 million metrics per minute for a given 6 hour window.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Once running and you have collected a handful of metrics, verify that your setup is correct by listing tags on the Atlas server:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-bash" data-lang="bash">$ curl http://ATLAS/api/v1/tags</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Tip</div>
|
|
</td>
|
|
<td class="content">
|
|
After executing several requests against your service, you can gather some very basic information on the request latency of every request by pasting the following url in your browser: <code><a href="http://ATLAS/api/v1/graph?q=name,rest,:eq,:avg" class="bare">http://ATLAS/api/v1/graph?q=name,rest,:eq,:avg</a></code>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The Atlas wiki contains a <a href="https://github.com/Netflix/atlas/wiki/Single-Line">compilation of sample queries</a> for various scenarios.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Make sure to check out the <a href="https://github.com/Netflix/atlas/wiki/Alerting-Philosophy">alerting philosophy</a> and docs on using <a href="https://github.com/Netflix/atlas/wiki/DES">double exponential smoothing</a> to generate dynamic alert thresholds.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<h1 id="_spring_cloud_stream" class="sect0">Spring Cloud Stream</h1>
|
|
<div class="openblock partintro">
|
|
<div class="content">
|
|
<div class="paragraph">
|
|
<p>This section goes into more detail about how you can work with Spring Cloud Stream.
|
|
It covers topics such as creating and running stream applications.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_introducing_spring_cloud_stream">Introducing Spring Cloud Stream</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream is a framework for building message-driven microservice applications.
|
|
Spring Cloud Stream builds upon Spring Boot to create standalone, production-grade Spring applications, and uses Spring Integration to provide connectivity to message brokers.
|
|
It provides opinionated configuration of middleware from several vendors, introducing the concepts of persistent publish-subscribe semantics, consumer groups, and partitions.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can add the <code>@EnableBinding</code> annotation to your application to get immediate connectivity to a message broker, and you can add <code>@StreamListener</code> to a method to cause it to receive events for stream processing.
|
|
The following is a simple sink application which receives external messages.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@SpringBootApplication
|
|
public class StreamApplication {
|
|
|
|
public static void main(String[] args) {
|
|
SpringApplication.run(StreamApplication.class, args);
|
|
}
|
|
}
|
|
|
|
@EnableBinding(Sink.class)
|
|
public class TimerSource {
|
|
|
|
...
|
|
|
|
@StreamListener(Sink.INPUT)
|
|
public void processVote(Vote vote) {
|
|
votingService.recordVote(vote);
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>@EnableBinding</code> annotation takes one or more interfaces as parameters (in this case, the parameter is a single <code>Sink</code> interface).
|
|
An interface declares input and/or output channels.
|
|
Spring Cloud Stream provides the interfaces <code>Source</code>, <code>Sink</code>, and <code>Processor</code>; you can also define your own interfaces.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The following is the definition of the <code>Source</code> interface:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">public interface Sink {
|
|
String INPUT = "input";
|
|
|
|
@Input(Sink.INPUT)
|
|
SubscribableChannel input();
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>@Input</code> annotation identifies an <em>input channel</em>, through which received messages enter the application; the <code>@Output</code> annotation identifies an <em>output channel</em>, through which published messages leave the application.
|
|
The <code>@Input</code> and <code>@Output</code> annotations can take a channel name as a parameter; if a name is not provided, the name of the annotated method will be used.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream will create an implementation of the interface for you.
|
|
You can use this in the application by autowiring it, as in the following example of a test case.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@RunWith(SpringJUnit4ClassRunner.class)
|
|
@SpringApplicationConfiguration(classes = StreamApplication.class)
|
|
@WebAppConfiguration
|
|
@DirtiesContext
|
|
public class StreamApplicationTests {
|
|
|
|
@Autowired
|
|
private Sink sink;
|
|
|
|
@Test
|
|
public void contextLoads() {
|
|
assertNotNull(this.sink.input());
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_main_concepts">Main Concepts</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream provides a number of abstractions and primitives that simplify the writing of message-driven microservice applications.
|
|
This section gives an overview of the following:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>Spring Cloud Stream’s application model</p>
|
|
</li>
|
|
<li>
|
|
<p>The Binder abstraction</p>
|
|
</li>
|
|
<li>
|
|
<p>Persistent publish-subscribe support</p>
|
|
</li>
|
|
<li>
|
|
<p>Consumer group support</p>
|
|
</li>
|
|
<li>
|
|
<p>Partitioning support</p>
|
|
</li>
|
|
<li>
|
|
<p>A pluggable Binder API</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_application_model">Application Model</h3>
|
|
<div class="paragraph">
|
|
<p>A Spring Cloud Stream application consists of a middleware-neutral core.
|
|
The application communicates with the outside world through input and output <em>channels</em> injected into it by Spring Cloud Stream.
|
|
Channels are connected to external brokers through middleware-specific Binder implementations.</p>
|
|
</div>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<img src="images/SCSt-with-binder.png" alt="SCSt with binder" width="300">
|
|
</div>
|
|
<div class="title">Figure 4. Spring Cloud Stream Application</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_fat_jar">Fat JAR</h4>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream applications can be run in standalone mode from your IDE for testing.
|
|
To run a Spring Cloud Stream application in production, you can create an executable (or "fat") JAR by using the standard Spring Boot tooling provided for Maven or Gradle.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_the_binder_abstraction">The Binder Abstraction</h3>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream provides Binder implementations for <a href="https://github.com/spring-cloud/spring-cloud-stream/tree/master/spring-cloud-stream-binders/spring-cloud-stream-binder-kafka">Kafka</a>, <a href="https://github.com/spring-cloud/spring-cloud-stream/tree/master/spring-cloud-stream-binders/spring-cloud-stream-binder-rabbit">Rabbit MQ</a>, <a href="https://github.com/spring-cloud/spring-cloud-stream-binder-redis">Redis</a>, and <a href="https://github.com/spring-cloud/spring-cloud-stream-binder-gemfire">Gemfire</a>.
|
|
Spring Cloud Stream also includes a <a href="https://github.com/spring-cloud/spring-cloud-stream/blob/master/spring-cloud-stream-test-support/src/main/java/org/springframework/cloud/stream/test/binder/TestSupportBinder.java">TestSupportBinder</a>, which leaves a channel unmodified so that tests can interact with channels directly and reliably assert on what is received.
|
|
You can use the extensible API to write your own Binder.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream uses Spring Boot for configuration, and the Binder abstraction makes it possible for a Spring Cloud Stream application to be flexible in how it connects to middleware.
|
|
For example, deployers can dynamically choose, at runtime, the destinations (e.g., the Kafka topics or RabbitMQ exchanges) to which channels connect.
|
|
Such configuration can be provided through external configuration properties and in any form supported by Spring Boot (including application arguments, environment variables, and <code>application.yml</code> or <code>application.properties</code> files).
|
|
In the sink example from the <a href="#_introducing_spring_cloud_stream">Introducing Spring Cloud Stream</a> section, setting the application property <code>spring.cloud.stream.bindings.input.destination</code> to <code>raw-sensor-data</code> will cause it to read from the <code>raw-sensor-data</code> Kafka topic, or from a queue bound to the <code>raw-sensor-data</code> RabbitMQ exchange.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream automatically detects and uses a binder found on the classpath.
|
|
You can easily use different types of middleware with the same code: just include a different binder at build time.
|
|
For more complex use cases, you can also package multiple binders with your application and have it choose the binder, and even whether to use different binders for different channels, at runtime.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_persistent_publish_subscribe_support">Persistent Publish-Subscribe Support</h3>
|
|
<div class="paragraph">
|
|
<p>Communication between applications follows a publish-subscribe model, where data is broadcast through shared topics.
|
|
This can be seen in the following figure, which shows a typical deployment for a set of interacting Spring Cloud Stream applications.</p>
|
|
</div>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<img src="images/SCSt-sensors.png" alt="SCSt sensors" width="300">
|
|
</div>
|
|
<div class="title">Figure 5. Spring Cloud Stream Publish-Subscribe</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Data reported by sensors to an HTTP endpoint is sent to a common destination named <code>raw-sensor-data</code>.
|
|
From the destination, it is independently processed by a microservice application that computes time-windowed averages and by another microservice application that ingests the raw data into HDFS.
|
|
In order to process the data, both applications declare the topic as their input at runtime.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The publish-subscribe communication model reduces the complexity of both the producer and the consumer, and allows new applications to be added to the topology without disruption of the existing flow.
|
|
For example, downstream from the average-calculating application, you can add an application that calculates the highest temperature values for display and monitoring.
|
|
You can then add another application that interprets the same flow of averages for fault detection.
|
|
Doing all communication through shared topics rather than point-to-point queues reduces coupling between microservices.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>While the concept of publish-subscribe messaging is not new, Spring Cloud Stream takes the extra step of making it an opinionated choice for its application model.
|
|
By using native middleware support, Spring Cloud Stream also simplifies use of the publish-subscribe model across different platforms.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="consumer-groups">Consumer Groups</h3>
|
|
<div class="paragraph">
|
|
<p>While the publish-subscribe model makes it easy to connect applications through shared topics, the ability to scale up by creating multiple instances of a given application is equally important.
|
|
When doing this, different instances of an application are placed in a competing consumer relationship, where only one of the instances is expected to handle a given message.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream models this behavior through the concept of a <em>consumer group</em>.
|
|
(Spring Cloud Stream consumer groups are similar to and inspired by Kafka consumer groups.)
|
|
Each consumer binding can use the <code>spring.cloud.stream.bindings.<channelName>.group</code> property to specify a group name.
|
|
For the consumers shown in the following figure, this property would be set as <code>spring.cloud.stream.bindings.<channelName>.group=hdfsWrite</code> or <code>spring.cloud.stream.bindings.<channelName>.group=average</code>.</p>
|
|
</div>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<img src="images/SCSt-groups.png" alt="SCSt groups" width="300">
|
|
</div>
|
|
<div class="title">Figure 6. Spring Cloud Stream Consumer Groups</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>All groups which subscribe to a given destination receive a copy of published data, but only one member of each group receives a given message from that destination.
|
|
By default, when a group is not specified, Spring Cloud Stream assigns the application to an anonymous and independent single-member consumer group that is in a publish-subscribe relationship with all other consumer groups.</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="durability">Durability</h4>
|
|
<div class="paragraph">
|
|
<p>Consistent with the opinionated application model of Spring Cloud Stream, consumer group subscriptions are <em>durable</em>.
|
|
That is, a binder implementation ensures that group subscriptions are persistent, and once at least one subscription for a group has been created, the group will receive messages, even if they are sent while all applications in the group are stopped.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>Anonymous subscriptions are non-durable by nature.
|
|
For some binder implementations (e.g., RabbitMQ), it is possible to have non-durable group subscriptions.</p>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In general, it is preferable to always specify a consumer group when binding an application to a given destination.
|
|
When scaling up a Spring Cloud Stream application, you must specify a consumer group for each of its input bindings.
|
|
This prevents the application’s instances from receiving duplicate messages (unless that behavior is desired, which is unusual).</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="partitioning">Partitioning Support</h3>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream provides support for <em>partitioning</em> data between multiple instances of a given application.
|
|
In a partitioned scenario, the physical communication medium (e.g., the broker topic) is viewed as being structured into multiple partitions.
|
|
One or more producer application instances send data to multiple consumer application instances and ensure that data identified by common characteristics are processed by the same consumer instance.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream provides a common abstraction for implementing partitioned processing use cases in a uniform fashion.
|
|
Partitioning can thus be used whether the broker itself is naturally partitioned (e.g., Kafka) or not (e.g., RabbitMQ).</p>
|
|
</div>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<img src="images/SCSt-partitioning.png" alt="SCSt partitioning" width="300">
|
|
</div>
|
|
<div class="title">Figure 7. Spring Cloud Stream Partitioning</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Partitioning is a critical concept in stateful processing, where it is critiical, for either performance or consistency reasons, to ensure that all related data is processed together.
|
|
For example, in the time-windowed average calculation example, it is important that all measurements from any given sensor are processed by the same application instance.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>To set up a partitioned processing scenario, you must configure both the data-producing and the data-consuming ends.</p>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_programming_model">Programming Model</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>This section describes Spring Cloud Stream’s programming model.
|
|
Spring Cloud Stream provides a number of predefined annotations for declaring bound input and output channels as well as how to listen to channels.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_declaring_and_binding_channels">Declaring and Binding Channels</h3>
|
|
<div class="sect3">
|
|
<h4 id="_triggering_binding_via_code_enablebinding_code">Triggering Binding Via <code>@EnableBinding</code></h4>
|
|
<div class="paragraph">
|
|
<p>You can turn a Spring application into a Spring Cloud Stream application by applying the <code>@EnableBinding</code> annotation to one of the application’s configuration classes.
|
|
The <code>@EnableBinding</code> annotation itself is meta-annotated with <code>@Configuration</code> and triggers the configuration of Spring Cloud Stream infrastructure:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">...
|
|
@Import(...)
|
|
@Configuration
|
|
@EnableIntegration
|
|
public @interface EnableBinding {
|
|
...
|
|
Class<?>[] value() default {};
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>@EnableBinding</code> annotation can take as parameters one or more interface classes that contain methods which represent bindable components (typically message channels).</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>In Spring Cloud Stream 1.0, the only supported bindable components are the Spring Messaging <code>MessageChannel</code> and its extensions <code>SubscribableChannel</code> and <code>PollableChannel</code>.
|
|
Future versions should extend this support to other types of components, using the same mechanism.
|
|
In this documentation, we will continue to refer to channels.</p>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="__code_input_code_and_code_output_code"><code>@Input</code> and <code>@Output</code></h4>
|
|
<div class="paragraph">
|
|
<p>A Spring Cloud Stream application can have an arbitrary number of input and output channels defined in an interface as <code>@Input</code> and <code>@Output</code> methods:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">public interface Barista {
|
|
|
|
@Input
|
|
SubscribableChannel orders();
|
|
|
|
@Output
|
|
MessageChannel hotDrinks();
|
|
|
|
@Output
|
|
MessageChannel coldDrinks();
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Using this interface as a parameter to <code>@EnableBinding</code> will trigger the creation of three bound channels named <code>orders</code>, <code>hotDrinks</code>, and <code>coldDrinks</code>, respectively.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@EnableBinding(Barista.class)
|
|
public class CafeConfiguration {
|
|
|
|
...
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="sect4">
|
|
<h5 id="_customizing_channel_names">Customizing Channel Names</h5>
|
|
<div class="paragraph">
|
|
<p>Using the <code>@Input</code> and <code>@Output</code> annotations, you can specify a customized channel name for the channel, as shown in the following example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">public interface Barista {
|
|
...
|
|
@Input("inboundOrders")
|
|
SubscribableChannel orders();
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In this example, the created bound channel will be named <code>inboundOrders</code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect4">
|
|
<h5 id="__code_source_code_code_sink_code_and_code_processor_code"><code>Source</code>, <code>Sink</code>, and <code>Processor</code></h5>
|
|
<div class="paragraph">
|
|
<p>For easy addressing of the most common use cases, which involve either an input channel, an output channel, or both, Spring Cloud Stream provides three predefined interfaces out of the box.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><code>Source</code> can be used for an application which has a single outbound channel.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">public interface Source {
|
|
|
|
String OUTPUT = "output";
|
|
|
|
@Output(Source.OUTPUT)
|
|
MessageChannel output();
|
|
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><code>Sink</code> can be used for an application which has a single inbound channel.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">public interface Sink {
|
|
|
|
String INPUT = "input";
|
|
|
|
@Input(Sink.INPUT)
|
|
SubscribableChannel input();
|
|
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><code>Processor</code> can be used for an application which has both an inbound channel and an outbound channel.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">public interface Processor extends Source, Sink {
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream provides no special handling for any of these interfaces; they are only provided out of the box.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_accessing_bound_channels">Accessing Bound Channels</h4>
|
|
<div class="sect4">
|
|
<h5 id="_injecting_the_bound_interfaces">Injecting the Bound Interfaces</h5>
|
|
<div class="paragraph">
|
|
<p>For each bound interface, Spring Cloud Stream will generate a bean that implements the interface.
|
|
Invoking a <code>@Input</code>-annotated or <code>@Output</code>-annotated method of one of these beans will return the relevant bound channel.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The bean in the following example sends a message on the output channel when its <code>hello</code> method is invoked.
|
|
It invokes <code>output()</code> on the injected <code>Source</code> bean to retrieve the target channel.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Component
|
|
public class SendingBean {
|
|
|
|
private Source source;
|
|
|
|
@Autowired
|
|
public SendingBean(Source source) {
|
|
this.source = source;
|
|
}
|
|
|
|
public void sayHello(String name) {
|
|
source.output().send(MessageBuilder.withPayload(body).build());
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect4">
|
|
<h5 id="_injecting_channels_directly">Injecting Channels Directly</h5>
|
|
<div class="paragraph">
|
|
<p>Bound channels can be also injected directly:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Component
|
|
public class SendingBean {
|
|
|
|
private MessageChannel output;
|
|
|
|
@Autowired
|
|
public SendingBean(MessageChannel output) {
|
|
this.output = output;
|
|
}
|
|
|
|
public void sayHello(String name) {
|
|
output.send(MessageBuilder.withPayload(body).build());
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If the name of the channel is customized on the declaring annotation, that name should be used instead of the method name.
|
|
Given the following declaration:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">public interface CustomSource {
|
|
...
|
|
@Output("customOutput")
|
|
MessageChannel output();
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The channel will be injected as shown in the following example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Component
|
|
public class SendingBean {
|
|
|
|
@Autowired
|
|
private MessageChannel output;
|
|
|
|
@Autowired @Qualifier("customOutput")
|
|
public SendingBean(MessageChannel output) {
|
|
this.output = output;
|
|
}
|
|
|
|
public void sayHello(String name) {
|
|
customOutput.send(MessageBuilder.withPayload(body).build());
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_producing_and_consuming_messages">Producing and Consuming Messages</h4>
|
|
<div class="paragraph">
|
|
<p>You can write a Spring Cloud Stream application using either Spring Integration annotations or Spring Cloud Stream’s <code>@StreamListener</code> annotation.
|
|
The <code>@StreamListener</code> annotation is modeled after other Spring Messaging annotations (such as <code>@MessageMapping</code>, <code>@JmsListener</code>, <code>@RabbitListener</code>, etc.) but adds content type management and type coercion features.</p>
|
|
</div>
|
|
<div class="sect4">
|
|
<h5 id="_native_spring_integration_support">Native Spring Integration Support</h5>
|
|
<div class="paragraph">
|
|
<p>Because Spring Cloud Stream is based on Spring Integration, Stream completely inherits Integration’s foundation and infrastructure as well as the component itself.
|
|
For example, you can attach the output channel of a <code>Source</code> to a <code>MessageSource</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@EnableBinding(Source.class)
|
|
public class TimerSource {
|
|
|
|
@Value("${format}")
|
|
private String format;
|
|
|
|
@Bean
|
|
@InboundChannelAdapter(value = Source.OUTPUT, poller = @Poller(fixedDelay = "${fixedDelay}", maxMessagesPerPoll = "1"))
|
|
public MessageSource<String> timerMessageSource() {
|
|
return () -> new GenericMessage<>(new SimpleDateFormat(format).format(new Date()));
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Or you can use a processor’s channels in a transformer:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@EnableBinding(Processor.class)
|
|
public class TransformProcessor {
|
|
@Transformer(inputChannel = Processor.INPUT, outputChannel = Processor.OUTPUT)
|
|
public Object transform(String message) {
|
|
return message.toUpper();
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect4">
|
|
<h5 id="_using_streamlistener_for_automatic_content_type_handling">Using @StreamListener for Automatic Content Type Handling</h5>
|
|
<div class="paragraph">
|
|
<p>Complementary to its Spring Integration support, Spring Cloud Stream provides its own <code>@StreamListener</code> annotation, modeled after other Spring Messaging annotations (e.g. <code>@MessageMapping</code>, <code>@JmsListener</code>, <code>@RabbitListener</code>, etc.).
|
|
The <code>@StreamListener</code> annotation provides a simpler model for handling inbound messages, especially when dealing with use cases that involve content type management and type coercion.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream provides an extensible <code>MessageConverter</code> mechanism for handling data conversion by bound channels and for, in this case, dispatching to methods annotated with <code>@StreamListener</code>.
|
|
The following is an example of an application which processes external <code>Vote</code> events:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@EnableBinding(Sink.class)
|
|
public class VoteHandler {
|
|
|
|
@Autowired
|
|
VotingService votingService;
|
|
|
|
@StreamListener(Sink.INPUT)
|
|
public void handle(Vote vote) {
|
|
votingService.record(vote);
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The distinction between <code>@StreamListener</code> and a Spring Integration <code>@ServiceActivator</code> is seen when considering an inbound <code>Message</code> that has a <code>String</code> payload and a <code>contentType</code> header of <code>application/json</code>.
|
|
In the case of <code>@StreamListener</code>, the <code>MessageConverter</code> mechanism will use the <code>contentType</code> header to parse the <code>String</code> payload into a <code>Vote</code> object.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>As with other Spring Messaging methods, method arguments can be annotated with <code>@Payload</code>, <code>@Headers</code> and <code>@Header</code>.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>For methods which return data, you must use the <code>@SendTo</code> annotation to specify the output binding destination for data returned by the method:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@EnableBinding(Processor.class)
|
|
public class TransformProcessor {
|
|
|
|
@Autowired
|
|
VotingService votingService;
|
|
|
|
@StreamListener(Processor.INPUT)
|
|
@SendTo(Processor.OUTPUT)
|
|
public VoteResult handle(Vote vote) {
|
|
return votingService.record(vote);
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>In the case of RabbitMQ, content type headers can be set by external applications.
|
|
Spring Cloud Stream supports them as part of an extended internal protocol used for any type of transport (including transports, such as Kafka, that do not normally support headers).</p>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_aggregation">Aggregation</h4>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream provides support for aggregating multiple applications together, connecting their input and output channels directly and avoiding the additional cost of exchanging messages via a broker.
|
|
As of version 1.0 of Spring Cloud Stream, aggregation is supported only for the following types of applications:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><em>sources</em> - applications with a single output channel named <code>output</code>, typically having a single binding of the type <code>org.springframework.cloud.stream.messaging.Source</code></p>
|
|
</li>
|
|
<li>
|
|
<p><em>sinks</em> - applications with a single input channel named <code>input</code>, typically having a single binding of the type <code>org.springframework.cloud.stream.messaging.Sink</code></p>
|
|
</li>
|
|
<li>
|
|
<p><em>processors</em> - applications with a single input channel named <code>input</code> and a single output channel named <code>output</code>, typically having a single binding of the type <code>org.springframework.cloud.stream.messaging.Processor</code>.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>They can be aggregated together by creating a sequence of interconnected applications, in which the output channel of an element in the sequence is connected to the input channel of the next element, if it exists.
|
|
A sequence can start with either a <em>source</em> or a <em>processor</em>, it can contain an arbitrary number of <em>processors</em> and must end with either a <em>processor</em> or a <em>sink</em>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Depending on the nature of the starting and ending element, the sequence may have one or more bindable channels, as follows:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>if the sequence starts with a source and ends with a sink, all communication between the applications is direct and no channels will be bound</p>
|
|
</li>
|
|
<li>
|
|
<p>if the sequence starts with a processor, then its input channel will become the <code>input</code> channel of the aggregate and will be bound accordingly</p>
|
|
</li>
|
|
<li>
|
|
<p>if the sequence ends with a processor, then its output channel will become the <code>output</code> channel of the aggregate and will be bound accordingly</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Aggregation is performed using the <code>AggregateApplicationBuilder</code> utility class, as in the following example.
|
|
Let’s consider a project in which we have source, processor and a sink, which may be defined in the project, or may be contained in one of the project’s dependencies.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@SpringBootApplication
|
|
@EnableBinding(Sink.class)
|
|
public class SinkApplication {
|
|
|
|
private static Logger logger = LoggerFactory.getLogger(SinkModuleDefinition.class);
|
|
|
|
@ServiceActivator(inputChannel=Sink.INPUT)
|
|
public void loggerSink(Object payload) {
|
|
logger.info("Received: " + payload);
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@SpringBootApplication
|
|
@EnableBinding(Processor.class)
|
|
public class ProcessorApplication {
|
|
|
|
@Transformer
|
|
public String loggerSink(String payload) {
|
|
return payload.toUpperCase();
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@SpringBootApplication
|
|
@EnableBinding(Source.class)
|
|
public class SourceApplication {
|
|
|
|
@Bean
|
|
@InboundChannelAdapter(value = Source.OUTPUT)
|
|
public String timerMessageSource() {
|
|
return new SimpleDateFormat().format(new Date());
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Each configuration can be used for running a separate component, but in this case they can be aggregated together as follows:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@SpringBootApplication
|
|
public class SampleAggregateApplication {
|
|
|
|
public static void main(String[] args) {
|
|
new AggregateApplicationBuilder()
|
|
.from(SourceApplication.class).args("--fixedDelay=5000")
|
|
.via(ProcessorApplication.class)
|
|
.to(SinkApplication.class).args("--debug=true").run(args);
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The starting component of the sequence is provided as argument to the <code>from()</code> method.
|
|
The ending component of the sequence is provided as argument to the <code>to()</code> method.
|
|
Intermediate processors are provided as argument to the <code>via()</code> method.
|
|
Multiple processors of the same type can be chained together (e.g. for pipelining transformations with different configurations).
|
|
For each component, the builder can provide runtime arguments for Spring Boot configuration.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_rxjava_support">RxJava support</h4>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream provides support for RxJava-based processors through the <code>RxJavaProcessor</code> available in <code>spring-cloud-stream-rxjava</code>.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">public interface RxJavaProcessor<I, O> {
|
|
Observable<O> process(Observable<I> input);
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>An implementation of <code>RxJavaProcessor</code> will receive <code>Observable</code> as an input that represents the flow of inbound message payloads.
|
|
The <code>process</code> method is invoked once at startup for setting up the data flow.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can enable the use of RxJava-based processors and use them in your processor application by using the <code>@EnableRxJavaProcessor</code> annotation.
|
|
<code>@EnableRxJavaProcessor</code> is meta-annotated with <code>@EnableBinding(Processor.class)</code> and will create the <code>Processor</code> binding.
|
|
Here is an example of an RxJava-based processor:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@EnableRxJavaProcessor
|
|
public class RxJavaTransformer {
|
|
|
|
private static Logger logger = LoggerFactory.getLogger(RxJavaTransformer.class);
|
|
|
|
@Bean
|
|
public RxJavaProcessor<String,String> processor() {
|
|
return inputStream -> inputStream.map(data -> {
|
|
logger.info("Got data = " + data);
|
|
return data;
|
|
})
|
|
.buffer(5)
|
|
.map(data -> String.valueOf(avg(data)));
|
|
}
|
|
|
|
private static Double avg(List<String> data) {
|
|
double sum = 0;
|
|
double count = 0;
|
|
for(String d : data) {
|
|
count++;
|
|
sum += Double.valueOf(d);
|
|
}
|
|
return sum/count;
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>When implementing an RxJava processor, it is important to handle exceptions as part of your processing flow.
|
|
Uncaught exceptions will be treated as errors by RxJava and will cause the <code>Observable</code> to complete, disrupting the flow.</p>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_binders">Binders</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream provides a Binder abstraction for use in connecting to physical destinations at the external middleware.
|
|
This section provides information about the main concepts behind the Binder SPI, its main components, and implementation-specific details.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_producers_and_consumers">Producers and Consumers</h3>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<img src="images/producers-consumers.png" alt="producers consumers" width="300">
|
|
</div>
|
|
<div class="title">Figure 8. Producers and Consumers</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>A <em>producer</em> is any component that sends messages to a channel.
|
|
The channel can be bound to an external message broker via a Binder implementation for that broker.
|
|
When invoking the <code>bindProducer()</code> method, the first parameter is the name of the destination within the broker, the second parameter is the local channel instance to which the producer will send messages, and the third parameter contains properties (such as a partition key expression) to be used within the adapter that is created for that channel.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>A <em>consumer</em> is any component that receives messages from a channel.
|
|
As with a producer, the consumer’s channel can be bound to an external message broker.
|
|
When invoking the <code>bindConsumer()</code> method, the first parameter is the destination name, and a second parameter provides the name of a logical group of consumers.
|
|
Each group that is represented by consumer bindings for a given destination receives a copy of each message that a producer sends to that destination (i.e., publish-subscribe semantics).
|
|
If there are multiple consumer instances bound using the same group name, then messages will be load-balanced across those consumer instances so that each message sent by a producer is consumed by only a single consumer instance within each group (i.e., queueing semantics).</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_binder_spi">Binder SPI</h3>
|
|
<div class="paragraph">
|
|
<p>The Binder SPI consists of a number of interfaces, out-of-the box utility classes and discovery strategies that provide a pluggable mechanism for connecting to external middleware.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The key point of the SPI is the <code>Binder</code> interface which is a strategy for connecting inputs and outputs to external middleware.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">public interface Binder<T, C extends ConsumerProperties, P extends ProducerProperties> {
|
|
Binding<T> bindConsumer(String name, String group, T inboundBindTarget, C consumerProperties);
|
|
|
|
Binding<T> bindProducer(String name, T outboundBindTarget, P producerProperties);
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The interface is parameterized, offering a number of extension points:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>input and output bind targets - as of version 1.0, only <code>MessageChannel</code> is supported, but this is intended to be used as an extension point in the future;</p>
|
|
</li>
|
|
<li>
|
|
<p>extended consumer and producer properties - allowing specific Binder implementations to add supplemental properties which can be supported in a type-safe manner.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>A typical binder implementation consists of the following</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>a class that implements the <code>Binder</code> interface;</p>
|
|
</li>
|
|
<li>
|
|
<p>a Spring <code>@Configuration</code> class that creates a bean of the type above along with the middleware connection infrastructure;</p>
|
|
</li>
|
|
<li>
|
|
<p>a <code>META-INF/spring.binders</code> file found on the classpath containing one or more binder definitions, e.g.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code>kafka:\
|
|
org.springframework.cloud.stream.binder.kafka.config.KafkaBinderConfiguration</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_binder_detection">Binder Detection</h3>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream relies on implementations of the Binder SPI to perform the task of connecting channels to message brokers.
|
|
Each Binder implementation typically connects to one type of messaging system.
|
|
Out of the box, Spring Cloud Stream provides binders for Kafka, RabbitMQ, and Redis.</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_classpath_detection">Classpath Detection</h4>
|
|
<div class="paragraph">
|
|
<p>By default, Spring Cloud Stream relies on Spring Boot’s auto-configuration to configure the binding process.
|
|
If a single Binder implementation is found on the classpath, Spring Cloud Stream will use it automatically.
|
|
For example, a Spring Cloud Stream project that aims to bind only to RabbitMQ can simply add the following dependency:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-xml" data-lang="xml"><dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-stream-binder-rabbit</artifactId>
|
|
</dependency></code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="multiple-binders">Multiple Binders on the Classpath</h3>
|
|
<div class="paragraph">
|
|
<p>When multiple binders are present on the classpath, the application must indicate which binder is to be used for each channel binding.
|
|
Each binder configuration contains a <code>META-INF/spring.binders</code>, which is a simple properties file:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code>rabbit:\
|
|
org.springframework.cloud.stream.binder.rabbit.config.RabbitServiceAutoConfiguration</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Similar files exist for the other provided binder implementations (e.g., Kafka), and custom binder implementations are expected to provide them, as well.
|
|
The key represents an identifying name for the binder implementation, whereas the value is a comma-separated list of configuration classes that each contain one and only one bean definition of type <code>org.springframework.cloud.stream.binder.Binder</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Binder selection can either be performed globally, using the <code>spring.cloud.stream.defaultBinder</code> property (e.g., <code>spring.cloud.stream.defaultBinder=rabbit</code>) or individually, by configuring the binder on each channel binding.
|
|
For instance, a processor application (that has channels with the names <code>input</code> and <code>output</code> for read/write respectively) which reads from Kafka and writes to RabbitMQ can specify the following configuration:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>spring.cloud.stream.bindings.input.binder=kafka
|
|
spring.cloud.stream.bindings.output.binder=rabbit</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="multiple-systems">Connecting to Multiple Systems</h3>
|
|
<div class="paragraph">
|
|
<p>By default, binders share the application’s Spring Boot auto-configuration, so that one instance of each binder found on the classpath will be created.
|
|
If your application should connect to more than one broker of the same type, you can specify multiple binder configurations, each with different environment settings.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>Turning on explicit binder configuration will disable the default binder configuration process altogether.
|
|
If you do this, all binders in use must be included in the configuration.
|
|
Frameworks that intend to use Spring Cloud Stream transparently may create binder configurations that can be referenced by name, but will not affect the default binder configuration.
|
|
In order to do so, a binder configuration may have its <code>defaultCandidate</code> flag set to false, e.g. <code>spring.cloud.stream.binders.<configurationName>.defaultCandidate=false</code>.
|
|
This denotes a configuration that will exist independently of the default binder configuration process.</p>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>For example, this is the typical configuration for a processor application which connects to two RabbitMQ broker instances:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yml" data-lang="yml">spring:
|
|
cloud:
|
|
stream:
|
|
bindings:
|
|
input:
|
|
destination: foo
|
|
binder: rabbit1
|
|
output:
|
|
destination: bar
|
|
binder: rabbit2
|
|
binders:
|
|
rabbit1:
|
|
type: rabbit
|
|
environment:
|
|
spring:
|
|
rabbitmq:
|
|
host: <host1>
|
|
rabbit2:
|
|
type: rabbit
|
|
environment:
|
|
spring:
|
|
rabbitmq:
|
|
host: <host2></code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_binder_configuration_properties">Binder configuration properties</h3>
|
|
<div class="paragraph">
|
|
<p>The following properties are available when creating custom binder configurations.
|
|
They must be prefixed with <code>spring.cloud.stream.binders.<configurationName></code>.</p>
|
|
</div>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">type</dt>
|
|
<dd>
|
|
<p> The binder type.
|
|
It typically references one of the binders found on the classpath, in particular a key in a <code>META-INF/spring.binders</code> file.</p>
|
|
<div class="paragraph">
|
|
<p>By default, it has the same value as the configuration name.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">inheritEnvironment</dt>
|
|
<dd>
|
|
<p>Whether the configuration will inherit the environment of the application itself.</p>
|
|
<div class="paragraph">
|
|
<p>Default <code>true</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">environment</dt>
|
|
<dd>
|
|
<p> Root for a set of properties that can be used to customize the environment of the binder.
|
|
When this is configured, the context in which the binder is being created is not a child of the application context.
|
|
This allows for complete separation between the binder components and the application components.</p>
|
|
<div class="paragraph">
|
|
<p>Default <code>empty</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">defaultCandidate</dt>
|
|
<dd>
|
|
<p> Whether the binder configuration is a candidate for being considered a default binder, or can be used only when explicitly referenced.
|
|
This allows adding binder configurations without interfering with the default processing.</p>
|
|
<div class="paragraph">
|
|
<p>Default <code>true</code>.</p>
|
|
</div>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_implementation_strategies">Implementation strategies</h3>
|
|
<div class="paragraph">
|
|
<p>This section details the binder implementation strategies for Kafka and Rabbit MQ, in what concerns mapping the Spring Cloud Stream concepts onto the middleware concepts.</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_kafka_binder">Kafka Binder</h4>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<img src="images/kafka-binder.png" alt="kafka binder" width="300">
|
|
</div>
|
|
<div class="title">Figure 9. Kafka Binder</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The Kafka Binder implementation maps the destination to a Kafka topic.
|
|
The consumer group maps directly to the same Kafka concept.
|
|
Spring Cloud Stream does not use the high-level consumer, but implements a similar concept for the simple consumer.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_rabbitmq_binder">RabbitMQ Binder</h4>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<img src="images/rabbit-binder.png" alt="rabbit binder" width="300">
|
|
</div>
|
|
<div class="title">Figure 10. RabbitMQ Binder</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The RabbitMQ Binder implementation maps the destination to a <code>TopicExchange</code>.
|
|
For each consumer group, a <code>Queue</code> will be bound to that <code>TopicExchange</code>.
|
|
Each consumer instance that binds will trigger creation of a corresponding RabbitMQ <code>Consumer</code> instance for its group’s <code>Queue</code>.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_configuration_options">Configuration Options</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream supports general configuration options as well as configuration for bindings and binders.
|
|
Some binders allow additional binding properties to support middleware-specific features.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Configuration options can be provided to Spring Cloud Stream applications via any mechanism supported by Spring Boot.
|
|
This includes application arguments, environment variables, and YAML or .properties files.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_spring_cloud_stream_properties">Spring Cloud Stream Properties</h3>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">spring.cloud.stream.instanceCount</dt>
|
|
<dd>
|
|
<p> The number of deployed instances of an application.
|
|
Must be set for partitioning and if using Kafka.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>1</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.instanceIndex</dt>
|
|
<dd>
|
|
<p> The instance index of the application: a number from <code>0</code> to <code>instanceCount</code>-1.
|
|
Used for partitioning and with Kafka.
|
|
Automatically set in Cloud Foundry to match the application’s instance index.</p>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.dynamicDestinations</dt>
|
|
<dd>
|
|
<p> A list of destinations that can be bound dynamically (for example, in a dynamic routing scenario).
|
|
If set, only listed destinations can be bound.</p>
|
|
<div class="paragraph">
|
|
<p>Default: empty (allowing any destination to be bound).</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.defaultBinder</dt>
|
|
<dd>
|
|
<p> The default binder to use, if multiple binders are configured.
|
|
See <a href="#multiple-binders">Multiple Binders on the Classpath</a>.</p>
|
|
<div class="paragraph">
|
|
<p>Default: empty.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.overrideCloudConnectors</dt>
|
|
<dd>
|
|
<p> This property is only applicable when the <code>cloud</code> profile is active and Spring Cloud Connectors are provided with the application.
|
|
If the property is false (the default), the binder will detect a suitable bound service (e.g. a RabbitMQ service bound in Cloud Foundry for the RabbitMQ binder) and will use it for creating connections (usually via Spring Cloud Connectors).
|
|
When set to true, this property instructs binders to completely ignore the bound services and rely on Spring Boot properties (e.g. relying on the <code>spring.rabbitmq.*</code> properties provided in the environment for the RabbitMQ binder).
|
|
The typical usage of this property is to be nested in a customized environment <a href="#multiple-systems">when connecting to multiple systems</a>.</p>
|
|
<div class="paragraph">
|
|
<p>Default: false.</p>
|
|
</div>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="binding-properties">Binding Properties</h3>
|
|
<div class="paragraph">
|
|
<p>Binding properties are supplied using the format <code>spring.cloud.stream.bindings.<channelName>.<property>=<value></code>.
|
|
The <code><channelName></code> represents the name of the channel being configured (e.g., <code>output</code> for a <code>Source</code>).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In what follows, we indicate where we have omitted the <code>spring.cloud.stream.bindings.<channelName>.</code> prefix and focus just on the property name, with the understanding that the prefix will be included at runtime.</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_properties_for_use_of_spring_cloud_stream">Properties for Use of Spring Cloud Stream</h4>
|
|
<div class="paragraph">
|
|
<p>The following binding properties are available for both input and output bindings and
|
|
must be prefixed with <code>spring.cloud.stream.bindings.<channelName>.</code>.</p>
|
|
</div>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">destination</dt>
|
|
<dd>
|
|
<p>The target destination of a channel on the bound middleware (e.g., the RabbitMQ exchange or Kafka topic).
|
|
If the channel is bound as a consumer, it could be bound to multiple destinations and the destination names can be specified as comma separated String values.
|
|
If not set, the channel name is used instead.</p>
|
|
</dd>
|
|
<dt class="hdlist1">group</dt>
|
|
<dd>
|
|
<p> The consumer group of the channel.
|
|
Applies only to inbound bindings.
|
|
See <a href="#consumer-groups">Consumer Groups</a>.</p>
|
|
<div class="paragraph">
|
|
<p>Default: null (indicating an anonymous consumer).</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">contentType</dt>
|
|
<dd>
|
|
<p> The content type of the channel.
|
|
//See <a href="#content type management">[content type management]</a>.</p>
|
|
<div class="paragraph">
|
|
<p>Default: null (so that no type coercion is performed).</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">binder</dt>
|
|
<dd>
|
|
<p> The binder used by this binding.
|
|
See <a href="#multiple-binders">Multiple Binders on the Classpath</a> for details.</p>
|
|
<div class="paragraph">
|
|
<p>Default: null (the default binder will be used, if one exists).</p>
|
|
</div>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_consumer_properties">Consumer properties</h4>
|
|
<div class="paragraph">
|
|
<p>The following binding properties are available for input bindings only and must be prefixed with <code>spring.cloud.stream.bindings.<channelName>.consumer.</code>.</p>
|
|
</div>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">concurrency</dt>
|
|
<dd>
|
|
<p>The concurrency of the inbound consumer.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>1</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">partitioned</dt>
|
|
<dd>
|
|
<p>Whether the consumer receives data from a partitioned producer.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>false</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">headerMode</dt>
|
|
<dd>
|
|
<p> When set to <code>raw</code>, disables header parsing on input.
|
|
Effective only for messaging middleware that does not support message headers natively and requires header embedding.
|
|
Useful when inbound data is coming from outside Spring Cloud Stream applications.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>embeddedHeaders</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">maxAttempts</dt>
|
|
<dd>
|
|
<p>The number of attempts of re-processing an inbound message.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>3</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">backOffInitialInterval</dt>
|
|
<dd>
|
|
<p>The backoff initial interval on retry.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>1000</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">backOffMaxInterval</dt>
|
|
<dd>
|
|
<p>The maximum backoff interval.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>10000</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">backOffMultiplier</dt>
|
|
<dd>
|
|
<p>The backoff multiplier.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>2.0</code>.</p>
|
|
</div>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_producer_properties">Producer Properties</h4>
|
|
<div class="paragraph">
|
|
<p>The following binding properties are available for output bindings only and must be prefixed with <code>spring.cloud.stream.bindings.<channelName>.producer.</code>.</p>
|
|
</div>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">partitionKeyExpression</dt>
|
|
<dd>
|
|
<p> A SpEL expression that determines how to partition outbound data.
|
|
If set, or if <code>partitionKeyExtractorClass</code> is set, outbound data on this channel will be partitioned, and <code>partitionCount</code> must be set to a value greater than 1 to be effective.
|
|
The two options are mutually exclusive.
|
|
See <a href="#partitioning">Partitioning Support</a>.</p>
|
|
<div class="paragraph">
|
|
<p>Default: null.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">partitionKeyExtractorClass</dt>
|
|
<dd>
|
|
<p> A <code>PartitionKeyExtractorStrategy</code> implementation.
|
|
If set, or if <code>partitionKeyExpression</code> is set, outbound data on this channel will be partitioned, and <code>partitionCount</code> must be set to a value greater than 1 to be effective.
|
|
The two options are mutually exclusive.
|
|
See <a href="#partitioning">Partitioning Support</a>.</p>
|
|
<div class="paragraph">
|
|
<p>Default: null.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">partitionSelectorClass</dt>
|
|
<dd>
|
|
<p> A <code>PartitionSelectorStrategy</code> implementation.
|
|
Mutually exclusive with <code>partitionSelectorExpression</code>.
|
|
If neither is set, the partition will be selected as the <code>hashCode(key) % partitionCount</code>, where <code>key</code> is computed via either <code>partitionKeyExpression</code> or <code>partitionKeyExtractorClass</code>.</p>
|
|
<div class="paragraph">
|
|
<p>Default: null.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">partitionSelectorExpression</dt>
|
|
<dd>
|
|
<p> A SpEL expression for customizing partition selection.
|
|
Mutually exclusive with <code>partitionSelectorClass</code>.
|
|
If neither is set, the partition will be selected as the <code>hashCode(key) % partitionCount</code>, where <code>key</code> is computed via either <code>partitionKeyExpression</code> or <code>partitionKeyExtractorClass</code>.</p>
|
|
<div class="paragraph">
|
|
<p>Default: null.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">partitionCount</dt>
|
|
<dd>
|
|
<p> The number of target partitions for the data, if partitioning is enabled.
|
|
Must be
|
|
set to a value greater than 1 if the producer is partitioned.
|
|
On Kafka, interpreted as a
|
|
hint; the larger of this and the partition count of the target topic is used instead.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>1</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">requiredGroups</dt>
|
|
<dd>
|
|
<p>A comma-separated list of groups to which the producer must ensure message delivery even if they start after it has been created (e.g., by pre-creating durable queues in RabbitMQ).</p>
|
|
</dd>
|
|
<dt class="hdlist1">headerMode</dt>
|
|
<dd>
|
|
<p> When set to <code>raw</code>, disables header embedding on output.
|
|
Effective only for messaging middleware that does not support message headers natively and requires header embedding.
|
|
Useful when producing data for non-Spring Cloud Stream applications.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>embeddedHeaders</code>.</p>
|
|
</div>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="binder-specific-configuration">Binder-Specific Configuration</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>The following binder, consumer, and producer properties are specific to binder implementations.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_rabbit_specific_settings">Rabbit-Specific Settings</h3>
|
|
<div class="sect3">
|
|
<h4 id="_rabbitmq_binder_properties">RabbitMQ Binder Properties</h4>
|
|
<div class="paragraph">
|
|
<p>By default, the RabbitMQ binder uses Spring Boot’s <code>ConnectionFactory</code>, and it therefore supports all Spring Boot configuration options for RabbitMQ.
|
|
(For reference, consult the <a href="http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#common-application-properties">Spring Boot documentation</a>.) RabbitMQ configuration options use the <code>spring.rabbitmq</code> prefix.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In addition to the Spring Boot options, the RabbitMQ binder supports the following properties:</p>
|
|
</div>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">spring.cloud.stream.rabbit.binder.adminAddresses</dt>
|
|
<dd>
|
|
<p> A comma-separated list of RabbitMQ management plugin URLs.
|
|
Only used when <code>nodes</code> contains more than one entry.
|
|
Each entry in this list must have a corresponding entry in <code>spring.rabbitmq.addresses</code>.</p>
|
|
<div class="paragraph">
|
|
<p>Default: empty.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.rabbit.binder.nodes</dt>
|
|
<dd>
|
|
<p> A comma-separated list of RabbitMQ node names.
|
|
When more than one entry, used to locate the server address where a queue is located.
|
|
Each entry in this list must have a corresponding entry in <code>spring.rabbitmq.addresses</code>.</p>
|
|
<div class="paragraph">
|
|
<p>Default: empty.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.rabbit.binder.compressionLevel</dt>
|
|
<dd>
|
|
<p> Compression level for compressed bindings.
|
|
See <code>java.util.zip.Deflater</code>.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>1</code> (BEST_LEVEL).</p>
|
|
</div>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_rabbitmq_consumer_properties">RabbitMQ Consumer Properties</h4>
|
|
<div class="paragraph">
|
|
<p>The following properties are available for Rabbit consumers only and
|
|
must be prefixed with <code>spring.cloud.stream.rabbit.bindings.<channelName>.consumer.</code>.</p>
|
|
</div>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">acknowledgeMode</dt>
|
|
<dd>
|
|
<p>The acknowledge mode.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>AUTO</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">autoBindDlq</dt>
|
|
<dd>
|
|
<p>Whether to automatically declare the DLQ and bind it to the binder DLX.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>false</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">durableSubscription</dt>
|
|
<dd>
|
|
<p> Whether subscription should be durable.
|
|
Only effective if <code>group</code> is also set.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>true</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">maxConcurrency</dt>
|
|
<dd>
|
|
<p>Default: <code>1</code>.</p>
|
|
</dd>
|
|
<dt class="hdlist1">prefetch</dt>
|
|
<dd>
|
|
<p>Prefetch count.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>1</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">prefix</dt>
|
|
<dd>
|
|
<p>A prefix to be added to the name of the <code>destination</code> and queues.</p>
|
|
<div class="paragraph">
|
|
<p>Default: "".</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">recoveryInterval</dt>
|
|
<dd>
|
|
<p>The interval between connection recovery attempts, in milliseconds.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>5000</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">requeueRejected</dt>
|
|
<dd>
|
|
<p>Whether delivery failures should be requeued.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>true</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">requestHeaderPatterns</dt>
|
|
<dd>
|
|
<p>The request headers to be transported.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>[STANDARD_REQUEST_HEADERS,'*']</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">replyHeaderPatterns</dt>
|
|
<dd>
|
|
<p>The reply headers to be transported.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>[STANDARD_REQUEST_HEADERS,'*']</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">republishToDlq</dt>
|
|
<dd>
|
|
<p> By default, messages which fail after retries are exhausted are rejected.
|
|
If a dead-letter queue (DLQ) is configured, RabbitMQ will route the failed message (unchanged) to the DLQ.
|
|
If set to <code>true</code>, the bus will republish failed messages to the DLQ with additional headers, including the exception message and stack trace from the cause of the final failure.</p>
|
|
</dd>
|
|
<dt class="hdlist1">transacted</dt>
|
|
<dd>
|
|
<p>Whether to use transacted channels.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>false</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">txSize</dt>
|
|
<dd>
|
|
<p>The number of deliveries between acks.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>1</code>.</p>
|
|
</div>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_rabbit_producer_properties">Rabbit Producer Properties</h4>
|
|
<div class="paragraph">
|
|
<p>The following properties are available for Rabbit producers only and
|
|
must be prefixed with <code>spring.cloud.stream.rabbit.bindings.<channelName>.producer.</code>.</p>
|
|
</div>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">autoBindDlq</dt>
|
|
<dd>
|
|
<p>Whether to automatically declare the DLQ and bind it to the binder DLX.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>false</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">batchingEnabled</dt>
|
|
<dd>
|
|
<p>Whether to enable message batching by producers.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>false</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">batchSize</dt>
|
|
<dd>
|
|
<p>The number of messages to buffer when batching is enabled.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>100</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">batchBufferLimit</dt>
|
|
<dd>
|
|
<p>Default: <code>10000</code>.</p>
|
|
</dd>
|
|
<dt class="hdlist1">batchTimeout</dt>
|
|
<dd>
|
|
<p>Default: <code>5000</code>.</p>
|
|
</dd>
|
|
<dt class="hdlist1">compress</dt>
|
|
<dd>
|
|
<p>Whether data should be compressed when sent.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>false</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">deliveryMode</dt>
|
|
<dd>
|
|
<p>Delivery mode.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>PERSISTENT</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">prefix</dt>
|
|
<dd>
|
|
<p>A prefix to be added to the name of the <code>destination</code> exchange.</p>
|
|
<div class="paragraph">
|
|
<p>Default: "".</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">requestHeaderPatterns</dt>
|
|
<dd>
|
|
<p>The request headers to be transported.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>[STANDARD_REQUEST_HEADERS,'*']</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">replyHeaderPatterns</dt>
|
|
<dd>
|
|
<p>The reply headers to be transported.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>[STANDARD_REQUEST_HEADERS,'*']</code>.</p>
|
|
</div>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_kafka_specific_settings">Kafka-Specific Settings</h3>
|
|
<div class="sect3">
|
|
<h4 id="_kafka_binder_properties">Kafka Binder Properties</h4>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">spring.cloud.stream.kafka.binder.brokers</dt>
|
|
<dd>
|
|
<p>A list of brokers to which the Kafka binder will connect.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>localhost</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.kafka.binder.defaultBrokerPort</dt>
|
|
<dd>
|
|
<p> <code>brokers</code> allows hosts specified with or without port information (e.g., <code>host1,host2:port2</code>).
|
|
This sets the default port when no port is configured in the broker list.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>9092</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.kafka.binder.zkNodes</dt>
|
|
<dd>
|
|
<p>A list of ZooKeeper nodes to which the Kafka binder can connect.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>localhost</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.kafka.binder.defaultZkPort</dt>
|
|
<dd>
|
|
<p> <code>zkNodes</code> allows hosts specified with or without port information (e.g., <code>host1,host2:port2</code>).
|
|
This sets the default port when no port is configured in the node list.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>2181</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.kafka.binder.headers</dt>
|
|
<dd>
|
|
<p>The list of custom headers that will be transported by the binder.</p>
|
|
<div class="paragraph">
|
|
<p>Default: empty.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.kafka.binder.offsetUpdateTimeWindow</dt>
|
|
<dd>
|
|
<p> The frequency, in milliseconds, with which offsets are saved.
|
|
Ignored if <code>0</code>.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>10000</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.kafka.binder.offsetUpdateCount</dt>
|
|
<dd>
|
|
<p> The frequency, in number of updates, which which consumed offsets are persisted.
|
|
Ignored if <code>0</code>.
|
|
Mutually exclusive with <code>offsetUpdateTimeWindow</code>.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>0</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.kafka.binder.requiredAcks</dt>
|
|
<dd>
|
|
<p>The number of required acks on the broker.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>1</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.kafka.binder.minPartitionCount</dt>
|
|
<dd>
|
|
<p> Effective only if <code>autoCreateTopics</code> or <code>autoAddPartitions</code> is set.
|
|
The global minimum number of partitions that the binder will configure on topics on which it produces/consumes data.
|
|
It can be superseded by the <code>partitionCount</code> setting of the producer or by the value of <code>instanceCount</code> * <code>concurrency</code> settings of the producer (if either is larger).</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>1</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.kafka.binder.replicationFactor</dt>
|
|
<dd>
|
|
<p>The replication factor of auto-created topics if <code>autoCreateTopics</code> is active.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>1</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.kafka.binder.autoCreateTopics</dt>
|
|
<dd>
|
|
<p> If set to <code>true</code>, the binder will create new topics automatically.
|
|
If set to <code>false</code>, the binder will rely on the topics being already configured.
|
|
In the latter case, if the topics do not exist, the binder will fail to start.
|
|
Of note, this setting is independent of the <code>auto.topic.create.enable</code> setting of the broker and it does not influence it: if the server is set to auto-create topics, they may be created as part of the metadata retrieval request, with default broker settings.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>true</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.kafka.binder.autoAddPartitions</dt>
|
|
<dd>
|
|
<p> If set to <code>true</code>, the binder will create add new partitions if required.
|
|
If set to <code>false</code>, the binder will rely on the partition size of the topic being already configured.
|
|
If the partition count of the target topic is smaller than the expected value, the binder will fail to start.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>false</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">spring.cloud.stream.kafka.binder.socketBufferSize</dt>
|
|
<dd>
|
|
<p>Size (in bytes) of the socket buffer to be used by the Kafka consumers.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>2097152</code>.</p>
|
|
</div>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_kafka_consumer_properties">Kafka Consumer Properties</h4>
|
|
<div class="paragraph">
|
|
<p>The following properties are available for Kafka consumers only and
|
|
must be prefixed with <code>spring.cloud.stream.kafka.bindings.<channelName>.consumer.</code>.</p>
|
|
</div>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">autoCommitOffset</dt>
|
|
<dd>
|
|
<p> Whether to autocommit offsets when a message has been processed.
|
|
If set to <code>false</code>, an <code>Acknowledgment</code> header will be available in the message headers for late acknowledgment.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>true</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">autoCommitOnError</dt>
|
|
<dd>
|
|
<p> Effective only if <code>autoCommitOffset</code> is set to <code>true</code>.
|
|
If set to <code>false</code> it suppresses auto-commits for messages that result in errors, and will commit only for successful messages, allows a stream to automatically replay from the last successfully processed message, in case of persistent failures.
|
|
If set to <code>true</code>, it will always auto-commit (if auto-commit is enabled).
|
|
If not set (default), it effectively has the same value as <code>enableDlq</code>, auto-committing erroneous messages if they are sent to a DLQ, and not committing them otherwise.</p>
|
|
<div class="paragraph">
|
|
<p>Default: not set.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">recoveryInterval</dt>
|
|
<dd>
|
|
<p>The interval between connection recovery attempts, in milliseconds.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>5000</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">resetOffsets</dt>
|
|
<dd>
|
|
<p>Whether to reset offsets on the consumer to the value provided by <code>startOffset</code>.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>false</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">startOffset</dt>
|
|
<dd>
|
|
<p> The starting offset for new groups, or when <code>resetOffsets</code> is <code>true</code>.
|
|
Allowed values: <code>earliest</code>, <code>latest</code>.</p>
|
|
<div class="paragraph">
|
|
<p>Default: null (equivalent to <code>earliest</code>).</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">enableDlq</dt>
|
|
<dd>
|
|
<p>When set to true, it will send enable DLQ behavior for the consumer.
|
|
Messages that result in errors will be forwarded to a topic named <code>error.<destination>.<group></code>.
|
|
This provides an alternative option to the more common Kafka replay scenario for the case when the number of errors is relatively small and replaying the entire original topic may be too cumbersome.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>false</code>.</p>
|
|
</div>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_kafka_producer_properties">Kafka Producer Properties</h4>
|
|
<div class="paragraph">
|
|
<p>The following properties are available for Kafka producers only and
|
|
must be prefixed with <code>spring.cloud.stream.kafka.bindings.<channelName>.producer.</code>.</p>
|
|
</div>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">bufferSize</dt>
|
|
<dd>
|
|
<p>Upper limit, in bytes, of how much data the Kafka producer will attempt to batch before sending.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>16384</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">sync</dt>
|
|
<dd>
|
|
<p>Whether the producer is synchronous.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>false</code>.</p>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">batchTimeout</dt>
|
|
<dd>
|
|
<p> How long the producer will wait before sending in order to allow more messages to accumulate in the same batch.
|
|
(Normally the producer does not wait at all, and simply sends all the messages that accumulated while the previous send was in progress.) A non-zero value may increase throughput at the expense of latency.</p>
|
|
<div class="paragraph">
|
|
<p>Default: <code>0</code>.</p>
|
|
</div>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="contenttypemanagement">Content Type and Transformation</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>To allow you to propagate information about the content type of produced messages, Spring Cloud Stream attaches, by default, a <code>contentType</code> header to outbound messages.
|
|
For middleware that does not directly support headers, Spring Cloud Stream provides its own mechanism of automatically wrapping outbound messages in an envelope of its own.
|
|
For middleware that does support headers, Spring Cloud Stream applications may receive messages with a given content type from non-Spring Cloud Stream applications.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream can handle messages based on this information in two ways:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>Through its <code>contentType</code> settings on inbound and outbound channels</p>
|
|
</li>
|
|
<li>
|
|
<p>Through its argument mapping performed for methods annotated with <code>@StreamListener</code></p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream allows you to declaratively configure type conversion for inputs and outputs using the <code>content-type</code> property of a binding.
|
|
Note that general type conversion may also be accomplished easily by using a transformer inside your application.
|
|
Currently, Spring Cloud Stream natively supports the following type conversions commonly used in streams:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><strong>JSON</strong> to/from <strong>POJO</strong></p>
|
|
</li>
|
|
<li>
|
|
<p><strong>JSON</strong> to/from <a href="https://github.com/spring-projects/spring-tuple/blob/master/spring-tuple/src/main/java/org/springframework/tuple/Tuple.java">org.springframework.tuple.Tuple</a></p>
|
|
</li>
|
|
<li>
|
|
<p><strong>Object</strong> to/from <strong>byte[]</strong> : Either the raw bytes serialized for remote transport, bytes emitted by an application, or converted to bytes using Java serialization(requires the object to be Serializable)</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>String</strong> to/from <strong>byte[]</strong></p>
|
|
</li>
|
|
<li>
|
|
<p><strong>Object</strong> to <strong>plain text</strong> (invokes the object’s <em>toString()</em> method)</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Where <em>JSON</em> represents either a byte array or String payload containing JSON.
|
|
Currently, Objects may be converted from a JSON byte array or String.
|
|
Converting to JSON always produces a String.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="mime-types">MIME types</h3>
|
|
<div class="paragraph">
|
|
<p><code>content-type</code> values are parsed as media types, e.g., <code>application/json</code> or <code>text/plain;charset=UTF-8</code>.
|
|
MIME types are especially useful for indicating how to convert to String or byte[] content.
|
|
Spring Cloud Stream also uses MIME type format to represent Java types, using the general type <code>application/x-java-object</code> with a <code>type</code> parameter.
|
|
For example, <code>application/x-java-object;type=java.util.Map</code> or <code>application/x-java-object;type=com.bar.Foo</code> can be set as the <code>content-type</code> property of an input binding.
|
|
In addition, Spring Cloud Stream provides custom MIME types, notably, <code>application/x-spring-tuple</code> to specify a Tuple.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="mime-types-and-java-types">MIME types and Java types</h3>
|
|
<div class="paragraph">
|
|
<p>The type conversions Spring Cloud Stream provides out of the box are summarized in the following table:</p>
|
|
</div>
|
|
<table class="tableblock frame-all grid-all spread">
|
|
<colgroup>
|
|
<col style="width: 20%;">
|
|
<col style="width: 20%;">
|
|
<col style="width: 20%;">
|
|
<col style="width: 20%;">
|
|
<col style="width: 20%;">
|
|
</colgroup>
|
|
<thead>
|
|
<tr>
|
|
<th class="tableblock halign-left valign-top">Source Payload</th>
|
|
<th class="tableblock halign-left valign-top">Target Payload</th>
|
|
<th class="tableblock halign-left valign-top">content-type header</th>
|
|
<th class="tableblock halign-left valign-top">content-type</th>
|
|
<th class="tableblock halign-left valign-top">Comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">POJO</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">JSON String</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">ignored</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">application/json</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Tuple</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">JSON String</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">ignored</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">application/json</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">JSON is tailored for Tuple</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">POJO</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">String (toString())</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">ignored</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">text/plain, java.lang.String</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">POJO</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">byte[] (java.io serialized)</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">ignored</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">application/x-java-serialized-object</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">JSON byte[] or String</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">POJO</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">application/json (or none)</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">application/x-java-object</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">byte[] or String</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Serializable</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">application/x-java-serialized-object</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">application/x-java-object</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">JSON byte[] or String</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Tuple</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">application/json (or none)</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">application/x-spring-tuple</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">byte[]</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">any</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">text/plain, java.lang.String</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">will apply any Charset specified in the content-type header</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">byte[]</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">any</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">application/octet-stream</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">will apply any Charset specified in the content-type header</p></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div id="NOTE" class="paragraph">
|
|
<p>Conversion applies to payloads that require type conversion.
|
|
For example, if a module produces an XML string with outputType=application/json, the payload will not be converted from XML to JSON.
|
|
This is because the payload at the module’s output channel is already a String so no conversion will be applied at runtime.</p>
|
|
</div>
|
|
<div id="TIP" class="paragraph">
|
|
<p>While conversion is supported for both input and output channels, it is especially recommended to be used for the conversion of outbound messages.
|
|
For the conversion of inbound messages, especially when the target is a POJO, the <code>@StreamListener</code> support will perform the conversion automatically.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="__code_streamlistener_code_and_message_conversion"><code>`@StreamListener</code> and Message Conversion</h3>
|
|
<div class="paragraph">
|
|
<p>The <code>@StreamListener</code> annotation provides a convenient way for converting incoming messages without the need to specify the content type of an input channel.
|
|
During the dispatching process to methods annotated with <code>@StreamListener</code>, a conversion will be applied automatically if the argument requires it.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>For example, let’s consider a message with the String content <code>{"greeting":"Hello, world"}</code> and a <code>content-type</code> header of <code>application/json</code> is received on the input channel.
|
|
Let us consider the following application that receives it:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">public class GreetingMessage {
|
|
|
|
String greeting;
|
|
|
|
public String getGreeting() {
|
|
return greeting;
|
|
}
|
|
|
|
public void setGreeting(String greeting) {
|
|
this.greeting = greeting;
|
|
}
|
|
}
|
|
|
|
@EnableBinding(Sink.class)
|
|
@EnableAutoConfiguration
|
|
public static class GreetingSink {
|
|
|
|
@StreamListener(Sink.INPUT)
|
|
public void receive(Greeting greeting) {
|
|
// handle Greeting
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The argument of the method will be populated automatically with the POJO containing the unmarshalled form of the JSON String.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_inter_application_communication">Inter-Application Communication</h2>
|
|
<div class="sectionbody">
|
|
<div class="sect2">
|
|
<h3 id="_connecting_multiple_application_instances">Connecting Multiple Application Instances</h3>
|
|
<div class="paragraph">
|
|
<p>While Spring Cloud Stream makes it easy for individual Spring Boot applications to connect to messaging systems, the typical scenario for Spring Cloud Stream is the creation of multi-application pipelines, where microservice applications send data to each other.
|
|
You can achieve this scenario by correlating the input and output destinations of adjacent applications.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Supposing that a design calls for the Time Source application to send data to the Log Sink application, you can use a common destination named <code>ticktock</code> for bindings within both applications.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Time Source (that has the channel name <code>output</code>) will set the following property:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>spring.cloud.stream.bindings.output.destination=ticktock</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Log Sink (that has the channel name <code>input</code>) will set the following property:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>spring.cloud.stream.bindings.input.destination=ticktock</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_instance_index_and_instance_count">Instance Index and Instance Count</h3>
|
|
<div class="paragraph">
|
|
<p>When scaling up Spring Cloud Stream applications, each instance can receive information about how many other instances of the same application exist and what its own instance index is.
|
|
Spring Cloud Stream does this through the <code>spring.cloud.stream.instanceCount</code> and <code>spring.cloud.stream.instanceIndex</code> properties.
|
|
For example, if there are three instances of a HDFS sink application, all three instances will have <code>spring.cloud.stream.instanceCount</code> set to <code>3</code>, and the individual applications will have <code>spring.cloud.stream.instanceIndex</code> set to <code>0</code>, <code>1</code>, and <code>2</code>, respectively.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>When Spring Cloud Stream applications are deployed via Spring Cloud Data Flow, these properties are configured automatically; when Spring Cloud Stream applications are launched independently, these properties must be set correctly.
|
|
By default, <code>spring.cloud.stream.instanceCount</code> is <code>1</code>, and <code>spring.cloud.stream.instanceIndex</code> is <code>0</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In a scaled-up scenario, correct configuration of these two properties is important for addressing partitioning behavior (see below) in general, and the two properties are always required by certain binders (e.g., the Kafka binder) in order to ensure that data are split correctly across multiple consumer instances.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_partitioning">Partitioning</h3>
|
|
<div class="sect3">
|
|
<h4 id="_configuring_output_bindings_for_partitioning">Configuring Output Bindings for Partitioning</h4>
|
|
<div class="paragraph">
|
|
<p>An output binding is configured to send partitioned data by setting one and only one of its <code>partitionKeyExpression</code> or <code>partitionKeyExtractorClass</code> properties, as well as its <code>partitionCount</code> property.
|
|
For example, the following is a valid and typical configuration:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>spring.cloud.stream.bindings.output.producer.partitionKeyExpression=payload.id
|
|
spring.cloud.stream.bindings.output.producer.partitionCount=5</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Based on the above example configuration, data will be sent to the target partition using the following logic.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>A partition key’s value is calculated for each message sent to a partitioned output channel based on the <code>partitionKeyExpression</code>.
|
|
The <code>partitionKeyExpression</code> is a SpEL expression which is evaluated against the outbound message for extracting the partitioning key.</p>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Tip</div>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>If a SpEL expression is not sufficient for your needs, you can instead calculate the partition key value by setting the property <code>partitionKeyExtractorClass</code> to a class which implements the <code>org.springframework.cloud.stream.binder.PartitionKeyExtractorStrategy</code> interface.
|
|
While the SpEL expression should usually suffice, more complex cases may use the custom implementation strategy.</p>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Once the message key is calculated, the partition selection process will determine the target partition as a value between <code>0</code> and <code>partitionCount - 1</code>.
|
|
The default calculation, applicable in most scenarios, is based on the formula <code>key.hashCode() % partitionCount</code>.
|
|
This can be customized on the binding, either by setting a SpEL expression to be evaluated against the key (via the <code>partitionSelectorExpression</code> property) or by setting a <code>org.springframework.cloud.stream.binder.PartitionSelectorStrategy</code> implementation (via the <code>partitionSelectorClass</code> property).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Additional properties can be configured for more advanced scenarios, as described in the following section.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>The Kafka binder will use the <code>partitionCount</code> setting as a hint to create a topic with the given partition count (in conjunction with the <code>minPartitionCount</code>, the maximum of the two being the value being used).
|
|
Exercise caution when configuring both <code>minPartitionCount</code> for a binder and <code>partitionCount</code> for an application, as the larger value will be used.
|
|
If a topic already exists with a smaller partition count and <code>autoAddPartitions</code> is disabled (the default), then the binder will fail to start.
|
|
If a topic already exists with a smaller partition count and <code>autoAddPartitions</code> is enabled, new partitions will be added.
|
|
If a topic already exists with a larger number of partitions than the maximum of (<code>minPartitionCount</code> and <code>partitionCount</code>), the existing partition count will be used.</p>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="sect4">
|
|
<h5 id="_configuring_input_bindings_for_partitioning">Configuring Input Bindings for Partitioning</h5>
|
|
<div class="paragraph">
|
|
<p>An input binding (with the channel name <code>input</code>) is configured to receive partitioned data by setting its <code>partitioned</code> property, as well as the <code>instanceIndex</code> and <code>instanceCount</code> properties on the application itself, as in the following example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>spring.cloud.stream.bindings.input.consumer.partitioned=true
|
|
spring.cloud.stream.instanceIndex=3
|
|
spring.cloud.stream.instanceCount=5</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>instanceCount</code> value represents the total number of application instances between which the data need to be partitioned, and the <code>instanceIndex</code> must be a unique value across the multiple instances, between <code>0</code> and <code>instanceCount - 1</code>.
|
|
The instance index helps each application instance to identify the unique partition (or, in the case of Kafka, the partition set) from which it receives data.
|
|
It is important to set both values correctly in order to ensure that all of the data is consumed and that the application instances receive mutually exclusive datasets.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>While a scenario which using multiple instances for partitioned data processing may be complex to set up in a standalone case, Spring Cloud Dataflow can simplify the process significantly by populating both the input and output values correctly as well as relying on the runtime infrastructure to provide information about the instance index and instance count.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_testing">Testing</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream provides support for testing your microservice applications without connecting to a messaging system.
|
|
You can do that by using the <code>TestSupportBinder</code>.
|
|
This is useful especially for unit testing your microservices.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>TestSupportBinder</code> allows users to interact with the bound channels and inspect what messages are sent and received by the application</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>For outbound message channels, the <code>TestSupportBinder</code> registers a single subscriber and retains the messages emitted by the application in a <code>MessageCollector</code>.
|
|
They can be retrieved during tests and have assertions made against them.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The user can also send messages to inbound message channels, so that the consumer application can consume the messages.
|
|
The following example shows how to test both input and output channels on a processor.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@RunWith(SpringJUnit4ClassRunner.class)
|
|
@SpringApplicationConfiguration(classes = ExampleTest.MyProcessor.class)
|
|
@IntegrationTest({"server.port=-1"})
|
|
@DirtiesContext
|
|
public class ExampleTest {
|
|
|
|
@Autowired
|
|
private Processor processor;
|
|
|
|
@Autowired
|
|
private BinderFactory<MessageChannel> binderFactory;
|
|
|
|
@Autowired
|
|
private MessageCollector messageCollector;
|
|
|
|
@Test
|
|
@SuppressWarnings("unchecked")
|
|
public void testWiring() {
|
|
Message<String> message = new GenericMessage<>("hello");
|
|
processor.input().send(message);
|
|
Message<String> received = (Message<String>) messageCollector.forChannel(processor.output()).poll();
|
|
assertThat(received.getPayload(), equalTo("hello world"));
|
|
}
|
|
|
|
|
|
@SpringBootApplication
|
|
@EnableBinding(Processor.class)
|
|
public static class MyProcessor {
|
|
|
|
@Autowired
|
|
private Processor channels;
|
|
|
|
@Transformer(inputChannel = Processor.INPUT, outputChannel = Processor.OUTPUT)
|
|
public String transform(String in) {
|
|
return in + " world";
|
|
}
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In the example above, we are creating an application that has an input and an output channel, bound through the <code>Processor</code> interface.
|
|
The bound interface is injected into the test so we can have access to both channels.
|
|
We are sending a message on the input channel and we are using the <code>MessageCollector</code> provided by Spring Cloud Stream’s test support to capture the message has been sent to the output channel as a result.
|
|
Once we have received the message, we can validate that the component functions correctly.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_health_indicator_3">Health Indicator</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Stream provides a health indicator for binders.
|
|
It is registered under the name of <code>binders</code> and can be enabled or disabled by setting the <code>management.health.binders.enabled</code> property.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_samples">Samples</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>For Spring Cloud Stream samples, please refer to the <a href="https://github.com/spring-cloud/spring-cloud-stream-samples">spring-cloud-stream-samples</a> repository on GitHub.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_getting_started">Getting Started</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>To get started with creating Spring Cloud Stream applications, visit the <a href="https://start.spring.io">Spring Initializr</a> and create a new Maven project named "GreetingSource".
|
|
Select Spring Boot version 1.3.4 SNAPSHOT and search or tick the checkbox for Stream Kafka (we will be using Kafka for messaging).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Next, create a new class, <code>GreetingSource</code>, in the same package as the <code>GreetingSourceApplication</code> class.
|
|
Give it the following code:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">import org.springframework.cloud.stream.annotation.EnableBinding;
|
|
import org.springframework.cloud.stream.messaging.Source;
|
|
import org.springframework.integration.annotation.InboundChannelAdapter;
|
|
|
|
@EnableBinding(Source.class)
|
|
public class GreetingSource {
|
|
|
|
@InboundChannelAdapter(Source.OUTPUT)
|
|
public String greet() {
|
|
return "hello world " + System.currentTimeMillis();
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>@EnableBinding</code> annotation is what triggers the creation of Spring Integration infrastructure components.
|
|
Specifically, it will create a Kafka connection factory, a Kafka outbound channel adapter, and the message channel defined inside the Source interface:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">public interface Source {
|
|
|
|
String OUTPUT = "output";
|
|
|
|
@Output(Source.OUTPUT)
|
|
MessageChannel output();
|
|
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The auto-configuration also creates a default poller, so that the <code>greet()</code> method will be invoked once per second.
|
|
The standard Spring Integration <code>@InboundChannelAdapter</code> annotation sends a message to the source’s output channel, using the return value as the payload of the message.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To test-drive this setup, run a Kafka message broker.
|
|
An easy way to do this is to use a Docker image:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code># On OS X
|
|
$ docker run -p 2181:2181 -p 9092:9092 --env ADVERTISED_HOST=`docker-machine ip \`docker-machine active\`` --env ADVERTISED_PORT=9092 spotify/kafka
|
|
|
|
# On Linux
|
|
$ docker run -p 2181:2181 -p 9092:9092 --env ADVERTISED_HOST=localhost --env ADVERTISED_PORT=9092 spotify/kafka</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Build the application:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>./mvnw clean package</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The consumer application is coded in a similar manner.
|
|
Go back to Initializr and create another project, named LoggingSink.
|
|
Then create a new class, <code>LoggingSink</code>, in the same package as the class <code>LoggingSinkApplication</code> and with the following code:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">import org.springframework.cloud.stream.annotation.EnableBinding;
|
|
import org.springframework.cloud.stream.annotation.StreamListener;
|
|
import org.springframework.cloud.stream.messaging.Sink;
|
|
|
|
@EnableBinding(Sink.class)
|
|
public class LoggingSink {
|
|
|
|
@StreamListener(Sink.INPUT)
|
|
public void log(String message) {
|
|
System.out.println(message);
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Build the application:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>./mvnw clean package</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To connect the GreetingSource application to the LoggingSink application, each application must share the same destination name.
|
|
Starting up both applications as shown below, you will see the consumer application printing "hello world" and a timestamp to the console:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code>cd GreetingSource
|
|
java -jar target/GreetingSource-0.0.1-SNAPSHOT.jar --spring.cloud.stream.bindings.output.destination=mydest
|
|
|
|
cd LoggingSink
|
|
java -jar target/LoggingSink-0.0.1-SNAPSHOT.jar --server.port=8090 --spring.cloud.stream.bindings.input.destination=mydest</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>(The different server port prevents collisions of the HTTP port used to service the Spring Boot Actuator endpoints in the two applications.)</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The output of the LoggingSink application will look something like the following:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code>[ main] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 8090 (http)
|
|
[ main] com.example.LoggingSinkApplication : Started LoggingSinkApplication in 6.828 seconds (JVM running for 7.371)
|
|
hello world 1458595076731
|
|
hello world 1458595077732
|
|
hello world 1458595078733
|
|
hello world 1458595079734
|
|
hello world 1458595080735</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<h1 id="_spring_cloud_bus" class="sect0">Spring Cloud Bus</h1>
|
|
<div class="openblock partintro">
|
|
<div class="content">
|
|
Spring Cloud Bus links nodes of a distributed system with a lightweight message broker. This can then be used to broadcast state changes (e.g. configuration changes) or other management instructions. A key idea is that the Bus is like a distributed Actuator for a Spring Boot application that is scaled out, but it can also be used as a communication channel between apps. The only implementation currently is with an AMQP broker as the transport, but the same basic feature set (and some more depending on the transport) is on the roadmap for other transports.
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_quick_start_2">Quick Start</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Bus works by adding Spring Boot autconfiguration if it detects itself on the classpath. All you need to do to enable the bus is to add <code>spring-cloud-starter-bus-amqp</code> or <code>spring-cloud-starter-bus-kafka</code> to your dependency management and Spring Cloud takes care of the rest. Make sure the broker (RabbitMQ or Kafka) is available and configured: running on localhost you shouldn’t have to do anything, but if you are running remotely use Spring Cloud Connectors, or Spring Boot conventions to define the broker credentials, e.g. for Rabbit</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>spring:
|
|
rabbitmq:
|
|
host: mybroker.com
|
|
port: 5672
|
|
username: user
|
|
password: secret</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The bus currently supports sending messages to all nodes listening or all nodes for a particular service (as defined by Eureka). More selector criteria may be added in the future (ie. only service X nodes in data center Y, etc…​). There are also some http endpoints are under the <code>/bus/*</code> actuator namespace. There are currently two implemented. The first, <code>/bus/env</code>, sends key/values pairs to update each nodes Spring Environment. The second, <code>/bus/refresh</code>, will reload each application’s configuration, just as if they had all been pinged on their <code>/refresh</code> endpoint.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
the Bus starters cover Rabbit and Kafka, because those are the two most common implementations, but Spring Cloud Stream is quite flexible and binder will work combined with <code>spring-cloud-bus</code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_addressing_an_instance">Addressing an Instance</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>The HTTP endpoints accept a "destination" parameter, e.g. "/bus/refresh?destination=customers:9000", where the destination is an <code>ApplicationContext</code> ID. If the ID is owned by an instance on the Bus then it will process the message and all other instances will ignore it. Spring Boot sets the ID for you in the <code>ContextIdApplicationContextInitializer</code> to a combination of the <code>spring.application.name</code>, active profiles and <code>server.port</code> by default.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_addressing_all_instances_of_a_service">Addressing all instances of a service</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>The "destination" parameter is used in a Spring <code>PathMatcher</code> (with the path separator as a colon <code>:</code>) to determine if an instance will process the message. Using the example from above, "/bus/refresh?destination=customers:**" will target all instances of the "customers" service regardless of the profiles and ports set as the <code>ApplicationContext</code> ID.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_application_context_id_must_be_unique">Application Context ID must be unique</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>The bus tries to eliminate processing an event twice, once from the original <code>ApplicationEvent</code> and once from the queue. To do this, it checks the sending application context id againts the current application context id. If multiple instances of a service have the same application context id, events will not be processed. Running on a local machine, each service will be on a different port and that will be part of the application context id. Cloud Foundry supplies an index to differentiate. To ensure that the application context id is the unique, set <code>spring.application.index</code> to something unique for each instance of a service. For example, in lattice, set <code>spring.application.index=${INSTANCE_INDEX}</code> in application.properties (or bootstrap.properties if using configserver).</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_customizing_the_message_broker">Customizing the Message Broker</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Bus uses
|
|
<a href="https://cloud.spring.io/spring-cloud-stream">Spring Cloud Stream</a> to
|
|
broadcast the messages so to get messages to flow you only need to
|
|
include the binder implementation of your choice in the
|
|
classpath. There are convenient starters specifically for the bus with
|
|
AMQP (RabbitMQ) and Kafka
|
|
(<code>spring-cloud-starter-bus-[amqp,kafka]</code>). Generally speaking
|
|
Spring Cloud Stream relies on Spring Boot autoconfiguration
|
|
conventions for configuring middleware, so for instance the AMQP
|
|
broker address can be changed with <code>spring.rabbitmq.*</code>
|
|
configuration properties. Spring Cloud Bus has a handful of native
|
|
configuration properties in <code>spring.cloud.bus.*</code>
|
|
(e.g. <code>spring.cloud.bus.destination</code> is the name of the topic to use
|
|
the the externall middleware). Normally the defaults will suffice.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To lean more about how to customize the message broker settings
|
|
consult the Spring Cloud Stream documentation.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_tracing_bus_events">Tracing Bus Events</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Bus events (subclasses of <code>RemoteApplicationEvent</code>) can be traced by
|
|
setting <code>spring.cloud.bus.trace.enabled=true</code>. If you do this then the
|
|
Spring Boot <code>TraceRepository</code> (if it is present) will show each event
|
|
sent and all the acks from each service instance. Example (from the
|
|
<code>/trace</code> endpoint):</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-json" data-lang="json">{
|
|
"timestamp": "2015-11-26T10:24:44.411+0000",
|
|
"info": {
|
|
"signal": "spring.cloud.bus.ack",
|
|
"type": "RefreshRemoteApplicationEvent",
|
|
"id": "c4d374b7-58ea-4928-a312-31984def293b",
|
|
"origin": "stores:8081",
|
|
"destination": "*:**"
|
|
}
|
|
},
|
|
{
|
|
"timestamp": "2015-11-26T10:24:41.864+0000",
|
|
"info": {
|
|
"signal": "spring.cloud.bus.sent",
|
|
"type": "RefreshRemoteApplicationEvent",
|
|
"id": "c4d374b7-58ea-4928-a312-31984def293b",
|
|
"origin": "customers:9000",
|
|
"destination": "*:**"
|
|
}
|
|
},
|
|
{
|
|
"timestamp": "2015-11-26T10:24:41.862+0000",
|
|
"info": {
|
|
"signal": "spring.cloud.bus.ack",
|
|
"type": "RefreshRemoteApplicationEvent",
|
|
"id": "c4d374b7-58ea-4928-a312-31984def293b",
|
|
"origin": "customers:9000",
|
|
"destination": "*:**"
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This trace shows that a <code>RefreshRemoteApplicationEvent</code> was sent from
|
|
<code>customers:9000</code>, broadcast to all services, and it was received
|
|
(acked) by <code>customers:9000</code> and <code>stores:8081</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To handle the ack signals yourself you could add an <code>@EventListener</code>
|
|
for the <code>AckRemoteApplicationEvent</code> and <code>SentApplicationEvent</code> types
|
|
to your app (and enable tracing). Or you could tap into the
|
|
<code>TraceRepository</code> and mine the data from there.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
Any Bus application can trace acks, but sometimes it will be
|
|
useful to do this in a central service that can do more complex
|
|
queries on the data. Or forward it to a specialized tracing service.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_broadcasting_your_own_events">Broadcasting Your Own Events</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>The Bus can carry any event of type <code>RemoteApplicationEvent</code>, but the
|
|
default transport is JSON and the deserializer needs to know which
|
|
types are going to be used ahead of time. To register a new type it
|
|
needs to be in a subpackage of <code>org.springframework.cloud.bus.event</code>.
|
|
You can use <code>@JsonTypeName</code> on your custom class or rely on the
|
|
default strategy which is to use the simple name of the class. Note
|
|
that both the producer and the consumer will need access to the class
|
|
definition.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<h1 id="_spring_cloud_sleuth" class="sect0">Spring Cloud Sleuth</h1>
|
|
<div class="openblock partintro">
|
|
<div class="content">
|
|
<div class="paragraph">
|
|
<p>Adrian Cole, Spencer Gibb, Marcin Grzejszczak, Dave Syer
|
|
:doctype: book</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Sleuth implements a distributed tracing solution for <a href="http://cloud.spring.io">Spring Cloud</a>.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_terminology">Terminology</h3>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Sleuth borrows <a href="http://research.google.com/pubs/pub36356.html">Dapper’s</a> terminology.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><strong>Span:</strong> The basic unit of work. For example, sending an RPC is a new span, as is sending a response to an
|
|
RPC. Span’s are identified by a unique 64-bit ID for the span and another 64-bit ID for the trace the span
|
|
is a part of. Spans also have other data, such as descriptions, timestamped events, key-value
|
|
annotations (tags), the ID of the span that caused them, and process ID’s (normally IP address).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spans are started and stopped, and they keep track of their timing information. Once you create a
|
|
span, you must stop it at some point in the future.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><strong>Trace:</strong> A set of spans forming a tree-like structure. For example, if you are running a distributed
|
|
big-data store, a trace might be formed by a put request.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><strong>Annotation:</strong> is used to record existence of an event in time. Some of the core annotations used to define
|
|
the start and stop of a request are:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><strong>cs</strong> - Client Sent - The client has made a request. This annotation depicts the start of the span.</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>sr</strong> - Server Received - The server side got the request and will start processing it.
|
|
If one subtracts the cs timestamp from this timestamp one will receive the network latency.</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>ss</strong> - Server Sent - Annotated upon completion of request processing (when the response
|
|
got sent back to the client). If one subtracts the sr timestamp from this timestamp one
|
|
will receive the time needed by the server side to process the request.</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>cr</strong> - Client Received - Signifies the end of the span. The client has successfully received the
|
|
response from the server side. If one subtracts the cs timestamp from this timestamp one
|
|
will receive the whole time needed by the client to receive the response from the server.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Visualization of what <strong>Span</strong> and <strong>Trace</strong> will look in a system together with the Zipkin annotations:</p>
|
|
</div>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/trace-id.png" alt="Trace Info propagation">
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Each color of a note signifies a span (7 spans - from <strong>A</strong> to <strong>G</strong>). If you have such information in the note:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code>Trace Id = X
|
|
Span Id = D
|
|
Client Sent</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>That means that the current span has <strong>Trace-Id</strong> set to <strong>X</strong>, <strong>Span-Id</strong> set to <strong>D</strong>. It also has emitted
|
|
<strong>Client Sent</strong> event.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This is how the visualization of the parent / child relationship of spans would look like:</p>
|
|
</div>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/parents.png" alt="Parent child relationship">
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_purpose">Purpose</h3>
|
|
<div class="paragraph">
|
|
<p>In the following sections the example from the image above will be taken into consideration.</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_distributed_tracing_with_zipkin">Distributed tracing with Zipkin</h4>
|
|
<div class="paragraph">
|
|
<p>Altogether there are <strong>10 spans</strong> . If you go to traces in Zipkin you will see this number:</p>
|
|
</div>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/zipkin-traces.png" alt="Traces">
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>However if you pick a particular trace then you will see <strong>7 spans</strong>:</p>
|
|
</div>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/zipkin-ui.png" alt="Traces Info propagation">
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
When picking a particular trace you will see merged spans. That means that if there were 2 spans sent to
|
|
Zipkin with Server Received and Server Sent / Client Received and Client Sent
|
|
annotations then they will presented as a single span.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In the image depicting the visualization of what <strong>Span</strong> and <strong>Trace</strong> is you can see 20
|
|
colorful labels. How does it happen that in Zipkin 10 spans are received?</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>2 span <strong>A</strong> labels signify span started and closed. Upon closing a single span is sent to Zipkin.</p>
|
|
</li>
|
|
<li>
|
|
<p>4 span <strong>B</strong> labels are in fact are single span with 4 annotations. However this span is composed of
|
|
two separate instances. One sent from service 1 and one from service 2. So in fact two span instances will be sent
|
|
to Zipkin and merged there.</p>
|
|
</li>
|
|
<li>
|
|
<p>2 span <strong>C</strong> labels signify span started and closed. Upon closing a single span is sent to Zipkin.</p>
|
|
</li>
|
|
<li>
|
|
<p>4 span <strong>B</strong> labels are in fact are single span with 4 annotations. However this span is composed of
|
|
two separate instances. One sent from service 2 and one from service 3. So in fact two span instances will be sent
|
|
to Zipkin and merged there.</p>
|
|
</li>
|
|
<li>
|
|
<p>2 span <strong>E</strong> labels signify span started and closed. Upon closing a single span is sent to Zipkin.</p>
|
|
</li>
|
|
<li>
|
|
<p>4 span <strong>B</strong> labels are in fact are single span with 4 annotations. However this span is composed of
|
|
two separate instances. One sent from service 2 and one from service 4. So in fact two span instances will be sent
|
|
to Zipkin and merged there.</p>
|
|
</li>
|
|
<li>
|
|
<p>2 span <strong>G</strong> labels signify span started and closed. Upon closing a single span is sent to Zipkin.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>So 1 span from <strong>A</strong>, 2 spans from <strong>B</strong>, 1 span from <strong>C</strong>, 2 spans from <strong>D</strong>, 1 span from <strong>E</strong>, 2 spans from <strong>F</strong> and 1 from <strong>G</strong>.
|
|
Altogether <strong>10</strong> spans.</p>
|
|
</div>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<a class="image" href="http://docssleuth-zipkin-server.cfapps.io/"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/pws.png" alt="Zipkin deployed on Pivotal Web Services" width="150" height="74"></a>
|
|
</div>
|
|
<div class="title">Click Pivotal Web Services icon to see it live!Click Pivotal Web Services icon to see it live!</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The dependency graph in Zipkin would look like this:</p>
|
|
</div>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/dependencies.png" alt="Dependencies">
|
|
</div>
|
|
</div>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<a class="image" href="http://docssleuth-zipkin-server.cfapps.io/dependency"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/pws.png" alt="Zipkin deployed on Pivotal Web Services" width="150" height="74"></a>
|
|
</div>
|
|
<div class="title">Click Pivotal Web Services icon to see it live!Click Pivotal Web Services icon to see it live!</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_log_correlation">Log correlation</h4>
|
|
<div class="paragraph">
|
|
<p>When grepping the logs of those four applications by trace id equal to e.g. <code>2485ec27856c56f4</code> one would get the following:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code>service1.log:2016-02-26 11:15:47.561 INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application : Hello from service1. Calling service2
|
|
service2.log:2016-02-26 11:15:47.710 INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application : Hello from service2. Calling service3 and then service4
|
|
service3.log:2016-02-26 11:15:47.895 INFO [service3,2485ec27856c56f4,1210be13194bfe5,true] 68060 --- [nio-8083-exec-1] i.s.c.sleuth.docs.service3.Application : Hello from service3
|
|
service2.log:2016-02-26 11:15:47.924 INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application : Got response from service3 [Hello from service3]
|
|
service4.log:2016-02-26 11:15:48.134 INFO [service4,2485ec27856c56f4,1b1845262ffba49d,true] 68061 --- [nio-8084-exec-1] i.s.c.sleuth.docs.service4.Application : Hello from service4
|
|
service2.log:2016-02-26 11:15:48.156 INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application : Got response from service4 [Hello from service4]
|
|
service1.log:2016-02-26 11:15:48.182 INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application : Got response from service2 [Hello from service2, response from service3 [Hello from service3] and from service4 [Hello from service4]]</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you’re using a log aggregating tool like <a href="https://www.elastic.co/products/kibana">Kibana</a>,
|
|
<a href="http://www.splunk.com/">Splunk</a> etc. you can order the events that took place. An example of
|
|
Kibana would look like this:</p>
|
|
</div>
|
|
<div class="imageblock">
|
|
<div class="content">
|
|
<img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/kibana.png" alt="Log correlation with Kibana">
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you want to use <a href="https://www.elastic.co/guide/en/logstash/current/index.html">Logstash</a> here is the Grok pattern for Logstash:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code>filter {
|
|
# pattern matching logback pattern
|
|
grok {
|
|
match => { "message" => "%{TIMESTAMP_ISO8601:timestamp}\s+%{LOGLEVEL:severity}\s+\[%{DATA:service},%{DATA:trace},%{DATA:span},%{DATA:exportable}\]\s+%{DATA:pid}---\s+\[%{DATA:thread}\]\s+%{DATA:class}\s+:\s+%{GREEDYDATA:rest}" }
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
If you want to use Grok together with the logs from Cloud Foundry you have to use this pattern:
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code>filter {
|
|
# pattern matching logback pattern
|
|
grok {
|
|
match => { "message" => "(?m)OUT\s+%{TIMESTAMP_ISO8601:timestamp}\s+%{LOGLEVEL:severity}\s+\[%{DATA:service},%{DATA:trace},%{DATA:span},%{DATA:exportable}\]\s+%{DATA:pid}---\s+\[%{DATA:thread}\]\s+%{DATA:class}\s+:\s+%{GREEDYDATA:rest}" }
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="sect4">
|
|
<h5 id="_json_logback_with_logstash">JSON Logback with Logstash</h5>
|
|
<div class="paragraph">
|
|
<p>Often you do not want to store your logs in a text file but in a JSON file that Logstash can immediately pick. To do that you have to do the following (for readability
|
|
we’re passing the dependencies in the <code>groupId:artifactId:version</code> notation.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><strong>Dependencies setup</strong></p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>Ensure that Logback is on the classpath (<code>ch.qos.logback:logback-core</code>)</p>
|
|
</li>
|
|
<li>
|
|
<p>Add Logstash Logback encode - example for version <code>4.6</code> : <code>net.logstash.logback:logstash-logback-encoder:4.6</code></p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><strong>Logback setup</strong></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Below you can find an example of a Logback configuration (file named <code><a href="https://github.com/spring-cloud-samples/sleuth-documentation-apps/blob/master/service1/src/main/resources/logback-spring.xml">logback-spring.xml</a></code>) that:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>logs information from the application in a JSON format to a <code>build/${spring.application.name}.json</code> file</p>
|
|
</li>
|
|
<li>
|
|
<p>has commented out two additional appenders - console and standard log file</p>
|
|
</li>
|
|
<li>
|
|
<p>has the same logging pattern as the one presented in the previous section</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-xml" data-lang="xml"></code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_adding_to_the_project">Adding to the project</h3>
|
|
<div class="sect3">
|
|
<h4 id="_only_sleuth_log_correlation">Only Sleuth (log correlation)</h4>
|
|
<div class="paragraph">
|
|
<p>If you want to profit only from Spring Cloud Sleuth without the Zipkin integration just add
|
|
the <code>spring-cloud-starter-sleuth</code> module to your project.</p>
|
|
</div>
|
|
<div class="listingblock primary">
|
|
<div class="title">Maven</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-xml" data-lang="xml"><dependencyManagement> <b class="conum">(1)</b>
|
|
<dependencies>
|
|
<dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-dependencies</artifactId>
|
|
<version>Brixton.RELEASE</version>
|
|
<type>pom</type>
|
|
<scope>import</scope>
|
|
</dependency>
|
|
</dependencies>
|
|
</dependencyManagement>
|
|
|
|
<dependency> <b class="conum">(2)</b>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-starter-sleuth</artifactId>
|
|
</dependency></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="colist arabic">
|
|
<ol>
|
|
<li>
|
|
<p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p>
|
|
</li>
|
|
<li>
|
|
<p>Add the dependency to <code>spring-cloud-starter-sleuth</code></p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div class="listingblock secondary">
|
|
<div class="title">Gradle</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-groovy" data-lang="groovy">dependencyManagement { <b class="conum">(1)</b>
|
|
imports {
|
|
mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
|
|
}
|
|
}
|
|
|
|
dependencies { <b class="conum">(2)</b>
|
|
compile "org.springframework.cloud:spring-cloud-starter-sleuth"
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="colist arabic">
|
|
<ol>
|
|
<li>
|
|
<p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p>
|
|
</li>
|
|
<li>
|
|
<p>Add the dependency to <code>spring-cloud-starter-sleuth</code></p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_sleuth_with_zipkin_via_http">Sleuth with Zipkin via HTTP</h4>
|
|
<div class="paragraph">
|
|
<p>If you want both Sleuth and Zipkin just add the <code>spring-cloud-starter-zipkin</code> dependency.</p>
|
|
</div>
|
|
<div class="listingblock primary">
|
|
<div class="title">Maven</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-xml" data-lang="xml"><dependencyManagement> <b class="conum">(1)</b>
|
|
<dependencies>
|
|
<dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-dependencies</artifactId>
|
|
<version>Brixton.RELEASE</version>
|
|
<type>pom</type>
|
|
<scope>import</scope>
|
|
</dependency>
|
|
</dependencies>
|
|
</dependencyManagement>
|
|
|
|
<dependency> <b class="conum">(2)</b>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-starter-zipkin</artifactId>
|
|
</dependency></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="colist arabic">
|
|
<ol>
|
|
<li>
|
|
<p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p>
|
|
</li>
|
|
<li>
|
|
<p>Add the dependency to <code>spring-cloud-starter-zipkin</code></p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div class="listingblock secondary">
|
|
<div class="title">Gradle</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-groovy" data-lang="groovy">dependencyManagement { <b class="conum">(1)</b>
|
|
imports {
|
|
mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
|
|
}
|
|
}
|
|
|
|
dependencies { <b class="conum">(2)</b>
|
|
compile "org.springframework.cloud:spring-cloud-starter-zipkin"
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="colist arabic">
|
|
<ol>
|
|
<li>
|
|
<p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p>
|
|
</li>
|
|
<li>
|
|
<p>Add the dependency to <code>spring-cloud-starter-zipkin</code></p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_sleuth_with_zipkin_via_spring_cloud_stream">Sleuth with Zipkin via Spring Cloud Stream</h4>
|
|
<div class="paragraph">
|
|
<p>If you want both Sleuth and Zipkin just add the <code>spring-cloud-sleuth-stream</code> dependency.</p>
|
|
</div>
|
|
<div class="listingblock primary">
|
|
<div class="title">Maven</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-xml" data-lang="xml"><dependencyManagement> <b class="conum">(1)</b>
|
|
<dependencies>
|
|
<dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-dependencies</artifactId>
|
|
<version>Brixton.RELEASE</version>
|
|
<type>pom</type>
|
|
<scope>import</scope>
|
|
</dependency>
|
|
</dependencies>
|
|
</dependencyManagement>
|
|
|
|
<dependency> <b class="conum">(2)</b>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-sleuth-stream</artifactId>
|
|
</dependency>
|
|
<dependency> <b class="conum">(3)</b>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-starter-sleuth</artifactId>
|
|
</dependency>
|
|
<!-- EXAMPLE FOR RABBIT BINDING -->
|
|
<dependency> <b class="conum">(4)</b>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-stream-binder-rabbit</artifactId>
|
|
</dependency></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="colist arabic">
|
|
<ol>
|
|
<li>
|
|
<p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p>
|
|
</li>
|
|
<li>
|
|
<p>Add the dependency to <code>spring-cloud-sleuth-stream</code></p>
|
|
</li>
|
|
<li>
|
|
<p>Add the dependency to <code>spring-cloud-starter-sleuth</code> - that way all dependant dependencies will be downloaded</p>
|
|
</li>
|
|
<li>
|
|
<p>Add a binder (e.g. Rabbit binder) to tell Spring Cloud Stream what it should bind to</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div class="listingblock secondary">
|
|
<div class="title">Gradle</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-groovy" data-lang="groovy">dependencyManagement { <b class="conum">(1)</b>
|
|
imports {
|
|
mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
|
|
}
|
|
}
|
|
|
|
dependencies {
|
|
compile "org.springframework.cloud:spring-cloud-sleuth-stream" <b class="conum">(2)</b>
|
|
compile "org.springframework.cloud:spring-cloud-starter-sleuth" <b class="conum">(3)</b>
|
|
// Example for Rabbit binding
|
|
compile "org.springframework.cloud:spring-cloud-stream-binder-rabbit" <b class="conum">(4)</b>
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="colist arabic">
|
|
<ol>
|
|
<li>
|
|
<p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p>
|
|
</li>
|
|
<li>
|
|
<p>Add the dependency to <code>spring-cloud-sleuth-stream</code></p>
|
|
</li>
|
|
<li>
|
|
<p>Add the dependency to <code>spring-cloud-starter-sleuth</code> - that way all dependant dependencies will be downloaded</p>
|
|
</li>
|
|
<li>
|
|
<p>Add a binder (e.g. Rabbit binder) to tell Spring Cloud Stream what it should bind to</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_spring_cloud_sleuth_stream_zipkin_collector">Spring Cloud Sleuth Stream Zipkin Collector</h4>
|
|
<div class="paragraph">
|
|
<p>If you want to start a Spring Cloud Sleuth Stream Zipkin collector just add the <code>spring-cloud-sleuth-zipkin-stream</code>
|
|
dependency</p>
|
|
</div>
|
|
<div class="listingblock primary">
|
|
<div class="title">Maven</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-xml" data-lang="xml"><dependencyManagement> <b class="conum">(1)</b>
|
|
<dependencies>
|
|
<dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-dependencies</artifactId>
|
|
<version>Brixton.RELEASE</version>
|
|
<type>pom</type>
|
|
<scope>import</scope>
|
|
</dependency>
|
|
</dependencies>
|
|
</dependencyManagement>
|
|
|
|
<dependency> <b class="conum">(2)</b>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-sleuth-zipkin-stream</artifactId>
|
|
</dependency>
|
|
<dependency> <b class="conum">(3)</b>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-starter-sleuth</artifactId>
|
|
</dependency>
|
|
<!-- EXAMPLE FOR RABBIT BINDING -->
|
|
<dependency> <b class="conum">(4)</b>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-stream-binder-rabbit</artifactId>
|
|
</dependency></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="colist arabic">
|
|
<ol>
|
|
<li>
|
|
<p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p>
|
|
</li>
|
|
<li>
|
|
<p>Add the dependency to <code>spring-cloud-sleuth-zipkin-stream</code></p>
|
|
</li>
|
|
<li>
|
|
<p>Add the dependency to <code>spring-cloud-starter-sleuth</code> - that way all dependant dependencies will be downloaded</p>
|
|
</li>
|
|
<li>
|
|
<p>Add a binder (e.g. Rabbit binder) to tell Spring Cloud Stream what it should bind to</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div class="listingblock secondary">
|
|
<div class="title">Gradle</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-groovy" data-lang="groovy">dependencyManagement { <b class="conum">(1)</b>
|
|
imports {
|
|
mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
|
|
}
|
|
}
|
|
|
|
dependencies {
|
|
compile "org.springframework.cloud:spring-cloud-sleuth-zipkin-stream" <b class="conum">(2)</b>
|
|
compile "org.springframework.cloud:spring-cloud-starter-sleuth" <b class="conum">(3)</b>
|
|
// Example for Rabbit binding
|
|
compile "org.springframework.cloud:spring-cloud-stream-binder-rabbit" <b class="conum">(4)</b>
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="colist arabic">
|
|
<ol>
|
|
<li>
|
|
<p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p>
|
|
</li>
|
|
<li>
|
|
<p>Add the dependency to <code>spring-cloud-sleuth-zipkin-stream</code></p>
|
|
</li>
|
|
<li>
|
|
<p>Add the dependency to <code>spring-cloud-starter-sleuth</code> - that way all dependant dependencies will be downloaded</p>
|
|
</li>
|
|
<li>
|
|
<p>Add a binder (e.g. Rabbit binder) to tell Spring Cloud Stream what it should bind to</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>and then just annotate your main class with <code>@EnableZipkinStreamServer</code> annotation:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java"></code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_features_2">Features</h2>
|
|
<div class="sectionbody">
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>Adds trace and span ids to the Slf4J MDC, so you can extract all the logs from a given trace or span in a log aggregator. Example logs:</p>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>2016-02-02 15:30:57.902 INFO [bar,6bfd228dc00d216b,6bfd228dc00d216b,false] 23030 --- [nio-8081-exec-3] ...
|
|
2016-02-02 15:30:58.372 ERROR [bar,6bfd228dc00d216b,6bfd228dc00d216b,false] 23030 --- [nio-8081-exec-3] ...
|
|
2016-02-02 15:31:01.936 INFO [bar,46ab0d418373cbc9,46ab0d418373cbc9,false] 23030 --- [nio-8081-exec-4] ...</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>notice the <code>[appname,traceId,spanId,exportable]</code> entries from the MDC:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><strong>spanId</strong> - the id of a specific operation that took place</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>appname</strong> - the name of the application that logged the span</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>traceId</strong> - the id of the latency graph that contains the span</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>exportable</strong> - whether the log should be exported to Zipkin or not. When would you like the span not to be
|
|
exportable? In the case in which you want to wrap some operation in a Span and have it written to the logs
|
|
only.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>Provides an abstraction over common distributed tracing data models: traces, spans (forming a DAG), annotations,
|
|
key-value annotations. Loosely based on HTrace, but Zipkin (Dapper) compatible.</p>
|
|
</li>
|
|
<li>
|
|
<p>Sleuth records timing information to aid in latency analysis. Using sleuth, you can pinpoint causes of
|
|
latency in your applications. Sleuth is written to not log too much, and to not cause your production application to crash.</p>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>propagates structural data about your call-graph in-band, and the rest out-of-band.</p>
|
|
</li>
|
|
<li>
|
|
<p>includes opinionated instrumentation of layers such as HTTP</p>
|
|
</li>
|
|
<li>
|
|
<p>includes sampling policy to manage volume</p>
|
|
</li>
|
|
<li>
|
|
<p>can report to a Zipkin system for query and visualization</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>Instruments common ingress and egress points from Spring applications (servlet filter, async endpoints,
|
|
rest template, scheduled actions, message channels, zuul filters, feign client).</p>
|
|
</li>
|
|
<li>
|
|
<p>Sleuth includes default logic to join a trace across http or messaging boundaries. For example, http propagation
|
|
works via Zipkin-compatible request headers. This propagation logic is defined and customized via
|
|
<code>SpanInjector</code> and <code>SpanExtractor</code> implementations.</p>
|
|
</li>
|
|
<li>
|
|
<p>Provides simple metrics of accepted / dropped spans.</p>
|
|
</li>
|
|
<li>
|
|
<p>If <code>spring-cloud-sleuth-zipkin</code> then the app will generate and collect Zipkin-compatible traces.
|
|
By default it sends them via HTTP to a Zipkin server on localhost (port 9411).
|
|
Configure the location of the service using <code>spring.zipkin.baseUrl</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>If <code>spring-cloud-sleuth-stream</code> then the app will generate and collect traces via <a href="https://github.com/spring-cloud/spring-cloud-stream">Spring Cloud Stream</a>.
|
|
Your app automatically becomes a producer of tracer messages that are sent over your broker of choice
|
|
(e.g. RabbitMQ, Apache Kafka, Redis).</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="admonitionblock important">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Important</div>
|
|
</td>
|
|
<td class="content">
|
|
If using Zipkin or Stream, configure the percentage of spans exported using <code>spring.sleuth.sampler.percentage</code>
|
|
(default 0.1, i.e. 10%). <strong>Otherwise you might think that Sleuth is not working cause it’s omitting some spans.</strong>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
the SLF4J MDC is always set and logback users will immediately see the trace and span ids in logs per the example
|
|
above. Other logging systems have to configure their own formatter to get the same result. The default is
|
|
<code>logging.pattern.level</code> set to <code>%clr(%5p) %clr([${spring.application.name:},%X{X-B3-TraceId:-},%X{X-B3-SpanId:-},%X{X-Span-Export:-}]){yellow}</code>
|
|
(this is a Spring Boot feature for logback users).
|
|
<strong>This means that if you’re not using SLF4J this pattern WILL NOT be automatically applied</strong>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_sampling">Sampling</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>In distributed tracing the data volumes can be very high so sampling
|
|
can be important (you usually don’t need to export all spans to get a
|
|
good picture of what is happening). Spring Cloud Sleuth has a
|
|
<code>Sampler</code> strategy that you can implement to take control of the
|
|
sampling algorithm. Samplers do not stop span (correlation) ids from
|
|
being generated, but they do prevent the tags and events being
|
|
attached and exported. By default you get a strategy that continues to
|
|
trace if a span is already active, but new ones are always marked as
|
|
non-exportable. If all your apps run with this sampler you will see
|
|
traces in logs, but not in any remote store. For testing the default
|
|
is often enough, and it probably is all you need if you are only using
|
|
the logs (e.g. with an ELK aggregator). If you are exporting span data
|
|
to Zipkin or Spring Cloud Stream, there is also an <code>AlwaysSampler</code>
|
|
that exports everything and a <code>PercentageBasedSampler</code> that samples a
|
|
fixed fraction of spans.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
the <code>PercentageBasedSampler</code> is the default if you are using
|
|
<code>spring-cloud-sleuth-zipkin</code> or <code>spring-cloud-sleuth-stream</code>. You can
|
|
configure the exports using <code>spring.sleuth.sampler.percentage</code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>A sampler can be installed just by creating a bean definition, e.g:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Bean
|
|
public Sampler defaultSampler() {
|
|
return new AlwaysSampler();
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_instrumentation">Instrumentation</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Sleuth instruments all your Spring application
|
|
automatically, so you shouldn’t have to do anything to activate
|
|
it. The instrumentation is added using a variety of technologies
|
|
according to the stack that is available, e.g. for a servlet web
|
|
application we use a <code>Filter</code>, and for Spring Integration we use
|
|
<code>ChannelInterceptors</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can customize the keys used in span tags. To limit the volume of
|
|
span data, by default an HTTP request will be tagged only with a
|
|
handful of metadata like the status code, host and URL. You can add
|
|
request headers by configuring <code>spring.sleuth.keys.http.headers</code> (a
|
|
list of header names).</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
Remember that tags are only collected and exported if there is a
|
|
<code>Sampler</code> that allows it (by default there is not, so there is no
|
|
danger of accidentally collecting too much data without configuring
|
|
something).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
Currently the instrumentation in Spring Cloud Sleuth is eager - it means that
|
|
we’re actively trying to pass the tracing context between threads. Also timing events
|
|
are captured even when sleuth isn’t exporting data to a tracing system.
|
|
This approach may change in the future towards being lazy on this matter.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_span_lifecycle">Span lifecycle</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>You can do the following operations on the Span by means of <strong>Tracer</strong> interface:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><a href="#creating-and-closing-spans">start</a> - when you start a span its name is assigned and start timestamp is recorded.</p>
|
|
</li>
|
|
<li>
|
|
<p><a href="#creating-and-closing-spans">close</a> - the span gets finished (the end time of the span is recorded) and if
|
|
the span is <strong>exportable</strong> then it will be eligible for collection to Zipkin.
|
|
The span is also removed from the current thread.</p>
|
|
</li>
|
|
<li>
|
|
<p><a href="#continuing-spans">continue</a> - a new instance of span will be created whereas it will be a copy of the
|
|
one that it continues.</p>
|
|
</li>
|
|
<li>
|
|
<p><a href="#continuing-spans">detach</a> - the span doesn’t get stopped or closed. It only gets removed from the current thread.</p>
|
|
</li>
|
|
<li>
|
|
<p><a href="#creating-spans-with-explicit-parent">create with explicit parent</a> - you can create a new span and set an explicit parent to it</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="creating-and-closing-spans">Creating and closing spans</h3>
|
|
<div class="paragraph">
|
|
<p>You can manually create spans by using the <strong>Tracer</strong> interface.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">// Start a span. If there was a span present in this thread it will become
|
|
// the `newSpan`'s parent.
|
|
Span newSpan = this.tracer.createSpan("calculateTax");
|
|
try {
|
|
// ...
|
|
// You can tag a span
|
|
this.tracer.addTag("taxValue", taxValue);
|
|
// ...
|
|
// You can log an event on a span
|
|
newSpan.logEvent("taxCalculated");
|
|
} finally {
|
|
// Once done remember to close the span. This will allow collecting
|
|
// the span to send it to Zipkin
|
|
this.tracer.close(newSpan);
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In this example we could see how to create a new instance of span. Assuming that there already
|
|
was a span present in this thread then it would become the parent of that span.</p>
|
|
</div>
|
|
<div class="admonitionblock important">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Important</div>
|
|
</td>
|
|
<td class="content">
|
|
Always clean after you create a span! Don’t forget to close a span if you want to send it to Zipkin.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="continuing-spans">Continuing spans</h3>
|
|
<div class="paragraph">
|
|
<p>Sometimes you don’t want to create a new span but you want to continue one. Example of such a
|
|
situation might be (of course it all depends on the use-case):</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><strong>AOP</strong> - If there was already a span created before an aspect was reached then you might not want to create a new span.</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>Hystrix</strong> - executing a Hystrix command is most likely a logical part of the current processing. It’s in fact
|
|
only a technical implementation detail that you wouldn’t necessarily want to reflect in tracing as a separate being.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The continued instance of span is equal to the one that it continues:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">Span continuedSpan = this.tracer.continueSpan(spanToContinue);
|
|
assertThat(continuedSpan).isEqualTo(spanToContinue);</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To continue a span you can use the <strong>Tracer</strong> interface.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">// let's assume that we're in a thread Y and we've received
|
|
// the `initialSpan` from thread X
|
|
Span continuedSpan = this.tracer.continueSpan(initialSpan);
|
|
try {
|
|
// ...
|
|
// You can tag a span
|
|
this.tracer.addTag("taxValue", taxValue);
|
|
// ...
|
|
// You can log an event on a span
|
|
continuedSpan.logEvent("taxCalculated");
|
|
} finally {
|
|
// Once done remember to detach the span. That way you'll
|
|
// safely remove it from the current thread without closing it
|
|
this.tracer.detach(continuedSpan);
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock important">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Important</div>
|
|
</td>
|
|
<td class="content">
|
|
Always clean after you create a span! Don’t forget to detach a span if some work was done started in one
|
|
thread (e.g. thread X) and it’s waiting for other threads (e.g. Y, Z) to finish.
|
|
Then the spans in the threads Y, Z should be detached at the end of their work. When the results are collected
|
|
the span in thread X should be closed.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="creating-spans-with-explicit-parent">Creating spans with an explicit parent</h3>
|
|
<div class="paragraph">
|
|
<p>There is a possibility that you want to start a new span and provide an explicit parent of that span.
|
|
Let’s assume that the parent of a span is in one thread and you want to start a new span in another thread. The
|
|
<code>startSpan</code> method of the <code>Tracer</code> interface is the method you are looking for.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">// let's assume that we're in a thread Y and we've received
|
|
// the `initialSpan` from thread X. `initialSpan` will be the parent
|
|
// of the `newSpan`
|
|
Span newSpan = this.tracer.createSpan("calculateCommission", initialSpan);
|
|
try {
|
|
// ...
|
|
// You can tag a span
|
|
this.tracer.addTag("commissionValue", commissionValue);
|
|
// ...
|
|
// You can log an event on a span
|
|
newSpan.logEvent("commissionCalculated");
|
|
} finally {
|
|
// Once done remember to close the span. This will allow collecting
|
|
// the span to send it to Zipkin. The tags and events set on the
|
|
// newSpan will not be present on the parent
|
|
this.tracer.close(newSpan);
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock important">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Important</div>
|
|
</td>
|
|
<td class="content">
|
|
After having created such a span remember to close it. Otherwise you will see a lot of warnings in your logs
|
|
related to the fact that you have a span present in the current thread other than the one you’re trying to close.
|
|
What’s worse your spans won’t get closed properly thus will not get collected to Zipkin.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_naming_spans">Naming spans</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Picking a span name is not a trivial task. Span name should depict an operation name. The name should
|
|
be low cardinality (e.g. not include identifiers).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Since there is a lot of instrumentation going on some of the span names will be
|
|
artificial like:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><code>http:path</code> when received an http request on a given path</p>
|
|
</li>
|
|
<li>
|
|
<p><code>async</code> for asynchronous operations done via wrapped <code>Callable</code> and <code>Runnable</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>@Scheduled</code> annotated methods will return the simple name of the class.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Fortunately, for the asynchronous processing you can provide explicit naming.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="__spanname_annotation">@SpanName annotation</h3>
|
|
<div class="paragraph">
|
|
<p>You can do name the span explicitly via the <code>@SpanName</code> annotation.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@SpanName("calculateTax")
|
|
class TaxCountingRunnable implements Runnable {
|
|
|
|
@Override public void run() {
|
|
// perform logic
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In this case, when processed in the following manner:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">Runnable runnable = new TraceRunnable(tracer, spanNamer, new TaxCountingRunnable());
|
|
Future<?> future = executorService.submit(runnable);
|
|
// ... some additional logic ...
|
|
future.get();</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The span will be named <code>calculateTax</code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_tostring_method">toString() method</h3>
|
|
<div class="paragraph">
|
|
<p>It’s pretty rare to create separate classes for <code>Runnable</code> or <code>Callable</code>. Typically one creates an anonymous
|
|
instance of those classes. You can’t annotate such classes thus to override that, if there is no <code>@SpanName</code> annotation present,
|
|
we’re checking if the class has a custom implementation of the <code>toString()</code> method.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>So executing such code:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">Runnable runnable = new TraceRunnable(tracer, spanNamer, new Runnable() {
|
|
@Override public void run() {
|
|
// perform logic
|
|
}
|
|
|
|
@Override public String toString() {
|
|
return "calculateTax";
|
|
}
|
|
});
|
|
Future<?> future = executorService.submit(runnable);
|
|
// ... some additional logic ...
|
|
future.get();</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>will lead in creating a span named <code>calculateTax</code>.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_customizations">Customizations</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Thanks to the <code>SpanInjector</code> and <code>SpanExtractor</code> you can customize the way spans
|
|
are created and propagated.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>There are currently two built-in ways to pass tracing information between processes:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>via Spring Integration</p>
|
|
</li>
|
|
<li>
|
|
<p>via HTTP</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Span ids are extracted from Zipkin-compatible (B3) headers (either <code>Message</code>
|
|
or HTTP headers), to start or join an existing trace. Trace information is
|
|
injected into any outbound requests so the next hop can extract them.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_spring_integration">Spring Integration</h3>
|
|
<div class="paragraph">
|
|
<p>For Spring Integration these are the beans responsible for creation of a Span from a <code>Message</code>
|
|
and filling in the <code>MessageBuilder</code> with tracing information.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Bean
|
|
public SpanExtractor<Message> messagingSpanExtractor() {
|
|
...
|
|
}
|
|
|
|
@Bean
|
|
public SpanInjector<MessageBuilder> messagingSpanInjector() {
|
|
...
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can override them by providing your own implementation and by adding a <code>@Primary</code> annotation
|
|
to your bean definition.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_http">HTTP</h3>
|
|
<div class="paragraph">
|
|
<p>For HTTP these are the beans responsible for creation of a Span from a <code>HttpServletRequest</code>
|
|
and filling in the <code>HttpServletResponse</code> with tracing information.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Bean
|
|
public SpanExtractor<HttpServletRequest> httpServletRequestSpanExtractor() {
|
|
...
|
|
}
|
|
|
|
@Bean
|
|
public SpanInjector<HttpServletResponse> httpServletResponseSpanInjector() {
|
|
...
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can override them by providing your own implementation and by adding a <code>@Primary</code> annotation
|
|
to your bean definition.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_example">Example</h3>
|
|
<div class="paragraph">
|
|
<p>Let’s assume that instead of the standard Zipkin compatible tracing HTTP header names
|
|
you have</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>for trace id - <code>correlationId</code></p>
|
|
</li>
|
|
<li>
|
|
<p>for span id - <code>mySpanId</code></p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This is a an example of a <code>SpanExtractor</code></p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">static class CustomHttpServletRequestSpanExtractor
|
|
implements SpanExtractor<HttpServletRequest> {
|
|
|
|
@Override
|
|
public Span joinTrace(HttpServletRequest carrier) {
|
|
long traceId = Span.hexToId(carrier.getHeader("correlationId"));
|
|
long spanId = Span.hexToId(carrier.getHeader("mySpanId"));
|
|
// extract all necessary headers
|
|
Span.SpanBuilder builder = Span.builder().traceId(traceId).spanId(spanId);
|
|
// build rest of the Span
|
|
return builder.build();
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The following <code>SpanInjector</code> could be created</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">static class CustomHttpServletResponseSpanInjector
|
|
implements SpanInjector<HttpServletResponse> {
|
|
|
|
@Override
|
|
public void inject(Span span, HttpServletResponse carrier) {
|
|
carrier.addHeader("correlationId", Span.idToHex(span.getTraceId()));
|
|
carrier.addHeader("mySpanId", Span.idToHex(span.getSpanId()));
|
|
// inject the rest of Span values to the header
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>And you could register them like this:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Bean
|
|
@Primary
|
|
SpanExtractor<HttpServletRequest> customHttpServletRequestSpanExtractor() {
|
|
return new CustomHttpServletRequestSpanExtractor();
|
|
}
|
|
|
|
@Bean
|
|
@Primary
|
|
SpanInjector<HttpServletResponse> customHttpServletResponseSpanInjector() {
|
|
return new CustomHttpServletResponseSpanInjector();
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_span_data_as_messages">Span Data as Messages</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>You can accumulate and send span data over
|
|
<a href="http://cloud.spring.io/spring-cloud-stream">Spring Cloud Stream</a> by
|
|
including the <code>spring-cloud-sleuth-stream</code> jar as a dependency, and
|
|
adding a Channel Binder implementation
|
|
(e.g. <code>spring-cloud-starter-stream-rabbit</code> for RabbitMQ or
|
|
<code>spring-cloud-starter-stream-kafka</code> for Kafka). This will
|
|
automatically turn your app into a producer of messages with payload
|
|
type <code>Spans</code>.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_zipkin_consumer">Zipkin Consumer</h3>
|
|
<div class="paragraph">
|
|
<p>There is a special convenience annotation for setting up a message consumer
|
|
for the Span data and pushing it into a Zipkin <code>SpanStore</code>. This application</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@SpringBootApplication
|
|
@EnableZipkinStreamServer
|
|
public class Consumer {
|
|
public static void main(String[] args) {
|
|
SpringApplication.run(Consumer.class, args);
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>will listen for the Span data on whatever transport you provide via a
|
|
Spring Cloud Stream <code>Binder</code> (e.g. include
|
|
<code>spring-cloud-starter-stream-rabbit</code> for RabbitMQ, and similar
|
|
starters exist for Redis and Kafka). The app will also be a
|
|
<a href="https://github.com/openzipkin/zipkin-java">Zipkin server</a>, which hosts
|
|
the UI and api on port 9411.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The default <code>SpanStore</code> is in-memory (good for demos and getting
|
|
started quickly). For a more robust solution you can add MySQL and
|
|
<code>spring-boot-starter-jdbc</code> to your classpath and enable the JDBC
|
|
<code>SpanStore</code> via configuration, e.g.:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
rabbitmq:
|
|
host: ${RABBIT_HOST:localhost}
|
|
datasource:
|
|
schema: classpath:/mysql.sql
|
|
url: jdbc:mysql://${MYSQL_HOST:localhost}/test
|
|
username: root
|
|
password: root
|
|
# Switch this on to create the schema on startup:
|
|
initialize: true
|
|
continueOnError: true
|
|
sleuth:
|
|
enabled: false
|
|
zipkin:
|
|
storage:
|
|
type: mysql</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
The <code>@EnableZipkinStreamServer</code> is also annotated with
|
|
<code>@EnableZipkinServer</code> so the process will also expose the standard
|
|
Zipkin server endpoints for collecting spans over HTTP, and for
|
|
querying in the Zipkin Web UI.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_custom_consumer">Custom Consumer</h3>
|
|
<div class="paragraph">
|
|
<p>A custom consumer can also easily be implemented using
|
|
<code>spring-cloud-sleuth-stream</code> and binding to the <code>SleuthSink</code>. Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@EnableBinding(SleuthSink.class)
|
|
@SpringBootApplication(exclude = SleuthStreamAutoConfiguration.class)
|
|
@MessageEndpoint
|
|
public class Consumer {
|
|
|
|
@ServiceActivator(inputChannel = SleuthSink.INPUT)
|
|
public void sink(Spans input) throws Exception {
|
|
// ... process spans
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
the sample consumer application above explicitly excludes
|
|
<code>SleuthStreamAutoConfiguration</code> so it doesn’t send messages to itself,
|
|
but this is optional (you might actually want to trace requests into
|
|
the consumer app).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_metrics">Metrics</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Currently Spring Cloud Sleuth registers very simple metrics related to spans.
|
|
It’s using the <a href="http://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-metrics.html#production-ready-recording-metrics">Spring Boot’s metrics support</a>
|
|
to calculate the number of accepted and dropped spans. Each time a span gets
|
|
sent to Zipkin the number of accepted spans will increase. If there’s an error then
|
|
the number of dropped spans will get increased.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_integrations">Integrations</h2>
|
|
<div class="sectionbody">
|
|
<div class="sect2">
|
|
<h3 id="_runnable_and_callable">Runnable and Callable</h3>
|
|
<div class="paragraph">
|
|
<p>If you’re wrapping your logic in <code>Runnable</code> or <code>Callable</code> it’s enough to wrap those classes in their Sleuth representative.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Example for <code>Runnable</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">Runnable runnable = new Runnable() {
|
|
@Override
|
|
public void run() {
|
|
// do some work
|
|
}
|
|
|
|
@Override
|
|
public String toString() {
|
|
return "spanNameFromToStringMethod";
|
|
}
|
|
};
|
|
// Manual `TraceRunnable` creation with explicit "calculateTax" Span name
|
|
Runnable traceRunnable = new TraceRunnable(tracer, spanNamer, runnable, "calculateTax");
|
|
// Wrapping `Runnable` with `Tracer`. The Span name will be taken either from the
|
|
// `@SpanName` annotation or from `toString` method
|
|
Runnable traceRunnableFromTracer = tracer.wrap(runnable);</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Example for <code>Callable</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">Callable<String> callable = new Callable<String>() {
|
|
@Override
|
|
public String call() throws Exception {
|
|
return someLogic();
|
|
}
|
|
|
|
@Override
|
|
public String toString() {
|
|
return "spanNameFromToStringMethod";
|
|
}
|
|
};
|
|
// Manual `TraceCallable` creation with explicit "calculateTax" Span name
|
|
Callable<String> traceCallable = new TraceCallable<>(tracer, spanNamer, callable, "calculateTax");
|
|
// Wrapping `Callable` with `Tracer`. The Span name will be taken either from the
|
|
// `@SpanName` annotation or from `toString` method
|
|
Callable<String> traceCallableFromTracer = tracer.wrap(callable);</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>That way you will ensure that a new Span is created and closed for each execution.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_hystrix">Hystrix</h3>
|
|
<div class="sect3">
|
|
<h4 id="_custom_concurrency_strategy">Custom Concurrency Strategy</h4>
|
|
<div class="paragraph">
|
|
<p>We’re registering a custom <a href="https://github.com/Netflix/Hystrix/wiki/Plugins#concurrencystrategy"><code>HystrixConcurrencyStrategy</code></a>
|
|
that wraps all <code>Callable</code> instances into their Sleuth representative -
|
|
the <code>TraceCallable</code>. The strategy either starts or continues a span depending on the fact whether tracing was already going
|
|
on before the Hystrix command was called. To disable the custom Hystrix Concurrency Strategy set the <code>spring.sleuth.hystrix.strategy.enabled</code> to <code>false</code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_manual_command_setting">Manual Command setting</h4>
|
|
<div class="paragraph">
|
|
<p>Assuming that you have the following <code>HystrixCommand</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">HystrixCommand<String> hystrixCommand = new HystrixCommand<String>(setter) {
|
|
@Override
|
|
protected String run() throws Exception {
|
|
return someLogic();
|
|
}
|
|
};</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In order to pass the tracing information you have to wrap the same logic in the Sleuth version of the <code>HystrixCommand</code> which is the
|
|
<code>TraceCommand</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">TraceCommand<String> traceCommand = new TraceCommand<String>(tracer, traceKeys, setter) {
|
|
@Override
|
|
public String doRun() throws Exception {
|
|
return someLogic();
|
|
}
|
|
};</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_rxjava">RxJava</h3>
|
|
<div class="paragraph">
|
|
<p>We’re registering a custom <a href="https://github.com/ReactiveX/RxJava/wiki/Plugins#rxjavaschedulershook"><code>RxJavaSchedulersHook</code></a>
|
|
that wraps all <code>Action0</code> instances into their Sleuth representative -
|
|
the <code>TraceAction</code>. The hook either starts or continues a span depending on the fact whether tracing was already going
|
|
on before the Action was scheduled. To disable the custom RxJavaSchedulersHook set the <code>spring.sleuth.rxjava.schedulers.hook.enabled</code> to <code>false</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can define a list of regular expressions for thread names, for which you don’t want a Span to be created. Just provide a comma separated list
|
|
of regular expressions in the <code>spring.sleuth.rxjava.schedulers.ignoredthreads</code> property.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_http_integration">HTTP integration</h3>
|
|
<div class="paragraph">
|
|
<p>Features from this section can be disabled by providing the <code>spring.sleuth.web.enabled</code> property with value equal to <code>false</code>.</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_http_filter">HTTP Filter</h4>
|
|
<div class="paragraph">
|
|
<p>Via the <code>TraceFilter</code> all sampled incoming requests result in creation of a Span. That Span’s name is <code>http:</code> + the path to which
|
|
the request was sent. E.g. if the request was sent to <code>/foo/bar</code> then the name will be <code>http:/foo/bar</code>. You can configure which URIs you would
|
|
like to skip via the <code>spring.sleuth.web.skipPattern</code> property. If you have <code>ManagementServerProperties</code> on classpath then
|
|
its value of <code>contextPath</code> gets appended to the provided skip pattern.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_async_servlet_support">Async Servlet support</h4>
|
|
<div class="paragraph">
|
|
<p>If your controller returns a <code>Callable</code> or a <code>WebAsyncTask</code> Spring Cloud Sleuth will continue the existing span instead of creating a new one.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_http_client_integration">HTTP client integration</h3>
|
|
<div class="sect3">
|
|
<h4 id="_synchronous_rest_template">Synchronous Rest Template</h4>
|
|
<div class="paragraph">
|
|
<p>We’re injecting a <code>RestTemplate</code> interceptor that ensures that all the tracing information is passed to the requests. Each time a
|
|
call is made a new Span is created. It gets closed upon receiving the response. In order to block the synchronous <code>RestTemplate</code> features
|
|
just set <code>spring.sleuth.web.client.enabled</code> to <code>false</code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_asynchronous_rest_template">Asynchronous Rest Template</h4>
|
|
<div class="paragraph">
|
|
<p>Custom instrumentation is set to create and close Spans upon sending and receiving requests. You can customize the <code>ClientHttpRequestFactory</code>
|
|
and the <code>AsyncClientHttpRequestFactory</code> by registering your beans. Remember to use tracing compatible implementations (e.g. don’t forget to
|
|
wrap <code>ThreadPoolTaskScheduler</code> in a <code>TraceAsyncListenableTaskExecutor</code>).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To block the <code>AsyncRestTemplate</code> features set <code>spring.sleuth.web.async.client.enabled</code> to <code>false</code>.
|
|
To disable creation of the default <code>TraceAsyncClientHttpRequestFactoryWrapper</code> set <code>spring.sleuth.web.async.client.factory.enabled</code>
|
|
to <code>false</code>. If you don’t want to create <code>AsyncRestClient</code> at all set <code>spring.sleuth.web.async.client.template.enabled</code> to <code>false</code>.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_feign">Feign</h3>
|
|
<div class="paragraph">
|
|
<p>By default Spring Cloud Sleuth provides integration with feign via the <code>TraceFeignClientAutoConfiguration</code>. You can disable it entirely
|
|
by setting <code>spring.sleuth.feign.enabled</code> to false. If you do so then no Feign related instrumentation will take place.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Part of Feign instrumentation is done via a <code>FeignBeanPostProcessor</code>. You can disable it by providing the <code>spring.sleuth.feign.processor.enabled</code> equal to <code>false</code>.
|
|
If you set it like this then Spring Cloud Sleuth will not instrument any of your custom Feign components. All the default instrumentation
|
|
however will be still there.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_asynchronous_communication">Asynchronous communication</h3>
|
|
<div class="sect3">
|
|
<h4 id="__async_annotated_methods">@Async annotated methods</h4>
|
|
<div class="paragraph">
|
|
<p>In Spring Cloud Sleuth we’re instrumenting async related components so that the tracing information is passed between threads.
|
|
You can disable this behaviour by setting the value of <code>spring.sleuth.async.enabled</code> to <code>false</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you annotate your method with <code>@Async</code> then we’ll automatically create a new Span with the following characteristics:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>the Span name will be the annotated method name</p>
|
|
</li>
|
|
<li>
|
|
<p>the Span will be tagged with that method’s class name and the method name too</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="__scheduled_annotated_methods">@Scheduled annotated methods</h4>
|
|
<div class="paragraph">
|
|
<p>In Spring Cloud Sleuth we’re instrumenting scheduled method execution so that the tracing information is passed between threads. You can disable this behaviour
|
|
by setting the value of <code>spring.sleuth.scheduled.enabled</code> to <code>false</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you annotate your method with <code>@Scheduled</code> then we’ll automatically create a new Span with the following characteristics:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>the Span name will be the annotated method name</p>
|
|
</li>
|
|
<li>
|
|
<p>the Span will be tagged with that method’s class name and the method name too</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you want to skip Span creation for some <code>@Scheduled</code> annotated classes you can set the
|
|
<code>spring.sleuth.scheduled.skipPattern</code> with a regular expression that will match the fully qualified name of the
|
|
<code>@Scheduled</code> annotated class.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_executor_executorservice_and_scheduledexecutorservice">Executor, ExecutorService and ScheduledExecutorService</h4>
|
|
<div class="paragraph">
|
|
<p>We’re providing <code>LazyTraceExecutor</code>, <code>TraceableExecutorService</code> and <code>TraceableScheduledExecutorService</code>. Those implementations
|
|
are creating Spans each time a new task is submitted, invoked or scheduled.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Here you can see an example of how to pass tracing information with <code>TraceableExecutorService</code> when working with <code>CompletableFuture</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">CompletableFuture<Long> completableFuture = CompletableFuture.supplyAsync(() -> {
|
|
// perform some logic
|
|
return 1_000_000L;
|
|
}, new TraceableExecutorService(executorService,
|
|
// 'calculateTax' explicitly names the span - this param is optional
|
|
tracer, traceKeys, spanNamer, "calculateTax"));</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_messaging">Messaging</h3>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Sleuth integrates with <a href="http://projects.spring.io/spring-integration/">Spring Integration</a>. It creates spans for publish and
|
|
subscribe events. To disable Spring Integration instrumentation, set <code>spring.sleuth.integration.enabled</code> to false.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_zuul">Zuul</h3>
|
|
<div class="paragraph">
|
|
<p>We’re registering Zuul filters to propagate the tracing information (the request header is enriched with tracing data).
|
|
To disable Zuul support set the <code>spring.sleuth.zuul.enabled</code> property to <code>false</code>.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_running_examples">Running examples</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>You can find the running examples deployed in the <a href="https://run.pivotal.io/">Pivotal Web Services</a>. Check them out in the following links:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><a href="http://docssleuth-zipkin-server.cfapps.io/">Zipkin for apps presented in the samples to the top</a>, its <a href="https://github.com/spring-cloud-samples/sleuth-documentation-apps">Github Code</a> and its build status <span class="image"><a class="image" href="https://build.spring.io/browse/SCE2E-SCSDAOCF"><img src="https://build.spring.io/plugins/servlet/buildStatusImage/SCE2E-SCSDAOCF" alt="Build Status"></a></span></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="http://docsbrewing-zipkin-web.cfapps.io/">Zipkin for Brewery on PWS</a>, its <a href="https://github.com/spring-cloud-samples/brewery">Github Code</a> and its build status <span class="image"><a class="image" href="https://build.spring.io/browse/SCE2E-SCSBFDOCF"><img src="https://build.spring.io/plugins/servlet/buildStatusImage/SCE2E-SCSSE2ECFT" alt="Build Status"></a></span></p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<h1 id="_spring_cloud_consul" class="sect0">Spring Cloud Consul</h1>
|
|
<div class="openblock partintro">
|
|
<div class="content">
|
|
This project provides Consul integrations for Spring Boot apps through autoconfiguration
|
|
and binding to the Spring Environment and other Spring programming model idioms. With a few
|
|
simple annotations you can quickly enable and configure the common patterns inside your
|
|
application and build large distributed systems with Consul based components. The
|
|
patterns provided include Service Discovery, Control Bus and Configuration.
|
|
Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon), Circuit Breaker
|
|
(Hystrix) are provided by integration with Spring Cloud Netflix.
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-consul-install">Install Consul</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Please see the <a href="https://www.consul.io/intro/getting-started/install.html">installation documentation</a> for instructions on how to install Consul.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-consul-agent">Consul Agent</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>A Consul Agent client must be available to all Spring Cloud Consul applications. By default, the Agent client is expected to be at <code>localhost:8500</code>. See the <a href="https://consul.io/docs/agent/basics.html">Agent documentation</a> for specifics on how to start an Agent client and how to connect to a cluster of Consul Agent Servers. For development, after you have installed consul, you may start a Consul Agent using the following command:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>./src/main/bash/local_run_consul.sh</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This will start an agent in server mode on port 8500, with the ui available at <a href="http://localhost:8500" class="bare">http://localhost:8500</a></p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-consul-discovery">Service Discovery with Consul</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Service Discovery is one of the key tenets of a microservice based architecture. Trying to hand configure each client or some form of convention can be very difficult to do and can be very brittle. Consul provides Service Discovery services via an <a href="https://www.consul.io/docs/agent/http.html">HTTP API</a> and <a href="https://www.consul.io/docs/agent/dns.html">DNS</a>. Spring Cloud Consul leverages the HTTP API for service registration and discovery. This does not prevent non-Spring Cloud applications from leveraging the DNS interface. Consul Agents servers are run in a <a href="https://www.consul.io/docs/internals/architecture.html">cluster</a> that communicates via a <a href="https://www.consul.io/docs/internals/gossip.html">gossip protocol</a> and uses the <a href="https://www.consul.io/docs/internals/consensus.html">Raft consensus protocol</a>.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_registering_with_consul">Registering with Consul</h3>
|
|
<div class="paragraph">
|
|
<p>When a client registers with Consul, it provides meta-data about itself such as host and port, id, name and tags. An HTTP <a href="https://www.consul.io/docs/agent/checks.html">Check</a> is created by default that Consul hits the <code>/health</code> endpoint every 10 seconds. If the health check fails, the service instance is marked as critical.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Example Consul client:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@SpringBootApplication
|
|
@EnableDiscoveryClient
|
|
@RestController
|
|
public class Application {
|
|
|
|
@RequestMapping("/")
|
|
public String home() {
|
|
return "Hello world";
|
|
}
|
|
|
|
public static void main(String[] args) {
|
|
new SpringApplicationBuilder(Application.class).web(true).run(args);
|
|
}
|
|
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>(i.e. utterly normal Spring Boot app). If the Consul client is located somewhere other than <code>localhost:8500</code>, the configuration is required to locate the client. Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>spring:
|
|
cloud:
|
|
consul:
|
|
host: localhost
|
|
port: 8500</pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock caution">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Caution</div>
|
|
</td>
|
|
<td class="content">
|
|
If you use <a href="#spring-cloud-consul-config">Spring Cloud Consul Config</a>, the above values will need to be placed in <code>bootstrap.yml</code> instead of <code>application.yml</code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The default service name, instance id and port, taken from the <code>Environment</code>, are <code>${spring.application.name}</code>, the Spring Context ID and <code>${server.port}</code> respectively.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><code>@EnableDiscoveryClient</code> make the app into both a Consul "service" (i.e. it registers itself) and a "client" (i.e. it can query Consul to locate other services).</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_http_health_check">HTTP Health Check</h3>
|
|
<div class="paragraph">
|
|
<p>The health check for a Consul instance defaults to "/health", which is the default locations of a useful endpoint in a Spring Boot Actuator application. You need to change these, even for an Actuator application if you use a non-default context path or servlet path (e.g. <code>server.servletPath=/foo</code>) or management endpoint path (e.g. <code>management.contextPath=/admin</code>). The interval that Consul uses to check the health endpoint may also be configured. "10s" and "1m" represent 10 seconds and 1 minute respectively. Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>spring:
|
|
cloud:
|
|
consul:
|
|
discovery:
|
|
healthCheckPath: ${management.contextPath}/health
|
|
healthCheckInterval: 15s</pre>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_metadata_and_consul_tags">Metadata and Consul tags</h4>
|
|
<div class="paragraph">
|
|
<p>Consul does not yet support metadata on services. Spring Cloud’s <code>ServiceInstance</code> has a <code>Map<String, String> metadata</code> field. Spring Cloud Consul uses Consul tags to approximate metadata until Consul officially supports metadata. Tags with the form <code>key=value</code> will be split and used as a <code>Map</code> key and value respectively. Tags without the equal <code>=</code> sign, will be used as both the key and value.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>spring:
|
|
cloud:
|
|
consul:
|
|
discovery:
|
|
tags: foo=bar, baz</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The above configuration will result in a map with <code>foo→bar</code> and <code>baz→baz</code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_making_the_consul_instance_id_unique">Making the Consul Instance ID Unique</h4>
|
|
<div class="paragraph">
|
|
<p>By default a consul instance is registered with an ID that is equal to its Spring Application Context ID. By default, the Spring Application Context ID is <code>${spring.application.name}:comma,separated,profiles:${server.port}</code>. For most cases, this will allow multiple instances of one service to run on one machine. If further uniqueness is required, Using Spring Cloud you can override this by providing a unique identifier in <code>spring.cloud.consul.discovery.instanceId</code>. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>spring:
|
|
cloud:
|
|
consul:
|
|
discovery:
|
|
instanceId: ${spring.application.name}:${spring.application.instance_id:${random.value}}</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>With this metadata, and multiple service instances deployed on localhost, the random value will kick in there to make the instance unique. In Cloudfoundry the <code>spring.application.instance_id</code> will be populated automatically in a Spring Boot Actuator application, so the random value will not be needed.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_using_the_discoveryclient">Using the DiscoveryClient</h3>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud has support for <a href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/docs/src/main/asciidoc/spring-cloud-netflix.adoc#spring-cloud-feign">Feign</a> (a REST client builder) and also <a href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/docs/src/main/asciidoc/spring-cloud-netflix.adoc#spring-cloud-ribbon">Spring <code>RestTemplate</code></a> using the logical service names instead of physical URLs.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can also use the <code>org.springframework.cloud.client.discovery.DiscoveryClient</code> which provides a simple API for discovery clients that is not specific to Netflix, e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>@Autowired
|
|
private DiscoveryClient discoveryClient;
|
|
|
|
public String serviceUrl() {
|
|
List<ServiceInstance> list = discoveryClient.getInstances("STORES");
|
|
if (list != null && list.size() > 0 ) {
|
|
return list.get(0).getUri();
|
|
}
|
|
return null;
|
|
}</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-consul-config">Distributed Configuration with Consul</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Consul provides a <a href="https://consul.io/docs/agent/http/kv.html">Key/Value Store</a> for storing configuration and other metadata. Spring Cloud Consul Config is an alternative to the <a href="https://github.com/spring-cloud/spring-cloud-config">Config Server and Client</a>. Configuration is loaded into the Spring Environment during the special "bootstrap" phase. Configuration is stored in the <code>/config</code> folder by default. Multiple <code>PropertySource</code> instances are created based on the application’s name and the active profiles that mimicks the Spring Cloud Config order of resolving properties. For example, an application with the name "testApp" and with the "dev" profile will have the following property sources created:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>config/testApp,dev/
|
|
config/testApp/
|
|
config/application,dev/
|
|
config/application/</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The most specific property source is at the top, with the least specific at the bottom. Properties is the <code>config/application</code> folder are applicable to all applications using consul for configuration. Properties in the <code>config/testApp</code> folder are only available to the instances of the service named "testApp".</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Configuration is currently read on startup of the application. Sending a HTTP POST to <code>/refresh</code> will cause the configuration to be reloaded. Watching the key value store (which Consul supports) is not currently possible, but will be a future addition to this project.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_how_to_activate">How to activate</h3>
|
|
<div class="paragraph">
|
|
<p>Including a dependency on <code>org.springframework.cloud:spring-cloud-consul-config</code> will enable auto-configuration that will setup Spring Cloud Consul Config.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_customizing">Customizing</h3>
|
|
<div class="paragraph">
|
|
<p>Consul Config may be customized using the following properties:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">bootstrap.yml</div>
|
|
<div class="content">
|
|
<pre>spring:
|
|
cloud:
|
|
consul:
|
|
config:
|
|
enabled: true
|
|
prefix: configuration
|
|
defaultContext: apps
|
|
profileSeparator: '::'</pre>
|
|
</div>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><code>enabled</code> setting this value to "false" disables Consul Config</p>
|
|
</li>
|
|
<li>
|
|
<p><code>prefix</code> sets the base folder for configuration values</p>
|
|
</li>
|
|
<li>
|
|
<p><code>defaultContext</code> sets the folder name used by all applications</p>
|
|
</li>
|
|
<li>
|
|
<p><code>profileSeparator</code> sets the value of the separator used to separate the profile name in property sources with profiles</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-consul-config-format">YAML or Properties with Config</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>It may be more convenient to store a blob of properties in YAML or Properties format as opposed to individual key/value pairs. Set the <code>spring.cloud.consul.config.format</code> property to <code>YAML</code> or <code>PROPERTIES</code>. For example to use YAML:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">bootstrap.yml</div>
|
|
<div class="content">
|
|
<pre>spring:
|
|
cloud:
|
|
consul:
|
|
config:
|
|
format: YAML</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>YAML must be set in the appropriate <code>data</code> key in consul. Using the defaults above the keys would look like:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>config/testApp,dev/data
|
|
config/testApp/data
|
|
config/application,dev/data
|
|
config/application/data</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You could store a YAML document in any of the keys listed above.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can change the data key using <code>spring.cloud.consul.config.data-key</code>.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-consul-config-git2consul">git2consul with Config</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>git2consul is a Consul community project that loads files from a git repository to individual keys into Consul. By default the names of the keys are names of the files. YAML and Properties files are supported with file extensions of <code>.yml</code> and <code>.properties</code> respectively. Set the <code>spring.cloud.consul.config.format</code> property to <code>FILES</code>. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">bootstrap.yml</div>
|
|
<div class="content">
|
|
<pre>spring:
|
|
cloud:
|
|
consul:
|
|
config:
|
|
format: FILES</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Given the following keys in <code>/config</code>, the <code>development</code> profile and an application name of <code>foo</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>.gitignore
|
|
application.yml
|
|
bar.properties
|
|
foo-development.properties
|
|
foo-production.yml
|
|
foo.properties
|
|
master.ref</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>the following property sources would be created:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>config/foo-development.properties
|
|
config/foo.properties
|
|
config/application.yml</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The value of each key needs to be a properly formatted YAML or Properties file.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-consul-failfast">Fail Fast</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>It may be convenient in certain circumstances (like local development or certain test scenarios) to not fail if consul isn’t available for configuration. Setting <code>spring.cloud.consul.config.failFast=false</code> in <code>bootstrap.yml</code> will cause the configuration module to log a warning rather than throw an exception. This will allow the application to continue startup normally.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-consul-retry">Consul Retry</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>If you expect that the consul agent may occasionally be unavailable when
|
|
your app starts, you can ask it to keep trying after a failure. You need to add
|
|
<code>spring-retry</code> and <code>spring-boot-starter-aop</code> to your classpath. The default
|
|
behaviour is to retry 6 times with an initial backoff interval of 1000ms and an
|
|
exponential multiplier of 1.1 for subsequent backoffs. You can configure these
|
|
properties (and others) using <code>spring.cloud.consul.retry.*</code> configuration properties.
|
|
This works with both Spring Cloud Consul Config and Discovery registration.</p>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Tip</div>
|
|
</td>
|
|
<td class="content">
|
|
To take full control of the retry add a <code>@Bean</code> of type
|
|
<code>RetryOperationsInterceptor</code> with id "consulRetryInterceptor". Spring
|
|
Retry has a <code>RetryInterceptorBuilder</code> that makes it easy to create one.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-consul-bus">Spring Cloud Bus with Consul</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Coming in a later release.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-consul-hystrix">Circuit Breaker with Hystrix</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Applications can use the Hystrix Circuit Breaker provided by the Spring Cloud Netflix project by including this starter in the projects pom.xml: <code>spring-cloud-starter-hystrix</code>. Hystrix doesn’t depend on the Netflix Discovery Client. The <code>@EnableHystrix</code> annotation should be placed on a configuration class (usually the main class). Then methods can be annotated with <code>@HystrixCommand</code> to be protected by a circuit breaker. See <a href="http://projects.spring.io/spring-cloud/spring-cloud.html#_circuit_breaker_hystrix_clients">the documentation</a> for more details.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-consul-turbine">Hystrix metrics aggregation with Turbine and Consul</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Turbine (provided by the Spring Cloud Netflix project), aggregates multiple instances Hystrix metrics streams, so the dashboard can display an aggregate view. Turbine uses the <code>DiscoveryClient</code> interface to lookup relevant instances. To use Turbine with Spring Cloud Consul, configure the Turbine application in a manner similar to the following examples:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">pom.xml</div>
|
|
<div class="content">
|
|
<pre><dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-netflix-turbine</artifactId>
|
|
</dependency>
|
|
<dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-starter-consul-discovery</artifactId>
|
|
</dependency></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Notice that the Turbine dependency is not a starter. The turbine starter includes support for Netflix Eureka.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>spring.application.name: turbine
|
|
applications: consulhystrixclient
|
|
turbine:
|
|
aggregator:
|
|
clusterConfig: ${applications}
|
|
appConfig: ${applications}</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>clusterConfig</code> and <code>appConfig</code> sections must match, so it’s useful to put the comma-separated list of service ID’s into a separate configuration property.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">Turbine.java</div>
|
|
<div class="content">
|
|
<pre>@EnableTurbine
|
|
@EnableDiscoveryClient
|
|
@SpringBootApplication
|
|
public class Turbine {
|
|
public static void main(String[] args) {
|
|
SpringApplication.run(DemoturbinecommonsApplication.class, args);
|
|
}
|
|
}</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<h1 id="_spring_cloud_zookeeper" class="sect0">Spring Cloud Zookeeper</h1>
|
|
<div class="openblock partintro">
|
|
<div class="content">
|
|
This project provides Zookeeper integrations for Spring Boot apps through autoconfiguration
|
|
and binding to the Spring Environment and other Spring programming model idioms. With a few
|
|
simple annotations you can quickly enable and configure the common patterns inside your
|
|
application and build large distributed systems with Zookeeper based components. The
|
|
patterns provided include Service Discovery and Configuration.
|
|
Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon), Circuit Breaker
|
|
(Hystrix) are provided by integration with Spring Cloud Netflix.
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-zookeeper-install">Install Zookeeper</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Please see the <a href="http://zookeeper.apache.org/doc/current/zookeeperStarted.html">installation documentation</a> for instructions on how to install Zookeeper.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-zookeeper-discovery">Service Discovery with Zookeeper</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Service Discovery is one of the key tenets of a microservice based architecture. Trying to hand configure each client or some form of convention can be very difficult to do and can be very brittle. <a href="http://curator.apache.org">Curator</a>(A java library for Zookeeper) provides Service Discovery services via <a href="http://curator.apache.org/curator-x-discovery/">Service Discovery Extension</a>. Spring Cloud Zookeeper leverages this extension for service registration and discovery.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_how_to_activate_2">How to activate</h3>
|
|
<div class="paragraph">
|
|
<p>Including a dependency on <code>org.springframework.cloud:spring-cloud-starter-zookeeper-discovery</code> will enable auto-configuration that will setup Spring Cloud Zookeeper Discovery.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_registering_with_zookeeper">Registering with Zookeeper</h3>
|
|
<div class="paragraph">
|
|
<p>When a client registers with Zookeeper, it provides meta-data about itself such as host and port, id and name.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Example Zookeeper client:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@SpringBootApplication
|
|
@EnableDiscoveryClient
|
|
@RestController
|
|
public class Application {
|
|
|
|
@RequestMapping("/")
|
|
public String home() {
|
|
return "Hello world";
|
|
}
|
|
|
|
public static void main(String[] args) {
|
|
new SpringApplicationBuilder(Application.class).web(true).run(args);
|
|
}
|
|
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>(i.e. utterly normal Spring Boot app). If Zookeeper is located somewhere other than <code>localhost:2181</code>, the configuration is required to locate the server. Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>spring:
|
|
cloud:
|
|
zookeeper:
|
|
connect-string: localhost:2181</pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock caution">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Caution</div>
|
|
</td>
|
|
<td class="content">
|
|
If you use <a href="#spring-cloud-zookeeper-config">Spring Cloud Zookeeper Config</a>, the above values will need to be placed in <code>bootstrap.yml</code> instead of <code>application.yml</code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The default service name, instance id and port, taken from the <code>Environment</code>, are <code>${spring.application.name}</code>, the Spring Context ID and <code>${server.port}</code> respectively.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><code>@EnableDiscoveryClient</code> makes the app into both a Zookeeper "service" (i.e. it registers itself) and a "client" (i.e. it can query Zookeeper to locate other services).</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_using_the_discoveryclient_2">Using the DiscoveryClient</h3>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud has support for <a href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/docs/src/main/asciidoc/spring-cloud-netflix.adoc#spring-cloud-feign">Feign</a> (a REST client builder) and also <a href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/docs/src/main/asciidoc/spring-cloud-netflix.adoc#spring-cloud-ribbon">Spring <code>RestTemplate</code></a> using the logical service names instead of physical URLs.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can also use the <code>org.springframework.cloud.client.discovery.DiscoveryClient</code> which provides a simple API for discovery clients that is not specific to Netflix, e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>@Autowired
|
|
private DiscoveryClient discoveryClient;
|
|
|
|
public String serviceUrl() {
|
|
List<ServiceInstance> list = discoveryClient.getInstances("STORES");
|
|
if (list != null && list.size() > 0 ) {
|
|
return list.get(0).getUri().toString();
|
|
}
|
|
return null;
|
|
}</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-zookeeper-dependencies">Zookeeper Dependencies</h2>
|
|
<div class="sectionbody">
|
|
<div class="sect2">
|
|
<h3 id="_using_the_zookeeper_dependencies">Using the Zookeeper Dependencies</h3>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Zookeeper gives you a possibility to provide dependencies of your application as properties. As dependencies you can understand other applications that are registered
|
|
in Zookeeper and which you would like to call via <a href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/docs/src/main/asciidoc/spring-cloud-netflix.adoc#spring-cloud-feign">Feign</a> (a REST client builder)
|
|
and also <a href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/docs/src/main/asciidoc/spring-cloud-netflix.adoc#spring-cloud-ribbon">Spring <code>RestTemplate</code></a>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can also benefit from the Zookeeper Dependency Watchers functionality that lets you control and monitor what is the state of your dependencies and decide what to do with that.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_how_to_activate_zookeeper_dependencies">How to activate Zookeeper Dependencies</h3>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>Including a dependency on <code>org.springframework.cloud:spring-cloud-starter-zookeeper-discovery</code> will enable auto-configuration that will setup Spring Cloud Zookeeper Dependencies.</p>
|
|
</li>
|
|
<li>
|
|
<p>If you have to have the <code>spring.cloud.zookeeper.dependencies</code> section properly set up - check the subsequent section for more details then the feature is active</p>
|
|
</li>
|
|
<li>
|
|
<p>You can have the dependencies turned off even if you’ve provided the dependencies in your properties. Just set the property <code>spring.cloud.zookeeper.dependency.enabled</code> to false (defaults to <code>true</code>).</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_setting_up_zookeeper_dependencies">Setting up Zookeeper Dependencies</h3>
|
|
<div class="paragraph">
|
|
<p>Let’s take a closer look at an example of dependencies representation:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre>spring.application.name: yourServiceName
|
|
spring.cloud.zookeeper:
|
|
dependencies:
|
|
newsletter:
|
|
path: /path/where/newsletter/has/registered/in/zookeeper
|
|
loadBalancerType: ROUND_ROBIN
|
|
contentTypeTemplate: application/vnd.newsletter.$version+json
|
|
version: v1
|
|
headers:
|
|
header1:
|
|
- value1
|
|
header2:
|
|
- value2
|
|
required: false
|
|
stubs: org.springframework:foo:stubs
|
|
mailing:
|
|
path: /path/where/mailing/has/registered/in/zookeeper
|
|
loadBalancerType: ROUND_ROBIN
|
|
contentTypeTemplate: application/vnd.mailing.$version+json
|
|
version: v1
|
|
required: true</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Let’s now go through each part of the dependency one by one. The root property name is <code>spring.cloud.zookeeper.dependencies</code>.</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_aliases">Aliases</h4>
|
|
<div class="paragraph">
|
|
<p>Below the root property you have to represent each dependency has by an alias due to the constraints of Ribbon (the application id has to be placed in the URL
|
|
thus you can’t pass any complex path like /foo/bar/name). The alias will be the name that you will use instead of serviceId for <code>DiscoveryClient</code>, <code>Feign</code> or <code>RestTemplate</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In the aforementioned examples the aliases are <code>newsletter</code> and <code>mailing</code>. Example of Feign usage with <code>newsletter</code> would be:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>@FeignClient("newsletter")
|
|
public interface NewsletterService {
|
|
@RequestMapping(method = RequestMethod.GET, value = "/newsletter")
|
|
String getNewsletters();
|
|
}</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_path">Path</h4>
|
|
<div class="paragraph">
|
|
<p>Represented by <code>path</code> yaml property.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Path is the path under which the dependency is registered under Zookeeper. Like presented before Ribbon operates on URLs thus this path is not compliant with its requirement.
|
|
That is why Spring Cloud Zookeeper maps the alias to the proper path.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_load_balancer_type">Load balancer type</h4>
|
|
<div class="paragraph">
|
|
<p>Represented by <code>loadBalancerType</code> yaml property.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you know what kind of load balancing strategy has to be applied when calling this particular dependency then you can provide it in the yaml file and it will be automatically applied.
|
|
You can choose one of the following load balancing strategies</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>STICKY - once chosen the instance will always be called</p>
|
|
</li>
|
|
<li>
|
|
<p>RANDOM - picks an instance randomly</p>
|
|
</li>
|
|
<li>
|
|
<p>ROUND_ROBIN - iterates over instances over and over again</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_content_type_template_and_version">Content-Type template and version</h4>
|
|
<div class="paragraph">
|
|
<p>Represented by <code>contentTypeTemplate</code> and <code>version</code> yaml property.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you version your api via the <code>Content-Type</code> header then you don’t want to add this header to each of your requests. Also if you want to call a new version of the API you don’t want to
|
|
roam around your code to bump up the API version. That’s why you can provide a <code>contentTypeTemplate</code> with a special <code>$version</code> placeholder. That placeholder will be filled by the value of the
|
|
<code>version</code> yaml property. Let’s take a look at an example.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Having the following <code>contentTypeTemplate</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>application/vnd.newsletter.$version+json</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>and the following <code>version</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>v1</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Will result in setting up of a <code>Content-Type</code> header for each request:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>application/vnd.newsletter.v1+json</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_default_headers">Default headers</h4>
|
|
<div class="paragraph">
|
|
<p>Represented by <code>headers</code> map in yaml</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Sometimes each call to a dependency requires setting up of some default headers. In order not to do that in code you can set them up in the yaml file.
|
|
Having the following <code>headers</code> section:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>headers:
|
|
Accept:
|
|
- text/html
|
|
- application/xhtml+xml
|
|
Cache-Control:
|
|
- no-cache</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Results in adding the <code>Accept</code> and <code>Cache-Control</code> headers with appropriate list of values in your HTTP request.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_obligatory_dependencies">Obligatory dependencies</h4>
|
|
<div class="paragraph">
|
|
<p>Represented by <code>required</code> property in yaml</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If one of your dependencies is required to be up and running when your application is booting then it’s enough to set up the <code>required: true</code> property in the yaml file.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If your application can’t localize the required dependency during boot time it will throw an exception and the Spring Context will fail to set up.
|
|
In other words your application won’t be able to start if the required dependency is not registered in Zookeeper.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can read more about Spring Cloud Zookeeper Presence Checker in the following sections.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_stubs">Stubs</h4>
|
|
<div class="paragraph">
|
|
<p>You can provide a colon separated path to the JAR containing stubs of the dependency. Example</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code>stubs: org.springframework:foo:stubs</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>means that for a particular dependencies can be found under:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>groupId: <code>org.springframework</code></p>
|
|
</li>
|
|
<li>
|
|
<p>artifactId: <code>foo</code></p>
|
|
</li>
|
|
<li>
|
|
<p>classifier: <code>stubs</code> - this is the default value</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This is actually equal to</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code>stubs: org.springframework:foo</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>since <code>stubs</code> is the default classifier.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_configuring_spring_cloud_zookeeper_dependencies">Configuring Spring Cloud Zookeeper Dependencies</h3>
|
|
<div class="paragraph">
|
|
<p>There is a bunch of properties that you can set to enable / disable parts of Zookeeper Dependencies functionalities.</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><code>spring.cloud.zookeeper.dependencies</code> - if you don’t set this property you won’t benefit from Zookeeper Dependencies</p>
|
|
</li>
|
|
<li>
|
|
<p><code>spring.cloud.zookeeper.dependency.ribbon.enabled</code> (enabled by default) - Ribbon requires explicit global configuration or a particular one for a dependency. By turning on this property
|
|
runtime load balancing strategy resolution is possible and you can profit from the <code>loadBalancerType</code> section of the Zookeeper Dependencies. The configuration that needs this property
|
|
has an implementation of <code>LoadBalancerClient</code> that delegates to the <code>ILoadBalancer</code> presented in the next bullet</p>
|
|
</li>
|
|
<li>
|
|
<p><code>spring.cloud.zookeeper.dependency.ribbon.loadbalancer</code> (enabled by default) - thanks to this property the custom <code>ILoadBalancer</code> knows that the part of the URI passed to Ribbon might
|
|
actually be the alias that has to be resolved to a proper path in Zookeeper. Without this property you won’t be able to register applications under nested paths.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>spring.cloud.zookeeper.dependency.headers.enabled</code> (enabled by default) - this property registers such a <code>RibbonClient</code> that automatically will append appropriate headers and content
|
|
types with version as presented in the Dependency configuration. Without this setting of those two parameters will not be operational.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>spring.cloud.zookeeper.dependency.resttemplate.enabled</code> (enabled by default) - when enabled will modify the request headers of <code>@LoadBalanced</code> annotated <code>RestTemplate</code> so that it passes
|
|
headers and content type with version set in Dependency configuration. Wihtout this setting of those two parameters will not be operational.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-zookeeper-dependency-watcher">Spring Cloud Zookeeper Dependency Watcher</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>The Dependency Watcher mechanism allows you to register listeners to your dependencies. The functionality is in fact an implementation of the <code>Observator</code> pattern. When a dependency changes
|
|
its state (UP or DOWN) then some custom logic can be applied.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_how_to_activate_3">How to activate</h3>
|
|
<div class="paragraph">
|
|
<p>Spring Cloud Zookeeper Dependencies functionality needs to be enabled to profit from Dependency Watcher mechanism.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_registering_a_listener">Registering a listener</h3>
|
|
<div class="paragraph">
|
|
<p>In order to register a listener you have to implement an interface <code>org.springframework.cloud.zookeeper.discovery.watcher.DependencyWatcherListener</code> and register it as a bean.
|
|
The interface gives you one method:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre> void stateChanged(String dependencyName, DependencyState newState);</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you want to register a listener for a particular dependency then the <code>dependencyName</code> would be the discriminator for your concrete implementation. <code>newState</code> will provide you with information
|
|
whether your dependency has changed to <code>CONNECTED</code> or <code>DISCONNECTED</code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_presence_checker">Presence Checker</h3>
|
|
<div class="paragraph">
|
|
<p>Bound with Dependency Watcher is the functionality called Presence Checker. It allows you to provide custom behaviour upon booting of your application to react accordingly to the state
|
|
of your dependencies.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The default implementation of the abstract <code>org.springframework.cloud.zookeeper.discovery.watcher.presence.DependencyPresenceOnStartupVerifier</code> class is the
|
|
<code>org.springframework.cloud.zookeeper.discovery.watcher.presence.DefaultDependencyPresenceOnStartupVerifier</code> which works in the following way.</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>If the dependency is marked us <code>required</code> and it’s not in Zookeeper then upon booting your application will throw an exception and shutdown</p>
|
|
</li>
|
|
<li>
|
|
<p>If dependency is not <code>required</code> the <code>org.springframework.cloud.zookeeper.discovery.watcher.presence.LogMissingDependencyChecker</code> will log that application is missing at <code>WARN</code> level</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The functionality can be overriden since the <code>DefaultDependencyPresenceOnStartupVerifier</code> is registered only when there is no bean of <code>DependencyPresenceOnStartupVerifier</code>.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="spring-cloud-zookeeper-config">Distributed Configuration with Zookeeper</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Zookeeper provides a <a href="http://zookeeper.apache.org/doc/current/zookeeperOver.html#sc_dataModelNameSpace">hierarchical namespace</a> that allows clients to store arbitrary data, such as configuration data. Spring Cloud Zookeeper Config is an alternative to the <a href="https://github.com/spring-cloud/spring-cloud-config">Config Server and Client</a>. Configuration is loaded into the Spring Environment during the special "bootstrap" phase. Configuration is stored in the <code>/config</code> namespace by default. Multiple <code>PropertySource</code> instances are created based on the application’s name and the active profiles that mimicks the Spring Cloud Config order of resolving properties. For example, an application with the name "testApp" and with the "dev" profile will have the following property sources created:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>config/testApp,dev
|
|
config/testApp
|
|
config/application,dev
|
|
config/application</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The most specific property source is at the top, with the least specific at the bottom. Properties is the <code>config/application</code> namespace are applicable to all applications using zookeeper for configuration. Properties in the <code>config/testApp</code> namespace are only available to the instances of the service named "testApp".</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Configuration is currently read on startup of the application. Sending a HTTP POST to <code>/refresh</code> will cause the configuration to be reloaded. Watching the configuration namespace (which Zookeeper supports) is not currently implemented, but will be a future addition to this project.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_how_to_activate_4">How to activate</h3>
|
|
<div class="paragraph">
|
|
<p>Including a dependency on <code>org.springframework.cloud:spring-cloud-starter-zookeeper-config</code> will enable auto-configuration that will setup Spring Cloud Zookeeper Config.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_customizing_2">Customizing</h3>
|
|
<div class="paragraph">
|
|
<p>Zookeeper Config may be customized using the following properties:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">bootstrap.yml</div>
|
|
<div class="content">
|
|
<pre>spring:
|
|
cloud:
|
|
zookeeper:
|
|
config:
|
|
enabled: true
|
|
root: configuration
|
|
defaultContext: apps
|
|
profileSeparator: '::'</pre>
|
|
</div>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><code>enabled</code> setting this value to "false" disables Zookeeper Config</p>
|
|
</li>
|
|
<li>
|
|
<p><code>root</code> sets the base namespace for configuration values</p>
|
|
</li>
|
|
<li>
|
|
<p><code>defaultContext</code> sets the name used by all applications</p>
|
|
</li>
|
|
<li>
|
|
<p><code>profileSeparator</code> sets the value of the separator used to separate the profile name in property sources with profiles</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<h1 id="_spring_boot_cloud_cli" class="sect0">Spring Boot Cloud CLI</h1>
|
|
<div class="openblock partintro">
|
|
<div class="content">
|
|
Spring Boot CLI provides <a href="http://projects.spring.io/spring-boot">Spring Boot</a> command line features for
|
|
<a href="https://github.com/spring-cloud">Spring Cloud</a>. You can write Groovy scripts to run Spring Cloud component applications
|
|
(e.g. <code>@EnableEurekaServer</code>). You can also easily do things like encryption and decryption to support Spring Cloud
|
|
Config clients with secret configuration values.
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_installation">Installation</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>To install, make
|
|
sure you have
|
|
<a href="https://github.com/spring-projects/spring-boot">Spring Boot CLI</a>
|
|
(1.3.5 or better):</p>
|
|
</div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre>$ spring version
|
|
Spring CLI v1.3.5.RELEASE</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>E.g. for SDKMan users</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code>$ sdk install springboot 1.3.5.RELEASE
|
|
$ sdk use springboot 1.3.5.RELEASE</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>and install the Spring Cloud plugin:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code>$ mvn install
|
|
$ spring install org.springframework.cloud:spring-cloud-cli:1.1.0.RELEASE</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock important">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Important</div>
|
|
</td>
|
|
<td class="content">
|
|
<strong>Prerequisites:</strong> to use the encryption and decryption features
|
|
you need the full-strength JCE installed in your JVM (it’s not there by default).
|
|
You can download the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files"
|
|
from Oracle, and follow instructions for installation (essentially replace the 2 policy files
|
|
in the JRE lib/security directory with the ones that you downloaded).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_writing_groovy_scripts_and_running_applications">Writing Groovy Scripts and Running Applications</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Spring Cloud CLI has support for most of the Spring Cloud declarative
|
|
features, such as the <code>@Enable*</code> class of annotations. For example,
|
|
here is a fully functional Eureka server</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">app.groovy</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-groovy" data-lang="groovy">@EnableEurekaServer
|
|
class Eureka {}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>which you can run from the command line like this</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>$ spring run app.groovy</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To include additional dependencies, often it suffices just to add the
|
|
appropriate feature-enabling annotation, e.g. <code>@EnableConfigServer</code>,
|
|
<code>@EnableOAuth2Sso</code> or <code>@EnableEurekaClient</code>. To manually include a
|
|
dependency you can use a <code>@Grab</code> with the special "Spring Boot" short
|
|
style artifact co-ordinates, i.e. with just the artifact ID (no need
|
|
for group or version information), e.g. to set up a client app to
|
|
listen on AMQP for management events from the Spring CLoud Bus:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">app.groovy</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-groovy" data-lang="groovy">@Grab('spring-cloud-starter-bus-amqp')
|
|
@RestController
|
|
class Service {
|
|
@RequestMapping('/')
|
|
def home() { [message: 'Hello'] }
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_encryption_and_decryption_3">Encryption and Decryption</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>The Spring Cloud CLI comes with an "encrypt" and a "decrypt"
|
|
command. Both accept arguments in the same form with a key specified
|
|
as a mandatory "--key", e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>$ spring encrypt mysecret --key foo
|
|
682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
|
|
$ spring decrypt --key foo 682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
|
|
mysecret</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To use a key in a file (e.g. an RSA public key for encyption) prepend
|
|
the key value with "@" and provide the file path, e.g.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>$ spring encrypt mysecret --key @${HOME}/.ssh/id_rsa.pub
|
|
AQAjPgt3eFZQXwt8tsHAVv/QHiY5sI2dRcR+...</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<h1 id="_spring_cloud_security" class="sect0">Spring Cloud Security</h1>
|
|
<div class="openblock partintro">
|
|
<div class="content">
|
|
Spring Cloud Security offers a set of primitives for building secure
|
|
applications and services with minimum fuss. A declarative model which
|
|
can be heavily configured externally (or centrally) lends itself to
|
|
the implementation of large systems of co-operating, remote components,
|
|
usually with a central indentity management service. It is also extremely
|
|
easy to use in a service platform like Cloud Foundry. Building on
|
|
Spring Boot and Spring Security OAuth2 we can quickly create systems that
|
|
implement common patterns like single sign on, token relay and token
|
|
exchange.
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_quickstart">Quickstart</h2>
|
|
<div class="sectionbody">
|
|
<div class="sect2">
|
|
<h3 id="_oauth2_single_sign_on">OAuth2 Single Sign On</h3>
|
|
<div class="paragraph">
|
|
<p>Here’s a Spring Cloud "Hello World" app with HTTP Basic
|
|
authentication and a single user account:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">app.groovy</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Grab('spring-boot-starter-security')
|
|
@Controller
|
|
class Application {
|
|
|
|
@RequestMapping('/')
|
|
String home() {
|
|
'Hello World'
|
|
}
|
|
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can run it with <code>spring run app.groovy</code> and watch the logs for the password (username is "user"). So far this is just the default for a Spring Boot app.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Here’s a Spring Cloud app with OAuth2 SSO:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">app.groovy</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Controller
|
|
@EnableOAuth2Sso
|
|
class Application {
|
|
|
|
@RequestMapping('/')
|
|
String home() {
|
|
'Hello World'
|
|
}
|
|
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Spot the difference? This app will actually behave exactly the same as
|
|
the previous one, because it doesn’t know it’s OAuth2 credentals
|
|
yet.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can register an app in github quite easily, so try that if you
|
|
want a production app on your own domain. If you are happy to test on
|
|
localhost:8080, then set up these properties in your application
|
|
configuration:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
oauth2:
|
|
client:
|
|
clientId: bd1c0a783ccdd1c9b9e4
|
|
clientSecret: 1a9030fbca47a5b2c28e92f19050bb77824b5ad1
|
|
accessTokenUri: https://github.com/login/oauth/access_token
|
|
userAuthorizationUri: https://github.com/login/oauth/authorize
|
|
clientAuthenticationScheme: form
|
|
resource:
|
|
userInfoUri: https://api.github.com/user
|
|
preferTokenInfo: false</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>run the app above and it will redirect to github for authorization. If
|
|
you are already signed into github you won’t even notice that it has
|
|
authenticated. These credentials will only work if your app is
|
|
running on port 8080.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To limit the scope that the client asks for when it obtains an access token
|
|
you can set <code>spring.oauth2.client.scope</code> (comma separated or an array in YAML). By
|
|
default the scope is empty and it is up to to Authorization Server to
|
|
decide what the defaults should be, usually depending on the settings in
|
|
the client registration that it holds.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
The examples above are all Groovy scripts. If you want to write the
|
|
same code in Java (or Groovy) you need to add Spring Security OAuth2
|
|
to the classpath (e.g. see the
|
|
<a href="https://github.com/spring-cloud-samples/sso">sample here</a>).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_oauth2_protected_resource">OAuth2 Protected Resource</h3>
|
|
<div class="paragraph">
|
|
<p>You want to protect an API resource with an OAuth2 token? Here’s a
|
|
simple example (paired with the client above):</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">app.groovy</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Grab('spring-cloud-starter-security')
|
|
@RestController
|
|
@EnableResourceServer
|
|
class Application {
|
|
|
|
@RequestMapping('/')
|
|
def home() {
|
|
[message: 'Hello World']
|
|
}
|
|
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>and</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">spring:
|
|
oauth2:
|
|
resource:
|
|
userInfoUri: https://api.github.com/user
|
|
preferTokenInfo: false</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_more_detail">More Detail</h2>
|
|
<div class="sectionbody">
|
|
<div class="sect2">
|
|
<h3 id="_single_sign_on">Single Sign On</h3>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
All of the OAuth2 SSO and resource server features moved to Spring Boot
|
|
in version 1.3. You can find documentation in the
|
|
<a href="http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/">Spring Boot user guide</a>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_token_relay">Token Relay</h3>
|
|
<div class="paragraph">
|
|
<p>A Token Relay is where an OAuth2 consumer acts as a Client and
|
|
forwards the incoming token to outgoing resource requests. The
|
|
consumer can be a pure Client (like an SSO application) or a Resource
|
|
Server.</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_client_token_relay">Client Token Relay</h4>
|
|
<div class="paragraph">
|
|
<p>If your app has a
|
|
<a href="http://cloud.spring.io/spring-cloud.html#netflix-zuul-reverse-proxy">Spring
|
|
Cloud Zuul</a> embedded reverse proxy (using <code>@EnableZuulProxy</code>) then you
|
|
can ask it to forward OAuth2 access tokens downstream to the services
|
|
it is proxying. Thus the SSO app above can be enhanced simply like this:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">app.groovy</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Controller
|
|
@EnableOAuth2Sso
|
|
@EnableZuulProxy
|
|
class Application {
|
|
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>and it will (in addition to loggin the user in and grabbing a token)
|
|
pass the authentication token downstream to the <code>/proxy/*</code>
|
|
services. If those services are implemented with
|
|
<code>@EnableOAuth2Resource</code> then they will get a valid token in the
|
|
correct header.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>How does it work? The <code>@EnableOAuth2Sso</code> annotation pulls in
|
|
<code>spring-cloud-starter-security</code> (which you could do manually in a
|
|
traditional app), and that in turn triggers some autoconfiguration for
|
|
a <code>ZuulFilter</code>, which itself is activated because Zuul is on the
|
|
classpath (via <code>@EnableZuulProxy</code>). The
|
|
<a href="https://github.com/spring-cloud/spring-cloud-security/tree/master/src/main/java/org/springframework/cloud/security/oauth2/proxy/OAuth2TokenRelayFilter.java">filter</a>
|
|
just extracts an access token from the currently authenticated user,
|
|
and puts it in a request header for the downstream requests.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_resource_server_token_relay">Resource Server Token Relay</h4>
|
|
<div class="paragraph">
|
|
<p>If your app has <code>@EnableOAuth2Resource</code> and also is a Client (i.e. it
|
|
has a <code>spring.oauth2.client.clientId</code>, even if it doesn’t use it),
|
|
then the <code>OAuth2RestOperations</code> that is provided for <code>@Autowired</code>
|
|
users by Spring Cloud (it is declared as <code>@Primary</code>) will also forward
|
|
tokens. If you don’t want to forward tokens (and that is a valid
|
|
choice, since you might want to act as yourself, rather than the
|
|
client that sent you the token), then you only need to create your own
|
|
<code>OAuth2RestOperations</code> instead of autowiring the default one. Here’s
|
|
a basic example showing the use of the autowired rest template ("foo.com"
|
|
is a Resource Server accepting the same tokens as the surrounding app):</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">MyController.java</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Autowired
|
|
private OAuth2RestOperations restTemplate;
|
|
|
|
@RequestMapping("/relay")
|
|
public String relay() {
|
|
ResponseEntity<String> response =
|
|
restTemplate.getForEntity("https://foo.com/bar", String.class);
|
|
return "Success! (" + response.getBody() + ")";
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_configuring_authentication_downstream_of_a_zuul_proxy">Configuring Authentication Downstream of a Zuul Proxy</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>You can control the authorization behaviour downstream of an
|
|
<code>@EnableZuulProxy</code> through the <code>proxy.auth.*</code> settings. Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">application.yml</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-yaml" data-lang="yaml">proxy:
|
|
auth:
|
|
routes:
|
|
customers: oauth2
|
|
stores: passthru
|
|
recommendations: none</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In this example the "customers" service gets an OAuth2 token relay,
|
|
the "stores" service gets a passthrough (the authorization header is
|
|
just passed downstream), and the "recommendations" service has its
|
|
authorization header removed. The default behaviour is to do a token
|
|
relay if there is a token available, and passthru otherwise.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>See
|
|
<a href="https://github.com/spring-cloud/spring-cloud-security/tree/master/src/main/java/org/springframework/cloud/security/oauth2/proxy/ProxyAuthenticationProperties">
|
|
ProxyAuthenticationProperties</a> for full details.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<h1 id="_spring_cloud_for_cloud_foundry" class="sect0">Spring Cloud for Cloud Foundry</h1>
|
|
<div class="openblock partintro">
|
|
<div class="content">
|
|
<div class="paragraph">
|
|
<p>Spring Cloud for Cloudfoundry makes it easy to run
|
|
<a href="https://github.com/spring-cloud">Spring Cloud</a> apps in
|
|
<a href="https://github.com/cloudfoundry">Cloud Foundry</a> (the Platform as a
|
|
Service). Cloud Foundry has the notion of a "service", which is
|
|
middlware that you "bind" to an app, essentially providing it with an
|
|
environment variable containing credentials (e.g. the location and
|
|
username to use for the service).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>spring-cloud-cloudfoundry-web</code> project provides basic support for
|
|
some enhanced features of webapps in Cloud Foundry: binding
|
|
automatically to single-sign-on services and optionally enabling
|
|
sticky routing for discovery.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>spring-cloud-cloudfoundry-discovery</code> project provides an
|
|
implementation of Spring Cloud Commons <code>DiscoveryClient</code> so you can
|
|
<code>@EnableDiscoveryClient</code> and provide your credentials as
|
|
<code>spring.cloud.cloudfoundry.discovery.[email,password]</code> and then you
|
|
can use the <code>DiscoveryClient</code> directly or via a <code>LoadBalancerClient</code>
|
|
(also <code>*.url</code> if you are not connecting to
|
|
<a href="https://run.pivotal.io">Pivotal Web Services</a>).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The first time you use it the discovery client might be slow owing to
|
|
the fact that it has to get an access token from Cloud Foundry.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_discovery">Discovery</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Here’s a Spring Cloud app with Cloud Foundry discovery:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">app.groovy</div>
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Grab('org.springframework.cloud:spring-cloud-cloudfoundry')
|
|
@RestController
|
|
@EnableDiscoveryClient
|
|
class Application {
|
|
|
|
@Autowired
|
|
DiscoveryClient client
|
|
|
|
@RequestMapping('/')
|
|
String home() {
|
|
'Hello from ' + client.getLocalServiceInstance()
|
|
}
|
|
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you run it without any service bindings:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>$ spring jar app.jar app.groovy
|
|
$ cf push -p app.jar</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>It will show its app name in the home page.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>DiscoveryClient</code> can lists all the apps in a space, according to
|
|
the credentials it is authenticated with, where the space defaults to
|
|
the one the client is running in (if any). If neither org nor space
|
|
are configured, they default per the user’s profile in Cloud Foundry.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_single_sign_on_2">Single Sign On</h2>
|
|
<div class="sectionbody">
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<div class="title">Note</div>
|
|
</td>
|
|
<td class="content">
|
|
All of the OAuth2 SSO and resource server features moved to Spring Boot
|
|
in version 1.3. You can find documentation in the
|
|
<a href="http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/">Spring Boot user guide</a>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This project provides automatic binding from CloudFoundry service
|
|
credentials to the Spring Boot features. If you have a CloudFoundry
|
|
service called "sso", for instance, with credentials containing
|
|
"client_id", "client_secret" and "auth_domain", it will bind
|
|
automatically to the Spring OAuth2 client that you enable with
|
|
<code>@EnableOAuth2Sso</code> (from Spring Boot). The name of the service can be
|
|
parameterized using <code>spring.oauth2.sso.serviceId</code>.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<h1 id="_spring_cloud_cluster" class="sect0">Spring Cloud Cluster</h1>
|
|
<div class="openblock partintro">
|
|
<div class="content">
|
|
Spring Cloud Cluster offers a set of primitives for building "cluster"
|
|
features into a distributed system. Example are leadership election,
|
|
consistent storage of cluster state, global locks and one-time tokens.
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_leader_election">Leader Election</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Leader election allows application to work together with other
|
|
applications to coordinate a cluster leadership via a third party system.
|
|
Currently we provide integrations with <code>zookeeper</code>, <code>hazelcast</code> and <code>etcd</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>From user perspective election is working via interfaces
|
|
<code>org.springframework.cloud.cluster.leader.Candidate</code> and
|
|
<code>org.springframework.cloud.cluster.leader.Context</code>. <code>Candidate</code>
|
|
contains access to leadership’s <code>role</code> and <code>id</code> and also have methods
|
|
<code>onGranted</code> and <code>onRevoked</code>. These callback methods are useful if
|
|
default <code>Candidate</code> implementation is changed.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Leader election is auto-configured if <code>spring-cloud-cluster-autoconfigure</code>
|
|
and either <code>spring-cloud-cluster-hazelcast</code>, <code>spring-cloud-cluster-zookeeper</code>
|
|
or <code>spring-cloud-cluster-etcd</code> jars are found from a classpath. In
|
|
case where both jars are found leader election is created using both
|
|
systems. See sections <a href="#spring-cloud-cluster-leaderelection-zookeeper">Zookeeper</a>,
|
|
<a href="#spring-cloud-cluster-leaderelection-hazelcast">Hazelcast</a> and
|
|
<a href="#spring-cloud-cluster-leaderelection-etcd">Etcd</a> for more
|
|
information about a created beans.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Default <code>Candidate</code> created from auto-configuration is
|
|
<code>org.springframework.cloud.cluster.leader.DefaultCandidate</code> which
|
|
currently only logs granted and revoked events.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If there’s a need for disable all leader related auto-configuration,
|
|
a <code>spring.cloud.cluster.leader.enabled</code> can be set to false which
|
|
then allows to do manual configuration even if the jars an on a
|
|
classpath. Properties <code>spring.cloud.cluster.leader.id</code> and
|
|
<code>spring.cloud.cluster.leader.role</code> can be used to set default
|
|
identifier and role.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If you are interested to simple get notification of granted and
|
|
revoked events one option is to attach event listener into spring
|
|
application context. Events <code>OnGrantedEvent</code> and <code>OnRevokedEvent</code> are
|
|
sent as spring event objects.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Simply create your own event listener class:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">class MyEventListener implements ApplicationListener<AbstractLeaderEvent> {
|
|
|
|
@Override
|
|
public void onApplicationEvent(AbstractLeaderEvent event) {
|
|
// do something with OnGrantedEvent or OnRevokedEvent
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>and then create it as a bean.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">@Configuration
|
|
static class Config {
|
|
@Bean
|
|
public MyEventListener myEventListener() {
|
|
return new MyEventListener();
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>For simply log events you can also use a utility class
|
|
<code>LoggingListener</code> which allows easy configuration.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="highlight"><code class="language-java" data-lang="java">import org.springframework.cloud.cluster.leader.event.LoggingListener;
|
|
|
|
@Configuration
|
|
static class Config {
|
|
@Bean
|
|
public LoggingListener loggingListener() {
|
|
return new LoggingListener("info");
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="spring-cloud-cluster-leaderelection-zookeeper">Zookeeper</h3>
|
|
<div class="paragraph">
|
|
<p><code>Candidate</code> implementation for zookeeper is created with a bean name
|
|
<code>zookeeperLeaderCandidate</code> which can be used to override the one
|
|
created during auto-configuration.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Zookeeper based election can be explicitly disabled using property
|
|
<code>spring.cloud.cluster.zookeeper.leader.enabled</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Other properties <code>spring.cloud.cluster.zookeeper.namespace</code> and
|
|
<code>spring.cloud.cluster.zookeeper.connect</code> can be used to set the
|
|
zookeeper base namespace path and connect string.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="spring-cloud-cluster-leaderelection-hazelcast">Hazelcast</h3>
|
|
<div class="paragraph">
|
|
<p><code>Candidate</code> implementation for hazelcast is created with a bean name
|
|
<code>hazelcastLeaderCandidate</code> which can be used to override the one
|
|
created during auto-configuration.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Hazelcast based election can be explicitly disabled using property
|
|
<code>spring.cloud.cluster.hazelcast.leader.enabled</code>. If you want to provide xml
|
|
based configuration for Hazelcast instance use property
|
|
<code>spring.cloud.cluster.hazelcast.config-location</code> to tell location of a
|
|
Hazelcast xml configuration file. <code>config-location</code> is a normal spring
|
|
<code>Resource</code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="spring-cloud-cluster-leaderelection-etcd">Etcd</h3>
|
|
<div class="paragraph">
|
|
<p><code>Candidate</code> implementation for etcd is created with a bean name
|
|
<code>etcdLeaderCandidate</code> which can be used to override the one
|
|
created during auto-configuration.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Etcd based election can be explicitly disabled using property
|
|
<code>spring.cloud.cluster.etcd.leader.enabled</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Multiple etcd cluster uris can be specified using property
|
|
<code>spring.cloud.cluster.etcd.connect</code></p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<h1 id="_appendix_compendium_of_configuration_properties" class="sect0">Appendix: Compendium of Configuration Properties</h1>
|
|
<div class="openblock partintro">
|
|
<div class="content">
|
|
<table class="tableblock frame-all grid-all spread">
|
|
<colgroup>
|
|
<col style="width: 33%;">
|
|
<col style="width: 33%;">
|
|
<col style="width: 33%;">
|
|
</colgroup>
|
|
<thead>
|
|
<tr>
|
|
<th class="tableblock halign-left valign-top">Name</th>
|
|
<th class="tableblock halign-left valign-top">Default</th>
|
|
<th class="tableblock halign-left valign-top">Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">encrypt.fail-on-error</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to say that a process should fail if there is an encryption or decryption
|
|
error.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">encrypt.key</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">A symmetric key. As a stronger alternative consider using a keystore.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">encrypt.key-store.alias</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Alias for a key in the store.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">encrypt.key-store.location</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Location of the key store file, e.g. classpath:/keystore.jks.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">encrypt.key-store.password</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Password that locks the keystore.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">encrypt.key-store.secret</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Secret protecting the key (defaults to the same as the password).</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">encrypt.rsa.algorithm</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The RSA algorithm to use (DEFAULT or OEAP). Once it is set do not change it (or
|
|
existing ciphers will not a decryptable).</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">encrypt.rsa.salt</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">deadbeef</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Salt for the random secret used to encrypt cipher text. Once it is set do not
|
|
change it (or existing ciphers will not a decryptable).</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">encrypt.rsa.strong</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to indicate that "strong" AES encryption should be used internally. If
|
|
true then the GCM algorithm is applied to the AES encrypted bytes. Default is
|
|
false (in which case "standard" CBC is used instead). Once it is set do not
|
|
change it (or existing ciphers will not a decryptable).</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.bus.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.bus.id</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.bus.sensitive</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.consul.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.consul.id</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.consul.sensitive</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.features.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.features.id</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.features.sensitive</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.pause.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.pause.id</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.pause.sensitive</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.refresh.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.refresh.id</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.refresh.sensitive</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.restart.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.restart.id</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.restart.pause-endpoint.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.restart.pause-endpoint.id</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.restart.pause-endpoint.sensitive</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.restart.resume-endpoint.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.restart.resume-endpoint.id</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.restart.resume-endpoint.sensitive</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.restart.sensitive</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.restart.timeout</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.resume.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.resume.id</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">endpoints.resume.sensitive</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.allow-redirects</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates whether server can redirect a client request to a backup server/cluster.
|
|
If set to false, the server will handle the request directly, If set to true, it
|
|
may send HTTP redirect to the client, with a new server location.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.availability-zones</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the list of availability zones (used in AWS data centers) for the region in
|
|
which this instance resides.
|
|
</p><p class="tableblock"> The changes are effective at runtime at the next registry fetch cycle as specified
|
|
by registryFetchIntervalSeconds.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.backup-registry-impl</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the name of the implementation which implements BackupRegistry to fetch the
|
|
registry information as a fall back option for only the first time when the eureka
|
|
client starts.
|
|
</p><p class="tableblock"> This may be needed for applications which needs additional resiliency for registry
|
|
information without which it cannot operate.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.cache-refresh-executor-exponential-back-off-bound</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">10</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Cache refresh executor exponential back off related property. It is a maximum
|
|
multiplier value for retry delay, in case where a sequence of timeouts occurred.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.cache-refresh-executor-thread-pool-size</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The thread pool size for the cacheRefreshExecutor to initialise with</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.client-data-accept</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">EurekaAccept name for client data accept</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.decoder-name</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">This is a transient config and once the latest codecs are stable, can be removed
|
|
(as there will only be one)</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.disable-delta</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates whether the eureka client should disable fetching of delta and should
|
|
rather resort to getting the full registry information.
|
|
</p><p class="tableblock"> Note that the delta fetches can reduce the traffic tremendously, because the rate
|
|
of change with the eureka server is normally much lower than the rate of fetches.
|
|
</p><p class="tableblock"> The changes are effective at runtime at the next registry fetch cycle as specified
|
|
by registryFetchIntervalSeconds</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.dollar-replacement</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">_-</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Get a replacement string for Dollar sign <code>$</code> during
|
|
serializing/deserializing information in eureka server.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to indicate that the Eureka client is enabled.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.encoder-name</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">This is a transient config and once the latest codecs are stable, can be removed
|
|
(as there will only be one)</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.escape-char-replacement</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">__</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Get a replacement string for underscore sign <code>_</code> during
|
|
serializing/deserializing information in eureka server.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.eureka-connection-idle-timeout-seconds</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">30</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates how much time (in seconds) that the HTTP connections to eureka server can
|
|
stay idle before it can be closed.
|
|
</p><p class="tableblock"> In the AWS environment, it is recommended that the values is 30 seconds or less,
|
|
since the firewall cleans up the connection information after a few mins leaving
|
|
the connection hanging in limbo</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.eureka-server-connect-timeout-seconds</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates how long to wait (in seconds) before a connection to eureka server needs
|
|
to timeout. Note that the connections in the client are pooled by
|
|
org.apache.http.client.HttpClient and this setting affects the actual connection
|
|
creation and also the wait time to get the connection from the pool.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.eureka-server-dnsname</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the DNS name to be queried to get the list of eureka servers.This information
|
|
is not required if the contract returns the service urls by implementing
|
|
serviceUrls.
|
|
</p><p class="tableblock"> The DNS mechanism is used when useDnsForFetchingServiceUrls is set to true and the
|
|
eureka client expects the DNS to configured a certain way so that it can fetch
|
|
changing eureka servers dynamically.
|
|
</p><p class="tableblock"> The changes are effective at runtime.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.eureka-server-port</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the port to be used to construct the service url to contact eureka server when
|
|
the list of eureka servers come from the DNS.This information is not required if
|
|
the contract returns the service urls eurekaServerServiceUrls(String).
|
|
</p><p class="tableblock"> The DNS mechanism is used when useDnsForFetchingServiceUrls is set to true and the
|
|
eureka client expects the DNS to configured a certain way so that it can fetch
|
|
changing eureka servers dynamically.
|
|
</p><p class="tableblock"> The changes are effective at runtime.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.eureka-server-read-timeout-seconds</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">8</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates how long to wait (in seconds) before a read from eureka server needs to
|
|
timeout.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.eureka-server-total-connections</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the total number of connections that is allowed from eureka client to all
|
|
eureka servers.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.eureka-server-total-connections-per-host</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">50</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the total number of connections that is allowed from eureka client to a eureka
|
|
server host.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.eureka-server-urlcontext</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the URL context to be used to construct the service url to contact eureka
|
|
server when the list of eureka servers come from the DNS. This information is not
|
|
required if the contract returns the service urls from eurekaServerServiceUrls.
|
|
</p><p class="tableblock"> The DNS mechanism is used when useDnsForFetchingServiceUrls is set to true and the
|
|
eureka client expects the DNS to configured a certain way so that it can fetch
|
|
changing eureka servers dynamically. The changes are effective at runtime.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.eureka-service-url-poll-interval-seconds</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates how often(in seconds) to poll for changes to eureka server information.
|
|
Eureka servers could be added or removed and this setting controls how soon the
|
|
eureka clients should know about it.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.fetch-registry</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates whether this client should fetch eureka registry information from eureka
|
|
server.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.fetch-remote-regions-registry</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Comma separated list of regions for which the eureka registry information will be
|
|
fetched. It is mandatory to define the availability zones for each of these regions
|
|
as returned by availabilityZones. Failing to do so, will result in failure of
|
|
discovery client startup.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.filter-only-up-instances</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates whether to get the applications after filtering the applications for
|
|
instances with only InstanceStatus UP states.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.g-zip-content</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates whether the content fetched from eureka server has to be compressed
|
|
whenever it is supported by the server. The registry information from the eureka
|
|
server is compressed for optimum network traffic.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.heartbeat-executor-exponential-back-off-bound</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">10</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Heartbeat executor exponential back off related property. It is a maximum
|
|
multiplier value for retry delay, in case where a sequence of timeouts occurred.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.heartbeat-executor-thread-pool-size</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The thread pool size for the heartbeatExecutor to initialise with</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.initial-instance-info-replication-interval-seconds</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">40</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates how long initially (in seconds) to replicate instance info to the eureka
|
|
server</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.instance-info-replication-interval-seconds</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">30</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates how often(in seconds) to replicate instance changes to be replicated to
|
|
the eureka server.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.log-delta-diff</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates whether to log differences between the eureka server and the eureka
|
|
client in terms of registry information.
|
|
</p><p class="tableblock"> Eureka client tries to retrieve only delta changes from eureka server to minimize
|
|
network traffic. After receiving the deltas, eureka client reconciles the
|
|
information from the server to verify it has not missed out some information.
|
|
Reconciliation failures could happen when the client has had network issues
|
|
communicating to server.If the reconciliation fails, eureka client gets the full
|
|
registry information.
|
|
</p><p class="tableblock"> While getting the full registry information, the eureka client can log the
|
|
differences between the client and the server and this setting controls that.
|
|
</p><p class="tableblock"> The changes are effective at runtime at the next registry fetch cycle as specified
|
|
by registryFetchIntervalSecondsr</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.on-demand-update-status-change</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">If set to true, local status updates via ApplicationInfoManager will trigger
|
|
on-demand (but rate limited) register/updates to remote eureka servers</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.prefer-same-zone-eureka</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates whether or not this instance should try to use the eureka server in the
|
|
same zone for latency and/or other reason.
|
|
</p><p class="tableblock"> Ideally eureka clients are configured to talk to servers in the same zone
|
|
</p><p class="tableblock"> The changes are effective at runtime at the next registry fetch cycle as specified
|
|
by registryFetchIntervalSeconds</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.property-resolver</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.proxy-host</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the proxy host to eureka server if any.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.proxy-password</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the proxy password if any.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.proxy-port</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the proxy port to eureka server if any.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.proxy-user-name</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the proxy user name if any.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.region</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">us-east-1</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the region (used in AWS datacenters) where this instance resides.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.register-with-eureka</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates whether or not this instance should register its information with eureka
|
|
server for discovery by others.
|
|
</p><p class="tableblock"> In some cases, you do not want your instances to be discovered whereas you just
|
|
want do discover other instances.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.registry-fetch-interval-seconds</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">30</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates how often(in seconds) to fetch the registry information from the eureka
|
|
server.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.registry-refresh-single-vip-address</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates whether the client is only interested in the registry information for a
|
|
single VIP.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.service-url</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Map of availability zone to list of fully qualified URLs to communicate with eureka
|
|
server. Each value can be a single URL or a comma separated list of alternative
|
|
locations.
|
|
</p><p class="tableblock"> Typically the eureka server URLs carry protocol,host,port,context and version
|
|
information if any. Example:
|
|
<a href="http://ec2-256-156-243-129.compute-1.amazonaws.com:7001/eureka/" class="bare">http://ec2-256-156-243-129.compute-1.amazonaws.com:7001/eureka/</a>
|
|
</p><p class="tableblock"> The changes are effective at runtime at the next service url refresh cycle as
|
|
specified by eurekaServiceUrlPollIntervalSeconds.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.transport</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.client.use-dns-for-fetching-service-urls</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates whether the eureka client should use the DNS mechanism to fetch a list of
|
|
eureka servers to talk to. When the DNS name is updated to have additional servers,
|
|
that information is used immediately after the eureka client polls for that
|
|
information as specified in eurekaServiceUrlPollIntervalSeconds.
|
|
</p><p class="tableblock"> Alternatively, the service urls can be returned serviceUrls, but the users should
|
|
implement their own mechanism to return the updated list in case of changes.
|
|
</p><p class="tableblock"> The changes are effective at runtime.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.dashboard.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to enable the Eureka dashboard. Default true.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.dashboard.path</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">/</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The path to the Eureka dashboard (relative to the servlet path). Defaults to "/".</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.a-sgname</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the AWS autoscaling group name associated with this instance. This information
|
|
is specifically used in an AWS environment to automatically put an instance out of
|
|
service after the instance is launched and it has been disabled for traffic..</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.app-group-name</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Get the name of the application group to be registered with eureka.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.appname</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">unknown</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Get the name of the application to be registered with eureka.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.data-center-info</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the data center this instance is deployed. This information is used to get
|
|
some AWS specific instance information if the instance is deployed in AWS.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.default-address-resolution-order</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">[]</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.health-check-url</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the absolute health check page URL for this instance. The users can provide
|
|
the healthCheckUrlPath if the health check page resides in the same instance
|
|
talking to eureka, else in the cases where the instance is a proxy for some other
|
|
server, users can provide the full URL. If the full URL is provided it takes
|
|
precedence.
|
|
</p><p class="tableblock"> <p>
|
|
It is normally used for making educated decisions based on the health of the
|
|
instance - for example, it can be used to determine whether to proceed deployments
|
|
to an entire farm or stop the deployments without causing further damage. The full
|
|
URL should follow the format <a href="http://${eureka.hostname}:7001/" class="bare">http://${eureka.hostname}:7001/</a> where the value
|
|
${eureka.hostname} is replaced at runtime.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.health-check-url-path</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">/health</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the relative health check URL path for this instance. The health check page
|
|
URL is then constructed out of the hostname and the type of communication - secure
|
|
or unsecure as specified in securePort and nonSecurePort.
|
|
</p><p class="tableblock"> It is normally used for making educated decisions based on the health of the
|
|
instance - for example, it can be used to determine whether to proceed deployments
|
|
to an entire farm or stop the deployments without causing further damage.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.home-page-url</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the absolute home page URL for this instance. The users can provide the
|
|
homePageUrlPath if the home page resides in the same instance talking to eureka,
|
|
else in the cases where the instance is a proxy for some other server, users can
|
|
provide the full URL. If the full URL is provided it takes precedence.
|
|
</p><p class="tableblock"> It is normally used for informational purposes for other services to use it as a
|
|
landing page. The full URL should follow the format <a href="http://${eureka.hostname}:7001/" class="bare">http://${eureka.hostname}:7001/</a>
|
|
where the value ${eureka.hostname} is replaced at runtime.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.home-page-url-path</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">/</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the relative home page URL Path for this instance. The home page URL is then
|
|
constructed out of the hostName and the type of communication - secure or unsecure.
|
|
</p><p class="tableblock"> It is normally used for informational purposes for other services to use it as a
|
|
landing page.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.host-info</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.hostname</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The hostname if it can be determined at configuration time (otherwise it will be
|
|
guessed from OS primitives).</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.inet-utils</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.initial-status</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Initial status to register with rmeote Eureka server.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.instance-enabled-onit</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates whether the instance should be enabled for taking traffic as soon as it
|
|
is registered with eureka. Sometimes the application might need to do some
|
|
pre-processing before it is ready to take traffic.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.instance-id</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Get the unique Id (within the scope of the appName) of this instance to be
|
|
registered with eureka.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.ip-address</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Get the IPAdress of the instance. This information is for academic purposes only as
|
|
the communication from other instances primarily happen using the information
|
|
supplied in {@link #getHostName(boolean)}.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.lease-expiration-duration-in-seconds</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">90</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates the time in seconds that the eureka server waits since it received the
|
|
last heartbeat before it can remove this instance from its view and there by
|
|
disallowing traffic to this instance.
|
|
</p><p class="tableblock"> Setting this value too long could mean that the traffic could be routed to the
|
|
instance even though the instance is not alive. Setting this value too small could
|
|
mean, the instance may be taken out of traffic because of temporary network
|
|
glitches.This value to be set to atleast higher than the value specified in
|
|
leaseRenewalIntervalInSeconds.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.lease-renewal-interval-in-seconds</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">30</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates how often (in seconds) the eureka client needs to send heartbeats to
|
|
eureka server to indicate that it is still alive. If the heartbeats are not
|
|
received for the period specified in leaseExpirationDurationInSeconds, eureka
|
|
server will remove the instance from its view, there by disallowing traffic to this
|
|
instance.
|
|
</p><p class="tableblock"> Note that the instance could still not take traffic if it implements
|
|
HealthCheckCallback and then decides to make itself unavailable.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.metadata-map</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the metadata name/value pairs associated with this instance. This information
|
|
is sent to eureka server and can be used by other instances.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.namespace</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Get the namespace used to find properties. Ignored in Spring Cloud.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.non-secure-port</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">80</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Get the non-secure port on which the instance should receive traffic.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.non-secure-port-enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates whether the non-secure port should be enabled for traffic or not.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.prefer-ip-address</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to say that, when guessing a hostname, the IP address of the server should be
|
|
used in prference to the hostname reported by the OS.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.secure-health-check-url</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the absolute secure health check page URL for this instance. The users can
|
|
provide the secureHealthCheckUrl if the health check page resides in the same
|
|
instance talking to eureka, else in the cases where the instance is a proxy for
|
|
some other server, users can provide the full URL. If the full URL is provided it
|
|
takes precedence.
|
|
</p><p class="tableblock"> <p>
|
|
It is normally used for making educated decisions based on the health of the
|
|
instance - for example, it can be used to determine whether to proceed deployments
|
|
to an entire farm or stop the deployments without causing further damage. The full
|
|
URL should follow the format <a href="http://${eureka.hostname}:7001/" class="bare">http://${eureka.hostname}:7001/</a> where the value
|
|
${eureka.hostname} is replaced at runtime.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.secure-port</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">443</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Get the Secure port on which the instance should receive traffic.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.secure-port-enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates whether the secure port should be enabled for traffic or not.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.secure-virtual-host-name</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the secure virtual host name defined for this instance.
|
|
</p><p class="tableblock"> This is typically the way other instance would find this instance by using the
|
|
secure virtual host name.Think of this as similar to the fully qualified domain
|
|
name, that the users of your services will need to find this instance.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.status-page-url</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the absolute status page URL path for this instance. The users can provide the
|
|
statusPageUrlPath if the status page resides in the same instance talking to
|
|
eureka, else in the cases where the instance is a proxy for some other server,
|
|
users can provide the full URL. If the full URL is provided it takes precedence.
|
|
</p><p class="tableblock"> It is normally used for informational purposes for other services to find about the
|
|
status of this instance. Users can provide a simple HTML indicating what is the
|
|
current status of the instance.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.status-page-url-path</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">/info</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the relative status page URL path for this instance. The status page URL is
|
|
then constructed out of the hostName and the type of communication - secure or
|
|
unsecure as specified in securePort and nonSecurePort.
|
|
</p><p class="tableblock"> It is normally used for informational purposes for other services to find about the
|
|
status of this instance. Users can provide a simple HTML indicating what is the
|
|
current status of the instance.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.instance.virtual-host-name</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the virtual host name defined for this instance.
|
|
</p><p class="tableblock"> This is typically the way other instance would find this instance by using the
|
|
virtual host name.Think of this as similar to the fully qualified domain name, that
|
|
the users of your services will need to find this instance.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.a-sgcache-expiry-timeout-ms</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.a-sgquery-timeout-ms</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">300</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.a-sgupdate-interval-ms</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.a-wsaccess-id</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.a-wssecret-key</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.batch-replication</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.binding-strategy</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.delta-retention-timer-interval-in-ms</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.disable-delta</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.disable-delta-for-remote-regions</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.disable-transparent-fallback-to-other-region</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.e-ipbind-rebind-retries</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.e-ipbinding-retry-interval-ms</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.e-ipbinding-retry-interval-ms-when-unbound</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.enable-replicated-request-compression</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.enable-self-preservation</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.eviction-interval-timer-in-ms</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.g-zip-content-from-remote-region</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.json-codec-name</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.list-auto-scaling-groups-role-name</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">ListAutoScalingGroups</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.log-identity-headers</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.max-elements-in-peer-replication-pool</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">10000</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.max-elements-in-status-replication-pool</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">10000</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.max-idle-thread-age-in-minutes-for-peer-replication</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">15</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.max-idle-thread-in-minutes-age-for-status-replication</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">10</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.max-threads-for-peer-replication</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">20</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.max-threads-for-status-replication</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.max-time-for-replication</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">30000</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.min-threads-for-peer-replication</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.min-threads-for-status-replication</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.number-of-replication-retries</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.peer-eureka-nodes-update-interval-ms</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.peer-eureka-status-refresh-time-interval-ms</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.peer-node-connect-timeout-ms</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.peer-node-connection-idle-timeout-seconds</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">30</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.peer-node-read-timeout-ms</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.peer-node-total-connections</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">1000</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.peer-node-total-connections-per-host</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">500</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.prime-aws-replica-connections</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.property-resolver</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.rate-limiter-burst-size</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">10</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.rate-limiter-enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.rate-limiter-full-fetch-average-rate</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">100</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.rate-limiter-privileged-clients</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.rate-limiter-registry-fetch-average-rate</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">500</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.rate-limiter-throttle-standard-clients</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.registry-sync-retries</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.registry-sync-retry-wait-ms</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.remote-region-app-whitelist</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.remote-region-connect-timeout-ms</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">1000</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.remote-region-connection-idle-timeout-seconds</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">30</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.remote-region-fetch-thread-pool-size</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">20</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.remote-region-read-timeout-ms</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">1000</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.remote-region-registry-fetch-interval</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">30</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.remote-region-total-connections</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">1000</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.remote-region-total-connections-per-host</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">500</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.remote-region-trust-store</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.remote-region-trust-store-password</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">changeit</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.remote-region-urls</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.remote-region-urls-with-name</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.renewal-percent-threshold</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0.85</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.renewal-threshold-update-interval-ms</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.response-cache-auto-expiration-in-seconds</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">180</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.response-cache-update-interval-ms</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.retention-time-in-msin-delta-queue</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.route53-bind-rebind-retries</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.route53-binding-retry-interval-ms</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.route53-domain-ttl</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">30</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.sync-when-timestamp-differs</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.use-read-only-response-cache</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.wait-time-in-ms-when-sync-empty</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">eureka.server.xml-codec-name</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">feign.compression.request.mime-types</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">[text/xml, application/xml, application/json]</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The list of supported mime types.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">feign.compression.request.min-request-size</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">2048</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The minimum threshold content size.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">health.config.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to indicate that the config server health indicator should be installed.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">health.hystrix.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to inidicate that the hystrix health indicator should be installed.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">netflix.atlas.batch-size</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">10000</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">netflix.atlas.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">netflix.atlas.uri</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">proxy.auth.load-balanced</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">proxy.auth.routes</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Authentication strategy per route.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.bus.ack.destination-service</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Service that wants to listen to acks. By default null (meaning all services).</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.bus.ack.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to switch off acks (default on).</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.bus.destination</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">springCloudBus</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Name of Spring Cloud Stream destination for messages.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.bus.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to indicate that the bus is enabled.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.bus.env.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to switch off environment change events (default on).</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.bus.refresh.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to switch off refresh events (default on).</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.bus.trace.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to switch on tracing of acks (default off).</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.cloudfoundry.discovery.email</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Email address of user to authenticate.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.cloudfoundry.discovery.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to indicate that discovery is enabled.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.cloudfoundry.discovery.password</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Password for user to authenticate and obtain token.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.cloudfoundry.discovery.url</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://api.run.pivotal.io" class="bare">https://api.run.pivotal.io</a></p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">URL of Cloud Foundry API (Cloud Controller).</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.allow-override</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to indicate that {@link #isSystemPropertiesOverride()
|
|
systemPropertiesOverride} can be used. Set to false to prevent users from changing
|
|
the default accidentally. Default true.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.discovery.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to indicate that config server discovery is enabled (config server URL will be
|
|
looked up via discovery).</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.discovery.service-id</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">CONFIGSERVER</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Service id to locate config server.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to say that remote configuration is enabled. Default true;</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.fail-fast</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to indicate that failure to connect to the server is fatal (default false).</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.label</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The label name to use to pull remote configuration properties. The default is set
|
|
on the server (generally "master" for a git based server).</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.name</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Name of application used to fetch remote properties.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.override-none</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to indicate that when {@link #setAllowOverride(boolean) allowOverride} is
|
|
true, external properties should take lowest priority, and not override any
|
|
existing property sources (including local config files). Default false.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.override-system-properties</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Flag to indicate that the external properties should override system properties.
|
|
Default true.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.password</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The password to use (HTTP Basic) when contacting the remote server.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.profile</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">default</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The default profile to use when fetching remote configuration (comma-separated).
|
|
Default is "default".</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.retry.initial-interval</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">1000</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Initial retry interval in milliseconds.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.retry.max-attempts</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum number of attempts.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.retry.max-interval</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">2000</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum interval for backoff.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.retry.multiplier</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">1.1</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Multiplier for next interval.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.uri</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://localhost:8888" class="bare">http://localhost:8888</a></p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The URI of the remote server (default <a href="http://localhost:8888" class="bare">http://localhost:8888</a>).</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.config.username</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The username to use (HTTP Basic) when contacting the remote server.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.config.acl-token</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.config.data-key</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">data</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">If format is Format.PROPERTIES or Format.YAML
|
|
then the following field is used as key to look up consul for configuration.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.config.default-context</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">application</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.config.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.config.fail-fast</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Throw exceptions during config lookup if true, otherwise, log warnings.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.config.format</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.config.prefix</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">config</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.config.profile-separator</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">,</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.config.watch.delay</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">10</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.config.watch.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.config.watch.wait-time</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.acl-token</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.catalog-services-watch-delay</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">10</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.catalog-services-watch-timeout</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Is service discovery enabled?</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.health-check-interval</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">10s</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">How often to perform the health check (e.g. 10s)</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.health-check-path</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">/health</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Alternate server path to invoke for health checking</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.health-check-timeout</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Timeout for health check (e.g. 10s)</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.health-check-url</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Custom health check url to override default</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.heartbeat.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.heartbeat.heartbeat-interval</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.heartbeat.interval-ratio</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.heartbeat.ttl-unit</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">s</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.heartbeat.ttl-value</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">30</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.host-info</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.hostname</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Hostname to use when accessing server</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.instance-id</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Unique service instance id</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.ip-address</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">IP address to use when accessing service (must also set preferIpAddress
|
|
to use)</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.lifecycle.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.management-suffix</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">management</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Suffix to use when registering management service</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.management-tags</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Tags to use when registering management service</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.port</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Port to register the service under (defaults to listening port)</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.prefer-agent-address</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Source of how we will determine the address to use</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.prefer-ip-address</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Use ip address rather than hostname during registration</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.query-passing</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Add the 'passing` parameter to /v1/health/service/serviceName.
|
|
This pushes health check passing to the server.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.register</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Register as a service in consul.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.register-health-check</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Register health check in consul. Useful during development of a service.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.scheme</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">http</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Whether to register an http or https service</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.server-list-query-tags</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Map of serviceId’s → tag to query for in server list.
|
|
This allows filtering services by a single tag.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.service-name</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Service name</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.discovery.tags</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Tags to use when registering service</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Is spring cloud consul enabled</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.host</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">localhost</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Consul agent hostname. Defaults to 'localhost'.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.port</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">8500</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Consul agent port. Defaults to '8500'.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.retry.initial-interval</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">1000</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Initial retry interval in milliseconds.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.retry.max-attempts</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum number of attempts.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.retry.max-interval</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">2000</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum interval for backoff.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.consul.retry.multiplier</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">1.1</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Multiplier for next interval.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.hypermedia.refresh.fixed-delay</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">5000</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.hypermedia.refresh.initial-delay</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">10000</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.inetutils.default-hostname</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">localhost</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The default hostname. Used in case of errors.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.inetutils.default-ip-address</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">127.0.0.1</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The default ipaddress. Used in case of errors.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.inetutils.ignored-interfaces</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">List of Java regex expressions for network interfaces that will be ignored.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.inetutils.timeout-seconds</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Timeout in seconds for calculating hostname.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.binders</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.bindings</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.consumer-defaults</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.default-binder</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.dynamic-destinations</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">[]</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.ignore-unknown-properties</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.instance-count</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.instance-index</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.producer-defaults</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.rabbit.binder.addresses</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">[]</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.rabbit.binder.admin-adresses</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">[]</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.rabbit.binder.compression-level</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.rabbit.binder.nodes</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">[]</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.rabbit.binder.password</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.rabbit.binder.ssl-properties-location</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.rabbit.binder.use-ssl</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.rabbit.binder.username</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.rabbit.binder.vhost</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.stream.rabbit.bindings</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.zookeeper.default-health-endpoint</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Default health endpoint that will be checked to verify that a dependency is alive</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.zookeeper.dependencies</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Mapping of alias to ZookeeperDependency. From Ribbon perspective the alias
|
|
is actually serviceID since Ribbon can’t accept nested structures in serviceID</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.zookeeper.dependency-configurations</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.zookeeper.dependency-names</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.zookeeper.discovery.enabled</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.zookeeper.discovery.instance-host</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.zookeeper.discovery.metadata</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the metadata name/value pairs associated with this instance. This information
|
|
is sent to zookeeper and can be used by other instances.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.zookeeper.discovery.root</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">/services</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.zookeeper.discovery.uri-spec</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">{scheme}://{address}:{port}</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.cloud.zookeeper.prefix</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Common prefix that will be applied to all Zookeeper dependencies' paths</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.integration.poller.fixed-delay</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">1000</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Fixed delay for default poller.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.integration.poller.max-messages-per-poll</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum messages per poll for the default poller.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.async.class-name-key</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">class</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Simple name of the class with a method annotated with {@code @Async}
|
|
from which the asynchronous process started
|
|
</p><p class="tableblock"> @see org.springframework.scheduling.annotation.Async</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.async.method-name-key</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">method</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the method annotated with {@code @Async}
|
|
</p><p class="tableblock"> @see org.springframework.scheduling.annotation.Async</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.async.prefix</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Prefix for header names if they are added as tags.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.async.thread-name-key</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">thread</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the thread that executed the async method
|
|
</p><p class="tableblock"> @see org.springframework.scheduling.annotation.Async</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.http.headers</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Additional headers that should be added as tags if they exist. If the header
|
|
value is multi-valued, the tag value will be a comma-separated, single-quoted
|
|
list.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.http.host</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">http.host</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The domain portion of the URL or host header. Example:
|
|
"mybucket.s3.amazonaws.com". Used to filter by host as opposed to ip address.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.http.method</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">http.method</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The HTTP method, or verb, such as "GET" or "POST". Used to filter against an
|
|
http route.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.http.path</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">http.path</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The absolute http path, without any query parameters. Example:
|
|
"/objects/abcd-ff". Used to filter against an http route, portably with zipkin
|
|
v1. In zipkin v1, only equals filters are supported. Dropping query parameters
|
|
makes the number of distinct URIs less. For example, one can query for the same
|
|
resource, regardless of signing parameters encoded in the query line. This does
|
|
not reduce cardinality to a HTTP single route. For example, it is common to
|
|
express a route as an http URI template like "/resource/{resource_id}". In
|
|
systems where only equals queries are available, searching for
|
|
{@code http.uri=/resource} won’t match if the actual request was
|
|
"/resource/abcd-ff". Historical note: This was commonly expressed as "http.uri"
|
|
in zipkin, eventhough it was most often just a path.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.http.prefix</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">http.</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Prefix for header names if they are added as tags.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.http.request-size</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">http.request.size</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The size of the non-empty HTTP request body, in bytes. Ex. "16384"
|
|
</p><p class="tableblock"> <p>Large uploads can exceed limits or contribute directly to latency.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.http.response-size</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">http.response.size</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The size of the non-empty HTTP response body, in bytes. Ex. "16384"
|
|
</p><p class="tableblock"> <p>Large downloads can exceed limits or contribute directly to latency.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.http.status-code</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">http.status_code</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The HTTP response code, when not in 2xx range. Ex. "503" Used to filter for
|
|
error status. 2xx range are not logged as success codes are less interesting
|
|
for latency troubleshooting. Omitting saves at least 20 bytes per span.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.http.url</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">http.url</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The entire URL, including the scheme, host and query parameters if available.
|
|
Ex.
|
|
"https://mybucket.s3.amazonaws.com/objects/abcd-ff?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Algorithm=AWS4-HMAC-SHA256…​"
|
|
Combined with {@link #method}, you can understand the fully-qualified
|
|
request line. This is optional as it may include private data or be of
|
|
considerable length.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.hystrix.command-group</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">commandGroup</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the command group. Hystrix uses the command group key to group
|
|
together commands such as for reporting, alerting, dashboards,
|
|
or team/library ownership.
|
|
</p><p class="tableblock"> @see com.netflix.hystrix.HystrixCommandGroupKey</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.hystrix.command-key</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">commandKey</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the command key. Describes the name for the given command.
|
|
A key to represent a {@link com.netflix.hystrix.HystrixCommand} for
|
|
monitoring, circuit-breakers, metrics publishing, caching and other such uses.
|
|
</p><p class="tableblock"> @see com.netflix.hystrix.HystrixCommandKey</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.hystrix.prefix</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Prefix for header names if they are added as tags.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.hystrix.thread-pool-key</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">threadPoolKey</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the thread pool key. The thread-pool key represents a {@link com.netflix.hystrix.HystrixThreadPool}
|
|
for monitoring, metrics publishing, caching, and other such uses. A {@link com.netflix.hystrix.HystrixCommand}
|
|
is associated with a single {@link com.netflix.hystrix.HystrixThreadPool} as
|
|
retrieved by the {@link com.netflix.hystrix.HystrixThreadPoolKey} injected into it,
|
|
or it defaults to one created using the {@link com.netflix.hystrix.HystrixCommandGroupKey}
|
|
it is created with.
|
|
</p><p class="tableblock"> @see com.netflix.hystrix.HystrixThreadPoolKey</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.message.headers</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Additional headers that should be added as tags if they exist. If the header
|
|
value is not a String it will be converted to a String using its toString()
|
|
method.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.message.payload.size</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">message/payload-size</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">An estimate of the size of the payload if available.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.message.payload.type</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">message/payload-type</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">The type of the payload.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.keys.message.prefix</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">message/</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Prefix for header names if they are added as tags.</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.metric.span.accepted-name</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">counter.span.accepted</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.metric.span.dropped-name</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">counter.span.dropped</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">spring.sleuth.sampler.percentage</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">0.1</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">Percentage of requests that should be sampled. E.g. 1.0 - 100% requests should be
|
|
sampled. The precision is whole-numbers only (i.e. there’s no support for 0.1% of
|
|
the traces).</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">zuul.add-proxy-headers</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">zuul.host.max-per-route-connections</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">20</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">zuul.host.max-total-connections</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">zuul.ignore-local-service</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">zuul.ignored-headers</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">zuul.ignored-patterns</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">zuul.ignored-services</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">zuul.prefix</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">zuul.remove-semicolon-content</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">zuul.retryable</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">zuul.routes</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">zuul.security_headers</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">zuul.servlet-path</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">/zuul</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">zuul.strip-prefix</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">zuul.trace-request-body</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="footer">
|
|
<div id="footer-text">
|
|
Last updated 2016-05-18 09:45:16 +01:00
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html> |