diff --git a/docs/Gemfile b/docs/Gemfile old mode 100644 new mode 100755 index d1a0cfb1d3..dd37e0f06d --- a/docs/Gemfile +++ b/docs/Gemfile @@ -38,4 +38,6 @@ gem "html-proofer" gem "rouge" # Allow running 'rake', e.g. for local link checks -gem "rake" \ No newline at end of file +gem "rake" + +gem "jekyll-toc" diff --git a/docs/_config.yaml b/docs/_config.yaml index 2c650a1ba6..0f811d7539 100644 --- a/docs/_config.yaml +++ b/docs/_config.yaml @@ -6,6 +6,7 @@ title: Microshift description: Microshift is a research project that is exploring how OpenShift Kubernetes can be optimized for small form factor and edge computing. type: website keep_files: ["CNAME"] +repository: redhat-et/microshift # Build settings markdown: kramdown @@ -29,11 +30,20 @@ plugins: - jekyll-remote-theme - jekyll-sitemap - premonition + - jekyll-toc minima:  skin: dark  social_links:    github: redhat-et -# header_pages:  - docs/commands.md -# - docs/config.md -# - docs/examples.md + +header_pages: + - index.md + - design/design.md + - microshift-aio/README.md + - microshift-containerized/README.md + - known-issues.md + +toc: + min_level: 2 # default: 1 + max_level: 6 # default: 6 diff --git a/docs/_includes/metas-ogp.html b/docs/_includes/metas-ogp.html new file mode 100644 index 0000000000..3cb56fa48b --- /dev/null +++ b/docs/_includes/metas-ogp.html @@ -0,0 +1,13 @@ + + {% if page.title %}{{ page.title }} | {{ site.title }}{% else %}{{ site.title }}{% endif %} + + + {% if page.author %}{% endif %} + + + + + + + + diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html new file mode 100644 index 0000000000..efcda1b46c --- /dev/null +++ b/docs/_layouts/default.html @@ -0,0 +1,30 @@ + + + + + + + + + + {% include metas-ogp.html %} + +{% seo %} + + + + + {%- include header.html -%} + +
+
+ {{ content | toc }} +
+
+ + {%- include footer.html -%} + + + \ No newline at end of file diff --git a/docs/_layouts/page.html b/docs/_layouts/page.html new file mode 100644 index 0000000000..9d1ec7defc --- /dev/null +++ b/docs/_layouts/page.html @@ -0,0 +1,14 @@ +--- +layout: default +--- +
+ +
+

{{ page.title | escape }}

+
+ +
+ {{ content | toc }} +
+ +
\ No newline at end of file diff --git a/docs/_layouts/post.html b/docs/_layouts/post.html new file mode 100644 index 0000000000..9df2c2f33a --- /dev/null +++ b/docs/_layouts/post.html @@ -0,0 +1,38 @@ +--- +layout: default +--- +
+ +
+

{{ page.title | escape }}

+

+ {%- assign date_format = site.minima.date_format | default: "%b %-d, %Y" -%} + + {%- if page.modified_date -%} + ~ + {%- assign mdate = page.modified_date | date_to_xmlschema -%} + + {%- endif -%} + {%- if page.author -%} + • {% for author in page.author %} + + {%- if forloop.last == false %}, {% endif -%} + {% endfor %} + {%- endif -%}

+
+ +
+ {{ content | toc }} +
+ + {%- if site.disqus.shortname -%} + {%- include disqus_comments.html -%} + {%- endif -%} + + +
\ No newline at end of file diff --git a/docs/_sass/fonts.scss b/docs/_sass/fonts.scss new file mode 100644 index 0000000000..04c28e9351 --- /dev/null +++ b/docs/_sass/fonts.scss @@ -0,0 +1,55 @@ +@font-face { + font-family: 'Noto Sans'; + font-weight: 400; + font-style: normal; + src: url('../fonts/Noto-Sans-regular/Noto-Sans-regular.eot'); + src: url('../fonts/Noto-Sans-regular/Noto-Sans-regular.eot?#iefix') format('embedded-opentype'), + local('Noto Sans'), + local('Noto-Sans-regular'), + url('../fonts/Noto-Sans-regular/Noto-Sans-regular.woff2') format('woff2'), + url('../fonts/Noto-Sans-regular/Noto-Sans-regular.woff') format('woff'), + url('../fonts/Noto-Sans-regular/Noto-Sans-regular.ttf') format('truetype'), + url('../fonts/Noto-Sans-regular/Noto-Sans-regular.svg#NotoSans') format('svg'); +} + +@font-face { + font-family: 'Noto Sans'; + font-weight: 700; + font-style: normal; + src: url('../fonts/Noto-Sans-700/Noto-Sans-700.eot'); + src: url('../fonts/Noto-Sans-700/Noto-Sans-700.eot?#iefix') format('embedded-opentype'), + local('Noto Sans Bold'), + local('Noto-Sans-700'), + url('../fonts/Noto-Sans-700/Noto-Sans-700.woff2') format('woff2'), + url('../fonts/Noto-Sans-700/Noto-Sans-700.woff') format('woff'), + url('../fonts/Noto-Sans-700/Noto-Sans-700.ttf') format('truetype'), + url('../fonts/Noto-Sans-700/Noto-Sans-700.svg#NotoSans') format('svg'); +} + +@font-face { + font-family: 'Noto Sans'; + font-weight: 400; + font-style: italic; + src: url('../fonts/Noto-Sans-italic/Noto-Sans-italic.eot'); + src: url('../fonts/Noto-Sans-italic/Noto-Sans-italic.eot?#iefix') format('embedded-opentype'), + local('Noto Sans Italic'), + local('Noto-Sans-italic'), + url('../fonts/Noto-Sans-italic/Noto-Sans-italic.woff2') format('woff2'), + url('../fonts/Noto-Sans-italic/Noto-Sans-italic.woff') format('woff'), + url('../fonts/Noto-Sans-italic/Noto-Sans-italic.ttf') format('truetype'), + url('../fonts/Noto-Sans-italic/Noto-Sans-italic.svg#NotoSans') format('svg'); +} + +@font-face { + font-family: 'Noto Sans'; + font-weight: 700; + font-style: italic; + src: url('../fonts/Noto-Sans-700italic/Noto-Sans-700italic.eot'); + src: url('../fonts/Noto-Sans-700italic/Noto-Sans-700italic.eot?#iefix') format('embedded-opentype'), + local('Noto Sans Bold Italic'), + local('Noto-Sans-700italic'), + url('../fonts/Noto-Sans-700italic/Noto-Sans-700italic.woff2') format('woff2'), + url('../fonts/Noto-Sans-700italic/Noto-Sans-700italic.woff') format('woff'), + url('../fonts/Noto-Sans-700italic/Noto-Sans-700italic.ttf') format('truetype'), + url('../fonts/Noto-Sans-700italic/Noto-Sans-700italic.svg#NotoSans') format('svg'); +} diff --git a/docs/_sass/premonition.scss b/docs/_sass/premonition.scss new file mode 100644 index 0000000000..d89e5465ca --- /dev/null +++ b/docs/_sass/premonition.scss @@ -0,0 +1,159 @@ +$default-color: #5bc0de; +$default-light-color: #e3edf2; +$info-color: #50af51; +$info-light-color: #f3f8f3; +$warning-color: #f0ad4e; +$warning-light-color: #fcf8f2; +$error-color: #d9534f; +$error-light-color: #fdf7f7; +$content-color: rgba(0, 0, 0, 0.5); +$citation-color: #495057; +$citation-light-color: #f8f9fa; + +$svg-default-color: "5bc0de"; +$svg-info-color: "50af51"; +$svg-warning-color: "f0ad4e"; +$svg-error-color: "d9534f"; +$svg-citation-color: "495057"; + +.premonition { + display: grid; + grid-template-columns: 43px auto; + padding-top: 13px; + padding-bottom: 13px; + margin: 30px 0 30px 0; + background-color: $default-light-color; + border-left: 4px solid $default-color; + color: $default-color; + + code { + background-color: #fff; + color: $default-color; + } + + .header { + font-weight: 500; + font-size: 1.1rem; + color: $default-color; + padding-bottom: 6px; + } + + .content { + color: $content-color; + padding-left: 20px; + padding-right: 40px; + } + + p { + margin-top: 0; + margin-bottom: 0; + } + + @mixin box-type($c, $lc) { + background-color: $lc; + color: $c; + border-color: $c; + + a { + color: $c; + text-decoration: underline; + } + code { + color: $c; + } + .header { + color: $c; + } + } + + &.info { + @include box-type($info-color, $info-light-color); + } + &.warning { + @include box-type($warning-color, $warning-light-color); + } + &.error { + @include box-type($error-color, $error-light-color); + } + &.citation { + @include box-type($citation-color, $citation-light-color); + + blockquote { + border-left: 0; + } + } + + .fa, + .fas, + .far, + .fal, + .fab { + font-size: 28px; + opacity: 0.3; + padding-top: 2px; + padding-left: 20px; + } + + & > svg { + opacity: 0.6; + margin-top: 0.36rem; + margin-left: 0.7rem; + } + + @mixin pn-icon($pre, $color, $post) { + border: 0; + margin: 3px 0 0 14px; + background-repeat: no-repeat; + background-color: transparent; + background-image: url($pre + "%23" + $color + $post); + background-size: 28px 28px; + width: 28px; + height: 28px; + opacity: 0.3; + } + + /* Autogenerated code */ + &.pn-note { + @include pn-icon( + "data:image/svg+xml,%3C%3Fxml version='1.0' encoding='UTF-8'%3F%3E%3Csvg width='165px' height='165px' viewBox='0 0 165 165' version='1.1' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink'%3E%3Cg id='Page-1' stroke='none' stroke-width='1' fill='none' fill-rule='evenodd'%3E%3Cpath d='M40,0.5 C18.1847524,0.5 0.5,18.1847524 0.5,40 L0.5,125 C0.5,146.815248 18.1847524,164.5 40,164.5 L125,164.5 C146.815248,164.5 164.5,146.815248 164.5,125 L164.5,40 C164.5,18.1847524 146.815248,0.5 125,0.5 L40,0.5 Z M73.9421225,101.035652 C105.680247,64.0622419 122.973943,44.3076275 125.890221,41.6952841 C129.340278,37.6445263 135.770506,37.5263132 140.538208,40.8455453 C145.631474,44.3914319 146.755991,50.3287958 142.263833,56.0881327 C114.758351,89.0776641 89.30795,118.028061 81.5674939,125.633994 C76.464822,130.398827 70.5909248,130.398827 66.4355344,125.58961 C62.9024905,121.371642 58.9333122,116.710237 54.3854087,111.427565 C53.8350288,110.788264 53.2758998,110.139548 52.706934,109.480131 C49.8512069,106.170414 46.9143172,102.783286 43.1506474,98.4546038 C43.1657573,98.4719821 36.1709078,90.431646 34.3564576,88.341891 C27.8799723,80.882735 24.2336656,76.6160672 22.1013335,73.9633891 L22.095737,73.9562966 C15.4200148,65.3371074 30.5778334,52.1721209 38.5786063,60.512576 C48.9690719,71.5242952 60.7566779,85.0318321 73.9420929,101.035687 Z' id='Note' stroke='%23979797' fill='", + $svg-default-color, + "'%3E%3C/path%3E%3C/g%3E%3C/svg%3E" + ); + } + &.pn-info { + @include pn-icon( + "data:image/svg+xml,%3C%3Fxml version='1.0' encoding='UTF-8'%3F%3E%3Csvg width='165px' height='165px' viewBox='0 0 165 165' version='1.1' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink'%3E%3Cg id='Page-1' stroke='none' stroke-width='1' fill='none' fill-rule='evenodd'%3E%3Cpath d='M82.5,165 C36.9365081,165 0,128.063492 0,82.5 C0,36.9365081 36.9365081,0 82.5,0 C128.063492,0 165,36.9365081 165,82.5 C165,128.063492 128.063492,165 82.5,165 Z M71.3481445,44.7539062 C71.3481445,47.7402493 72.400136,50.2853899 74.5041504,52.3894043 C76.6081648,54.4934187 79.1533054,55.5454102 82.1396484,55.5454102 C85.0807439,55.5454102 87.603261,54.4934187 89.7072754,52.3894043 C91.8112898,50.2853899 92.8632812,47.7402493 92.8632812,44.7539062 C92.8632812,41.7675632 91.8112898,39.2224226 89.7072754,37.1184082 C87.603261,35.0143938 85.0807439,33.9624023 82.1396484,33.9624023 C79.1533054,33.9624023 76.6081648,35.0143938 74.5041504,37.1184082 C72.400136,39.2224226 71.3481445,41.7675632 71.3481445,44.7539062 Z M65.2397461,126.674316 L65.2397461,130 L98.3608398,130 L98.3608398,126.674316 C95.8722206,126.176593 94.1754603,125.497888 93.2705078,124.638184 C92.3655554,123.778479 91.9130859,121.83286 91.9130859,118.80127 L91.9130859,65.9975586 L65.2397461,65.9975586 L65.2397461,69.3911133 C68.0450987,69.8888371 69.9228468,70.6467234 70.8730469,71.6647949 C71.8232469,72.6828664 72.2983398,74.5945498 72.2983398,77.3999023 L72.2983398,118.258301 C72.2983398,121.425634 71.6196357,123.620111 70.262207,124.841797 C69.3572546,125.656254 67.6831177,126.267088 65.2397461,126.674316 Z' id='Info' fill='", + $svg-info-color, + "'%3E%3C/path%3E%3C/g%3E%3C/svg%3E" + ); + } + &.pn-warn { + @include pn-icon( + "data:image/svg+xml,%3C%3Fxml version='1.0' encoding='UTF-8'%3F%3E%3Csvg width='165px' height='165px' viewBox='0 0 165 165' version='1.1' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink'%3E%3Cg id='Page-1' stroke='none' stroke-width='1' fill='none' fill-rule='evenodd'%3E%3Cpath d='M82.5,165 C36.9365081,165 0,128.063492 0,82.5 C0,36.9365081 36.9365081,0 82.5,0 C128.063492,0 165,36.9365081 165,82.5 C165,128.063492 128.063492,165 82.5,165 Z M70.0629883,121.226562 C70.0629883,124.484391 71.2054736,127.255767 73.4904785,129.540771 C75.7754834,131.825776 78.5468587,132.968262 81.8046875,132.968262 C85.0625163,132.968262 87.8338916,131.825776 90.1188965,129.540771 C92.4039014,127.255767 93.5463867,124.484391 93.5463867,121.226562 C93.5463867,117.968734 92.4039014,115.197358 90.1188965,112.912354 C87.8338916,110.627349 85.0625163,109.484863 81.8046875,109.484863 C78.5468587,109.484863 75.7754834,110.627349 73.4904785,112.912354 C71.2054736,115.197358 70.0629883,117.968734 70.0629883,121.226562 Z M70.0629883,49.1474609 C70.0629883,50.8668706 70.4475873,53.2423351 71.2167969,56.2739258 C71.7145207,58.2195735 72.8230708,62.1108107 74.5424805,67.9477539 C75.8999091,72.5177637 76.804848,76.0696488 77.2573242,78.6035156 C77.7098004,81.1373825 78.5921158,87.7886831 79.9042969,98.5576172 L83.9086914,98.5576172 C84.8588915,90.0058166 85.5489074,84.3160135 85.9787598,81.4880371 C86.4086122,78.6600607 87.2117454,75.1194874 88.3881836,70.8662109 C90.3338313,63.8075819 91.6799279,58.7286125 92.4265137,55.6291504 C93.1730994,52.5296883 93.5463867,50.2107824 93.5463867,48.6723633 C93.5463867,43.7856201 92.3586545,40.278982 89.9831543,38.1523438 C87.6076541,36.0257055 84.8815258,34.9624023 81.8046875,34.9624023 C78.637354,34.9624023 75.8886021,36.0370172 73.5583496,38.1862793 C71.2280971,40.3355413 70.0629883,43.989232 70.0629883,49.1474609 Z' id='Warning' fill='", + $svg-warning-color, + "'%3E%3C/path%3E%3C/g%3E%3C/svg%3E" + ); + } + &.pn-error { + @include pn-icon( + "data:image/svg+xml,%3C%3Fxml version='1.0' encoding='UTF-8'%3F%3E%3Csvg width='165px' height='165px' viewBox='0 0 165 165' version='1.1' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink'%3E%3Cg id='Page-1' stroke='none' stroke-width='1' fill='none' fill-rule='evenodd'%3E%3Cpath d='M94.8695048,7.74207645 L163.217029,144.437125 C166.674878,151.352824 163.871738,159.762246 156.956039,163.220096 C155.012063,164.192084 152.86848,164.698115 150.695048,164.698115 L14,164.698115 C6.2680135,164.698115 -4.08562073e-14,158.430102 -4.26325641e-14,150.698115 C-4.26325641e-14,148.524684 0.506031285,146.381101 1.47801933,144.437125 L69.8255435,7.74207645 C73.283393,0.826377491 81.6928155,-1.97676336 88.6085145,1.48108612 C91.3178981,2.83577793 93.514813,5.03269282 94.8695048,7.74207645 Z M70.4105124,130.924678 C70.4105124,134.182506 71.5529978,136.953882 73.8380027,139.238887 C76.1230076,141.523892 78.8943829,142.666377 82.1522117,142.666377 C85.4100404,142.666377 88.1814157,141.523892 90.4664206,139.238887 C92.7514256,136.953882 93.8939109,134.182506 93.8939109,130.924678 C93.8939109,127.666849 92.7514256,124.895474 90.4664206,122.610469 C88.1814157,120.325464 85.4100404,119.182978 82.1522117,119.182978 C78.8943829,119.182978 76.1230076,120.325464 73.8380027,122.610469 C71.5529978,124.895474 70.4105124,127.666849 70.4105124,130.924678 Z M70.4105124,58.845576 C70.4105124,60.5649857 70.7951115,62.9404502 71.564321,65.9720409 C72.0620449,67.9176886 73.170595,71.8089258 74.8900046,77.645869 C76.2474333,82.2158788 77.1523722,85.7677639 77.6048484,88.3016307 C78.0573246,90.8354976 78.93964,97.4867982 80.251821,108.255732 L84.2562156,108.255732 C85.2064156,99.7039317 85.8964315,94.0141286 86.3262839,91.1861522 C86.7561363,88.3581758 87.5592696,84.8176025 88.7357078,80.564326 C90.6813555,73.505697 92.0274521,68.4267276 92.7740378,65.3272655 C93.5206236,62.2278034 93.8939109,59.9088975 93.8939109,58.3704784 C93.8939109,53.4837352 92.7061786,49.9770971 90.3306785,47.8504589 C87.9551783,45.7238206 85.22905,44.6605175 82.1522117,44.6605175 C78.9848781,44.6605175 76.2361263,45.7351324 73.9058738,47.8843944 C71.5756212,50.0336565 70.4105124,53.6873471 70.4105124,58.845576 Z' id='Error' fill='", + $svg-error-color, + "'%3E%3C/path%3E%3C/g%3E%3C/svg%3E" + ); + } + &.pn-quote { + @include pn-icon( + "data:image/svg+xml,%3C%3Fxml version='1.0' encoding='UTF-8'%3F%3E%3Csvg width='165px' height='165px' viewBox='0 0 165 165' version='1.1' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink'%3E%3Cg id='Page-1' stroke='none' stroke-width='1' fill='none' fill-rule='evenodd'%3E%3Cpath d='M104.546838,164.525333 C97.1871585,164.350607 90.6368822,160.915227 90.6512001,150.013018 C90.4479076,131.842639 90.4697154,98.303237 90.6512001,49.7828789 C91.9844555,2.36817118 138.064959,0.504907944 148.576644,0.0692731383 C152.479575,0.302510658 153.780675,2.21617827 154.578947,4.17356105 C155.831948,9.88458567 155.831948,17.6357453 154.578947,27.4270401 C153.93686,32.7057192 151.936092,35.3224781 148.576644,35.2773166 C143.472082,35.2236794 151.862467,35.2263624 140.927765,35.2773166 C128.559674,35.7091823 122.660334,39.3672244 122.615074,56.9085817 C122.635604,63.1213926 122.635604,71.5842998 122.615074,82.2973033 C138.48496,82.4101196 149.139584,82.4488979 154.578947,82.4136382 C159.435737,82.5353733 163.923774,84.3352392 164.565789,96.288498 C164.874062,119.857257 164.829662,136.387115 164.782895,150.013018 C164.664253,157.17723 161.233392,164.356416 151.753558,164.525333 C127.51005,164.615729 113.455097,164.525333 104.546838,164.525333 Z M14.0400451,164.45606 C6.68036548,164.281334 0.130089247,160.845954 0.144407166,149.943745 C-0.058885353,131.773366 -0.0370775896,98.2339638 0.144407166,49.7136058 C1.47766255,2.29889804 47.5581663,0.435634806 58.0698511,-9.9475983e-14 C61.9727821,0.233237519 63.2738816,2.14690514 64.0721544,4.10428791 C65.3251551,9.81531253 65.3251551,17.5664722 64.0721544,27.3577669 C63.4300669,32.6364461 61.4292991,35.2532049 58.0698511,35.2080434 C52.9652887,35.1544062 61.3556736,35.1570892 50.4209719,35.2080434 C38.0528815,35.6399092 32.153541,39.2979513 32.1082808,56.8393085 C32.1288111,63.0521194 32.1288111,71.5150266 32.1082808,82.2280302 C47.9781667,82.3408464 58.6327912,82.3796247 64.0721544,82.3443651 C68.9289443,82.4661002 73.4169814,84.265966 74.0589965,96.2192249 C74.367269,119.787984 74.3228688,136.317842 74.2761018,149.943745 C74.1574604,157.107957 70.7265987,164.287143 61.2467647,164.45606 C37.0032571,164.546456 22.9483044,164.45606 14.0400451,164.45606 Z' id='Quote' fill='", + $svg-citation-color, + "'%3E%3C/path%3E%3C/g%3E%3C/svg%3E" + ); + } + &.pn-square { + @include pn-icon( + "data:image/svg+xml,%3C%3Fxml version='1.0' encoding='UTF-8'%3F%3E%3Csvg width='165px' height='165px' viewBox='0 0 165 165' version='1.1' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink'%3E%3Cg id='Page-1' stroke='none' stroke-width='1' fill='none' fill-rule='evenodd'%3E%3Cpath d='M82.5,165 C36.9365081,165 0,128.063492 0,82.5 C0,36.9365081 36.9365081,0 82.5,0 C128.063492,0 165,36.9365081 165,82.5 C165,128.063492 128.063492,165 82.5,165 Z M115.5,99 C124.612698,99 132,91.3888407 132,82 C132,72.6111593 124.612698,65 115.5,65 C106.387302,65 99,72.6111593 99,82 C99,91.3888407 106.387302,99 115.5,99 Z M49.5,99 C58.6126984,99 66,91.3888407 66,82 C66,72.6111593 58.6126984,65 49.5,65 C40.3873016,65 33,72.6111593 33,82 C33,91.3888407 40.3873016,99 49.5,99 Z M66,114 L66,129 L99,129 L99,114 L66,114 Z' id='Default' fill='", + $svg-default-color, + "'%3E%3C/path%3E%3C/g%3E%3C/svg%3E" + ); + } + /* End of Autogenerated code */ +} diff --git a/docs/_sass/rouge-github.scss b/docs/_sass/rouge-github.scss new file mode 100644 index 0000000000..daf76adee9 --- /dev/null +++ b/docs/_sass/rouge-github.scss @@ -0,0 +1,209 @@ +.highlight table td { padding: 5px; } +.highlight table pre { margin: 0; } +.highlight .cm { + color: #999988; + font-style: italic; +} +.highlight .cp { + color: #999999; + font-weight: bold; +} +.highlight .c1 { + color: #999988; + font-style: italic; +} +.highlight .cs { + color: #999999; + font-weight: bold; + font-style: italic; +} +.highlight .c, .highlight .cd { + color: #999988; + font-style: italic; +} +.highlight .err { + color: #a61717; + background-color: #e3d2d2; +} +.highlight .gd { + color: #000000; + background-color: #ffdddd; +} +.highlight .ge { + color: #000000; + font-style: italic; +} +.highlight .gr { + color: #aa0000; +} +.highlight .gh { + color: #999999; +} +.highlight .gi { + color: #000000; + background-color: #ddffdd; +} +.highlight .go { + color: #888888; +} +.highlight .gp { + color: #555555; +} +.highlight .gs { + font-weight: bold; +} +.highlight .gu { + color: #aaaaaa; +} +.highlight .gt { + color: #aa0000; +} +.highlight .kc { + color: #000000; + font-weight: bold; +} +.highlight .kd { + color: #000000; + font-weight: bold; +} +.highlight .kn { + color: #000000; + font-weight: bold; +} +.highlight .kp { + color: #000000; + font-weight: bold; +} +.highlight .kr { + color: #000000; + font-weight: bold; +} +.highlight .kt { + color: #445588; + font-weight: bold; +} +.highlight .k, .highlight .kv { + color: #000000; + font-weight: bold; +} +.highlight .mf { + color: #009999; +} +.highlight .mh { + color: #009999; +} +.highlight .il { + color: #009999; +} +.highlight .mi { + color: #009999; +} +.highlight .mo { + color: #009999; +} +.highlight .m, .highlight .mb, .highlight .mx { + color: #009999; +} +.highlight .sb { + color: #d14; +} +.highlight .sc { + color: #d14; +} +.highlight .sd { + color: #d14; +} +.highlight .s2 { + color: #d14; +} +.highlight .se { + color: #d14; +} +.highlight .sh { + color: #d14; +} +.highlight .si { + color: #d14; +} +.highlight .sx { + color: #d14; +} +.highlight .sr { + color: #009926; +} +.highlight .s1 { + color: #d14; +} +.highlight .ss { + color: #990073; +} +.highlight .s { + color: #d14; +} +.highlight .na { + color: #008080; +} +.highlight .bp { + color: #999999; +} +.highlight .nb { + color: #0086B3; +} +.highlight .nc { + color: #445588; + font-weight: bold; +} +.highlight .no { + color: #008080; +} +.highlight .nd { + color: #3c5d5d; + font-weight: bold; +} +.highlight .ni { + color: #800080; +} +.highlight .ne { + color: #990000; + font-weight: bold; +} +.highlight .nf { + color: #990000; + font-weight: bold; +} +.highlight .nl { + color: #990000; + font-weight: bold; +} +.highlight .nn { + color: #555555; +} +.highlight .nt { + color: #000080; +} +.highlight .vc { + color: #008080; +} +.highlight .vg { + color: #008080; +} +.highlight .vi { + color: #008080; +} +.highlight .nv { + color: #008080; +} +.highlight .ow { + color: #000000; + font-weight: bold; +} +.highlight .o { + color: #000000; + font-weight: bold; +} +.highlight .w { + color: #bbbbbb; +} +.highlight { + background-color: #f8f8f8; +} diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss new file mode 100644 index 0000000000..a7800edd75 --- /dev/null +++ b/docs/assets/css/style.scss @@ -0,0 +1,10 @@ +--- +# Only the main Sass file needs front matter (the dashes are enough) +--- + +@import "minima/skins/{{ site.minima.skin | default: 'classic' }}", + "minima/initialize"; + +@import "premonition"; +@import "rouge-github"; +@import "fonts"; diff --git a/docs/assets/fonts/Noto-Sans-700/Noto-Sans-700.eot b/docs/assets/fonts/Noto-Sans-700/Noto-Sans-700.eot new file mode 100755 index 0000000000..03bf93fec2 Binary files /dev/null and b/docs/assets/fonts/Noto-Sans-700/Noto-Sans-700.eot differ diff --git a/docs/assets/fonts/Noto-Sans-700/Noto-Sans-700.svg b/docs/assets/fonts/Noto-Sans-700/Noto-Sans-700.svg new file mode 100644 index 0000000000..925fe47475 --- /dev/null +++ b/docs/assets/fonts/Noto-Sans-700/Noto-Sans-700.svg @@ -0,0 +1,336 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/fonts/Noto-Sans-700/Noto-Sans-700.ttf b/docs/assets/fonts/Noto-Sans-700/Noto-Sans-700.ttf new file mode 100755 index 0000000000..4599e3ca9a Binary files /dev/null and b/docs/assets/fonts/Noto-Sans-700/Noto-Sans-700.ttf differ diff --git a/docs/assets/fonts/Noto-Sans-700/Noto-Sans-700.woff b/docs/assets/fonts/Noto-Sans-700/Noto-Sans-700.woff new file mode 100755 index 0000000000..9d0b78df81 Binary files /dev/null and b/docs/assets/fonts/Noto-Sans-700/Noto-Sans-700.woff differ diff --git a/docs/assets/fonts/Noto-Sans-700/Noto-Sans-700.woff2 b/docs/assets/fonts/Noto-Sans-700/Noto-Sans-700.woff2 new file mode 100755 index 0000000000..55fc44bcd1 Binary files /dev/null and b/docs/assets/fonts/Noto-Sans-700/Noto-Sans-700.woff2 differ diff --git a/docs/assets/fonts/Noto-Sans-700italic/Noto-Sans-700italic.eot b/docs/assets/fonts/Noto-Sans-700italic/Noto-Sans-700italic.eot new file mode 100755 index 0000000000..cb97b2b4dd Binary files /dev/null and b/docs/assets/fonts/Noto-Sans-700italic/Noto-Sans-700italic.eot differ diff --git a/docs/assets/fonts/Noto-Sans-700italic/Noto-Sans-700italic.svg b/docs/assets/fonts/Noto-Sans-700italic/Noto-Sans-700italic.svg new file mode 100644 index 0000000000..abdafc0f53 --- /dev/null +++ b/docs/assets/fonts/Noto-Sans-700italic/Noto-Sans-700italic.svg @@ -0,0 +1,334 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/fonts/Noto-Sans-700italic/Noto-Sans-700italic.ttf b/docs/assets/fonts/Noto-Sans-700italic/Noto-Sans-700italic.ttf new file mode 100755 index 0000000000..6640dbeb33 Binary files /dev/null and b/docs/assets/fonts/Noto-Sans-700italic/Noto-Sans-700italic.ttf differ diff --git a/docs/assets/fonts/Noto-Sans-700italic/Noto-Sans-700italic.woff b/docs/assets/fonts/Noto-Sans-700italic/Noto-Sans-700italic.woff new file mode 100755 index 0000000000..209739eeb0 Binary files /dev/null and b/docs/assets/fonts/Noto-Sans-700italic/Noto-Sans-700italic.woff differ diff --git a/docs/assets/fonts/Noto-Sans-700italic/Noto-Sans-700italic.woff2 b/docs/assets/fonts/Noto-Sans-700italic/Noto-Sans-700italic.woff2 new file mode 100755 index 0000000000..f5525aa28b Binary files /dev/null and b/docs/assets/fonts/Noto-Sans-700italic/Noto-Sans-700italic.woff2 differ diff --git a/docs/assets/fonts/Noto-Sans-italic/Noto-Sans-italic.eot b/docs/assets/fonts/Noto-Sans-italic/Noto-Sans-italic.eot new file mode 100755 index 0000000000..a997349935 Binary files /dev/null and b/docs/assets/fonts/Noto-Sans-italic/Noto-Sans-italic.eot differ diff --git a/docs/assets/fonts/Noto-Sans-italic/Noto-Sans-italic.svg b/docs/assets/fonts/Noto-Sans-italic/Noto-Sans-italic.svg new file mode 100644 index 0000000000..dcd8fc89dc --- /dev/null +++ b/docs/assets/fonts/Noto-Sans-italic/Noto-Sans-italic.svg @@ -0,0 +1,337 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/fonts/Noto-Sans-italic/Noto-Sans-italic.ttf b/docs/assets/fonts/Noto-Sans-italic/Noto-Sans-italic.ttf new file mode 100755 index 0000000000..7f75a2d909 Binary files /dev/null and b/docs/assets/fonts/Noto-Sans-italic/Noto-Sans-italic.ttf differ diff --git a/docs/assets/fonts/Noto-Sans-italic/Noto-Sans-italic.woff b/docs/assets/fonts/Noto-Sans-italic/Noto-Sans-italic.woff new file mode 100755 index 0000000000..6dce67cede Binary files /dev/null and b/docs/assets/fonts/Noto-Sans-italic/Noto-Sans-italic.woff differ diff --git a/docs/assets/fonts/Noto-Sans-italic/Noto-Sans-italic.woff2 b/docs/assets/fonts/Noto-Sans-italic/Noto-Sans-italic.woff2 new file mode 100755 index 0000000000..a9c14c4920 Binary files /dev/null and b/docs/assets/fonts/Noto-Sans-italic/Noto-Sans-italic.woff2 differ diff --git a/docs/assets/fonts/Noto-Sans-regular/Noto-Sans-regular.eot b/docs/assets/fonts/Noto-Sans-regular/Noto-Sans-regular.eot new file mode 100755 index 0000000000..15fc8bfc91 Binary files /dev/null and b/docs/assets/fonts/Noto-Sans-regular/Noto-Sans-regular.eot differ diff --git a/docs/assets/fonts/Noto-Sans-regular/Noto-Sans-regular.svg b/docs/assets/fonts/Noto-Sans-regular/Noto-Sans-regular.svg new file mode 100644 index 0000000000..bd2894d6a2 --- /dev/null +++ b/docs/assets/fonts/Noto-Sans-regular/Noto-Sans-regular.svg @@ -0,0 +1,335 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/fonts/Noto-Sans-regular/Noto-Sans-regular.ttf b/docs/assets/fonts/Noto-Sans-regular/Noto-Sans-regular.ttf new file mode 100755 index 0000000000..a83bbf9fc8 Binary files /dev/null and b/docs/assets/fonts/Noto-Sans-regular/Noto-Sans-regular.ttf differ diff --git a/docs/assets/fonts/Noto-Sans-regular/Noto-Sans-regular.woff b/docs/assets/fonts/Noto-Sans-regular/Noto-Sans-regular.woff new file mode 100755 index 0000000000..17c85006d0 Binary files /dev/null and b/docs/assets/fonts/Noto-Sans-regular/Noto-Sans-regular.woff differ diff --git a/docs/assets/fonts/Noto-Sans-regular/Noto-Sans-regular.woff2 b/docs/assets/fonts/Noto-Sans-regular/Noto-Sans-regular.woff2 new file mode 100755 index 0000000000..a87d9cd7c6 Binary files /dev/null and b/docs/assets/fonts/Noto-Sans-regular/Noto-Sans-regular.woff2 differ diff --git a/docs/assets/js/scale.fix.js b/docs/assets/js/scale.fix.js new file mode 100644 index 0000000000..2f4f8fd4d3 --- /dev/null +++ b/docs/assets/js/scale.fix.js @@ -0,0 +1,30 @@ +(function (document) { + var metas = document.getElementsByTagName("meta"), + changeViewportContent = function (content) { + for (var i = 0; i < metas.length; i++) { + if (metas[i].name == "viewport") { + metas[i].content = content; + } + } + }, + initialize = function () { + changeViewportContent( + "width=device-width, minimum-scale=1.0, maximum-scale=1.0" + ); + }, + gestureStart = function () { + changeViewportContent( + "width=device-width, minimum-scale=0.25, maximum-scale=1.6" + ); + }, + gestureEnd = function () { + initialize(); + }; + + if (navigator.userAgent.match(/iPhone/i)) { + initialize(); + + document.addEventListener("touchstart", gestureStart, false); + document.addEventListener("touchend", gestureEnd, false); + } +})(document); diff --git a/docs/design/design.md b/docs/design/design.md index 2e50dde624..b3e84935b9 100644 --- a/docs/design/design.md +++ b/docs/design/design.md @@ -1,116 +1,134 @@ -# Design Documentation -The is a documentation of MicroShift's design goals, design principles, and fundamental design decisions. For details on specific feature enhancements, please refer to the corresponding low-level design documents. +--- +modified: "2021-10-25T10:52:50.869+02:00" +title: Design doc. +tags: Design documentation, goals +layout: page +toc: true +--- +The is a documentation of MicroShift's design goals, design principles, and fundamental design decisions. For details on specific feature enhancements, please refer to the corresponding low-level design documents. ## Design Goals + MicroShift aims at meeting all of the following design goals: -* **Optimized for field-deployment:** - * Provisioning and replacing devices running MicroShift is "plug&play"1; MicroShift does not add friction to this. - * e.g. auto-configuring, auto-clustering - * MicroShift works seamlessly under adverse network conditions. - * e.g. disconnected or rarely connected, NAT'ed or firewalled, changing IP addresses, IPv4 or v6, high latency / low bandwidth, no control over local network (DNS, DHCP, LBN, GW), connectivity via LTE dongle (i.e. no LAN) - * MicroShift operates autonomously; it does not require external orchestration. - * MicroShift is safe to change1; it has means to automatically recover from faulty software or configuration updates that would render it unmanageable or non-operational. - * MicroShift is secure1 even in environments without physical accesss security. +- **Optimized for field-deployment:** + + - Provisioning and replacing devices running MicroShift is "plug&play"1; MicroShift does not add friction to this. + - e.g. auto-configuring, auto-clustering + - MicroShift works seamlessly under adverse network conditions. + - e.g. disconnected or rarely connected, NAT'ed or firewalled, changing IP addresses, IPv4 or v6, high latency / low bandwidth, no control over local network (DNS, DHCP, LBN, GW), connectivity via LTE dongle (i.e. no LAN) + - MicroShift operates autonomously; it does not require external orchestration. + - MicroShift is safe to change1; it has means to automatically recover from faulty software or configuration updates that would render it unmanageable or non-operational. + - MicroShift is secure1 even in environments without physical accesss security. 1) when used in combination with an edge-optimized OS like RHEL 4 Edge or Fedora IoT -* **Production-grade:** - * MicroShift supports deployments with 1 or 3 control plane and 0..N worker instances. - * MicroShift can be deployed containerized on Podman or Docker or non-containerized via RPM and managed via systemd; it is compatible with `rpm-ostree`-based systems. - * MicroShift's lifecyle is decoupled from the underlying OS's lifecycle. - * MicroShift can be deployed such that updates or changes to it do not disrupt running workloads. - * MicroShift meets DISA STIG and FedRAMP security requirements; it runs as non-privileged workload and supports common CVE and auditing workflows. - * MicroShift allows segregation between the "edge device administrator" and the "edge service development and operations" personas. - * the former being responsible for device+OS lifecycle and installing MicroShift as a workload, the latter being responsible for services on and resources of the MicroShift cluster - * MicroShift provides application-level events and metrics for observability. +- **Production-grade:** -* **Usability:** - * MicroShift does not require Kubernetes-expertise to configure, deploy, or lifecycle-manage it; Linux admins will find it behaves like any other Linux workload. - * MicroShift does not require Kubernetes-experts to learn new techniques; Kubernetes developers and operations teams will find it supports their tools and processes. - * MicroShift is highly opinionated, working with minimal/no configuration out of the box, but offers escape hatches for advanced users. + - MicroShift supports deployments with 1 or 3 control plane and 0..N worker instances. + - MicroShift can be deployed containerized on Podman or Docker or non-containerized via RPM and managed via systemd; it is compatible with `rpm-ostree`-based systems. + - MicroShift's lifecyle is decoupled from the underlying OS's lifecycle. + - MicroShift can be deployed such that updates or changes to it do not disrupt running workloads. + - MicroShift meets DISA STIG and FedRAMP security requirements; it runs as non-privileged workload and supports common CVE and auditing workflows. + - MicroShift allows segregation between the "edge device administrator" and the "edge service development and operations" personas. + - the former being responsible for device+OS lifecycle and installing MicroShift as a workload, the latter being responsible for services on and resources of the MicroShift cluster + - MicroShift provides application-level events and metrics for observability. -* **Small resource footprint:** - * MicroShift makes frugal use of system resources. It runs on <1GB RAM and <1 CPU core (Intel Atom- or ARM Cortex-class). It consumes <500MB on the wire (per install/update) and <1GB at rest (excl. etcd state). +- **Usability:** -* **Consistency with OpenShift:** - * MicroShift runs all workloads that OpenShift runs, except those which depend on OpenShift's cluster operators. - * MicroShift clusters can be managed like OpenShift clusters through [Open Cluster Management](https://github.com/open-cluster-management), except where functions depend on OpenShift's cluster operators. + - MicroShift does not require Kubernetes-expertise to configure, deploy, or lifecycle-manage it; Linux admins will find it behaves like any other Linux workload. + - MicroShift does not require Kubernetes-experts to learn new techniques; Kubernetes developers and operations teams will find it supports their tools and processes. + - MicroShift is highly opinionated, working with minimal/no configuration out of the box, but offers escape hatches for advanced users. +- **Small resource footprint:** + + - MicroShift makes frugal use of system resources. It runs on <1GB RAM and <1 CPU core (Intel Atom- or ARM Cortex-class). It consumes <500MB on the wire (per install/update) and <1GB at rest (excl. etcd state). + +- **Consistency with OpenShift:** + - MicroShift runs all workloads that OpenShift runs, except those which depend on OpenShift's cluster operators. + - MicroShift clusters can be managed like OpenShift clusters through [Open Cluster Management](https://github.com/open-cluster-management), except where functions depend on OpenShift's cluster operators. ## Design Principles -When deciding between different design options, we follow the following principles: -* **Minimal core**: We keep MicroShift to a minimal set of functionality, but provide mechanisms for extension. - * Discriminator: If a functionality can be added post-cluster-up with reasonable effort, then it should not be part of the MicroShift core/binary. -* **Minimal configuration**: We minimize the number of configuration parameters exposed to users. Where parameters cannot be avoided, we provide robust defaults or try to auto-configure them. - * Discriminator: If a parameter can be infered from another parameter, auto-detected, or only covers rare use cases, then likely it should not be exposed to users. -* **Robustness to failure modes**: We expect and gracefully handle failure modes stemming from field-deployment and that MicroShift is just an app on somebody else's OS it cannot control. -* **Production over Development**: We engineer for production-deployments, not Kubernetes application development environments. -* **Frugal use of resources**: We are mindful of MicroShift's resources consumption, considering all resources (memory, CPU, storage I/O, network I/O). -* **No premature resouce optimization**: We do not attempt to squeeze out the last 20% of resouces, e.g. by patching or compressing code, inventing lighter-weight components, etc. -* **Ease-of-Use**: We make MicroShift intutive and simple to use, even if that means providing fewer features and options. -* **Prefer well-established mechanisms**: We meet users where they are by letting them use well-established tools and patterns rather than requiring them to learn new ones. -* **Cheap Control Plane Restarts**: We keep MicroShift restarts cheap (= fast, low resource consumption, low workload impact, etc.) as it is our default model for software and configuration changes. -* **Alignment with OpenShift**: We reuse OpenShift's code, operational logic, and production chain tools and processes where possible with reasonable effort, unless this would conflict with MicroShift's goals. +When deciding between different design options, we follow the following principles: +- **Minimal core**: We keep MicroShift to a minimal set of functionality, but provide mechanisms for extension. + - Discriminator: If a functionality can be added post-cluster-up with reasonable effort, then it should not be part of the MicroShift core/binary. +- **Minimal configuration**: We minimize the number of configuration parameters exposed to users. Where parameters cannot be avoided, we provide robust defaults or try to auto-configure them. + - Discriminator: If a parameter can be infered from another parameter, auto-detected, or only covers rare use cases, then likely it should not be exposed to users. +- **Robustness to failure modes**: We expect and gracefully handle failure modes stemming from field-deployment and that MicroShift is just an app on somebody else's OS it cannot control. +- **Production over Development**: We engineer for production-deployments, not Kubernetes application development environments. +- **Frugal use of resources**: We are mindful of MicroShift's resources consumption, considering all resources (memory, CPU, storage I/O, network I/O). +- **No premature resouce optimization**: We do not attempt to squeeze out the last 20% of resouces, e.g. by patching or compressing code, inventing lighter-weight components, etc. +- **Ease-of-Use**: We make MicroShift intutive and simple to use, even if that means providing fewer features and options. +- **Prefer well-established mechanisms**: We meet users where they are by letting them use well-established tools and patterns rather than requiring them to learn new ones. +- **Cheap Control Plane Restarts**: We keep MicroShift restarts cheap (= fast, low resource consumption, low workload impact, etc.) as it is our default model for software and configuration changes. +- **Alignment with OpenShift**: We reuse OpenShift's code, operational logic, and production chain tools and processes where possible with reasonable effort, unless this would conflict with MicroShift's goals. ## Design Decisions + ### Overall Architecture -* MicroShift is an application deployed onto a running OS, preferably as container on `podman`, managed through `systemd`. As such, it cannot assume any responsiblity or control over the device or OS it runs on, including OS software or configuration updates or typical device management tasks such as configuring host CA certs or host telemetry. -* MicroShift runs as a single binary embedding as goroutines only those services strictly necessary to bring up a *minimal Kubernetes/OpenShift control and data plane*. Motivation: - * Maximizes reproducibility; cluster will come up fully or not at all. - * Does not require external orchestration, for example through operators, and allows for very fast start-up/update times. - * Makes it simple to grok as workload for a a Linux admin persona, works well / easier to implement with systemd. - * Smaller resource footprint has _not_ been a motivation, it may be a welcome side-effect. -* MicroShift provides a small, optional set of infrastructure services to support common use cases and reuses OpenShift's container images for these: - * openshift-dns, openshift-router, service-ca, local storage provider -* MicroShift instances (processes) run directly on the host or containerized on Podman. They can take on the roles of Control Plane, Node, or both: - * Instances with Control Plane role run etcd and the Kubernetes and OpenShift control plane services. As these services don't require a kubelet, pure Control Plane instances are not nodes in the Kubernetes sense and require fewer system privileges. - * Instances with Node role run a kubelet (and thus register as node) and kube-proxy and interface with CRI-O for running workloads. They may thus require higher system privileges. -* While it's possible to run a single MicroShift instance with both Control Plane and Node roles, there may be reasons to run two instances - one Control Plane and one Node - on the same host, e.g. to run the Control Plane with fewer privileges for security reasons. Implementation decisions should consider this. -* MicroShift does not bundle any OS user space! Bundling makes maintenance and security hard, breaks compliance. Instead, user space is provided by the host OS, the container image base layer or a sidecar container. + +- MicroShift is an application deployed onto a running OS, preferably as container on `podman`, managed through `systemd`. As such, it cannot assume any responsiblity or control over the device or OS it runs on, including OS software or configuration updates or typical device management tasks such as configuring host CA certs or host telemetry. +- MicroShift runs as a single binary embedding as goroutines only those services strictly necessary to bring up a _minimal Kubernetes/OpenShift control and data plane_. Motivation: + - Maximizes reproducibility; cluster will come up fully or not at all. + - Does not require external orchestration, for example through operators, and allows for very fast start-up/update times. + - Makes it simple to grok as workload for a a Linux admin persona, works well / easier to implement with systemd. + - Smaller resource footprint has _not_ been a motivation, it may be a welcome side-effect. +- MicroShift provides a small, optional set of infrastructure services to support common use cases and reuses OpenShift's container images for these: + - openshift-dns, openshift-router, service-ca, local storage provider +- MicroShift instances (processes) run directly on the host or containerized on Podman. They can take on the roles of Control Plane, Node, or both: + - Instances with Control Plane role run etcd and the Kubernetes and OpenShift control plane services. As these services don't require a kubelet, pure Control Plane instances are not nodes in the Kubernetes sense and require fewer system privileges. + - Instances with Node role run a kubelet (and thus register as node) and kube-proxy and interface with CRI-O for running workloads. They may thus require higher system privileges. +- While it's possible to run a single MicroShift instance with both Control Plane and Node roles, there may be reasons to run two instances - one Control Plane and one Node - on the same host, e.g. to run the Control Plane with fewer privileges for security reasons. Implementation decisions should consider this. +- MicroShift does not bundle any OS user space! Bundling makes maintenance and security hard, breaks compliance. Instead, user space is provided by the host OS, the container image base layer or a sidecar container. ### CLI -* The `microshift` binary runs the Control Plane / Node process, it is not a tool to manage or be clients to those processes (like `oc` or `kubeadmin`). This is reflected in the sub-commands and paraemters offered by it, e.g. using the `run` verb (which implies run-to-cancel/run-to-completion) instead of `start`/`stop` verb-pairs (which imply asynch commands that return immediately). -* For consistency and to play nicely with systemd, we avoid command line parameters that would need to be different between invokations (e.g. first-run vs subsequent runs) or instantiations (e.g. 1st Control Plane instances vs. 2nd or 3rd Control Plane instance). + +- The `microshift` binary runs the Control Plane / Node process, it is not a tool to manage or be clients to those processes (like `oc` or `kubeadmin`). This is reflected in the sub-commands and paraemters offered by it, e.g. using the `run` verb (which implies run-to-cancel/run-to-completion) instead of `start`/`stop` verb-pairs (which imply asynch commands that return immediately). +- For consistency and to play nicely with systemd, we avoid command line parameters that would need to be different between invokations (e.g. first-run vs subsequent runs) or instantiations (e.g. 1st Control Plane instances vs. 2nd or 3rd Control Plane instance). ### Configuration -* MicroShift uses a strictly declarative style of configuration. -* MicroShift uses as few configuration options as possible. Where it provides configuration options, they are intuitive and have sensible defauls respectively are auto-configured. -* MicroShift is preferably configured through config files, but allows overriding of parameters via environment variables (for use in containers, systemd) and command line flags (for ad-hoc use). -* MicroShift can use both user-local and system-wide configuration. + +- MicroShift uses a strictly declarative style of configuration. +- MicroShift uses as few configuration options as possible. Where it provides configuration options, they are intuitive and have sensible defauls respectively are auto-configured. +- MicroShift is preferably configured through config files, but allows overriding of parameters via environment variables (for use in containers, systemd) and command line flags (for ad-hoc use). +- MicroShift can use both user-local and system-wide configuration. ### Security -* MicroShift instances should run with least privileges. In particular Control Plane-only instances should run completely non-privileged. -* MicroShift should minimize the number of open network ports. In particular Node-only instances should not open any listening ports. -* Assume there is no way to access the device or MicroShift instance from remote, i.e. no SSH access nor Kubernetes API access (for kubectl). Instead, communication is *always* initiated from the device / cluster towards the management system. -* Open issues / questions: - * Model for joining nodes to MicroShift clusters. - * Model for certificate rotation. - * Requirements for FedRAMP and DISA STIG compliance. - * How to leverage / support the host OS's features for FIDO Device Onboard, remote attestation, integrity measurement architecture. - * How to support secure supply chain. + +- MicroShift instances should run with least privileges. In particular Control Plane-only instances should run completely non-privileged. +- MicroShift should minimize the number of open network ports. In particular Node-only instances should not open any listening ports. +- Assume there is no way to access the device or MicroShift instance from remote, i.e. no SSH access nor Kubernetes API access (for kubectl). Instead, communication is _always_ initiated from the device / cluster towards the management system. +- Open issues / questions: + - Model for joining nodes to MicroShift clusters. + - Model for certificate rotation. + - Requirements for FedRAMP and DISA STIG compliance. + - How to leverage / support the host OS's features for FIDO Device Onboard, remote attestation, integrity measurement architecture. + - How to support secure supply chain. ### Networking -* Host networking is configured by device management. MicroShift has to work with what it's been given by the host OS. -* No Multus. -* Open issues / questions: - * Lightweight CNI? - * API Load Balancing? - * Service Load Balancing? - * Ingress? + +- Host networking is configured by device management. MicroShift has to work with what it's been given by the host OS. +- No Multus. +- Open issues / questions: + - Lightweight CNI? + - API Load Balancing? + - Service Load Balancing? + - Ingress? ### Storage -* MicroShift defaults to local ephemeral storage (enough for basic use cases). -* Open issues / questions: - * Provide escape hatch to add own CSI (which?). + +- MicroShift defaults to local ephemeral storage (enough for basic use cases). +- Open issues / questions: + - Provide escape hatch to add own CSI (which?). ### Production / Supply Chain / Release Management -* MicroShift vendors OKD source code without modification. Where it deploys container images for additional services, it deploys OKD's published container images, not the OpenShift downstream's. -* MicroShift's versioning scheme follows OKD's. This scheme signals the base OpenShift version (4.x) and order/age of builds, but intentionally avoids signaling patch level, backward compatibility (as SemVer, for example), or stability. -* We ensure the tip of our development branch is deployable and while MicroShift is still early days and experimental we expect developers (and users who want the "latest") to build & deploy from source. -* Releases are mainly provided for convenience to users that just want to give MicroShift a quick try without friction. They are cut irregularly, e.g. to make a new feature available. -* When rebasing onto a new OKD version, we vendor that version's packages and update the container image digests of the infrastructure services MicroShift deploys, i.e. the "release metadata" is baked into the MicroShift binary. -* Eventually, we expect there to be a "MicroShift Release Image" that is based on / derived from the OpenShift Release Image: It references the MicroShift container image plus the subset of container images shared with and published by OpenShift. Defining a release image should allow to reuse the proven OpenShift CI and release tooling later. + +- MicroShift vendors OKD source code without modification. Where it deploys container images for additional services, it deploys OKD's published container images, not the OpenShift downstream's. +- MicroShift's versioning scheme follows OKD's. This scheme signals the base OpenShift version (4.x) and order/age of builds, but intentionally avoids signaling patch level, backward compatibility (as SemVer, for example), or stability. +- We ensure the tip of our development branch is deployable and while MicroShift is still early days and experimental we expect developers (and users who want the "latest") to build & deploy from source. +- Releases are mainly provided for convenience to users that just want to give MicroShift a quick try without friction. They are cut irregularly, e.g. to make a new feature available. +- When rebasing onto a new OKD version, we vendor that version's packages and update the container image digests of the infrastructure services MicroShift deploys, i.e. the "release metadata" is baked into the MicroShift binary. +- Eventually, we expect there to be a "MicroShift Release Image" that is based on / derived from the OpenShift Release Image: It references the MicroShift container image plus the subset of container images shared with and published by OpenShift. Defining a release image should allow to reuse the proven OpenShift CI and release tooling later. diff --git a/docs/index.md b/docs/index.md index 81b2d6b5aa..abc25ea283 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,31 +1,38 @@ -# Microshift +--- +modified: "2021-10-25T11:08:42.763+02:00" +title: The Project +tags: microsihift project, edge, µShift +layout: page +toc: true +--- Microshift is a research project that is exploring how OpenShift1 Kubernetes can be optimized for small form factor and edge computing. Edge devices deployed out in the field pose very different operational, environmental, and business challenges from those of cloud computing. These motivate different engineering trade-offs for Kubernetes at the far edge than for cloud or near-edge scenarios. Microshift's design goals cater to this: -* make frugal use of system resources (CPU, memory, network, storage, etc.), -* tolerate severe networking constraints, -* update (resp. roll back) securely, safely, speedily, and seamlessly (without disrupting workloads), and -* build on and integrate cleanly with edge-optimized OSes like Fedora IoT and RHEL for Edge, while -* providing a consistent development and management experience with standard OpenShift. +- make frugal use of system resources (CPU, memory, network, storage, etc.), +- tolerate severe networking constraints, +- update (resp. roll back) securely, safely, speedily, and seamlessly (without disrupting workloads), and +- build on and integrate cleanly with edge-optimized OSes like Fedora IoT and RHEL for Edge, while +- providing a consistent development and management experience with standard OpenShift. We believe these properties should also make Microshift a great tool for other use cases such as Kubernetes applications development on resource-constrained systems, scale testing, and provisioning of lightweight Kubernetes control planes. Watch this [end-to-end MicroShift provisioning demo video](https://youtu.be/QOiB8NExtA4) to get a first impression of MicroShift deployed onto a [RHEL for edge computing](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux/edge-computing) device and managed through [Open Cluster Management](https://github.com/open-cluster-management). -**Note: Microshift is still early days and moving fast. Features are missing. Things break. But you can still help shape it, too.** +> warning "" +> Microshift is still early days and moving fast. Features are missing. Things break. But you can still help shape it, too.\*\* 1) more precisely [OKD](https://www.okd.io/), the Kubernetes distribution by the OpenShift community ## Minimum specs - In order to run Microshift, you will need at least: + - 2 CPU cores - 2GB of RAM - ~124MB of free storage space for the Microshift binary -- 64-bit CPU (although 32-bit is *technically* possible, if you're up for the challenge) +- 64-bit CPU (although 32-bit is _technically_ possible, if you're up for the challenge) For barebones development the minimum requirement is 3GB of RAM, though this can increase if you are using resource-intensive devtools. @@ -35,6 +42,7 @@ if you are using resource-intensive devtools. The all-in-one containerized Microshift can run on Windows, MacOS, and Linux. Currently, the Microshift binary is known to be supported on the following Operating Systems: + - Fedora 33/34 - CentOS 8 Stream - RHEL 8 @@ -43,28 +51,33 @@ Currently, the Microshift binary is known to be supported on the following Opera It may be possible to run Microshift on other systems, however they haven't been tested so you may run into issues. - ## Using Microshift + To give Microshift a try, simply install a recent test version (we don't provide stable releases yet) on a Fedora-derived Linux distro (we've only tested Fedora, RHEL, and CentOS Stream so far) using: -``` +```sh curl -sfL https://raw.githubusercontent.com/redhat-et/microshift/main/install.sh | bash ``` This will install Microshift's dependencies (CRI-O), install it as a systemd service and start it. For convenience, the script will also add a new "microshift" context to your `$HOME/.kube/config`, so you'll be able to access your cluster using, e.g.: -``` + +```sh kubectl get all -A --context microshift ``` + or -``` + +```sh kubectl config use-context microshift kubectl get all -A ``` -Notes: When installing Microshift on a system with an older version already installed, it is safest to remove the old data directory and start fresh: -``` +> info "" +> When installing Microshift on a system with an older version already installed, it is safest to remove the old data directory and start fresh: + +```sh rm -rf /var/lib/microshift && rm -r $HOME/.microshift ``` @@ -72,42 +85,45 @@ rm -rf /var/lib/microshift && rm -r $HOME/.microshift ## Developing Microshift -> Note: when building or running **ARM64** container images, Linux host environments must have the `qemu-user-static` package installed. E.g. on Fedora: `dnf install qemu-user-static`. +> warning "" +> when building or running **ARM64** container images, Linux host environments must have the `qemu-user-static` package installed. E.g. on Fedora: `dnf install qemu-user-static`. ### Building You can locally build Microshift using one of two methods, either using a container build (recommended) on Podman or Docker: -``` + +```sh sudo yum -y install make golang make microshift ``` or directly on the host after installing the build-time dependencies. When using RHEL ensure the system is registered and run the following before installing the prerequisites. -``` +```sh ARCH=$( /bin/arch ) sudo subscription-manager repos --enable "codeready-builder-for-rhel-8-${ARCH}-rpms" ``` The following packages are required for Fedora and RHEL. -``` + +```sh sudo yum install -y glibc-static gcc make golang make ``` ### Environment Configuration -Before running Microshift, the host must first be configured. This can be handled by running +Before running Microshift, the host must first be configured. This can be handled by running -``` +```sh CONFIG_ENV_ONLY=true ./install.sh ``` Microshift keeps all its state in its data-dir, which defaults to `/var/lib/microshift` when running Microshift as privileged user and `$HOME/.microshift` otherwise. Note that running Microshift unprivileged only works without node role at the moment (i.e. using `--roles=controlplane` instead of the default of `--roles=controlplane,node`). ### Kubeconfig -When starting the Microshift for the first time the Kubeconfig file is created. If you need it for another user or to use externally the kubeadmin's kubeconfig is placed at `/var/lib/microshift/resources/kubeadmin/kubeconfig`. +When starting the Microshift for the first time the Kubeconfig file is created. If you need it for another user or to use externally the kubeadmin's kubeconfig is placed at `/var/lib/microshift/resources/kubeadmin/kubeconfig`. ### Contributing @@ -117,4 +133,4 @@ For more information on working with Microshift, you can find a contributor's gu Join us on [Slack](https://microshift.slack.com)! -Community meetings are held weekly, Wednesdays at 10:30AM - 11:00AM EST. Be sure to join the community [calendar](https://calendar.google.com/calendar/embed?src=nj6l882mfe4d2g9nr1h7avgrcs%40group.calendar.google.com&ctz=America%2FChicago)! Click "Google Calendar" in the lower right hand corner to subscribe. +Community meetings are held weekly, Wednesdays at 10:30AM - 11:00AM EST. Be sure to join the community [calendar](https://calendar.google.com/calendar/embed?src=nj6l882mfe4d2g9nr1h7avgrcs%40group.calendar.google.com&ctz=America%2FChicago)! Click "Google Calendar" in the lower right hand corner to subscribe. diff --git a/docs/known-issues.md b/docs/known-issues.md index 076c16f037..78155937a2 100644 --- a/docs/known-issues.md +++ b/docs/known-issues.md @@ -1,8 +1,16 @@ -# On EC2 RHEL 8.4 +--- +modified: "2021-10-25T11:10:27.304+02:00" +title: Known Issues +tags: known issues, troubleshooting +layout: page +toc: true +--- -## `service-ca` can't be created +## On EC2 with RHEL 8.4 -If you want to run `microshift` on EC2 REHL 8.4(`cat /etc/os-release`), you might find [`ingress and service-ca will not stay online`](https://github.com/redhat-et/microshift/issues/270). +### `service-ca` can't be created + +If you want to run `microshift` on EC2 RHEL 8.4(`cat /etc/os-release`), you might find [`ingress and service-ca will not stay online`](https://github.com/redhat-et/microshift/issues/270). Inside the failing pods, you might find errors as: `10.43.0.1:443: read: connection timed out`. @@ -12,20 +20,20 @@ In order to work on RHEL 8.4, you may disable the networkManager and reboot to r Eg: -``` +```sh systemctl disable nm-cloud-setup.service nm-cloud-setup.timer reboot ``` You can find the details of this EC2 networkManage issue tracked at [issue](https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/740). - -## Openshift pods restarts on `CrashLoopBackOff` +### Openshift pods restarts on `CrashLoopBackOff` A few minutes after `microshift` started, openshift pods fall into `CrashLoopBackOff`. If you check up the `journalctl |grep iptables`, you may see the following: -``` + +```log Sep 21 19:12:54 ip-172-31-85-30.ec2.internal microshift[1297]: I0921 19:12:54.399365 1297 server_others.go:185] Using iptables Proxier. Sep 21 19:13:50 ip-172-31-85-30.ec2.internal kernel: iptables[2438]: segfault at 88 ip 00007feaf5dc0e47 sp 00007fff6f2fea08 error 4 in libnftnl.so.11.3.0[7feaf5dbc000+16000] @@ -34,17 +42,23 @@ Sep 21 20:35:57 ip-172-31-85-30.ec2.internal microshift[1297]: E0921 20:35:57.91 ``` Also, the `openshift-ingress` pod will faild on: -``` + +```console I0921 17:36:17.811391 1 router.go:262] router "msg"="router is including routes in all namespaces" E0921 17:36:17.914638 1 haproxy.go:418] can't scrape HAProxy: dial unix /var/lib/haproxy/run/haproxy.sock: connect: no such file or directory I0921 17:36:17.948417 1 router.go:579] template "msg"="router reloaded" "output"=" - Checking http://localhost:80 ...\n - Health check ok : 0 retry attempt(s).\n" ``` -As a walk around, you can follow steps below: + +As a workaround, you can follow steps below: + - delete `flannel` daemonset - `kubectl delete ds -n kube-system kube-flannel-ds` + ```sh + kubectl delete ds -n kube-system kube-flannel-ds + ``` + - restart all the openshift pods. -This workaround won't affect the singel node `microshift` functionality since the `flannel` daemonset is used for multi-node microshift. +This workaround won't affect the single node `microshift` functionality since the `flannel` daemonset is used for multi-node microshift. -This issue is tracked at: [#296](https://github.com/redhat-et/microshift/issues/296) \ No newline at end of file +This issue is tracked at: [#296](https://github.com/redhat-et/microshift/issues/296) diff --git a/docs/microshift-aio/README.md b/docs/microshift-aio/README.md index 62b3c97880..ef1da3b870 100644 --- a/docs/microshift-aio/README.md +++ b/docs/microshift-aio/README.md @@ -1,19 +1,21 @@ --- -modified: "2021-10-21T16:30:17.270+02:00" +modified: "2021-10-25T11:09:31.544+02:00" +title: All-In-One +layout: page +tags: all-in-one, aio +toc: true --- -# Containerized Microshift - ## Run Microshift All-In-One as a Systemd Service -Copy microshift-aio unit file to /etc/systemd and the aio run script to /usr/bin +Copy `microshift-aio` unit file to `/etc/systemd` and the aio run script to `/usr/bin` ```bash cp packaging/systemd/microshift-aio.service /etc/systemd/system/microshift-aio.service cp packaging/systemd/microshift-aio /usr/bin/ ``` -Now enable and start the service. The KUBECONFIG location will be written to /etc/microshift-aio/microshift-aio.conf. +Now enable and start the service. The `KUBECONFIG` location will be written to `/etc/microshift-aio/microshift-aio.conf`. If the `microshift-data` podman volume does not exist, the systemd service will create one. ```bash @@ -23,22 +25,22 @@ source /etc/microshift-aio/microshift-aio.conf Verify that microshift is running. -``` +```sh kubectl get pods -A ``` -Stop microshift-aio service +Stop `microshift-aio` service ```bash systemctl stop microshift-aio ``` -**NOTE** Stopping microshift-aio service _does not_ remove the podman volume `microshift-data`. -A restart will use the same volume. +> note "" +> Stopping microshift-aio service _does not_ remove the podman volume `microshift-data`. A restart will use the same volume. ## Run the Image Without Systemd -First, enable the following selinux rule: +First, enable the following SElinux rule: ```bash setsebool -P container_manage_cgroup true diff --git a/docs/microshift-containerized/README.md b/docs/microshift-containerized/README.md index 0f0d6a9169..7fd3f9c5b8 100644 --- a/docs/microshift-containerized/README.md +++ b/docs/microshift-containerized/README.md @@ -1,6 +1,12 @@ -# Containerized Microshift +--- +modified: "2021-10-25T11:09:43.609+02:00" +title: Containerized +tags: container, docker, podman +layout: page +toc: true +--- -## Pre-requisite +## Pre-requisites Before runnng microshift-containerized as a systemd service, ensure to update the host `crio-bridge.conf` as @@ -24,6 +30,7 @@ Before runnng microshift-containerized as a systemd service, ensure to update th } } ``` + ## Run microshift-containerized as a systemd service Copy microshift-containerized unit file to `/etc/systemd` and the microshift-containerized run script to `/usr/bin` @@ -32,8 +39,8 @@ Copy microshift-containerized unit file to `/etc/systemd` and the microshift-con sudo cp packaging/systemd/microshift-containerized.service /etc/systemd/system/microshift-containerized.service sudo cp packaging/systemd/microshift-containerized /usr/bin/ ``` -Now enable and start the service. The KUBECONFIG location will be written to `/etc/microshift-containerized/microshift-containerized.conf`. +Now enable and start the service. The KUBECONFIG location will be written to `/etc/microshift-containerized/microshift-containerized.conf`. ```bash sudo systemctl enable microshift-containerized --now @@ -41,7 +48,8 @@ source /etc/microshift-containerized/microshift-containerized.conf ``` Verify that microshift is running. -``` + +```sh kubectl get pods -A ``` @@ -61,11 +69,13 @@ sudo critcl ps To access the cluster on the host or inside the container ### Access the cluster inside the container + Execute the following command to get into the container: ```bash sudo podman exec -ti microshift-containerized bash ``` + Inside the container, run the following to see the pods: ```bash @@ -74,8 +84,10 @@ kubectl get pods -A ``` ### Access the cluster on the host + #### Linux + ```bash export KUBECONFIG=/var/lib/microshift/resources/kubeadmin/kubeconfig kubectl get pods -A -w -``` \ No newline at end of file +```